Docs: fix make test-docs and add documentation for network conf

Author: dannywillems

Cargo.lock

@@ -12,6 +12,18 @@ use std::{
 use binprot::{BinProtRead, BinProtWrite};
 use serde::{Deserialize, Deserializer, Serialize, Serializer};
 
+/// Unique identifier for a Mina blockchain network.
+///
+/// The ChainId is a 32-byte hash that uniquely identifies a specific Mina network
+/// configuration. It is computed from various network parameters including:
+/// - Genesis state hash
+/// - Constraint system digests (circuit verification hashes)
+/// - Protocol constants (timing parameters, fees, etc.)
+/// - Protocol version numbers
+/// - Transaction pool configuration
+///
+/// Different networks (mainnet, devnet) will have different ChainIds, and any
+/// change to core protocol parameters will result in a new ChainId.
 #[derive(Clone, PartialEq, Eq)]
 pub struct ChainId([u8; 32]);
 
@@ -45,6 +57,22 @@ fn hash_genesis_constants(
 }
 
 impl ChainId {
+    /// Compute a ChainId from network configuration parameters.
+    ///
+    /// This function deterministically generates a unique ChainId by hashing
+    /// together all the parameters that define a Mina network's behavior.
+    /// Any change to these parameters will result in a different ChainId.
+    ///
+    /// # Arguments
+    /// * `constraint_system_digests` - MD5 hashes of the zkSNARK circuits
+    /// * `genesis_state_hash` - Hash of the network's genesis block
+    /// * `genesis_constants` - Protocol timing and behavior constants
+    /// * `protocol_transaction_version` - Transaction format version
+    /// * `protocol_network_version` - Network protocol version
+    /// * `tx_max_pool_size` - Maximum transaction pool size
+    ///
+    /// # Returns
+    /// A new ChainId uniquely identifying this network configuration
     pub fn compute(
         constraint_system_digests: &[Md5],
         genesis_state_hash: &StateHash,
@@ -68,7 +96,15 @@ impl ChainId {
         ChainId(hasher.finalize().try_into().unwrap())
     }
 
-    /// Computes shared key for libp2p Pnet protocol.
+    /// Computes the preshared key for libp2p private network protocol.
+    ///
+    /// This creates a network-specific encryption key that ensures nodes
+    /// can only communicate with other nodes on the same Mina network.
+    /// The key is derived from the ChainId to automatically separate
+    /// different networks at the transport layer.
+    ///
+    /// # Returns
+    /// A 32-byte preshared key for libp2p Pnet
     pub fn preshared_key(&self) -> [u8; 32] {
         let mut hasher = Blake2b256::default();
         hasher.update(b"/coda/0.0.1/");
@@ -79,10 +115,22 @@ impl ChainId {
         psk_fixed
     }
 
+    /// Convert the ChainId to a hexadecimal string representation.
+    ///
+    /// # Returns
+    /// A 64-character hex string (32 bytes * 2 hex chars per byte)
     pub fn to_hex(&self) -> String {
         hex::encode(self.0)
     }
 
+    /// Parse a ChainId from a hexadecimal string.
+    ///
+    /// # Arguments
+    /// * `s` - A 64-character hex string representing the ChainId
+    ///
+    /// # Returns
+    /// * `Ok(ChainId)` if the string is valid
+    /// * `Err(hex::FromHexError)` if the string is malformed
     pub fn from_hex(s: &str) -> Result<ChainId, hex::FromHexError> {
         let h = hex::decode(s)?;
         let bs = h[..32]
@@ -91,6 +139,16 @@ impl ChainId {
         Ok(ChainId(bs))
     }
 
+    /// Create a ChainId from raw bytes.
+    ///
+    /// # Arguments
+    /// * `bytes` - A byte slice containing at least 32 bytes
+    ///
+    /// # Returns
+    /// A ChainId using the first 32 bytes of the input
+    ///
+    /// # Panics
+    /// Panics if the input contains fewer than 32 bytes
     pub fn from_bytes(bytes: &[u8]) -> ChainId {
         let mut arr = [0u8; 32];
         arr.copy_from_slice(&bytes[..32]);
@@ -147,11 +205,25 @@ impl Debug for ChainId {
     }
 }
 
+/// The ChainId for the Mina devnet.
+///
+/// This ChainId identifies the development/testing network and is computed
+/// from devnet's specific configuration parameters. Nodes must use this
+/// ChainId to participate in the devnet.
+///
+/// Hex representation: `29936104443aaf264a7f0192ac64b1c7173198c1ed404c1bcff5e562e05eb7f6`
 pub const DEVNET_CHAIN_ID: ChainId = ChainId([
     0x29, 0x93, 0x61, 0x04, 0x44, 0x3a, 0xaf, 0x26, 0x4a, 0x7f, 0x01, 0x92, 0xac, 0x64, 0xb1, 0xc7,
     0x17, 0x31, 0x98, 0xc1, 0xed, 0x40, 0x4c, 0x1b, 0xcf, 0xf5, 0xe5, 0x62, 0xe0, 0x5e, 0xb7, 0xf6,
 ]);
 
+/// The ChainId for the Mina mainnet.
+///
+/// This ChainId identifies the production Mina blockchain and is computed
+/// from mainnet's specific configuration parameters. Nodes must use this
+/// ChainId to participate in the mainnet.
+///
+/// Hex representation: `a7351abc7ddf2ea92d1b38cc8e636c271c1dfd2c081c637f62ebc2af34eb7cc1`
 pub const MAINNET_CHAIN_ID: ChainId = ChainId([
     0xa7, 0x35, 0x1a, 0xbc, 0x7d, 0xdf, 0x2e, 0xa9, 0x2d, 0x1b, 0x38, 0xcc, 0x8e, 0x63, 0x6c, 0x27,
     0x1c, 0x1d, 0xfd, 0x2c, 0x08, 0x1c, 0x63, 0x7f, 0x62, 0xeb, 0xc2, 0xaf, 0x34, 0xeb, 0x7c, 0xc1,

core/src/chain_id.rs

@@ -14,24 +14,196 @@ pub fn constraint_constants() -> &'static ConstraintConstants {
     NetworkConfig::global().constraint_constants
 }
 
+/// Constants that define fork-specific blockchain state.
+///
+/// Fork constants specify the blockchain state at which a protocol upgrade or fork occurred.
+/// These are used to handle protocol changes and ensure compatibility across network upgrades.
 #[derive(Clone, Debug)]
 pub struct ForkConstants {
+    /// Hash of the blockchain state at the fork point
     pub state_hash: Fp,
+
+    /// Blockchain length (number of blocks) at the fork point
     pub blockchain_length: u32,
+
+    /// Global slot number since genesis at the fork point
     pub global_slot_since_genesis: u32,
 }
 
+/// Protocol constraint constants that define core blockchain behavior.
+///
+/// These constants configure fundamental aspects of the Mina protocol including consensus,
+/// transaction processing, economic parameters, and ledger structure. They are compile-time
+/// parameters that must be consistent across all nodes in a network.
+///
+/// ## Consensus and Timing Parameters
+///
+/// The consensus mechanism relies on slot-based timing where blocks are produced in discrete
+/// time slots. The timing hierarchy is:
+/// - **Slots**: Basic time units for block production
+/// - **Sub-windows**: Groups of slots within an epoch
+/// - **Windows**: Collections of sub-windows that define epoch structure
+/// - **Epochs**: Complete consensus periods
+///
+/// ## Economic Parameters
+///
+/// The protocol defines economic incentives through fees and rewards:
+/// - **Coinbase rewards**: Paid to block producers for successful blocks
+/// - **Account creation fees**: Required to create new accounts on the ledger
+/// - **Supercharged rewards**: Multiplier for enhanced block producer rewards
+///
+/// ## Ledger and Transaction Structure
+///
+/// The ledger uses a Merkle tree structure for efficient verification:
+/// - **Ledger depth**: Determines the maximum number of accounts (2^depth)
+/// - **Transaction capacity**: Limits transactions per block for performance
+/// - **Pending coinbase**: Manages delayed coinbase payouts
+///
+/// ## Usage Example
+///
+/// ```rust
+/// use openmina_core::constants::constraint_constants;
+///
+/// // Access global constraint constants
+/// let constants = constraint_constants();
+///
+/// // Calculate slots per window
+/// let slots_per_window = constants.sub_windows_per_window;
+/// println!("Sub-windows per window: {}", slots_per_window);
+///
+/// // Get block timing
+/// let block_time_ms = constants.block_window_duration_ms;
+/// println!("Block time: {}ms", block_time_ms);
+///
+/// // Check economic parameters
+/// let coinbase_reward = constants.coinbase_amount;
+/// let creation_fee = constants.account_creation_fee;
+/// println!("Coinbase: {} nanomina, Account fee: {} nanomina",
+///          coinbase_reward, creation_fee);
+/// ```
+///
+/// ## Network Differences
+///
+/// While most constraint constants are identical across networks, some parameters
+/// may differ between mainnet and testnets for development purposes.
+///
+/// Related OCaml implementation: <https://github.com/MinaProtocol/mina/tree/compatible/src/config>
+/// Protocol specification: <https://github.com/MinaProtocol/mina/blob/compatible/docs/specs/types_and_structures/serialized_key.md>
 #[derive(Clone, Debug)]
 pub struct ConstraintConstants {
+    /// Number of sub-windows that make up a complete window.
+    ///
+    /// Used in the consensus mechanism to structure epoch timing. Combined with
+    /// `slots_per_sub_window` from protocol constants, this determines the total
+    /// slots per window: `slots_per_window = slots_per_sub_window × sub_windows_per_window`.
+    ///
+    /// **Value**: 11 (both mainnet and devnet)
     pub sub_windows_per_window: u64,
+
+    /// Depth of the account ledger Merkle tree.
+    ///
+    /// This determines the maximum number of accounts that can be stored in the ledger:
+    /// `max_accounts = 2^ledger_depth`. The depth affects proof sizes and verification time.
+    /// A larger depth allows more accounts but increases computational overhead.
+    ///
+    /// **Value**: 35 (supports ~34 billion accounts)
+    /// **Usage**: Account addressing, sparse ledger proofs, zkSNARK constraints
     pub ledger_depth: u64,
+
+    /// Number of blocks to delay before SNARK work becomes available.
+    ///
+    /// This creates a buffer period between when a block is produced and when
+    /// the associated SNARK work can be included in subsequent blocks. This delay
+    /// helps ensure fair distribution of SNARK work opportunities.
+    ///
+    /// **Value**: 2 blocks
+    /// **Usage**: SNARK work scheduling, proof marketplace timing
     pub work_delay: u64,
+
+    /// Duration of each block production slot in milliseconds.
+    ///
+    /// This is the fundamental time unit for the consensus protocol. Block producers
+    /// attempt to create blocks during their assigned slots. The duration affects
+    /// network synchronization requirements and transaction confirmation times.
+    ///
+    /// **Value**: 180,000ms (3 minutes)
+    /// **Usage**: Consensus timing, slot calculations, network synchronization
     pub block_window_duration_ms: u64,
+
+    /// Log₂ of the maximum number of transactions per block.
+    ///
+    /// The actual transaction capacity is `2^transaction_capacity_log_2`. This logarithmic
+    /// representation is used because the value directly affects zkSNARK circuit constraints.
+    /// Higher capacity allows more transactions but increases block processing time.
+    ///
+    /// Corresponds to `transaction_capacity` in the protocol specification, which defines
+    /// the maximum transactions per block (represented as `two_to_the`).
+    ///
+    /// **Value**: 7 (supports 2^7 = 128 transactions per block)
+    /// **Usage**: Transaction pool management, block construction, circuit constraints
     pub transaction_capacity_log_2: u64,
+
+    /// Number of confirmations before coinbase reward is spendable.
+    ///
+    /// Coinbase rewards are not immediately spendable and require a certain number
+    /// of block confirmations before they can be used. This parameter defines the
+    /// depth of the pending coinbase Merkle tree structure used to track these
+    /// delayed rewards until they mature.
+    ///
+    /// **Value**: 5 (coinbase rewards require 5 block confirmations)
+    /// **Usage**: Coinbase reward management, staged ledger operations, reward maturity
     pub pending_coinbase_depth: usize,
+
+    /// Block reward amount in nanomina (10⁻⁹ MINA).
+    ///
+    /// This is the base reward paid to block producers for successfully creating a block.
+    /// The amount is specified in nanomina, where 1 MINA = 10⁹ nanomina. Block producers
+    /// may receive additional rewards through the supercharged coinbase mechanism.
+    ///
+    /// **Value**: 720,000,000,000 nanomina (720 MINA)
+    /// **Usage**: Block producer rewards, economic incentives, reward calculations
     pub coinbase_amount: u64,
+
+    /// Multiplier for supercharged coinbase rewards.
+    ///
+    /// Supercharged rewards were designed to provide double block rewards (factor of 2)
+    /// to block producers staking with unlocked tokens during the early mainnet period
+    /// following the 2021 launch. This mechanism incentivized participation and orderly
+    /// markets after mainnet launch.
+    ///
+    /// **Historical values**:
+    /// - Original mainnet: 2 (double rewards for unlocked tokens)
+    /// - Berkeley hardfork (June 2024): 1 (supercharged rewards removed via MIP1)
+    ///
+    /// The removal was decided by community vote on January 1, 2023, as proposed by
+    /// community member Gareth Davies. This change ensures uniform rewards for all
+    /// tokens and reduces inflation, promoting a sustainable economic model.
+    ///
+    /// **References**:
+    /// - Berkeley Upgrade: <https://minaprotocol.com/blog/minas-berkeley-upgrade-what-to-expect>
+    /// - Supercharged Rewards Removal: <https://minaprotocol.com/blog/update-on-minas-supercharged-rewards-schedule>
+    /// - Original Proposal: <https://github.com/MinaProtocol/mina/issues/5753>
+    ///
+    /// **Usage**: Enhanced reward calculations, incentive mechanisms
     pub supercharged_coinbase_factor: u64,
+
+    /// Fee required to create a new account in nanomina.
+    ///
+    /// When a transaction creates a new account that doesn't exist on the ledger,
+    /// this fee is charged in addition to the transaction fee. This prevents
+    /// spam account creation and manages ledger growth.
+    ///
+    /// **Value**: 1,000,000,000 nanomina (1 MINA)
+    /// **Usage**: Account creation, transaction validation, fee calculations
     pub account_creation_fee: u64,
+
+    /// Optional fork constants defining a protocol upgrade point.
+    ///
+    /// When present, these constants specify the blockchain state at which a protocol
+    /// fork or upgrade occurred. This allows the protocol to handle transitions between
+    /// different versions while maintaining consensus.
+    ///
+    /// **Usage**: Protocol upgrades, compatibility handling, genesis configuration
     pub fork: Option<ForkConstants>,
 }
 #[derive(Clone, Debug, BinProtWrite)]