WARNING: Please note that this repository is a work in progress and is currently unaudited. Use it with caution as it may contain unfinished features or bugs."

Introduction

This repository allows users to generate the proofs necessary to prove consensus layer state on EigenLayer, specifically the EigenPods system. These proofs are used for verifying 1) that withdrawal credentials of a validator are pointed to an EigenPod, 2) that changes in balance of a validator due to slashing, etc can be propagated to EigenLayer's smart contracts 3) Prove a validator's withdrawal on the consensus layer, which then allows a staker to withdraw their validator's ETH from their EigenPod. Specifically, these proofs are passed as inputs to the verifyWithdrawalCredentials(), verifyBalanceUpdates() and verifyAndProcessWithdrawals() functions, see here for the exact function interface definitions.

An important note is that this CLI is designed to be used with inputs that can be retrieved from a consensus layer client, here is the relevant API specification.

How to Generate the Proofs with the Proof Generation library

This package allows you to generate withdrawal credential proofs, withdrawal proofs and balance update proofs. To generate the proofs using this library, run the following commands:

Build the Executable

$cd generation
$go build
$cd ..

Generate Validator Withdrawal Credential Proof

Here is the command:

$ ./generation/generation -command ValidatorFieldsProof -oracleBlockHeaderFile [ORACLE_BLOCK_HEADER_FILE_PATH] -stateFile [STATE_FILE_PATH]-validatorIndex [VALIDATOR_INDEX] -outputFile [OUTPUT_FILE_PATH] -chainID [CHAIN_ID]

Here is an example of running this command with the sample state/block files in the /data folder

./generation/generation -command ValidatorFieldsProof -oracleBlockHeaderFile "../data/goerli_block_header_6399998.json" -stateFile "../data/goerli_slot_6399998.json" -validatorIndex 302913 -outputFile "withdrawal_credential_proof_302913.json" -chainID 5

Generate Withdrawal Proof

Here is the command:

$ ./generation/generation -command WithdrawalFieldsProof -oracleBlockHeaderFile [ORACLE_BLOCK_HEADER_FILE_PATH] -stateFile [STATE_FILE_PATH]-validatorIndex [VALIDATOR_INDEX] -outputFile [OUTPUT_FILE_PATH] -chainID [CHAIN_ID] -historicalSummariesIndex [HISTORICAL_SUMMARIES_INDEX] -blockHeaderIndex [BLOCK_HEADER_INDEX] -historicalSummaryStateFile [HISTORICAL_SUMMARY_STATE_FILE_PATH] -blockHeaderFile [BLOCK_HEADER_FILE_PATH] -blockBodyFile [BLOCK_BODY_FILE_PATH] -withdrawalIndex [WITHDRAWAL_INDEX]

Here is an example of running this command with the sample state/block files in the /data folder

./generation/generation -command WithdrawalFieldsProof -oracleBlockHeaderFile "../data/goerli_block_header_6399998.json" -stateFile "../data/goerli_slot_6399998.json" -validatorIndex 200240 -outputFile "withdrawal_proof_302913.json" -chainID 5 -historicalSummariesIndex 146 -blockHeaderIndex 8092 -historicalSummaryStateFile "../data/goerli_slot_6397852.json" -blockHeaderFile  "../data/goerli_block_header_6397852.json" -blockBodyFile "../data/goerli_block_6397852.json" -withdrawalIndex 0

Generate a Balance Update Proof.

$ ./generation/generation "BalanceUpdateProof"  -oracleBlockHeaderFile [ORACLE_BLOCK_HEADER_FILE_PATH] -stateFile [STATE_FILE_PATH]-validatorIndex [VALIDATOR_INDEX] -outputFile [OUTPUT_FILE_PATH] -chainID [CHAIN_ID]

Here is an example of running this command with the sample state/block files in the /data folder:

./generation/generation -command BalanceUpdateProof -oracleBlockHeaderFile "../data/goerli_block_header_6399998.json" -stateFile "../data/goerli_slot_6399998.json" -validatorIndex 302913 -outputFile "withdrawal_credential_proof_302913.json" -chainID 5

Proof Generation Input Glossary

oracleBlockHeaderFile is the block header of the oracle block heade root being used to make the proof
stateFile is the associated state file of the oracle block being used
validatorIndex is the index of the validator being proven for in the consensus layer
outputFile is the location where the generated proof will be written to
chainID is the chainID (either goerli = 5 or mainnet = 1) being generated for.
historicalSummariesIndex refer to What Are Historical Summary Proofs? secion. This is the index of the historical summary we're gonna use to prove the withdrawal
historicalSummaryStateFile state file corresponding to the state_summary_root stored in the historical summary we're gonna use.
blockHeaderIndex index of the block header that contains the withdrawal being proven
blockHeaderFile file containing the block header that contains the withdrawal being proven
blockBodyFile file containing the block body that contains the withdrawal being proven
withdrawalIndex index of the withdrawal being proven within the block (there are 16 withdrawals per block).

What Are Historical Summary Proofs?

Historical summary proofs allow us to prove withdrawals from more than 27 hours (8192 slots) after they are included in the beacon chain. Currently we require the submission of a historical summary proof which forces any withdrawers to wait at the most 27 hours before the historical_summaries container is updated with the latest historical summary that includes the block root with the withdrawal in question. Refer here for the beacon chain specs for historical summaries.

youfoundron / eigenpod-proofs-generation