@secondlayer/verify 0.1.0 → 0.2.0

package/README.md

@@ -9,6 +9,13 @@ checkpoint -> Bitcoin headers (proof of work) -> burn block -> signer set (MARF
            -> header signatures (70% of signer weight) -> state witness (state root) -> state diff
 ```
 
+Blocks below the checkpoint take a shorter chain. The checkpoint's header commits to every ancestor by hash, so no signatures are needed:
+
+```
+checkpoint -> block id at that height (parent links, or one MARF proof) -> header hashes to the id
+           -> state witness (state root) -> state diff
+```
+
 Every byte comes from a source you don't have to trust. A lying source can make a link fail, never pass. Powers `secondlayer verify block` in [`@secondlayer/cli`](https://www.npmjs.com/package/@secondlayer/cli).
 
 ## Install
@@ -43,6 +50,8 @@ const source = {
 };
 ```
 
+Heights below the checkpoint need no extra options: `verifyBlock(150_000, { source })` derives the direction. Within 16 blocks of a trusted block the verifier follows `parent_block_id` links. Farther down it asks the source for one MARF proof of `__MARF_BLOCK_HEIGHT_TO_HASH::<height>` at the checkpoint: each block writes its parent's id there, so the proof names the ancestor and is checked against the checkpoint's state root. Pre-Nakamoto (2.x) blocks need a source with `getEpoch2Header`, which both sources here implement.
+
 `verifyBlock` never throws for bad source data: it returns `ok: false` with `failures`, the first entry being the first broken link. Use `BlockVerifier` to verify many blocks from one checkpoint and reuse the synced Bitcoin headers and proven signer sets.
 
 By default only proofs are read, and proofs are free. Pass `rows: true` to also name every write and check the indexed rows: the source's `state_writes` and `vm_events` reads bill as Index rows on the Secondlayer API.
@@ -62,11 +71,14 @@ await verifyBlock(9_137_005, { source, rows: true });
 | Its state | the witness recomputes the header's state root |
 | Every key it wrote | `rows: true` and a source with `state_writes`: each written leaf is named, nothing hidden |
 | Indexed rows | `rows: true`: each `vm_events` row matches a leaf the block wrote |
+| Below the checkpoint: it is the checkpoint chain's block at that height | parent links or a MARF proof from the checkpoint's state root, then the header (Nakamoto or 2.x) hashes to that id |
 
 ## What it trusts, and what it doesn't cover
 
 - **The checkpoint.** `MAINNET_CHECKPOINT` (Stacks block 8,956,304, cycle 143 signers, Bitcoin block 967,680) is trusted as-is. Pass `checkpoint` to use your own.
-- **Bitcoin heights.** Blocks whose burn height is below the checkpoint's Bitcoin block can't be verified. Headers are checked for valid work, not compared against a competing chain, and reorgs past the synced tip are not followed.
+- **Bitcoin heights.** At or above the checkpoint, a block's burn block must be at or above the checkpoint's Bitcoin block. Below the checkpoint the burn block is checked only when it is (with the baked checkpoint it never is); the hash chain pins those blocks instead. Headers are checked for valid work, not compared against a competing chain, and reorgs past the synced tip are not followed.
+- **MARF proofs of `__MARF_*` keys.** A node's `/v2/clarity/marf` answers only keys with a stored value string, and these have none. The API's `/v1/proofs/marf` falls back to its proof sidecar for them; with `NodeRpcProofSource` alone, blocks more than 16 below a trusted block fail `ancestry` as `unavailable`.
+- **Epoch 2.x consensus hashes.** A 2.x header commits to its parent's block hash, not its id. The id always comes from a trusted descendant (its header, or a MARF proof), and the source's consensus hash must hash with the header to it. State proofs for 2.x heights are against the anchored block's root, which covers the microblocks it confirms.
 - **Names need `rows: true` and `state_writes`.** Without them every write is still proven, but unnamed; `notes` says so.
 - **Not covered:** print events (Stacks headers don't commit to them) and transaction contents.
 

package/dist/index.d.ts

@@ -30,8 +30,43 @@ declare function parseNakamotoHeader(raw: Bytes): NakamotoHeader;
 * except the signer signatures. Also the header's block_hash.
 */
 declare const signerSignatureHash: (h: NakamotoHeader) => Bytes;
-/** StacksBlockId = sha512/256(block_hash || consensus_hash). */
-declare const blockId2: (h: NakamotoHeader) => Bytes;
+/**
+* Epoch 2.x anchored block header. It commits to the parent's block hash, not
+* its index block hash, and carries no consensus hash: the source supplies
+* that, and `blockId` binds it to an id proven elsewhere.
+*/
+interface Epoch2Header {
+	version: number;
+	/** total_work.burn: burn spent on the fork so far. */
+	burnSpent: bigint;
+	/** total_work.work: the Stacks chain length (one per anchored block). */
+	chainLength: bigint;
+	vrfProof: Bytes;
+	parentBlockHash: Bytes;
+	parentMicroblock: Bytes;
+	parentMicroblockSequence: number;
+	txMerkleRoot: Bytes;
+	/** Covers the block and the parent microblock stream it confirms. */
+	stateIndexRoot: Bytes;
+	microblockPubkeyHash: Bytes;
+	/** sha512/256 of the serialized header. */
+	blockHash: Bytes;
+	consensusHash: Bytes;
+}
+type StacksHeader = NakamotoHeader | Epoch2Header;
+/**
+* Parse the epoch 2.x StacksBlockHeader at the start of `raw` (a header from
+* `/v2/headers`, or block bytes from `/v2/blocks/<id>`), with the 20-byte
+* consensus hash of the sortition that elected it.
+*/
+declare function parseEpoch2Header(raw: Bytes, consensusHash: Bytes): Epoch2Header;
+declare const isEpoch2Header: (h: StacksHeader) => h is Epoch2Header;
+/**
+* StacksBlockId (index block hash) = sha512/256(block_hash || consensus_hash).
+* A Nakamoto block hash is its signer signature hash; a 2.x one hashes the
+* whole header.
+*/
+declare const blockId2: (h: StacksHeader) => Bytes;
 /** TrieHash::from_key: sha512/256(utf8(key)). */
 declare const marfPath: (key: string) => Bytes;
 /** MARFValue::from_value: sha512/256(utf8(value)) padded to 40 bytes. */
@@ -59,7 +94,7 @@ interface MarfProofInput {
 	* vouched for by header bytes (a bare root->id map would let a forged
 	* ancestor trie through).
 	*/
-	headers: NakamotoHeader[];
+	headers: StacksHeader[];
 }
 /**
 * TrieMerkleProof::verify. True iff `value` is stored at `path` in the MARF
@@ -257,8 +292,8 @@ interface VerifyCheckpoint {
 /**
 * Mainnet: Stacks block 8,956,304 (`3914ea5f…74bb`) holding the cycle 143
 * signer set (29 signers, weight 4000), and Bitcoin block 967,680 (a
-* retarget-period start inside cycle 143). Verifies blocks whose burn
-* height is 967,680 or later.
+* retarget-period start inside cycle 143). Later blocks verify forward
+* (burn height 967,680 or later); earlier ones by hash chain from 8,956,304.
 */
 declare const MAINNET_CHECKPOINT: VerifyCheckpoint;
 /** Sortition preimage behind a consensus hash. */
@@ -297,10 +332,26 @@ interface VmEventRow {
 	raw_key?: string | null;
 	raw_value?: string | null;
 }
+/** An epoch 2.x header and the consensus hash its index block hash commits to. */
+interface Epoch2HeaderResponse {
+	/** Consensus-serialized StacksBlockHeader. */
+	header: Bytes;
+	consensusHash: Bytes;
+}
 interface ProofSource {
 	/** Raw Nakamoto block bytes (header first), by block id or height. */
 	getBlock(ref: string | number): Promise<Bytes>;
-	/** MARF inclusion proof for a 32-byte path at `tipId`; null when the key is absent. */
+	/**
+	* Epoch 2.x block header by index block hash: blocks below the checkpoint
+	* from before Nakamoto. Without it only Nakamoto blocks verify.
+	*/
+	getEpoch2Header?(blockId: string): Promise<Epoch2HeaderResponse>;
+	/**
+	* MARF inclusion proof for a 32-byte path at `tipId`; null when the key is
+	* absent. Blocks below the checkpoint also ask for
+	* `__MARF_BLOCK_HEIGHT_TO_HASH::<height>`, whose value is no stored string:
+	* only `proof` is read for it.
+	*/
 	getMarfProof(pathHex: string, tipId: string): Promise<MarfProofResponse | null>;
 	/** State witness (wire v3) for a block. */
 	getWitness(blockId: string): Promise<Bytes>;
@@ -327,14 +378,15 @@ interface SecondlayerSourceOptions {
 	fetch?: Fetch;
 }
 /**
-* Every proof input from the Secondlayer API: `/v1/proofs/*` for blocks, MARF
-* proofs, witnesses, burn preimages and Bitcoin headers; the Index API for
+* Every proof input from the Secondlayer API: `/v1/proofs/*` for blocks, epoch
+* 2.x headers, MARF proofs, witnesses, burn preimages and Bitcoin headers; the Index API for
 * state_writes and vm_events, read only when verifyBlock gets `rows: true`.
 * Methods are own properties, so a partial source spreads over it:
 * `{ ...new SecondlayerProofSource(o), ...new NodeRpcProofSource(n) }`.
 */
 declare class SecondlayerProofSource implements ProofSource {
 	getBlock: (ref: string | number) => Promise<Bytes>;
+	getEpoch2Header: (blockId: string) => Promise<Epoch2HeaderResponse>;
 	getMarfProof: (pathHex: string, tipId: string) => Promise<MarfProofResponse | null>;
 	getWitness: (blockId: string) => Promise<Bytes>;
 	getBurnPreimage: (consensusHash: string) => Promise<BurnPreimage>;
@@ -349,11 +401,13 @@ interface NodeRpcSourceOptions {
 	fetch?: Fetch;
 }
 /**
-* Blocks and MARF proofs straight from a Stacks node's RPC. Witnesses, burn
-* preimages and Bitcoin headers need another source: spread this over one.
+* Blocks, epoch 2.x headers and MARF proofs straight from a Stacks node's RPC.
+* Witnesses, burn preimages and Bitcoin headers need another source: spread
+* this over one.
 */
-declare class NodeRpcProofSource implements Pick<ProofSource, "getBlock" | "getMarfProof"> {
+declare class NodeRpcProofSource implements Pick<ProofSource, "getBlock" | "getEpoch2Header" | "getMarfProof"> {
 	getBlock: (ref: string | number) => Promise<Bytes>;
+	getEpoch2Header: (blockId: string) => Promise<Epoch2HeaderResponse>;
 	getMarfProof: (pathHex: string, tipId: string) => Promise<MarfProofResponse | null>;
 	constructor(opts: NodeRpcSourceOptions);
 }
@@ -432,8 +486,8 @@ interface BlockStateResult {
 * `parentLeaves`, and the remaining writes come back unnamed.
 */
 declare function verifyBlockState(input: BlockStateInput): Promise<BlockStateResult>;
-type VerifyStep = "block" | "bitcoin" | "burn" | "signer-set" | "signatures" | "witness" | "names" | "rows";
-type VerifyFailureCode = StateFailureCode | "unavailable" | "id-mismatch" | "height-mismatch" | "invalid-header" | "preimage-mismatch" | "burn-not-in-chain" | "before-checkpoint" | "anchor-not-found" | "anchor-outside-window" | "anchor-unsigned" | "set-proof-invalid" | "below-threshold" | "unknown-signer" | "duplicate-signer" | "bad-signature";
+type VerifyStep = "ancestry" | "block" | "bitcoin" | "burn" | "signer-set" | "signatures" | "witness" | "names" | "rows";
+type VerifyFailureCode = StateFailureCode | "unavailable" | "id-mismatch" | "height-mismatch" | "invalid-header" | "preimage-mismatch" | "burn-not-in-chain" | "before-checkpoint" | "not-ancestor" | "ancestry-proof-invalid" | "anchor-not-found" | "anchor-outside-window" | "anchor-unsigned" | "set-proof-invalid" | "below-threshold" | "unknown-signer" | "duplicate-signer" | "bad-signature";
 interface VerifyFailure {
 	step: VerifyStep;
 	code: VerifyFailureCode;
@@ -446,13 +500,31 @@ interface VerifyFailure {
 	path?: string;
 	ordinal?: number;
 }
+/** How a block below the checkpoint was tied to it. */
+interface Ancestry {
+	/** Trusted descendant it was proven from: the checkpoint, or a block proven below it earlier. */
+	fromHeight: number;
+	fromBlockId: string;
+	/**
+	* `parents`: each header hashes to the parent id its child commits to.
+	* `marf`: one MARF proof of `__MARF_BLOCK_HEIGHT_TO_HASH::<height>` against
+	* the descendant's state root.
+	*/
+	via: "parents" | "marf";
+}
 interface BlockVerification {
-	/** Every step passed: header, burn binding, signatures, state root, names and rows. */
+	/**
+	* Every step passed. At or above the checkpoint: header, burn binding,
+	* signatures, state root, names and rows. Below it: ancestry, header,
+	* state root, names and rows (and the burn binding when Bitcoin reaches it).
+	*/
 	ok: boolean;
 	height?: number;
 	blockId?: string;
 	/** The header's state_index_root, hex: what the witness must hash to. */
 	stateRoot?: string;
+	/** Set for blocks below the checkpoint, which need no signatures. */
+	ancestry?: Ancestry;
 	cycle?: number;
 	burnHeight?: number;
 	/** Display-order hex. */
@@ -491,7 +563,10 @@ declare class BlockVerifier {
 	private readonly sets;
 	/** Where each proven set was anchored: the lower bound for the next search. */
 	private readonly anchors;
+	/** Headers fetched by id, each checked to hash to it. */
 	private readonly headers;
+	/** Blocks proven on the checkpoint's chain below it, by height. */
+	private readonly below;
 	private readonly burns;
 	/** Unverified source answers by consensus hash. */
 	private readonly preimages;
@@ -500,9 +575,50 @@ declare class BlockVerifier {
 	/** Verify one block by id (hex) or height. Never throws for bad source data. */
 	verify(ref: string | number): Promise<BlockVerification>;
 	private run;
-	/** Header by id, from the cache or the source; the bytes must hash to `id`. */
+	/** At or above the checkpoint: Bitcoin, burn binding, signer set, signatures, state. */
+	private runForward;
+	/**
+	* Below the checkpoint: prove the checkpoint chain's id at `height` (and
+	* that it is `claimed`, when the caller asked by id), then the header that
+	* hashes to it, then its state. Signatures add nothing to a header pinned
+	* by hash from a trusted descendant.
+	*/
+	private runBelow;
+	/**
+	* The checkpoint chain's block id at `height`, from the nearest trusted
+	* block above it: parent links when within MAX_WALK, else one MARF proof.
+	*/
+	private ancestor;
+	/** The lowest trusted block above `height`: the checkpoint or one proven below it. */
+	private nearestAbove;
+	/**
+	* Follow parent ids down from `from`: each parent header must hash to the
+	* id its child committed to. Null when a 2.x header stops the walk: it
+	* commits to its parent's block hash, not the parent's id.
+	*/
+	private walk;
+	/**
+	* Read the id at `height` from `from`'s state: block `height + 1` wrote it
+	* to `__MARF_BLOCK_HEIGHT_TO_HASH::<height>`, and the proof must recompute
+	* `from`'s state root through the header of every trie it crosses.
+	*/
+	private jump;
+	/**
+	* Below the checkpoint the hash chain already pins the block; still bind
+	* its burn block when the Bitcoin checkpoint reaches it. The burn height
+	* here is the source's hint, so a low one only skips this extra check.
+	*/
+	private bindBurnBelow;
+	/** Witness against the authenticated header's root, then the named diff and rows. */
+	private verifyState;
+	/** Header by id, from the cache or the source; it must hash to `id`. */
 	private header;
 	/**
+	* A Nakamoto block by id, or when the source has none (epoch 2.x blocks are
+	* not served as Nakamoto blocks) its epoch 2.x header.
+	*/
+	private fetchHeader;
+	/**
 	* Prove `value` at `path` in `tip`'s state, fetching the header of every
 	* ancestor trie the proof crosses.
 	*/
@@ -515,7 +631,8 @@ declare class BlockVerifier {
 	private parentLeaves;
 	/**
 	* A carried leaf holds the parent's value. The parent header is
-	* authenticated by hash: its id is committed in the signed child header.
+	* authenticated by hash: its id is committed in the authenticated child
+	* (its header, or for 2.x its own trie).
 	*/
 	private parentHolds;
 	/** Consensus hash -> PoW-verified burn block, via the sortition preimage. */
@@ -544,4 +661,4 @@ declare class BlockVerifier {
 }
 /** One-shot: verify a block from a checkpoint (MAINNET_CHECKPOINT by default). */
 declare const verifyBlock: (ref: string | number, opts: VerifyOptions) => Promise<BlockVerification>;
-export { BlockDiff, BlockDiffInput, BlockStateInput, BlockStateResult, BlockVerification, BlockVerifier, BurnPreimage, Bytes, Checkpoint, ClassifiedLeaf, DiffLeaf, DiffWrite, HeaderChain, HeaderRule, HeaderValidationError, MAINNET_CHECKPOINT, MAINNET_FIRST_BURN_HEIGHT, MAINNET_PREPARE_LENGTH, MAINNET_REWARD_CYCLE_LENGTH, MarfProofInput, MarfProofResponse, NakamotoHeader, NodeRpcProofSource, NodeRpcSourceOptions, ProofSource, ProvenDiff, SIGNERS_CONTRACT, SecondlayerProofSource, SecondlayerSourceOptions, SignerCheck, SignerSet, SourceError, StateFailure, StateFailureCode, StateWitness, StateWrite, VerifyCheckpoint, VerifyFailure, VerifyFailureCode, VerifyOptions, VerifyStep, VmEventRow, WitnessLeaf, blockId2 as blockId, classifyBlockDiff, cycleStart, dataVarKey, decodeSignerSet, ftBalanceKey, hex, mapEntryKey, marfPath, marfProofAncestors, marfValue, parseNakamotoHeader, parseWitness, rewardCycle, signerSignatureHash, unhex, verifyBlock, verifyBlockState, verifyConsensusPreimage, verifyMarfProof, verifySignerSignatures };
+export { Ancestry, BlockDiff, BlockDiffInput, BlockStateInput, BlockStateResult, BlockVerification, BlockVerifier, BurnPreimage, Bytes, Checkpoint, ClassifiedLeaf, DiffLeaf, DiffWrite, Epoch2Header, Epoch2HeaderResponse, HeaderChain, HeaderRule, HeaderValidationError, MAINNET_CHECKPOINT, MAINNET_FIRST_BURN_HEIGHT, MAINNET_PREPARE_LENGTH, MAINNET_REWARD_CYCLE_LENGTH, MarfProofInput, MarfProofResponse, NakamotoHeader, NodeRpcProofSource, NodeRpcSourceOptions, ProofSource, ProvenDiff, SIGNERS_CONTRACT, SecondlayerProofSource, SecondlayerSourceOptions, SignerCheck, SignerSet, SourceError, StacksHeader, StateFailure, StateFailureCode, StateWitness, StateWrite, VerifyCheckpoint, VerifyFailure, VerifyFailureCode, VerifyOptions, VerifyStep, VmEventRow, WitnessLeaf, blockId2 as blockId, classifyBlockDiff, cycleStart, dataVarKey, decodeSignerSet, ftBalanceKey, hex, isEpoch2Header, mapEntryKey, marfPath, marfProofAncestors, marfValue, parseEpoch2Header, parseNakamotoHeader, parseWitness, rewardCycle, signerSignatureHash, unhex, verifyBlock, verifyBlockState, verifyConsensusPreimage, verifyMarfProof, verifySignerSignatures };