A trustless oracle for the ETH/stETH Curve pool using Merkle Patricia proofs of Ethereum state.
The oracle currently assumes that the pool's fee
and A
(amplification coefficient) values don't
change between the time of proof generation and submission.
The oracle works by generating and verifying Merkle Patricia proofs of the following Ethereum state:
-
Curve stETH/ETH pool contract account and the following slots from its storage trie:
admin_balances[0]
admin_balances[1]
-
stETH contract account and the following slots from its storage trie:
shares[0xDC24316b9AE028F1497c275EB9192a3Ea0f67022]
keccak256("lido.StETH.totalShares")
keccak256("lido.Lido.beaconBalance")
keccak256("lido.Lido.bufferedEther")
keccak256("lido.Lido.depositedValidators")
keccak256("lido.Lido.beaconValidators")
The repo contains two main contracts:
-
StableSwapStateOracle.sol
is the main oracle contract. It receives and verifies the report from the offchain code, and persists the verified state along with its timestamp. -
StableSwapPriceHelper.vy
is a helper contract used byStableSwapStateOracle.sol
and written in Vyper. It contains the code for calculating exchange price based on the pool state. The code is copied from the actual pool contract with minimal modifiactions.
First, deploy StableSwapPriceHelper
. Then, deploy StableSwapStateOracle
, pointing it
to StableSwapPriceHelper
using the constructor param:
# assuming eth-brownie console
helper = StableSwapPriceHelper.deploy({ 'from': deployer })
oracle = StableSwapStateOracle.deploy(helper, { 'from': deployer })
To send proofs to the state oracle, call submitState
function:
header_rlp_bytes = '0x...'
proofs_rlp_bytes = '0x...'
tx = oracle.submitState(header_rlp_bytes, proofs_rlp_bytes, { 'from': reporter })
The function is permissionless and, upon successful verification, will generate two events,
SlotValuesUpdated
and PriceUpdated
, and update the oracle with the verified pool balances
and stETH price. You can access them by calling getState
and getPrice
:
(timestamp, etherBalance, stethBalance, stethPrice) = oracle.getState()
stethPrice = oracle.getPrice()
Use the following script to generate and submit a proof to the oracle contract:
python offchain/generate_steth_price_proof.py \
--rpc <HTTP RPC endpoint of a geth full node> \
--keyfile <path to a JSON file containing an encrypted private key> \
--gas-price <tx gas price in wei> \
--contract <state oracle contract address> \
--block <block number>
Some flags are optional:
- Skip the
--keyfile
flag to print the proof without sending a tx. - Skip the
--gas-price
flag to use gas prive determined by the node. - Skip the
--block
flag to generate a proof correnspoding to the blocklatest - 15
.