diff --git a/steel/README.md b/steel/README.md index c9e62707..1f71c211 100644 --- a/steel/README.md +++ b/steel/README.md @@ -10,7 +10,7 @@ In the realm of Ethereum and smart contracts, obtaining data directly from the b Traditionally, these operations, especially when it comes to proving and verifying off-chain computations, involve a degree of complexity: either via proof of storage mechanisms requiring detailed knowledge of slot indexes, or via query-specific circuit development. In contrast, this library abstracts away these complexities, allowing developers to query Ethereum's state by just defining the Solidity method they wish to call. -To demonstrate a simple instance of using the view call library, let's consider possibly the most common view call: querying the balance of an ERC-20 token for a specific address. +To demonstrate a simple instance of using this library, let's consider possibly the most common view call: querying the balance of an ERC-20 token for a specific address. You can find the full example [here](../examples/erc20/README.md). ## Guest code @@ -114,19 +114,37 @@ let journal = Journal { env::commit_slice(&journal.abi_encode()); ``` -We also provide an example, [erc20-counter], showcasing such integration. +We provide several examples showcasing such integration, including [erc20-counter] and [token-stats]. -### Block hash validation +### Block commitment validation -Since internally the `blockhash` opcode is used for validation, the commitment must not be older than 256 blocks. -Given a block time of 12 seconds, this allows just over 50 minutes to create the proof and ensure that the validating transaction is included in a block. -In many cases, this will work just fine: even very large computations such as proving an entire Ethereum block can be done in well under 50 minutes with sufficient resources. +Validating the block committed by a Steel proof is essential to ensure that the proof accurately reflects the correct blockchain state. +Steel supports two methods for block validation (see the `validateCommitment` function in [Steel.sol](../contracts/src/steel/Steel.sol)). -For scenarios needing a verified block hash older than 256 blocks: +#### 1. Block hash Commitment -* Save the required block hash to the contract state if known in advance (e.g., when initiating a governance proposal). -* Use RISC Zero to prove the hash chain from the queried block up to a block within the most recent 256. +This method uses the `blockhash` opcode to commit to a block hash that is no more than 256 blocks old. +With Ethereum's 12-second block time, this provides a window of about 50 minutes to generate the proof and ensure that the validating transaction is contained in a block. +This approach is ideal for most scenarios, including complex computations, as it typically provides sufficient time to generate the proof. + +#### 2. Beacon Block Root Commitment + +The second method allows validation using the [EIP-4788] beacon roots contract. +This technique extends the time window in which the proof can be validated on-chain to just over a day, making it suitable for scenarios requiring more extensive computation. +It requires access to a beacon API endpoint and can be enabled by calling `EvmEnv::into_beacon_input`. +However, this approach is specific to Ethereum Steel proofs and depends on the implementation of EIP-4788. + +Note that EIP-4788 only provides access to the parent beacon root, requiring iterative queries in Solidity to retrieve the target beacon root for validation. +This iterative process can result in slightly higher gas costs compared to using the `blockhash` opcode. Overall, it is suitable for environments where longer proof generation times are required. + +#### Bookmarking + +A *bookmarking* validation technique can also be built on top of either block commitment approach. +The idea is to store the target block commitment in the contract state before generating a Steel proof that targets that specific block. +Once the block hash (or beacon root) has been bookmarked, it can be used later for validation, ensuring that the proof corresponds to the correct blockchain state. [erc20-counter]: ../examples/erc20-counter/README.md +[token-stats]: ../examples/token-stats/README.md [Bonsai Foundry Template]: https://github.com/risc0/bonsai-foundry-template [Steel library]: ../contracts/src/steel/Steel.sol +[EIP-4788]: https://eips.ethereum.org/EIPS/eip-4788