@utxopia/sdk 0.1.0-alpha.4 → 0.1.0-alpha.6

package/dist/prover/web.js

@@ -10,9 +10,8 @@
  * - Signature = EdDSA-Poseidon over (merkleRoot, boundParamsHash, nullifiers..., commitmentsOut...)
  */
 import { poseidonHashSync, computeJoinSplitCommitmentSync, computeJoinSplitNullifierSync, } from "../poseidon";
-import { BN254_FIELD_PRIME } from "../crypto";
+import { BN254_FIELD_PRIME, bytesToHex } from "../crypto";
 import { TREE_DEPTH } from "../merkle";
-import { getConfig } from "../config";
 import { MAX_SAFE_JOINSPLIT_SIZE } from "../vk-registry";
 /** Maximum satoshis (total BTC supply) */
 const MAX_SATOSHIS = 21000000n * 100000000n;
@@ -42,6 +41,26 @@ const isBrowser = typeof window !== "undefined";
 const isNode = typeof process !== "undefined" && process.versions?.node;
 // Configurable circuit paths
 let circuitBasePath = isBrowser ? "/circuits/groth16" : "./circuits";
+/**
+ * Fetch a circuit's `*.vkey.json` from the same base path its zkey comes from.
+ *
+ * Deliberately reads `circuitBasePath` rather than taking a URL: the point of the check this
+ * feeds (`assertVkeyMatchesRegistry`) is that the vkey describes the artifacts actually being
+ * proved with, and a caller-supplied URL could describe a different build entirely.
+ */
+export async function fetchCircuitVkey(circuitType) {
+    const cached = vkeyCache.get(circuitType);
+    if (cached)
+        return cached;
+    const url = `${circuitBasePath}/${circuitType}/${circuitType}.vkey.json`;
+    const res = await fetch(url);
+    if (!res.ok) {
+        throw new Error(`Could not fetch circuit vkey ${url}: ${res.status} ${res.statusText}`);
+    }
+    const vkey = await res.json();
+    vkeyCache.set(circuitType, vkey);
+    return vkey;
+}
 /**
  * Set the base path for circuit artifacts
  */
@@ -50,18 +69,14 @@ export function setCircuitPath(path) {
         return;
     circuitBasePath = path;
     circuitCache.clear();
+    vkeyCache.clear();
     artifactBytesCache.clear();
     artifactDownloadCache.clear();
 }
-/**
- * Get the current circuit base path
- */
-export function getCircuitPath() {
-    return circuitBasePath;
-}
 // Lazy-loaded snarkjs module
 let snarkjs = null;
 const circuitCache = new Map();
+const vkeyCache = new Map();
 let proverInitialized = false;
 /**
  * Load snarkjs module
@@ -115,7 +130,6 @@ export function setCircuitArtifactDigests(digests) {
     // Anything admitted under the old policy must be re-checked under the new one.
     artifactBytesCache.clear();
 }
-const toHex = (buf) => Array.from(new Uint8Array(buf), (b) => b.toString(16).padStart(2, "0")).join("");
 async function verifyArtifactBytes(url, bytes) {
     if (!artifactDigests)
         return;
@@ -125,7 +139,7 @@ async function verifyArtifactBytes(url, bytes) {
         throw new Error(`No integrity digest recorded for circuit artifact ${url} — refusing to prove. ` +
             `Regenerate the artifact manifest so it covers every shape this origin serves.`);
     }
-    const actual = toHex(await crypto.subtle.digest("SHA-256", bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength)));
+    const actual = bytesToHex(new Uint8Array(await crypto.subtle.digest("SHA-256", bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength))));
     if (actual !== artifactDigests[key]) {
         throw new Error(`Circuit artifact ${key} failed its integrity check (expected ${artifactDigests[key]}, ` +
             `got ${actual}). Refusing to prove against an artifact this build does not recognise.`);
@@ -556,42 +570,3 @@ export async function cleanup() {
 // ==========================================================================
 // Solana Instruction Building (for Groth16 on-chain verification)
 // ==========================================================================
-/**
- * Groth16 verifier program ID (from current config)
- */
-export function getGroth16VerifierProgramId() {
-    const config = getConfig();
-    return config.groth16VerifierProgramId;
-}
-/**
- * Build instruction data for Groth16 verification
- */
-export function buildVerifyInstructionData(proof, publicSignals, vkHash) {
-    const piBytes = publicSignals.flatMap((pi) => {
-        const bytes = new Array(32).fill(0);
-        const bigint = BigInt(pi);
-        for (let i = 31; i >= 0; i--) {
-            bytes[i] = Number((bigint >> BigInt((31 - i) * 8)) & 0xffn);
-        }
-        return bytes;
-    });
-    const cleanHex = vkHash.startsWith("0x") ? vkHash.slice(2) : vkHash;
-    const vkHashBytes = new Uint8Array(cleanHex.length / 2);
-    for (let i = 0; i < vkHashBytes.length; i++) {
-        vkHashBytes[i] = parseInt(cleanHex.substr(i * 2, 2), 16);
-    }
-    const totalSize = proof.length + 4 + piBytes.length + 32;
-    const data = new Uint8Array(totalSize);
-    let offset = 0;
-    data.set(proof, offset);
-    offset += proof.length;
-    const piCount = publicSignals.length;
-    data[offset++] = piCount & 0xff;
-    data[offset++] = (piCount >> 8) & 0xff;
-    data[offset++] = (piCount >> 16) & 0xff;
-    data[offset++] = (piCount >> 24) & 0xff;
-    data.set(new Uint8Array(piBytes), offset);
-    offset += piBytes.length;
-    data.set(vkHashBytes, offset);
-    return data;
-}

package/dist/psbt.d.ts

@@ -9,6 +9,7 @@
  *
  * Uses @scure/btc-signer for PSBT construction.
  */
+import { type BitcoinNetwork } from "./taproot";
 /** UTXO descriptor for PSBT inputs */
 export interface UtxoDescriptor {
     /** Transaction ID (hex, 64 chars) */
@@ -44,7 +45,7 @@ export interface BuildDepositPsbtParams {
     /** Fee rate in sats/vbyte */
     feeRate: number;
     /** Bitcoin network */
-    network?: "mainnet" | "testnet" | "signet";
+    network?: BitcoinNetwork;
 }
 /** Result of PSBT construction */
 export interface BuildDepositPsbtResult {

package/dist/psbt.js

@@ -11,7 +11,7 @@
  */
 import * as btc from "@scure/btc-signer";
 import { hex } from "@scure/base";
-import { DEPOSIT_OP_RETURN_SIZE, createOpReturnScriptFromPayload } from "./taproot";
+import { DEPOSIT_OP_RETURN_SIZE, createOpReturnScriptFromPayload, bech32Hrp } from "./taproot";
 // =============================================================================
 // Constants
 // =============================================================================
@@ -64,7 +64,11 @@ export function buildDepositPsbt(params) {
     if (opReturnPayload && opReturnPayload.length !== DEPOSIT_OP_RETURN_SIZE) {
         throw new Error(`OP_RETURN payload must be ${DEPOSIT_OP_RETURN_SIZE} bytes, got ${opReturnPayload.length}`);
     }
-    const btcNetwork = network === "mainnet" ? btc.NETWORK : btc.TEST_NETWORK;
+    // Regtest shares testnet's version bytes but not its bech32 hrp, so folding it
+    // into TEST_NETWORK leaves every bcrt1 address undecodable.
+    const btcNetwork = network === "mainnet"
+        ? btc.NETWORK
+        : { ...btc.TEST_NETWORK, bech32: bech32Hrp(network) };
     // Calculate total input value
     const totalInput = senderUtxos.reduce((sum, u) => sum + u.value, 0);
     // Detect input type from first UTXO

package/dist/spend-doc.js

@@ -11,6 +11,7 @@
  * Poseidon(merkleRoot, boundParamsHash, nullifiers.., commitmentsOut..).
  */
 import { computeSolanaDomainBoundParamsHash, createRedeemBoundParams, createTransferBoundParams, createUnshieldBoundParams, } from "./bound-params";
+import { bytesToHex as hex } from "./crypto";
 export class SpendDocMismatch extends Error {
 }
 function fmt(raw, decimals) {
@@ -20,7 +21,6 @@ function fmt(raw, decimals) {
     const frac = decimals === 0 ? "" : s.slice(s.length - decimals).replace(/0+$/, "");
     return `${neg ? "-" : ""}${whole}${frac ? `.${frac}` : ""}`;
 }
-const hex = (b) => Array.from(b, (x) => x.toString(16).padStart(2, "0")).join("");
 function sortedValues(v) {
     return [...v].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0)).join(",");
 }

package/dist/stealth.d.ts

@@ -189,8 +189,8 @@ export interface NonInteractiveDepositWithRefundResult extends NonInteractiveDep
  * @param network - Bitcoin network for address encoding
  * @param userRefundPubkey - Optional 32-byte x-only pubkey for refund script path
  */
-export declare function createNonInteractiveDeposit(recipientMeta: StealthMetaAddress, custodyInternalKey: Uint8Array, network?: "mainnet" | "testnet" | "regtest", userRefundPubkey?: undefined, opReturnContext?: DepositOpReturnContext): Promise<NonInteractiveDepositResult>;
-export declare function createNonInteractiveDeposit(recipientMeta: StealthMetaAddress, custodyInternalKey: Uint8Array, network: "mainnet" | "testnet" | "regtest", userRefundPubkey: Uint8Array, opReturnContext: DepositOpReturnContext): Promise<NonInteractiveDepositWithRefundResult>;
+export declare function createNonInteractiveDeposit(recipientMeta: StealthMetaAddress, custodyInternalKey: Uint8Array, network?: BitcoinNetwork, userRefundPubkey?: undefined, opReturnContext?: DepositOpReturnContext): Promise<NonInteractiveDepositResult>;
+export declare function createNonInteractiveDeposit(recipientMeta: StealthMetaAddress, custodyInternalKey: Uint8Array, network: BitcoinNetwork, userRefundPubkey: Uint8Array, opReturnContext: DepositOpReturnContext): Promise<NonInteractiveDepositWithRefundResult>;
 /**
  * Create a non-interactive deposit directly to an Ika-controlled vault.
  *
@@ -199,7 +199,7 @@ export declare function createNonInteractiveDeposit(recipientMeta: StealthMetaAd
  * in OP_RETURN(header || poolTag || ephemeralPub || npk), and the destination chain
  * credits the note from that transaction.
  */
-export declare function createDirectVaultDeposit(recipientMeta: StealthMetaAddress, vaultXOnlyPubkey: Uint8Array, network?: "mainnet" | "testnet" | "regtest", opReturnContext?: DepositOpReturnContext): Promise<NonInteractiveDepositResult>;
+export declare function createDirectVaultDeposit(recipientMeta: StealthMetaAddress, vaultXOnlyPubkey: Uint8Array, network?: BitcoinNetwork, opReturnContext?: DepositOpReturnContext): Promise<NonInteractiveDepositResult>;
 /**
  * The delegable half of deposit recovery.
  *
@@ -322,7 +322,7 @@ export interface TweakDepositResult {
  * with no OP_RETURN is invisible to block scanning, so an unregistered address
  * is one nobody is watching.
  */
-export declare function createTweakDeposit(recipientMeta: StealthMetaAddress, vaultXOnlyPubkey: Uint8Array, recovery: DepositRecoveryMaterial, network?: "mainnet" | "testnet" | "regtest"): Promise<TweakDepositResult>;
+export declare function createTweakDeposit(recipientMeta: StealthMetaAddress, vaultXOnlyPubkey: Uint8Array, recovery: DepositRecoveryMaterial, network?: BitcoinNetwork): Promise<TweakDepositResult>;
 /**
  * Create a non-interactive deposit using the current SDK config.
  *
@@ -333,7 +333,7 @@ export declare function createTweakDeposit(recipientMeta: StealthMetaAddress, va
  * credits the note by SPV-verifying that deposit transaction directly. Legacy sweep-mode
  * address derivation is intentionally not selected from config anymore.
  */
-export declare function createDepositFromConfig(recipientMeta: StealthMetaAddress, network?: "mainnet" | "testnet" | "regtest", opReturnContext?: DepositOpReturnContext): Promise<NonInteractiveDepositResult>;
+export declare function createDepositFromConfig(recipientMeta: StealthMetaAddress, network?: BitcoinNetwork, opReturnContext?: DepositOpReturnContext): Promise<NonInteractiveDepositResult>;
 export declare function isDirectVaultDepositMode(mode?: string): boolean;
 /**
  * Choose the Taproot internal key for deposit-address derivation.
@@ -448,6 +448,7 @@ export declare function scanUnifiedNotesMulti(source: WalletSignerAdapter | UTXO
  */
 export declare function scanUnifiedNotes(source: WalletSignerAdapter | UTXOpiaKeys, announcements: OnChainStealthAnnouncement[], tokenId: bigint): Promise<ScannedNote[]>;
 import type { Address } from "@solana/kit";
+import type { BitcoinNetwork } from "./taproot";
 export interface ConnectionAdapter {
     getAccountInfo: (pubkey: Address) => Promise<{
         data: Uint8Array;
@@ -480,13 +481,6 @@ export declare function packEncryptedAmountWithSign(encryptedAmount: Uint8Array,
  * Convert StealthOutputData to circuit-ready format
  */
 export declare function packStealthOutputForCircuit(output: StealthOutputData): CircuitStealthOutput;
-/**
- * Unpack encrypted amount from packed Field element
- */
-export declare function unpackEncryptedAmountWithSign(packed: bigint): {
-    encryptedAmount: Uint8Array;
-    ySign: boolean;
-};
 /**
  * Create stealth output data for a self-send (change output)
  */

package/dist/stealth.js

@@ -737,20 +737,6 @@ export function packStealthOutputForCircuit(output) {
         encryptedAmountWithSign,
     };
 }
-/**
- * Unpack encrypted amount from packed Field element
- */
-export function unpackEncryptedAmountWithSign(packed) {
-    const ySign = (packed & (1n << 64n)) !== 0n;
-    const amount = packed & ((1n << 64n) - 1n);
-    const encryptedAmount = new Uint8Array(8);
-    let temp = amount;
-    for (let i = 0; i < 8; i++) {
-        encryptedAmount[i] = Number(temp & 0xffn);
-        temp >>= 8n;
-    }
-    return { encryptedAmount, ySign };
-}
 /**
  * Create stealth output data for a self-send (change output)
  */

package/dist/taproot.d.ts

@@ -18,7 +18,7 @@
  * @param internalKey - Configured FROST/Ika custody key (x-only, 32 bytes; required)
  * @returns Taproot address (bc1p... or tb1p...)
  */
-export declare function deriveTaprootAddress(commitment: Uint8Array, network?: "mainnet" | "testnet" | "regtest", internalKey?: Uint8Array): {
+export declare function deriveTaprootAddress(commitment: Uint8Array, network?: BitcoinNetwork, internalKey?: Uint8Array): {
     address: string;
     outputKey: Uint8Array;
     tweak: Uint8Array;
@@ -64,7 +64,7 @@ export declare function depositLeafScript(commitment: Uint8Array, ikaXOnlyPubkey
  * Returns everything the sweeper needs to spend it: a script-path witness is
  * `[signature, leafScript, controlBlock]`.
  */
-export declare function deriveDepositAddress(commitment: Uint8Array, ikaXOnlyPubkey: Uint8Array, network?: "mainnet" | "testnet" | "regtest"): {
+export declare function deriveDepositAddress(commitment: Uint8Array, ikaXOnlyPubkey: Uint8Array, network?: BitcoinNetwork): {
     address: string;
     outputKey: Uint8Array;
     leafScript: Uint8Array;
@@ -80,6 +80,34 @@ export declare function deriveDepositAddress(commitment: Uint8Array, ikaXOnlyPub
  * @returns true if address matches expected derivation
  */
 export declare function verifyTaprootAddress(address: string, commitment: Uint8Array, internalKey?: Uint8Array): boolean;
+/**
+ * The networks whose addresses this SDK derives.
+ *
+ * Kept as one alias because the members drifted when it was spelled out at each
+ * call site: psbt.ts folded regtest into testnet while taproot.ts did not, and
+ * the two disagreed about what a bcrt1 address was.
+ */
+export type BitcoinNetwork = "mainnet" | "testnet" | "signet" | "regtest";
+/**
+ * bech32 human-readable prefix for a Bitcoin network.
+ *
+ * Regtest is the reason this exists: it shares testnet's version bytes but not
+ * its prefix, and every place that folded the two together produced addresses
+ * no regtest node would accept.
+ */
+export declare function bech32Hrp(network: BitcoinNetwork): string;
+/**
+ * The network an address's bech32 prefix names, or null if it names none.
+ *
+ * Null rather than a testnet default: an unrecognised prefix is an address this
+ * SDK cannot place, and quietly calling it testnet is how bcrt1 addresses ended
+ * up classified as testnet everywhere.
+ */
+export declare function networkForHrp(prefix: string): BitcoinNetwork | null;
+/**
+ * Encode an x-only output key as a witness-v1 (P2TR) address.
+ */
+export declare function p2trAddress(outputKey: Uint8Array, network: BitcoinNetwork): string;
 /**
  * Generate a P2TR (Pay-to-Taproot) script pubkey
  *
@@ -100,7 +128,7 @@ export declare function parseP2TRScriptPubkey(scriptPubkey: Uint8Array): Uint8Ar
 export declare function isValidBitcoinAddress(address: string): {
     valid: boolean;
     type: "p2pkh" | "p2sh" | "p2wpkh" | "p2wsh" | "p2tr" | "unknown";
-    network: "mainnet" | "testnet" | "unknown";
+    network: BitcoinNetwork | "unknown";
 };
 /** Destination chain encoded in the compact deposit OP_RETURN header. */
 export declare const DEPOSIT_DESTINATION_CHAIN: {
@@ -201,7 +229,7 @@ export declare function computeTapLeafHash(script: Uint8Array, leafVersion?: num
  * @param internalKey - 32-byte x-only FROST group public key
  * @param network - Bitcoin network for address encoding
  */
-export declare function deriveTaprootAddressWithRefund(npk: Uint8Array, userRefundPubkey: Uint8Array, internalKey: Uint8Array, network?: "mainnet" | "testnet" | "regtest"): {
+export declare function deriveTaprootAddressWithRefund(npk: Uint8Array, userRefundPubkey: Uint8Array, internalKey: Uint8Array, network?: BitcoinNetwork): {
     address: string;
     outputKey: Uint8Array;
     merkleRoot: Uint8Array;

package/dist/taproot.js

@@ -7,7 +7,7 @@
  */
 import { sha256 } from "@noble/hashes/sha2.js";
 import { taggedHash, hexToBytes, bytesToHex } from "./crypto";
-import * as bech32 from "bech32";
+import { bech32, bech32m } from "@scure/base";
 import { secp256k1 } from "@noble/curves/secp256k1.js";
 // Never use the secp256k1 generator as a custody key. Its discrete log is
 // public, so a key-path output derived from it is sweepable by anyone.
@@ -59,11 +59,7 @@ export function deriveTaprootAddress(commitment, network = "testnet", internalKe
     // x-only output key (BIP-340): drop prefix from compressed form
     const outputKeyHex = outputPoint.toHex(true); // 33-byte compressed hex
     const outputKey = hexToBytes(outputKeyHex.slice(2)); // drop "02"/"03" prefix
-    // Encode as bech32m address
-    const hrp = network === "mainnet" ? "bc" : network === "regtest" ? "bcrt" : "tb";
-    const words = bech32.bech32m.toWords(outputKey);
-    // Witness version 1 for taproot
-    const address = bech32.bech32m.encode(hrp, [1, ...words]);
+    const address = p2trAddress(outputKey, network);
     return {
         address,
         outputKey,
@@ -151,20 +147,56 @@ export function deriveDepositAddress(commitment, ikaXOnlyPubkey, network = "test
  */
 export function verifyTaprootAddress(address, commitment, internalKey) {
     try {
-        const decoded = bech32.bech32m.decode(address);
+        const decoded = bech32m.decode(address);
         const witnessVersion = decoded.words[0];
         if (witnessVersion !== 1) {
             return false;
         }
-        const actualOutputKey = new Uint8Array(bech32.bech32m.fromWords(decoded.words.slice(1)));
-        const network = decoded.prefix === "bc" ? "mainnet" : "testnet";
+        const network = networkForHrp(decoded.prefix);
+        if (!network)
+            return false;
         const expected = deriveTaprootAddress(commitment, network, internalKey);
-        return arraysEqual(actualOutputKey, expected.outputKey);
+        // Compare the whole address, not just the output key: the key is identical
+        // on every network, so an output-key match said nothing about the encoding.
+        // bech32 is case-insensitive, hence the fold.
+        return address.toLowerCase() === expected.address;
     }
     catch {
         return false;
     }
 }
+/**
+ * bech32 human-readable prefix for a Bitcoin network.
+ *
+ * Regtest is the reason this exists: it shares testnet's version bytes but not
+ * its prefix, and every place that folded the two together produced addresses
+ * no regtest node would accept.
+ */
+export function bech32Hrp(network) {
+    return network === "mainnet" ? "bc" : network === "regtest" ? "bcrt" : "tb";
+}
+/**
+ * The network an address's bech32 prefix names, or null if it names none.
+ *
+ * Null rather than a testnet default: an unrecognised prefix is an address this
+ * SDK cannot place, and quietly calling it testnet is how bcrt1 addresses ended
+ * up classified as testnet everywhere.
+ */
+export function networkForHrp(prefix) {
+    return prefix === "bc"
+        ? "mainnet"
+        : prefix === "tb"
+            ? "testnet"
+            : prefix === "bcrt"
+                ? "regtest"
+                : null;
+}
+/**
+ * Encode an x-only output key as a witness-v1 (P2TR) address.
+ */
+export function p2trAddress(outputKey, network) {
+    return bech32m.encode(bech32Hrp(network), [1, ...bech32m.toWords(outputKey)]);
+}
 /**
  * Generate a P2TR (Pay-to-Taproot) script pubkey
  *
@@ -203,32 +235,24 @@ export function parseP2TRScriptPubkey(scriptPubkey) {
 export function isValidBitcoinAddress(address) {
     try {
         // Bech32m (Taproot)
-        if (address.startsWith("bc1p") || address.startsWith("tb1p")) {
-            const decoded = bech32.bech32m.decode(address);
-            if (decoded.words[0] === 1 && decoded.words.length === 53) {
-                return {
-                    valid: true,
-                    type: "p2tr",
-                    network: decoded.prefix === "bc" ? "mainnet" : "testnet",
-                };
+        if (address.startsWith("bc1p") ||
+            address.startsWith("tb1p") ||
+            address.startsWith("bcrt1p")) {
+            const decoded = bech32m.decode(address);
+            const network = networkForHrp(decoded.prefix);
+            if (network && decoded.words[0] === 1 && decoded.words.length === 53) {
+                return { valid: true, type: "p2tr", network };
             }
         }
         // Bech32 (SegWit v0)
         if (address.startsWith("bc1q") ||
             address.startsWith("tb1q") ||
             address.startsWith("bcrt1q")) {
-            const decoded = bech32.bech32.decode(address);
-            if (decoded.words[0] === 0) {
+            const decoded = bech32.decode(address);
+            const network = networkForHrp(decoded.prefix);
+            if (network && decoded.words[0] === 0) {
                 const type = decoded.words.length === 33 ? "p2wpkh" : "p2wsh";
-                return {
-                    valid: true,
-                    type,
-                    network: decoded.prefix === "bc"
-                        ? "mainnet"
-                        : decoded.prefix === "bcrt"
-                            ? "testnet"
-                            : "testnet",
-                };
+                return { valid: true, type, network };
             }
         }
         // Legacy (base58check)
@@ -533,9 +557,7 @@ export function deriveTaprootAddressWithRefund(npk, userRefundPubkey, internalKe
     controlBlock[0] = 0xc0 | parityBit;
     controlBlock.set(internalKey, 1);
     // 7. Encode as bech32m address
-    const hrp = network === "mainnet" ? "bc" : network === "regtest" ? "bcrt" : "tb";
-    const words = bech32.bech32m.toWords(outputKey);
-    const address = bech32.bech32m.encode(hrp, [1, ...words]);
+    const address = p2trAddress(outputKey, network);
     return {
         address,
         outputKey,

package/dist/vk-registry.d.ts

@@ -98,3 +98,24 @@ export declare function parseVkRegistry(data: Uint8Array): ParsedVkRegistry;
 export declare function assertVkRegistryForShape(data: Uint8Array | null | undefined, nInputs: number, nOutputs: number): ParsedVkRegistry;
 /** True if `data` is an initialized `VkRegistry` for the given shape. */
 export declare function isVkRegistryReady(data: Uint8Array | null | undefined, nInputs: number, nOutputs: number): boolean;
+/**
+ * Assert the circuit artifacts this client loaded correspond to the verifying key the chain
+ * will check against.
+ *
+ * `assertVkRegistryForShape` proves the registry exists and names the right shape;
+ * `setCircuitArtifactDigests` proves the artifacts are the bytes this build expects. Neither
+ * ties the two together, and that gap is a real one: a zkey from a different phase-2 setup
+ * proves fine, downloads fine, passes every integrity check, and is then rejected on chain as
+ * "proof invalid" — with nothing pointing at the version mismatch.
+ *
+ * It is not hypothetical. `https://circuit.utxopia.com/circuits/groth16` and
+ * `.../circuits/v2/groth16` both serve 200s for every shape, with different `delta` — same
+ * ceremony, different per-circuit setup. Both therefore satisfy the program's own vk_hash
+ * recomputation, which binds delta+IC to the compiled-in alpha/beta/gamma and so catches a
+ * foreign ceremony but NOT a stale phase-2 from the right one. This is the check that does.
+ *
+ * @param vkey          The `*.vkey.json` fetched from the SAME base path as the zkey. Fetching
+ *                      it from anywhere else makes this assertion meaningless.
+ * @param registryData  Raw `VkRegistry` account data for the shape.
+ */
+export declare function assertVkeyMatchesRegistry(vkey: SnarkjsVkeyJson, registryData: Uint8Array | null | undefined, nInputs: number, nOutputs: number): void;

package/dist/vk-registry.js

@@ -210,3 +210,42 @@ export function isVkRegistryReady(data, nInputs, nOutputs) {
         return false;
     }
 }
+/**
+ * Assert the circuit artifacts this client loaded correspond to the verifying key the chain
+ * will check against.
+ *
+ * `assertVkRegistryForShape` proves the registry exists and names the right shape;
+ * `setCircuitArtifactDigests` proves the artifacts are the bytes this build expects. Neither
+ * ties the two together, and that gap is a real one: a zkey from a different phase-2 setup
+ * proves fine, downloads fine, passes every integrity check, and is then rejected on chain as
+ * "proof invalid" — with nothing pointing at the version mismatch.
+ *
+ * It is not hypothetical. `https://circuit.utxopia.com/circuits/groth16` and
+ * `.../circuits/v2/groth16` both serve 200s for every shape, with different `delta` — same
+ * ceremony, different per-circuit setup. Both therefore satisfy the program's own vk_hash
+ * recomputation, which binds delta+IC to the compiled-in alpha/beta/gamma and so catches a
+ * foreign ceremony but NOT a stale phase-2 from the right one. This is the check that does.
+ *
+ * @param vkey          The `*.vkey.json` fetched from the SAME base path as the zkey. Fetching
+ *                      it from anywhere else makes this assertion meaningless.
+ * @param registryData  Raw `VkRegistry` account data for the shape.
+ */
+export function assertVkeyMatchesRegistry(vkey, registryData, nInputs, nOutputs) {
+    const registry = assertVkRegistryForShape(registryData, nInputs, nOutputs);
+    const expectedIc = joinSplitNumPublicInputs(nInputs, nOutputs) + 1;
+    if (vkey.IC.length !== expectedIc) {
+        throw new Error(`Circuit vkey for JoinSplit ${nInputs}x${nOutputs} has ${vkey.IC.length} IC points, ` +
+            `expected ${expectedIc} — the artifacts are for a different shape.`);
+    }
+    const local = computeVkHash(vkey);
+    if (!local.every((b, i) => b === registry.vkHash[i])) {
+        throw new Error(`Circuit artifacts for JoinSplit ${nInputs}x${nOutputs} do not match the on-chain ` +
+            `verifying key (artifact vkHash ${bytesToHex(local)}, registry ${bytesToHex(registry.vkHash)}). ` +
+            `A proof built from these would be rejected as invalid. Usually the circuit base URL ` +
+            `points at a stale build — check it resolves to the same version the registry was ` +
+            `registered from.`);
+    }
+}
+function bytesToHex(b) {
+    return Array.from(b, (x) => x.toString(16).padStart(2, "0")).join("");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@utxopia/sdk",
-  "version": "0.1.0-alpha.4",
+  "version": "0.1.0-alpha.6",
   "description": "UTXOpia SDK - Private Bitcoin across Solana and Sui",
   "type": "module",
   "main": "dist/index.js",
@@ -27,40 +27,10 @@
       "import": "./dist/prover/mobile.js",
       "default": "./dist/prover/mobile.js"
     },
-    "./stealth": {
-      "types": "./dist/stealth/index.d.ts",
-      "import": "./dist/stealth/index.js",
-      "default": "./dist/stealth/index.js"
-    },
     "./bitcoin": {
       "types": "./dist/bitcoin/index.d.ts",
       "import": "./dist/bitcoin/index.js",
       "default": "./dist/bitcoin/index.js"
-    },
-    "./solana": {
-      "types": "./dist/solana/index.d.ts",
-      "import": "./dist/solana/index.js",
-      "default": "./dist/solana/index.js"
-    },
-    "./watcher": {
-      "types": "./dist/watcher/index.d.ts",
-      "import": "./dist/watcher/index.js",
-      "default": "./dist/watcher/index.js"
-    },
-    "./watcher/web": {
-      "types": "./dist/watcher/web.d.ts",
-      "import": "./dist/watcher/web.js",
-      "default": "./dist/watcher/web.js"
-    },
-    "./watcher/native": {
-      "types": "./dist/watcher/native.d.ts",
-      "import": "./dist/watcher/native.js",
-      "default": "./dist/watcher/native.js"
-    },
-    "./react": {
-      "types": "./dist/react/index.d.ts",
-      "import": "./dist/react/index.js",
-      "default": "./dist/react/index.js"
     }
   },
   "files": [
@@ -93,7 +63,6 @@
     "@scure/btc-signer": "2.0.1",
     "@solana-program/system": "^0.10.0",
     "@solana/kit": "^5.5.0",
-    "bech32": "^2.0.0",
     "circomlibjs": "^0.1.7",
     "poseidon-lite": "0.3.0"
   },

package/src/bitcoin/ika.ts

@@ -8,7 +8,7 @@
  */
 
 import { taggedHash, hexToBytes, bytesToHex } from "../crypto";
-import { bech32m } from "bech32";
+import { p2trAddress, type BitcoinNetwork } from "../taproot";
 import { secp256k1 } from "@noble/curves/secp256k1.js";
 
 /**
@@ -33,12 +33,12 @@ export type IkaDWalletRef =
  *   address = bech32m(hrp, [witness_version=1, ...words(output_key)])
  *
  * @param ref       The Ika dWallet reference (literal pubkey, or future async id).
- * @param network   "mainnet" | "testnet" | "regtest"
+ * @param network   BitcoinNetwork
  * @returns         The P2TR address (`bc1p…` / `tb1p…` / `bcrt1p…`)
  */
 export function deriveCustodyAddressFromIkaDWallet(
   ref: IkaDWalletRef,
-  network: "mainnet" | "testnet" | "regtest"
+  network: BitcoinNetwork
 ): string {
   const xonly = extractXOnly(ref);
   const tweak = taggedHash("TapTweak", xonly);
@@ -52,10 +52,7 @@ export function deriveCustodyAddressFromIkaDWallet(
   // Drop the 1-byte parity prefix to get the x-only output key.
   const outputKey = hexToBytes(outputPoint.toHex(true).slice(2));
 
-  const hrp =
-    network === "mainnet" ? "bc" : network === "regtest" ? "bcrt" : "tb";
-  const words = bech32m.toWords(outputKey);
-  return bech32m.encode(hrp, [1, ...words]);
+  return p2trAddress(outputKey, network);
 }
 
 /**
@@ -67,14 +64,12 @@ export function deriveCustodyAddressFromIkaDWallet(
  */
 export function deriveRawXOnlyP2TRAddress(
   xonlyPubkey: Uint8Array,
-  network: "mainnet" | "testnet" | "regtest"
+  network: BitcoinNetwork
 ): string {
   if (xonlyPubkey.length !== 32) {
     throw new Error("xonlyPubkey must be 32 bytes");
   }
-  const hrp =
-    network === "mainnet" ? "bc" : network === "regtest" ? "bcrt" : "tb";
-  return bech32m.encode(hrp, [1, ...bech32m.toWords(xonlyPubkey)]);
+  return p2trAddress(xonlyPubkey, network);
 }
 
 function extractXOnly(ref: IkaDWalletRef): Uint8Array {