fractal-pqc 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FRACTAL AI S.A.S.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,163 @@
+# fractal-pqc
+
+A small, **runnable, test-vector-verified** reference for quantum-safe migration of a
+Bitcoin-style key. It binds a classical **secp256k1 / Taproot** key to a post-quantum
+**ML-DSA-65 (NIST FIPS-204)** key and requires a post-quantum signature to authorize —
+the core mechanism of any Bitcoin quantum-readiness transition.
+
+Built from the same crypto-agility discipline FractalAI already runs in production on
+its own post-quantum L1 (verify-both-during-migration, no-downgrade), distilled to the
+`secp256k1 → ML-DSA-65` case relevant to Bitcoin.
+
+## Why this exists
+
+A large quantum computer can recover a `secp256k1` private key from an exposed public
+key (Shor's algorithm), so any Bitcoin output whose pubkey is on-chain becomes
+spendable by an attacker. The migration problem: let a holder **bind their existing key
+to a post-quantum successor key** and, from then on, require a PQC signature to spend —
+without invalidating already-signed history. This kit is a concrete, honest first step.
+
+## What is REAL here (verified, not aspirational)
+
+Everything below is exercised by `npm test` with real keys — **46/46 checks pass**:
+
+- **secp256k1** commitment + spend authorization (`@noble/curves`).
+- **Taproot BIP-340 Schnorr** sign/verify, asserted against the **official BIP-340 test
+  vector** — i.e. byte-for-byte consensus-correct with Bitcoin, not an approximation.
+- **ML-DSA-65 (FIPS-204, Cat-3)** signing/verification (`@noble/post-quantum`): 1952-byte
+  public key, 4032-byte secret, 3309-byte signature.
+- **Dual-signature migration commitment**: classical + PQC both sign the same canonical,
+  domain-separated binding; a verifier reconstructs identical bytes.
+- **Taproot → PQC recovery commitment** (P2QRH-style): binds a 32-byte x-only Taproot
+  output key to an ML-DSA-65 key, dual-signed.
+- **Real Bitcoin address derivation**: bech32/bech32m (**official BIP-173/350 vectors**),
+  P2TR `bc1p…`/`tb1p…` via the **BIP-341** taproot tweak (**official BIP-341 vector →
+  `bc1p2wsldez…`**), and P2WPKH `bc1q…`.
+- **Real Bitcoin transactions**: segwit/legacy serialization + txid (validated against the
+  **Bitcoin genesis coinbase txid**), and a **BIP-341 key-path sighash that matches the
+  OFFICIAL `bip-0341/wallet-test-vectors.json` byte-for-byte** (a permanent test in the
+  suite) — i.e. a key-path SIGHASH_DEFAULT spend signs the Bitcoin-consensus message and
+  will not be sighash-rejected by the network. Key-path signing produces a Schnorr sig
+  that also verifies against the Taproot output key.
+- **Fees + coin selection**: exact segwit vsize (1-in/1-out P2TR = 111 vB), accumulative
+  coin selection with change/dust handling and a fee-rate (sat/vB) → conserves value.
+- **BIP-174 PSBT** (P2TR key-path): `createPsbt` → `signPsbtTaprootKeyPath` → `finalizePsbt`
+  into a broadcastable tx; serialize↔parse round-trips, base64 carries the `psbt\xff` magic,
+  and the finalized witness signature verifies against the Taproot output key. The signer
+  refuses any input the key doesn't control (custodian-safe).
+- **Testnet broadcaster**: fetches your address's UTXOs + the live fee rate (mempool.space
+  Esplora API), builds+signs the spend, and publishes it — **dry-run by default**, `--broadcast`
+  to send. `addressToScriptPubKey` lets you pay any SegWit address.
+- **The quantum property under test** (correctly modeled): `verifySpend` requires the
+  verifier to pin the holder's **anchored** commitment (`anchoredFactHash`). Given that
+  pin, an attacker who recovered the classical key post-Shor — and who can forge a
+  *well-formed* cert re-binding the victim's classical key to the attacker's OWN PQC key
+  — is still rejected (`anchor-mismatch`), because the forged cert's factHash differs
+  from the anchored one. Without the anchor, `verifySpend` fails closed (`anchor-required`).
+
+Run it:
+
+```bash
+cd integrations/pqc-migration-kit
+npm install        # or reuse the workspace's @noble packages
+npm test
+```
+
+## SDK
+
+```js
+import {
+  generateMigrationIdentity, createMigrationCommitment, verifyMigrationCommitment,
+  authorizeSpend, verifySpend,
+  generateTaprootKey, taprootSign, taprootVerify, verifiesBip340OfficialVector,
+  createTaprootPqcCommitment, verifyTaprootPqcCommitment,
+} from "fractal-pqc";
+
+const id = generateMigrationIdentity();          // secp256k1 + ML-DSA-65
+const cert = createMigrationCommitment(id);      // dual-signed, anchorable
+verifyMigrationCommitment(cert).valid;           // true
+```
+
+## CLI
+
+```bash
+npx fractal-pqc verify-vector          # assert the official BIP-340 test vector
+npx fractal-pqc selftest               # run the full real test suite (46 checks)
+npx fractal-pqc keygen > key.json      # generate a migration identity (testnet/experimental)
+npx fractal-pqc keygen --taproot > tk.json           # a Taproot key
+npx fractal-pqc address --key tk.json --network tb   # derive a real tb1p… Taproot address
+npx fractal-pqc commit --key key.json > commit.json
+npx fractal-pqc verify commit.json     # exit 0 = valid, 1 = invalid/tampered
+npx fractal-pqc taproot-commit --key <taproot+pq key.json>   # Taproot -> PQC recovery commitment
+```
+
+`verify`/`taproot-verify`/`verify-vector` exit non-zero on failure, so they compose into
+CI and custody scripts.
+
+## Send a real spend on testnet
+
+```bash
+npx fractal-pqc keygen --taproot > tk.json          # your Taproot key
+npx fractal-pqc receive --key tk.json --network tb  # → tb1p… funding address + explorer link
+# fund that address from a testnet faucet, then:
+npx fractal-pqc send-testnet --key tk.json --to <dest tb1…> --amount 20000 --network tb
+#   ↑ DRY-RUN: fetches your UTXOs + live fee rate, builds+signs, prints hex + txid (does NOT send)
+npx fractal-pqc send-testnet --key tk.json --to <dest tb1…> --amount 20000 --network tb --broadcast
+#   ↑ actually publishes via mempool.space and returns the txid + explorer URL
+```
+
+The SDK equivalent is `sendP2trKeyPath({ internalPriv, to, amountSats, network, broadcast })`.
+
+## Security model — the anchor is load-bearing
+
+The quantum protection does **not** come from a cert verifying in isolation (a cert only
+proves whoever built it held both secret keys). It comes from **anchoring**: the holder
+publishes their commitment first-seen and immutably (e.g. an on-chain Merkle leaf) BEFORE
+Q-day, and every verifier **pins that anchored factHash**. `verifySpend`/`verifyMigrationCommitment`
+take `anchoredFactHash` and reject any cert that doesn't match it. Skip the anchor and the
+kit provides no quantum protection — `verifySpend` fails closed rather than pretend otherwise.
+Providing the anchor registry (first-seen, no-duplicate, immutable) is part of the
+grant-funded roadmap below; this reference makes the anchor a **required verifier input**
+so the property is never silently over-claimed.
+
+## What this is NOT (honest scope — do not overstate)
+
+- **Not yet confirmed in a live mempool.** The sighash is proven consensus-correct against
+  the official BIP-341 vector, and the broadcaster is built + dry-run-tested — but an actual
+  funded **testnet** broadcast (which needs tBTC from a faucet) is the operator's final step.
+- **Key-path-only (no script tree / merkle root).** `taprootTweakPrivateKey`/`signTaprootKeyPath`
+  handle key-path-only outputs — exactly what this kit's `p2trAddress` derives. Pointing the
+  signer at a foreign Taproot output that commits to a script tree would produce an invalid
+  signature. Script-path (tapscript) spends are not implemented (key-path PSBT + fees are).
+- **Secrets are not zeroized.** Private-key `Uint8Array`s are not wiped after use (best-effort
+  only in JS); `keygen` prints secrets by design (testnet/experimental).
+- **Not a BIP and not consensus.** The "recovery commitment" is an application-layer
+  construction, not a Bitcoin output type. A real quantum-resistant output requires a
+  soft fork (e.g. a P2QRH / BIP-360-style commitment) — out of scope for this reference.
+- **Not audited.** Reference code; the underlying `@noble` libraries are audited, this
+  composition is not.
+
+## Roadmap — from reference to real Bitcoin custody tooling (the grant-funded work)
+
+Each milestone is independently verifiable, open-source, and shippable on its own:
+
+1. **Bitcoin address + tx layer** — ✅ *done + vector-verified*: bech32/bech32m (BIP-173/350),
+   P2TR `bc1p…` derivation (BIP-341), segwit tx + txid (genesis-checked), a BIP-341 key-path
+   sighash **matching the official BIP-341 vector byte-for-byte**, **fees + coin selection**,
+   **BIP-174 PSBT** create→sign→finalize, and a **testnet broadcaster** (fetch UTXOs/fees →
+   build+sign → publish; dry-run tested offline) — all permanent tests.
+   **Remaining:** a funded **testnet** broadcast to confirm in a live mempool (needs tBTC),
+   and script-path (tapscript) spends.
+2. **P2QRH-style quantum-resistant output** — a concrete commitment scheme + spending
+   path a custodian can pre-register for held UTXOs, with a reference verifier.
+3. **Custodian migration CLI** — take a real (testnet) UTXO set, emit PQC recovery
+   commitments, and produce the dual-signed migration record; end-to-end on testnet.
+4. **On-chain anchoring** (first-seen, immutable) — anchor recovery commitments as
+   verifiable leaves (reusing FractalAI's Merkle-anchor pipeline) so a holder's migration
+   is publicly provable and pinnable — this is what makes the `verifySpend` anchor real.
+5. **Soft-fork integration analysis** — a PQC security review of candidate Bitcoin
+   quantum proposals at the signature-integration surface.
+
+## License
+
+MIT. Uses `@noble/curves`, `@noble/hashes`, `@noble/post-quantum` (audited, MIT).

package/bin/cli.mjs

@@ -0,0 +1,220 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: MIT
+//
+// fractal-pqc — CLI for the FractalAI PQC migration kit.
+// Quantum-safe migration of a Bitcoin-style key (secp256k1/Taproot -> ML-DSA-65).
+//
+// Commands:
+//   fractal-pqc keygen [--taproot]              Generate a migration identity (hex).
+//   fractal-pqc commit  --key <file>            Create a dual-signed migration commitment.
+//   fractal-pqc verify  <commitment.json>       Verify a migration commitment (exit 0/1).
+//   fractal-pqc taproot-commit --key <file>     Create a Taproot->PQC recovery commitment.
+//   fractal-pqc taproot-verify <commitment.json>
+//   fractal-pqc verify-vector                   Check the official BIP-340 test vector.
+//   fractal-pqc selftest                        Run the full real test suite (19 checks).
+//
+// SECURITY: keys printed by `keygen` are for testnet / experimentation. Do NOT paste a
+// production Bitcoin secret key into any tool; this kit is a reference, not a signer HSM.
+
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { spawnSync } from "node:child_process";
+import {
+  generateMigrationIdentity,
+  createMigrationCommitment,
+  verifyMigrationCommitment,
+  generateTaprootKey,
+  createTaprootPqcCommitment,
+  verifyTaprootPqcCommitment,
+  verifiesBip340OfficialVector,
+  p2trAddress,
+  p2wpkhAddress,
+  sendP2trKeyPath,
+  explorerAddrUrl,
+} from "../src/index.mjs";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const hex = (b) => Buffer.from(b).toString("hex");
+const fromHex = (h) => Uint8Array.from(Buffer.from(h, "hex"));
+const out = (o) => console.log(JSON.stringify(o, null, 2));
+const die = (msg) => { console.error(`error: ${msg}`); process.exit(2); };
+
+const [, , cmd, ...rest] = process.argv;
+
+function flag(name) {
+  const i = rest.indexOf(`--${name}`);
+  return i >= 0 ? rest[i + 1] : undefined;
+}
+
+function readJson(path, what = "file") {
+  if (!path) die(`a ${what} path is required`);
+  let raw;
+  try { raw = readFileSync(path, "utf8"); } catch (e) { die(`cannot read ${what}: ${e.message}`); }
+  try { return JSON.parse(raw); } catch { die(`invalid JSON in ${what}: ${path}`); }
+}
+function loadKeyFile(path) {
+  return readJson(path, "--key <file>");
+}
+// Require a hex field on a key object, else fail cleanly (exit 2) instead of letting
+// fromHex(undefined) throw a raw Node stack trace.
+function reqHex(obj, ...names) {
+  const name = names.find((n) => typeof obj[n] === "string" && /^[0-9a-fA-F]*$/.test(obj[n]));
+  if (!name) die(`--key file is missing/invalid field: ${names.join(" | ")}`);
+  return fromHex(obj[name]);
+}
+const VALID_NETWORKS = new Set(["bc", "tb", "bcrt"]);
+
+switch (cmd) {
+  case "keygen": {
+    if (rest.includes("--taproot")) {
+      const t = generateTaprootKey();
+      out({
+        kind: "taproot",
+        secretKey: hex(t.secretKey),
+        xOnlyPub: hex(t.xOnlyPub),
+        _warning: "TESTNET/EXPERIMENTAL ONLY — never use a real Bitcoin secret key here.",
+      });
+    } else {
+      const id = generateMigrationIdentity();
+      out({
+        kind: "migration-identity",
+        classicalPriv: hex(id.classicalPriv),
+        classicalPub: hex(id.classicalPub),
+        pqSecret: hex(id.pqSecret),
+        pqPublic: hex(id.pqPublic),
+        _warning: "TESTNET/EXPERIMENTAL ONLY — secrets printed in cleartext.",
+      });
+    }
+    break;
+  }
+
+  case "commit": {
+    const k = loadKeyFile(flag("key"));
+    const id = {
+      classicalPriv: reqHex(k, "classicalPriv"),
+      classicalPub: reqHex(k, "classicalPub"),
+      pqSecret: reqHex(k, "pqSecret"),
+      pqPublic: reqHex(k, "pqPublic"),
+    };
+    out(createMigrationCommitment(id));
+    break;
+  }
+
+  case "verify": {
+    const path = rest.find((a) => !a.startsWith("--"));
+    if (!path) die("usage: fractal-pqc verify <commitment.json> [--anchor <factHash>]");
+    const cert = readJson(path, "commitment");
+    const anchor = flag("anchor");
+    if (!anchor) {
+      console.error("note: no --anchor given → checking WELL-FORMEDNESS only, not that this is the holder's anchored binding. Pass --anchor <factHash> for the security check.");
+    }
+    const r = verifyMigrationCommitment(cert, anchor ? { anchoredFactHash: anchor } : {});
+    out(r);
+    process.exit(r.valid ? 0 : 1);
+  }
+
+  case "taproot-commit": {
+    const k = loadKeyFile(flag("key"));
+    // Accept either a taproot keyfile (+ --pq for the PQC key) or a combined file.
+    const taproot = { secretKey: reqHex(k, "secretKey", "taprootSecret"), xOnlyPub: reqHex(k, "xOnlyPub", "taprootXOnlyPub") };
+    const pqFile = flag("pq") ? readJson(flag("pq"), "--pq <file>") : k;
+    const pqId = { pqSecret: reqHex(pqFile, "pqSecret"), pqPublic: reqHex(pqFile, "pqPublic") };
+    out(createTaprootPqcCommitment(taproot, pqId));
+    break;
+  }
+
+  case "taproot-verify": {
+    const path = rest.find((a) => !a.startsWith("--"));
+    if (!path) die("usage: fractal-pqc taproot-verify <commitment.json> [--anchor <factHash>]");
+    const cert = readJson(path, "commitment");
+    const anchor = flag("anchor");
+    if (!anchor) {
+      console.error("note: no --anchor given → well-formedness only. Pass --anchor <factHash> for the security check.");
+    }
+    const r = verifyTaprootPqcCommitment(cert, anchor ? { anchoredFactHash: anchor } : {});
+    out(r);
+    process.exit(r.valid ? 0 : 1);
+  }
+
+  case "address": {
+    const k = loadKeyFile(flag("key"));
+    const net = flag("network") || "bc"; // bc | tb | bcrt
+    if (!VALID_NETWORKS.has(net)) die(`unknown --network '${net}' (expected bc | tb | bcrt)`);
+    const result = {};
+    const xonly = k.xOnlyPub ?? k.taprootXOnlyPub;
+    if (xonly) result.p2tr = p2trAddress(reqHex({ xonly }, "xonly"), net);
+    if (k.classicalPub) result.p2wpkh = p2wpkhAddress(reqHex(k, "classicalPub"), net);
+    if (!result.p2tr && !result.p2wpkh) die("key file needs xOnlyPub (Taproot) or classicalPub (P2WPKH)");
+    result.network = net;
+    out(result);
+    break;
+  }
+
+  case "receive": {
+    const k = loadKeyFile(flag("key"));
+    const net = flag("network") || "tb";
+    if (!VALID_NETWORKS.has(net)) die(`unknown --network '${net}' (expected bc | tb | bcrt)`);
+    const xonly = k.xOnlyPub ?? k.taprootXOnlyPub;
+    if (!xonly) die("--key must be a Taproot key (from `keygen --taproot`)");
+    const addr = p2trAddress(reqHex({ xonly }, "xonly"), net);
+    out({ fundingAddress: addr, network: net, explorer: explorerAddrUrl(addr, net),
+      hint: net === "tb" ? "Fund it from a testnet faucet, then: fractal-pqc send-testnet --key <file> --to <addr> --amount <sats>" : undefined });
+    break;
+  }
+
+  case "send-testnet": {
+    const k = loadKeyFile(flag("key"));
+    const net = flag("network") || "tb";
+    const to = flag("to");
+    const amount = Number(flag("amount"));
+    if (!to) die("--to <address> is required");
+    if (!Number.isInteger(amount) || amount <= 0) die("--amount <sats> must be a positive integer");
+    const secret = k.secretKey ?? k.taprootSecret;
+    if (!secret) die("--key must be a Taproot key with a secretKey (from `keygen --taproot`)");
+    const doBroadcast = rest.includes("--broadcast");
+    const feeRate = flag("fee-rate") ? Number(flag("fee-rate")) : undefined;
+    try {
+      const r = await sendP2trKeyPath({
+        internalPriv: reqHex({ secret }, "secret"), to, amountSats: amount,
+        network: net === "bc" ? "bc" : net, feeRate, broadcast: doBroadcast,
+      });
+      out({
+        ...r,
+        note: doBroadcast ? "BROADCAST — published to the network." : "DRY-RUN — not sent. Re-run with --broadcast to publish.",
+      });
+      process.exit(0);
+    } catch (e) { die(e.message); }
+    break;
+  }
+
+  case "verify-vector": {
+    const ok = verifiesBip340OfficialVector();
+    out({ bip340_official_vector: ok ? "VERIFIED (Bitcoin-consensus-correct)" : "FAILED" });
+    process.exit(ok ? 0 : 1);
+  }
+
+  case "selftest": {
+    const r = spawnSync(process.execPath, [join(__dirname, "..", "test", "vectors.mjs")], { stdio: "inherit" });
+    process.exit(r.status ?? 1);
+  }
+
+  default:
+    console.log(`fractal-pqc — quantum-safe migration for a Bitcoin-style key
+
+Usage:
+  fractal-pqc keygen [--taproot]           Generate a migration identity (hex)
+  fractal-pqc commit --key <file>          Create a dual-signed migration commitment
+  fractal-pqc verify <commitment.json>     Verify a migration commitment (exit 0/1)
+  fractal-pqc taproot-commit --key <file>  Create a Taproot->PQC recovery commitment
+  fractal-pqc taproot-verify <file.json>   Verify a Taproot->PQC recovery commitment
+  fractal-pqc address --key <file> [--network bc|tb|bcrt]   Derive P2TR/P2WPKH address
+  fractal-pqc receive --key <taproot> [--network tb]        Show the funding (P2TR) address
+  fractal-pqc send-testnet --key <taproot> --to <addr> --amount <sats> [--fee-rate N] [--network tb|signet] [--broadcast]
+                                           Build+sign a P2TR spend; dry-run unless --broadcast
+  fractal-pqc verify-vector                Check the official BIP-340 test vector
+  fractal-pqc selftest                     Run the full real test suite (19 checks)
+
+Docs: integrations/pqc-migration-kit/README.md`);
+    process.exit(cmd ? 1 : 0);
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "fractal-pqc",
+  "version": "0.3.0",
+  "description": "Runnable reference for quantum-safe migration of a Bitcoin-style key: bind secp256k1/Taproot to ML-DSA-65 (FIPS-204), derive P2TR addresses, build+sign BIP-341 key-path spends (official-vector-verified), and broadcast on testnet. Real primitives, honest scope.",
+  "type": "module",
+  "license": "MIT",
+  "author": "FractalAI",
+  "homepage": "https://fractalai.net.co",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/fractalai/fractal-ai",
+    "directory": "integrations/pqc-migration-kit"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "main": "./src/index.mjs",
+  "exports": {
+    ".": "./src/index.mjs",
+    "./migration-envelope": "./src/migration-envelope.mjs",
+    "./bitcoin": "./src/bitcoin.mjs"
+  },
+  "bin": {
+    "fractal-pqc": "./bin/cli.mjs"
+  },
+  "files": [
+    "src",
+    "bin",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node test/vectors.mjs",
+    "selftest": "node bin/cli.mjs selftest"
+  },
+  "dependencies": {
+    "@noble/curves": "^2.2.0",
+    "@noble/hashes": "^2.2.0",
+    "@noble/post-quantum": "^0.6.1"
+  },
+  "keywords": [
+    "bitcoin",
+    "post-quantum",
+    "ml-dsa",
+    "fips-204",
+    "secp256k1",
+    "taproot",
+    "quantum-migration",
+    "crypto-agility"
+  ]
+}

package/src/address.mjs

@@ -0,0 +1,102 @@
+// SPDX-License-Identifier: MIT
+//
+// Real Bitcoin address derivation: P2TR (Taproot, BIP-341 key-path) and P2WPKH.
+// Validated against the official BIP-341 test vector in test/vectors.mjs.
+
+import { secp256k1, schnorr } from "@noble/curves/secp256k1.js";
+import { sha256 } from "@noble/hashes/sha2.js";
+import { ripemd160 } from "@noble/hashes/legacy.js";
+import { segwitEncode, segwitDecode } from "./bech32.mjs";
+
+const Point = secp256k1.Point;
+// secp256k1 group order n (BIP-340/341 scalar modulus).
+const N = 0xfffffffffffffffffffffffffffffffebaaedce6af48a03bbfd25e8cd0364141n;
+
+function bytesToBigInt(b) {
+  let x = 0n;
+  for (const byte of b) x = (x << 8n) | BigInt(byte);
+  return x;
+}
+function bigIntTo32(x) {
+  const out = new Uint8Array(32);
+  for (let i = 31; i >= 0; i--) { out[i] = Number(x & 0xffn); x >>= 8n; }
+  return out;
+}
+
+/**
+ * BIP-341 key-path taproot tweak (no script tree): Q = P + int(tagged_hash("TapTweak", P))·G.
+ * @param {Uint8Array} internalXOnly 32-byte x-only internal public key
+ * @returns {Uint8Array} 32-byte x-only tweaked output key
+ */
+export function taprootTweakOutputKey(internalXOnly) {
+  if (!(internalXOnly instanceof Uint8Array) || internalXOnly.length !== 32) {
+    throw new Error("internal key must be a 32-byte x-only public key");
+  }
+  // BIP-341: t = int(hashTapTweak(P)); fail if t >= n (don't silently reduce).
+  const t = bytesToBigInt(schnorr.utils.taggedHash("TapTweak", internalXOnly));
+  if (t === 0n || t >= N) throw new Error("taproot tweak out of range");
+  const P = schnorr.utils.lift_x(bytesToBigInt(internalXOnly)); // even-Y internal point
+  const Q = P.add(Point.BASE.multiply(t));
+  if (Q.is0()) throw new Error("taproot: output key is the point at infinity");
+  return bigIntTo32(Q.toAffine().x);
+}
+
+const VALID_HRP = new Set(["bc", "tb", "bcrt"]);
+function assertHrp(hrp) {
+  if (!VALID_HRP.has(hrp)) throw new Error(`unknown network HRP '${hrp}' (expected bc | tb | bcrt)`);
+}
+
+/**
+ * Derive a P2TR (Taproot) address `bc1p…` / `tb1p…` from an x-only internal key.
+ * @param {Uint8Array} internalXOnly 32-byte x-only internal public key
+ * @param {"bc"|"tb"|"bcrt"} [hrp="bc"] network prefix
+ */
+export function p2trAddress(internalXOnly, hrp = "bc") {
+  assertHrp(hrp);
+  const outputKey = taprootTweakOutputKey(internalXOnly);
+  const addr = segwitEncode(hrp, 1, outputKey);
+  if (!addr) throw new Error("failed to encode P2TR address");
+  return addr;
+}
+
+/**
+ * Decode a bech32/bech32m SegWit address into its scriptPubKey bytes, so we can pay it.
+ *   witver 0  → OP_0  PUSH<20|32> program      (P2WPKH / P2WSH)
+ *   witver 1+ → OP_n  PUSH32 program           (P2TR at v1)
+ * @param {string} addr the address
+ * @param {"bc"|"tb"|"bcrt"} [hrp="bc"] expected network
+ * @returns {Uint8Array} scriptPubKey
+ */
+export function addressToScriptPubKey(addr, hrp = "bc") {
+  assertHrp(hrp);
+  const dec = segwitDecode(hrp, addr);
+  if (!dec) throw new Error(`not a valid ${hrp} SegWit address: ${addr}`);
+  const op = dec.version === 0 ? 0x00 : 0x50 + dec.version; // OP_0 or OP_1..OP_16
+  const out = new Uint8Array(2 + dec.program.length);
+  out[0] = op; out[1] = dec.program.length; out.set(dec.program, 2);
+  return out;
+}
+
+/** HASH160 = RIPEMD160(SHA256(x)). */
+export function hash160(bytes) {
+  return ripemd160(sha256(bytes));
+}
+
+/**
+ * Derive a native-SegWit P2WPKH address `bc1q…` from a 33-byte compressed pubkey.
+ * @param {Uint8Array} compressedPub 33-byte compressed secp256k1 public key
+ * @param {"bc"|"tb"|"bcrt"} [hrp="bc"]
+ */
+export function p2wpkhAddress(compressedPub, hrp = "bc") {
+  assertHrp(hrp);
+  // Reject anything but a 33-byte compressed secp256k1 pubkey — a P2WPKH over an
+  // uncompressed/malformed key is non-standard and unspendable; returning it as a valid
+  // address is a fund-loss foot-gun.
+  if (!(compressedPub instanceof Uint8Array) || compressedPub.length !== 33 ||
+      (compressedPub[0] !== 0x02 && compressedPub[0] !== 0x03)) {
+    throw new Error("P2WPKH requires a 33-byte compressed public key (0x02/0x03 prefix)");
+  }
+  const addr = segwitEncode(hrp, 0, hash160(compressedPub));
+  if (!addr) throw new Error("failed to encode P2WPKH address");
+  return addr;
+}