@secondlayer/verify

Verifies a block's state against an authenticated header.

The witness must recompute stateRoot, then every leaf is classified. With state writes, any leaf that is not a named write, a carried parent value or MARF bookkeeping is a hidden write. Without them the diff is still proven, since every leaf is in the block: carried leaves are told apart only through parentLeaves, and the remaining writes come back unnamed.

Thrown for a malformed block body or a transaction root mismatch.

Hashes a block's transactions and checks them against the header.

Each transaction is hashed to its txid and checked against the header's tx_merkle_root. The body after header.byteLength is a u32 count, then the transactions back to back. It returns null when the bytes are the header alone, as a source that serves headers only does. It throws TransactionsError on a malformed body, trailing bytes or a root mismatch.

Computes the tx_merkle_root over transaction ids.

A leaf is H(0x00 ‖ txid) and a node is H(0x01 ‖ l ‖ r). An odd level duplicates its last node, and a lone leaf is still paired with itself, so a one-transaction block hashes H(0x01 ‖ leaf ‖ leaf).

Describes a verification as one line per link and a verdict.

It is the human view, shared by the CLI and the browser checker. Ancestry appears only below the checkpoint. rows says whether the caller asked for the rows link.

Verifies blocks from one checkpoint against one source.

It caches the Bitcoin header chain, proven signer sets and fetched headers across calls.

Verify one block by id (hex) or height. Never throws for bad source data.

Proves a Bitcoin tx is in the checkpoint's Bitcoin chain.

It can also prove that one output pays expect. Pass an SpvProof, or a txid for the source's getBitcoinTxProof to fetch. It never throws for bad source data.

One-shot: verify a block from a checkpoint (MAINNET_CHECKPOINT by default).

Reads blocks, epoch 2.x headers and MARF proofs from a Stacks node.

It uses the node's RPC. Witnesses, burn preimages and Bitcoin headers need another source: spread this over one.

Raw block bytes, header first, by block id or height.

An epoch 2.x header and its consensus hash, by index block hash.

A MARF inclusion proof for a path at a tip.

It is null when the key is absent.

Reads every proof input from the Secondlayer API.

Blocks, epoch 2.x headers, MARF proofs, witnesses, burn preimages, Bitcoin headers and each block's state writes come from /v1/proofs/*, which is free and rate limited. Indexed vm_events rows come from the Index API as metered rows, and are read only when verifyBlock gets rows: true. Methods are own properties, so a partial source spreads over it: { ...new SecondlayerProofSource(o), ...new NodeRpcProofSource(n) }.

Raw block bytes, header first, by block id or height.

An epoch 2.x header and its consensus hash, by index block hash.

A MARF inclusion proof for a path at a tip.

It is null when the key is absent.

The state witness for a block.

The burn preimage behind a consensus hash.

Raw 80-byte Bitcoin headers, count of them from height from.

Every MARF write of a block, in ordinal order.

It is null when there are none.

The indexed vm_events write rows of a block, from the Index API.

A Bitcoin tx, its merkle branch and header, by txid.

The txid is display-order hex.

Thrown when a proof source request fails.

It carries the request url, the HTTP status (null when there was none) and the detail.

Encodes bytes as a lowercase hex string.

Hex to bytes; tolerates a 0x prefix.

Computes a header's block id, also called the index block hash.

The id is sha512/256(block_hash || consensus_hash). A Nakamoto block hash is its signer signature hash; a 2.x one hashes the whole header.

Narrows a Stacks header to an epoch 2.x header.

Parses the epoch 2.x block header at the start of raw.

raw is a header from /v2/headers, or block bytes from /v2/blocks/<id>. consensusHash is the 20-byte hash of the sortition that elected the block.

Parse the NakamotoBlockHeader at the start of raw block bytes (/v3/blocks/<id>). Handles v0 and v1 (v1 appends problematic_txs).

Hashes a Nakamoto header the way its signers sign it.

It is sha512/256 over every header field except the signer signatures, which is also the header's block_hash.

Hashes a key to its MARF path: sha512/256 of the UTF-8 key.

Lists the ancestor tries a MARF proof crosses.

Each id is the backptr a descendant trie follows toward the leaf, and verifyMarfProof needs every one's header. They are read from untrusted proof bytes, so they are only fetch hints: the proof still fails unless each header hashes to the id the trie committed. Malformed proofs yield no ids.

Hashes a value to its MARF value: sha512/256, padded to 40 bytes.

Verifies a MARF inclusion proof.

It is true only when value is stored at path in the MARF whose tip root is root. Inclusion only: MARF proofs cannot prove absence. Malformed proof bytes verify false.

Classify every leaf of block N's trie against the claimed write set. Each leaf must be a claimed write, a carried (unchanged) parent value, or a MARF-internal key; anything else is a hidden write.

Parse a v2 state witness and recompute its root. Throws on malformed input. The result proves nothing until root equals a header's state_index_root.

Decodes a cycle-signer-set value from the .signers contract.

The value is hex or bytes, as stored in the MARF: (some (list (tuple (signer principal) (weight uint) ...))).

Sums the weight of the signers who signed a block header.

It recovers each header signature's key over signer_signature_hash, maps it to its mainnet p2pkh principal, and sums weights from set. The set must be the one for the reward cycle of the tenure-electing burn block.

First burn height of reward cycle cycle.

Reward cycle containing burnHeight.

Check preimage against a 20-byte consensus hash. Returns the burn block hash as hex, already in Bitcoin display order (as bitcoin-cli getblockhash prints it), or null when the preimage does not match.

The MARF key of a data variable: vm::<contract>::1::<var>.

The MARF key of a fungible token balance: vm::<contract>::2::<token>::<principal json>.

The holder is serde-JSON PrincipalData, e.g. {"Standard":[22,[...20 bytes]]}.

The MARF key of a map entry: vm::<contract>::0::<map>::<serialized key hex>.

Starts a header chain at a checkpoint.

Height of a header in this chain by display-order hash, or undefined.

The header entry at a height, if the chain has one.

Validates and appends headers in order. All-or-nothing: if any header fails, the chain is left exactly as it was and the error is thrown.

Thrown when a Bitcoin header fails a validation rule.

rule names the rule and height the header that failed it.