Collateral Onboarding Guide for Oracle Domain Teams

Directory
1.Overview 
2.Learning Objectives
3.Pre-requisites
4.Introduction to MIP10c3
5.Technical Complexity Evaluation
6.Build the Data Model
7.Oracle Tooling Software Updates
8.Prepare the Medianizer and OSM Contracts
9.Integration Testing
10.Kovan and Mainnet Contract Deployment
11.Finalize and Publish Tooling Software Updates
12.Staging Tests
13.Publish the Collateral Onboarding Oracle Assessment (MIP10c3-SP) 
14.Deployment of Oracle Software to feeds and relayers 
15.Summary
1. Overview
The Maker Protocol enables users to generate Dai against an array of assets, including ETH, WBTC, and USDC. In order to ensure that all collateral assets are priced correctly in the Protocol, an Oracle system is used to provide a real-time stream of market price data for each asset in a secure and resilient manner. The Oracle system needs to be resistant to attacks, be they at the technical, crypto-economic, or informational level.
This price information provided by Oracles is utilized to determine whether Maker Vault positions are sufficiently capitalized or below the collateralization ratio and subject to liquidation. Oracle price information also determines the maximum amount of Dai a user can generate against their collateral. Given the widespread effects the Oracles have on the Maker Protocol, it is imperative that the Data Models used in their implementations are refined to mitigate risk and optimize performance. These Data Models define how data is sourced and how it is filtered into a canonical price.
This Guide captures the best practices of long-time Community smart contract developers as well as the current Oracle Domain Team. It intends to show developers interested in working for the Oracle Domain Team or independently contributing to MakerDAO how the Oracle System and its component parts function and are built upon. We hope that this guide evolves as the Community improves on the processes included herein and as the number of Oracle Domain Teams expands. Thanks for reading!
2. Learning Objectives
Learn about the Oracles Domain Work
Learn how to onboard an Oracle for collateral onboarding through the MIP10 framework.
3. Pre-requisites
​Introduction to the Maker Protocol​
​Oracle Module​
​MIPs​
​Solc 0.5.12​
​Dapp tools​
Familiarity with seth and dapp.
Working nix environment for testing.
4. Introduction to MIP10c3
​MIP10 defines Oracle Management in the Maker Protocol, including onboarding an Oracle, updating a Data Model, and performing other tasks that ensure Maker Oracles function properly. MIP10c3 specifically covers the onboarding of a new Oracle, where Oracle is defined as the on-chain price source. Onboarding a new collateral on the Maker Protocol requires creating a new Oracle, and having the Oracle Feeds updated to start serving it.
Below, you can find all the steps defined in MIP10c3. While additional information and best practices are provided, they are not formally part of the MIP specifications.
This document does not cover the inclusion of Oracle customers to the Maker Protocol.
Overview of the collateral onboarding process
1.​Technical Complexity Evaluation​
Produce an assessment of the planned collateral
2.​Oracle Tooling Software Updates​
Adapt the Oracle software to gather pricing information on the collateral and use the deployed smart contracts
3.​Oracle Smart Contract Preparation ​
Make the necessary modifications to the contract and compile them.
4.​Integration Testing​
Run a single Feed and Relayer to confirm they interface well with each other and with the smart contracts.
5.​Deploy Kovan and Mainnet Smart Contracts​
Deploy the compile contract to Kovan and Mainnet with the proper permissions
6.​Finalize and Publish Tooling Software Updates​
Final update to the software to point to the deployed mainnet contract.
7.​Publish the Collateral Onboarding Oracle Assessment (MIP10c3-SP)​
Use the sub-proposal template to gather the information.
8.​Staging Tests​
Long-running test to ensure stability
9.​Deployment of Oracle Software to feeds and relayers​
Coordinate with the dark feeds, light feeds, and relayers to update to the new software version and monitor the freshly updated network.
5. Technical Complexity Evaluation
Determine the complexity of Oracle integration for the collateral type and how long it would take to implement such a solution.
Data Sources
First, determine the number and availability of public data sources needed to construct a reliable, resilient, and secure Oracle for the proposed collateral asset. Start by looking at the list of the exchanges where the collateral is currently being traded, which can be obtained from CoinGecko and Messari, or from the promoters of the token listing. The exchanges listed will vary in quality; therefore, take into account the following criteria when evaluating an exchange as a potential price source:
Trading volume and order book depth: We are looking for consistently deep order books and large historic trading volume. Taken together, these two criteria ensure that the price of the collateral on that exchange will not be significantly more volatile than the collateral itself ( i.e., large orders will not skew the price significantly more than the other sources).
Exchange reputation: Some exchanges report inflated numbers, due in part to wash trading. Consult industry resources, such as Messari.io’s “Real Volume” list of trusted exchanges to assess the exchange reputation. Even if some exchanges might exhibit some wash trading, it might still be used as a data source if it’s found out that it has a significant proportion of legitimate trading.
Availability of an API: Does the exchange make available a public API that can be consulted by the price feeds.
Existing exchange integration: Exchanges already integrated with the Protocol are favored because this reduces the amount of work required for integrating the price source in the existing tooling.
For certain collateral types, crypto exchanges might not be the right source of pricing data, and particular rules might apply. For instance
For some stablecoins, it might be desirable for their price to be a fixed value.
Wrapped assets for which the protocol uses the underlying asset price instead of the wrapped version. Ex.: WBTC that is priced assuming a 1:1 equivalent with BTC.
Data Models
The required data models for the new collateral must be easily implementable and not require complex development. Ideally, the data model will be usable directly by the existing tooling without modification. If modifications are needed, provide an estimate of the time and effort required to implement.
Examples of functionality that might require extra development:
Use of on-chain sources
Authenticated/private API
Non-HTTP API
Use of a function other than the median for aggregation, such as median or other special rules such as removing the lowest and highest values.
Externalities
As part of the technical complexity evaluation, external dependencies that the integration of a price for feed would add to the Oracle must be identified. The objective is to minimize adding risks, costs, and latency to the Oracle Protocol that would have to be managed in the long term.
Example:
Paid API access or free API access that could be throttled or disabled.
Slow API sources or data that requires a significant amount of processing.
High reliance on a specific price feed.
Timeline
The Oracle Domain Team must ensure that it can deliver the price source in the timeline expected by the community:
Does adding these features interfere with ongoing or planned development of new tooling?
Does adding these features require work and/or coordination from other stakeholders, such as the Smart Contracts Team(s)?
How long might it take to design, implement, test, and deploy such a solution?
6. Build the Data Model
The data model for a collateral type is the formula used by the oracles to determine its price. It is comprised of:
List of price sources: A list of trading pairs that include the collateral, typically coming from 5 to 6 exchanges.
Quorum: Minimum number of feeds necessary to provide price information for the Oracle price to be considered valid.
Feed models: How the individual feeds aggregate the price sources. Typically, “median” is used.
Oracle models: How the Oracle will aggregate the price information from the individual feeds. Typically, “median” is used.
If the collateral isn’t traded directly to USD, supporting data models will be required (e.g., XYZ eExchange trades ETH with BTC. To use this price source, a BTC/USD data model will be required. A certain number of supporting data models are already used and supported (ETH/USD, BTC/USD, and USD/TUSD).
Oracle Data Model
1
| Source     | Asset Pair | Quorum | Feed Model  | Oracle Model |
2
| :--------------- | :--------- | :-----: | :---------: | :----------: |
3
| < data source >  | < param >  | < # > | < model > | < model >    |
Copied!
Example (PAXG/USD):
1
|    Source    |  Asset Pair   |Quorum | Feed Model  | Oracle Model |
2
| :----------- | :------------ | :---: | :---------: | :----------: |
3
|    Binance   |    PAXG/USDT  |   13  |    Median   |    Median    |
4
|    Bitthumb  |    PAXG/USDT  | 
5
|    Gemini    |    PAXG/USD   |
6
|    Kraken    |    PAXG/USD   |
7
|    Uniswap   |    PAXG/ETH   |
Copied!
Oracle Supporting Data Model(s)
1
|    Source     |  Asset Pair   |  Feed Model  |
2
| :------------ | :------------ | :----------: | 
3
|   < data src> |    <param>    |   <model>    |
Copied!
Example (USDT/USD):
1
|    Source     |  Asset Pair   |  Feed Model  |
2
| :------------ | :------------ | :----------: | 
3
|   Binance     |    BTC/USDT   |    Median    |
4
|   BitFinex    |    USDT/USD   |              |
5
|   FTX         |    ETH/USDT   |              |
6
|   Huobi       |    ETH/USDT   |              |
7
|   Kraken      |    USDT/USD   |              |
8
|   OKEx        |    BTC/USDT   |              |
Copied!
7. Oracle Tooling Software Updates
Support of the new Data Model requires updating the off-chain software run by feeds and relayers. Three major pieces of software currently used, setzer, gofer and omnia.
setzer
setzer is the tool used to query the prices from the off-chain sources. It queries a list of external APIs and aggregates the values returned. The aggregated result can then be used by omnia. Oracle domain contributors are invited to fork the GitHub repo and submit a pull request for inclusion in the main branch.
Each collateral price has a setzer-price-XXXusd that returns the current price of the collateral. For instance, if you want to know the current price of Ether, you would run bin/setzer price ETHUSD and obtain the current price: 351.2382000000.
Calling the bin/setzer script translates the request to a call to the script libexec/setzer/setzer-price, which in turn will invoke libexec/setzer/setzer-price-ethusd.
Adding a price script
To add a new collateral, a setzer-price-XXXusd script must be created. Let's take, for example, PAXG, for which the following data model was defined:
1
|    Source    |  Asset Pair   |Quorum | Feed Model  | Oracle Model |
2
| :----------- | :------------ | :---: | :---------: | :----------: |
3
|    Binance   |    PAXG/USDT  |   13  |    Median   |    Median    |
4
|    Bitthumb  |    PAXG/USDT  | 
5
|    Gemini    |    PAXG/USD   |
6
|    Kraken    |    PAXG/USD   |
7
|    Uniswap   |    PAXG/ETH   |
Copied!
The script starts off by setting the pair name, here paxgusd.
1
#!/usr/bin/env bash
2
set -e
3
pair=paxgusd
Copied!
Then the list of exchanges used for finding its price is defined. These exchanges were previously defined in setzer-x-price.
1
sources=(
2
binance
3
bitthumb
4
gemini
5
kraken
6
uniswap
7
)
Copied!
The easiest case to cover is a pair against the USD, as it doesn’t require secondary models. Here, the PAXG/USD prices from Gemini and Kraken fit this criteria.
1
case $1 in
2
  gemini|kraken) {
3
    setzer x-price "$1" paxg:usd
4
  };;
Copied!
In many cases, a second price must be added to the calculation. For instance, for PAXG/USDT, the USDT price has to be converted to USD.
1
binance|bitthumb) {
2
    paxg_usdt=$(setzer x-price "$1" paxg:usdt)
3
    usdt_usd=$(setzer price usdtusd)
4
    setzer --format "$(bc -l <<<"$paxg_usdt * $usdt_usd")"
5
  };;
Copied!
Same thing with PAXG/ETH, for which ETH/USD is required to determine the USD price.
1
 uniswap) {
2
    paxg_eth=$(setzer x-price "$1" paxg:eth)
3
    eth_usd=$(setzer price ethusd)
4
    setzer --format "$(bc -l <<<"$paxg_eth * $eth_usd")"
5
  };;
Copied!
The script is completed by covering the default case where the commands ls, sources and median are passed to the setzer---price-commands script.
1
 *) {
2
    setzer --price-commands "-$1-" $pair "${sources[@]}"
3
  };;
4
esac
Copied!
Testing the script is done by invoking it directly:
1
$ chmod a+x setzer-price-paxgusd
2
$ ./setzer-price-paxgusd binance
3
1922.4023458415
4
$ ./setzer-price-paxgusd kraken
5
1922.0000000000
6
$ ./setzer-price-paxgusd gemini
7
1923.8900000000
8
$ ./setzer-price-paxgusd uniswap
9
1927.3950381315
10
$ ./setzer-price-paxgusd bitthumb
11
1838.4216082708
Copied!
Testing the main setzer script:
1
$ bin/setzer pairs | grep PXGUSD
2
PXGUSD
3
​
4
​
5
$ bin/setzer price pxgusd
6
1923.7400000000
Copied!
Adding a price source
If it is necessary to support a new price source, such as a new exchange or a different API, the script setzer-x-price must be modified.
For instance, to change the data model for PAXG/USD to use the PAXG/USDT pricing from the Probit exchange, it is required to determine the API call that will provide the information. In this case, researching the Probit API documentation will allow crafting this HTTP request:
1
$ echo json=$(curl -sS <https://api.probit.com/api/exchange/v1/ticker?market_ids=PAXG-USDT>)
2
json={"data":[{"last":"1930","low":"1892","high":"1949","change":"14","base_volume":"4.86095411","quote_volume":"9299.20180356","market_id":"PAXG-USDT","time":"2020-10-05T19:38:27.000Z"}]}
Copied!
jshon can extract the price from the json response:
1
$ jshon <<<"$json" -e data -e 0 -e last -u
2
1926
Copied!
The following code can then be added to setzer-x-price.
1
probit) {
2
  json=$(curl -sS "[<https://api.probit.com/api/exchange/v1/ticker?market_ids=${base^^}-${quote^^}>](<https://api.probit.com/api/exchange/v1/ticker?market_ids=$%7Bbase%5E%5E%7D-$%7Bquote%5E%5E%7D>)")
3
  setzer --format "$(jshon <<<"$json" -e data -e 0 -e last -u)"
4
};;
Copied!
After adding Probit to the setzer-x-price script, the new source can be tested by directly invoking setzer:
1
$ bin/setzer price paxgusd probit
2
1926.6460884486
Copied!
gofer
Gofer is another tool used to query the prices from the off-chain sources. If you don’t need to define new external APIs, no code update is needed and only a config change is required. See the section “Finalize and Publish Tooling Software Updates” below for the configuration updates required.
omnia
omnia is the script that periodically calls setzer to obtain price data. When it determines that the price it provided previously needs to be updated, it signs a message that is distributed using the scuttlebutt network.
Adding new collateral prices to omnia requires updating three files.
oracles-v2/nix/srcs.nix to bump the setzer rev with the commit hash. If the setzer PR isn't merged, update url and ref to point our work branch to test omnia. Make sure to update it later to point to the main branch once the setzer PR is merged.
omnia/config/feed.conf to add the new pair. Use default msgSpread and msgExpirations:
Example:
1
"PAXGUSD": {
2
 "msgExpiration": 1800,
3
 "msgSpread": 1
4
}
Copied!
omnia/config/feed.conf to add the new pair, including the Medianizer address, which will be updated once it is deployed.
Example:
1
"PAXGUSD": {
2
 "oracle": "0x<Medianizer contract address>",
3
 "oracleSpread": 1.0,
4
 "oracleExpiration": 15500,
5
 "msgExpiration": 1800
6
}
Copied!
8. Prepare the Medianizer and OSM Contracts
Collateral prices are accessed by the Maker Protocol via the Oracle Security Module smart contract. This contract gets its pricing information from the Medianizer, which is the smart contract that the information is pushed to by the Oracle Relayers.
The Oracle Domain Team is responsible for the Medianizer and OSM contracts. As part of the collateral onboarding process, the Medianizer and OSM smart contracts are deployed on both the Kovan testnet and the Ethereum mainnet. Care must be taken while deploying to ensure that the right permissions are set correctly:
Feed addresses
Medianizer read-only access
OSM read-only access
Ownership of both contracts.
Always verify the latest contract addresses of the Maker Protocol before continuing with the implementation. Source the changelog for the latest contracts.
Medianizer
Medianizer is responsible for taking the pricing information provided by the Relayers, and verifying that the information is signed by the authorized list of Feeds.
1.Clone the smart contract from the repo https://github.com/makerdao/median​
2.In src/median.sol, paste the following code snippet at the end, while changing the contract name and the value of the wat variable. 
1
contract MedianPAXGUSD is Median {
2
    bytes32 public constant wat = "PAXGUSD";
3
​
4
    function recover(uint256 val_, uint256 age_, uint8 v, bytes32 r, bytes32 s) internal pure returns (address) {
5
        return ecrecover(
6
            keccak256(abi.encodePacked("\x19Ethereum Signed Message:\n32", keccak256(abi.encodePacked(val_, age_, wat)))),
7
            v, r, s
8
        );
9
    }
10
}
Copied!
1.Update the dependencies: dapp update
2.Compile with solc 0.5.12: dapp --use solc:0.5.12 build
Oracle Security Module (OSM)
The Oracle Security Module delays the price information provided by the Medianizer contract for use by the Maker Protocol. The OSM does not require modifications, except for passing the address of the Medianizer contract to the constructor.
1.Clone the smart contract from the the repo: https://github.com/makerdao/osm/​
2.Update the dependencies: dapp update
3.Compile the contract: dapp --use solc:0.5.12 build
9. Integration Testing
Deploy and Configure Integration Testing Contracts
Set ETH_RPC_URL and ETH_KEYSTORE to point to the corresponding ethereum node and account for Kovan or another testnet. Deploying smart contracts also requires a fairly large gas limit, such as ETH_GAS=5000000.
1.Deploy the smart contract using dapp create <contractname> (Use the contract name you used above, such as MedianPAXGUSD)
2.Note the returned address, this is the contract address that will store in $MEDIAN for the other steps.
3.Verify the smart contract on Etherscan by using the flatten source code provided by:hevm flatten --source-file src/median.sol --json-file out/dapp.sol.json
4.Add the list of approved feeds to the contract using lift. Put the feed address list in the FEEDS variable. For integration testing, use a feed account on which you have control, as you will test omnia message signatures. The oracle-v2 repo conveniently includes a test account in the smoke-tests directory, 0x1f8fbe73820765677e68eb6e933dcb3c94c9b708.
1
FEEDS=("0x1f8fbe73820765677e68eb6e933dcb3c94c9b708")
2
seth send $MEDIAN "lift(address[] memory)" "$(echo ${FEEDS[@]} | sed s/\ /\",\"/g)"
Copied!
1.Set the quorum (i.e., the minimum number of feeds required to make the price valid) in the data model. For the testing, set it to 1, as there is only one feed.
1
seth send $MEDIAN "setBar(uint256)" $(seth --to-uint256 1)
Copied!
1.Deploy the OSM smart contract: dapp create OSM $MEDIAN. Note the returned address, this is the contract address that will store in $OSM for the other steps.
2.Verify the smart contract on Etherscan by using the flatten source code provided by:
1
hevm flatten --source-file src/osm.sol --json-file out/dapp.sol.json
Copied!
Etherscan should have already set correctly the Constructor Arguments, which is the Medianizer address.
1.Give OSM access to Medianizer
1
seth send $MEDIAN "kiss(address)(uint256)" $OSM
Copied!
Without this permission, a poke()to the OSM would fail because it requires the OSM to be able to query the price from the Medianizer.
Run the tests
As a testing prerequisite, install Nix, if you haven’t done already
nix curl -L https://nixos.org/nix/install | sh
. ~/.nix-profile/etc/profile.d/nix.sh
Omnia Feed test
From your oracle-v2 directory:
cp omnia/config/feed.conf /tmp/omnia.config
export OMNIA_CONFIG=/tmp/omnia.config
In /tmp/omnia.conf, set from, keystore and password to a test account included with the oracle-v2 repo:
1
"ethereum": {
2
             "from": "0x1f8fbe73820765677e68eb6e933dcb3c94c9b708",
3
             "keystore": "../smoke-tests/resources/keys",
4
             "password": "../smoke-tests/resources/key"
5
     },
Copied!
Execute nix-shell (first run will take a long time)
cd omnia
ssb-server start &
./omnia.sh
Confirm that omnia is able to pull the price for your collateral and publish it to the network. You will get an output similar to this:
1
[10/09/20 14:40:47] [V] {
2
  "type": "PXGUSD",
3
  "version": "1.3.9",
4
  "price": 1932.6067700778,
5
  "priceHex": "000000000000000000000000000000000000000000000068c44e81ff0a4aea00",
6
  "time": 1602254445,
7
  "timeHex": "000000000000000000000000000000000000000000000000000000005f80766d",
8
  "hash": "6b48ef84fa4484438d791089d4966053134dc0ce68c1935df1c60ef067758723",
9
  "signature": "87cf8fc4e30c0939de3da63f7c8b228dfdad1e80db43783d7316bde1d62eb3285d24b069d58900652dc6589a3cce83af99e7a6c28fd767efa9537c962e614b3d1b",
10
  "sources": {
11
 "gemini": "1931.5200000000",
12
 "uniswap": "1955.8511034425",
13
 "binance": "1933.6935401555",
14
 "kraken": "1930.0900000000",
15
 "probit": "1934.0138737164",
16
 "bitthumb": "1876.9444477637"
17
  }
18
}
19
[10/09/20 14:40:47] Publishing new price message...
20
{
21
  "key": "%Kw2cAauVwC0H8CYjYooiupHq1Owvv2f8llOKlP40kjw=.sha256",
22
  "value": {
23
 "previous": "%8lTgn0kCsFP5sG8JNkTGFWdsHPoqs+Uq5uSouI05Tc0=.sha256",
24
 "sequence": 17,
25
 "author": "@rE23z01yWbc/dOix9rIHFlkBj1OCWWckNkSxEG5E7mw=.ed25519",
26
 "timestamp": 1602254447731,
27
 "hash": "sha256",
28
 "content": {
29
   "type": "PXGUSD",
30
   "version": "1.3.9",
31
   "price": 1932.6067700778,
32
   "priceHex": "000000000000000000000000000000000000000000000068c44e81ff0a4aea00",
33
   "time": 1602254445,
34
   "timeHex": "000000000000000000000000000000000000000000000000000000005f80766d",
35
   "hash": "6b48ef84fa4484438d791089d4966053134dc0ce68c1935df1c60ef067758723",
36
   "signature": "87cf8fc4e30c0939de3da63f7c8b228dfdad1e80db43783d7316bde1d62eb3285d24b069d58900652dc6589a3cce83af99e7a6c28fd767efa9537c962e614b3d1b",
37
   "sources": {
38
     "gemini": "1931.5200000000",
39
     "uniswap": "1955.8511034425",
40
     "binance": "1933.6935401555",
41
     "kraken": "1930.0900000000",
42
     "probit": "1934.0138737164",
43
     "bitthumb": "1876.9444477637"
44
   }
45
 },
46
 "signature": "Wx+YRJrhZAJt/K98MLHKix5G1Hxj8t4iaHVy5gXrWz/R09CDaoDNq5wXvMBwmZ4WujPUoAMISm0IKXRTGtvyDg==.sig.ed25519"
47
  },
48
  "timestamp": 1602254447732
49
}
Copied!
Omnia Relayer test
From your oracle-v2 directory:
cp omnia/config/relayer.conf /tmp/omnia-relayer.conf
export OMNIA_CONFIG=/tmp/omnia-relayer.conf
In /tmp/omnia-relayer.conf, set from, keystore, password to the values corresponding to any funded account on the testnet you are using. Set network to a node RPC URL, such as one from infura.io. Set the oracle address for your collateral to your integration contract address.
nix-shell 
cd omnia
If you stopped it, restart ssb using ssb-server start &
./omnia.sh
The Omnia Relayer will read the published message from the Feed, and push it on-chain.
Make sure that the transaction succeeds (SUCCESS: 1). If necessary, troubleshoot the reverted ethereum transaction.
1
[10/09/20 15:28:01] Sending tx...
2
TX: 0x...
3
SUCCESS: 1
4
GAS USED: 58713
5
[10/09/20 15:28:10] [V] Sleeping 60 seconds..
Copied!
Validation
Now that Omnia successfully pushed the price information on-chain, confirm that OSM is able to read it properly.
Poke the OSM contract to read the current value from the Medianizer: seth send $OSM "poke()()"
Read the on-chain value using:
1
storage=$(seth storage $OSM 0x4)
2
price=$(seth --from-wei "$(seth --to-dec "${storage:34:32}")")
3
echo $price
4
1934.814612130400000000
Copied!
If these steps are successful and that OSM has the price your Feed published earlier, you may proceed to Kovan and Mainnet contract deployments.
10. Kovan and Mainnet Contract Deployment
Follow the steps below for deployment on both Kovan and Mainnet.
1.Set ETH_RPC_URL and ETH_KEYSTORE to point to the corresponding ethereum node and a funded account.
2.Deploy the smart contract using dapp create MedianPAXGUSD (updating the contract name) Note the returned address, this is the contract address that will store in $MEDIAN for the other steps.
3.Verify the smart contract on Etherscan by using the flatten source code provided by:hevm flatten --source-file src/median.sol --json-file out/dapp.sol.json
4.Add the list of approved feeds to the contract using lift. Put the feed address list in the FEEDS variable.  For Kovan, coordinate with other Oracle Domain teams to obtain the latest feed list. If necessary, you may extract this list from an existing Medianizer contract using the following script but changing the address to a known working median contract on Kovan:
1
#!/bin/bash
2
for i in {0..255}
3
do
4
  addr=$(seth call 0x64DE91F5A373Cd4c28de3600cB34C7C6cE410C85 'slot(uint8)' $i)
5
  if [ $addr != "0x0000000000000000000000000000000000000000000000000000000000000000" ]
6
  then
7
    echo "0x$(cut -c27-66 <<< $addr)"
8
  fi
9
done
Copied!
For mainnet, obtain the list of currently approved production light and dark feeds from MIP10c7, and compare it with the live feed list from one of the production Medianizer. Coordinate with the other Oracle Domain teams if you find a discrepancy.
1
FEEDS=("0x1f8fbe73820765677e68eb6e933dcb3c94c9b708")
2
​
3
​
4
seth send $MEDIAN "lift(address[] memory)" "$(echo ${FEEDS[@]} | sed s/\ /\",\"/g)"
Copied!
1.Set the quorum (i.e., the minimum number of feeds required to make the price valid) in the data model. Here, it is set to 13:
1
seth send $MEDIAN "setBar(uint256)" $(seth --to-uint256 13)
Copied!
1.Add the Maker Governance DSPause Proxy as one of the owners of the contract (MCD_PAUSE_PROXY on changelog.makerdao.com). Note that this does not remove the deployer address as owner. You will need to remove yourselves (deny()) after deploying the OSM.
1
seth send $MEDIAN "rely(address)" "0x0e4725db88Bb038bBa4C4723e91Ba183BE11eDf3"
Copied!
1.Deploy the OSM smart contract: dapp create OSM $MEDIAN . Note the returned address, this is the contract address and store it in $OSM for the other steps.
2.Verify the smart contract on Etherscan by using the flatten source code provided by:
1
hevm flatten --source-file src/osm.sol --json-file out/dapp.sol.json
Copied!
Etherscan should have already set correctly the Constructor Arguments, which is the Medianizer address.
1.Give OSM access to Medianizer
1
seth send $MEDIAN "kiss(address)(uint256)" $OSM
Copied!
1.Add the Maker Governance DSPause Proxy as one of the owners of the contract (MCD_PAUSE_PROXY on  changelog.makerdao.com).
1
seth send $OSM "rely(address)" "0x0e4725db88Bb038bBa4C4723e91Ba183BE11eDf3"
Copied!
1.Enable read access to the Maker Protocol
This step enables read access for the MCD spotter contract, so it can access the prices. Set the address to MCD_SPOT from changelog.makerdao.com​
1
seth send $OSM "kiss(address)" 0x3a042de6413eDB15F2784f2f97cC68C7E9750b2D
Copied!
You may confirm that the spotter has access by checking bud
1
seth call $OSM "bud(address)(uint256)" 0x3a042de6413eDB15F2784f2f97cC68C7E9750b2D
Copied!
Permission tightening
Once you confirm that everything has been deployed correctly, with all the right permissions, remove yourself as owner from both the OSM and Medianizer
1
seth send $OSM "deny(address)" $ETH_FROM
2
​
3
​
4
seth send $MEDIAN "deny(address)" $ETH_FROM
Copied!
11. Finalize and Publish Tooling Software Updates
1. Submit a PR for Setzer
Make sure you have tested setzer price as described above before submitting your pull request.
2. Submit a PR for Omnia
Because Omnia configuration depends on the availability of a specific setzer version and deployed mainnet contracts, we have to wait for the Setzer PR to be merged to mainnet and for the availability of a deployed median contract on mainnet.
Update oracles-v2/nix/srcs.nix to bump the setzer rev with the commit hash from the mainnet branch.
Update oracles-v2/omnia/config/feed.conf, oracles-v2/omnia/config/relayer.conf and oracles-v2/omnia/config/relayer-kovan.conf to point to the mainnet deployment of the Medianizer contract.
Update oracles-v2/systemd/gofer.json to add the data model for your new collateral. See the gofer documentation for more details and examples.
12. Staging Tests
To ensure software stability and avoid dangerous oracle outages in production, it is necessary to run the new Oracle Software and deploy smart contracts for a period of 7 to 14 days on at least 4 feeds and 2 relayers on a testnet environment.
To facilitate these steps, terraform configuration and deployment scripts are made available in a dedicated repository. These sample configuration and script allow for the quick and flexible deployment of testing environments using a cloud provider.
The existing Oracle Team maintains an Oracle staging network on Kovan that can be used for this testing. Coordinate with the Oracle Team to join this network, or consider deploying your own.
13. Publish the Collateral Onboarding Oracle Assessment (MIP10c3-SP)
Use the official MIP10c3-SP template to create a new sub-proposal for the collateral. To be able to complete it, you will need the following information:
Data Model
Supporting Data Model
Mainnet contract addresses for Medianizer and OSM contracts
Git tags for Setzer and Omnia releases
Note that the template is also used to define the Oracle customers (other than the Maker Protocol). Reviewing the inclusion of such customers is not in the scope of this document.
Once completed, submit a PR to the official MIP repo and publish a post to the forum with the content of the SP.
14. Deployment of Oracle Software to feeds and relayers
In preparation for the addition of collateral to the Maker Protocol, the Oracle Team will coordinate with the dark feeds, light feeds, and relayers to update to the new software version and monitor the freshly updated network.
Feed providers need to always be alert to new updates of their clients and update their clients to latest changes.
Every time there’s an update to the configuration in the oracles feed software, every other feed provider must update to that configuration so as to not run into issues when adding new feeds in the future. In other words, every feed provider must have the same version of the software client, with the same configuration.
15. Summary
In this guide, you were introduced to the MIP10c3 process of setting up an oracle for a new collateral that is to be onboarded to the Maker Protocol. The steps involved were selecting the right data sources, updating the software stack, deploying the smart contracts and testing it. The final step was to put it all together for the Maker Governance approval by using the MIP10c3 template. With this guide, you gathered the knowledge to help the Maker Protocol become more decentralized by learning the Oracle Domain Work and help onboard new collaterals into the protocol.
Governance & Collateral Onboarding - Previous
Collateral Onboarding Governance Process
Next - Smart Contracts Domain
Collateral Onboarding Guide for Smart Contracts Domain Teams
Last modified 5mo ago