Merge pull request #1554 from o1-labs/dw/protocol-doc

Core: add documentation for constants.rs

Author: dannywillems

core/src/chain_id.rs

@@ -56,6 +56,7 @@
 //! ```rust
 //! use mina_core::ChainId;
 //!
+//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
 //! // Use predefined network
 //! let mainnet_id = mina_core::MAINNET_CHAIN_ID;
 //! println!("Mainnet ID: {}", mainnet_id);
@@ -65,6 +66,8 @@
 //!
 //! // Generate preshared key for private networking
 //! let psk = chain_id.preshared_key();
+//! # Ok(())
+//! # }
 //! ```
 
 use mina_p2p_messages::v2::{
@@ -135,6 +138,7 @@ use serde::{Deserialize, Deserializer, Serialize, Serializer};
 /// ```rust
 /// use mina_core::{ChainId, MAINNET_CHAIN_ID};
 ///
+/// # fn main() -> Result<(), Box<dyn std::error::Error>> {
 /// // Use predefined mainnet ID
 /// let mainnet = MAINNET_CHAIN_ID;
 /// println!("Mainnet: {}", mainnet.to_hex());
@@ -144,6 +148,8 @@ use serde::{Deserialize, Deserializer, Serialize, Serializer};
 ///
 /// // Generate private network key
 /// let psk = mainnet.preshared_key();
+/// # Ok(())
+/// # }
 /// ```
 #[derive(Clone, PartialEq, Eq)]
 pub struct ChainId([u8; 32]);
@@ -221,6 +227,11 @@ impl ChainId {
     /// use mina_core::ChainId;
     /// use mina_p2p_messages::v2::UnsignedExtendedUInt32StableV1;
     ///
+    /// # // Use actual devnet values for the example
+    /// # let constraint_digests = mina_core::network::devnet::CONSTRAINT_SYSTEM_DIGESTS;
+    /// # let genesis_hash: mina_p2p_messages::v2::StateHash =
+    /// #     "3NL93SipJfAMNDBRfQ8Uo8LPovC74mnJZfZYB5SK7mTtkL72dsPx".parse().unwrap();
+    /// # let protocol_constants = mina_core::constants::PROTOCOL_CONSTANTS.clone();
     /// let chain_id = ChainId::compute(
     ///     &constraint_digests,
     ///     &genesis_hash,
@@ -349,9 +360,12 @@ impl ChainId {
     /// ```rust
     /// use mina_core::ChainId;
     ///
+    /// # fn main() -> Result<(), Box<dyn std::error::Error>> {
     /// let chain_id = ChainId::from_hex(
     ///     "a7351abc7ddf2ea92d1b38cc8e636c271c1dfd2c081c637f62ebc2af34eb7cc1"
     /// )?;
+    /// # Ok(())
+    /// # }
     /// ```
     pub fn from_hex(s: &str) -> Result<ChainId, hex::FromHexError> {
         let h = hex::decode(s)?;

core/src/constants.rs

@@ -14,35 +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
+/// 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 mina_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 in a single slot window
+    /// 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
+
+    /// 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 slots to delay SNARK work for proof generation
+
+    /// 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 window in milliseconds
+
+    /// 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,
-    /// Log2 of maximum transactions per block
+
+    /// 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,
-    /// Depth of the pending coinbase Merkle tree
+
+    /// 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,
-    /// Base amount awarded for producing a block
+
+    /// 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 coinbase when account is "supercharged"
+
+    /// 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 charged for creating a new account
+
+    /// 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 configuration for protocol upgrades
+
+    /// 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)]