WEB3-22: chore: Expand documentation on how to handle linking Steel proofs to verified block hashes (#244)

This PR integrates the README improvements from #194 .

closes #181 
closes WEB3-22

---------

Co-authored-by: Victor Graf <[email protected]>

Author: Wollac

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