Gas Killer Docs
Solidity Reference

Reference

GasKillerSDK and GasKillerNestedSDK API surface, state update types, and revert selectors.

API surface of GasKillerSDK. Inheriting it gives your contract everything on this page.

abstract contract GasKillerSDK is
    StateTracker, TransitionGuard, ERC165, IGasKillerSDK, IGasKillerSDKBatch, IGasKillerValueBound

abstract contract GasKillerNestedSDK is GasKillerSDK, IGasKillerNested

GasKillerNestedSDK adds verifyAndUpdateTree for nested settlement.

Constants

ConstantValueMeaning
—300Default blockStaleMeasure, in blocks, when unset
ERC-165 id0x82b35a01IGasKillerSDK; the router requires it
ERC-165 id0xce8e6efcIGasKillerSDKBatch; batching and the in-transition latch
ERC-165 id0x0fd29eceIGasKillerValueBound; required for tasks with value
ERC-165 id0x78481874IGasKillerNested; the contract can take part in nested settlement

The quorum threshold is not an SDK constant. It belongs to the SchnorrStakeRegistry the target is wired to, as thresholdNum / thresholdDen of the registry's total weight. The public testnet registry requires 2/3.

verifyAndUpdate

The settlement entrypoint. The router builds this call for you (you never encode it by hand), but its parameters explain every failure mode.

function verifyAndUpdate(
    bytes32 msgHash,
    uint32 referenceBlockNumber,
    bytes calldata storageUpdates,
    uint256 transitionIndex,
    bytes4 targetFunction,
    uint256 s,
    address Raddr,
    address[] calldata nonSigners
) external payable;
ParameterPurpose
msgHashThe signed digest; recomputed on-chain and compared
referenceBlockNumberBlock the operator set is evaluated at
storageUpdatesABI-encoded (StateUpdateType[], bytes[]) — the diff to apply
transitionIndexCounter value this payload was computed against
targetFunctionSelector of the tracked function that was simulated
sAggregate Schnorr response scalar
RaddrAggregate nonce, as address(R)
nonSignersOperators that did not sign, in strictly ascending order

It executes in this order, so an earlier check masks any later one:

  1. referenceBlockNumber < block.number → else FutureBlockNumber
  2. referenceBlockNumber + blockStaleMeasure >= block.number → else StaleBlockNumber
  3. transitionIndex + 1 == stateTransitionCount() → else InvalidTransitionIndex
  4. Digest, including msg.value, matches msgHash → else InvalidSignature
  5. isValidSignature on the configured registry: subtract each non-signer's key and weight from the aggregate, check the threshold, verify the signature → else InvalidQuorumSignature, or a registry revert
  6. Apply the updates

Verification gas doesn't grow with the size of the operator set: one ecrecover against the registry's cached aggregate key, plus one point subtraction per non-signer.

The signed digest

sha256(abi.encode(transitionIndex, address(this), targetFunction, storageUpdates))
// with msg.value appended when the transition carries ETH:
sha256(abi.encode(transitionIndex, address(this), targetFunction, storageUpdates, msg.value))

It binds the payload to one contract, one state of it, and the exact ETH sent. getMessageHash(transitionIndex, targetFunction, storageUpdates) and getMessageHashWithValue(..., value) return it for off-chain checks.

verifyAndUpdateBatch

Settles several independently signed transitions in one transaction. Every transition after the first verifies at warm-access prices.

struct TaskSubmission {
    bytes32 msgHash;
    uint32 referenceBlockNumber;
    bytes storageUpdates;
    uint256 transitionIndex;
    bytes4 targetFunction;
    uint256 s;
    address Raddr;
    address[] nonSigners;
    uint256 value;
}

function verifyAndUpdateBatch(TaskSubmission[] calldata submissions) external payable;

Each submission is checked exactly as a standalone verifyAndUpdate would check it, so the signed digest does not change when a transition is batched. Submissions apply in order of ascending transitionIndex, and the batch is atomic.

A submission whose index has already settled is skipped rather than reverting the batch, so someone settling one submission first can't void the rest. Only a gap in the indexes reverts, with InvalidTransitionIndex.

Send at least the sum of the submissions' value. Any surplus, such as a skipped submission's share, is refunded to the sender.

verifyAndUpdateTree

GasKillerNestedSDK only. Settles a nested settlement rooted at this contract. The router builds the call; send the payload as-is.

function verifyAndUpdateTree(TreeSubmission calldata submission) external payable;

It runs the same block, transition-index and value checks as verifyAndUpdate, then has each contract further down the chain apply its own part. The signature also carries an expiry block, which the payload's valid_until_block never exceeds.

State update types

storageUpdates decodes to a list of operations applied in order.

TypeEffect
STOREWrite a 32-byte value to a storage slot
CALLExternal call, optionally with ETH value
LOG0–LOG4Emit a log with 0–4 indexed topics
CREATEDeploy a contract, nonce-derived address
CREATE2Deploy a contract, salt-derived address
NESTEDHave a nested Gas Killer contract apply its own part, optionally with ETH value

Most integrations only ever produce STORE and LOG*. See Tracked functions for the funding rules that apply to the value-bearing types.

Inherited members

From StateTracker:

MemberDescription
trackStateModifier; increments the transition counter before the body
stateTransitionCount()Transitions applied so far

From TransitionGuard:

MemberDescription
guardTransitionModifier; reverts re-entry, holds the in-transition latch
inTransition()True while a transition is applying

Both use fixed hashed slots, and TransitionGuard uses EIP-1153 transient storage, so a Cancun-or-later EVM is required.

Revert selectors

What a failed settlement means. Reverts from the SDK:

SelectorErrorCauseFix
0x252f8a0eFutureBlockNumberReference block is not yet minedRetry; usually a node lagging behind head
0x305c3e93StaleBlockNumberPayload older than blockStaleMeasureSubmit a new task — the payload expired
0x7376e0a2InvalidTransitionIndexContract state advanced since signingSubmit a new task; another transition landed first
0x8baa579fInvalidSignatureRecomputed digest ≠ msgHashSend exactly the payload's value; otherwise the payload was altered
0x68477238InvalidQuorumSignatureThe registry rejected the signatureSee below
0xc2e5347dEmptyBatchverifyAndUpdateBatch called with no submissionsReport it — malformed batch
0x1eb7025cInsufficientBatchValuemsg.value below the applied submissions' total valueSend at least the sum of every submission's value
0x83a33c51BlockStaleMeasureOverflow_setBlockStaleMeasure given a value above uint96Fix the value your contract passes
0x287cdcedReentrantTransitionverifyAndUpdate re-entered mid-transitionA CALL update re-entered the contract; see inTransition()
0x493f09c4RevertingContextAn external or nested call revertedDecode its inner revert data. Empty data on a call that sends ETH usually means the balance is short
0x30116425DeploymentFailedA CREATE/CREATE2 update failedOften a balance that can't cover the deployment's value
0x5f6f132cInvalidArgumentsUpdate arguments malformedReport it
0x25773e13MalformedLogPayloadLog update malformedReport it

Nested settlement reverts

These come straight from verifyAndUpdateTree, or, when they happen in a nested contract's part, wrapped in RevertingContext. Decode its inner data (cast decode-error <revertData>) to find which of these it was.

SelectorErrorFix
0x63a089fcNotTreeMemberSend exactly the payload's value
0xa5313d69LeafMismatchA nested contract's state changed since signing. Submit a new task
0xc5d89109NotApprovedA nested contract is wired to a different registry. Wire every contract to the published one
0x7c315b2eNestedNotAppliedA nested contract doesn't inherit GasKillerNestedSDK
0x0aa2ca67, 0x90a8ddf4, 0xa8bab44a, 0x3d52f9e6NotPendingChild, NestedOutsideTree, MissingWitness, UnconsumedWitnessesMalformed payload. Report it

Reverts that come from the SchnorrStakeRegistry, not the SDK:

SelectorErrorWhat it usually means
0xdc897c0cStaleSnapshotThe operator set changed after the reference block. Submit a new task
0x11ea130dFutureReferenceBlockReference block is not yet mined. Retry
0xbfc6c337NotRegistered(address)A listed non-signer is not in this registry. Your target may be wired to a different registry than the router signs for, see Configuration
0xedb3eb6cNonSignersNotSortedMalformed non-signer list. Report it
0x2e29e1fdApprovalExpiredA nested settlement passed its expiry. Submit a new task
0x14259559InvalidExpiryProofMalformed nested settlement payload. Report it
0xad60149eInvalidApprovalSignatureA nested settlement's signature was rejected, for the same reasons as InvalidQuorumSignature

InvalidQuorumSignature

The registry returned false. There are two causes:

  • Too few signers. The operators who signed hold less than the threshold share of the registry's weight. This is transient: too many operators missed the round.
  • The aggregate doesn't match. The key the registry holds is not the one the operators signed with. If it happens on every task, your target is wired to the wrong registry. If it happens once, the operator set changed mid-round and a new task will settle.

Decode an unknown selector with cast 4byte <selector>, or recover a revert locally by replaying the payload at a block inside its validity window:

cast call "$TO" "$DATA" --from "$FROM" --block <n> --rpc-url "$RPC_URL"

A payload that reverts at every block in its window is not a timing problem: it is a configuration problem.

Source

On this page