Blocks

Overview

A Starknet block is a list of transactions and a block header that contains multiple fields, including the hash of the previous block and a commitment to their state diff, as well as commitments to the transactions, events, and receipts it includes.

Block header fields

Name	Type	Description
block_number	u64	The number of this block (i.e., its height)
parent_block_hash	felt252	The hash of the block’s parent
global_state_root	felt252	A commitment to the new state
sequencer_address	ContractAddress	The Starknet address of the sequencer that created the block
block_timestamp	Timestamp	The time at which the sequencer began building the block, in seconds since the Unix epoch
transaction_count	u32	The number of transactions in the block
events_count	u32	The number of events in the block.
state_diff_length	u32	The total amount of storage diffs, nonce updates, deployed contracts, and declared classes
state_diff_commitment	felt252	A commitment to the state diff of the block
transactions_commitment	felt252	A commitment to the transactions included in the block
events_commitment	felt252	A commitment to the events included in the block
receipts_commitment	felt252	A commitment to the receipts of the transactions included in the block
l1_gas_price	(u128, u128)	The price of L1 gas that was used while constructing the block, where the first value is the price in wei and the second is the price in fri (see Fees for more details)
l1_data_gas_price	(u128, u128)	The price of L1 blob gas that was used while constructing the block, where the first value is the price in wei and the second is the price in fri (see Fees for more details)
l2_gas_price	(u128, u128)	The price of L2 gas that was used while constructing the block, where the first value is the price in wei and the second is the price in fri (see Fees for more details)
l1_da_mode	String	CALLDATA or BLOB, depending on how Starknet state diffs are sent to L1
protocol_version	String	The version of the Starknet protocol used when creating the block

Block hash

A block hash is defined by:

h(
    "STARKNET_BLOCK_HASH1",
    block_number,
    global_state_root,
    sequencer_address,
    block_timestamp,
    transaction_count || event_count || state_diff_length || l1_da_mode,
    state_diff_commitment,
    transactions_commitment
    events_commitment,
    receipts_commitment,
    gas_prices_hash,
    protocol_version,
    0,
    parent_block_hash
)

Where:

• h is the Poseidon hash function

• transaction_count || event_count || state_diff_length || l1_da_mode is the concatenation of the 64-bit representations of transaction_count, event_count, and state_diff_length with 0 if l1_da_mode is CALLDATA and 1 if l1_da_mode is BLOB

• gas_prices_hash is defined by:

  h(
      "STARKNET_GAS_PRICES0",
      l1_gas_price_wei,
      l1_gas_price_fri,
      l1_data_gas_price_wei,
      l1_data_gas_price_fri,
      l2_gas_price_wei,
      l2_gas_price_fri
  )
  

  where h is the Poseidon hash function and l1_gas_price_wei, l1_gas_price_fri, l1_data_gas_price_wei, l1_data_gas_price_fri, l2_gas_price_wei, and l2_gas_price_fri are the wei and fri denominated prices for the three resource types.

For a reference implementation, see block_hash_calculator.rs in the Starknet sequencer’s GitHub repository

State diff commitment

The state diff commitment is defined by:

h(
    "STARKNET_STATE_DIFF0",
    s,
    deployed_or_replaced_address_1, ... , deployed_or_replaced_address_s,
    d,
    declared_or_migrated_class_hash_1, declared_or_migrated_compiled_class_hash_1..., declared_or_migrated_class_hash_d, declared_or_migrated_class_hash_d,
    1,
    0,
    n,
    c_1, k_1_1, v_1_1, ... k_1_m1, v_1_m1, ... ,c_n, k_n_1, v_n_1, ... ,k_n_mn, v_n_mn,
    k,
    account1, new_nonce1, ... ,accountk, new_noncek
)

Where:

• h is the Poseidon hash function
• s is the number of deployed and replaced contracts in the block
• deployed_or_replaced_address1, ... , deployed_or_replaced_addresss are the deployed and replaced addresses sorted in numerical increasing order according to the addresses
  • For a replaced address, each value is replaced_contract_address, new_class_hash
• d is the number of declared and migrated classes in the block
• declared_or_migrated_class_hash1, declared_or_migrated_compiled_class_hash1..., declared_or_migrated_class_hashd, declared_or_migrated_class_hashd are the declared or replaced class hashes sorted in a numerical increasing order.
  • declared_or_migrated_class_hash is the hash of the Sierra code
  • declared_or_migrated_compiled_class_hash is the hash of the CASM code
• 1 and 0 are placeholders that may be used in the future
• n is the number of contracts whose storage was updated
• c_i, k_i_1, v_i_1, … , k_i_mi,v_i_mi are mi updates (k_i_1, v_i_1), … ,(k_i_mi, v_i_mi) to contract addresses c_i. Where k_i_j is the j-th key and v_i_j is the j-th new value
• k is the number of accounts whose nonce was updatedTransactions, events, and receipts commitments

Transactions, events, and receipts commitments

The commitment to transactions, the commitment to events and the commitment to receipts are all roots of height-64 binary Merkle Patricia tries where the leaf at index i corresponds to:

• For transactions: h(transaction_hash, signature) for the i’th transaction included in the block, where transaction_hash is calculated as follows and h is the Poseidon hash function. Note that the signature is itself a (possibly empty) array of field elements.
• For events: The event hash of the i’th emitted event included in the block
• For receipts: The receipt hash of the i’th transaction receipt included in the block

Event hash

The hash of an event emitted by a contract whose address is emitter_address and a transaction whose hash is tx_hash is defined by:

h(
    emitter_address,
    tx_hash,
    h(keys),
    h(data)
)

Where h is the Poseidon hash function.

Receipt hash

The hash of a transaction receipt is defined by:

h(
    transaction_hash,
    actual_fee,
    h(messages),
    sn_keccak(revert_reason),
    h(l2_gas_consumed, l1_gas_consumed, l1_data_gas_consumed)
)

Where:

• h is the Poseidon hash function

• h(messages) for messages = (from1, to1, payload1), … , (fromn, ton, payloadn) is defined by:

  h(
      n,
      from1, to1, h(len(payload1) || payload1), ... , fromn, ton, h(len(payloadn) || payloadn)
  )