ERC-7412 On-demand off-chain data lookup (On-Demand Off-Chain Data Retrieval)
Draft · Other · created 2023-07-26
A standard in which, when a contract needs off-chain data during execution, it halts execution with a designated error, and the client fetches the signed data and prepends a verification call to build a multicall transaction.
Why it is needed
Ethereum's scaling roadmap is moving toward splitting into multiple execution environments such as layer 2s and layer 3s. As a result, the ability to read data from multiple chains has become important for building scalable apps, but it is unrealistic to expect oracle networks to continuously push vast amounts of price data into every layer 2 and layer 3. Bridges for writing data to other chains are being developed, but a similar standard is needed for reading data from other chains or off-chain. The existing ERC-3668 introduced a way to request off-chain data using revert (halting execution), but because it relies on callback functions, it struggles to handle situations where nested calls each require different off-chain data. This standard uses multicall (bundling multiple calls into a single transaction) instead of callbacks to overcome this constraint.
What to implement
error OracleDataRequired(address oracleContract, bytes oracleQuery, uint256 feeRequired): When off-chain data is needed, the contract reverts with this error. It indicates which oracle contract and which query should be used to obtain the data, and the fee required.function oracleId() view external returns (bytes32 oracleId);: Returns a unique identifier pointing to the decentralized oracle network that produces the desired signed data.function fulfillOracleQuery(bytes signedOffchainData) payable external;: Receives signed off-chain data, verifies it, and records it on-chain so that subsequent calls can read it.error FeeRequired(uint amount): An error that reverts when a fee is required to process a query. amount is the amount of native gas token, in wei.error Errors(bytes[] errors);: An optional error that bundles multiple errors together at once. It lets a client handle several data requests in a single simulation.
In depth
Structure of the OracleDataRequired error
Contracts implementing this standard MUST revert with error OracleDataRequired(address oracleContract, bytes oracleQuery, uint256 feeRequired) whenever off-chain data is needed. oracleQuery specifies the off-chain data needed, and the valid data format depends on the oracle ID that the oracle contract advertises. For a cross-chain read, it might contain a chain ID, contract address, function signature, payload, and a timestamp or 'latest'; for a price feed, it might contain a ticker symbol and a timestamp. oracleContract is the address of the contract that can resolve this error by verifying and supplying the off-chain data.
The IERC7412 interface and oracle ID
The oracle contract MUST implement the IERC7412 interface. oracleId() returns a unique identifier pointing to the decentralized oracle network that produces the desired signed off-chain data. The original text compares the oracle ID to a chain ID within the Ethereum ecosystem: just as a client looks up an RPC endpoint from a chain ID, it is expected to look up a gateway corresponding to an oracle ID. fulfillOracleQuery(bytes signedOffchainData) receives signed off-chain data, verifies it, and records it on-chain. It must be possible to derive oracleQuery from signedOffchainData, so that the oracle contract can supply verified data based on the query.
Fee handling: FeeRequired
If processing a query requires a cost, a contract implementing IERC7412 MUST revert with error FeeRequired(uint amount). amount represents, in wei, the amount of native gas token required to execute fulfillOracleQuery. This error must be resolved once the caller sends enough msg.value to cover the fee. However, any gas token sent in excess of amount MAY NOT be refunded. The original text notes that in practice the fee is expected to remain nearly constant. This structure creates an economic incentive by collecting fees from data consumers and providing them to the decentralized oracle network's node operators.
Bundling multiple requests: the Errors array
For cases where multiple oracle data requests are needed at once, such as a protocol that uses several price feeds simultaneously, the interface MAY include a bundling error, error Errors(bytes[] errors). This lets a client efficiently handle multiple OracleDataRequired errors in a single transaction simulation, reducing the number of separate requests needed. A client encountering this error must parse and handle each error in the array individually, and may use recursion if there are nested error objects.
Responsibility for assembling the multicall and wallet support
How to assemble the multicall is the client's responsibility. The necessary fulfillOracleQuery calls are placed before the original call, bundling everything into a single atomic transaction. Wallets supporting ERC-4337 account abstraction can already construct atomic multi-operations, and to support EOAs (externally owned accounts), a protocol may implement ERC-2771. A generic multicall contract has the constraint that it can only bundle functions that do not reference msg.sender or msg.data. Meanwhile, by using a URI for the oracleId and specifying a URI in oracleQuery, this can be made compatible with arbitrary on-chain URIs without modifying client libraries, similar to ERC-3668.
Differences from ERC-3668
This proposal is effectively an alternative to ERC-3668. Its error structure is very simple, so implementers only need to know which oracle network to rely on, the query format that network accepts, and which contract will receive the data. Because it relies on multicall instead of callbacks, it can handle situations where nested calls each require different off-chain data much more simply. Even when using account abstraction clients, the end user only needs to sign a single transaction no matter how complex the internal call structure is, and the client automatically prepends the necessary off-chain data. Oracle providers can also scalably support an unlimited number of networks, and it is compatible with local and forked networks used for protocol development.
Behavior shown by the reference implementation
The client pseudocode in the original text simulates the desired transaction, and when an OracleDataRequired error occurs, it fetches the off-chain data, prepends a verification transaction to the front of the multicall, and repeats this until the error no longer occurs. The example oracle contract stores the verified data in a latestVerifiedData mapping. If the timestamp of the stored data is older than STALENESS_TOLERANCE (86400 seconds, one day), it reverts with OracleDataRequired again. In the example higher-level contract CrosschainAdder, the developer can call the oracle contract's functions as if reading on-chain data, without needing to worry about the standard's implementation. Such cross-chain functions can also be used to let two chain IDs point to the chain itself where it is deployed, in order to offload computation-heavy view functions externally and avoid O(n) or worse on-chain iteration.
Proposal status: Draft
This document is a Standards Track ERC currently in Draft status per the source. It was created on July 26, 2023 and has not yet been finalized, so specification details such as error formats or interfaces may change. It is advisable to check the latest source before implementing or depending on it.
Things to watch out for
- Multicalls can obscure transaction content: In wallets without sophisticated transaction decoding, reliance on multicall-based structures can obscure transaction content. Multicalls are becoming increasingly common in protocol development independent of this standard, and this is a challenge wallet developers are already addressing.
- Validating data is the responsibility of the oracle contract: Validating the data provided by an oracle network is the responsibility of the oracle contract. This standard itself does not create new opportunities for invalid data to be provided to smart contracts.