Near protocol Protocol Consensus and Runtime Boundaries for State Changes
Protocol determines which ordered inputs NEAR validators accept and how every correct node converts them into the same next state. Consensus chooses an accepted chain of blocks and their shard chunks; the runtime then validates transactions and receipts, charges resources, executes permitted actions, and derives new state roots plus execution outcomes. This separation matters because block inclusion, receipt execution, and finality answer different questions. A submitted transaction may be rejected before conversion, while a valid transaction can create asynchronous receipts whose later results affect different shards. The applicable protocol version fixes the rules for an epoch, so an implementation cannot substitute local settings for network-agreed behavior.
In short: Consensus orders valid shard work, while the runtime deterministically converts that work into outcomes, receipts, and committed state roots.
A Normal Transition and Its Bounded Retry
A state-changing request begins with no accepted outcome. The normal path moves from transaction validation to an action receipt, runtime execution, and a terminal outcome. If an RPC cannot find the hash, the smallest safe recovery is to check synchronized network state before signing again. A missing response from one endpoint does not prove that the network rejected the transaction.
| Observed State | Smallest Reversible Response |
|---|---|
| Transaction rejected for a deterministic payload error | Correct the reported payload error, confirm the original cannot advance, and sign a replacement. |
| Hash unknown at one RPC endpoint | Check a synchronized endpoint and recent chain data before creating another signed request. |
| Transaction outcome contains receipt identifiers | Follow those identifiers because the accepted work is already continuing. |
| Action receipt waits for data receipts | Stop retrying while the runtime holds the action for its declared dependencies. |
| Terminal receipt outcome is recorded | Handle its explicit success or failure, then inspect state at the required finality. |
| Shared boundary | Submission alone is not completion evidence; the relevant outcome sets the stop condition. |
This recovery check handles an uncertain RPC response without risking a duplicate of an action that the network may already have accepted. Once receipt identifiers exist, a new transaction is a separate request rather than a retry of the same network work. A deterministic validation error has the opposite boundary: waiting cannot make an invalid signed payload valid.
Who Decides Which State Transition Counts?
Consensus determines the accepted block sequence, while runtime validation determines whether proposed contents produce the commitments recorded in that sequence. Block producers assemble blocks, chunk producers contribute shard-specific work, and validators check the signatures, approvals, roots, and other validity conditions that bind those parts together.
Every non-genesis block must logically include approvals from block producers whose cumulative stake exceeds two-thirds of the current epoch’s total stake. The approval rule gives the chain a stake-weighted basis for progress and finality. It does not authorize an invalid state transition.
A node validating a block or chunk rejects it when the commitments it computes disagree with the contents. Consensus therefore orders candidate work, but the runtime still has to reproduce the proposed state result under the active rules. Agreement on ordering and agreement on execution meet at the committed roots.
Shard Chunks Bind Work to Block Headers
Shard chunks package the transactions, incoming receipts, and resulting commitments for separate portions of state. A block brings those chunk headers into one chain-wide record without merging every shard into one execution queue. Each chunk links prior state to a new state root, while transaction, receipt, and outcome roots let validators detect altered or inconsistent contents. This design preserves one accepted history while allowing shard work to progress in parallel.
Runtime Inputs and Deterministic Outputs
The runtime is the rule engine that turns ordered shard data into an exact state transition. It does not choose the canonical chain. Its job begins after the chain layer supplies the relevant block context, prior state, transactions, and receipts.
State and Ordered Work
Applying a chunk takes the current state root, validator updates, incoming receipts, and transactions, then returns a new state root, outgoing receipts, outcomes, and a proof. Processing order matters because a later action can read state written by an earlier accepted action. Nodes must therefore use the same ordering and the same active rule set.
Validation Before Commitment
Transaction and receipt checks protect the transition boundary. Invalid signatures, unusable permissions, stale transaction context, insufficient balances, malformed actions, or failed runtime conditions can prevent the requested mutation. Intermediate changes remain reversible during application; the runtime finalizes the state update only after the applicable work has completed under its rules.
Commitments From Execution
A state root is a compact cryptographic commitment to the resulting shard state, not a human-readable account summary. Execution outcomes describe what happened, and outgoing receipts identify work that must continue later. Correct nodes using identical inputs and the same versioned rules must derive matching commitments. A mismatch signals invalid data, incompatible rules, or faulty execution rather than an acceptable alternative state.
What Stops Contract Execution From Consuming Unlimited Resources?
Gas metering bounds contract execution by charging protocol-defined units for computation, memory access, storage operations, and host functions. A function call carries prepaid gas, and execution cannot spend beyond the amount available to that call. Exhausting it causes the call to fail instead of allowing unbounded computation to stall the shard.
Gas units measure work, while the gas price converts that work into a token-denominated cost. Attached deposits remain separate from gas charges; supported gas keys can pay those charges from the key’s prefunded balance rather than the signer’s account balance. Failure does not restore gas already consumed. Eligible unused prepaid gas can return through refund processing, so the final charged amount depends on executed work rather than the initial allowance alone.
Receipts Carry Work Across Execution Boundaries
Receipts let the runtime continue accepted work in later blocks and on the shard responsible for the receiver. They also separate one completed transition from its dependent transitions.
Action Receipts
An action receipt names a receiver and contains actions for that receiver’s account. The destination shard executes it under the runtime rules that apply there. Creating the receipt proves that earlier processing scheduled the action; it does not prove that the receiver completed it successfully.
Data Receipts
Data receipts carry results needed by dependent actions. The runtime matches each declared data identifier to the action waiting for it. If required data has not arrived, the action receipt is postponed rather than executed with missing input. Once every dependency is present, the runtime can convert the received results into promise results and resume the waiting action.
Refund Receipts
Refund receipts return eligible unused gas or deposits after execution determines what was consumed. They follow the same receiver-oriented routing model as other receipts. A refund is therefore another state transition, not an off-chain correction to an account balance, and its destination must still exist when processing occurs.
Asynchronous branches can finish in different blocks. One branch may succeed while another fails, and the earlier success is not automatically reversed. Separate receipts cannot be made atomic. Contracts can record pending state, inspect downstream results in callbacks, and either complete the update or compensate for earlier effects after the branches finish.
Failure Scope and Persistent Effects
A runtime failure prevents the failing receipt’s attempted mutation from becoming its successful state result, but it does not rewind separate receipts that already completed. Gas consumed before the error remains chargeable, while eligible attached value may be refunded under the relevant action rules. This boundary explains why a transaction can have an accepted initial outcome and still end with a failed descendant receipt. Recovery belongs in explicit callback logic when earlier effects require compensation.
Inclusion, Execution, and Finality
These three states answer different operational questions. Treating them as synonyms creates false confirmations and unnecessary retries.
Block Inclusion
Inclusion shows that the observed block or chunk contains the transaction and records its initial processing on that fork. The transaction outcome may only convert the requested actions into receipts. Any receiver-side execution, callback, or refund can still remain pending.
Receipt Execution
Execution outcomes reveal whether each receipt succeeded, failed, or produced more receipts. Applications should trace the returned identifiers until the branch relevant to their operation reaches a terminal status. A successful parent outcome does not overwrite an explicit failure reported by a descendant.
Chain Finality
Finality describes the chain’s confidence that an accepted block will not be displaced by a competing history. It does not change a failed outcome into a success. A state query should use the finality level required by the application and should be interpreted against the block context returned by the node.
Completion therefore needs the right evidence for the requested effect: a terminal execution result for the relevant receipt branch and, where stronger settlement confidence matters, state observed from a finalized chain position.
Versioned Rules and Network Upgrades
A protocol version identifies network rules and remains distinct from a nearcore software release number. Validators advertise support, but installing a binary does not activate its proposed rules immediately. Once at least 80% of stake votes for a version in the last block of an epoch, activation occurs in the first block two epochs later. Nodes that cannot apply the activated version cannot safely substitute older behavior, so compatibility must be established before they continue validating network state.
State Evidence for Applications and Operators
Execution status explains how work ended, while a state query explains what the selected chain position contains. Logs can help diagnose a contract path, but they are not a replacement for outcome status or committed state. An RPC response should identify its block context so callers can distinguish a fresh optimistic observation from data anchored at their required finality.
Operators need the same separation when investigating a mismatch. They can compare the active network version, the ordered inputs, execution outcomes, and the commitment derived by the runtime. Replaying arbitrary local behavior is not a valid recovery path because consensus accepts only the versioned result. For example, operators can compare against the state root recorded in a finalized chunk header.
Practical questions about Protocol
Can Local Node Settings Change an Accepted State Transition?
No. Operational settings can affect peer connections, storage, caches, tracked data, and RPC service behavior, but they cannot redefine consensus-visible execution. A node must apply the active network version and derive the same commitments as other correct validators. If a local modification produces another state root from identical accepted inputs, the network does not treat that output as an equally valid interpretation.
Does a Nearcore Release Number Equal the Network Protocol Version?
No. The software release identifies a particular client build, while the protocol version identifies the rules active for a network epoch. A release may contain support for a proposed version before validators activate it. This separation lets operators install compatible software ahead of the stake-weighted vote without causing each upgraded node to begin applying new rules independently.
Why Must Contract Execution Avoid Nondeterministic Inputs?
Nondeterministic execution could make correct nodes derive different state roots from the same ordered work. The runtime therefore exposes controlled blockchain context and meters supported host operations under versioned rules. Contract code cannot use an ordinary external network request or a local machine’s clock as an unchecked state-transition input. External information must enter through a transaction or another protocol-supported mechanism.
Why Is a Read-Only State Query Outside the Transition Pipeline?
A view query reads state at a selected block context without creating a transaction or committing a new mutation. A contract view method may execute code to calculate its response, but the node discards any attempted writes. The response can still differ across block contexts, so callers should retain the returned context and request the finality level that matches their use case.
What Happens When a Contract Function Traps After Writing Temporary State?
The runtime does not commit the failing function’s temporary state changes as a successful transition. Gas consumed before the trap remains chargeable, and the resulting outcome reports failure. Separate receipts that completed earlier are not rolled back. If those earlier effects need to be reversed, the contract must arrange a callback or another compensating action with enough gas to run.
Are Client Gas Estimates Part of Consensus?
No. A client estimate helps construct a transaction, but validators enforce the prepaid gas in the signed action and the cost schedule selected by the active network version. Underestimating can make execution run out of gas. Overestimating reserves a larger allowance, with eligible unused gas handled through refund processing rather than treated as work that was consumed.
Do Callback Results Arrive in the Order Actions Were First Submitted?
Not necessarily. Cross-contract work is asynchronous, and receipts can travel to different shards or wait for declared data dependencies. The runtime executes a dependent action only after all required data receipts arrive. Contract logic should identify each promise result by its declared dependency structure instead of assuming that network delivery matches the visual order of the original calls.
Which Evidence Can Tie a Queried Value to Committed State?
A cryptographic state proof can tie a value to the state root for a specific block when the query interface supplies such a proof. The verifier must already trust or verify that block and its finality context. A plain RPC value without a proof relies on the selected node, while the state root alone commits to data but does not reveal the requested key or value.