Skip to main content
Version: Next

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 2.0.0 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.'2.0.0'
hard_resetWhen set to true, clear blocks and transactions 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.
11100

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.'120 minutes'
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.'16384 ms'
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'
migrate_legacy_accountsIf true, the protocol upgrade will migrate ALL user accounts to addressable entity. If false, user accounts will be left as they are and will be lazily migrated on a per-account basis if / when that account is used during transaction execution.true
migrate_legacy_contractsIf true, the protocol upgrade will migrate ALL user contracts to addressable entity. If false, user contracts will be left as they are and will be lazily migrated on a per-contract basis if / when that contract is used during transaction execution.true
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.'0 days'
vesting_schedule_periodThe period in which the genesis validator's bid is released over time after it is unlocked.'0 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, 175070816]
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
maximum_delegation_amountMaximum allowed delegation amount in motes.1_000_000_000_000_000_000
prune_batch_sizeGlobal state prune batch size for tip pruning. 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'.'Zug'
max_delegators_per_validatorThe maximum amount of delegators per validator. If the value is 0, there is no maximum capacity.1200
finders_feeThe split in finality signature rewards between block producer and participating signers.[1, 5]
finality_signature_proportionThe proportion of baseline rewards going to reward finality signatures specifically.[1, 2]
signature_rewards_max_delayLookback interval indicating how many past blocks we are looking at to reward.3
allow_unrestricted_transfersAllows peer to peer transfers between users. Setting this to false makes sense only for private chains.true
allow_auction_bidsEnables the auction entry points 'delegate' and 'add_bid'. Setting this to false makes sense only for private chains that don't need to auction new validator slots. These auction entry points will return an error if called, when this option is set to false.true
compute_rewardsIf set to false, then consensus doesn't compute rewards and always uses 0.true
refund_handlingDefines how refunds of the unused portion of payment amounts are calculated and handled. Valid options are: refund (a ratio of the unspent token is returned to the spender); burn (a ratio of the unspent token is burned); no_refund (no refunds are paid out){ type = 'no_refund' }
fee_handlingDefines how fees are handled. Valid options are: no_fee (fees are eliminated); pay_to_proposer (fees are paid to the block proposer); accumulate (fees are accumulated in a special purse and distributed at the end of each era evenly among all administrator accounts); burn (fees are burned){ type = 'no_fee' }
validator_credit_capIf a validator would recieve a validator credit, it cannot exceed this percentage of their total stake.[1, 5]
pricing_handlingDefines how pricing is handled. Valid options are: classic (senders of transaction self-specify how much they pay); fixed (costs are fixed, per the cost table); reserved (prepaid transaction, currently not supported){ type = 'fixed' }
allow_reservationsDoes the network allow pre-payment / reservations for future execution? Currently not supported.false
gas_hold_balance_handlingDefines how gas holds affect available balance calculations. Valid options are: accrued (sum of full value of all non-expired holds) and amortized (sum of each hold is amortized over the time remaining until expiry).{ type = 'accrued' }
gas_hold_intervalDefines how long gas holds last.'24 hours'
administratorsList of public keys of administrator accounts. Setting this option makes only on private chains which require administrator accounts for regulatory reasons.[]

See the Fee Elimination page for more details regarding refund_handling, fee_handling, validator_credit_cap, pricing_handling, gas_hold_balance_handling, and gas_hold_interval.

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.'66 seconds'

transactions

These settings manage transactions and their lifecycle.

AttributeDescriptionMainnet Setting
max_ttlThe duration after the transaction timestamp during which the transaction can be included in a block.'2 hours'
block_max_approval_countThe maximum number of approvals permitted in a single block.2600
max_block_sizeMaximum block size in bytes, including transactions contained by the block. 0 means unlimited.5_242_880
block_gas_limitThe upper limit of the total gas of all transactions in a block.3_300_000_000_000
native_transfer_minimum_motesThe minimum amount in motes for a valid native transfer.2_500_000_000
max_timestamp_leewayThe maximum value to which transaction_acceptor.timestamp_leeway can be set in the config.toml file.'5 seconds'

transactions.v1

These settings manage the transaction lanes including both native and Wasm based interactions. See Lanes and gas costs for details.

AttributeMainnet Setting
native_mint_lane[0, 1024, 1024, 65_000_000_000, 650]
native_auction_lane[1, 2048, 2048, 362_500_000_000, 145]
wasm_lanes[[2, 1_048_576, 2048, 1_000_000_000_000, 1], [3, 344_064, 1024, 500_000_000_000, 3], [4, 172_032, 1024, 50_000_000_000, 7], [5, 12_288, 512, 1_500_000_000, 15]]

transactions.deploy

AttributeDescriptionMainnet Setting
max_payment_costThe maximum number of motes allowed to be spent during payment. 0 means unlimited.'0'
max_dependenciesThe maximum number of other transactions a transaction can depend on (requiring them to have been executed before it can execute).10
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

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.1_117_587

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.messages_limits

The following chainspec settings manage the cost of contract-level messages.

AttributeDescriptionMainnet Setting
max_topic_name_sizeMaximum size of the topic name.256
max_topics_per_contractMaximum number of topics that can be added for each contract.128
max_message_sizeMaximum size in bytes of the serialized message payload.1_024

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.

Host-Side FunctionCostArguments
add5_800[0, 0, 0, 0]
add_associated_key1_200_000[0, 0, 0]
add_contract_version200[0, 0, 0, 0, 120_000, 0, 0, 0, 30_000, 0, 0]
blake2b1_200_000[0, 120_000, 0, 0]
call_contract300_000_000[0, 0, 0, 120_000, 0, 120_000, 0]
call_versioned_contract300_000_000[0, 0, 0, 0, 120_000, 0, 120_000, 0]
create_contract_package_at_hash200[0, 0]
create_contract_user_group200[0, 0, 0, 0, 0, 0, 0, 0]
create_purse2_500_000_000[0, 0]
disable_contract_version200[0, 0, 0, 0]
get_balance3_000_000[0, 0, 0]
get_blocktime330[0]
get_caller380[0]
get_key2_000[0, 440, 0, 0, 0]
get_main_purse1_300[0]
get_named_arg200[0, 120_000, 0, 120_000]
get_named_arg_size200[0, 0, 0]
get_phase710[0]
get_system_contract1_100[0, 0, 0]
has_key1_500[0, 840]
is_valid_uref760[0, 0]
load_named_keys42_000[0, 0]
new_uref17_000[0, 0, 590]
random_bytes200[0, 0]
print20_000[0, 4_600]
provision_contract_user_group_uref200[0, 0, 0, 0, 0]
put_key100_000_000[0, 120_000, 0, 120_000]
read_host_buffer3_500[0, 310, 0]
read_value60_000[0, 120_000, 0]
read_value_local5_500[0, 590, 0]
remove_associated_key4_200[0, 0]
remove_contract_user_group200[0, 0, 0, 0]
remove_contract_user_group_urefs200[0, 0, 0, 0, 0, 120_000]
remove_key61_000[0, 3_200]
ret23_000[0, 420_000]
revert500[0]
set_action_threshold74_000[0, 0]
transfer_from_purse_to_account2_500_000_000[0, 0, 0, 0, 0, 0, 0, 0, 0]
transfer_from_purse_to_purse82_000_000[0, 0, 0, 0, 0, 0, 0, 0]
transfer_to_account2_500_000_000[0, 0, 0, 0, 0, 0, 0]
update_associated_key4_200[0, 0, 0]
write14_000[0, 0, 0, 980]
dictionary_put9_500[0, 1_800, 0, 520]
enable_contract_version200[0, 0, 0, 0]
manage_message_topic200[0, 30_000, 0, 0]
emit_message200[0, 30_000, 0, 120_000]
cost_increase_per_message50

system_costs

The following settings manage protocol operating costs.

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
change_bid_public_keyCost of calling the change_bid_public_key entrypoint.5_000_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
burnCost of calling the burn 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