fractal-pqc 0.3.0

package/src/bech32.mjs

@@ -0,0 +1,123 @@
+// SPDX-License-Identifier: MIT
+//
+// bech32 / bech32m (BIP-173 / BIP-350) + SegWit address encode/decode.
+// Reference implementation (derived from the BIP-173 public-domain reference),
+// used to derive REAL Bitcoin addresses (P2WPKH `bc1q…`, P2TR `bc1p…`).
+// Validated against the official BIP-350 test vectors in test/vectors.mjs.
+
+const CHARSET = "qpzry9x8gf2tvdw0s3jn54khce6mua7l";
+const GENERATOR = [0x3b6a57b2, 0x26508e6d, 0x1ea119fa, 0x3d4233dd, 0x2a1462b3];
+
+export const ENCODING = { BECH32: "bech32", BECH32M: "bech32m" };
+const CONST = { bech32: 1, bech32m: 0x2bc830a3 };
+
+function polymod(values) {
+  let chk = 1;
+  for (const v of values) {
+    const top = chk >> 25;
+    chk = ((chk & 0x1ffffff) << 5) ^ v;
+    for (let i = 0; i < 5; i++) if ((top >> i) & 1) chk ^= GENERATOR[i];
+  }
+  return chk;
+}
+
+function hrpExpand(hrp) {
+  const out = [];
+  for (let i = 0; i < hrp.length; i++) out.push(hrp.charCodeAt(i) >> 5);
+  out.push(0);
+  for (let i = 0; i < hrp.length; i++) out.push(hrp.charCodeAt(i) & 31);
+  return out;
+}
+
+function verifyChecksum(hrp, data, spec) {
+  return polymod(hrpExpand(hrp).concat(data)) === CONST[spec];
+}
+
+function createChecksum(hrp, data, spec) {
+  const values = hrpExpand(hrp).concat(data).concat([0, 0, 0, 0, 0, 0]);
+  const mod = polymod(values) ^ CONST[spec];
+  const out = [];
+  for (let i = 0; i < 6; i++) out.push((mod >> (5 * (5 - i))) & 31);
+  return out;
+}
+
+export function bech32Encode(hrp, data, spec) {
+  const combined = data.concat(createChecksum(hrp, data, spec));
+  let out = hrp + "1";
+  for (const d of combined) out += CHARSET.charAt(d);
+  return out;
+}
+
+export function bech32Decode(bechStr) {
+  if (bechStr.length > 90) return null;
+  // BIP-173: every character must be printable ASCII [33,126]. The CHARSET lookup only
+  // guards the data section; the HRP must be range-checked explicitly or a control/high
+  // byte in the HRP with a valid checksum would be wrongly accepted.
+  for (let i = 0; i < bechStr.length; i++) {
+    const c = bechStr.charCodeAt(i);
+    if (c < 33 || c > 126) return null;
+  }
+  const lower = bechStr.toLowerCase();
+  const upper = bechStr.toUpperCase();
+  if (bechStr !== lower && bechStr !== upper) return null; // mixed case
+  const str = lower;
+  const pos = str.lastIndexOf("1");
+  if (pos < 1 || pos + 7 > str.length) return null;
+  const hrp = str.slice(0, pos);
+  const data = [];
+  for (let i = pos + 1; i < str.length; i++) {
+    const d = CHARSET.indexOf(str.charAt(i));
+    if (d === -1) return null;
+    data.push(d);
+  }
+  for (const spec of [ENCODING.BECH32, ENCODING.BECH32M]) {
+    if (verifyChecksum(hrp, data, spec)) return { hrp, data: data.slice(0, -6), spec };
+  }
+  return null;
+}
+
+// Base conversion between bit groups (e.g. 8-bit bytes -> 5-bit groups).
+export function convertBits(data, fromBits, toBits, pad) {
+  let acc = 0, bits = 0;
+  const out = [];
+  const maxv = (1 << toBits) - 1;
+  const maxAcc = (1 << (fromBits + toBits - 1)) - 1;
+  for (const value of data) {
+    if (value < 0 || value >> fromBits) return null;
+    acc = ((acc << fromBits) | value) & maxAcc;
+    bits += fromBits;
+    while (bits >= toBits) { bits -= toBits; out.push((acc >> bits) & maxv); }
+  }
+  if (pad) { if (bits) out.push((acc << (toBits - bits)) & maxv); }
+  else if (bits >= fromBits || ((acc << (toBits - bits)) & maxv)) return null;
+  return out;
+}
+
+/**
+ * Encode a SegWit address. witver 0 uses bech32; witver 1+ uses bech32m (BIP-350).
+ * @param {string} hrp "bc" (mainnet), "tb" (testnet), "bcrt" (regtest)
+ * @param {number} witver witness version (0..16)
+ * @param {Uint8Array} program witness program bytes (20 for v0 P2WPKH, 32 for v1 P2TR)
+ */
+export function segwitEncode(hrp, witver, program) {
+  const spec = witver === 0 ? ENCODING.BECH32 : ENCODING.BECH32M;
+  const five = convertBits(Array.from(program), 8, 5, true);
+  if (five === null) return null;
+  const addr = bech32Encode(hrp, [witver].concat(five), spec);
+  return segwitDecode(hrp, addr) ? addr : null; // round-trip sanity
+}
+
+/** Decode+validate a SegWit address; returns {version, program} or null. */
+export function segwitDecode(hrp, addr) {
+  const dec = bech32Decode(addr);
+  if (!dec || dec.hrp !== hrp || dec.data.length < 1) return null;
+  const witver = dec.data[0];
+  const program = convertBits(dec.data.slice(1), 5, 8, false);
+  if (program === null || program.length < 2 || program.length > 40) return null;
+  if (witver > 16) return null;
+  if (witver === 0 && program.length !== 20 && program.length !== 32) return null;
+  // BIP-350: v0 must be bech32, v1+ must be bech32m.
+  if (witver === 0 && dec.spec !== ENCODING.BECH32) return null;
+  if (witver !== 0 && dec.spec !== ENCODING.BECH32M) return null;
+  return { version: witver, program: Uint8Array.from(program) };
+}

package/src/bitcoin.mjs

@@ -0,0 +1,134 @@
+// SPDX-License-Identifier: MIT
+//
+// pqc-migration-kit/bitcoin — REAL Bitcoin Taproot (BIP-340 Schnorr) primitives plus
+// a post-quantum recovery commitment for a Taproot output (P2QRH-style).
+//
+// This is the module that turns "we have zero secp256k1/Taproot" into a concrete,
+// test-vector-verified capability:
+//   • Real BIP-340 Schnorr over secp256k1 (Bitcoin's Taproot signature scheme),
+//     validated against the OFFICIAL BIP-340 test vector — i.e. byte-for-byte
+//     consensus-correct, not an approximation.
+//   • A quantum-recovery commitment binding a Taproot x-only output key to an
+//     ML-DSA-65 (FIPS-204) key, dual-signed (Schnorr + PQC). A Taproot holder can
+//     publish this today so that, at/after Q-day, control is provable via the PQC key.
+//
+// HONEST SCOPE: this handles Bitcoin KEYS and SIGNATURES (real) and a migration
+// commitment (real). It does NOT yet build/broadcast Bitcoin transactions, parse
+// UTXOs, or define a soft-fork output type — that is the grant-funded roadmap in
+// README.md. We claim exactly what the code does: Bitcoin-correct Schnorr + a
+// dual-signed PQC recovery commitment.
+
+import { schnorr } from "@noble/curves/secp256k1.js";
+import { ml_dsa65 } from "@noble/post-quantum/ml-dsa.js";
+import { sha3_256 } from "@noble/hashes/sha3.js";
+
+const enc = new TextEncoder();
+const COMMIT_DOMAIN = enc.encode("FRACTAL-BTC-TAPROOT-PQC-RECOVERY-v1");
+
+function u32be(n) {
+  const b = new Uint8Array(4);
+  new DataView(b.buffer).setUint32(0, n >>> 0, false);
+  return b;
+}
+function canonical(domain, fields) {
+  const parts = [u32be(domain.length), domain];
+  for (const f of fields) parts.push(u32be(f.length), f);
+  let total = 0; for (const p of parts) total += p.length;
+  const out = new Uint8Array(total); let o = 0;
+  for (const p of parts) { out.set(p, o); o += p.length; }
+  return out;
+}
+const toHex = (b) => Buffer.from(b).toString("hex");
+const fromHex = (h) => Uint8Array.from(Buffer.from(h, "hex"));
+
+// ── Real Taproot key + BIP-340 Schnorr ─────────────────────────────────────────
+
+/** A Taproot key pair: 32-byte x-only public key (Bitcoin Taproot output key form). */
+export function generateTaprootKey() {
+  const kp = schnorr.keygen();
+  const publicKey = kp.publicKey ?? schnorr.getPublicKey(kp.secretKey);
+  return { secretKey: kp.secretKey, xOnlyPub: publicKey };
+}
+
+/** BIP-340 Schnorr sign over a 32-byte message (e.g. a Taproot sighash). */
+export function taprootSign(secretKey, msg32) {
+  return schnorr.sign(msg32, secretKey);
+}
+
+/** BIP-340 Schnorr verify. Same signature Bitcoin consensus uses for Taproot. */
+export function taprootVerify(sig, msg32, xOnlyPub) {
+  try { return schnorr.verify(sig, msg32, xOnlyPub); } catch { return false; }
+}
+
+// Official BIP-340 test vector (index 1). If this fails, our Schnorr is NOT
+// Bitcoin-compatible — so we assert it in the test suite as a consensus check.
+export const BIP340_VECTOR_1 = {
+  pubkey: "DFF1D77F2A671C5F36183726DB2341BE58FEAE1DA2DECED843240F7B502BA659",
+  message: "243F6A8885A308D313198A2E03707344A4093822299F31D0082EFA98EC4E6C89",
+  signature:
+    "6896BD60EEAE296DB48A229FF71DFE071BDE413E6D43F917DC8DCF8C78DE33418906D11AC976ABCCB20B091292BFF4EA897EFCB639EA871CFA95F6DE339E4B0A",
+};
+
+/** Returns true iff our Schnorr verifier accepts the official BIP-340 vector. */
+export function verifiesBip340OfficialVector() {
+  return taprootVerify(
+    fromHex(BIP340_VECTOR_1.signature),
+    fromHex(BIP340_VECTOR_1.message),
+    fromHex(BIP340_VECTOR_1.pubkey),
+  );
+}
+
+// ── Taproot → PQC quantum-recovery commitment (P2QRH-style) ────────────────────
+
+/**
+ * Bind a Taproot output key to a post-quantum ML-DSA-65 key with a DUAL signature.
+ * The Taproot key signs (proving current control of the UTXO's key) and the PQC key
+ * signs (proving possession of the recovery key). Publishing this commitment lets a
+ * holder prove, after secp256k1 is broken, that THEY pre-registered the successor key
+ * — the honest first building block of a Bitcoin quantum-migration path.
+ */
+export function createTaprootPqcCommitment(taproot, pqIdentity) {
+  const msg = canonical(COMMIT_DOMAIN, [taproot.xOnlyPub, pqIdentity.pqPublic]);
+  const taprootSig = schnorr.sign(sha3_256(msg), taproot.secretKey); // 32-byte digest
+  const pqSig = ml_dsa65.sign(msg, pqIdentity.pqSecret);
+  return {
+    version: "btc-taproot-pqc-recovery-v1",
+    taprootXOnlyPub: toHex(taproot.xOnlyPub),
+    pqPublic: toHex(pqIdentity.pqPublic),
+    taprootSig: toHex(taprootSig),
+    pqSig: toHex(pqSig),
+    factHash: toHex(sha3_256(msg)),
+  };
+}
+
+/**
+ * Verify a Taproot→PQC recovery commitment: BOTH signatures must verify over the same
+ * canonical binding.
+ *
+ * ⚠️ Like the migration envelope, well-formedness ≠ security. A classical-key attacker
+ * (post-Shor) can build a well-formed cert binding the victim's Taproot key to the
+ * attacker's OWN PQC key. For the recovery property you MUST pass `opts.anchoredFactHash`
+ * — the factHash of the holder's first-seen, immutably anchored commitment — which the
+ * verifier pins; a rebound cert has a different factHash and is rejected.
+ *
+ * @param {object} cert
+ * @param {{anchoredFactHash?: string}} [opts]
+ */
+export function verifyTaprootPqcCommitment(cert, opts = {}) {
+  try {
+    const xOnly = fromHex(cert.taprootXOnlyPub);
+    const pqPublic = fromHex(cert.pqPublic);
+    const msg = canonical(COMMIT_DOMAIN, [xOnly, pqPublic]);
+    const taprootOk = taprootVerify(fromHex(cert.taprootSig), sha3_256(msg), xOnly);
+    const pqOk = ml_dsa65.verify(fromHex(cert.pqSig), msg, pqPublic);
+    const computedFact = toHex(sha3_256(msg));
+    const factOk = cert.factHash === computedFact;
+    const wellFormed = taprootOk && pqOk && factOk;
+    const anchorOk = opts.anchoredFactHash == null ? null : (computedFact === opts.anchoredFactHash);
+    return { valid: wellFormed && anchorOk !== false, wellFormed, taprootOk, pqOk, factOk, anchorOk };
+  } catch (err) {
+    return { valid: false, wellFormed: false, taprootOk: false, pqOk: false, factOk: false, anchorOk: false, error: String(err) };
+  }
+}
+
+export const _internal = { canonical, COMMIT_DOMAIN, toHex, fromHex };

package/src/broadcast.mjs

@@ -0,0 +1,117 @@
+// SPDX-License-Identifier: MIT
+//
+// Testnet broadcaster for P2TR key-path spends. Fetches UTXOs + fee rate for a funded
+// address, builds + signs the spend with the kit, and (optionally) broadcasts via a
+// public Esplora-style API (mempool.space / blockstream.info).
+//
+// Default is DRY-RUN: it returns the signed tx hex + txid WITHOUT sending. Pass
+// { broadcast: true } to actually publish. Live broadcast requires a real funded UTXO
+// on the chosen network — this module never invents funds.
+
+import { generateTaprootKey } from "./bitcoin.mjs";
+import { p2trAddress, addressToScriptPubKey, taprootTweakOutputKey } from "./address.mjs";
+import { p2trScriptPubKey } from "./tx.mjs";
+import { selectCoins } from "./fees.mjs";
+import { createPsbt, signPsbtTaprootKeyPath, finalizePsbt } from "./psbt.mjs";
+import { schnorr } from "@noble/curves/secp256k1.js";
+
+const NETWORKS = {
+  tb: { hrp: "tb", api: "https://mempool.space/testnet/api", explorer: "https://mempool.space/testnet" },
+  bc: { hrp: "bc", api: "https://mempool.space/api", explorer: "https://mempool.space" },
+  signet: { hrp: "tb", api: "https://mempool.space/signet/api", explorer: "https://mempool.space/signet" },
+  // Mutinynet: a public custom signet (30s blocks) with a fast Esplora — same Bitcoin
+  // consensus + tb1 address format, ideal for a quick end-to-end demo.
+  mutinynet: { hrp: "tb", api: "https://mutinynet.com/api", explorer: "https://mutinynet.com" },
+};
+
+function net(network = "tb") {
+  const n = NETWORKS[network];
+  if (!n) throw new Error(`unknown network '${network}' (tb | bc | signet)`);
+  return n;
+}
+
+async function getJson(url) {
+  const res = await fetch(url);
+  if (!res.ok) throw new Error(`GET ${url} → ${res.status} ${await res.text().catch(() => "")}`);
+  return res.json();
+}
+
+/** Fetch confirmed+unconfirmed UTXOs for an address (Esplora `/address/:a/utxo`). */
+export async function fetchUtxos(address, { network = "tb", apiBase } = {}) {
+  const base = apiBase || net(network).api;
+  const list = await getJson(`${base}/address/${address}/utxo`);
+  return list.map((u) => ({ txid: u.txid, vout: u.vout, valueSats: u.value, status: u.status }));
+}
+
+/** Recommended fee rate (sat/vB). Falls back to 1 on parse issues. */
+export async function fetchFeeRate({ network = "tb", apiBase, tier = "halfHourFee" } = {}) {
+  const base = apiBase || net(network).api;
+  const j = await getJson(`${base}/v1/fees/recommended`);
+  return Math.max(1, Math.ceil(j[tier] ?? j.hourFee ?? 1));
+}
+
+/** Broadcast a raw tx hex (Esplora `POST /tx`). Returns the txid. */
+export async function broadcastTx(rawHex, { network = "tb", apiBase } = {}) {
+  const base = apiBase || net(network).api;
+  const res = await fetch(`${base}/tx`, { method: "POST", body: rawHex });
+  const text = await res.text();
+  if (!res.ok) throw new Error(`broadcast rejected (${res.status}): ${text}`);
+  return text.trim(); // Esplora returns the txid as plaintext
+}
+
+export const explorerTxUrl = (txid, network = "tb") => `${net(network).explorer}/tx/${txid}`;
+export const explorerAddrUrl = (addr, network = "tb") => `${net(network).explorer}/address/${addr}`;
+
+/**
+ * Build (and optionally broadcast) a P2TR key-path spend from a funded Taproot address.
+ *
+ * @param {object} opts
+ * @param {Uint8Array} opts.internalPriv 32-byte Taproot internal private key (sender)
+ * @param {string} opts.to destination address (any SegWit address on the network)
+ * @param {number} opts.amountSats amount to send
+ * @param {"tb"|"bc"|"signet"} [opts.network="tb"]
+ * @param {number} [opts.feeRate] sat/vB; if omitted, fetched from the network
+ * @param {Array} [opts.utxos] override UTXOs (otherwise fetched for the sender address)
+ * @param {boolean} [opts.broadcast=false] actually publish (default: dry-run)
+ * @param {string} [opts.apiBase] override the Esplora API base
+ * @returns {Promise<{fromAddress,toScriptPubKey,inputs,fee,changeSats,hex,txid,vsize,broadcasted,explorer}>}
+ */
+export async function sendP2trKeyPath(opts) {
+  const { internalPriv, to, amountSats, network = "tb", broadcast = false, apiBase } = opts;
+  if (!(internalPriv instanceof Uint8Array) || internalPriv.length !== 32) throw new Error("internalPriv must be a 32-byte key");
+  const n = net(network);
+  const internalXOnly = schnorr.getPublicKey(internalPriv);
+  const fromAddress = p2trAddress(internalXOnly, n.hrp);
+  const senderSpk = p2trScriptPubKey(taprootTweakOutputKey(internalXOnly));
+  const toSpk = addressToScriptPubKey(to, n.hrp);
+
+  const feeRate = opts.feeRate ?? (await fetchFeeRate({ network, apiBase }));
+  const utxos = opts.utxos ?? (await fetchUtxos(fromAddress, { network, apiBase }));
+  if (!utxos.length) throw new Error(`no UTXOs for ${fromAddress} — fund it first (${explorerAddrUrl(fromAddress, network)})`);
+
+  const sel = selectCoins(utxos, amountSats, feeRate);
+  const outputs = [{ valueSats: amountSats, scriptPubKey: toSpk }];
+  if (sel.hasChange) outputs.push({ valueSats: sel.changeSats, scriptPubKey: senderSpk }); // change → self
+  const tx = {
+    version: 2, locktime: 0,
+    inputs: sel.inputs.map((u) => ({ txid: u.txid, vout: u.vout, sequence: 0xfffffffd })),
+    outputs,
+  };
+  const meta = sel.inputs.map(() => ({ witnessUtxo: { valueSats: 0, scriptPubKey: senderSpk }, tapInternalKey: internalXOnly }));
+  // fill real spent amounts (needed by the BIP-341 sighash)
+  sel.inputs.forEach((u, i) => { meta[i].witnessUtxo.valueSats = u.valueSats; });
+
+  const psbt = createPsbt(tx, meta);
+  signPsbtTaprootKeyPath(psbt, sel.inputs.map(() => internalPriv));
+  const fin = finalizePsbt(psbt);
+
+  let broadcasted = false;
+  if (broadcast) { await broadcastTx(fin.hex, { network, apiBase }); broadcasted = true; }
+  return {
+    fromAddress, toScriptPubKey: Buffer.from(toSpk).toString("hex"),
+    inputs: sel.inputs.length, fee: sel.fee, changeSats: sel.changeSats, vsize: sel.vsize,
+    hex: fin.hex, txid: fin.txid, broadcasted, explorer: explorerTxUrl(fin.txid, network),
+  };
+}
+
+export { generateTaprootKey };

package/src/fees.mjs

@@ -0,0 +1,84 @@
+// SPDX-License-Identifier: MIT
+//
+// Fee estimation + coin selection for P2TR (Taproot key-path) spends.
+// Weights follow BIP-141 (segwit) / BIP-341: vsize = ceil(weight/4),
+// weight = base_bytes*4 + witness_bytes.
+//
+// Per-element sizes (key-path P2TR, SIGHASH_DEFAULT 64-byte sig):
+//   tx overhead   base 4(version)+1(nin)+1(nout)+4(locktime)=10 ; witness 2(marker+flag)
+//   P2TR input    base 36(outpoint)+1(empty scriptSig)+4(sequence)=41 ; witness 1+1+64=66
+//   P2TR output   base 8(value)+1(len)+34(OP_1 PUSH32)=43
+//   P2WPKH output base 8+1+22=31   (for change to a bech32 v0 addr, if used)
+
+export const VSIZE = {
+  OVERHEAD_BASE: 10,
+  OVERHEAD_WITNESS: 2,
+  P2TR_IN_BASE: 41,
+  P2TR_IN_WITNESS: 66,
+  P2TR_OUT: 43,
+  P2WPKH_OUT: 31,
+};
+
+const DUST_P2TR = 330; // sats; a P2TR output below this is non-standard (dust)
+
+/** Estimated virtual size (vB) for an all-P2TR-input tx with the given output count. */
+export function estimateP2trVsize(numInputs, numP2trOutputs) {
+  const base = VSIZE.OVERHEAD_BASE + VSIZE.P2TR_IN_BASE * numInputs + VSIZE.P2TR_OUT * numP2trOutputs;
+  const witness = VSIZE.OVERHEAD_WITNESS + VSIZE.P2TR_IN_WITNESS * numInputs;
+  const weight = base * 4 + witness;
+  return Math.ceil(weight / 4);
+}
+
+/** Fee in sats for a vsize at a given fee rate (sat/vB), rounded up. */
+export function feeForVsize(vsize, feeRateSatPerVb) {
+  return Math.ceil(vsize * feeRateSatPerVb);
+}
+
+/**
+ * Accumulative (largest-first) coin selection for a single P2TR recipient output plus an
+ * optional P2TR change output. All amounts in sats.
+ *
+ * @param {Array<{txid:string, vout:number, valueSats:number|bigint}>} utxos available UTXOs
+ * @param {number|bigint} targetSats amount to send to the recipient
+ * @param {number} feeRateSatPerVb fee rate
+ * @param {number} [dust=330] dust threshold for the change output
+ * @returns {{inputs:Array, fee:number, changeSats:number, hasChange:boolean, vsize:number}}
+ * @throws if funds are insufficient to cover target + fee
+ */
+export function selectCoins(utxos, targetSats, feeRateSatPerVb, dust = DUST_P2TR) {
+  const target = BigInt(targetSats);
+  if (target <= 0n) throw new Error("targetSats must be positive");
+  if (!(feeRateSatPerVb > 0)) throw new Error("feeRateSatPerVb must be positive");
+  // Guard against silent Number() precision loss on return (real BTC ≪ 2^53 sats).
+  const MAX = BigInt(Number.MAX_SAFE_INTEGER);
+  if (target > MAX) throw new Error("targetSats exceeds MAX_SAFE_INTEGER");
+  for (const u of utxos) if (BigInt(u.valueSats) > MAX) throw new Error("utxo valueSats exceeds MAX_SAFE_INTEGER");
+  const sorted = [...utxos].sort((a, b) => {
+    const x = BigInt(a.valueSats), y = BigInt(b.valueSats);
+    return y > x ? 1 : y < x ? -1 : 0; // largest-first, stable for equal values
+  });
+
+  const chosen = [];
+  let sum = 0n;
+  for (const u of sorted) {
+    chosen.push(u);
+    sum += BigInt(u.valueSats);
+    // Try WITH change first (recipient + change = 2 outputs).
+    const vsizeWithChange = estimateP2trVsize(chosen.length, 2);
+    const feeWithChange = BigInt(feeForVsize(vsizeWithChange, feeRateSatPerVb));
+    const change = sum - target - feeWithChange;
+    if (change >= BigInt(dust)) {
+      return { inputs: chosen, fee: Number(feeWithChange), changeSats: Number(change), hasChange: true, vsize: vsizeWithChange };
+    }
+    // A dust-free change output isn't viable (change < dust). If we can still cover a
+    // changeless tx, take it and fold the sub-dust remainder into the fee — never create
+    // a dust output, and never falsely reject fundable UTXOs (the earlier extra guard
+    // `remainder < dust` rejected valid changeless spends when the remainder was ≥ dust).
+    const vsizeNoChange = estimateP2trVsize(chosen.length, 1);
+    const feeNoChange = BigInt(feeForVsize(vsizeNoChange, feeRateSatPerVb));
+    if (sum >= target + feeNoChange) {
+      return { inputs: chosen, fee: Number(sum - target), changeSats: 0, hasChange: false, vsize: vsizeNoChange };
+    }
+  }
+  throw new Error("insufficient funds for target + fee");
+}

package/src/index.mjs

@@ -0,0 +1,59 @@
+// SPDX-License-Identifier: MIT
+//
+// fractal-pqc — SDK entry point.
+//
+// Programmatic surface for quantum-safe migration of a Bitcoin-style key:
+// bind secp256k1 / Taproot to ML-DSA-65 (FIPS-204) and require a post-quantum
+// signature to authorize. Real primitives, honestly scoped (see README).
+//
+//   import {
+//     generateMigrationIdentity, createMigrationCommitment, verifyMigrationCommitment,
+//     authorizeSpend, verifySpend,
+//     generateTaprootKey, taprootSign, taprootVerify, verifiesBip340OfficialVector,
+//     createTaprootPqcCommitment, verifyTaprootPqcCommitment,
+//   } from "fractal-pqc";
+
+export {
+  generateMigrationIdentity,
+  createMigrationCommitment,
+  verifyMigrationCommitment,
+  authorizeSpend,
+  verifySpend,
+} from "./migration-envelope.mjs";
+
+export {
+  generateTaprootKey,
+  taprootSign,
+  taprootVerify,
+  verifiesBip340OfficialVector,
+  createTaprootPqcCommitment,
+  verifyTaprootPqcCommitment,
+  BIP340_VECTOR_1,
+} from "./bitcoin.mjs";
+
+// Real Bitcoin address + transaction layer (BIP-173/350/341).
+export {
+  bech32Encode, bech32Decode, segwitEncode, segwitDecode, convertBits, ENCODING,
+} from "./bech32.mjs";
+export {
+  taprootTweakOutputKey, p2trAddress, p2wpkhAddress, hash160, addressToScriptPubKey,
+} from "./address.mjs";
+// Testnet broadcaster (fetch UTXOs/fees, build+sign, optionally publish).
+export {
+  fetchUtxos, fetchFeeRate, broadcastTx, sendP2trKeyPath, explorerTxUrl, explorerAddrUrl,
+} from "./broadcast.mjs";
+export {
+  serializeLegacy, serializeSegwit, txid, p2trScriptPubKey,
+  taprootKeyPathSighash, taprootTweakPrivateKey, signTaprootKeyPath,
+} from "./tx.mjs";
+
+// Fees + coin selection, and BIP-174 PSBT (P2TR key-path).
+export {
+  estimateP2trVsize, feeForVsize, selectCoins, VSIZE,
+} from "./fees.mjs";
+export {
+  createPsbt, serializePsbt, serializePsbtHex, serializePsbtBase64,
+  parsePsbt, signPsbtTaprootKeyPath, finalizePsbt,
+} from "./psbt.mjs";
+
+export const VERSION = "0.3.0";