fractal-pqc 0.3.0

package/src/migration-envelope.mjs

@@ -0,0 +1,206 @@
+// SPDX-License-Identifier: MIT
+//
+// pqc-migration-kit — Quantum migration envelope for a Bitcoin-style key.
+//
+// PROBLEM (Galaxy "Bitcoin Quantum Readiness"): a large quantum computer running
+// Shor's algorithm can recover a secp256k1 private key from an exposed public key,
+// so any BTC output whose pubkey is on-chain becomes spendable by an attacker.
+// The migration challenge is to let a holder bind their EXISTING classical key to a
+// new post-quantum key and, from then on, require a post-quantum signature to spend —
+// WITHOUT invalidating the history already signed under the classical key.
+//
+// This module is a self-contained, runnable REFERENCE of that mechanism. It is the
+// same "verify-both during migration, no-downgrade" discipline FractalAI already runs
+// in production on its own L1 (crypto-agility layer + on-chain rotation registry),
+// distilled to the secp256k1 -> ML-DSA-65 case relevant to Bitcoin.
+//
+// HONEST SCOPE — read before citing:
+//   • This is a cryptographic reference/demonstrator, NOT deployed on Bitcoin, NOT a
+//     BIP, NOT consensus code. It does not touch the Bitcoin network.
+//   • It uses REAL primitives: @noble/curves secp256k1 (Bitcoin's curve) and
+//     @noble/post-quantum ml_dsa65 (NIST FIPS-204, Category 3). No mocks.
+//   • "Migration window" semantics here = a dual-key commitment + PQC-required
+//     authorization. Turning this into real Bitcoin custody tooling (UTXO/Taproot
+//     integration, P2QRH/BIP-360-style outputs, soft-fork analysis) is exactly the
+//     grant-funded work — see README.
+
+import { secp256k1 } from "@noble/curves/secp256k1.js";
+import { ml_dsa65 } from "@noble/post-quantum/ml-dsa.js";
+import { sha256 } from "@noble/hashes/sha2.js";
+import { sha3_256 } from "@noble/hashes/sha3.js";
+
+// ── Canonical, domain-separated encoding ──────────────────────────────────────
+// Mirrors FractalAI's on-chain signing discipline (VAID-1 / reserve_proof_message):
+// fixed domain tag, length-prefixed fields, big-endian lengths, raw bytes — so the
+// bytes signed are unambiguous and a verifier reconstructs them exactly.
+
+const COMMIT_DOMAIN = new TextEncoder().encode("FRACTAL-PQC-MIGRATION-COMMIT-v1");
+const SPEND_DOMAIN = new TextEncoder().encode("FRACTAL-PQC-MIGRATION-SPEND-v1");
+
+function u32be(n) {
+  const b = new Uint8Array(4);
+  new DataView(b.buffer).setUint32(0, n >>> 0, false);
+  return b;
+}
+
+/** Length-prefixed concatenation of a domain tag and a list of byte fields. */
+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"));
+
+// ── Identity ──────────────────────────────────────────────────────────────────
+
+/**
+ * A migrating holder's key material: their EXISTING classical secp256k1 key (as a
+ * Bitcoin holder already has) plus a freshly generated ML-DSA-65 post-quantum key.
+ * In practice the classical key is imported, not generated; we generate here so the
+ * reference is runnable end-to-end.
+ */
+export function generateMigrationIdentity() {
+  const classical = secp256k1.keygen(); // { secretKey, publicKey } — 33-byte compressed pub
+  const pq = ml_dsa65.keygen();
+  return {
+    classicalPriv: classical.secretKey,
+    classicalPub: classical.publicKey,
+    pqSecret: pq.secretKey,
+    pqPublic: pq.publicKey,
+  };
+}
+
+// ── Migration commitment (the "quantum-resistant binding") ─────────────────────
+
+/**
+ * Bind the classical pubkey to the PQC pubkey with a DUAL signature: the classical
+ * key signs the binding (proving current control) AND the PQC key signs it (proving
+ * possession of the successor key). Anchoring this commitment on-chain (out of scope
+ * here) is what makes a holder's migration publicly, permanently verifiable.
+ */
+export function createMigrationCommitment(identity) {
+  const msg = canonical(COMMIT_DOMAIN, [identity.classicalPub, identity.pqPublic]);
+  // secp256k1 signs the 32-byte hash of the message (Bitcoin/ECDSA convention).
+  // @noble/curves v2 returns a 64-byte compact signature directly.
+  const classicalSig = secp256k1.sign(sha256(msg), identity.classicalPriv);
+  // ML-DSA-65 signs the full message. @noble API: sign(message, secretKey).
+  const pqSig = ml_dsa65.sign(msg, identity.pqSecret);
+  return {
+    version: "pqc-migration-commit-v1",
+    classicalPub: toHex(identity.classicalPub),
+    pqPublic: toHex(identity.pqPublic),
+    classicalSig: toHex(classicalSig),
+    pqSig: toHex(pqSig),
+    // The anchor LEAF: publish/anchor this first-seen so verifiers can pin it. As a
+    // verify-time field it is only a self-consistency check (derivable from the cert) —
+    // the authentication comes from matching it against the external anchor, not from
+    // its mere presence.
+    factHash: toHex(sha3_256(msg)),
+  };
+}
+
+/**
+ * Verify a migration commitment. BOTH signatures must verify over the exact same
+ * canonical binding (the crypto-agility "verify-both" invariant).
+ *
+ * ⚠️ WELL-FORMEDNESS IS NOT THE SECURITY PROPERTY. This function alone proves only
+ * that whoever built the cert held BOTH secret keys at build time — it does NOT prove
+ * the cert is the holder's canonical binding. An attacker who recovered the classical
+ * key (post-Shor) can build a well-formed cert binding the victim's classical pubkey
+ * to the ATTACKER's own PQC key. To get the quantum no-downgrade property you MUST
+ * pass `opts.anchoredFactHash` — the factHash of the holder's FIRST-SEEN, immutably
+ * anchored commitment (e.g. an on-chain Merkle leaf published before Q-day). The
+ * verifier pins that value; a rebound cert has a different factHash and is rejected.
+ *
+ * @param {object} cert
+ * @param {{anchoredFactHash?: string}} [opts]
+ * @returns {{valid:boolean, wellFormed:boolean, classicalOk:boolean, pqOk:boolean, factOk:boolean, anchorOk:(boolean|null)}}
+ */
+export function verifyMigrationCommitment(cert, opts = {}) {
+  try {
+    const classicalPub = fromHex(cert.classicalPub);
+    const pqPublic = fromHex(cert.pqPublic);
+    const msg = canonical(COMMIT_DOMAIN, [classicalPub, pqPublic]);
+    const classicalOk = secp256k1.verify(fromHex(cert.classicalSig), sha256(msg), classicalPub);
+    // @noble API: verify(signature, message, publicKey).
+    const pqOk = ml_dsa65.verify(fromHex(cert.pqSig), msg, pqPublic);
+    const computedFact = toHex(sha3_256(msg));
+    const factOk = cert.factHash === computedFact;
+    const wellFormed = classicalOk && pqOk && factOk;
+    // Anchor pin: null = not checked (well-formedness only); true/false = matches the
+    // holder's anchored binding or not. `valid` is the SECURE result: it requires the
+    // anchor to match when one is supplied, and never over-reports.
+    const anchorOk = opts.anchoredFactHash == null ? null : (computedFact === opts.anchoredFactHash);
+    return { valid: wellFormed && anchorOk !== false, wellFormed, classicalOk, pqOk, factOk, anchorOk };
+  } catch (err) {
+    return { valid: false, wellFormed: false, classicalOk: false, pqOk: false, factOk: false, anchorOk: false, error: String(err) };
+  }
+}
+
+// ── Post-migration authorization ("spend") ─────────────────────────────────────
+
+/**
+ * After migration, authorize an action (e.g. a spend committing to a tx hash) with the
+ * PQC key. The quantum property holds ONLY when the verifier pins the holder's ANCHORED
+ * commitment (see verifySpend): the PQC signature must be under the pubkey the holder
+ * anchored first-seen, so a classical-key attacker who re-binds to their own PQC key is
+ * rejected at the anchor check, not here.
+ */
+export function authorizeSpend(identity, txHash /* Uint8Array (32 bytes) */) {
+  const msg = canonical(SPEND_DOMAIN, [identity.pqPublic, txHash]);
+  return toHex(ml_dsa65.sign(msg, identity.pqSecret));
+}
+
+/**
+ * Verify a post-migration spend against the holder's ANCHORED commitment.
+ *
+ * `opts.anchoredFactHash` is REQUIRED — the factHash of the holder's first-seen,
+ * immutably anchored commitment (from the on-chain anchor / first-seen registry, NOT
+ * from the cert being checked). Steps: (1) the presented cert must match that anchor
+ * and be well-formed, then (2) the PQC signature must authorize txHash under the
+ * anchored PQC pubkey.
+ *
+ * This is what delivers the quantum property: an attacker who recovered the classical
+ * key can forge a well-formed cert binding the victim's classical key to the attacker's
+ * OWN PQC key, but that cert's factHash ≠ the anchored one, so it is rejected here
+ * (`anchor-mismatch`). Calling without an anchor fails closed (`anchor-required`).
+ *
+ * @param {object} cert
+ * @param {Uint8Array} txHash 32-byte tx hash
+ * @param {string} pqSigHex hex ML-DSA-65 signature over the SPEND message
+ * @param {{anchoredFactHash: string}} opts REQUIRED anchor pin
+ */
+export function verifySpend(cert, txHash, pqSigHex, opts = {}) {
+  if (!opts.anchoredFactHash) {
+    return {
+      valid: false,
+      reason: "anchor-required",
+      note:
+        "verifySpend requires opts.anchoredFactHash (the holder's first-seen, anchored " +
+        "commitment). Without it the quantum no-downgrade property does not hold.",
+    };
+  }
+  const commit = verifyMigrationCommitment(cert, { anchoredFactHash: opts.anchoredFactHash });
+  if (!commit.valid) {
+    return { valid: false, reason: commit.anchorOk === false ? "anchor-mismatch" : "invalid-commitment", commit };
+  }
+  try {
+    const pqPublic = fromHex(cert.pqPublic);
+    const msg = canonical(SPEND_DOMAIN, [pqPublic, txHash]);
+    const ok = ml_dsa65.verify(fromHex(pqSigHex), msg, pqPublic);
+    return { valid: ok, reason: ok ? "ok" : "bad-pq-signature", commit };
+  } catch (err) {
+    return { valid: false, reason: "error", error: String(err), commit };
+  }
+}
+
+export const _internal = { canonical, COMMIT_DOMAIN, SPEND_DOMAIN, toHex, fromHex };

package/src/psbt.mjs

@@ -0,0 +1,149 @@
+// SPDX-License-Identifier: MIT
+//
+// Minimal BIP-174 PSBT (v0) for P2TR key-path spends: create → sign → finalize.
+// Supports exactly the fields a Taproot key-path custodian flow needs:
+//   global : PSBT_GLOBAL_UNSIGNED_TX (0x00)
+//   input  : PSBT_IN_WITNESS_UTXO (0x01), PSBT_IN_SIGHASH_TYPE (0x03),
+//            PSBT_IN_TAP_KEY_SIG (0x13), PSBT_IN_TAP_INTERNAL_KEY (0x17)
+// Validated in test/vectors.mjs by (a) serialize→parse round-trip and (b) that a signed
+// PSBT finalizes to the SAME network tx as the vetted direct signer in tx.mjs.
+
+import {
+  serializeLegacy, serializeSegwit, taprootKeyPathSighash, taprootTweakPrivateKey, txid, _internal,
+} from "./tx.mjs";
+import { schnorr } from "@noble/curves/secp256k1.js";
+
+const { toHex, fromHex, varint, u64le } = _internal;
+const MAGIC = Uint8Array.of(0x70, 0x73, 0x62, 0x74, 0xff); // "psbt\xff"
+const cat = (...a) => { let n = 0; for (const x of a) n += x.length; const o = new Uint8Array(n); let i = 0; for (const x of a) { o.set(x, i); i += x.length; } return o; };
+const SEP = Uint8Array.of(0x00);
+
+// key-value: <varint keylen><keytype(1)+keydata><varint vallen><val>. Our keys have no
+// keydata, so keylen = 1.
+function kv(keytype, value) { return cat(varint(1), Uint8Array.of(keytype), varint(value.length), value); }
+function witnessUtxoBytes(o) { return cat(u64le(o.valueSats), varint(o.scriptPubKey.length), o.scriptPubKey); }
+
+/**
+ * Build an unsigned PSBT.
+ * @param {{version?:number, locktime?:number, inputs:Array, outputs:Array}} tx
+ * @param {Array<{witnessUtxo:{valueSats:number|bigint, scriptPubKey:Uint8Array}, tapInternalKey:Uint8Array}>} inputsMeta
+ */
+export function createPsbt(tx, inputsMeta) {
+  if (inputsMeta.length !== tx.inputs.length) throw new Error("inputsMeta must match tx.inputs length");
+  return {
+    tx: { version: tx.version ?? 2, locktime: tx.locktime ?? 0, inputs: tx.inputs, outputs: tx.outputs },
+    inputs: inputsMeta.map((m) => ({ witnessUtxo: m.witnessUtxo, tapInternalKey: m.tapInternalKey, tapKeySig: null, sighashType: 0 })),
+  };
+}
+
+/** Serialize a PSBT to bytes (BIP-174). */
+export function serializePsbt(psbt) {
+  const parts = [MAGIC];
+  // global: unsigned tx (empty scriptSigs, no witness — serializeLegacy provides that).
+  parts.push(kv(0x00, serializeLegacy(psbt.tx)), SEP);
+  for (const inp of psbt.inputs) {
+    parts.push(kv(0x01, witnessUtxoBytes(inp.witnessUtxo)));
+    if (inp.sighashType !== undefined && inp.sighashType !== null) {
+      const st = new Uint8Array(4); new DataView(st.buffer).setUint32(0, inp.sighashType >>> 0, true);
+      parts.push(kv(0x03, st));
+    }
+    if (inp.tapKeySig) parts.push(kv(0x13, inp.tapKeySig));
+    if (inp.tapInternalKey) parts.push(kv(0x17, inp.tapInternalKey));
+    parts.push(SEP);
+  }
+  for (const _ of psbt.tx.outputs) parts.push(SEP); // one (empty) map per output
+  return cat(...parts);
+}
+
+export const serializePsbtHex = (psbt) => toHex(serializePsbt(psbt));
+export const serializePsbtBase64 = (psbt) => Buffer.from(serializePsbt(psbt)).toString("base64");
+
+/**
+ * Parse a PSBT (bytes) for structural validation. NOTE: this is intentionally lossy — it
+ * validates the BIP-174 framing (magic, key-value encoding, no duplicate keys, no trailing
+ * bytes) and recovers input/output COUNTS, but does not decode field values. The create→
+ * sign→finalize flow keeps the rich object in memory; don't rely on `parsePsbt(...).tx` for
+ * amounts/scripts.
+ */
+export function parsePsbt(bytes) {
+  let p = 0;
+  const b = bytes instanceof Uint8Array ? bytes : fromHex(bytes);
+  for (let i = 0; i < MAGIC.length; i++) if (b[p++] !== MAGIC[i]) throw new Error("bad PSBT magic");
+  const readVarint = () => { const f = b[p++]; if (f < 0xfd) return f; if (f === 0xfd) { const v = b[p] | (b[p + 1] << 8); p += 2; return v; } if (f === 0xfe) { const v = new DataView(b.buffer, b.byteOffset + p, 4).getUint32(0, true); p += 4; return v; } const v = Number(new DataView(b.buffer, b.byteOffset + p, 8).getBigUint64(0, true)); p += 8; return v; };
+  const readMap = () => {
+    const rec = {}; const seen = new Set();
+    for (;;) {
+      const keylen = readVarint();
+      if (keylen === 0) break; // separator
+      const keytype = b[p]; const key = b.slice(p, p + keylen); p += keylen;
+      // BIP-174: duplicate keys (full key bytes) MUST make the PSBT invalid.
+      const kk = toHex(key);
+      if (seen.has(kk)) throw new Error("duplicate PSBT key");
+      seen.add(kk);
+      const vallen = readVarint(); const val = b.slice(p, p + vallen); p += vallen;
+      rec[keytype] = { key, val };
+    }
+    return rec;
+  };
+  const global = readMap();
+  if (!global[0x00]) throw new Error("PSBT missing unsigned tx");
+  // Parse the embedded unsigned tx to learn input/output counts.
+  const tx = parseLegacyTx(global[0x00].val);
+  const inputs = tx.inputs.map(() => readMap());
+  const outputs = tx.outputs.map(() => readMap());
+  if (p !== b.length) throw new Error("trailing bytes after PSBT");
+  return { magicOk: true, tx, inputMaps: inputs, outputMaps: outputs };
+}
+
+function parseLegacyTx(b) {
+  let p = 0;
+  const u32 = () => { const v = new DataView(b.buffer, b.byteOffset + p, 4).getUint32(0, true); p += 4; return v; };
+  const rd = (n) => { const s = b.slice(p, p + n); p += n; return s; };
+  const vi = () => { const f = b[p++]; if (f < 0xfd) return f; if (f === 0xfd) { const v = b[p] | (b[p + 1] << 8); p += 2; return v; } if (f === 0xfe) { const v = u32(); return v; } const v = Number(new DataView(b.buffer, b.byteOffset + p, 8).getBigUint64(0, true)); p += 8; return v; };
+  const version = u32();
+  // BIP-174: the global unsigned tx MUST NOT contain witness data. A 0x00 marker where the
+  // input-count varint belongs signals a segwit-serialized tx → reject rather than misparse.
+  if (b[p] === 0x00) throw new Error("PSBT unsigned tx must not be segwit-serialized");
+  const nin = vi(); const inputs = [];
+  for (let i = 0; i < nin; i++) { rd(32); u32(); const sl = vi(); rd(sl); u32(); inputs.push({}); }
+  const nout = vi(); const outputs = [];
+  for (let i = 0; i < nout; i++) { p += 8; const sl = vi(); rd(sl); outputs.push({}); }
+  u32();
+  return { version, inputs, outputs };
+}
+
+/**
+ * Sign every input of a PSBT as a Taproot key-path spend (SIGHASH_DEFAULT), using the
+ * matching internal private key. The sighash commits to ALL inputs' amounts+scriptPubKeys,
+ * taken from each input's witnessUtxo.
+ * @param {object} psbt
+ * @param {Uint8Array[]} internalPrivs one internal private key per input
+ */
+export function signPsbtTaprootKeyPath(psbt, internalPrivs) {
+  if (internalPrivs.length !== psbt.inputs.length) throw new Error("internalPrivs must match inputs length");
+  const values = psbt.inputs.map((i) => i.witnessUtxo.valueSats);
+  const spks = psbt.inputs.map((i) => i.witnessUtxo.scriptPubKey);
+  for (let idx = 0; idx < psbt.inputs.length; idx++) {
+    const { privKey, outputXOnly } = taprootTweakPrivateKey(internalPrivs[idx]);
+    // Refuse to sign an input this key does NOT control — otherwise we'd silently emit an
+    // unspendable tx (the sig wouldn't satisfy the P2TR output being spent). P2TR spk =
+    // 0x51 0x20 <32B output key>.
+    const spk = spks[idx];
+    if (spk.length !== 34 || spk[0] !== 0x51 || spk[1] !== 0x20 || !outputXOnly.every((v, i) => v === spk[2 + i])) {
+      throw new Error(`input ${idx}: signing key does not control this scriptPubKey`);
+    }
+    const sighash = taprootKeyPathSighash(psbt.tx, idx, values, spks);
+    psbt.inputs[idx].tapKeySig = schnorr.sign(sighash, privKey);
+  }
+  return psbt;
+}
+
+/**
+ * Finalize a fully-signed PSBT into a broadcastable network transaction.
+ * @returns {{hex:string, txid:string}}
+ */
+export function finalizePsbt(psbt) {
+  if (psbt.inputs.some((i) => !i.tapKeySig)) throw new Error("PSBT not fully signed");
+  const tx = { ...psbt.tx, inputs: psbt.tx.inputs.map((inp, i) => ({ ...inp, witness: [psbt.inputs[i].tapKeySig] })) };
+  return { hex: toHex(serializeSegwit(tx)), txid: txid(tx) };
+}

package/src/tx.mjs

@@ -0,0 +1,152 @@
+// SPDX-License-Identifier: MIT
+//
+// Minimal REAL Bitcoin transaction layer: serialization + txid, plus BIP-341 Taproot
+// key-path signing (SIGHASH_DEFAULT). Enough to CONSTRUCT and SIGN a P2TR spend.
+//
+// Validated in test/vectors.mjs against:
+//   • the Bitcoin genesis coinbase txid (serialization + double-SHA256 txid correct),
+//   • the BIP-341 taproot tweak (private↔public key consistency: the tweaked private
+//     key's Schnorr pubkey equals the tweaked output key from address.mjs),
+//   • sign→verify: the produced Schnorr signature verifies against the Taproot output
+//     key, i.e. it satisfies a key-path spend of that output.
+//
+// HONEST SCOPE: the BIP-341 sighash is implemented to spec and the signature verifies
+// against the output key. The FINAL consensus proof — broadcasting a funded spend on
+// Bitcoin testnet and/or cross-checking against the official BIP-341 sighash test
+// vector file — is the closing validation step (needs a funded testnet UTXO). This
+// module gives a custodian real address derivation + a ready-to-validate spend path.
+
+import { secp256k1, schnorr } from "@noble/curves/secp256k1.js";
+import { sha256 } from "@noble/hashes/sha2.js";
+import { taprootTweakOutputKey } from "./address.mjs";
+
+const N = 0xfffffffffffffffffffffffffffffffebaaedce6af48a03bbfd25e8cd0364141n;
+
+// ── byte helpers ───────────────────────────────────────────────────────────────
+const cat = (...arrs) => { let n = 0; for (const a of arrs) n += a.length; const o = new Uint8Array(n); let i = 0; for (const a of arrs) { o.set(a, i); i += a.length; } return o; };
+const u8 = (n) => Uint8Array.of(n & 0xff);
+function u32le(n) { const b = new Uint8Array(4); new DataView(b.buffer).setUint32(0, n >>> 0, true); return b; }
+function u64le(n) {
+  const bn = BigInt(n);
+  // Reject out-of-range amounts instead of silently truncating (>u64) or wrapping
+  // negatives. Real BTC values are ≤ MAX_MONEY (2.1e15 sats) ≪ u64.
+  if (bn < 0n || bn > 0xffffffffffffffffn) throw new RangeError("valueSats out of u64 range");
+  const b = new Uint8Array(8); const dv = new DataView(b.buffer);
+  dv.setUint32(0, Number(bn & 0xffffffffn), true); dv.setUint32(4, Number((bn >> 32n) & 0xffffffffn), true); return b;
+}
+function varint(n) {
+  n = Number(n);
+  if (n < 0xfd) return u8(n);
+  if (n <= 0xffff) { const b = new Uint8Array(3); b[0] = 0xfd; new DataView(b.buffer).setUint16(1, n, true); return b; }
+  if (n <= 0xffffffff) { const b = new Uint8Array(5); b[0] = 0xfe; new DataView(b.buffer).setUint32(1, n, true); return b; }
+  const b = new Uint8Array(9); b[0] = 0xff; new DataView(b.buffer).setBigUint64(1, BigInt(n), true); return b;
+}
+const varbytes = (b) => cat(varint(b.length), b);
+const rev = (b) => Uint8Array.from(b).reverse();
+const dsha = (b) => sha256(sha256(b));
+const toHex = (b) => Buffer.from(b).toString("hex");
+const fromHex = (h) => Uint8Array.from(Buffer.from(h, "hex"));
+function bytesToBigInt(b) { let x = 0n; for (const y of b) x = (x << 8n) | BigInt(y); return x; }
+function bigIntTo32(x) { const o = new Uint8Array(32); for (let i = 31; i >= 0; i--) { o[i] = Number(x & 0xffn); x >>= 8n; } return o; }
+
+// A P2TR scriptPubKey is OP_1 (0x51) PUSH32 <output key>.
+export const p2trScriptPubKey = (outputXOnly) => cat(Uint8Array.of(0x51, 0x20), outputXOnly);
+
+// ── transaction model ────────────────────────────────────────────────────────
+// input:  { txid: hex (big-endian, as shown in explorers), vout, sequence?, witness?: Uint8Array[] }
+// output: { valueSats: number|bigint, scriptPubKey: Uint8Array }
+
+function serializeInputs(inputs) {
+  const parts = [varint(inputs.length)];
+  for (const i of inputs) {
+    if (!/^[0-9a-fA-F]{64}$/.test(i.txid)) throw new Error(`invalid txid (need 64 hex chars): ${i.txid}`);
+    parts.push(rev(fromHex(i.txid)));            // prevout hash, internal LE order
+    parts.push(u32le(i.vout));
+    parts.push(varint(0));                        // empty scriptSig (segwit)
+    parts.push(u32le(i.sequence ?? 0xffffffff));
+  }
+  return cat(...parts);
+}
+function serializeOutputs(outputs) {
+  const parts = [varint(outputs.length)];
+  for (const o of outputs) { parts.push(u64le(o.valueSats)); parts.push(varbytes(o.scriptPubKey)); }
+  return cat(...parts);
+}
+
+/** Legacy (non-witness) serialization — used for txid of legacy txs and as the base. */
+export function serializeLegacy(tx) {
+  return cat(u32le(tx.version ?? 1), serializeInputs(tx.inputs), serializeOutputs(tx.outputs), u32le(tx.locktime ?? 0));
+}
+
+/** SegWit serialization (marker+flag+witness). */
+export function serializeSegwit(tx) {
+  const parts = [u32le(tx.version ?? 1), Uint8Array.of(0x00, 0x01), serializeInputs(tx.inputs), serializeOutputs(tx.outputs)];
+  for (const i of tx.inputs) {
+    const w = i.witness ?? [];
+    parts.push(varint(w.length));
+    for (const item of w) parts.push(varbytes(item));
+  }
+  parts.push(u32le(tx.locktime ?? 0));
+  return cat(...parts);
+}
+
+/** txid = reverse(double-SHA256(legacy serialization)), hex as shown in explorers. */
+export function txid(tx) { return toHex(rev(dsha(serializeLegacy(tx)))); }
+
+// ── BIP-341 key-path sighash (SIGHASH_DEFAULT = 0x00) ───────────────────────────
+// prevoutScriptPubKeys / prevoutValues describe EVERY input being spent (required by
+// the taproot sighash), in input order.
+export function taprootKeyPathSighash(tx, inputIndex, prevoutValues, prevoutScriptPubKeys) {
+  // The taproot sighash commits to ALL spent inputs' amounts + scriptPubKeys, so these
+  // arrays must line up with the inputs or the sighash is silently wrong (unspendable).
+  if (prevoutValues.length !== tx.inputs.length || prevoutScriptPubKeys.length !== tx.inputs.length) {
+    throw new Error("prevoutValues / prevoutScriptPubKeys must match tx.inputs length");
+  }
+  if (inputIndex < 0 || inputIndex >= tx.inputs.length) throw new Error("inputIndex out of range");
+  const version = u32le(tx.version ?? 1);
+  const locktime = u32le(tx.locktime ?? 0);
+  const shaPrevouts = sha256(cat(...tx.inputs.map((i) => cat(rev(fromHex(i.txid)), u32le(i.vout)))));
+  const shaAmounts = sha256(cat(...prevoutValues.map((v) => u64le(v))));
+  const shaScriptpubkeys = sha256(cat(...prevoutScriptPubKeys.map((s) => varbytes(s))));
+  const shaSequences = sha256(cat(...tx.inputs.map((i) => u32le(i.sequence ?? 0xffffffff))));
+  const shaOutputs = sha256(cat(...tx.outputs.map((o) => cat(u64le(o.valueSats), varbytes(o.scriptPubKey)))));
+  const spendType = u8(0); // no annex, key path
+  const msg = cat(
+    u8(0x00),                 // hash_type = SIGHASH_DEFAULT
+    version, locktime,
+    shaPrevouts, shaAmounts, shaScriptpubkeys, shaSequences,
+    shaOutputs,
+    spendType, u32le(inputIndex),
+  );
+  // Epoch byte 0x00 is prepended to the tagged-hash input.
+  return schnorr.utils.taggedHash("TapSighash", cat(u8(0x00), msg));
+}
+
+// ── BIP-341 key-path signing ────────────────────────────────────────────────────
+/**
+ * Tweak an internal private key for key-path spending: normalize to even-Y (BIP-340),
+ * add the taproot tweak. Returns { privKey (32B), outputXOnly (32B) }.
+ */
+export function taprootTweakPrivateKey(internalPriv) {
+  let d = bytesToBigInt(internalPriv) % N;
+  const P = secp256k1.Point.BASE.multiply(d);
+  if (P.toAffine().y % 2n === 1n) d = N - d;         // BIP-340 even-Y normalization
+  const internalXOnly = bigIntTo32(secp256k1.Point.BASE.multiply(d).toAffine().x);
+  const t = bytesToBigInt(schnorr.utils.taggedHash("TapTweak", internalXOnly)) % N;
+  const dPrime = (d + t) % N;
+  return { privKey: bigIntTo32(dPrime), outputXOnly: taprootTweakOutputKey(internalXOnly) };
+}
+
+/**
+ * Sign one key-path P2TR input. Returns the 64-byte Schnorr witness signature (hex).
+ * Also fills tx.inputs[inputIndex].witness = [sig].
+ */
+export function signTaprootKeyPath(tx, inputIndex, internalPriv, prevoutValues, prevoutScriptPubKeys) {
+  const { privKey } = taprootTweakPrivateKey(internalPriv);
+  const sighash = taprootKeyPathSighash(tx, inputIndex, prevoutValues, prevoutScriptPubKeys);
+  const sig = schnorr.sign(sighash, privKey);
+  tx.inputs[inputIndex].witness = [sig];
+  return toHex(sig);
+}
+
+export const _internal = { toHex, fromHex, dsha, rev, varint, u64le, N };