Getting Started

Connect your existing protocol to Oval.

Oval works by placing a smart contract between the Chainlink and your protocol. See Contract Architecture for details. This acts like a "wrapper" over Chainlink and provides the logic needed to run OEV auctions on Chainlink updates, while maintaining compatibility with the original interface. This contract works by controlling precisely when the latest price from Chainlink is made available to the protocol, ensuring that the winner of the auction gets the first opportunity to use it (enabling Oracle related MEV extraction).

For support on launching your own Oval instance please reach out to us on Discord here in the #Oval channel. We'll guide you in custom configurations and in onboarding your Oval contract to use the the UMA permissioned unlocker (RPC).

How Oval changes the connection to Chainlink

The integration flow involves 2 steps:

1. Configure and deploy your instance of the Oval contract.

2. Update your contracts to insert Oval between your protocol and Chainlink price feeds.

This getting started guide aims to show how to deploy an Oval contract. For working examples that show how Oval works on a testnet see Flashbots Integration. For a mainnet fork example see Aave Integration. If you want to use Oval within your application we recommend first reaching out to us on Discord.

Deployment

The Oval contracts are designed to be composable and modular, enabling the deployer to customize them to their needs. We've created a minimal viable Oval configuration that is perfect for getting started. It's located in the Oval quickstart repo. This Oval contract uses Chainlink as source and destination and uses the Immutable controller to manage the Oval instance.

To deploy your own instance of this contract follow these steps:

0. Prerequisites:

This guide 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 know what address you want to set as the permissioned actor that can initiate an auction. If this is a production mainnet deployment, reach out to the UMA team. You can contact us on discord.

4. You know the address of the Chainlink oracle you want to connect to. A full list of Chainlink oracles can be found here.

5. 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, you need to configure the deployment options given your desired configuration. This is done through an environment file. There is a sample env within the repo that you can modify. To do this run:

cp example.env .env

Then open the .env file with your favorite editor and change its contents accordingly. It should look something like this:

PRIVATE_KEY=0xPUT_YOUR_PRIVATE_KEY_HERE # This account will do the deployment
SOURCE_ADDRESS=0x5f4ec3df9cbd43714fe2740f5e3616155c5b8419 # example Chainlink ETH/USD
LOCK_WINDOW=24 # How long each update is blocked for OEV auction to run.
MAX_TRAVERSAL=4 # How many iterations to look back for historic data.
UNLOCKER=0xPUT_YOUR_UNLOCKER_ADDRESS_HERE # Your address provided on Discord.
RPC_MAINNET=PUT_YOUR_RPC_URL_HERE # Your network or fork RPC Url.

A note on the UNLOCKER: This setting is the most complex within the config. This is the actor that can initiate the Oval auction (see here). If you are using the Oval Node then you will need to place a custom address that the UMA integration teams will give you in this field. Otherwise, this address should be something you can control and is used to initiate the auction within MEV-Share.

Note on RPC_MAINNET

if you want to deploy this within an Anvil fork then run:

anvil --fork-url YOUR_RPC_URL_HERE

And set the RPC_MAINNET value within the .env file to http://127.0.0.1:8545. Doing this will let you deploy your Oval instance to a local mainnet fork which can be useful for testing.

3. Deploy the ChainlinkOvalImmutable

Next, we can execute the deployment script to deploy your Oval contract. This can be run as follows:

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

forge script ./src/ChainlinkOvalImmutable.s.sol --rpc-url $RPC_MAINNET --broadcast

This will output the deployment address of your Oval instance. You then need to configure your protocol to use this address in place of the associated Chainlink deployment.