@secondlayer/shared 6.22.0 → 6.24.0

package/dist/src/node/consensus.d.ts

@@ -0,0 +1,38 @@
+/** Mainnet PoX schedule (from /v2/pox) — overridable for other networks. */
+declare const MAINNET_FIRST_BURN_HEIGHT = 666050;
+declare const MAINNET_REWARD_CYCLE_LENGTH = 2100;
+interface RewardSetSigner {
+	/** 33-byte compressed secp256k1 public key (hex, no 0x). */
+	signing_key: string;
+	weight: number;
+}
+interface RewardSet {
+	signers: RewardSetSigner[];
+	total_weight: number;
+}
+interface SignerVerification {
+	/** Summed weight of distinct reward-set signers that signed the block. */
+	signedWeight: number;
+	totalWeight: number;
+	/** floor(total_weight * 7 / 10). */
+	threshold: number;
+	thresholdMet: boolean;
+	/** Count of distinct reward-set keys that signed. */
+	matchedSigners: number;
+}
+/** Reward cycle for a burn block height. Defaults to the mainnet PoX schedule. */
+declare function rewardCycle(burnBlockHeight: number, opts?: {
+	firstBurnHeight?: number
+	cycleLength?: number
+}): number;
+/** Recover the signer pubkey (compressed hex) from a 65-byte VRS recoverable
+*  ECDSA signature over the block_hash. */
+declare function recoverSignerKey(blockHashHex: string, vrsSignatureHex: string): string;
+/**
+* Recover each header signer signature, match it to the reward set, and sum the
+* distinct matched signers' weights against the 70% threshold. A signature that
+* fails to recover or whose key isn't in the set simply doesn't count — never
+* a false positive.
+*/
+declare function verifySignerSignatures(blockHashHex: string, signerSignaturesHex: string[], rewardSet: RewardSet): SignerVerification;
+export { verifySignerSignatures, rewardCycle, recoverSignerKey, SignerVerification, RewardSetSigner, RewardSet, MAINNET_REWARD_CYCLE_LENGTH, MAINNET_FIRST_BURN_HEIGHT };

package/dist/src/node/consensus.js

@@ -0,0 +1,67 @@
+import { createRequire } from "node:module";
+var __defProp = Object.defineProperty;
+var __returnValue = (v) => v;
+function __exportSetter(name, newValue) {
+  this[name] = __returnValue.bind(null, newValue);
+}
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: __exportSetter.bind(all, name)
+    });
+};
+
+// src/node/consensus.ts
+import { recoverPublicKey } from "@secondlayer/stacks/utils";
+var strip = (h) => h.startsWith("0x") ? h.slice(2) : h;
+var MAINNET_FIRST_BURN_HEIGHT = 666050;
+var MAINNET_REWARD_CYCLE_LENGTH = 2100;
+function rewardCycle(burnBlockHeight, opts = {}) {
+  const first = opts.firstBurnHeight ?? MAINNET_FIRST_BURN_HEIGHT;
+  const length = opts.cycleLength ?? MAINNET_REWARD_CYCLE_LENGTH;
+  return Math.floor((burnBlockHeight - first) / length);
+}
+function recoverSignerKey(blockHashHex, vrsSignatureHex) {
+  return strip(recoverPublicKey(strip(blockHashHex), strip(vrsSignatureHex), true));
+}
+function verifySignerSignatures(blockHashHex, signerSignaturesHex, rewardSet) {
+  const byKey = new Map(rewardSet.signers.map((s) => [strip(s.signing_key), s.weight]));
+  const seen = new Set;
+  let signedWeight = 0;
+  let matchedSigners = 0;
+  for (const sig of signerSignaturesHex) {
+    let pubkey;
+    try {
+      pubkey = recoverSignerKey(blockHashHex, sig);
+    } catch {
+      continue;
+    }
+    const weight = byKey.get(pubkey);
+    if (weight !== undefined && !seen.has(pubkey)) {
+      seen.add(pubkey);
+      signedWeight += weight;
+      matchedSigners += 1;
+    }
+  }
+  const threshold = Math.floor(rewardSet.total_weight * 7 / 10);
+  return {
+    signedWeight,
+    totalWeight: rewardSet.total_weight,
+    threshold,
+    thresholdMet: signedWeight >= threshold,
+    matchedSigners
+  };
+}
+export {
+  verifySignerSignatures,
+  rewardCycle,
+  recoverSignerKey,
+  MAINNET_REWARD_CYCLE_LENGTH,
+  MAINNET_FIRST_BURN_HEIGHT
+};
+
+//# debugId=1937481E7D2EF9AA64756E2164756E21
+//# sourceMappingURL=consensus.js.map

package/dist/src/node/consensus.js.map

@@ -0,0 +1,10 @@
+{
+  "version": 3,
+  "sources": ["../src/node/consensus.ts"],
+  "sourcesContent": [
+    "import { recoverPublicKey } from \"@secondlayer/stacks/utils\";\n\n/**\n * Consensus verification: do ≥70% of a reward cycle's signer weight attest to a\n * Nakamoto block? Each header `signer_signature` is a recoverable ECDSA over the\n * block_hash; recover the pubkey, match it to the cycle's reward set, and sum the\n * matched signers' weights. Verified bit-exact against mainnet 3.4.0.0.3 (see\n * docs/design/trustless-verification-proofs.md, signer-signature appendix).\n */\nconst strip = (h: string): string => (h.startsWith(\"0x\") ? h.slice(2) : h);\n\n/** Mainnet PoX schedule (from /v2/pox) — overridable for other networks. */\nexport const MAINNET_FIRST_BURN_HEIGHT = 666_050;\nexport const MAINNET_REWARD_CYCLE_LENGTH = 2100;\n\nexport interface RewardSetSigner {\n\t/** 33-byte compressed secp256k1 public key (hex, no 0x). */\n\tsigning_key: string;\n\tweight: number;\n}\n\nexport interface RewardSet {\n\tsigners: RewardSetSigner[];\n\ttotal_weight: number;\n}\n\nexport interface SignerVerification {\n\t/** Summed weight of distinct reward-set signers that signed the block. */\n\tsignedWeight: number;\n\ttotalWeight: number;\n\t/** floor(total_weight * 7 / 10). */\n\tthreshold: number;\n\tthresholdMet: boolean;\n\t/** Count of distinct reward-set keys that signed. */\n\tmatchedSigners: number;\n}\n\n/** Reward cycle for a burn block height. Defaults to the mainnet PoX schedule. */\nexport function rewardCycle(\n\tburnBlockHeight: number,\n\topts: { firstBurnHeight?: number; cycleLength?: number } = {},\n): number {\n\tconst first = opts.firstBurnHeight ?? MAINNET_FIRST_BURN_HEIGHT;\n\tconst length = opts.cycleLength ?? MAINNET_REWARD_CYCLE_LENGTH;\n\treturn Math.floor((burnBlockHeight - first) / length);\n}\n\n/** Recover the signer pubkey (compressed hex) from a 65-byte VRS recoverable\n *  ECDSA signature over the block_hash. */\nexport function recoverSignerKey(\n\tblockHashHex: string,\n\tvrsSignatureHex: string,\n): string {\n\treturn strip(\n\t\trecoverPublicKey(strip(blockHashHex), strip(vrsSignatureHex), true),\n\t);\n}\n\n/**\n * Recover each header signer signature, match it to the reward set, and sum the\n * distinct matched signers' weights against the 70% threshold. A signature that\n * fails to recover or whose key isn't in the set simply doesn't count — never\n * a false positive.\n */\nexport function verifySignerSignatures(\n\tblockHashHex: string,\n\tsignerSignaturesHex: string[],\n\trewardSet: RewardSet,\n): SignerVerification {\n\tconst byKey = new Map<string, number>(\n\t\trewardSet.signers.map((s) => [strip(s.signing_key), s.weight]),\n\t);\n\tconst seen = new Set<string>();\n\tlet signedWeight = 0;\n\tlet matchedSigners = 0;\n\tfor (const sig of signerSignaturesHex) {\n\t\tlet pubkey: string;\n\t\ttry {\n\t\t\tpubkey = recoverSignerKey(blockHashHex, sig);\n\t\t} catch {\n\t\t\tcontinue; // malformed signature → no credit\n\t\t}\n\t\tconst weight = byKey.get(pubkey);\n\t\tif (weight !== undefined && !seen.has(pubkey)) {\n\t\t\tseen.add(pubkey);\n\t\t\tsignedWeight += weight;\n\t\t\tmatchedSigners += 1;\n\t\t}\n\t}\n\tconst threshold = Math.floor((rewardSet.total_weight * 7) / 10);\n\treturn {\n\t\tsignedWeight,\n\t\ttotalWeight: rewardSet.total_weight,\n\t\tthreshold,\n\t\tthresholdMet: signedWeight >= threshold,\n\t\tmatchedSigners,\n\t};\n}\n"
+  ],
+  "mappings": ";;;;;;;;;;;;;;;;;AAAA;AASA,IAAM,QAAQ,CAAC,MAAuB,EAAE,WAAW,IAAI,IAAI,EAAE,MAAM,CAAC,IAAI;AAGjE,IAAM,4BAA4B;AAClC,IAAM,8BAA8B;AAyBpC,SAAS,WAAW,CAC1B,iBACA,OAA2D,CAAC,GACnD;AAAA,EACT,MAAM,QAAQ,KAAK,mBAAmB;AAAA,EACtC,MAAM,SAAS,KAAK,eAAe;AAAA,EACnC,OAAO,KAAK,OAAO,kBAAkB,SAAS,MAAM;AAAA;AAK9C,SAAS,gBAAgB,CAC/B,cACA,iBACS;AAAA,EACT,OAAO,MACN,iBAAiB,MAAM,YAAY,GAAG,MAAM,eAAe,GAAG,IAAI,CACnE;AAAA;AASM,SAAS,sBAAsB,CACrC,cACA,qBACA,WACqB;AAAA,EACrB,MAAM,QAAQ,IAAI,IACjB,UAAU,QAAQ,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,WAAW,GAAG,EAAE,MAAM,CAAC,CAC9D;AAAA,EACA,MAAM,OAAO,IAAI;AAAA,EACjB,IAAI,eAAe;AAAA,EACnB,IAAI,iBAAiB;AAAA,EACrB,WAAW,OAAO,qBAAqB;AAAA,IACtC,IAAI;AAAA,IACJ,IAAI;AAAA,MACH,SAAS,iBAAiB,cAAc,GAAG;AAAA,MAC1C,MAAM;AAAA,MACP;AAAA;AAAA,IAED,MAAM,SAAS,MAAM,IAAI,MAAM;AAAA,IAC/B,IAAI,WAAW,aAAa,CAAC,KAAK,IAAI,MAAM,GAAG;AAAA,MAC9C,KAAK,IAAI,MAAM;AAAA,MACf,gBAAgB;AAAA,MAChB,kBAAkB;AAAA,IACnB;AAAA,EACD;AAAA,EACA,MAAM,YAAY,KAAK,MAAO,UAAU,eAAe,IAAK,EAAE;AAAA,EAC9D,OAAO;AAAA,IACN;AAAA,IACA,aAAa,UAAU;AAAA,IACvB;AAAA,IACA,cAAc,gBAAgB;AAAA,IAC9B;AAAA,EACD;AAAA;",
+  "debugId": "1937481E7D2EF9AA64756E2164756E21",
+  "names": []
+}

package/dist/src/node/local-client.d.ts

@@ -6,6 +6,8 @@ interface BlocksTable {
 	parent_hash: string;
 	burn_block_height: number;
 	burn_block_hash: ColumnType<string | null, string | null | undefined, string | null>;
+	/** Nakamoto StacksBlockId. Null on rows ingested before it was persisted. */
+	index_block_hash: ColumnType<string | null, string | null | undefined, string | null>;
 	timestamp: number;
 	canonical: Generated<boolean>;
 	created_at: Generated<Date>;

package/dist/src/node/nakamoto.d.ts

@@ -0,0 +1,90 @@
+/**
+* Nakamoto block-header parsing + consensus hashing for trustless verification.
+*
+* Every constant here is verified bit-exact against mainnet `stacks-node
+* 3.4.0.0.3` (see docs/design/trustless-verification-proofs.md, Appendix). This
+* Building block for transaction-inclusion / block-canonicity proofs: fetch a
+* raw `/v3/blocks/{id}` body, parse the header, and recompute the block_hash,
+* index_block_hash, and tx_merkle_root the chain itself commits to.
+*/
+/** SHA-512/256 — the hash Stacks uses everywhere (NOT truncated SHA-512). */
+declare function sha512_256(bytes: Uint8Array): Uint8Array;
+interface NakamotoBlockHeader {
+	version: number;
+	chainLength: bigint;
+	burnSpent: bigint;
+	/** 20-byte consensus hash (hex). */
+	consensusHash: string;
+	/** 32-byte parent StacksBlockId (hex). */
+	parentBlockId: string;
+	/** 32-byte SHA512/256 merkle root over the block's txids (hex). */
+	txMerkleRoot: string;
+	/** 32-byte MARF root after applying this block (hex). */
+	stateIndexRoot: string;
+	timestamp: bigint;
+	/** 65-byte recoverable ECDSA miner signature (hex). */
+	minerSignature: string;
+	/** Per-signer recoverable ECDSA signatures, reward-set order (hex, 65B each). */
+	signerSignatures: string[];
+	/** Full serialized pox_treatment BitVec bytes (u16 bits ‖ u32 len ‖ data). */
+	poxTreatment: Uint8Array;
+	/**
+	* Exact bytes whose SHA512/256 IS the block_hash / signer_signature_hash:
+	* the header with the signer_signature vector omitted (header[0:206] ‖ pox).
+	*/
+	signerSignatureHashPreimage: Uint8Array;
+	/** Offset at which the tx `Vec` begins (= total header byte length). */
+	headerByteLength: number;
+}
+/** Parse the Nakamoto block header from the raw `/v3/blocks` body. */
+declare function parseNakamotoBlockHeader(raw: Uint8Array): NakamotoBlockHeader;
+/**
+* block_hash (== signer_signature_hash): SHA512/256 over the header with the
+* signer_signature vector omitted. This is what each signer signs.
+*/
+declare function nakamotoBlockHash(header: NakamotoBlockHeader): string;
+/** index_block_hash (StacksBlockId) = SHA512/256(block_hash ‖ consensus_hash). */
+declare function nakamotoBlockId(blockHashHex: string, consensusHashHex: string): string;
+/** A Stacks txid = SHA512/256 of the transaction's consensus serialization. */
+declare function stacksTxid(rawTx: Uint8Array): string;
+/**
+* tx_merkle_root over the block's txids (hex), reproducing the consensus rule:
+* leaf = H(0x00 ‖ txid), node = H(0x01 ‖ left ‖ right), odd level duplicates the
+* last node. Returns the root hex; throws on an empty tx list.
+*/
+declare function txMerkleRoot(txidsHex: string[]): string;
+/** One authentication-path step: the sibling hash and which side it's on. */
+interface MerkleProofStep {
+	/** Side the SIBLING is on relative to the accumulator. */
+	position: "left" | "right";
+	/** Sibling node hash (hex). */
+	hash: string;
+}
+/**
+* Build the tx-inclusion authentication path for the tx at `index` in a block,
+* reproducing the consensus merkle tree (incl. duplicate-last-on-odd). The path
+* lets a verifier recompute `tx_merkle_root` from just the target txid.
+*/
+declare function txMerkleProof(txidsHex: string[], index: number): MerkleProofStep[];
+/**
+* Verify a tx-inclusion proof: fold the target `txid` (hex) up through `path`
+* and check it equals `txMerkleRoot` (hex). The verifier recomputes the txid
+* itself from the raw tx bytes, so nothing here is trusted.
+*/
+declare function verifyTxMerkleProof(txidHex: string, path: MerkleProofStep[], txMerkleRootHex: string): boolean;
+/**
+* Fetch and parse a Nakamoto block from a stacks-node. `blockId` is the
+* index_block_hash (with or without 0x). Returns the raw bytes + parsed header +
+* the recomputed block_hash / index_block_hash so a caller can cross-check.
+*/
+declare function fetchNakamotoBlock(opts: {
+	nodeUrl: string
+	blockId: string
+	fetchImpl?: typeof fetch
+}): Promise<{
+	raw: Uint8Array
+	header: NakamotoBlockHeader
+	blockHash: string
+	indexBlockHash: string
+}>;
+export { verifyTxMerkleProof, txMerkleRoot, txMerkleProof, stacksTxid, sha512_256, parseNakamotoBlockHeader, nakamotoBlockId, nakamotoBlockHash, fetchNakamotoBlock, NakamotoBlockHeader, MerkleProofStep };

package/dist/src/node/nakamoto.js

@@ -0,0 +1,177 @@
+import { createRequire } from "node:module";
+var __defProp = Object.defineProperty;
+var __returnValue = (v) => v;
+function __exportSetter(name, newValue) {
+  this[name] = __returnValue.bind(null, newValue);
+}
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: __exportSetter.bind(all, name)
+    });
+};
+
+// src/node/nakamoto.ts
+import { createHash } from "node:crypto";
+function sha512_256(bytes) {
+  return createHash("sha512-256").update(bytes).digest();
+}
+var toHex = (b) => Buffer.from(b).toString("hex");
+var fromHex = (h) => Uint8Array.from(Buffer.from(h.startsWith("0x") ? h.slice(2) : h, "hex"));
+var PREFIX_LEN = 206;
+var CONSENSUS_HASH_OFF = 17;
+var TX_MERKLE_ROOT_OFF = 69;
+var STATE_INDEX_ROOT_OFF = 101;
+var TIMESTAMP_OFF = 133;
+var MINER_SIG_OFF = 141;
+var SIGNER_VEC_OFF = 206;
+var SIG_LEN = 65;
+function u32(b, off) {
+  return new DataView(b.buffer, b.byteOffset, b.byteLength).getUint32(off);
+}
+function u64(b, off) {
+  return new DataView(b.buffer, b.byteOffset, b.byteLength).getBigUint64(off);
+}
+function parseNakamotoBlockHeader(raw) {
+  if (raw.length < PREFIX_LEN + 4) {
+    throw new Error("raw block too short for a Nakamoto header");
+  }
+  const signerCount = u32(raw, SIGNER_VEC_OFF);
+  const sigsStart = SIGNER_VEC_OFF + 4;
+  const signerSignatures = [];
+  for (let i = 0;i < signerCount; i++) {
+    const off = sigsStart + i * SIG_LEN;
+    signerSignatures.push(toHex(raw.subarray(off, off + SIG_LEN)));
+  }
+  const poxOff = sigsStart + signerCount * SIG_LEN;
+  const poxDataLen = u32(raw, poxOff + 2);
+  const poxEnd = poxOff + 6 + poxDataLen;
+  const poxTreatment = raw.subarray(poxOff, poxEnd);
+  const preimage = new Uint8Array(PREFIX_LEN + poxTreatment.length);
+  preimage.set(raw.subarray(0, PREFIX_LEN), 0);
+  preimage.set(poxTreatment, PREFIX_LEN);
+  return {
+    version: raw[0],
+    chainLength: u64(raw, 1),
+    burnSpent: u64(raw, 9),
+    consensusHash: toHex(raw.subarray(CONSENSUS_HASH_OFF, CONSENSUS_HASH_OFF + 20)),
+    parentBlockId: toHex(raw.subarray(37, 69)),
+    txMerkleRoot: toHex(raw.subarray(TX_MERKLE_ROOT_OFF, TX_MERKLE_ROOT_OFF + 32)),
+    stateIndexRoot: toHex(raw.subarray(STATE_INDEX_ROOT_OFF, STATE_INDEX_ROOT_OFF + 32)),
+    timestamp: u64(raw, TIMESTAMP_OFF),
+    minerSignature: toHex(raw.subarray(MINER_SIG_OFF, MINER_SIG_OFF + SIG_LEN)),
+    signerSignatures,
+    poxTreatment,
+    signerSignatureHashPreimage: preimage,
+    headerByteLength: poxEnd
+  };
+}
+function nakamotoBlockHash(header) {
+  return toHex(sha512_256(header.signerSignatureHashPreimage));
+}
+function nakamotoBlockId(blockHashHex, consensusHashHex) {
+  const a = fromHex(blockHashHex);
+  const b = fromHex(consensusHashHex);
+  const buf = new Uint8Array(a.length + b.length);
+  buf.set(a, 0);
+  buf.set(b, a.length);
+  return toHex(sha512_256(buf));
+}
+function stacksTxid(rawTx) {
+  return toHex(sha512_256(rawTx));
+}
+var LEAF_TAG = 0;
+var NODE_TAG = 1;
+function tagged(tag, ...parts) {
+  const len = parts.reduce((n, p) => n + p.length, 1);
+  const buf = new Uint8Array(len);
+  buf[0] = tag;
+  let o = 1;
+  for (const p of parts) {
+    buf.set(p, o);
+    o += p.length;
+  }
+  return sha512_256(buf);
+}
+function txMerkleRoot(txidsHex) {
+  if (txidsHex.length === 0)
+    throw new Error("no transactions");
+  let level = txidsHex.map((t) => tagged(LEAF_TAG, fromHex(t)));
+  while (level.length > 1) {
+    if (level.length % 2 === 1)
+      level.push(level[level.length - 1]);
+    const next = [];
+    for (let i = 0;i < level.length; i += 2) {
+      next.push(tagged(NODE_TAG, level[i], level[i + 1]));
+    }
+    level = next;
+  }
+  return toHex(level[0]);
+}
+function txMerkleProof(txidsHex, index) {
+  if (index < 0 || index >= txidsHex.length) {
+    throw new Error("index out of range");
+  }
+  let level = txidsHex.map((t) => tagged(LEAF_TAG, fromHex(t)));
+  let idx = index;
+  const path = [];
+  while (level.length > 1) {
+    if (level.length % 2 === 1)
+      level.push(level[level.length - 1]);
+    const siblingIdx = idx % 2 === 0 ? idx + 1 : idx - 1;
+    path.push({
+      position: idx % 2 === 0 ? "right" : "left",
+      hash: toHex(level[siblingIdx])
+    });
+    const next = [];
+    for (let i = 0;i < level.length; i += 2) {
+      next.push(tagged(NODE_TAG, level[i], level[i + 1]));
+    }
+    level = next;
+    idx = Math.floor(idx / 2);
+  }
+  return path;
+}
+function verifyTxMerkleProof(txidHex, path, txMerkleRootHex) {
+  let acc = tagged(LEAF_TAG, fromHex(txidHex));
+  for (const step of path) {
+    const sib = fromHex(step.hash);
+    acc = step.position === "right" ? tagged(NODE_TAG, acc, sib) : tagged(NODE_TAG, sib, acc);
+  }
+  const root = txMerkleRootHex.startsWith("0x") ? txMerkleRootHex.slice(2) : txMerkleRootHex;
+  return toHex(acc) === root;
+}
+async function fetchNakamotoBlock(opts) {
+  const id = opts.blockId.startsWith("0x") ? opts.blockId.slice(2) : opts.blockId;
+  const f = opts.fetchImpl ?? fetch;
+  const res = await f(`${opts.nodeUrl.replace(/\/+$/, "")}/v3/blocks/${id}`);
+  if (!res.ok) {
+    throw new Error(`/v3/blocks/${id} returned ${res.status}`);
+  }
+  const raw = new Uint8Array(await res.arrayBuffer());
+  const header = parseNakamotoBlockHeader(raw);
+  const blockHash = nakamotoBlockHash(header);
+  return {
+    raw,
+    header,
+    blockHash,
+    indexBlockHash: nakamotoBlockId(blockHash, header.consensusHash)
+  };
+}
+export {
+  verifyTxMerkleProof,
+  txMerkleRoot,
+  txMerkleProof,
+  stacksTxid,
+  sha512_256,
+  parseNakamotoBlockHeader,
+  nakamotoBlockId,
+  nakamotoBlockHash,
+  fetchNakamotoBlock
+};
+
+//# debugId=7DE7C366A0D5645764756E2164756E21
+//# sourceMappingURL=nakamoto.js.map

package/dist/src/node/nakamoto.js.map

@@ -0,0 +1,10 @@
+{
+  "version": 3,
+  "sources": ["../src/node/nakamoto.ts"],
+  "sourcesContent": [
+    "import { createHash } from \"node:crypto\";\n\n/**\n * Nakamoto block-header parsing + consensus hashing for trustless verification.\n *\n * Every constant here is verified bit-exact against mainnet `stacks-node\n * 3.4.0.0.3` (see docs/design/trustless-verification-proofs.md, Appendix). This\n * Building block for transaction-inclusion / block-canonicity proofs: fetch a\n * raw `/v3/blocks/{id}` body, parse the header, and recompute the block_hash,\n * index_block_hash, and tx_merkle_root the chain itself commits to.\n */\n\n/** SHA-512/256 — the hash Stacks uses everywhere (NOT truncated SHA-512). */\nexport function sha512_256(bytes: Uint8Array): Uint8Array {\n\treturn createHash(\"sha512-256\").update(bytes).digest();\n}\n\nconst toHex = (b: Uint8Array): string => Buffer.from(b).toString(\"hex\");\nconst fromHex = (h: string): Uint8Array =>\n\tUint8Array.from(Buffer.from(h.startsWith(\"0x\") ? h.slice(2) : h, \"hex\"));\n\n// Fixed-size header prefix: version..miner_signature, before signer_signature.\nconst PREFIX_LEN = 206;\nconst CONSENSUS_HASH_OFF = 17;\nconst TX_MERKLE_ROOT_OFF = 69;\nconst STATE_INDEX_ROOT_OFF = 101;\nconst TIMESTAMP_OFF = 133;\nconst MINER_SIG_OFF = 141;\nconst SIGNER_VEC_OFF = 206; // u32 count, then 65 bytes per signer\nconst SIG_LEN = 65;\n\nexport interface NakamotoBlockHeader {\n\tversion: number;\n\tchainLength: bigint;\n\tburnSpent: bigint;\n\t/** 20-byte consensus hash (hex). */\n\tconsensusHash: string;\n\t/** 32-byte parent StacksBlockId (hex). */\n\tparentBlockId: string;\n\t/** 32-byte SHA512/256 merkle root over the block's txids (hex). */\n\ttxMerkleRoot: string;\n\t/** 32-byte MARF root after applying this block (hex). */\n\tstateIndexRoot: string;\n\ttimestamp: bigint;\n\t/** 65-byte recoverable ECDSA miner signature (hex). */\n\tminerSignature: string;\n\t/** Per-signer recoverable ECDSA signatures, reward-set order (hex, 65B each). */\n\tsignerSignatures: string[];\n\t/** Full serialized pox_treatment BitVec bytes (u16 bits ‖ u32 len ‖ data). */\n\tpoxTreatment: Uint8Array;\n\t/**\n\t * Exact bytes whose SHA512/256 IS the block_hash / signer_signature_hash:\n\t * the header with the signer_signature vector omitted (header[0:206] ‖ pox).\n\t */\n\tsignerSignatureHashPreimage: Uint8Array;\n\t/** Offset at which the tx `Vec` begins (= total header byte length). */\n\theaderByteLength: number;\n}\n\nfunction u32(b: Uint8Array, off: number): number {\n\treturn new DataView(b.buffer, b.byteOffset, b.byteLength).getUint32(off);\n}\nfunction u64(b: Uint8Array, off: number): bigint {\n\treturn new DataView(b.buffer, b.byteOffset, b.byteLength).getBigUint64(off);\n}\n\n/** Parse the Nakamoto block header from the raw `/v3/blocks` body. */\nexport function parseNakamotoBlockHeader(raw: Uint8Array): NakamotoBlockHeader {\n\tif (raw.length < PREFIX_LEN + 4) {\n\t\tthrow new Error(\"raw block too short for a Nakamoto header\");\n\t}\n\tconst signerCount = u32(raw, SIGNER_VEC_OFF);\n\tconst sigsStart = SIGNER_VEC_OFF + 4;\n\tconst signerSignatures: string[] = [];\n\tfor (let i = 0; i < signerCount; i++) {\n\t\tconst off = sigsStart + i * SIG_LEN;\n\t\tsignerSignatures.push(toHex(raw.subarray(off, off + SIG_LEN)));\n\t}\n\t// pox_treatment: u16 num_bits ‖ u32 data_len ‖ data[data_len].\n\tconst poxOff = sigsStart + signerCount * SIG_LEN;\n\tconst poxDataLen = u32(raw, poxOff + 2);\n\tconst poxEnd = poxOff + 6 + poxDataLen;\n\tconst poxTreatment = raw.subarray(poxOff, poxEnd);\n\n\t// block_hash preimage = header minus signer_signature = prefix[0:206] ‖ pox.\n\tconst preimage = new Uint8Array(PREFIX_LEN + poxTreatment.length);\n\tpreimage.set(raw.subarray(0, PREFIX_LEN), 0);\n\tpreimage.set(poxTreatment, PREFIX_LEN);\n\n\treturn {\n\t\tversion: raw[0],\n\t\tchainLength: u64(raw, 1),\n\t\tburnSpent: u64(raw, 9),\n\t\tconsensusHash: toHex(\n\t\t\traw.subarray(CONSENSUS_HASH_OFF, CONSENSUS_HASH_OFF + 20),\n\t\t),\n\t\tparentBlockId: toHex(raw.subarray(37, 69)),\n\t\ttxMerkleRoot: toHex(\n\t\t\traw.subarray(TX_MERKLE_ROOT_OFF, TX_MERKLE_ROOT_OFF + 32),\n\t\t),\n\t\tstateIndexRoot: toHex(\n\t\t\traw.subarray(STATE_INDEX_ROOT_OFF, STATE_INDEX_ROOT_OFF + 32),\n\t\t),\n\t\ttimestamp: u64(raw, TIMESTAMP_OFF),\n\t\tminerSignature: toHex(raw.subarray(MINER_SIG_OFF, MINER_SIG_OFF + SIG_LEN)),\n\t\tsignerSignatures,\n\t\tpoxTreatment,\n\t\tsignerSignatureHashPreimage: preimage,\n\t\theaderByteLength: poxEnd,\n\t};\n}\n\n/**\n * block_hash (== signer_signature_hash): SHA512/256 over the header with the\n * signer_signature vector omitted. This is what each signer signs.\n */\nexport function nakamotoBlockHash(header: NakamotoBlockHeader): string {\n\treturn toHex(sha512_256(header.signerSignatureHashPreimage));\n}\n\n/** index_block_hash (StacksBlockId) = SHA512/256(block_hash ‖ consensus_hash). */\nexport function nakamotoBlockId(\n\tblockHashHex: string,\n\tconsensusHashHex: string,\n): string {\n\tconst a = fromHex(blockHashHex);\n\tconst b = fromHex(consensusHashHex);\n\tconst buf = new Uint8Array(a.length + b.length);\n\tbuf.set(a, 0);\n\tbuf.set(b, a.length);\n\treturn toHex(sha512_256(buf));\n}\n\n/** A Stacks txid = SHA512/256 of the transaction's consensus serialization. */\nexport function stacksTxid(rawTx: Uint8Array): string {\n\treturn toHex(sha512_256(rawTx));\n}\n\nconst LEAF_TAG = 0x00;\nconst NODE_TAG = 0x01;\n\nfunction tagged(tag: number, ...parts: Uint8Array[]): Uint8Array {\n\tconst len = parts.reduce((n, p) => n + p.length, 1);\n\tconst buf = new Uint8Array(len);\n\tbuf[0] = tag;\n\tlet o = 1;\n\tfor (const p of parts) {\n\t\tbuf.set(p, o);\n\t\to += p.length;\n\t}\n\treturn sha512_256(buf);\n}\n\n/**\n * tx_merkle_root over the block's txids (hex), reproducing the consensus rule:\n * leaf = H(0x00 ‖ txid), node = H(0x01 ‖ left ‖ right), odd level duplicates the\n * last node. Returns the root hex; throws on an empty tx list.\n */\nexport function txMerkleRoot(txidsHex: string[]): string {\n\tif (txidsHex.length === 0) throw new Error(\"no transactions\");\n\tlet level = txidsHex.map((t) => tagged(LEAF_TAG, fromHex(t)));\n\twhile (level.length > 1) {\n\t\tif (level.length % 2 === 1) level.push(level[level.length - 1]);\n\t\tconst next: Uint8Array[] = [];\n\t\tfor (let i = 0; i < level.length; i += 2) {\n\t\t\tnext.push(tagged(NODE_TAG, level[i], level[i + 1]));\n\t\t}\n\t\tlevel = next;\n\t}\n\treturn toHex(level[0]);\n}\n\n/** One authentication-path step: the sibling hash and which side it's on. */\nexport interface MerkleProofStep {\n\t/** Side the SIBLING is on relative to the accumulator. */\n\tposition: \"left\" | \"right\";\n\t/** Sibling node hash (hex). */\n\thash: string;\n}\n\n/**\n * Build the tx-inclusion authentication path for the tx at `index` in a block,\n * reproducing the consensus merkle tree (incl. duplicate-last-on-odd). The path\n * lets a verifier recompute `tx_merkle_root` from just the target txid.\n */\nexport function txMerkleProof(\n\ttxidsHex: string[],\n\tindex: number,\n): MerkleProofStep[] {\n\tif (index < 0 || index >= txidsHex.length) {\n\t\tthrow new Error(\"index out of range\");\n\t}\n\tlet level = txidsHex.map((t) => tagged(LEAF_TAG, fromHex(t)));\n\tlet idx = index;\n\tconst path: MerkleProofStep[] = [];\n\twhile (level.length > 1) {\n\t\tif (level.length % 2 === 1) level.push(level[level.length - 1]);\n\t\tconst siblingIdx = idx % 2 === 0 ? idx + 1 : idx - 1;\n\t\tpath.push({\n\t\t\tposition: idx % 2 === 0 ? \"right\" : \"left\",\n\t\t\thash: toHex(level[siblingIdx]),\n\t\t});\n\t\tconst next: Uint8Array[] = [];\n\t\tfor (let i = 0; i < level.length; i += 2) {\n\t\t\tnext.push(tagged(NODE_TAG, level[i], level[i + 1]));\n\t\t}\n\t\tlevel = next;\n\t\tidx = Math.floor(idx / 2);\n\t}\n\treturn path;\n}\n\n/**\n * Verify a tx-inclusion proof: fold the target `txid` (hex) up through `path`\n * and check it equals `txMerkleRoot` (hex). The verifier recomputes the txid\n * itself from the raw tx bytes, so nothing here is trusted.\n */\nexport function verifyTxMerkleProof(\n\ttxidHex: string,\n\tpath: MerkleProofStep[],\n\ttxMerkleRootHex: string,\n): boolean {\n\tlet acc = tagged(LEAF_TAG, fromHex(txidHex));\n\tfor (const step of path) {\n\t\tconst sib = fromHex(step.hash);\n\t\tacc =\n\t\t\tstep.position === \"right\"\n\t\t\t\t? tagged(NODE_TAG, acc, sib)\n\t\t\t\t: tagged(NODE_TAG, sib, acc);\n\t}\n\tconst root = txMerkleRootHex.startsWith(\"0x\")\n\t\t? txMerkleRootHex.slice(2)\n\t\t: txMerkleRootHex;\n\treturn toHex(acc) === root;\n}\n\n/**\n * Fetch and parse a Nakamoto block from a stacks-node. `blockId` is the\n * index_block_hash (with or without 0x). Returns the raw bytes + parsed header +\n * the recomputed block_hash / index_block_hash so a caller can cross-check.\n */\nexport async function fetchNakamotoBlock(opts: {\n\tnodeUrl: string;\n\tblockId: string;\n\tfetchImpl?: typeof fetch;\n}): Promise<{\n\traw: Uint8Array;\n\theader: NakamotoBlockHeader;\n\tblockHash: string;\n\tindexBlockHash: string;\n}> {\n\tconst id = opts.blockId.startsWith(\"0x\")\n\t\t? opts.blockId.slice(2)\n\t\t: opts.blockId;\n\tconst f = opts.fetchImpl ?? fetch;\n\tconst res = await f(`${opts.nodeUrl.replace(/\\/+$/, \"\")}/v3/blocks/${id}`);\n\tif (!res.ok) {\n\t\tthrow new Error(`/v3/blocks/${id} returned ${res.status}`);\n\t}\n\tconst raw = new Uint8Array(await res.arrayBuffer());\n\tconst header = parseNakamotoBlockHeader(raw);\n\tconst blockHash = nakamotoBlockHash(header);\n\treturn {\n\t\traw,\n\t\theader,\n\t\tblockHash,\n\t\tindexBlockHash: nakamotoBlockId(blockHash, header.consensusHash),\n\t};\n}\n"
+  ],
+  "mappings": "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",
+  "debugId": "7DE7C366A0D5645764756E2164756E21",
+  "names": []
+}

package/dist/src/streams-bulk-manifest.d.ts

@@ -0,0 +1,33 @@
+/**
+* ed25519 signing for the Streams cold-bulk parquet manifest.
+*
+* The live Streams lane is ed25519-signed; the bulk manifest was plain JSON with
+* only per-file sha256, so a tampered manifest+file pair verified cleanly. This
+* signs the manifest itself with the same platform key, so a consumer can trust
+* the file hashes only after the manifest signature checks out — making the two
+* availability lanes symmetric.
+*
+* The signed bytes are the manifest's canonical JSON with the signature envelope
+* fields removed, so signer and verifier agree without a separate canonical
+* form: `signature`/`key_id` are appended last, so stripping them and
+* re-serializing reproduces the exact pre-sign bytes.
+*/
+type SignatureEnvelope = {
+	signature?: string
+	key_id?: string
+};
+/** The exact bytes a manifest signature covers: the manifest JSON minus the
+*  signature envelope fields. */
+declare function canonicalStreamsBulkManifestPayload(manifest: Record<string, unknown> & SignatureEnvelope): string;
+/**
+* Attach an ed25519 `signature` + `key_id` over the manifest's canonical bytes.
+* Returns a new manifest; re-signing one that already carries a signature signs
+* over its un-enveloped form (idempotent shape).
+*/
+declare function signStreamsBulkManifest<T extends Record<string, unknown> & SignatureEnvelope>(manifest: T, privateKeyPem: string): T & {
+	signature: string
+	key_id: string
+};
+/** Verify a manifest's ed25519 signature against the published public key. */
+declare function verifyStreamsBulkManifestSignature(manifest: Record<string, unknown> & SignatureEnvelope, publicKeyPem: string): boolean;
+export { verifyStreamsBulkManifestSignature, signStreamsBulkManifest, canonicalStreamsBulkManifestPayload };

package/dist/src/streams-bulk-manifest.js

@@ -0,0 +1,104 @@
+import { createRequire } from "node:module";
+var __defProp = Object.defineProperty;
+var __returnValue = (v) => v;
+function __exportSetter(name, newValue) {
+  this[name] = __returnValue.bind(null, newValue);
+}
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: __exportSetter.bind(all, name)
+    });
+};
+
+// src/crypto/ed25519.ts
+var exports_ed25519 = {};
+__export(exports_ed25519, {
+  verifyEd25519: () => verifyEd25519,
+  signEd25519: () => signEd25519,
+  publicKeyPemFromPrivate: () => publicKeyPemFromPrivate,
+  loadEd25519PublicKey: () => loadEd25519PublicKey,
+  loadEd25519PrivateKey: () => loadEd25519PrivateKey,
+  generateEd25519KeyPair: () => generateEd25519KeyPair,
+  ed25519KeyId: () => ed25519KeyId
+});
+import {
+  createHash,
+  createPrivateKey,
+  createPublicKey,
+  generateKeyPairSync,
+  sign as nodeSign,
+  verify as nodeVerify
+} from "node:crypto";
+function generateEd25519KeyPair() {
+  const { privateKey, publicKey } = generateKeyPairSync("ed25519");
+  return {
+    privateKeyPem: privateKey.export({ format: "pem", type: "pkcs8" }).toString(),
+    publicKeyPem: publicKey.export({ format: "pem", type: "spki" }).toString()
+  };
+}
+function loadEd25519PrivateKey(pem) {
+  return createPrivateKey(pem);
+}
+function loadEd25519PublicKey(pem) {
+  return createPublicKey(pem);
+}
+function publicKeyPemFromPrivate(privateKeyPem) {
+  return createPublicKey(createPrivateKey(privateKeyPem)).export({ format: "pem", type: "spki" }).toString();
+}
+function ed25519KeyId(publicKeyPem) {
+  const der = createPublicKey(publicKeyPem).export({
+    format: "der",
+    type: "spki"
+  });
+  return createHash("sha256").update(der).digest("base64url").slice(0, 16);
+}
+function signEd25519(payload, privateKey) {
+  return nodeSign(null, Buffer.from(payload, "utf8"), privateKey).toString("base64");
+}
+function verifyEd25519(payload, signatureBase64, publicKey) {
+  try {
+    return nodeVerify(null, Buffer.from(payload, "utf8"), publicKey, Buffer.from(signatureBase64, "base64"));
+  } catch {
+    return false;
+  }
+}
+
+// src/streams-bulk-manifest.ts
+function canonicalStreamsBulkManifestPayload(manifest) {
+  const { signature: _signature, key_id: _keyId, ...rest } = manifest;
+  return JSON.stringify(rest);
+}
+function normalizePem(pem) {
+  return pem.includes("\\n") ? pem.replace(/\\n/g, `
+`) : pem;
+}
+function signStreamsBulkManifest(manifest, privateKeyPem) {
+  const pem = normalizePem(privateKeyPem);
+  const privateKey = loadEd25519PrivateKey(pem);
+  const keyId = ed25519KeyId(publicKeyPemFromPrivate(pem));
+  const { signature: _signature, key_id: _keyId, ...base } = manifest;
+  const payload = JSON.stringify(base);
+  return {
+    ...base,
+    signature: signEd25519(payload, privateKey),
+    key_id: keyId
+  };
+}
+function verifyStreamsBulkManifestSignature(manifest, publicKeyPem) {
+  if (!manifest.signature)
+    return false;
+  const payload = canonicalStreamsBulkManifestPayload(manifest);
+  return verifyEd25519(payload, manifest.signature, loadEd25519PublicKey(publicKeyPem));
+}
+export {
+  verifyStreamsBulkManifestSignature,
+  signStreamsBulkManifest,
+  canonicalStreamsBulkManifestPayload
+};
+
+//# debugId=CAF4339AB8D4DD3E64756E2164756E21
+//# sourceMappingURL=streams-bulk-manifest.js.map

package/dist/src/streams-bulk-manifest.js.map

@@ -0,0 +1,11 @@
+{
+  "version": 3,
+  "sources": ["../src/crypto/ed25519.ts", "../src/streams-bulk-manifest.ts"],
+  "sourcesContent": [
+    "import {\n\ttype KeyObject,\n\tcreateHash,\n\tcreatePrivateKey,\n\tcreatePublicKey,\n\tgenerateKeyPairSync,\n\tsign as nodeSign,\n\tverify as nodeVerify,\n} from \"node:crypto\";\n\n/**\n * Asymmetric ed25519 signing for Streams response proofs.\n *\n * Asymmetric (not HMAC) so the proof is real: only the server holds the private\n * key, and any consumer verifies with the published public key — no shared\n * secret to leak. ed25519 uses node's `sign`/`verify` with a `null` algorithm.\n * Keys are PEM (PKCS8 private / SPKI public) for env transport; load once and\n * reuse the KeyObject on hot paths.\n */\n\nexport function generateEd25519KeyPair(): {\n\tprivateKeyPem: string;\n\tpublicKeyPem: string;\n} {\n\tconst { privateKey, publicKey } = generateKeyPairSync(\"ed25519\");\n\treturn {\n\t\tprivateKeyPem: privateKey\n\t\t\t.export({ format: \"pem\", type: \"pkcs8\" })\n\t\t\t.toString(),\n\t\tpublicKeyPem: publicKey.export({ format: \"pem\", type: \"spki\" }).toString(),\n\t};\n}\n\nexport function loadEd25519PrivateKey(pem: string): KeyObject {\n\treturn createPrivateKey(pem);\n}\n\nexport function loadEd25519PublicKey(pem: string): KeyObject {\n\treturn createPublicKey(pem);\n}\n\nexport function publicKeyPemFromPrivate(privateKeyPem: string): string {\n\treturn createPublicKey(createPrivateKey(privateKeyPem))\n\t\t.export({ format: \"pem\", type: \"spki\" })\n\t\t.toString();\n}\n\n/** Stable short id for a public key (rotation hint via X-Signature-KeyId). */\nexport function ed25519KeyId(publicKeyPem: string): string {\n\tconst der = createPublicKey(publicKeyPem).export({\n\t\tformat: \"der\",\n\t\ttype: \"spki\",\n\t});\n\treturn createHash(\"sha256\").update(der).digest(\"base64url\").slice(0, 16);\n}\n\nexport function signEd25519(payload: string, privateKey: KeyObject): string {\n\treturn nodeSign(null, Buffer.from(payload, \"utf8\"), privateKey).toString(\n\t\t\"base64\",\n\t);\n}\n\nexport function verifyEd25519(\n\tpayload: string,\n\tsignatureBase64: string,\n\tpublicKey: KeyObject,\n): boolean {\n\ttry {\n\t\treturn nodeVerify(\n\t\t\tnull,\n\t\t\tBuffer.from(payload, \"utf8\"),\n\t\t\tpublicKey,\n\t\t\tBuffer.from(signatureBase64, \"base64\"),\n\t\t);\n\t} catch {\n\t\treturn false;\n\t}\n}\n",
+    "import {\n\ted25519KeyId,\n\tloadEd25519PrivateKey,\n\tloadEd25519PublicKey,\n\tpublicKeyPemFromPrivate,\n\tsignEd25519,\n\tverifyEd25519,\n} from \"./crypto/ed25519.ts\";\n\n/**\n * ed25519 signing for the Streams cold-bulk parquet manifest.\n *\n * The live Streams lane is ed25519-signed; the bulk manifest was plain JSON with\n * only per-file sha256, so a tampered manifest+file pair verified cleanly. This\n * signs the manifest itself with the same platform key, so a consumer can trust\n * the file hashes only after the manifest signature checks out — making the two\n * availability lanes symmetric.\n *\n * The signed bytes are the manifest's canonical JSON with the signature envelope\n * fields removed, so signer and verifier agree without a separate canonical\n * form: `signature`/`key_id` are appended last, so stripping them and\n * re-serializing reproduces the exact pre-sign bytes.\n */\ntype SignatureEnvelope = { signature?: string; key_id?: string };\n\n/** The exact bytes a manifest signature covers: the manifest JSON minus the\n *  signature envelope fields. */\nexport function canonicalStreamsBulkManifestPayload(\n\tmanifest: Record<string, unknown> & SignatureEnvelope,\n): string {\n\tconst { signature: _signature, key_id: _keyId, ...rest } = manifest;\n\treturn JSON.stringify(rest);\n}\n\nfunction normalizePem(pem: string): string {\n\t// Env transport often escapes newlines; restore real PEM line breaks.\n\treturn pem.includes(\"\\\\n\") ? pem.replace(/\\\\n/g, \"\\n\") : pem;\n}\n\n/**\n * Attach an ed25519 `signature` + `key_id` over the manifest's canonical bytes.\n * Returns a new manifest; re-signing one that already carries a signature signs\n * over its un-enveloped form (idempotent shape).\n */\nexport function signStreamsBulkManifest<\n\tT extends Record<string, unknown> & SignatureEnvelope,\n>(\n\tmanifest: T,\n\tprivateKeyPem: string,\n): T & { signature: string; key_id: string } {\n\tconst pem = normalizePem(privateKeyPem);\n\tconst privateKey = loadEd25519PrivateKey(pem);\n\tconst keyId = ed25519KeyId(publicKeyPemFromPrivate(pem));\n\tconst { signature: _signature, key_id: _keyId, ...base } = manifest;\n\tconst payload = JSON.stringify(base);\n\treturn {\n\t\t...(base as T),\n\t\tsignature: signEd25519(payload, privateKey),\n\t\tkey_id: keyId,\n\t};\n}\n\n/** Verify a manifest's ed25519 signature against the published public key. */\nexport function verifyStreamsBulkManifestSignature(\n\tmanifest: Record<string, unknown> & SignatureEnvelope,\n\tpublicKeyPem: string,\n): boolean {\n\tif (!manifest.signature) return false;\n\tconst payload = canonicalStreamsBulkManifestPayload(manifest);\n\treturn verifyEd25519(\n\t\tpayload,\n\t\tmanifest.signature,\n\t\tloadEd25519PublicKey(publicKeyPem),\n\t);\n}\n"
+  ],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,UAMC;AAAA,YACA;AAAA;AAaM,SAAS,sBAAsB,GAGpC;AAAA,EACD,QAAQ,YAAY,cAAc,oBAAoB,SAAS;AAAA,EAC/D,OAAO;AAAA,IACN,eAAe,WACb,OAAO,EAAE,QAAQ,OAAO,MAAM,QAAQ,CAAC,EACvC,SAAS;AAAA,IACX,cAAc,UAAU,OAAO,EAAE,QAAQ,OAAO,MAAM,OAAO,CAAC,EAAE,SAAS;AAAA,EAC1E;AAAA;AAGM,SAAS,qBAAqB,CAAC,KAAwB;AAAA,EAC7D,OAAO,iBAAiB,GAAG;AAAA;AAGrB,SAAS,oBAAoB,CAAC,KAAwB;AAAA,EAC5D,OAAO,gBAAgB,GAAG;AAAA;AAGpB,SAAS,uBAAuB,CAAC,eAA+B;AAAA,EACtE,OAAO,gBAAgB,iBAAiB,aAAa,CAAC,EACpD,OAAO,EAAE,QAAQ,OAAO,MAAM,OAAO,CAAC,EACtC,SAAS;AAAA;AAIL,SAAS,YAAY,CAAC,cAA8B;AAAA,EAC1D,MAAM,MAAM,gBAAgB,YAAY,EAAE,OAAO;AAAA,IAChD,QAAQ;AAAA,IACR,MAAM;AAAA,EACP,CAAC;AAAA,EACD,OAAO,WAAW,QAAQ,EAAE,OAAO,GAAG,EAAE,OAAO,WAAW,EAAE,MAAM,GAAG,EAAE;AAAA;AAGjE,SAAS,WAAW,CAAC,SAAiB,YAA+B;AAAA,EAC3E,OAAO,SAAS,MAAM,OAAO,KAAK,SAAS,MAAM,GAAG,UAAU,EAAE,SAC/D,QACD;AAAA;AAGM,SAAS,aAAa,CAC5B,SACA,iBACA,WACU;AAAA,EACV,IAAI;AAAA,IACH,OAAO,WACN,MACA,OAAO,KAAK,SAAS,MAAM,GAC3B,WACA,OAAO,KAAK,iBAAiB,QAAQ,CACtC;AAAA,IACC,MAAM;AAAA,IACP,OAAO;AAAA;AAAA;;;AChDF,SAAS,mCAAmC,CAClD,UACS;AAAA,EACT,QAAQ,WAAW,YAAY,QAAQ,WAAW,SAAS;AAAA,EAC3D,OAAO,KAAK,UAAU,IAAI;AAAA;AAG3B,SAAS,YAAY,CAAC,KAAqB;AAAA,EAE1C,OAAO,IAAI,SAAS,KAAK,IAAI,IAAI,QAAQ,QAAQ;AAAA,CAAI,IAAI;AAAA;AAQnD,SAAS,uBAEf,CACA,UACA,eAC4C;AAAA,EAC5C,MAAM,MAAM,aAAa,aAAa;AAAA,EACtC,MAAM,aAAa,sBAAsB,GAAG;AAAA,EAC5C,MAAM,QAAQ,aAAa,wBAAwB,GAAG,CAAC;AAAA,EACvD,QAAQ,WAAW,YAAY,QAAQ,WAAW,SAAS;AAAA,EAC3D,MAAM,UAAU,KAAK,UAAU,IAAI;AAAA,EACnC,OAAO;AAAA,OACF;AAAA,IACJ,WAAW,YAAY,SAAS,UAAU;AAAA,IAC1C,QAAQ;AAAA,EACT;AAAA;AAIM,SAAS,kCAAkC,CACjD,UACA,cACU;AAAA,EACV,IAAI,CAAC,SAAS;AAAA,IAAW,OAAO;AAAA,EAChC,MAAM,UAAU,oCAAoC,QAAQ;AAAA,EAC5D,OAAO,cACN,SACA,SAAS,WACT,qBAAqB,YAAY,CAClC;AAAA;",
+  "debugId": "CAF4339AB8D4DD3E64756E2164756E21",
+  "names": []
+}

package/dist/src/types.d.ts

@@ -5,6 +5,8 @@ interface BlocksTable {
 	parent_hash: string;
 	burn_block_height: number;
 	burn_block_hash: ColumnType<string | null, string | null | undefined, string | null>;
+	/** Nakamoto StacksBlockId. Null on rows ingested before it was persisted. */
+	index_block_hash: ColumnType<string | null, string | null | undefined, string | null>;
 	timestamp: number;
 	canonical: Generated<boolean>;
 	created_at: Generated<Date>;

package/migrations/0089_blocks_index_block_hash.ts

@@ -0,0 +1,25 @@
+import { type Kysely, sql } from "kysely";
+import { onChainPlane } from "../src/db/migration-role.ts";
+
+// Persist the Nakamoto `index_block_hash` (StacksBlockId) on `blocks`. It
+// already arrives in the node's /new_block payload but was dropped at insert;
+// keeping it lets the tx-inclusion proof endpoint resolve a block's signed
+// header from /v3/blocks without an extra node round-trip per request. Nullable:
+// historical rows backfill lazily / on demand. `blocks` is a chain-plane table,
+// so the DDL no-ops on the control DB under the source/target split.
+export async function up(db: Kysely<unknown>): Promise<void> {
+	await onChainPlane(async () => {
+		await sql`SET lock_timeout = '30s'`.execute(db);
+		await sql`ALTER TABLE blocks ADD COLUMN IF NOT EXISTS index_block_hash TEXT`.execute(
+			db,
+		);
+	});
+}
+
+export async function down(db: Kysely<unknown>): Promise<void> {
+	await onChainPlane(async () => {
+		await sql`ALTER TABLE blocks DROP COLUMN IF EXISTS index_block_hash`.execute(
+			db,
+		);
+	});
+}