diff --git a/core/src/chain_id.rs b/core/src/chain_id.rs index 8f80e2562..9af2cf0a5 100644 --- a/core/src/chain_id.rs +++ b/core/src/chain_id.rs @@ -56,6 +56,7 @@ //! ```rust //! use mina_core::ChainId; //! +//! # fn main() -> Result<(), Box> { //! // 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> { /// // 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> { /// let chain_id = ChainId::from_hex( /// "a7351abc7ddf2ea92d1b38cc8e636c271c1dfd2c081c637f62ebc2af34eb7cc1" /// )?; + /// # Ok(()) + /// # } /// ``` pub fn from_hex(s: &str) -> Result { let h = hex::decode(s)?; diff --git a/core/src/constants.rs b/core/src/constants.rs index 5d391a9ef..39d5bf12d 100644 --- a/core/src/constants.rs +++ b/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: +/// Protocol specification: #[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: + /// - Supercharged Rewards Removal: + /// - Original Proposal: + /// + /// **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, } #[derive(Clone, Debug, BinProtWrite)]