# Fusaka Auditor Handbook ## Local devnets for testing A Kurtosis package that deploys a private, portable, and modular Ethereum devnet: https://github.com/ethpandaops/ethereum-package https://ethpandaops.io/posts/kurtosis-deep-dive/ Kurtosis Discord: https://discord.gg/hUcHAGsT ### Quick-start Here are some quick steps to get a fuskaka devnet with 6 different client pairs running: ``` Install docker & kurtosis Create a network-params.yaml: https://gist.github.com/pk910/96296447f54591d1ea726363688ce3b6 Start the devnet with: kurtosis run github.com/ethpandaops/ethereum-package --args-file ./network-params.yaml --image-download always (The client images will change when clients do proper releases with fulu support.) ``` ## Specifications ### EIPs #### Scheduled for Inclusion – Core EIPs - [EIP-7594: PeerDAS - Peer Data Availability Sampling](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-7594.md) - [EIP-7823: Set upper bounds for MODEXP](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-7823.md) - [EIP-7825: Transaction Gas Limit Cap](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-7825.md) - [EIP-7883: ModExp Gas Cost Increase](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-7883.md) - [EIP-7892: Blob Parameter Only Hardforks](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-7892.md) - [EIP-7917: Deterministic proposer lookahead](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-7917.md) - [EIP-7918: Blob base fee bounded by execution cost](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-7918.md) - [EIP-7934: RLP Execution Block Size Limit](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-7934.md) - [EIP-7935: Set default gas limit to XX0M](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-7935.md) - [EIP-7939: Count leading zeros (CLZ) opcode](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-7939.md) - [EIP-7951: Precompile for secp256r1 Curve Support](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-7951.md) #### Scheduled for Inclusion – Other EIPs - [EIP-7642: eth/69 - Drop pre-merge fields](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-7642.md) - [EIP-7910: eth_config JSON-RPC Method](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-7910.md) ### [consensus-specs](https://github.com/ethereum/consensus-specs) - [fulu spec](https://github.com/ethereum/consensus-specs/tree/master/specs/fulu) Tip: Use the [Ethereum Spec Viewer](https://jtraglia.github.io/eth-spec-viewer/) to compare with previous specifications. At the top of the page, select "Fulu" in the "Filter by fork" dropdown box, then click "Apply Filters". ### [execution-specs](https://github.com/ethereum/execution-specs) - [osaka spec](https://github.com/ethereum/execution-specs/tree/forks/osaka/src/ethereum/osaka) ## Previous Audits N/A ## Known issues Known issues are unfortunately scattered across a multitude of locations, such as github issues, commits, PRs, [Eth R&D Discord](https://discord.gg/rBk63MJA), [Random Notes](https://notes.ethereum.org/zXTQhlFUQJC7JgDUuxI1KQ), forum posts, etc. Given the decentralized nature of Ethereum, it is not possible to keep them in a single location. Something will need to have been reasonable public and accessible for it to be labelled as a known issue. ## Consensus Layer Clients ### [Lighthouse](https://github.com/sigp/lighthouse) This is a guide to the implementation of the Fulu hard fork in Lighthouse, aimed at security researchers and testers. #### Branches All Fulu changes are aleady on the [`unstable`](https://github.com/sigp/lighthouse/tree/unstable) branch, and we plan to cut a release candidate branch some time early September, likely named `release-v8.0.0-rc.0` for the holesky fork release. Reviews today should focus on the **`unstable`** branch until the release branch is created. #### Core Consensus Types Lighthouse uses a library called [`superstruct`](https://crates.io/crates/superstruct) to generate fork-specific variants of data types like BeaconState, BeaconBlock, etc. These types live inside the `consensus/types` crate. Some key Fulu types: - [`data_column_sidecar.rs`](https://github.com/sigp/lighthouse/blob/34dd1b27aeb4d786f20655a8c03128a0375d2ad5/consensus/types/src/data_column_sidecar.rs#L109): Data column sidecar struct with KZG commitments and proofs - [`beacon_state.rs`](https://github.com/sigp/lighthouse/blob/836c39efaaeeb29823d0b66bcd42adb1347ea3f1/consensus/types/src/beacon_state.rs#L561): New `proposer_lookahead` field in Fulu beacon state #### Execution layer interaction Lighthouse’s code for interacting with execution layer (EL) clients lives in [`beacon_node/execution_layer`](https://github.com/sigp/lighthouse/blob/34dd1b27aeb4d786f20655a8c03128a0375d2ad5/beacon_node/execution_layer). #### Upgrade to Fulu See state upgrade process in the [`upgrade_to_fulu`](https://github.com/sigp/lighthouse/blob/b08d49c4cb340eacd8d77a7a04df006e145c21a5/consensus/state_processing/src/upgrade/fulu.rs#L8) function #### EIP-7594: PeerDAS ##### Custody Groups, Columns & Subnets - [`validator_custody.rs`](https://github.com/sigp/lighthouse/blob/2d223575d614bb163be8d6734f2e9fd150aa32ed/beacon_node/beacon_chain/src/validator_custody.rs#L124) contains the logic for validator custody calculation and changes - [`data_column_custody_group.rs`](https://github.com/sigp/lighthouse/blob/b4704eab4ac8edf0ea0282ed9a5758b784038dd2/consensus/types/src/data_column_custody_group.rs#L22) contains functions for calculating custody groups, column subnets and custody columns ##### Network - [`rpc_methods.rs`](https://github.com/sigp/lighthouse/blob/2d223575d614bb163be8d6734f2e9fd150aa32ed/beacon_node/network/src/network_beacon_processor/rpc_methods.rs): contains new RPC interfaces including `DataColumnsByRoot` and `DataColumnsByRange` - [`gossip_methods.rs`](https://github.com/sigp/lighthouse/blob/522bd9e9c6ac167f2231525e937c9ebbcb86cf6e/beacon_node/network/src/network_beacon_processor/gossip_methods.rs): handling of gossip messages, including the new `data_column_sidecar` gossip topics - [`sync_methods.rs`](https://github.com/sigp/lighthouse/blob/522bd9e9c6ac167f2231525e937c9ebbcb86cf6e/beacon_node/network/src/network_beacon_processor/sync_methods.rs): handles the processing of RPC responses including data columns. ##### Sync See the [sync](https://github.com/sigp/lighthouse/blob/b4704eab4ac8edf0ea0282ed9a5758b784038dd2/beacon_node/network/src/sync) module for all the sync components including range sync, backfill sync and block lookups. A high diagram of how these components interacts can be found [here](https://github.com/sigp/lighthouse/blob/522bd9e9c6ac167f2231525e937c9ebbcb86cf6e/beacon_node/network/src/sync/tests/mod.rs#L34-L50). ##### Data Column Verification and Data Availability Check - [`validate_data_column_sidecar_for_gossip`](https://github.com/sigp/lighthouse/blob/b4704eab4ac8edf0ea0282ed9a5758b784038dd2/beacon_node/beacon_chain/src/data_column_verification.rs#L478) function to gossip verify data columns, including KZG verifciation - [`verify_kzg_for_rpc_block`](https://github.com/sigp/lighthouse/blob/b4704eab4ac8edf0ea0282ed9a5758b784038dd2/beacon_node/beacon_chain/src/data_availability_checker.rs#L359) function to verify a single RPC block. - [`verify_kzg_for_rpc_blocks`](https://github.com/sigp/lighthouse/blob/b4704eab4ac8edf0ea0282ed9a5758b784038dd2/beacon_node/beacon_chain/src/data_availability_checker.rs#L421) function to verify a `Vec` of RPC block, used by range and backfill sync. - [`DataAvailabilityChecker`](https://github.com/sigp/lighthouse/blob/b4704eab4ac8edf0ea0282ed9a5758b784038dd2/beacon_node/beacon_chain/src/data_availability_checker.rs#L118) manages data availaility checks, and reconstruction - [kzg_utils.rs](https://github.com/sigp/lighthouse/blob/b4704eab4ac8edf0ea0282ed9a5758b784038dd2/beacon_node/beacon_chain/src/kzg_utils.rs) contains functions for all KZG operations (`blobs_to_data_column_sidecars`, `compute_cells`, `validate_data_columns`) #### EIP-7917: Deterministic Proposer Lookahead - [`eth_spec.rs`](https://github.com/sigp/lighthouse/blob/b4704eab4ac8edf0ea0282ed9a5758b784038dd2/consensus/types/src/eth_spec.rs#L52): contains the `EthSpec` (spec preset) trait and structs for spec presets, including the `ProposerLookaheadSlots` configuration for EIP-7917. - [`initialize_proposer_lookahead`](https://github.com/sigp/lighthouse/blob/b08d49c4cb340eacd8d77a7a04df006e145c21a5/consensus/state_processing/src/upgrade/fulu.rs#L21): proposer lookahead initialisation as part of Fulu state upgrade. - [`process_proposer_lookahead`](https://github.com/sigp/lighthouse/blob/522bd9e9c6ac167f2231525e937c9ebbcb86cf6e/consensus/state_processing/src/per_epoch_processing/single_pass.rs#L476): logic to process proposer lookahead as part of per epoch processing. - [`BeaconStatae::get_beacon_proposer_index`](https://github.com/sigp/lighthouse/blob/836c39efaaeeb29823d0b66bcd42adb1347ea3f1/consensus/types/src/beacon_state.rs#L1106) #### EIP-7892: Blob Parameter Only Hardforks - [`chain_spec.rs`](https://github.com/sigp/lighthouse/blob/836c39efaaeeb29823d0b66bcd42adb1347ea3f1/consensus/types/src/chain_spec.rs#L1463-1541): contains the `ChainSpec` (spec config) and BPO fork (EIP-7892) types `BlobParameters` and `BlobSchedule`. - [`fork_context.rs`](https://github.com/sigp/lighthouse/blob/522bd9e9c6ac167f2231525e937c9ebbcb86cf6e/consensus/types/src/fork_context.rs#L34): provides fork specific info like the current fork name and the fork digests corresponding to every valid fork. - [`NetworkService::update_next_fork_digest`](https://github.com/sigp/lighthouse/blob/522bd9e9c6ac167f2231525e937c9ebbcb86cf6e/beacon_node/network/src/service.rs#L819): Logic to transition to a new named fork or BPO fork. ### [Prysm](https://github.com/prysmaticlabs/prysm) Review branch: `develop` https://github.com/OffchainLabs/prysm/pulls?q=is%3Apr+label%3Afulu https://github.com/OffchainLabs/prysm/pulls?q=is%3Apr+label%3Apeer-das The [`specrefs`](https://github.com/OffchainLabs/prysm/tree/develop/specrefs) can be used to find implementations of the [fulu specifications](https://github.com/ethereum/consensus-specs/tree/master/specs/fulu) in Prysm. To find items for this fork, search for `fork="fulu"` in each file. For example: ![](https://notes.ethereum.org/_uploads/B1FfDWrYxg.png) ### [Teku](https://github.com/Consensys/teku) Review branch: `master` The [`specrefs`](https://github.com/Consensys/teku/tree/master/specrefs) can be used to find implementations of the [fulu specifications](https://github.com/ethereum/consensus-specs/tree/master/specs/fulu) in Teku. To find items for this fork, search for `fork="fulu"` in each file. For example: ![](https://notes.ethereum.org/_uploads/S1g0ObL-ulg.png) ### [Lodestar](https://github.com/ChainSafe/lodestar/) Find Lodestar's auditor handbook here: * https://hackmd.io/@philknows/Hywn5GzOge ### [Grandine](https://github.com/grandinetech/grandine) Grandine tracks changes Fulu-related changes in [peerdas-fulu branch]( https://github.com/grandinetech/grandine/tree/peerdas-fulu). The diff between the develop can be found [here](https://github.com/grandinetech/grandine/compare/develop...peerdas-fulu ). ### [Nimbus](https://github.com/status-im/nimbus-eth2) To find Fulu-specific code and codepaths in Nimbus, one can start with by finding the Nim identifiers: - `ConsensusFork.Fulu`; - `FULU_FORK_EPOCH`; - `FULU_FORK_VERSION` Fulu constants and datatypes are defined in - `beacon_chain/spec/datatypes/fulu.nim` - `beacon_chain/spec/mev/fulu_mev.nim` - `beacon_chain/spec/presets/gnosis/fulu_preset.nim` - `beacon_chain/spec/presets/mainnet/fulu_preset.nim` - `beacon_chain/spec/presets/minimal/fulu_preset.nim` `beacon_chain/spec/` contains most hardfork-specific code, various of which concerns Fulu. Parts are outside that, for example the `beacon_chain/sync/` code has to handle Pectra-specific concerns at times due to syncing and req/resp'ing columns instead of blobs. To find the Fulu functions and datatypes from another direction, starting from https://github.com/ethereum/consensus-specs/blob/v1.6.0-alpha.4/specs/fulu/beacon-chain.md and browsing any new, modified, or extended containers and simply searching for those exact strings in Nimbus will generally find them, as Nimbus when possible attempts to nominally and structurally mirror the consensus specs. Similarly, all of the function names (new `get_blob_parameters`, modified `compute_fork_digest`, et cetera) directly appear in a basically 1:1 way in Nimbus, mirroring the spec code as closely as practically feasible. This also applies to https://github.com/ethereum/consensus-specs/blob/v1.6.0-alpha.4/specs/fulu/p2p-interface.md where one can search for, e.g., `DATA_COLUMN_SIDECAR_SUBNET_COUNT` and `MIN_EPOCHS_FOR_DATA_COLUMN_SIDECARS_REQUESTS` and find relevant handling, because Nimbus mirrors those precisely. Conceptually, the bulk of changes in the Nimbus CL for Fusaka are due to PeerDAS. As such, anything handling `ColumnQuarantine`, `DataColumn`, `DataColumnIdentifier`, `DataColumnSidecar`, supernodes, or validator custody is new to Fulu, even if it doesn't by name call itself Fulu. Furthermore, any and all BPO code is new to Fulu. ## Execution Layer Clients ### [Go-Ethereum](https://github.com/ethereum/go-ethereum) Most PRs related to Fusaka have been tagged "Osaka": https://github.com/ethereum/go-ethereum/pulls?q=is%3Apr+label%3Aosaka+ ### [Nethermind](https://github.com/NethermindEth/nethermind) ### [Erigon](https://github.com/erigontech/erigon) The following should be the majority of Fusaka changes: https://github.com/erigontech/erigon/pulls?q=is%3Apr+label%3AFUSAKA ### [Reth](https://github.com/paradigmxyz/reth/) ### [Besu](https://github.com/hyperledger/besu) Most PRs related to Fusaka have been tagged "Osaka": https://github.com/hyperledger/besu/pulls?q=label%3AOsaka
Last changed by  
 
Fredrik Svantes
1866
Published on HackMD