Blocks, transactions and receipts

A block is a fixed-size header, which carries the proof of work and commits to everything else, and a body with the transactions and one receipt for each. A transaction asks the chain to run a program, and its receipt records what happened. This page describes the fields that explorers show and integrators build and read. The exact rules are in section 4 of the protocol rules.

The types in the tables are those of canonical bytes.

The header#

Every field has a fixed width, so every header is exactly 294 bytes. Header-first synchronization and light clients rely on that: nodes can check headers, and their proof of work, before they fetch bodies.

A block's BlockId is the hash of its header, H("block", encode(Header)), and it is the BlockId that has to meet the target (proof of work). The header commits to the rest of the block through four hashes:

• transactions_root and receipts_root, ordered commitments to the transactions and the receipts in the body;
• producer_hash, the hash H("producer", producer_data) of the miner's producer data;
• state_root, the root of the state tree after the block's transactions have run.

The four votes are in resource-vector order: C, S, D, G. Each is 0 to hold, 1 to increase or 2 to decrease that capacity; any other value makes the header invalid. What the votes do is on capacity voting.

Header validity#

A header must sit one height above its parent, name the network's ChainId and carry the target its ancestry requires (time and difficulty, which also covers timestamps). Its three roots and resources_used must equal what the validator computes for itself from the body and the parent state. The exact list is in section 4.2, and what a validator checks for a whole block is on how nodes agree.

The body#

The body holds the miner's producer data, the number of transactions, the transactions, and then one receipt per transaction in the same order, each transaction and each receipt framed by its length (the exact layout).

Producer data is whatever bytes the miner chooses, of any length. It is paid for as block data, the header's producer_hash commits to it, and programs can read it through the host interface.

Receipts travel with the block for transport and proofs, but a validator derives its own by execution and requires them to match exactly; it never trusts the supplied bytes. An empty body, with no transactions, is valid.

Transactions execute once each, one after another in body order. The first runs against the parent's state; each later one sees that state plus the successful effects of the transactions before it. Receipt i belongs to transaction i.

Transactions#

There are two kinds:

• Call names a target ContractId and carries input bytes.
• Deploy carries WebAssembly code and input for its first run.

The budget is a ceiling, not a payment. It may exceed the block's capacity, because only what the block's transactions actually consume together has to fit (block capacity). Only the data budget has bounds of its own: at least the transaction's own place in the block, and at most 2^32 − 1 (the exact bounds). A miner may apply stricter admission rules of its own, but these are policy, not validity.

TransactionId = H("transaction", ChainId || encode(Transaction))

The hash covers the ChainId, so a transaction has a different ID on every network, and the whole envelope, so changing even the budget changes the ID.

No sender and no replay protection#

A transaction says nothing about who sent or authorized it, and the protocol keeps no list of transactions it has already seen: there is no global replay protection or uniqueness rule. The same bytes can be included again, even twice in one block, and each occurrence executes normally. That is why the API reports a list of occurrences for an ID.

Authorization belongs to applications. An application can have its users sign a separately encoded intent, which should bind the chain, the application, the action and the application's own replay-protection data. Signing the complete envelope, including the signature itself, is not required. See authentication and replay.

Receipts#

A receipt is the outcome of one transaction, as every validator computes it: the TransactionId, a status, the resources actually used, the result bytes and the events kept.

No other status value is valid. A successful deployment's result is the ContractId it created, as described in deploy and invoke.

A failed transaction has no effect on state and keeps no events: a receipt with any status other than 0 has zero events. Its receipt still records what it consumed, along with any result bytes a revert returned. Diagnostic messages, stack traces, error strings, timings and compilation details are never part of a receipt, so implementations cannot disagree about them and they cannot affect any root.

Inside a program, the host's call and deploy functions report a child's outcome with the same status codes, or with call error 128 when no child was run at all. 128 is a value returned to the calling program, never a receipt status (when it is returned).

Events#

An event is the emitting ContractId plus bytes defined by the program. Events are kept, in emission order, only from invocations that succeed and whose callers succeed too.

An invocation that fails, whether by revert, trap or exhaustion, contributes no events, and neither does anything it called. When the top-level invocation fails, the receipt keeps none at all. Emitting an event still costs data even if it is later discarded; see what each counter measures.