Skip to main content

The Blockchain Specification

The blockchain specification, or chainspec, is a collection of configuration settings describing the network state at genesis and upgrades to basic system functionality (including system contracts and gas costs) occurring after genesis. This page describes each field in the chainspec, based on version 1.5.2 of the Casper node. The chainspec can and should be customized for private networks. The chainspec attributes are divided into categories based on what they are configuring.

protocol

These settings describe the active protocol version.

AttributeDescriptionMainnet Setting
versionThe Casper node protocol version.'1.5.2'
hard_resetWhen set to true, clear blocks and deploys back to the switch block (the end of the last era) just before the activation point. Used during the upgrade process to reset the network progress. In most cases, this setting should be true.true
activation_pointThe protocol version that should become active.

If it is a timestamp string, it represents the timestamp for the genesis block. This is the beginning of Era 0. By this time, a sufficient majority (> 50% + F/2 — see the finality_threshold_fraction below) of validator nodes must be running to start the blockchain. This timestamp is also used in seeding the pseudo-random number generator used in the contract runtime for computing the genesis post-state hash.

If it is an integer, it represents an era ID, meaning the protocol version becomes active at the start of this era.
9100

network

The following settings configure the networking layer.

AttributeDescriptionMainnet Setting
nameHuman readable network name for convenience. The state_root_hash of the genesis block is the true identifier. The name influences the genesis hash by contributing to seeding the pseudo-random number generator used in the contract runtime for computing the genesis post-state hash.'casper'
maximum_net_message_sizeThe maximum size of an acceptable networking message in bytes. Any message larger than this will be rejected at the networking level.25_165_824

core

These settings manage the core protocol behavior.

AttributeDescriptionMainnet Setting
era_durationEra duration.'120min'
minimum_era_heightMinimum number of blocks per era. An era will take longer than era_duration if that is necessary to reach the minimum height.20
minimum_block_timeMinimum difference between a block's and its child's timestamp.'16384ms'
validator_slotsNumber of slots available in the validator auction.100
finality_threshold_fractionA number between 0 and 1 representing the fault tolerance threshold as a fraction used by the internal finalizer.
It is the fraction of validators that would need to equivocate to make two honest nodes see two conflicting blocks as finalized.
Let's say this value is F. A higher value F makes it safer to rely on finalized blocks. It also makes it more difficult to finalize blocks, however, and requires strictly more than (F + 1)/2 validators to be working correctly.
[1, 3]
start_protocol_version_with_strict
_finality_signatures_required
Protocol version from which nodes are required to hold strict finality signatures.'1.5.0'
legacy_required_finalityThe finality required for legacy blocks. Options are 'Strict', 'Weak', and 'Any'.
Used to determine finality sufficiency for new joiners syncing blocks created in a protocol version before the start protocol version with strict finality signatures.
'Strict'
auction_delayNumber of eras before an auction defines the set of validators. If a validator bonds with a sufficient bid in era N, it will be a validator in era N + auction_delay + 1.1
locked_funds_periodThe period after genesis during which a genesis validator's bid is locked.'90days'
vesting_schedule_periodThe period in which the genesis validator's bid is released over time after it is unlocked.'13 weeks'
unbonding_delayDefault number of eras that need to pass to be able to withdraw unbonded funds.7
round_seigniorage_rateRound seigniorage rate represented as a fraction of the total supply.
- Annual issuance: 8%.
- Minimum block time: 2^15 milliseconds.
- Ticks per year: 31536000000.

(1+0.08)^((2^15)/31536000000)-1 is expressed as a fractional number below in Python:
Fraction((1 + 0.08)**((2**15)/31536000000) - 1).limit_denominator(1000000000)
[7, 87535408]
max_associated_keysMaximum number of associated keys for a single account.100
max_runtime_call_stack_heightMaximum height of the contract runtime call stack.12
minimum_delegation_amountMinimum allowed delegation amount in motes.500_000_000_000
prune_batch_sizeGlobal state prune batch size for tip pruning in version 1.4.15. Possible values:
- 0 when the feature is OFF
- Integer if the feature is ON, representing the number of eras to process per block.
0
strict_argument_checkingEnables strict arguments checking when calling a contract; i.e., all non-optional args are provided and they are of the correct CLType.false
simultaneous_peer_requestsNumber of simultaneous peer requests.5
consensus_protocolThe consensus protocol to use. Options are 'Zug' or 'Highway'.'Highway'
max_delegators_per_validatorThe maximum amount of delegators per validator. If the value is 0, there is no maximum capacity.1200

highway

These settings configure the Highway Consensus protocol.

AttributeDescriptionMainnet Setting
maximum_round_lengthHighway dynamically chooses its round length between minimum_block_time and maximum_round_length.'132seconds'
reduced_reward_multiplierThe factor by which rewards for a round are multiplied if the greatest summit has ≤50% quorum, i.e., no finality. Expressed as a fraction (1/5 by default on Mainnet).[1, 5]

deploys

These settings manage deploys and their lifecycle.

AttributeDescriptionMainnet Setting
max_payment_costThe maximum number of motes allowed to be spent during payment. 0 means unlimited.'0'
max_ttlThe duration after the deploy timestamp during which the deploy can be included in a block.'18hours'
max_dependenciesThe maximum number of other deploys a deploy can depend on (requiring them to have been executed before it can execute).10
max_block_sizeMaximum block size in bytes, including deploys contained by the block. 0 means unlimited.10_485_760
max_deploy_sizeMaximum deploy size in bytes. Size is of the deploy when serialized via ToBytes.1_048_576
block_max_deploy_countThe maximum number of non-transfer deploys permitted in a single block.50
block_max_transfer_countThe maximum number of Wasm-less transfer deploys permitted in a single block.1250
block_max_approval_countThe maximum number of approvals permitted in a single block.2600
block_gas_limitThe upper limit of the total gas of all deploys in a block.4_000_000_000_000
payment_args_max_lengthThe limit of length of serialized payment code arguments.1024
session_args_max_lengthThe limit of length of serialized session code arguments.1024
native_transfer_minimum_motesThe minimum amount in motes for a valid native transfer.2_500_000_000

wasm

The following are Wasm-related settings.

AttributeDescriptionMainnet Setting
max_memoryAmount of free memory (in 64 kB pages) each contract can use for its stack.64
max_stack_heightMax stack height (native WebAssembly stack limiter).500

wasm.storage_costs

These settings manage Wasm storage costs.

AttributeDescriptionMainnet Setting
gas_per_byteGas charged per byte stored in global state.630_000

wasm.opcode_costs

The following settings manage the cost table for Wasm opcodes.

AttributeDescriptionMainnet Setting
bitBit operations multiplier.300
addArithmetic add operations multiplier.210
mulMul operations multiplier.240
divDiv operations multiplier.320
loadMemory load operation multiplier.2_500
storeMemory store operation multiplier.4_700
constConst store operation multiplier.110
localLocal operations multiplier.390
globalGlobal operations multiplier.390
integer_comparisonInteger operations multiplier.250
conversionConversion operations multiplier.420
unreachableUnreachable operation multiplier.270
nopNop operation multiplier.200
current_memoryGet the current memory operation multiplier.290
grow_memoryGrow memory cost per page (64 kB).240_000

wasm.opcode_costs.control_flow

These settings manage costs for control flow operations.

AttributeDescriptionMainnet Setting
blockCost for block opcode.440
loopCost for loop opcode.440
ifCost for if opcode.440
elseCost for else opcode.440
endCost for end opcode.440
brCost for br opcode.35_000
br_ifCost for br_if opcode.35_000
returnCost for return opcode.440
selectCost for select opcode.440
callCost for call opcode.68_000
call_indirectCost for call_indirect opcode.68_000
dropCost for drop opcode.440

wasm.opcode_costs.control_flow.br_table

The following settings manage br_table Wasm opcodes.

AttributeDescriptionMainnet Setting
costFixed cost per br_table opcode.35_000
size_multiplierSize of target labels in the br_table opcode will be multiplied by size_multiplier.100

wasm.host_function_costs

The following settings specify costs for low-level bindings for host-side ("external") functions. More documentation and host function declarations are located in smart_contracts/contract/src/ext_ffi.rs.

  • add = { cost = 5_800, arguments = [0, 0, 0, 0] }
  • add_associated_key = { cost = 9_000, arguments = [0, 0, 0] }
  • add_contract_version = { cost = 200, arguments = [0, 0, 0, 0, 0, 0, 0, 0, 0, 0] }
  • blake2b = { cost = 200, arguments = [0, 0, 0, 0] }
  • call_contract = { cost = 4_500, arguments = [0, 0, 0, 0, 0, 420, 0] }
  • call_versioned_contract = { cost = 4_500, arguments = [0, 0, 0, 0, 0, 0, 0, 420, 0] }
  • create_contract_package_at_hash = { cost = 200, arguments = [0, 0] }
  • create_contract_user_group = { cost = 200, arguments = [0, 0, 0, 0, 0, 0, 0, 0] }
  • create_purse = { cost = 2_500_000_000, arguments = [0, 0] }
  • disable_contract_version = { cost = 200, arguments = [0, 0, 0, 0] }
  • get_balance = { cost = 3_800, arguments = [0, 0, 0] }
  • get_blocktime = { cost = 330, arguments = [0] }
  • get_caller = { cost = 380, arguments = [0] }
  • get_key = { cost = 2_000, arguments = [0, 440, 0, 0, 0] }
  • get_main_purse = { cost = 1_300, arguments = [0] }
  • get_named_arg = { cost = 200, arguments = [0, 0, 0, 0] }
  • get_named_arg_size = { cost = 200, arguments = [0, 0, 0] }
  • get_phase = { cost = 710, arguments = [0] }
  • get_system_contract = { cost = 1_100, arguments = [0, 0, 0] }
  • has_key = { cost = 1_500, arguments = [0, 840] }
  • is_valid_uref = { cost = 760, arguments = [0, 0] }
  • load_named_keys = { cost = 42_000, arguments = [0, 0] }
  • new_uref = { cost = 17_000, arguments = [0, 0, 590] }
  • random_bytes = { cost = 200, arguments = [0, 0] }
  • print = { cost = 20_000, arguments = [0, 4_600] }
  • provision_contract_user_group_uref = { cost = 200, arguments = [0, 0, 0, 0, 0] }
  • put_key = { cost = 38_000, arguments = [0, 1_100, 0, 0] }
  • read_host_buffer = { cost = 3_500, arguments = [0, 310, 0] }
  • read_value = { cost = 6_000, arguments = [0, 0, 0] }
  • read_value_local = { cost = 5_500, arguments = [0, 590, 0] }
  • remove_associated_key = { cost = 4_200, arguments = [0, 0] }
  • remove_contract_user_group = { cost = 200, arguments = [0, 0, 0, 0] }
  • remove_contract_user_group_urefs = { cost = 200, arguments = [0, 0, 0, 0, 0, 0] }
  • remove_key = { cost = 61_000, arguments = [0, 3_200] }
  • ret = { cost = 23_000, arguments = [0, 420_000] }
  • revert = { cost = 500, arguments = [0] }
  • set_action_threshold = { cost = 74_000, arguments = [0, 0] }
  • transfer_from_purse_to_account = { cost = 2_500_000_000, arguments = [0, 0, 0, 0, 0, 0, 0, 0, 0] }
  • transfer_from_purse_to_purse = { cost = 82_000, arguments = [0, 0, 0, 0, 0, 0, 0, 0] }
  • transfer_to_account = { cost = 2_500_000_000, arguments = [0, 0, 0, 0, 0, 0, 0] }
  • update_associated_key = { cost = 4_200, arguments = [0, 0, 0] }
  • write = { cost = 14_000, arguments = [0, 0, 0, 980] }
  • write_local = { cost = 9_500, arguments = [0, 1_800, 0, 520] }

system_costs

The following settings manage protocol operating costs.

AttributeDescriptionMainnet Setting
wasmless_transfer_costDefault gas cost for a wasmless transfer.100_000_000

system_costs.auction_costs

These settings manage the costs of calling the auction system contract entrypoints.

AttributeDescriptionMainnet Setting
get_era_validatorsCost of calling the get_era_validators entrypoint.10_000
read_seigniorage_recipientsCost of calling the read_seigniorage_recipients entrypoint.10_000
add_bidCost of calling the add_bid entrypoint.2_500_000_000
withdraw_bidCost of calling the withdraw_bid entrypoint.2_500_000_000
delegateCost of calling the delegate entrypoint.2_500_000_000
undelegateCost of calling the undelegate entrypoint.2_500_000_000
run_auctionCost of calling the run_auction entrypoint.10_000
slashCost of calling the slash entrypoint.10_000
distributeCost of calling the distribute entrypoint.10_000
withdraw_delegator_rewardCost of calling the withdraw_delegator_reward entrypoint.10_000
withdraw_validator_rewardCost of calling the withdraw_validator_reward entrypoint.10_000
read_era_idCost of calling the read_era_id entrypoint.10_000
activate_bidCost of calling the activate_bid entrypoint.10_000
redelegateCost of calling the redelegate entrypoint.2_500_000_000

system_costs.mint_costs

These settings manage the costs of calling the mint system contract entrypoints.

AttributeDescriptionMainnet Setting
mintCost of calling the mint entrypoint.2_500_000_000
reduce_total_supplyCost of calling the reduce_total_supply entrypoint.10_000
createCost of calling the create entrypoint.2_500_000_000
balanceCost of calling the balance entrypoint.10_000
transferCost of calling the transfer entrypoint.10_000
read_base_round_rewardCost of calling the read_base_round_reward entrypoint.10_000
mint_into_existing_purseCost of calling the mint_into_existing_purse entrypoint.2_500_000_000

system_costs.handle_payment_costs

These settings manage the costs of calling entrypoints on the handle_payment system contract.

AttributeDescriptionMainnet Setting
get_payment_purseCost of calling the get_payment_purse entrypoint.10_000
set_refund_purseCost of calling the set_refund_purse entrypoint.10_000
get_refund_purseCost of calling the get_refund_purse entrypoint.10_000
finalize_paymentCost of calling the finalize_payment entrypoint.10_000

system_costs.standard_payment_costs

These settings manage the costs of calling entrypoints on the standard_payment system contract.

AttributeDescriptionMainnet Setting
payCost of calling the pay entrypoint and sending an amount to a payment purse.10_000