@secondlayer/stacks 2.8.1 → 2.9.0

package/dist/src/bitcoin/index.cjs

@@ -0,0 +1,679 @@
+// src/bitcoin/index.ts
+var exports_bitcoin = {};
+__export(exports_bitcoin, {
+  verifyBitcoinPayment: () => verifyBitcoinPayment,
+  stripWitness: () => stripWitness,
+  rootFromProof: () => rootFromProof,
+  reverseBytes: () => reverseBytes,
+  parseOutputScript: () => parseOutputScript,
+  parseBlockHeader: () => parseBlockHeader,
+  parseBitcoinTx: () => parseBitcoinTx,
+  merkleRoot: () => merkleRoot,
+  isClarity6Active: () => isClarity6Active,
+  getBurnBlockHeight: () => getBurnBlockHeight,
+  formatBitcoinAddress: () => formatBitcoinAddress,
+  fallbackProofSource: () => fallbackProofSource,
+  esploraSource: () => esploraSource,
+  encodeMerkleProofArgs: () => encodeMerkleProofArgs,
+  doubleSha256: () => doubleSha256,
+  decodeTxOutput: () => decodeTxOutput,
+  buildTxProof: () => buildTxProof,
+  buildMerkleProof: () => buildMerkleProof,
+  blockHash: () => blockHash,
+  bitcoinVerifier: () => bitcoinVerifier,
+  bitcoinTxid: () => bitcoinTxid,
+  bitcoinRpcSource: () => bitcoinRpcSource,
+  SPV_ADAPTER_CONTRACTS: () => SPV_ADAPTER_CONTRACTS,
+  SPV_ADAPTER_ABI: () => SPV_ADAPTER_ABI,
+  BtcReader: () => BtcReader
+});
+module.exports = __toCommonJS(exports_bitcoin);
+
+// src/bitcoin/serialize.ts
+function doubleSha256(bytes) {
+  return import_sha2.sha256(import_sha2.sha256(bytes));
+}
+function reverseBytes(bytes) {
+  const out = new Uint8Array(bytes.length);
+  for (let i = 0;i < bytes.length; i++) {
+    out[i] = bytes[bytes.length - 1 - i];
+  }
+  return out;
+}
+
+class BtcReader {
+  data;
+  view;
+  offset = 0;
+  constructor(data) {
+    this.data = data;
+    this.view = new DataView(data.buffer, data.byteOffset, data.byteLength);
+  }
+  get length() {
+    return this.data.length;
+  }
+  readUInt8() {
+    const v = this.view.getUint8(this.offset);
+    this.offset += 1;
+    return v;
+  }
+  peekUInt8() {
+    return this.view.getUint8(this.offset);
+  }
+  readUInt32LE() {
+    const v = this.view.getUint32(this.offset, true);
+    this.offset += 4;
+    return v;
+  }
+  readUInt64LE() {
+    const v = this.view.getBigUint64(this.offset, true);
+    this.offset += 8;
+    return v;
+  }
+  readBytes(n) {
+    if (this.offset + n > this.data.length) {
+      throw new Error(`Bitcoin tx underflow: need ${n} bytes at offset ${this.offset}, have ${this.data.length}`);
+    }
+    const slice = this.data.slice(this.offset, this.offset + n);
+    this.offset += n;
+    return slice;
+  }
+  readVarInt() {
+    const first = this.readUInt8();
+    if (first < 253)
+      return first;
+    if (first === 253) {
+      const v = this.view.getUint16(this.offset, true);
+      this.offset += 2;
+      return v;
+    }
+    if (first === 254) {
+      return this.readUInt32LE();
+    }
+    const big = this.readUInt64LE();
+    if (big > BigInt(Number.MAX_SAFE_INTEGER)) {
+      throw new Error("Bitcoin varint exceeds safe integer range");
+    }
+    return Number(big);
+  }
+}
+function scanTx(rawTx) {
+  const r = new BtcReader(rawTx);
+  const version = r.readUInt32LE();
+  let hasWitness = false;
+  if (r.peekUInt8() === 0) {
+    r.readUInt8();
+    const flag = r.readUInt8();
+    if (flag !== 1) {
+      throw new Error(`Unexpected SegWit flag 0x${flag.toString(16)}`);
+    }
+    hasWitness = true;
+  }
+  const bodyStart = r.offset;
+  const inputCount = r.readVarInt();
+  const inputs = [];
+  for (let i = 0;i < inputCount; i++) {
+    const prevTxid = r.readBytes(32);
+    const vout = r.readUInt32LE();
+    const scriptSig = r.readBytes(r.readVarInt());
+    const sequence = r.readUInt32LE();
+    inputs.push({ prevTxid, vout, scriptSig, sequence });
+  }
+  const outputCount = r.readVarInt();
+  const outputs = [];
+  for (let i = 0;i < outputCount; i++) {
+    const value = r.readUInt64LE();
+    const scriptPubKey = r.readBytes(r.readVarInt());
+    outputs.push({ value, scriptPubKey });
+  }
+  const bodyEnd = r.offset;
+  if (hasWitness) {
+    for (let i = 0;i < inputCount; i++) {
+      const itemCount = r.readVarInt();
+      for (let j = 0;j < itemCount; j++) {
+        r.readBytes(r.readVarInt());
+      }
+    }
+  }
+  const locktime = r.readUInt32LE();
+  const legacy = concatBytes(rawTx.slice(0, 4), rawTx.slice(bodyStart, bodyEnd), rawTx.slice(r.offset - 4, r.offset));
+  return { version, hasWitness, inputs, outputs, locktime, legacy };
+}
+function parseBitcoinTx(rawTx) {
+  const s = scanTx(rawTx);
+  return {
+    version: s.version,
+    hasWitness: s.hasWitness,
+    inputs: s.inputs,
+    outputs: s.outputs,
+    locktime: s.locktime,
+    txidInternal: doubleSha256(s.legacy)
+  };
+}
+function stripWitness(rawTx) {
+  return scanTx(rawTx).legacy;
+}
+function bitcoinTxid(rawTx, { display = false } = {}) {
+  const txid = doubleSha256(scanTx(rawTx).legacy);
+  return display ? reverseBytes(txid) : txid;
+}
+function parseBlockHeader(header) {
+  if (header.length !== 80) {
+    throw new Error(`Bitcoin block header must be 80 bytes, got ${header.length}`);
+  }
+  const r = new BtcReader(header);
+  const version = r.readUInt32LE();
+  const prevBlock = r.readBytes(32);
+  const merkleRoot = r.readBytes(32);
+  const timestamp = r.readUInt32LE();
+  const bits = r.readUInt32LE();
+  const nonce = r.readUInt32LE();
+  return { version, prevBlock, merkleRoot, timestamp, bits, nonce };
+}
+function blockHash(header, { display = false } = {}) {
+  const hash = doubleSha256(header);
+  return display ? reverseBytes(hash) : hash;
+}
+// src/bitcoin/merkle.ts
+function hashPair(left, right) {
+  return doubleSha256(concatBytes(left, right));
+}
+function nextLevel(level) {
+  const next = [];
+  for (let i = 0;i < level.length; i += 2) {
+    const left = level[i];
+    if (left === undefined)
+      throw new Error("merkle: missing left node");
+    const right = level[i + 1] ?? left;
+    next.push(hashPair(left, right));
+  }
+  return next;
+}
+function merkleRoot(txidsInternal) {
+  if (txidsInternal.length === 0) {
+    throw new Error("merkleRoot: empty tx list");
+  }
+  let level = txidsInternal.slice();
+  while (level.length > 1) {
+    level = nextLevel(level);
+  }
+  const root = level[0];
+  if (root === undefined)
+    throw new Error("merkleRoot: no root");
+  return root;
+}
+function buildMerkleProof(txidsInternal, txIndex) {
+  const txCount = txidsInternal.length;
+  if (txCount === 0) {
+    throw new Error("buildMerkleProof: empty tx list");
+  }
+  if (txIndex < 0 || txIndex >= txCount) {
+    throw new Error(`buildMerkleProof: txIndex ${txIndex} out of range for ${txCount} txs`);
+  }
+  const siblings = [];
+  let index = txIndex;
+  let level = txidsInternal.slice();
+  while (level.length > 1) {
+    const isRight = index % 2 === 1;
+    const siblingIndex = isRight ? index - 1 : index + 1;
+    const self = level[index];
+    if (self === undefined)
+      throw new Error("buildMerkleProof: missing node");
+    siblings.push(level[siblingIndex] ?? self);
+    level = nextLevel(level);
+    index = Math.floor(index / 2);
+  }
+  return { siblings, txIndex, txCount };
+}
+function rootFromProof(leafInternal, proof) {
+  let hash = leafInternal;
+  let index = proof.txIndex;
+  for (const sibling of proof.siblings) {
+    hash = index % 2 === 1 ? hashPair(sibling, hash) : hashPair(hash, sibling);
+    index = Math.floor(index / 2);
+  }
+  return hash;
+}
+
+// src/bitcoin/proof.ts
+function normalizeTxid(txid) {
+  return without0x(txid).toLowerCase();
+}
+async function buildTxProof(source, params) {
+  const { txid, vout } = params;
+  const want = normalizeTxid(txid);
+  const [rawTx, block] = await Promise.all([
+    source.getRawTx(txid),
+    source.getBlockForTx(txid)
+  ]);
+  const parsed = parseBitcoinTx(rawTx);
+  const gotDisplay = bytesToHex(reverseBytes(parsed.txidInternal));
+  if (gotDisplay !== want) {
+    throw new Error(`source returned a tx whose id ${gotDisplay} does not match requested ${want}`);
+  }
+  const atIndex = block.txidsInternal[block.txIndex];
+  if (!atIndex || bytesToHex(atIndex) !== bytesToHex(parsed.txidInternal)) {
+    throw new Error(`source txIndex ${block.txIndex} does not point at tx ${want}`);
+  }
+  const merkle = buildMerkleProof(block.txidsInternal, block.txIndex);
+  const headerRoot = parseBlockHeader(block.header).merkleRoot;
+  const computed = rootFromProof(parsed.txidInternal, merkle);
+  if (bytesToHex(computed) !== bytesToHex(headerRoot)) {
+    throw new Error("constructed merkle proof does not reconcile with the block header merkle root");
+  }
+  return {
+    rawTx,
+    txidInternal: parsed.txidInternal,
+    vout,
+    merkle,
+    header: block.header,
+    height: block.height
+  };
+}
+function fallbackProofSource(sources) {
+  if (sources.length === 0) {
+    throw new Error("fallbackProofSource: at least one source is required");
+  }
+  async function firstSuccess(fn) {
+    let lastError;
+    for (const source of sources) {
+      try {
+        return await fn(source);
+      } catch (error) {
+        lastError = error;
+      }
+    }
+    throw lastError;
+  }
+  return {
+    getRawTx: (txid) => firstSuccess((s) => s.getRawTx(txid)),
+    getBlockForTx: (txid) => firstSuccess((s) => s.getBlockForTx(txid))
+  };
+}
+function bitcoinRpcSource(config) {
+  const doFetch = config.fetch ?? fetch;
+  async function rpc(method, rpcParams) {
+    const headers = {
+      "content-type": "application/json"
+    };
+    if (config.auth) {
+      const basic = typeof config.auth === "string" ? config.auth : btoa(`${config.auth.username}:${config.auth.password}`);
+      headers.authorization = `Basic ${basic}`;
+    }
+    const res = await doFetch(config.url, {
+      method: "POST",
+      headers,
+      body: JSON.stringify({
+        jsonrpc: "1.0",
+        id: "secondlayer",
+        method,
+        params: rpcParams
+      })
+    });
+    if (!res.ok) {
+      throw new Error(`bitcoin rpc ${method} failed: HTTP ${res.status}`);
+    }
+    const json = await res.json();
+    if (json.error) {
+      throw new Error(`bitcoin rpc ${method} error: ${json.error.message}`);
+    }
+    return json.result;
+  }
+  return {
+    async getRawTx(txid) {
+      return hexToBytes(await rpc("getrawtransaction", [txid, false]));
+    },
+    async getBlockForTx(txid) {
+      const tx = await rpc("getrawtransaction", [
+        txid,
+        true
+      ]);
+      if (!tx.blockhash) {
+        throw new Error(`tx ${txid} is not in a block (node needs -txindex, or the tx is unconfirmed)`);
+      }
+      const block = await rpc("getblock", [
+        tx.blockhash,
+        1
+      ]);
+      const header = await rpc("getblockheader", [tx.blockhash, false]);
+      const txIndex = block.tx.indexOf(normalizeTxid(txid));
+      if (txIndex < 0) {
+        throw new Error(`tx ${txid} not found in block ${tx.blockhash}`);
+      }
+      return {
+        header: hexToBytes(header),
+        height: block.height,
+        txidsInternal: block.tx.map((t) => reverseBytes(hexToBytes(t))),
+        txIndex
+      };
+    }
+  };
+}
+function esploraSource(config) {
+  const doFetch = config.fetch ?? fetch;
+  const base = config.url.replace(/\/+$/, "");
+  async function get(path) {
+    const res = await doFetch(`${base}${path}`);
+    if (!res.ok) {
+      throw new Error(`esplora GET ${path} failed: HTTP ${res.status}`);
+    }
+    return res;
+  }
+  return {
+    async getRawTx(txid) {
+      return hexToBytes((await (await get(`/tx/${txid}/hex`)).text()).trim());
+    },
+    async getBlockForTx(txid) {
+      const status = await (await get(`/tx/${txid}`)).json();
+      if (!status.status.confirmed) {
+        throw new Error(`tx ${txid} is unconfirmed`);
+      }
+      const blockHashHex = status.status.block_hash;
+      const header = (await (await get(`/block/${blockHashHex}/header`)).text()).trim();
+      const txids = await (await get(`/block/${blockHashHex}/txids`)).json();
+      const txIndex = txids.indexOf(normalizeTxid(txid));
+      if (txIndex < 0) {
+        throw new Error(`tx ${txid} not found in block ${blockHashHex}`);
+      }
+      return {
+        header: hexToBytes(header),
+        height: status.status.block_height,
+        txidsInternal: txids.map((t) => reverseBytes(hexToBytes(t))),
+        txIndex
+      };
+    }
+  };
+}
+// src/bitcoin/codec.ts
+function merkleDepth(txCount) {
+  let depth = 0;
+  let n = txCount;
+  while (n > 1) {
+    n = Math.ceil(n / 2);
+    depth++;
+  }
+  return depth;
+}
+var MAX_SIBLINGS = 24;
+function assertHash32(bytes, label) {
+  if (bytes.length !== 32) {
+    throw new Error(`${label} must be 32 bytes, got ${bytes.length}`);
+  }
+}
+function encodeMerkleProofArgs(params) {
+  const { leaf, root, proof } = params;
+  assertHash32(leaf, "merkle leaf");
+  assertHash32(root, "merkle root");
+  if (proof.txIndex < 0 || proof.txIndex >= proof.txCount) {
+    throw new Error(`tx-index ${proof.txIndex} out of range for tx-count ${proof.txCount}`);
+  }
+  if (proof.siblings.length > MAX_SIBLINGS) {
+    throw new Error(`proof has ${proof.siblings.length} siblings, native verify-merkle-proof caps at ${MAX_SIBLINGS}`);
+  }
+  const expectedDepth = merkleDepth(proof.txCount);
+  if (proof.siblings.length !== expectedDepth) {
+    throw new Error(`proof has ${proof.siblings.length} siblings but tx-count ${proof.txCount} requires exactly ${expectedDepth}`);
+  }
+  for (const [i, sibling] of proof.siblings.entries()) {
+    assertHash32(sibling, `sibling ${i}`);
+  }
+  return [
+    bufferCV(leaf),
+    bufferCV(root),
+    uintCV(proof.txIndex),
+    uintCV(proof.txCount),
+    listCV(proof.siblings.map((s) => bufferCV(s)))
+  ];
+}
+function expectBuffer(cv, label) {
+  if (cv?.type !== "buffer") {
+    throw new Error(`expected ${label} to be a buffer, got ${cv?.type}`);
+  }
+  return hexToBytes(cv.value);
+}
+function decodeTxOutput(cv) {
+  const tuple = cv.type === "ok" ? cv.value : cv;
+  if (tuple.type !== "tuple") {
+    throw new Error(`expected a tuple, got ${tuple.type}`);
+  }
+  const fields = tuple.value;
+  const amount = fields.amount;
+  if (amount?.type !== "uint") {
+    throw new Error(`expected tuple field "amount" to be uint, got ${amount?.type}`);
+  }
+  return {
+    script: expectBuffer(fields.script, 'tuple field "script"'),
+    amount: amount.value,
+    txid: expectBuffer(fields.txid, 'tuple field "txid"')
+  };
+}
+var OP_DUP = 118;
+var OP_HASH160 = 169;
+var OP_EQUALVERIFY = 136;
+var OP_CHECKSIG = 172;
+var OP_EQUAL = 135;
+var OP_RETURN = 106;
+var OP_0 = 0;
+var OP_1 = 81;
+function parseOutputScript(script) {
+  const n = script.length;
+  if (n === 25 && script[0] === OP_DUP && script[1] === OP_HASH160 && script[2] === 20 && script[23] === OP_EQUALVERIFY && script[24] === OP_CHECKSIG) {
+    return { type: "p2pkh", hash: script.slice(3, 23) };
+  }
+  if (n === 23 && script[0] === OP_HASH160 && script[1] === 20 && script[22] === OP_EQUAL) {
+    return { type: "p2sh", hash: script.slice(2, 22) };
+  }
+  if (n === 22 && script[0] === OP_0 && script[1] === 20) {
+    return { type: "p2wpkh", hash: script.slice(2, 22) };
+  }
+  if (n === 34 && script[0] === OP_0 && script[1] === 32) {
+    return { type: "p2wsh", hash: script.slice(2, 34) };
+  }
+  if (n === 34 && script[0] === OP_1 && script[1] === 32) {
+    return { type: "p2tr", hash: script.slice(2, 34) };
+  }
+  if (n >= 1 && script[0] === OP_RETURN) {
+    return { type: "op_return", data: script.slice(1) };
+  }
+  return { type: "unknown" };
+}
+// src/bitcoin/constants.ts
+var SPV_ADAPTER_CONTRACTS = {};
+// src/bitcoin/abi/spvAdapter.ts
+var SPV_ADAPTER_ABI = {
+  functions: [
+    {
+      name: "get-tx-output",
+      access: "read-only",
+      args: [
+        { name: "tx", type: { buff: { length: 4096 } } },
+        { name: "vout", type: "uint128" }
+      ],
+      outputs: {
+        response: {
+          ok: {
+            tuple: [
+              { name: "script", type: { buff: { length: 1024 } } },
+              { name: "amount", type: "uint128" },
+              { name: "txid", type: { buff: { length: 32 } } }
+            ]
+          },
+          error: "uint128"
+        }
+      }
+    },
+    {
+      name: "verify-merkle",
+      access: "read-only",
+      args: [
+        { name: "leaf", type: { buff: { length: 32 } } },
+        { name: "root", type: { buff: { length: 32 } } },
+        { name: "tx-index", type: "uint128" },
+        { name: "tx-count", type: "uint128" },
+        {
+          name: "siblings",
+          type: { list: { type: { buff: { length: 32 } }, length: 24 } }
+        }
+      ],
+      outputs: "bool"
+    },
+    {
+      name: "was-tx-mined",
+      access: "read-only",
+      args: [
+        { name: "header", type: { buff: { length: 80 } } },
+        { name: "height", type: "uint128" },
+        { name: "leaf", type: { buff: { length: 32 } } },
+        { name: "tx-index", type: "uint128" },
+        { name: "tx-count", type: "uint128" },
+        {
+          name: "siblings",
+          type: { list: { type: { buff: { length: 32 } }, length: 24 } }
+        }
+      ],
+      outputs: { response: { ok: "bool", error: "uint128" } }
+    }
+  ]
+};
+// src/bitcoin/activation.ts
+async function getBurnBlockHeight(client) {
+  const info = await client.request("/v2/info");
+  if (typeof info?.burn_block_height !== "number") {
+    throw new Error("could not read burn_block_height from /v2/info");
+  }
+  return info.burn_block_height;
+}
+async function isClarity6Active(client, gate = {}) {
+  if (gate.activationBurnHeight == null) {
+    throw new Error("Clarity 6 (SIP-044 / Epoch 4.0) activation burn height is not yet known — pass { activationBurnHeight } once the vote selects it");
+  }
+  const current = await getBurnBlockHeight(client);
+  return current >= gate.activationBurnHeight;
+}
+// src/bitcoin/verifier.ts
+function clarityToBool(cv) {
+  const value = cv.type === "ok" ? cv.value : cv;
+  if (value.type === "true")
+    return true;
+  if (value.type === "false")
+    return false;
+  throw new Error(`expected a boolean result, got ${value.type}`);
+}
+function bitcoinVerifier(client, config) {
+  const { contract, sender } = config;
+  async function verifyMerkleProof(input) {
+    const args = encodeMerkleProofArgs(input);
+    const result = await readContract(client, {
+      contract,
+      functionName: "verify-merkle",
+      args,
+      sender
+    });
+    return clarityToBool(result);
+  }
+  return {
+    verifyMerkleProof,
+    verifySpvProof(proof) {
+      const root = parseBlockHeader(proof.header).merkleRoot;
+      return verifyMerkleProof({
+        leaf: proof.txidInternal,
+        root,
+        proof: proof.merkle
+      });
+    },
+    async wasTxMined(proof) {
+      const result = await readContract(client, {
+        contract,
+        functionName: "was-tx-mined",
+        args: [
+          bufferCV(proof.header),
+          uintCV(proof.height),
+          bufferCV(proof.txidInternal),
+          uintCV(proof.merkle.txIndex),
+          uintCV(proof.merkle.txCount),
+          listCV(proof.merkle.siblings.map((s) => bufferCV(s)))
+        ],
+        sender
+      });
+      if (result.type === "err")
+        return false;
+      return clarityToBool(result);
+    },
+    async getTxOutput(rawTx, vout) {
+      const result = await readContract(client, {
+        contract,
+        functionName: "get-tx-output",
+        args: [bufferCV(rawTx), uintCV(vout)],
+        sender
+      });
+      if (result.type === "err") {
+        throw new Error(`get-tx-output failed on-chain: ${JSON.stringify(result.value)}`);
+      }
+      return decodeTxOutput(result);
+    }
+  };
+}
+// src/bitcoin/address.ts
+var NETWORK_PARAMS = {
+  mainnet: { p2pkh: 0, p2sh: 5, hrp: "bc" },
+  testnet: { p2pkh: 111, p2sh: 196, hrp: "tb" }
+};
+function base58Check(version, payload) {
+  const data = concatBytes(Uint8Array.of(version), payload);
+  const checksum = doubleSha256(data).slice(0, 4);
+  return base58.encode(concatBytes(data, checksum));
+}
+function formatBitcoinAddress(parsed, network = "mainnet") {
+  const params = NETWORK_PARAMS[network];
+  const hash = parsed.hash;
+  if (!hash)
+    return;
+  switch (parsed.type) {
+    case "p2pkh":
+      return base58Check(params.p2pkh, hash);
+    case "p2sh":
+      return base58Check(params.p2sh, hash);
+    case "p2wpkh":
+    case "p2wsh":
+      return bech32.encode(params.hrp, [0, ...bech32.toWords(hash)]);
+    case "p2tr":
+      return bech32m.encode(params.hrp, [1, ...bech32m.toWords(hash)]);
+    default:
+      return;
+  }
+}
+// src/bitcoin/actions.ts
+async function verifyBitcoinPayment(client, params) {
+  const {
+    contract,
+    vout,
+    network = "mainnet",
+    expect,
+    authenticateHeader = true,
+    sender
+  } = params;
+  const proof = "proof" in params ? params.proof : await buildTxProof(params.source, { txid: params.txid, vout });
+  const verifier = bitcoinVerifier(client, { contract, sender });
+  const mined = authenticateHeader ? await verifier.wasTxMined(proof) : await verifier.verifySpvProof(proof);
+  const parsedTx = parseBitcoinTx(proof.rawTx);
+  const out = parsedTx.outputs[vout];
+  if (!out) {
+    throw new Error(`vout ${vout} out of range (tx has ${parsedTx.outputs.length} outputs)`);
+  }
+  const parsedScript = parseOutputScript(out.scriptPubKey);
+  const address = formatBitcoinAddress(parsedScript, network);
+  const output = {
+    vout,
+    script: out.scriptPubKey,
+    amount: out.value,
+    type: parsedScript.type,
+    address
+  };
+  const amountOk = expect?.amount === undefined || out.value === expect.amount;
+  const addressOk = expect?.address === undefined || address === expect.address;
+  const verified = mined && amountOk && addressOk;
+  return { verified, mined, output, proof };
+}
+
+//# debugId=1FFA7B1EF14A3F8864756E2164756E21
+//# sourceMappingURL=index.cjs.map