@secondlayer/verify 0.5.2 → 0.5.4

package/dist/index.d.ts

@@ -1,7 +1,10 @@
+/** A byte string, held as a Uint8Array. */
 type Bytes = Uint8Array;
+/** Encodes bytes as a lowercase hex string. */
 declare const hex: (b: Bytes) => string;
 /** Hex to bytes; tolerates a 0x prefix. */
 declare const unhex: (s: string) => Bytes;
+/** A Nakamoto-era Stacks block header. */
 interface NakamotoHeader {
 	/** Low 7 bits = header version; high bit = shadow block. */
 	version: number;
@@ -26,8 +29,10 @@ interface NakamotoHeader {
 */
 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.
+* 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`.
 */
 declare const signerSignatureHash: (h: NakamotoHeader) => Bytes;
 /**
@@ -53,32 +58,38 @@ interface Epoch2Header {
 	blockHash: Bytes;
 	consensusHash: Bytes;
 }
+/** A Stacks block header from either era. */
 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.
+* 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.
 */
 declare function parseEpoch2Header(raw: Bytes, consensusHash: Bytes): Epoch2Header;
+/** Narrows a Stacks header to an epoch 2.x header. */
 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.
+* 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.
 */
 declare const blockId2: (h: StacksHeader) => Bytes;
-/** TrieHash::from_key: sha512/256(utf8(key)). */
+/** Hashes a key to its MARF path: sha512/256 of the UTF-8 key. */
 declare const marfPath: (key: string) => Bytes;
-/** MARFValue::from_value: sha512/256(utf8(value)) padded to 40 bytes. */
+/** Hashes a value to its MARF value: sha512/256, 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.
+* 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.
 */
 declare function marfProofAncestors(proof: Bytes): string[];
+/** A MARF proof with the leaf path and value it covers. */
 interface MarfProofInput {
 	/** Consensus-serialized TrieMerkleProof (`/v2/clarity/marf/<path>?proof=1`). */
 	proof: Bytes;
@@ -97,9 +108,11 @@ interface MarfProofInput {
 	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.
+* 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.
 */
 declare function verifyMarfProof(input: MarfProofInput): boolean;
 interface WitnessLeaf {
@@ -108,6 +121,7 @@ interface WitnessLeaf {
 	/** 32-byte value hash (first 32 bytes of the MARFValue; the tail is zero). */
 	valueHash: Bytes;
 }
+/** A recomputed trie root, its ancestor roots, and leaves. */
 interface StateWitness {
 	/** Recomputed trie root; compare to the authenticated header's state_index_root. */
 	root: Bytes;
@@ -121,6 +135,7 @@ interface StateWitness {
 * The result proves nothing until `root` equals a header's state_index_root.
 */
 declare function parseWitness(bytes: Bytes): StateWitness;
+/** The witness leaves, claimed writes, and bookkeeping keys to classify. */
 interface BlockDiffInput {
 	/** `parseWitness(bytes).leaves`, from a witness whose root was checked. */
 	leaves: WitnessLeaf[];
@@ -134,6 +149,7 @@ interface BlockDiffInput {
 interface ClassifiedLeaf extends WitnessLeaf {
 	key: string;
 }
+/** A block's witnessed leaves, split into writes, carried, and internal. */
 interface BlockDiff {
 	/** Leaves matching a claimed write (path and value). */
 	writes: ClassifiedLeaf[];
@@ -159,10 +175,13 @@ 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) ...)))`.
+* 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) ...)))`.
 */
 declare function decodeSignerSet(value: string | Bytes): SignerSet;
+/** Whether the signed weight meets the threshold with known signers. */
 interface SignerCheck {
 	/** Signed weight meets the threshold, and every signature is a distinct known signer. */
 	valid: boolean;
@@ -180,9 +199,11 @@ interface SignerCheck {
 	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.
+* 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.
 */
 declare function verifySignerSignatures(header: NakamotoHeader, set: SignerSet): SignerCheck;
 /**
@@ -193,6 +214,7 @@ declare function verifySignerSignatures(header: NakamotoHeader, set: SignerSet):
 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;
+/** Burn blocks in a mainnet reward cycle. */
 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;
@@ -201,13 +223,14 @@ declare const cycleStart: (cycle: number, firstBurnHeight?: number, cycleLength?
 /** 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). */
+/** The MARF key of a map entry: `vm::<contract>::0::<map>::<serialized key hex>`. */
 declare function mapEntryKey(contractId: string, mapName: string, key: ClarityValue): string;
-/** `vm::<contract>::1::<var>` (make_key_for_trip, StoreType::Variable). */
+/** The MARF key of a data variable: `vm::<contract>::1::<var>`. */
 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]]}`.
+* 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]]}`.
 */
 declare function ftBalanceKey(contractId: string, tokenName: string, holder: string): string;
 interface BlockHeader {
@@ -223,13 +246,20 @@ interface BlockHeader {
 	bits: number;
 	nonce: number;
 }
+/** A Bitcoin header rule a chain check can fail on. */
 type HeaderRule = "checkpoint" | "format" | "prev-link" | "bits" | "retarget" | "median-time-past" | "version" | "proof-of-work";
+/**
+* Thrown when a Bitcoin header fails a validation rule.
+*
+* `rule` names the rule and `height` the header that failed it.
+*/
 declare class HeaderValidationError extends Error {
 	readonly height: number;
 	readonly rule: HeaderRule;
 	readonly name = "HeaderValidationError";
 	constructor(height: number, rule: HeaderRule, detail: string);
 }
+/** A trusted Bitcoin header that anchors header validation. */
 interface Checkpoint {
 	height: number;
 	/** Raw 80-byte header, bytes or hex. Trusted without validation. */
@@ -241,6 +271,7 @@ interface Checkpoint {
 	*/
 	periodStartTime?: number;
 }
+/** A Bitcoin header with its height, hash, and raw bytes. */
 interface ChainEntry {
 	height: number;
 	/** Display-order hex. */
@@ -248,6 +279,7 @@ interface ChainEntry {
 	header: BlockHeader;
 	raw: Uint8Array;
 }
+/** A validated chain of Bitcoin headers, grown forward from a checkpoint. */
 declare class HeaderChain {
 	private readonly base;
 	private readonly periodStartTime;
@@ -255,6 +287,7 @@ declare class HeaderChain {
 	private readonly heights;
 	private work;
 	private constructor();
+	/** Starts a header chain at a checkpoint. */
 	static fromCheckpoint(checkpoint: Checkpoint): HeaderChain;
 	get tip(): ChainEntry;
 	/** Work summed from the checkpoint (inclusive) to the tip; not chainwork since genesis. */
@@ -262,6 +295,7 @@ declare class HeaderChain {
 	get checkpointHeight(): number;
 	/** Height of a header in this chain by display-order hash, or undefined. */
 	heightOf(hashHex: string): number | undefined;
+	/** The header entry at a height, if the chain has one. */
 	headerAt(height: number): ChainEntry | undefined;
 	/**
 	* Validates and appends headers in order. All-or-nothing: if any header
@@ -284,6 +318,7 @@ declare class HeaderChain {
 * (burn height 967,680 or later); earlier ones by hash chain from 9,055,251.
 */
 declare const MAINNET_CHECKPOINT: VerifyCheckpoint;
+/** A trusted Stacks header and signer set to start verification from. */
 interface VerifyCheckpoint {
 	stacks: {
 		/** Raw Nakamoto header (hex) of a trusted block whose state holds `signerSet`. */
@@ -332,7 +367,7 @@ 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. */
+/** An epoch 2.x header and the consensus hash it commits to. */
 interface Epoch2HeaderResponse {
 	/** Consensus-serialized StacksBlockHeader. */
 	header: Bytes;
@@ -366,6 +401,12 @@ interface ProofSource {
 	/** Indexed vm_events write rows of the block, checked against its proven diff. */
 	getVmEvents?(height: number): Promise<VmEventRow[]>;
 }
+/**
+* Thrown when a proof source request fails.
+*
+* It carries the request `url`, the HTTP `status` (null when there was none)
+* and the detail.
+*/
 declare class SourceError extends Error {
 	readonly url: string;
 	readonly status: number | null;
@@ -375,6 +416,7 @@ declare class SourceError extends Error {
 type Fetch = (url: string, init?: RequestInit) => Promise<Response>;
 /** The hosted API. */
 declare const DEFAULT_API_URL = "https://api.secondlayer.tools";
+/** Options for reading proofs from the Secondlayer API. */
 interface SecondlayerSourceOptions {
 	/** API origin. Defaults to {@link DEFAULT_API_URL}. */
 	baseUrl?: string;
@@ -386,37 +428,64 @@ interface SecondlayerSourceOptions {
 	fetch?: Fetch;
 }
 /**
-* Every proof input from the Secondlayer API: `/v1/proofs/*` (free, rate
-* limited) for blocks, epoch 2.x headers, MARF proofs, witnesses, burn
-* preimages, Bitcoin headers and each block's state writes; the Index API
-* (metered rows) for vm_events, read only when verifyBlock gets `rows: true`.
-* Methods are own properties, so a partial source spreads over it:
+* 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) }`.
 */
 declare class SecondlayerProofSource implements ProofSource {
+	/** Raw block bytes, header first, by block id or height. */
 	getBlock: (ref: string | number) => Promise<Bytes>;
+	/** An epoch 2.x header and its consensus hash, by index block hash. */
 	getEpoch2Header: (blockId: string) => Promise<Epoch2HeaderResponse>;
+	/**
+	* A MARF inclusion proof for a path at a tip.
+	*
+	* It is null when the key is absent.
+	*/
 	getMarfProof: (pathHex: string, tipId: string) => Promise<MarfProofResponse | null>;
+	/** The state witness for a block. */
 	getWitness: (blockId: string) => Promise<Bytes>;
+	/** The burn preimage behind a consensus hash. */
 	getBurnPreimage: (consensusHash: string) => Promise<BurnPreimage>;
+	/** Raw 80-byte Bitcoin headers, `count` of them from height `from`. */
 	getBitcoinHeaders: (from: number, count: number) => Promise<string[]>;
+	/**
+	* Every MARF write of a block, in ordinal order.
+	*
+	* It is null when there are none.
+	*/
 	getStateWrites: (height: number) => Promise<StateWrite[] | null>;
+	/** The indexed `vm_events` write rows of a block, from the Index API. */
 	getVmEvents: (height: number) => Promise<VmEventRow[]>;
 	constructor(opts?: SecondlayerSourceOptions);
 }
+/** Options for reading proofs from a Stacks node. */
 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.
+* 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.
 */
 declare class NodeRpcProofSource implements Pick<ProofSource, "getBlock" | "getEpoch2Header" | "getMarfProof"> {
+	/** Raw block bytes, header first, by block id or height. */
 	getBlock: (ref: string | number) => Promise<Bytes>;
+	/** An epoch 2.x header and its consensus hash, by index block hash. */
 	getEpoch2Header: (blockId: string) => Promise<Epoch2HeaderResponse>;
+	/**
+	* A MARF inclusion proof for a path at a tip.
+	*
+	* It is null when the key is absent.
+	*/
 	getMarfProof: (pathHex: string, tipId: string) => Promise<MarfProofResponse | null>;
 	constructor(opts: NodeRpcSourceOptions);
 }
@@ -457,6 +526,7 @@ interface StateFailure {
 	path?: string;
 	ordinal?: number;
 }
+/** A block's height, parent, and state root to check rows against. */
 interface BlockStateInput {
 	/** MARF height of the block (its Stacks chain length). */
 	height: number;
@@ -482,6 +552,7 @@ interface BlockStateInput {
 	*/
 	parentHolds?: (leaf: WitnessLeaf) => Promise<boolean>;
 }
+/** The proven diff, rows checked, notes, and failures. */
 interface BlockStateResult {
 	diff?: ProvenDiff;
 	rowsChecked: number;
@@ -489,14 +560,16 @@ interface BlockStateResult {
 	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
+* 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.
 */
 declare function verifyBlockState(input: BlockStateInput): Promise<BlockStateResult>;
+/** A transaction's id and its consensus-serialized bytes. */
 interface BlockTransaction {
 	/** sha512/256 of the transaction bytes, hex. */
 	txid: string;
@@ -504,20 +577,25 @@ interface BlockTransaction {
 	raw: Bytes;
 }
 /**
-* tx_merkle_root over txids: leaf = H(0x00 ‖ txid), node = H(0x01 ‖ l ‖ r),
-* an odd level duplicates its last node, and a lone leaf is still paired with
-* itself (one-tx blocks hash H(0x01 ‖ leaf ‖ leaf)).
+* 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).
 */
 declare function txMerkleRoot2(txids: Bytes[]): Bytes;
+/** Thrown for a malformed block body or a transaction root mismatch. */
 declare class TransactionsError extends Error {
 	readonly code: "malformed" | "tx-root-mismatch";
 	constructor(code: "malformed" | "tx-root-mismatch", message: string);
 }
 /**
-* The block's transactions, each hashed to its txid, checked against the
-* header's tx_merkle_root. The body after `header.byteLength` is a u32 count
-* then the transactions back to back. Null when the bytes are the header
-* alone (a source that serves headers only): nothing to check. Throws
+* 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
 * {@link TransactionsError} on a malformed body, trailing bytes or a root
 * mismatch.
 */
@@ -548,6 +626,7 @@ interface Ancestry {
 	*/
 	via: "parents" | "marf";
 }
+/** The result of verifying a block, step by step. */
 interface BlockVerification {
 	/**
 	* Every step passed. At or above the checkpoint: header, burn binding,
@@ -588,6 +667,7 @@ interface BlockVerification {
 	/** Empty when ok. The first entry is the first broken link. */
 	failures: VerifyFailure[];
 }
+/** The proof source, checkpoint, and row checking for a block verify. */
 interface VerifyOptions {
 	source: ProofSource;
 	/** Defaults to MAINNET_CHECKPOINT. */
@@ -606,8 +686,10 @@ interface VerifyOptions {
 	onStep?: (step: VerifyStep) => void;
 }
 /**
-* Verifies blocks from one checkpoint against one source, caching the Bitcoin
-* header chain, proven signer sets and fetched headers across calls.
+* Verifies blocks from one checkpoint against one source.
+*
+* It caches the Bitcoin header chain, proven signer sets and fetched headers
+* across calls.
 */
 declare class BlockVerifier {
 	private readonly source;
@@ -736,6 +818,7 @@ 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>;
 type LinkStatus = "ok" | "failed" | "skipped";
+/** One verification step with its status and what it proved. */
 interface LinkLine {
 	step: VerifyStep;
 	label: string;
@@ -749,9 +832,11 @@ declare const LINKS: readonly {
 	label: string
 }[];
 /**
-* One line per link, then the verdict: the human view of a verification,
-* shared by the CLI and the browser checker. Ancestry appears only below the
-* checkpoint. `rows` says whether the caller asked for the rows link.
+* 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.
 */
 declare function describeLinks(r: BlockVerification, cp: VerifyCheckpoint, opts?: {
 	rows?: boolean