@secondlayer/verify 0.0.0-stage → 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,664 @@
+type Bytes = Uint8Array;
+declare const hex: (b: Bytes) => string;
+/** Hex to bytes; tolerates a 0x prefix. */
+declare const unhex: (s: string) => Bytes;
+interface NakamotoHeader {
+	/** Low 7 bits = header version; high bit = shadow block. */
+	version: number;
+	chainLength: bigint;
+	burnSpent: bigint;
+	consensusHash: Bytes;
+	parentBlockId: Bytes;
+	txMerkleRoot: Bytes;
+	stateIndexRoot: Bytes;
+	timestamp: bigint;
+	minerSignature: Bytes;
+	/** 65-byte recoverable signatures: recovery id, r, s. */
+	signerSignatures: Bytes[];
+	/** Header bytes minus the signer_signature vec: the signer sighash preimage. */
+	signerSighashPreimage: Bytes;
+	/** Serialized header length; block bytes after this are the transactions. */
+	byteLength: number;
+}
+/**
+* Parse the NakamotoBlockHeader at the start of raw block bytes
+* (`/v3/blocks/<id>`). Handles v0 and v1 (v1 appends `problematic_txs`).
+*/
+declare function parseNakamotoHeader(raw: Bytes): NakamotoHeader;
+/**
+* NakamotoBlockHeader::signer_signature_hash: sha512/256 over every header field
+* except the signer signatures. Also the header's block_hash.
+*/
+declare const signerSignatureHash: (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. */
+declare function marfValue(value: string): Bytes;
+/**
+* Block ids of the ancestor tries a proof crosses: each one is the backptr a
+* descendant trie follows toward the leaf. `verifyMarfProof` needs every one's
+* header. 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.
+*/
+declare function marfProofAncestors(proof: Bytes): string[];
+interface MarfProofInput {
+	/** Consensus-serialized TrieMerkleProof (`/v2/clarity/marf/<path>?proof=1`). */
+	proof: Bytes;
+	/** Leaf path: `marfPath(key)`. */
+	path: Bytes;
+	/** 40-byte MARFValue: `marfValue(valueString)`. */
+	value: Bytes;
+	/** Tip state_index_root, from a header the caller authenticated. */
+	root: Bytes;
+	/**
+	* Tip header plus every ancestor header the proof crosses. Each contributes
+	* state_index_root -> recomputed block id, so ancestor roots are only ever
+	* vouched for by header bytes (a bare root->id map would let a forged
+	* ancestor trie through).
+	*/
+	headers: StacksHeader[];
+}
+/**
+* TrieMerkleProof::verify. True iff `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.
+*/
+declare function verifyMarfProof(input: MarfProofInput): boolean;
+interface WitnessLeaf {
+	/** Full 32-byte trie path: `marfPath(key)`. */
+	path: Bytes;
+	/** 32-byte value hash (first 32 bytes of the MARFValue; the tail is zero). */
+	valueHash: Bytes;
+}
+interface StateWitness {
+	/** Recomputed trie root; compare to the authenticated header's state_index_root. */
+	root: Bytes;
+	/** Skip-list ancestor trie roots folded into `root`. */
+	ancestorRoots: Bytes[];
+	leaves: WitnessLeaf[];
+	nodes: number;
+}
+/**
+* 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.
+*/
+declare function parseWitness(bytes: Bytes): StateWitness;
+interface BlockDiffInput {
+	/** `parseWitness(bytes).leaves`, from a witness whose root was checked. */
+	leaves: WitnessLeaf[];
+	/** Claimed writes of the block: [key, value string] as stored by Clarity. */
+	writes: [key: string, value: string][];
+	/** MARF bookkeeping keys (`__MARF_*`) with their raw 40-byte MARFValue hex, derived from the header chain. */
+	internal: [key: string, valueHex: string][];
+	/** Value at `pathHex` in the PARENT block's state (40-byte MARFValue hex), already proven by the caller. */
+	parentValue: (pathHex: string) => string | undefined;
+}
+interface ClassifiedLeaf extends WitnessLeaf {
+	key: string;
+}
+interface BlockDiff {
+	/** Leaves matching a claimed write (path and value). */
+	writes: ClassifiedLeaf[];
+	/** Unclaimed leaves holding the parent's value: copied forward, not written. */
+	carried: WitnessLeaf[];
+	/** Leaves matching a `__MARF_*` bookkeeping entry. */
+	internal: ClassifiedLeaf[];
+	/** Leaves nothing explains: an unreported write. Non-empty = reject. */
+	hidden: WitnessLeaf[];
+	/** Claimed write keys with no leaf holding the claimed value. Non-empty = reject. */
+	missing: string[];
+	/** No hidden leaves and no missing writes: the claimed writes are the block's complete diff. */
+	complete: boolean;
+}
+/**
+* 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.
+*/
+declare function classifyBlockDiff(input: BlockDiffInput): BlockDiff;
+/** Boot contract holding `cycle-signer-set`, one entry per reward cycle. */
+declare const SIGNERS_CONTRACT = "SP000000000000000000002Q6VF78.signers";
+/** Signer principal -> weight. */
+type SignerSet = Map<string, bigint>;
+/**
+* Decode the `.signers` `cycle-signer-set` map value (hex or bytes, as stored
+* in the MARF): `(some (list (tuple (signer principal) (weight uint) ...)))`.
+*/
+declare function decodeSignerSet(value: string | Bytes): SignerSet;
+interface SignerCheck {
+	/** Signed weight meets the threshold, and every signature is a distinct known signer. */
+	valid: boolean;
+	signedWeight: bigint;
+	totalWeight: bigint;
+	/** ceil(total * 7 / 10). */
+	threshold: bigint;
+	/** Recovered signer principals that counted, in signature order. */
+	signers: string[];
+	/** Recovered principals not in the set. */
+	unknown: string[];
+	/** Principals that signed more than once. */
+	duplicates: string[];
+	/** Signatures that do not recover (malformed or high-S). */
+	invalid: number;
+}
+/**
+* Recover each header signature's key over signer_signature_hash, map it to
+* its mainnet p2pkh principal, and sum weights from `set`. The set must be the
+* one for the reward cycle of the tenure-electing burn block.
+*/
+declare function verifySignerSignatures(header: NakamotoHeader, set: SignerSet): SignerCheck;
+/**
+* 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.
+*/
+declare function verifyConsensusPreimage(consensusHash: Bytes, preimage: Bytes): string | null;
+/** Mainnet PoX parameters (first_burnchain_block_height, reward_cycle_length). */
+declare const MAINNET_FIRST_BURN_HEIGHT = 666050;
+declare const MAINNET_REWARD_CYCLE_LENGTH = 2100;
+/** Mainnet prepare phase: the last 100 burn blocks of a cycle pick the next cycle's signers. */
+declare const MAINNET_PREPARE_LENGTH = 100;
+/** First burn height of reward cycle `cycle`. */
+declare const cycleStart: (cycle: number, firstBurnHeight?: number, cycleLength?: number) => number;
+/** Reward cycle containing `burnHeight`. */
+declare function rewardCycle(burnHeight: number, firstBurnHeight?: number, cycleLength?: number): number;
+import { ClarityValue } from "@secondlayer/stacks/clarity";
+/** `vm::<contract>::0::<map>::<serialized key hex>` (make_key_for_data_map_entry). */
+declare function mapEntryKey(contractId: string, mapName: string, key: ClarityValue): string;
+/** `vm::<contract>::1::<var>` (make_key_for_trip, StoreType::Variable). */
+declare function dataVarKey(contractId: string, varName: string): string;
+/**
+* `vm::<contract>::2::<token>::<principal json>` (get_ft_balance). The holder
+* is serde-JSON PrincipalData, e.g. `{"Standard":[22,[...20 bytes]]}`.
+*/
+declare function ftBalanceKey(contractId: string, tokenName: string, holder: string): string;
+interface BlockHeader {
+	/** Signed 32-bit version field. */
+	version: number;
+	/** Display-order hex of the previous block hash. */
+	prevHash: string;
+	/** Display-order hex of the merkle root. */
+	merkleRoot: string;
+	/** Unix timestamp, seconds. */
+	time: number;
+	/** Compact-encoded target. */
+	bits: number;
+	nonce: number;
+}
+type HeaderRule = "checkpoint" | "format" | "prev-link" | "bits" | "retarget" | "median-time-past" | "version" | "proof-of-work";
+declare class HeaderValidationError extends Error {
+	readonly height: number;
+	readonly rule: HeaderRule;
+	readonly name = "HeaderValidationError";
+	constructor(height: number, rule: HeaderRule, detail: string);
+}
+interface Checkpoint {
+	height: number;
+	/** Raw 80-byte header, bytes or hex. Trusted without validation. */
+	header: Uint8Array | string;
+	/**
+	* Timestamp of the first block of the checkpoint's difficulty period
+	* (height − height % 2016). Required when the checkpoint is not itself a
+	* period start; needed to verify the next retarget.
+	*/
+	periodStartTime?: number;
+}
+interface ChainEntry {
+	height: number;
+	/** Display-order hex. */
+	hash: string;
+	header: BlockHeader;
+	raw: Uint8Array;
+}
+declare class HeaderChain {
+	private readonly base;
+	private readonly periodStartTime;
+	private readonly entries;
+	private readonly heights;
+	private work;
+	private constructor();
+	static fromCheckpoint(checkpoint: Checkpoint): HeaderChain;
+	get tip(): ChainEntry;
+	/** Work summed from the checkpoint (inclusive) to the tip; not chainwork since genesis. */
+	get totalWork(): bigint;
+	get checkpointHeight(): number;
+	/** Height of a header in this chain by display-order hash, or undefined. */
+	heightOf(hashHex: string): number | undefined;
+	headerAt(height: number): ChainEntry | undefined;
+	/**
+	* 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.
+	*/
+	append(headers: Iterable<Uint8Array | string>): void;
+	private validate;
+	private expectedBits;
+	/**
+	* Median of the last 11 timestamps. Right after the checkpoint fewer are
+	* known; like Core near genesis, the median of what is available is used.
+	*/
+	private medianTimePast;
+	private push;
+}
+interface VerifyCheckpoint {
+	stacks: {
+		/** Raw Nakamoto header (hex) of a trusted block whose state holds `signerSet`. */
+		header: string
+		/** Reward cycle `signerSet` belongs to. */
+		cycle: number
+		/** `.signers` `cycle-signer-set[cycle]` as stored: hex of `(some (list ...))`. */
+		signerSet: string
+	};
+	/** Retarget-boundary Bitcoin header at or below the first burn block of `stacks.cycle`. */
+	bitcoin: Checkpoint;
+}
+/**
+* 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). 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. */
+interface BurnPreimage {
+	preimage: Bytes;
+	/** The source's claimed burn height: a hint for how far to sync Bitcoin headers, never trusted. */
+	burnHeight: number;
+}
+/** Node RPC `/v2/clarity/marf/<path>?proof=1` answer. */
+interface MarfProofResponse {
+	/** Value string as Clarity stored it (hex for Clarity values), 0x prefix tolerated. */
+	data: string;
+	/** Consensus-serialized TrieMerkleProof. */
+	proof: Bytes;
+}
+/** One storage-layer MARF write (`state_writes` row), in block write order. */
+interface StateWrite {
+	/** Null for block-level writes outside any transaction. */
+	tx_index: number | null;
+	ordinal: number;
+	/** Full MARF key, e.g. `vm::<contract>::0::<map>::<key hex>`. */
+	key: string;
+	/** Hex of the stored value string's UTF-8 bytes. */
+	value_hex: string;
+}
+/** A `vm_events` write row, as the Index API serves it. */
+interface VmEventRow {
+	event_type: "var_set" | "map_set" | "map_insert" | "map_delete";
+	/** The row's ordinal within the block. */
+	event_index: number;
+	tx_id?: string;
+	tx_index?: number;
+	contract_id: string;
+	var_name?: string | null;
+	map?: string | null;
+	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>;
+	/**
+	* 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>;
+	getBurnPreimage(consensusHash: string): Promise<BurnPreimage>;
+	/** Raw 80-byte Bitcoin headers (hex or bytes) from height `from`. */
+	getBitcoinHeaders(from: number, count: number): Promise<(string | Bytes)[]>;
+	/** Every MARF write of the block; null when the source has none for it. */
+	getStateWrites?(height: number): Promise<StateWrite[] | null>;
+	/** Indexed vm_events write rows of the block, checked against its proven diff. */
+	getVmEvents?(height: number): Promise<VmEventRow[]>;
+}
+declare class SourceError extends Error {
+	readonly url: string;
+	readonly status: number | null;
+	readonly name = "SourceError";
+	constructor(url: string, status: number | null, detail: string);
+}
+type Fetch = (url: string, init?: RequestInit) => Promise<Response>;
+interface SecondlayerSourceOptions {
+	/** API origin, e.g. `https://api.secondlayer.tools`. */
+	baseUrl: string;
+	/** Account key, sent as `Authorization: Bearer`. */
+	apiKey: string;
+	fetch?: Fetch;
+}
+/**
+* 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>;
+	getBitcoinHeaders: (from: number, count: number) => Promise<string[]>;
+	getStateWrites: (height: number) => Promise<StateWrite[] | null>;
+	getVmEvents: (height: number) => Promise<VmEventRow[]>;
+	constructor(opts: SecondlayerSourceOptions);
+}
+interface NodeRpcSourceOptions {
+	/** Stacks node RPC origin, e.g. `http://localhost:20443`. */
+	nodeUrl: string;
+	fetch?: Fetch;
+}
+/**
+* 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" | "getEpoch2Header" | "getMarfProof"> {
+	getBlock: (ref: string | number) => Promise<Bytes>;
+	getEpoch2Header: (blockId: string) => Promise<Epoch2HeaderResponse>;
+	getMarfProof: (pathHex: string, tipId: string) => Promise<MarfProofResponse | null>;
+	constructor(opts: NodeRpcSourceOptions);
+}
+interface DiffWrite {
+	/** MARF key, when a state_writes row names the leaf. */
+	key?: string;
+	/** Leaf path, hex. */
+	path: string;
+	/** sha512/256 of the stored value string, hex. */
+	valueHash: string;
+	/** Transaction of the last write; null for block-level writes. */
+	txIndex?: number | null;
+	/** False when the source had no state_writes: the leaf may also be a carried copy. */
+	named: boolean;
+}
+interface DiffLeaf {
+	key?: string;
+	path: string;
+	valueHash: string;
+}
+interface ProvenDiff {
+	/** Every leaf is named (state_writes served) and classified. */
+	named: boolean;
+	writes: DiffWrite[];
+	/** Unchanged values copied forward from the parent (proven at the parent). */
+	carried: DiffLeaf[];
+	/** `__MARF_BLOCK_*` bookkeeping. */
+	internal: DiffLeaf[];
+}
+type StateFailureCode = "malformed" | "root-mismatch" | "bad-write" | "hidden-write" | "missing-write" | "key-not-written" | "value-mismatch" | "bad-row";
+interface StateFailure {
+	step: "witness" | "names" | "rows";
+	code: StateFailureCode;
+	message: string;
+	key?: string;
+	path?: string;
+	ordinal?: number;
+}
+interface BlockStateInput {
+	/** MARF height of the block (its Stacks chain length). */
+	height: number;
+	/** Parent block id from the authenticated header. */
+	parentBlockId: Bytes;
+	/** state_index_root from the authenticated header. */
+	stateRoot: Bytes;
+	witness: Bytes;
+	/** The block's state_writes; null when the source has none (names unavailable). */
+	writes: StateWrite[] | null;
+	/** Indexed rows to prove against the diff. */
+	rows?: VmEventRow[];
+	/**
+	* Leaves of the parent's own trie, from a parent witness whose root the
+	* caller checked against the parent header: each is the parent state's
+	* value at its path. Resolves carried leaves without a proof per leaf.
+	*/
+	parentLeaves?: WitnessLeaf[];
+	/**
+	* True iff the leaf's value is stored at its path in the parent's state
+	* (proven by the caller). Asked only with state_writes, for leaves the
+	* parent's own trie does not explain.
+	*/
+	parentHolds?: (leaf: WitnessLeaf) => Promise<boolean>;
+}
+interface BlockStateResult {
+	diff?: ProvenDiff;
+	rowsChecked: number;
+	notes: string[];
+	failures: StateFailure[];
+}
+/**
+* Verify block 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
+* (every leaf is in the block): carried leaves are told apart only through
+* `parentLeaves`, and the remaining writes come back unnamed.
+*/
+declare function verifyBlockState(input: BlockStateInput): Promise<BlockStateResult>;
+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;
+	message: string;
+	/** Reward cycle being proven (signer-set step). */
+	cycle?: number;
+	/** Block the failure is about, when not the target. */
+	blockId?: string;
+	key?: string;
+	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. 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. */
+	bitcoinBlockHash?: string;
+	signerWeight?: bigint;
+	totalWeight?: bigint;
+	threshold?: bigint;
+	diff?: ProvenDiff;
+	/** vm_events rows proven against the diff. */
+	rowsChecked?: number;
+	notes: string[];
+	/** Empty when ok. The first entry is the first broken link. */
+	failures: VerifyFailure[];
+}
+interface VerifyOptions {
+	source: ProofSource;
+	/** Defaults to MAINNET_CHECKPOINT. */
+	checkpoint?: VerifyCheckpoint;
+	/**
+	* Also name the block's writes and prove its indexed rows: reads the
+	* source's `getStateWrites` and `getVmEvents`, which bill as Index rows on
+	* the Secondlayer API. Off by default, so verification reads proofs only.
+	*/
+	rows?: boolean;
+}
+/**
+* Verifies blocks from one checkpoint against one source, caching the Bitcoin
+* header chain, proven signer sets and fetched headers across calls.
+*/
+declare class BlockVerifier {
+	private readonly source;
+	private readonly checkpoint;
+	private readonly rows;
+	private readonly chain;
+	/** Proven signer sets by cycle. */
+	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;
+	private readonly start;
+	constructor(opts: VerifyOptions);
+	/** Verify one block by id (hex) or height. Never throws for bad source data. */
+	verify(ref: string | number): Promise<BlockVerification>;
+	private run;
+	/** 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.
+	*/
+	private proveAt;
+	/**
+	* The parent's own trie leaves, from its witness checked against the
+	* parent header. Optional evidence: when the source cannot serve it,
+	* carried leaves fall back to per-leaf proofs (named) or stay unlabeled.
+	*/
+	private parentLeaves;
+	/**
+	* A carried leaf holds the parent's value. The parent header is
+	* 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. */
+	private bindBurn;
+	/** Extend the Bitcoin chain to `height`, validating PoW, retarget and MTP. */
+	private syncBitcoin;
+	/**
+	* The proven signer set for `cycle`. Walks forward from the checkpoint:
+	* set c+1 is read from an anchor block in c+1's prepare phase, whose
+	* header set c signed.
+	*/
+	private signerSet;
+	/** The checkpoint block as a search bound; its burn height is a source hint. */
+	private startPoint;
+	private burnHint;
+	private preimage;
+	private locateAnchor;
+	/**
+	* Set `cycle` from `anchor`: the anchor must be bound to a burn block in
+	* `cycle`'s prepare phase, be signed by the set of the cycle that burn
+	* height dictates (`cycle - 1`), and hold set `cycle` in its state (MARF
+	* proof). Adjacent sets overlap enough that one block can clear both, so
+	* the set is always chosen by proven burn height, never by which passes.
+	*/
+	private proveNextSet;
+}
+/** One-shot: verify a block from a checkpoint (MAINNET_CHECKPOINT by default). */
+declare const verifyBlock: (ref: string | number, opts: VerifyOptions) => Promise<BlockVerification>;
+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 };