Advanced Configuration

Customize your Oval deployment.

The Getting Started guide shows you how to use the simplest possible Oval deployment with a Chainlink source, a Chainlink destination and an immutable controller. Deployments can be extended by using custom components within the Oval setup.

Customizing the Integration controller

Integration controllers control how an Oval instance is updated. They influence the behaviour of Oval in exactly 3 ways:

1. Who can initiate an OEV auction, (as discussed here), known as unlockers

2. How long the permissioned actor(s) have to initiate an auction from an update, known as lockWindow. This also governs the maximum delay a source update is blocked before being released to a downstream protocol in the event of the permissioned actor(s) going offline or MEV-Share breaking (see Controlling when to release what price)
3. How many max iterations to traverse when looking for historic values, called maxTraversal. This value is less important to control and exists to accommodate long lockWindows coupled with high speed updates on source oracles. It is safe to leave it at a value of 4.

The simplest way to customize these settings is to use the BaseController within your Oval deployment which gives you control over all 3 configurations listed above. This controller has an Owner which has exclusive permissions to modify these settings. An example usage of this controller could be to set the BaseController to be owned by your DAO or multisig, thereby giving you control over these settings within the Oval deployment.

Deploying Oval with BaseController

This example will guide you in deploying and customizing the ChainlinkOvalBase contract, a version of Oval that uses the BaseController. The deployment flow here is very similar to that of the Getting Started tutorial except we can now configure the unlockers, lockWindow, and maxTraversal after deployment.

0. Prerequisites:

This getting started makes some assumptions:

1. Foundry is installed on your machine. If not, it can be found here.

2. You have a wallet and the associated private key for the network you want to deploy on. If deploying on Goerli, you can fund your wallet here or here or here.

3. You are using Chainlink and know the address of the source Chainlink oracle you want to connect to. A full list of Chainlink oracles can be found here.

4. You have an RPC URL to connect to. If not, you can get one from Infura.

1. Clone the Quickstart repo and install dependencies

git clone https://github.com/UMAprotocol/oval-quickstart.git
cd oval-quickstart
forge install

2. Configure the deployment options

Next, we need to define some envs to setup the deployment environment. In particular we need a private key and an RPC URL:

cp example.env .env

Then open .env file with your favorite editor and change its contents accordingly. For this advanced configuration we only need a PRIVATE_KEY and RPC_MAINNET

PRIVATE_KEY=0xPUT_YOUR_PRIVATE_KEY_HERE # This account will do the deployment
RPC_MAINNET=PUT_YOUR_RPC_URL_HERE # Your network or fork RPC Url.

3. Deploy the ChainlinkOvalBase contract

Next, we can directly deploy the ChainlinkOvalBase.sol contract and leave the configuration until the next step. To deploy the contract, run the forge create command. The example below deploys an Oval contract that wraps the Chainlink ETH/USD oracle. Be sure to set the number of decimals (8 in the example below) corresponding to the decimals() value from the Chainlink oracle.

source .env # Load the variables in the .env file

forge create src/ChainlinkOvalBase.sol:ChainlinkOvalBase \ 
--private-key $PRIVATE_KEY --rpc-url $RPC_MAINNET 
--constructor-args 0x5f4ec3df9cbd43714fe2740f5e3616155c5b8419 8

Once this deployment is done, you can call functions on your Oval contract to customize the deployment:

1. setUnlocker to add a new unlocker to the unlockers set (actors who can unlock prices). To add an unlocker, set the second argument to true. To remove an unlocker, set the second argument to false.

2. setLockWindow to change the lockWindow (how long a price will be locked before being automatically unlocked). This effectively controls the auction period.

3. setMaxTraversalto change the maximum traversals a historic lookback can loop through.

4. Lastly, given that ChainlinkOvalBase inherits from OpenZepplin Ownable, you can call transferOwnership once the configuration is done to transfer the ownership to your DAO/multisig or other address.

Extending Integration Controllers

The Oval contract architecture has been designed such that custom controllers are possible, as long as they conform to the interface defined within the Integration Controllers specification. For example you might want to have a set of addresses that can disable your Oval contract, making it act as a passthrough by setting lockWindow=0. Or you may want to have a different set of addresses to manage the unlockers list. Reach out to us on Discord if you'd like support in creating custom controllers.