Ethereum oracle

Ethereum oracle

Published June 21, 2017


We present a peer-to-peer methodology for trading ERC20 tokens on the Ethereum blockchain. Very first, we outline the limitations of blockchain order books and suggest a strong alternative in peer-to-peer token trading: off-chain negotiation and on-chain settlement. We then describe a protocol through which parties are able to signal to others their intent to trade tokens. Once connected, counterparties loosely communicate prices and transmit orders among themselves. During this process, parties may request prices from an independent third party oracle to verify accuracy. Eventually, we present an Ethereum brainy contract to pack orders on the Ethereum blockchain.

Table of Contents

The number of digital assets on Ethereum over the past twelve months has enlargened aggressively as more and more use cases are implemented as clever contracts. It is our thesis that this trend will proceed into the future, as such we believe this growth will augment the request to exchange into and out of assets as users budge inbetween use cases or rebalance their tokenized portfolios. Exchanges based on blockchain order books are not without inherent limitations, many of which can be mitigated by the design decisions outlined in this paper. We seek to provide an alternative to blockchain order books by specifying a set of protocols that unlock asset liquidity and free the Ethereum ecosystem to progress without such limitations.

Order Books

Order books suggest a very automatable way to match supply and request of a given tradeable asset. Traditionally, these are centralized and are combined with order execution, which permits orders to be created, executed, and canceled at a central source of truth. In the spirit of decentralization, order books have been redesigned for blockchains. However, deploying an order book on a blockchain presents several constraints.

Blockchain order books do not scale. Executing code on a blockchain incurs a cost, so an automated order-cancel-order cycle quickly becomes expensive and defeats the strength of an order book as a high spectacle, automatable matching system. Indeed, if that matching algorithm is running on the blockchain, a party placing orders will incur an execution cost that increases substantially with the size of the order book.

Blockchain order books are public. Because the transaction to create an order on the blockchain is processed by miners, those miners are privy to an order before it’s posted to the book. This creates an chance for front-running that could materially affect the original order. Additionally, because the order is published publicly, the order price is the same for everyone, removing a supplier’s capability to tailor liquidity.

Blockchain order books are unfair. Physically distributed systems inherently suffer latency inbetween their knots. As miners are geographically distributed, sophisticated parties may be able to colocate, detect orders, and outperform blockchain latency, effectively acting on order information before other parties. This information asymmetry may very well dishearten less sophisticated parties from taking part in the ecosystem at all.

Peer-to-peer (P2P)

Alternatively, peer-to-peer trading enables individual parties to trade with each other directly. Most of the transactions we make day to day are peer-to-peer: buying coffee at a cafe, selling boots on eBay, or buying cat food on Amazon. Because these are private transactions inbetween people or businesses, each party knows and ultimately chooses with whom they transact.

Peer-to-peer trading scales. Orders are transmitted inbetween individual parties and are “one and done” as opposed to orders on a public exchange with no assure to fully pack. This makes cancels on an order book a regular occurrence, whereas peer-to-peer orders are likely packed because they are provided to parties that have already voiced interest. Additionally, peer-to-peer supply and request matching can be solved through lightweight peer discovery as opposed to expensive algorithmic matchmaking–regardless of whether on or off chain.

Peer-to-peer trading is private. Once two parties have found and chosen to trade with each other, no third parties are required to negotiate. The communication inbetween these parties remains private for the duration of the negotiation, removing the chance for other parties to act on order request behavior. Only when the order is submitted to be packed will it become public skill.

Peer-to-peer trading is fair. Because orders are created and transmitted directly inbetween two parties, no outside participants can have an advantage. As long as they are working with numerous independent parties, participants can get prices that are comparable to or better than what they would achieve on an exchange. Additionally, those pricing orders can do so aggressively without fear of being taken advantage of by automated, low-latency trading strategies.

The scalability, privacy, and fairness constraints imposed by blockchain order books have necessitated an alternative. Today’s Ethereum ecosystem needs an open peer-to-peer solution for asset exchange.

Introducing Exchange

Interchange is a protocol to facilitate a true peer-to-peer ecosystem for trading tokens on the Ethereum blockchain. The following is an extensible specification that supports efficient counterparty discovery and negotiations. These protocols are intended to become a foundation for the asset trading ecosystem and to accelerate Ethereum ecosystem growth. By publishing this paper and opening for discussion, we seek comments from ecosystem stakeholders with the aim to produce high-quality protocols to enable a broad diversity of real-world applications.

With only a few messages passed inbetween counterparties, trades can be negotiated quickly, fairly, and privately. For the purposes of this document, a Maker is the party that provides an order, and a Taker is the party that fills it. Because each party is a peer, any party can assume the role of Maker or Taker at any time. Tokens in the following specification are ERC20 compliant and any token that implements the standard can be traded using this protocol.

The core protocol is sequenced in the following diagram. The Maker and Taker perform trade negotiation off-chain. The Contract below is an Ethereum wise contract, which the Taker calls when ready to pack an order on the blockchain.

  1. Taker calls getOrder on the Maker.
  2. Maker replies with an order.
  3. Taker calls _fill( )_ on the Contract.

Order API

The following APIs are transport-agnostic remote procedure calls (RPC) used to communicate among peers and services. Examples use token tickers instead of addresses, but the actual calls require addresses of ERC20 compliant tokens. The call signatures below are for discussion purposes as further technical details are to be published in a separate document.

The Order API is off-chain and specifies asynchronous calls made inbetween counterparties during trade negotiation. An implementor may choose to serve a request-provide cycle as a synchronous request-response. Because an order is signed by the Maker, the Taker is able to later submit it to the brainy contract to be packed.


getOrder(makerAmount, makerToken, takerToken, takerAddress)

Called by a Taker on a Maker, requesting an order to trade tokens.


provideOrder(makerAddress, makerAmount, makerToken, takerAddress, takerAmount, takerToken, expiration, nonce, signature)

Called by a Maker on a Taker, providing a signed order for execution.

Quote API

Quotes are for indicating price information inbetween parties and are not executable. Quotes can be later turned into orders if the conditions are met for both counterparties.


getQuote(makerAmount, makerToken, takerTokens)

Called by a Taker on a Maker, requesting a quote in specific tokens.


provideQuote(makerAmount, makerToken, takerAmounts)

Called by a Taker on a Maker, providing quotes in Taker tokens.

An Indexer is an off-chain service that aggregates and matches peers based on their intent to trade: whether prospective Makers and Takers wish to buy or sell tokens. Indexers are off-chain services that aggregate this “intent to trade” and help match peers based on intent to buy or sell specific tokens. Many prospective Makers can signal intent to trade, and when a Taker asks the Indexer to find suitable counterparties, there may be numerous results. Once the Taker has found a Maker with whom they would like to trade, they proceed to negotiate using the Peer Protocol above. Once agreement is reached inbetween a Maker and Taker, the order is packed on the clever contract.

The interactions inbetween a Maker, Taker, and Indexer are illustrated in the following diagram. The Maker, Taker, and Indexer all operate away from the blockchain and communicate by any preferred messaging medium.

  1. Maker calls addIntent on the Indexer.
  2. Taker calls findIntent on the Indexer.
  3. Indexer calls _foundIntent( )_ on the Taker.
  4. Taker calls getOrder on the Maker.
  5. Maker replies with an order.
  6. Taker calls _fill( )_ on the Contract.

The interaction inbetween several Makers, a Taker, and an Indexer is illustrated in the following diagram. Each Maker independently announces their intent. The Taker asks to find Makers with specific intent, and the Indexer comes back a list of Ethereum addresses and details.

  1. Several Makers call addIntent on the Indexer.
  2. Taker calls findIntent on the Indexer.
  3. Indexer calls _foundIntent( )_ on the Taker.

Once a Taker has found suitable Makers, they may use the Order API to request orders from each Maker to weigh them against each other. If the Taker has determined to pack a given order, they will make a pack call on the brainy contract.

  1. Taker calls getOrder on several Makers.
  2. Makers reply with orders.
  3. Taker selects an order and calls _fill( )_ on the Contract.

Indexer API

The Indexer API manages intent to trade, which is signalled inbetween peers. The following calls are made inbetween peers and an Indexer.


addIntent(makerToken, takerTokens)

Add an intent to buy or sell some amount of token.


removeIntent(makerToken, takerTokens)

Liquidate an intent to trade tokens.



List active intent associated with an address.


findIntent(makerToken, takerToken)

Find someone willing to trade specific tokens.


foundIntent(makerAddress, intentList)

The Indexer found someone with intent to trade.

An Oracle is an off-chain service that provides pricing information to Makers and Takers. When pricing an order prior to delivering it to a Taker, a Maker may ask the Oracle for what it considers a fair price suggestion. Likewise, having received an order, a Taker may ask the Oracle to check the price on the order to verify that it’s fair. The Oracle provides this pricing information to help both the Maker and the Taker make more educated pricing decisions and to sleek the process of trade negotiation.

  1. Taker calls getOrder on the Maker.
  2. Maker calls getPrice on the Oracle.
  3. Oracle comes back a price to the Maker.
  4. After analyzing price information, Maker replies with an order.
  5. Taker calls _fill( )_ on the Contract.

A very similar interaction happens inbetween Taker and Oracle when the Taker receives an order.

  1. Taker calls getOrder on the Maker.
  2. Maker replies with an order.
  3. Taker calls getPrice on the Oracle.
  4. Oracle comebacks a price to the Taker.
  5. After analyzing price information, Taker calls _fill( )_ on the Contract.

Oracle API

The Oracle API is used by Makers and Takers to determine order prices. Prices are suggestions and are not executable.


getPrice(makerToken, takerToken)

Called by a Taker or a Maker on an Oracle to get a price.


providePrice(makerToken, takerToken, price)

Called by an Oracle on a Maker or Taker to give a price.

An Ethereum brainy contract to pack or cancel orders.

pack(makerAddress, makerAmount, makerToken, takerAddress, takerAmount, takerToken, expiration, nonce, v, r, s)

An atomic interchange of tokens called by a Taker. The contract ensures that the message sender matches taker and ensures that the time indicated in expiration has not passed. To pack orders, peers must have already called approve on the specified tokens to permit the contract to withdraw at least the specified amounts. For token transfers, the contract calls transferFrom on the respective tokens. At the successful completion of this function a Packed event is broadcast to the blockchain. The parameters v , r , and s constitute the maker signature.


cancel(makerAddress, makerAmount, makerToken, takerAddress, takerAmount, takerToken, expiration, nonce, v, r, s)

A cancellation of an order that has already been communicated to a Taker but not yet packed. Called by the Maker of the order. Marks the order as already having been packed on the contract so a subsequent attempt to pack the order will fail. At the successful completion of this function a Canceled event is broadcast to the blockchain.

Ether Orders

The wise contract supports trading ether (ETH) for tokens. If the order includes a null takerToken address (0x0) the wise contract will check the value of ether that was sent with the function call and transfer that on behalf of the Taker to the Maker.

The Interchange protocol serves a growing request for a decentralized asset exchange on the Ethereum network. Blockchain-based order books, while novel and certainly within the ethos of our ecosystem, have limitations that we believe ultimately make it difficult for them to rival with presently available centralized solutions. Exchange provides a method that is both decentralized and unaffected by these limitations.

By implementing the protocol, participants build up access to liquidity in a scalable, private, and fair way, without sacrificing access to superb pricing. The protocol and APIs are extensible and we encourage the community to build applications with us. We welcome feedback and look forward to pushing the Ethereum community forward with you.

Related movie: Ethereum December price predictions

Leave a Reply

Your email address will not be published. Required fields are marked *