Maker Protocol Technical Docs
  • MakerDAO Technical Docs
  • Getting Started
    • Maker Protocol 101
  • Smart Contract Modules
    • Dai Module
      • Dai - Detailed Documentation
    • Core Module
      • Vat - Detailed Documentation
      • Spot - Detailed Documentation
    • Collateral Module
      • Join - Detailed Documentation
    • Liquidation 2.0 Module
    • System Stabilizer Module
      • Flapper - Detailed Documentation
      • Flopper - Detailed Documentation
      • Vow - Detailed Documentation
    • Oracle Module
      • Oracle Security Module (OSM) - Detailed Documentation
      • Median - Detailed Documentation
    • MKR Module
    • Governance Module
      • Spell - Detailed Documentation
      • Pause - Detailed Documentation
      • Chief - Detailed Documentation
    • Rates Module
      • Pot - Detailed Documentation
      • Jug - Detailed Documentation
    • Proxy Module
      • Proxy Actions - Detailed Documentation
      • Vote Proxy - Detailed Documentation
      • CDP Manager - Detailed Documentation
      • DSR Manager - Detailed Documentation
    • Flash Mint Module
    • Maker Protocol Emergency Shutdown
      • Emergency Shutdown for Partners
      • The Emergency Shutdown Process for Multi-Collateral Dai (MCD)
      • End - Detailed Documentation
      • ESM - Detailed Documentation
  • Glossary
    • MCD Glossaries
    • Smart Contract Annotations
  • Deployment Addresses
    • Maker Protocol Deployments
  • Security
    • Security for the Maker Protocol
  • Building on top of the Maker Protocol
    • Developer Guides and Tutorials
    • The Dai Javascript Library of the Maker Protocol
      • Getting started
      • Configuration
        • Plugins
      • Vault manager
      • Collateral types
      • Dai Savings Rate
      • Currency units
      • System data
      • Advanced
        • Transaction manager
        • DSProxy
        • Events
        • Using multiple accounts
        • Adding a new service
      • Single-Collateral Sai
        • Collateralized Debt Position
        • CDP Service
        • Price Service
        • System Status
        • Tokens
        • Token Conversion
        • Exchange Service
    • Pymaker
  • Keepers
    • The Auctions of the Maker Protocol
    • Auction Keepers
      • Auction Keeper Bot Setup Guide
    • Market Maker Keepers
      • Market Maker Keeper Bot Setup Guide
    • Cage Keeper
    • Simple Arbitrage Keeper
    • Chief Keeper
  • Command-line Interfaces
    • Seth
    • Multi Collateral Dai (MCD) CLI
    • Dai and Collateral Redemption during Emergency Shutdown
    • Emergency Shutdown (ES) CLI
  • Miscellaneous
    • Liquidations 1.2 System (Deprecated)
      • Cat - Detailed Documentation
      • Flipper - Detailed Documentation
    • SCD <> MCD Migration
    • Upgrading to Multi-Collateral Dai Guide
Powered by GitBook
On this page
  • 1. Introduction (Summary)
  • 2. Module Details
  • Oracle Module Components Documentation
  • 3. Key Mechanism and Concepts
  • 4. Gotchas (Potential sources of user error)
  • 5. Failure Modes (Bounds on Operating Conditions & External Risk Factors)
Export as PDF
  1. Smart Contract Modules

Oracle Module

The Maker Protocol's Oracles

PreviousVow - Detailed DocumentationNextOracle Security Module (OSM) - Detailed Documentation

Last updated 5 years ago

  • Module Name: Oracle Module

  • Type/Category: Oracles —> OSM.sol & Median.sol

  • Contract Sources:

1. Introduction (Summary)

An oracle module is deployed for each collateral type, feeding it the price data for a corresponding collateral type to the Vat. The Oracle Module introduces the whitelisting of addresses, which allows them to broadcast price updates off-chain, which are then fed into a median before being pulled into the OSM. The Spot'ter will then proceed to read from the OSM and will act as the liaison between the oracles and dss.

2. Module Details

The Oracle Module has 2 core components consisting of the Median and OSM contracts.

Oracle Module Components Documentation

3. Key Mechanism and Concepts

Summary of the Oracle Module Components

  • The Median provides Maker's trusted reference price. In short, it works by maintaining a whitelist of price feed contracts which are authorized to post price updates. Every time a new list of prices is received, the median of these is computed and used to update the stored value. The median has permissioning logic which is what enables the addition and removal of whitelisted price feed addresses that are controlled via governance. The permissioning logic allows governance to set other parameters that control the Median's behavior—for example, the bar parameter is the minimum number of prices necessary to accept a new median value.

4. Gotchas (Potential sources of user error)

Relationship between the OSM and the Median:

  • You can read straight from the median and in return, you would get a more real-time price. However, this depends on the cadence of updates (calls to poke).

  • The OSM is similar but has a 1-hour price delay. It has the same process for reading (whitelist, auth, read and peek) as a median. The way the OSM works, is you cannot update it directly but you can poke it to go and read from something that also has the same structure (the peek method - in this case, its the median but you can set it to read from anything that conforms to the same interface).

  • Whenever the OSM reads from a source, it queues the value that it reads for the following hour or following hop property, which is set to 1 hour (but can be anything). When it is poke'd, it reads the value of the median and it will save the value. Then the previous value becomes that, so it is always off by an hour. After an hour passes, when poked, the value that it saved becomes the current value and whatever value is in the median becomes the future value for the next hour.

  • spot - if you poke it with an ilk (ex: ETH) it will read form the OSM and if the price is valid, it updates.

Relationship to the Spot'ter:

  • In relation to the Spot the oracle module handles how market prices are recorded on the blockchain. The Spotter operates as the interface contract, which external actors can use to retrieve the current market price from the Oracle module for the specified collateral type. The Vat in turn reads the market price from the spotter.

5. Failure Modes (Bounds on Operating Conditions & External Risk Factors)

  • Median - there is currently no way to turn off the oracle (failure or returns false) if all the oracles come together and sign a price of zero. This would result in the price being invalid and would return false on peek, telling us to not trust the value.

  • OSM

    • poke() is not called promptly, allowing malicious prices to be swiftly uptaken.

    • Authorization Attacks and Misconfigurations.

The OSM (named via acronym from "Oracle Security Module") ensures that new price values propagated from the Oracles are not taken up by the system until a specified delay has passed. Values are read from a designated contract (or any contract that implements the read() and peek() interface) via the poke() method; the read() and peek() methods will give the current value of the price feed, and other contracts must be whitelisted in order to call these. An OSM contract can only read from a single price feed, so in practice one OSM contract must be deployed per collateral type.

Read more

Associated MCD System Diagram
Median
OSM
Median Documentation
OSM Documentation
DSValue
here.
Interaction Diagram (Credit: MCD-101 Presentation, by Kenton Prescott)