refactor(ethereum-common): Add documentation comments (#265)

gear-tech · Dec 24, 2024 · 09ebf00 · 09ebf00
1 parent 8042d1e
commit 09ebf00
Show file tree

Hide file tree

Showing 15 changed files with 98 additions and 5 deletions.
diff --git a/api/gear/ethereum_event_client.idl b/api/gear/ethereum_event_client.idl
@@ -33,10 +33,14 @@ type BlockBody = struct {
   blob_kzg_commitments: h256,
 };
 
+/// A homogenous collection of a fixed number of byte values.
 type BytesFixed1 = struct {
   FixedArray1ForU8,
 };
 
+/// A homogenous collection of a fixed number of values.
+/// 
+/// NOTE: collection of length `0` is illegal.
 type FixedArray1ForU8 = struct {
   [u8, 32],
 };
@@ -61,23 +65,31 @@ type ExecutionPayload = struct {
   excess_blob_gas: u64,
 };
 
+/// A homogenous collection of a fixed number of byte values.
 type BytesFixed2 = struct {
   FixedArray2ForU8,
 };
 
+/// A homogenous collection of a fixed number of values.
+/// 
+/// NOTE: collection of length `0` is illegal.
 type FixedArray2ForU8 = struct {
   [u8, 20],
 };
 
+/// A homogenous collection of a variable number of byte values.
 type ByteList = struct {
   ListForU8,
 };
 
 /// A homogenous collection of a variable number of values.
+/// 
+/// NOTE: collection of length `0` is illegal.
 type ListForU8 = struct {
   data: vec u8,
 };
 
+/// According to Ethereum spec [v1.4.0](https://github.com/ethereum/consensus-specs/blob/v1.4.0/specs/phase0/beacon-chain.md#beaconblockheader).
 type BlockHeader = struct {
   slot: u64,
   proposer_index: u64,

diff --git a/ethereum-common/src/base_types/byte_list.rs b/ethereum-common/src/base_types/byte_list.rs
@@ -1,5 +1,6 @@
 use super::*;
 
+/// A homogenous collection of a variable number of byte values.
 #[derive(Debug, Clone, Decode, Encode, PartialEq, TypeInfo)]
 pub struct ByteList<const N: usize>(pub List<u8, N>);
 

diff --git a/ethereum-common/src/base_types/bytes_fixed.rs b/ethereum-common/src/base_types/bytes_fixed.rs
@@ -1,5 +1,6 @@
 use super::*;
 
+/// A homogenous collection of a fixed number of byte values.
 #[derive(Clone, Debug, Decode, Encode, PartialEq, TypeInfo)]
 pub struct BytesFixed<const N: usize>(pub FixedArray<u8, N>);
 

diff --git a/ethereum-common/src/base_types/fixed_array.rs b/ethereum-common/src/base_types/fixed_array.rs
@@ -1,5 +1,8 @@
 use super::*;
 
+/// A homogenous collection of a fixed number of values.
+///
+/// NOTE: collection of length `0` is illegal.
 #[derive(Clone, TypeInfo)]
 pub struct FixedArray<T, const N: usize>(pub [T; N]);
 

diff --git a/ethereum-common/src/base_types/list.rs b/ethereum-common/src/base_types/list.rs
@@ -1,6 +1,8 @@
 use super::*;
 
 /// A homogenous collection of a variable number of values.
+///
+/// NOTE: collection of length `0` is illegal.
 #[derive(Clone, TypeInfo)]
 pub struct List<T, const N: usize> {
     data: Vec<T>,

diff --git a/ethereum-common/src/base_types/mod.rs b/ethereum-common/src/base_types/mod.rs
@@ -1,5 +1,5 @@
 //! The module contains implementations of basic types used by higher level
-//! types. Inspired by https://github.com/sigp/ssz_types/ and https://github.com/ralexstokes/ssz-rs.
+//! types. Inspired by <https://github.com/sigp/ssz_types> and <https://github.com/ralexstokes/ssz-rs>.
 
 use super::*;
 

diff --git a/ethereum-common/src/beacon/block.rs b/ethereum-common/src/beacon/block.rs
@@ -1,5 +1,6 @@
 use super::*;
 
+/// According to Ethereum spec [v1.4.0](https://github.com/ethereum/consensus-specs/blob/v1.4.0/specs/phase0/beacon-chain.md#beaconblock).
 #[derive(
     Debug, Clone, Decode, Encode, Deserialize, PartialEq, tree_hash_derive::TreeHash, TypeInfo,
 )]

diff --git a/ethereum-common/src/beacon/block_body.rs b/ethereum-common/src/beacon/block_body.rs
@@ -1,5 +1,6 @@
 use super::*;
 
+/// According to Ethereum spec [v1.4.0](https://github.com/ethereum/consensus-specs/blob/v1.4.0/specs/deneb/beacon-chain.md#beaconblockbody).
 #[derive(
     Debug, Clone, Decode, Encode, Deserialize, PartialEq, tree_hash_derive::TreeHash, TypeInfo,
 )]

diff --git a/ethereum-common/src/beacon/block_header.rs b/ethereum-common/src/beacon/block_header.rs
@@ -1,5 +1,6 @@
 use super::*;
 
+/// According to Ethereum spec [v1.4.0](https://github.com/ethereum/consensus-specs/blob/v1.4.0/specs/phase0/beacon-chain.md#beaconblockheader).
 #[derive(
     Debug, Clone, Decode, Encode, Deserialize, PartialEq, tree_hash_derive::TreeHash, TypeInfo,
 )]

diff --git a/ethereum-common/src/beacon/common.rs b/ethereum-common/src/beacon/common.rs
@@ -1,15 +1,22 @@
-//! The module defines types used by Beacon Chain entities. Inspired by
-//! https://github.com/a16z/helios and https://github.com/sigp/lighthouse/ projects.
+//! The module implement types used defined by Ethereum Beacon Chain spec v1.4.0.
+//!
+//! Inspired by <https://github.com/a16z/helios> and <https://github.com/sigp/lighthouse> projects.
 
 use super::*;
 
 pub type Bytes32 = base_types::BytesFixed<32>;
+/// According to Ethereum spec [v1.4.0](https://github.com/ethereum/consensus-specs/blob/v1.4.0/specs/bellatrix/beacon-chain.md#custom-types).
 pub type Address = base_types::BytesFixed<20>;
+/// According to Ethereum spec [v1.4.0](https://github.com/ethereum/consensus-specs/blob/v1.4.0/specs/bellatrix/beacon-chain.md#execution).
 pub type LogsBloom = base_types::BytesFixed<256>;
+/// According to Ethereum spec [v1.4.0](https://github.com/ethereum/consensus-specs/blob/v1.4.0/specs/bellatrix/beacon-chain.md#custom-types).
 pub type Transaction = base_types::ByteList<1_073_741_824>;
+/// According to Ethereum spec [v1.4.0](https://github.com/ethereum/consensus-specs/blob/v1.4.0/specs/phase0/beacon-chain.md#custom-types).
 pub type SignatureBytes = base_types::BytesFixed<96>;
+/// According to Ethereum spec [v1.4.0](https://github.com/ethereum/consensus-specs/blob/v1.4.0/specs/phase0/beacon-chain.md#custom-types).
 pub type BLSPubKey = base_types::BytesFixed<48>;
 
+/// According to Ethereum spec [v1.4.0](https://github.com/ethereum/consensus-specs/blob/v1.4.0/specs/capella/beacon-chain.md#withdrawal).
 #[derive(
     Debug, Clone, Decode, Encode, Deserialize, PartialEq, tree_hash_derive::TreeHash, TypeInfo,
 )]
@@ -23,6 +30,7 @@ pub struct Withdrawal {
     pub amount: u64,
 }
 
+/// According to Ethereum spec [v1.4.0](https://github.com/ethereum/consensus-specs/blob/v1.4.0/specs/phase0/beacon-chain.md#eth1data).
 #[derive(
     Debug, Clone, Decode, Encode, Deserialize, PartialEq, tree_hash_derive::TreeHash, TypeInfo,
 )]
@@ -33,6 +41,7 @@ pub struct Eth1Data {
     pub block_hash: Bytes32,
 }
 
+/// According to Ethereum spec [v1.4.0](https://github.com/ethereum/consensus-specs/blob/v1.4.0/specs/phase0/beacon-chain.md#signedbeaconblockheader).
 #[derive(
     Debug, Clone, Decode, Encode, Deserialize, PartialEq, tree_hash_derive::TreeHash, TypeInfo,
 )]
@@ -41,6 +50,7 @@ pub struct SignedBeaconBlockHeader {
     pub signature: SignatureBytes,
 }
 
+/// According to Ethereum spec [v1.4.0](https://github.com/ethereum/consensus-specs/blob/v1.4.0/specs/phase0/beacon-chain.md#proposerslashing).
 #[derive(
     Debug, Clone, Decode, Encode, Deserialize, PartialEq, tree_hash_derive::TreeHash, TypeInfo,
 )]
@@ -49,6 +59,7 @@ pub struct ProposerSlashing {
     pub signed_header_2: SignedBeaconBlockHeader,
 }
 
+/// According to Ethereum spec [v1.4.0](https://github.com/ethereum/consensus-specs/blob/v1.4.0/specs/phase0/beacon-chain.md#attesterslashing).
 #[derive(
     Debug, Clone, Decode, Encode, Deserialize, PartialEq, tree_hash_derive::TreeHash, TypeInfo,
 )]
@@ -57,6 +68,7 @@ pub struct AttesterSlashing {
     pub attestation_2: IndexedAttestation,
 }
 
+/// According to Ethereum spec [v1.4.0](https://github.com/ethereum/consensus-specs/blob/v1.4.0/specs/phase0/beacon-chain.md#indexedattestation).
 #[derive(
     Debug, Clone, Decode, Encode, Deserialize, PartialEq, tree_hash_derive::TreeHash, TypeInfo,
 )]
@@ -66,6 +78,7 @@ pub struct IndexedAttestation {
     pub signature: SignatureBytes,
 }
 
+/// According to Ethereum spec [v1.4.0](https://github.com/ethereum/consensus-specs/blob/v1.4.0/specs/phase0/beacon-chain.md#attestation).
 #[derive(
     Debug, Clone, Decode, Encode, Deserialize, PartialEq, tree_hash_derive::TreeHash, TypeInfo,
 )]
@@ -75,6 +88,7 @@ pub struct Attestation {
     pub signature: SignatureBytes,
 }
 
+/// According to Ethereum spec [v1.4.0](https://github.com/ethereum/consensus-specs/blob/v1.4.0/specs/phase0/beacon-chain.md#attestationdata).
 #[derive(
     Debug, Clone, Decode, Encode, Deserialize, PartialEq, tree_hash_derive::TreeHash, TypeInfo,
 )]
@@ -88,6 +102,7 @@ pub struct AttestationData {
     pub target: Checkpoint,
 }
 
+/// According to Ethereum spec [v1.4.0](https://github.com/ethereum/consensus-specs/blob/v1.4.0/specs/phase0/beacon-chain.md#checkpoint).
 #[derive(
     Debug, Clone, Decode, Encode, Deserialize, PartialEq, tree_hash_derive::TreeHash, TypeInfo,
 )]
@@ -97,6 +112,7 @@ pub struct Checkpoint {
     pub root: Bytes32,
 }
 
+/// According to Ethereum spec [v1.4.0](https://github.com/ethereum/consensus-specs/blob/v1.4.0/specs/phase0/beacon-chain.md#deposit).
 #[derive(
     Debug, Clone, Decode, Encode, Deserialize, PartialEq, tree_hash_derive::TreeHash, TypeInfo,
 )]
@@ -105,6 +121,7 @@ pub struct Deposit {
     pub data: DepositData,
 }
 
+/// According to Ethereum spec [v1.4.0](https://github.com/ethereum/consensus-specs/blob/v1.4.0/specs/phase0/beacon-chain.md#depositdata).
 #[derive(
     Debug, Clone, Decode, Encode, Deserialize, PartialEq, tree_hash_derive::TreeHash, TypeInfo,
 )]
@@ -116,6 +133,7 @@ pub struct DepositData {
     pub signature: SignatureBytes,
 }
 
+/// According to Ethereum spec [v1.4.0](https://github.com/ethereum/consensus-specs/blob/v1.4.0/specs/phase0/beacon-chain.md#signedvoluntaryexit).
 #[derive(
     Debug, Clone, Decode, Encode, Deserialize, PartialEq, tree_hash_derive::TreeHash, TypeInfo,
 )]
@@ -124,6 +142,7 @@ pub struct SignedVoluntaryExit {
     pub signature: SignatureBytes,
 }
 
+/// According to Ethereum spec [v1.4.0](https://github.com/ethereum/consensus-specs/blob/v1.4.0/specs/phase0/beacon-chain.md#voluntaryexit).
 #[derive(
     Debug, Clone, Decode, Encode, Deserialize, PartialEq, tree_hash_derive::TreeHash, TypeInfo,
 )]
@@ -134,6 +153,7 @@ pub struct VoluntaryExit {
     pub validator_index: u64,
 }
 
+/// According to Ethereum spec [v1.4.0](https://github.com/ethereum/consensus-specs/blob/v1.4.0/specs/capella/beacon-chain.md#signedblstoexecutionchange).
 #[derive(
     Debug, Clone, Decode, Encode, Deserialize, PartialEq, tree_hash_derive::TreeHash, TypeInfo,
 )]
@@ -142,6 +162,7 @@ pub struct SignedBlsToExecutionChange {
     pub signature: SignatureBytes,
 }
 
+/// According to Ethereum spec [v1.4.0](https://github.com/ethereum/consensus-specs/blob/v1.4.0/specs/capella/beacon-chain.md#blstoexecutionchange).
 #[derive(
     Debug, Clone, Decode, Encode, Deserialize, PartialEq, tree_hash_derive::TreeHash, TypeInfo,
 )]
@@ -152,6 +173,7 @@ pub struct BlsToExecutionChange {
     pub to_execution_address: Address,
 }
 
+/// According to Ethereum spec [v1.4.0](https://github.com/ethereum/consensus-specs/blob/v1.4.0/specs/altair/beacon-chain.md#syncaggregate).
 #[derive(
     Debug, Clone, Decode, Encode, Deserialize, PartialEq, tree_hash_derive::TreeHash, TypeInfo,
 )]
@@ -160,6 +182,7 @@ pub struct SyncAggregate {
     pub sync_committee_signature: SignatureBytes,
 }
 
+/// According to Ethereum spec [v1.4.0](https://github.com/ethereum/consensus-specs/blob/v1.4.0/specs/altair/beacon-chain.md#synccommittee).
 #[derive(
     Debug, Clone, Decode, Encode, Deserialize, PartialEq, tree_hash_derive::TreeHash, TypeInfo,
 )]

diff --git a/ethereum-common/src/beacon/execution_payload.rs b/ethereum-common/src/beacon/execution_payload.rs
@@ -1,5 +1,6 @@
 use super::*;
 
+/// According to Ethereum spec [v1.4.0](https://github.com/ethereum/consensus-specs/blob/v1.4.0/specs/deneb/beacon-chain.md#executionpayload).
 #[derive(
     Debug, Clone, Decode, Encode, Deserialize, PartialEq, tree_hash_derive::TreeHash, TypeInfo,
 )]

diff --git a/ethereum-common/src/beacon/light.rs b/ethereum-common/src/beacon/light.rs
@@ -1,4 +1,5 @@
-// Module contains lightened versions of the entities.
+//! Module contains lightened versions of the entities, i.e. some fields
+//! are replaced by its tree hash root value.
 
 use super::*;
 

diff --git a/ethereum-common/src/lib.rs b/ethereum-common/src/lib.rs
@@ -33,8 +33,11 @@ pub use tree_hash::{self, Hash256};
 use tree_hash::{TreeHash, TreeHashType};
 pub use trie_db;
 
+/// According to Ethereum spec [v1.4.0](https://github.com/ethereum/consensus-specs/blob/v1.4.0/specs/phase0/beacon-chain.md#time-parameters).
 pub const SLOTS_PER_EPOCH: u64 = 32;
+/// According to Ethereum spec [v1.4.0](https://github.com/ethereum/consensus-specs/blob/v1.4.0/specs/altair/beacon-chain.md#sync-committee).
 pub const EPOCHS_PER_SYNC_COMMITTEE: u64 = 256;
+/// According to Ethereum spec [v1.4.0](https://github.com/ethereum/consensus-specs/blob/v1.4.0/specs/altair/beacon-chain.md#sync-committee).
 pub const SYNC_COMMITTEE_SIZE: usize = 512;
-// https://github.com/ethereum/consensus-specs/blob/dev/specs/altair/light-client/p2p-interface.md#configuration
+/// According to Ethereum spec [v1.4.0](https://github.com/ethereum/consensus-specs/blob/v1.4.0/specs/altair/light-client/p2p-interface.md#configuration).
 pub const MAX_REQUEST_LIGHT_CLIENT_UPDATES: u8 = 128;
diff --git a/ethereum-common/src/merkle.rs b/ethereum-common/src/merkle.rs
@@ -4,13 +4,32 @@ use super::{
 };
 use ring::digest::{Context as RingContext, SHA256 as RingSHA256};
 
+/// According to Ethereum spec [v1.4.0](https://github.com/ethereum/consensus-specs/blob/v1.4.0/specs/altair/light-client/sync-protocol.md#constants).
+///
+/// It is a result of applying [get_generalized_index_length](https://github.com/ethereum/consensus-specs/blob/v1.4.0/ssz/merkle-proofs.md#get_generalized_index_length) to the `CURRENT_SYNC_COMMITTEE_GINDEX` value.
 pub const MERKLE_PROOF_DEPTH_CURRENT_SYNC_COMMITTEE: u32 = 5;
+/// According to Ethereum spec [v1.4.0](https://github.com/ethereum/consensus-specs/blob/v1.4.0/specs/altair/light-client/sync-protocol.md#constants).
+///
+/// Complement part of [`MERKLE_PROOF_DEPTH_CURRENT_SYNC_COMMITTEE`].
 pub const MERKLE_PROOF_INDEX_CURRENT_SYNC_COMMITTEE: u32 = 22;
+/// According to Ethereum spec [v1.4.0](https://github.com/ethereum/consensus-specs/blob/v1.4.0/specs/altair/light-client/sync-protocol.md#constants).
+///
+/// It is a result of applying [get_generalized_index_length](https://github.com/ethereum/consensus-specs/blob/v1.4.0/ssz/merkle-proofs.md#get_generalized_index_length) to the `NEXT_SYNC_COMMITTEE_GINDEX` value.
 pub const MERKLE_PROOF_DEPTH_NEXT_SYNC_COMMITTEE: u32 = 5;
+/// According to Ethereum spec [v1.4.0](https://github.com/ethereum/consensus-specs/blob/v1.4.0/specs/altair/light-client/sync-protocol.md#constants).
+///
+/// Complement part of [`MERKLE_PROOF_DEPTH_NEXT_SYNC_COMMITTEE`].
 pub const MERKLE_PROOF_INDEX_NEXT_SYNC_COMMITTEE: u32 = 23;
+/// According to Ethereum spec [v1.4.0](https://github.com/ethereum/consensus-specs/blob/v1.4.0/specs/altair/light-client/sync-protocol.md#constants).
+///
+/// It is a result of applying [get_generalized_index_length](https://github.com/ethereum/consensus-specs/blob/v1.4.0/ssz/merkle-proofs.md#get_generalized_index_length) to the `FINALIZED_ROOT_GINDEX` value.
 pub const MERKLE_PROOF_DEPTH_FINALITY: u32 = 6;
+/// According to Ethereum spec [v1.4.0](https://github.com/ethereum/consensus-specs/blob/v1.4.0/specs/altair/light-client/sync-protocol.md#constants).
+///
+/// Complement part of [`MERKLE_PROOF_DEPTH_FINALITY`].
 pub const MERKLE_PROOF_INDEX_FINALITY: u32 = 41;
 
+/// According to Ethereum spec [v1.4.0](https://github.com/ethereum/consensus-specs/blob/v1.4.0/specs/phase0/beacon-chain.md#is_valid_merkle_branch).
 pub fn is_valid_merkle_branch(
     leaf: [u8; 32],
     branch: &[[u8; 32]],