blockchain.conf.json

Overview

The blockchain.conf.json file serves as a comprehensive configuration manifest for a blockchain system, encapsulating a wide array of parameters essential for the operation, consensus, economics, and network configuration of the blockchain. It defines cryptographic roots, currency values, protocol versions, validator settings, gas pricing, chain parameters, and other operational limits and thresholds. This JSON-based configuration enables the blockchain runtime and related subsystems to initialize and enforce protocol rules consistently.

This file is integral to the blockchain core infrastructure, interacting closely with consensus algorithms, validator management modules, gas metering and pricing mechanisms, and blockchain state validation components.

Detailed Explanation of Configuration Sections

Cryptographic Parameters (p0 to p3)

• p0, p1, p2, p3: These fields contain 64-character hexadecimal strings representing cryptographic roots or hashes used by the blockchain. They likely correspond to initial state hashes, zero states, or other fixed points in the blockchain's cryptographic structure.

Currency and Value Definitions (p7)

• p7: An array of currency definitions, each containing:

  • currency: Numeric identifier of the currency.

  • value: String representing the amount associated with the currency.

Usage: Defines base amounts or initial balances for different currencies recognized by the blockchain.

Protocol Version and Capabilities (p8)

• p8: Contains:

  • version: Numeric protocol version.

  • capabilities: String representing capability flags or feature bits enabled for the protocol.

Usage: Used by the blockchain runtime to determine enabled protocol features and compatibility.

Parameter Lists (p9, p10)

• p9, p10: Arrays of numeric identifiers, possibly representing sets of operational codes, message types, or protocol flags.

Gameplay or Operational Parameters (p11)

• p11: Defines two sets of parameters labeled normal_params and critical_params, each including:

  • min_tot_rounds, max_tot_rounds: Minimum and maximum number of rounds.

  • min_wins, max_losses: Win/loss thresholds.

  • min_store_sec, max_store_sec: Storage duration limits in seconds.

  • bit_price, cell_price: Pricing parameters for bits and cells.

Usage: These parameters may govern operational thresholds, economic limits, or consensus-related conditions.

Workchain Configurations (p12)

• p12: Array of workchain configurations, each containing:

  • workchain_id: Identifier for the workchain.

  • enabled_since: UNIX timestamp indicating when the workchain became active.

  • actual_min_split, min_split, max_split: Parameters controlling shard splitting.

  • active: Boolean indicating if the workchain is active.

  • accept_msgs: Boolean indicating if the workchain accepts messages.

  • flags, version, basic, vm_version, vm_mode: Various flags and versioning info.

  • zerostate_root_hash, zerostate_file_hash: Hashes for the workchain's zero state.

Usage: Defines the configuration and lifecycle parameters for each workchain in the blockchain network.

Block of Cells (p13)

• p13.boc: A base64 or similar encoded string representing a serialized block of cells (BOC), a fundamental data structure in the blockchain.

Fee Parameters (p14)

• p14: Contains:

  • masterchain_block_fee: Fee for masterchain blocks.

  • basechain_block_fee: Fee for basechain blocks.

Usage: Specifies fees required for block processing on different chains.

Validator Election Parameters (p15)

• p15: Timing parameters for validator elections:

  • validators_elected_for: Duration validators are elected for.

  • elections_start_before: Time before election start.

  • elections_end_before: Time before election end.

  • stake_held_for: Duration stake is held.

Validator Limits (p16)

• p16: Constraints for validator counts:

  • max_validators, max_main_validators, min_validators.

Stake Limits (p17)

• p17: Includes stake-related thresholds:

  • min_stake, max_stake, min_total_stake, max_stake_factor.

Pricing Over Time (p18)

• p18: Array containing price points with timestamps (utime_since) and prices per second for bits, cells, and masterchain equivalents.

Gas Parameters (p20, p21)

• p20, p21: Two sets of gas parameters, possibly representing different contexts (e.g., masterchain and basechain):

  • Limits (flat gas, gas limit, special gas limit).

  • Gas price.

  • Gas credit.

  • Freeze and delete due limits.

Load and Resource Limits (p22, p23)

• p22, p23: Define threshold limits for bytes, gas, and logical time delta (lt_delta) in three tiers:

  • underload, soft_limit, hard_limit.

Pricing Factors (p24, p25)

• p24, p25: Pricing parameters including:

  • lump_price, bit_price, cell_price.

  • ihr_price_factor (Infinite Hash Rate price factor).

  • Fractional values first_frac and next_frac.

Consensus and Catchain Settings (p28, p29)

• p28: Parameters related to validator shuffling and catchain lifetimes:

  • Booleans and numeric lifetimes for catchain and validators.

  • Number of shard validators.

• p29: Consensus timing and size parameters:

  • Flags for catchain IDs.

  • Candidate round counts and delays.

  • Consensus timeout and attempt durations.

  • Maximum block and collated bytes.

Predefined Keys or Identifiers (p31)

• p31: Array of 64-character hex strings, likely representing predefined keys, addresses, or identifiers used by the system.

Validator List and Weights (p34)

• p34: Validator set definition:

  • Time range (utime_since, utime_until).

  • Counts (total, main).

  • Total weight.

  • List of validators with their public_key and individual weight.

Payout Thresholds and Percentages (p42)

• p42: Defines:

  • threshold: A hexadecimal string representing a threshold value.

  • payouts: Array of payout rules with license_type and payout_percent.

Implementation Details and Algorithms

• The configuration employs fixed keys (p0, p1, etc.) as identifiers for each configuration section, which suggests a tightly controlled schema designed for deterministic parsing.

• Numeric values such as timestamps, counts, and prices are represented as strings or numbers to maintain precision and avoid floating-point errors.

• The structure supports multiple workchains (p12), allowing the blockchain to operate with parallel chains or shards.

• Validator configuration (p34) includes weights to influence consensus or voting power, which plays a crucial role in election and stake-based consensus algorithms.

• Gas and resource limits (p20-p23) implement a tiered approach (underload, soft, hard limits), which is a common algorithmic technique to manage resource consumption and network stability.

• Economic parameters such as stake limits (p17) and pricing (p24, p25) provide dynamic control over network economics, influencing staking behavior and transaction fees.

Interaction With Other System Components

• Consensus Module: Uses validator parameters (p15, p16, p34), stake thresholds (p17), and catchain settings (p28, p29) to manage validator selection and consensus rounds.

• Gas Metering and Pricing: Relies on gas parameters (p20, p21) and pricing factors (p24, p25) to calculate fees and enforce gas limits during transaction execution.

• Workchain and Sharding System: Reads workchain definitions (p12) to initialize individual chains, handle message acceptance, and manage shard splits.

• Economic and Token Modules: Use currency values (p7), stake limits (p17), and payout rules (p42) to handle token economics, rewards, and penalties.

• Blockchain State Validation: Uses cryptographic roots (p0-p3), zero state hashes (p12), and serialized blocks (p13) to verify blockchain integrity and initialize state.

Visual Diagram: Configuration Structure Overview

flowchart TD
A[blockchain.conf.json]
A --> B[Cryptographic Parameters]
A --> C[Currency & Values]
A --> D[Protocol Version & Capabilities]
A --> E[Parameter Lists]
A --> F[Operational Parameters]
A --> G[Workchain Configurations]
A --> H[Serialized Block of Cells]
A --> I[Fee Parameters]
A --> J[Validator Election Parameters]
A --> K[Validator Limits]
A --> L[Stake Limits]
A --> M[Pricing Over Time]
A --> N[Gas Parameters]
A --> O[Resource Limits]
A --> P[Pricing Factors]
A --> Q[Consensus & Catchain Settings]
A --> R[Predefined Keys]
A --> S[Validator List & Weights]
A --> T[Payout Thresholds & Percentages]
B -->|p0-p3| Cryptography
C -->|p7| Currency
D -->|p8| VersionCaps
E -->|p9-p10| ParamLists
F -->|p11| OpParams
G -->|p12| Workchains
H -->|p13| BOC
I -->|p14| Fees
J -->|p15| ElectionParams
K -->|p16| ValidatorLimits
L -->|p17| StakeLimits
M -->|p18| PricingTime
N -->|p20-p21| GasParams
O -->|p22-p23| ResourceLimits
P -->|p24-p25| PriceFactors
Q -->|p28-p29| ConsensusParams
R -->|p31| Keys
S -->|p34| Validators
T -->|p42| Payouts

This diagram presents the hierarchical relationship and main categories of configuration in the blockchain.conf.json file, providing a structural overview of how various parts are organized and interrelated.