blockchain.conf.json

Overview

The blockchain.conf.json file defines a comprehensive configuration for a blockchain system. It encapsulates critical constants, parameters, and settings that govern the behavior, capabilities, economic model, validator rules, gas limits, and other operational aspects of the blockchain. This configuration file is a static JSON representation likely loaded by the blockchain node software to initialize and enforce protocol rules and settings consistently across the network.

This file does not contain executable code, but serves as a structured data source from which other components in the system derive their operational parameters. It is closely related to blockchain consensus, economics, network validation, and gas management functionalities.

Detailed Structure and Field Descriptions

The JSON structure is organized into several parameter groups, each identified by keys like "p0", "p1", "p7", etc. Each group contains parameters relevant to a particular aspect of the blockchain.

p0, p1, p2, p3 (Hashes and Identifiers)

• p0, p1, p2, p3 contain long hexadecimal strings, likely representing cryptographic hashes or unique identifiers used by the blockchain.

• Purpose: These values might represent initial state hashes, genesis block roots, or protocol identifiers.

p7 (Currencies and Values)

• An array of objects, each with:

  • currency (integer): Identifier for a currency type.

  • value (string): The associated value or amount for the currency.

• Example:

  {
    "currency": 239,
    "value": "666666666666"
  }
  

• Usage: Defines supported currencies and their initial or default values.

p8 (Version and Capabilities)

• Contains:

  • version (integer): Protocol version number.

  • capabilities (string): Numeric string representing bit flags or capabilities supported by this blockchain node.

• Usage: Used to determine protocol features enabled or supported.

p9, p10 (Allowed or Supported Identifiers)

• Arrays of integers representing sets of allowed IDs, likely for various protocol or network entities.

• p9 and p10 differ slightly in contents, possibly representing different permission sets or feature sets.

p11 (Normal and Critical Parameters)

• Contains two nested objects: normal_params and critical_params.

• Each defines parameters such as:

  • min_tot_rounds, max_tot_rounds: Minimum and maximum total rounds for a process (e.g., consensus rounds).

  • min_wins, max_losses: Thresholds for wins or losses.

  • min_store_sec, max_store_sec: Time durations in seconds for storage constraints.

  • bit_price, cell_price: Pricing for bits and cells, possibly related to resource costs.

• Usage: Defines configuration profiles for "normal" and "critical" operating modes or conditions.

p12 (Workchain Configuration)

• An array of objects, each describing a workchain:

  • Fields include workchain_id, enabled_since (timestamp), min_split, max_split, active (boolean), accept_msgs (boolean), zero state hashes, versioning, VM modes, and flags.

• Example entry:

  {
    "workchain_id": 0,
    "enabled_since": 1605687562,
    "active": true,
    "accept_msgs": true,
    "zerostate_root_hash": "...",
    "version": 0,
    ...
  }
  

• Usage: Defines parameters for individual workchains within the blockchain system.

p13 (BOC - Bag of Cells)

• Contains a base64-like encoded string under boc.

• Usage: Likely represents serialized blockchain data or state in the Bag of Cells format, which is a serialization format used in certain blockchain systems.

p14 (Block Fees)

• Defines fees for blocks in different chains:

  • masterchain_block_fee

  • basechain_block_fee

• Values are large numeric strings representing fees in smallest currency units.

p15 (Validator Election Timing)

• Defines timing parameters for validator elections:

  • validators_elected_for: Duration validators are elected for.

  • elections_start_before, elections_end_before: Timing relative to election events.

  • stake_held_for: Duration stake must be held.

p16 (Validator Limits)

• Defines limits for validator counts:

  • max_validators

  • max_main_validators

  • min_validators

p17 (Stake Parameters)

• Defines staking parameters:

  • min_stake, max_stake: Minimum and maximum stake amounts.

  • min_total_stake: Minimum total stake required.

  • max_stake_factor: Factor limiting stake size.

p18 (Pricing Over Time)

• Array with entries defining:

  • utime_since: Unix epoch time from which pricing applies.

  • bit_price_ps, cell_price_ps: Price per second for bits and cells.

  • mc_bit_price_ps, mc_cell_price_ps: Masterchain-specific prices.

p20 and p21 (Gas Limits and Pricing)

• Contain gas-related parameters for different chains or contexts:

  • flat_gas_limit, flat_gas_price, gas_price, gas_limit, special_gas_limit, gas_credit, block_gas_limit, freeze_due_limit, delete_due_limit.

• Used to control computational resource pricing and limits.

p22 and p23 (Resource Limits)

• Define byte, gas, and logical time delta limits with three thresholds:

  • underload

  • soft_limit

  • hard_limit

• These define system constraints for memory usage and gas consumption.

p24 and p25 (Pricing Factors)

• Define prices for lumps, bits, cells, and IHR (Instant Hypercube Routing) price factors with fractional values.

• Differentiated between two parameter sets.

p28 (Catchain and Validator Lifetimes)

• Defines parameters related to validator committees and catchain (consensus chain):

  • shuffle_mc_validators (boolean)

  • Lifetimes for catchain and shard validators

  • Number of shard validators

p29 (Consensus Timing and Limits)

• Contains parameters controlling consensus:

  • new_catchain_ids (boolean)

  • round_candidates

  • next_candidate_delay_ms

  • consensus_timeout_ms

  • fast_attempts

  • attempt_duration

  • catchain_max_deps

  • max_block_bytes

  • max_collated_bytes

p31 (Public Key List)

• An array of hexadecimal strings that represent public keys.

• Possibly used for identifying trusted entities or validators.

p34 (Validator Weights)

• Defines validator information for a time range (utime_since to utime_until), including:

  • Total number of validators

  • Total weight of all validators

  • A list of validators with their public_key and weight.

• Usage: Used for weighted voting and consensus decisions.

p42 (Payout Thresholds)

• Defines:

  • threshold: Numeric value, possibly a minimum payout threshold.

  • payouts: Array of license types with associated payout percentages.

Important Implementation Details

• The file uses fixed keys (p0, p1, ... p42) to categorize parameters, which suggests a strict parsing and validation schema in the consuming software.

• Numeric values are often stored as strings to avoid precision loss for very large integers.

• The configuration distinguishes between normal and critical parameters to support multiple modes or states of operation.

• Validator and consensus parameters emphasize timing, weight, and stake, reflecting the importance of decentralized governance.

• Gas and resource limits ensure system stability by capping resource consumption.

• Cryptographic hashes and keys are used extensively to ensure integrity and authenticity of state and participants.

Interaction with Other System Components

• Blockchain Node Software: Loads this configuration to initialize blockchain parameters such as consensus rules, gas costs, validator sets, and network capabilities.

• Consensus Engine: Uses validator weights (p34), election parameters (p15), and consensus timing (p29) to manage validator elections and block production.

• Economic Model: Pricing parameters (p11, p14, p17, p18, p24, p25) inform transaction fees, stake requirements, and validator rewards.

• Gas Management: Parameters in p20, p21, p22, and p23 regulate gas pricing and limits during transaction processing.

• Workchain Management: p12 defines workchain-specific settings, enabling multi-workchain support.

• Security: Cryptographic fields (p0-p3, p31) provide the foundation for trust and verification.

• Serialization and State Management: The p13 field with BOC data may be used to bootstrap or verify blockchain states.

Usage Example

A blockchain node on startup reads blockchain.conf.json and extracts:

• Network parameters like workchains and capabilities.

• Gas and pricing parameters to compute transaction costs.

• Validator sets and weights for consensus participation.

• Stake and election parameters to enforce economic rules.

For instance, to determine the minimum stake required for validators, the system reads p17.min_stake.

Visual Diagram

flowchart TD
ConfigFile["blockchain.conf.json"]
ConfigFile --> Hashes["Hashes and IDs (p0-p3)"]
ConfigFile --> Currencies["Currencies (p7)"]
ConfigFile --> VersionCaps["Version & Capabilities (p8)"]
ConfigFile --> AllowedIDs["Allowed IDs (p9, p10)"]
ConfigFile --> Params["Parameters (p11)"]
ConfigFile --> Workchains["Workchains (p12)"]
ConfigFile --> BOC["BOC Data (p13)"]
ConfigFile --> Fees["Block Fees (p14)"]
ConfigFile --> Elections["Election Timing (p15)"]
ConfigFile --> ValidatorLimits["Validator Limits (p16)"]
ConfigFile --> StakeParams["Stake Parameters (p17)"]
ConfigFile --> PricingOverTime["Pricing Over Time (p18)"]
ConfigFile --> GasLimits1["Gas Limits Set 1 (p20)"]
ConfigFile --> GasLimits2["Gas Limits Set 2 (p21)"]
ConfigFile --> ResourceLimits1["Resource Limits Set 1 (p22)"]
ConfigFile --> ResourceLimits2["Resource Limits Set 2 (p23)"]
ConfigFile --> PricingFactors1["Pricing Factors Set 1 (p24)"]
ConfigFile --> PricingFactors2["Pricing Factors Set 2 (p25)"]
ConfigFile --> CatchainParams["Catchain & Validator Lifetimes (p28)"]
ConfigFile --> ConsensusParams["Consensus Timing & Limits (p29)"]
ConfigFile --> PubKeys["Public Keys List (p31)"]
ConfigFile --> ValidatorWeights["Validator Weights (p34)"]
ConfigFile --> PayoutThresholds["Payout Thresholds (p42)"]

This flowchart illustrates the main parameter groups within the file and their organization, showing how the configuration is structured into thematic sections relevant for blockchain operation.