@secondlayer/verify 0.5.2 → 0.5.3

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 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;
@@ -26,8 +27,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;
 /**
@@ -55,28 +58,32 @@ interface Epoch2Header {
 }
 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[];
 interface MarfProofInput {
@@ -97,9 +104,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 {
@@ -159,8 +168,10 @@ 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;
 interface SignerCheck {
@@ -180,9 +191,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 +206,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 +215,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 {
@@ -224,6 +239,11 @@ interface BlockHeader {
 	nonce: number;
 }
 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;
@@ -248,6 +268,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 +276,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 +284,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
@@ -366,6 +389,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;
@@ -386,21 +415,39 @@ 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);
 }
@@ -410,13 +457,21 @@ interface NodeRpcSourceOptions {
 	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);
 }
@@ -489,11 +544,12 @@ 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>;
@@ -504,20 +560,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.
 */
@@ -606,8 +667,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;
@@ -749,9 +812,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