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

package/src/stealth.ts

@@ -401,21 +401,21 @@ export interface NonInteractiveDepositWithRefundResult extends NonInteractiveDep
 export async function createNonInteractiveDeposit(
   recipientMeta: StealthMetaAddress,
   custodyInternalKey: Uint8Array,
-  network?: "mainnet" | "testnet" | "regtest",
+  network?: BitcoinNetwork,
   userRefundPubkey?: undefined,
   opReturnContext?: DepositOpReturnContext,
 ): Promise<NonInteractiveDepositResult>;
 export async function createNonInteractiveDeposit(
   recipientMeta: StealthMetaAddress,
   custodyInternalKey: Uint8Array,
-  network: "mainnet" | "testnet" | "regtest",
+  network: BitcoinNetwork,
   userRefundPubkey: Uint8Array,
   opReturnContext: DepositOpReturnContext,
 ): Promise<NonInteractiveDepositWithRefundResult>;
 export async function createNonInteractiveDeposit(
   recipientMeta: StealthMetaAddress,
   custodyInternalKey: Uint8Array,
-  network: "mainnet" | "testnet" | "regtest" = "testnet",
+  network: BitcoinNetwork = "testnet",
   userRefundPubkey?: Uint8Array,
   opReturnContext?: DepositOpReturnContext,
 ): Promise<NonInteractiveDepositResult | NonInteractiveDepositWithRefundResult> {
@@ -491,7 +491,7 @@ export async function createNonInteractiveDeposit(
 export async function createDirectVaultDeposit(
   recipientMeta: StealthMetaAddress,
   vaultXOnlyPubkey: Uint8Array,
-  network: "mainnet" | "testnet" | "regtest" = "testnet",
+  network: BitcoinNetwork = "testnet",
   opReturnContext?: DepositOpReturnContext,
 ): Promise<NonInteractiveDepositResult> {
   if (!opReturnContext) {
@@ -735,7 +735,7 @@ export async function createTweakDeposit(
   recipientMeta: StealthMetaAddress,
   vaultXOnlyPubkey: Uint8Array,
   recovery: DepositRecoveryMaterial,
-  network: "mainnet" | "testnet" | "regtest" = "testnet",
+  network: BitcoinNetwork = "testnet",
 ): Promise<TweakDepositResult> {
   if (vaultXOnlyPubkey.length !== 32) {
     throw new Error("vaultXOnlyPubkey must be 32 bytes");
@@ -781,7 +781,7 @@ export async function createTweakDeposit(
  */
 export async function createDepositFromConfig(
   recipientMeta: StealthMetaAddress,
-  network: "mainnet" | "testnet" | "regtest" = "testnet",
+  network: BitcoinNetwork = "testnet",
   opReturnContext?: DepositOpReturnContext,
 ): Promise<NonInteractiveDepositResult> {
   const config = getConfig();
@@ -1220,6 +1220,7 @@ export async function scanUnifiedNotes(
 // ========== Connection Adapter ==========
 
 import type { Address } from "@solana/kit";
+import type { BitcoinNetwork } from "./taproot";
 
 export interface ConnectionAdapter {
   getAccountInfo: (
@@ -1285,23 +1286,6 @@ export function packStealthOutputForCircuit(output: StealthOutputData): CircuitS
   };
 }
 
-/**
- * Unpack encrypted amount from packed Field element
- */
-export function unpackEncryptedAmountWithSign(packed: bigint): { encryptedAmount: Uint8Array; ySign: boolean } {
-  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/src/taproot.ts

@@ -8,7 +8,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
@@ -31,7 +31,7 @@ const UNSAFE_GENERATOR_INTERNAL_KEY_HEX =
  */
 export function deriveTaprootAddress(
   commitment: Uint8Array,
-  network: "mainnet" | "testnet" | "regtest" = "testnet",
+  network: BitcoinNetwork = "testnet",
   internalKey?: Uint8Array
 ): {
   address: string;
@@ -77,11 +77,7 @@ export function deriveTaprootAddress(
   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,
@@ -164,7 +160,7 @@ export function depositLeafScript(
 export function deriveDepositAddress(
   commitment: Uint8Array,
   ikaXOnlyPubkey: Uint8Array,
-  network: "mainnet" | "testnet" | "regtest" = "testnet"
+  network: BitcoinNetwork = "testnet"
 ): {
   address: string;
   outputKey: Uint8Array;
@@ -203,25 +199,73 @@ export function verifyTaprootAddress(
   internalKey?: Uint8Array
 ): boolean {
   try {
-    const decoded = bech32.bech32m.decode(address);
+    const decoded = bech32m.decode(address as `${string}1${string}`);
     const witnessVersion = decoded.words[0];
     if (witnessVersion !== 1) {
       return false;
     }
 
-    const actualOutputKey = new Uint8Array(
-      bech32.bech32m.fromWords(decoded.words.slice(1))
-    );
+    const network = networkForHrp(decoded.prefix);
+    if (!network) return false;
 
-    const network = decoded.prefix === "bc" ? "mainnet" : "testnet";
     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;
   }
 }
 
+/**
+ * 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 function bech32Hrp(network: BitcoinNetwork): string {
+  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: string): BitcoinNetwork | null {
+  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: Uint8Array,
+  network: BitcoinNetwork,
+): string {
+  return bech32m.encode(bech32Hrp(network), [1, ...bech32m.toWords(outputKey)]);
+}
+
 /**
  * Generate a P2TR (Pay-to-Taproot) script pubkey
  *
@@ -264,18 +308,19 @@ export function parseP2TRScriptPubkey(
 export function isValidBitcoinAddress(address: string): {
   valid: boolean;
   type: "p2pkh" | "p2sh" | "p2wpkh" | "p2wsh" | "p2tr" | "unknown";
-  network: "mainnet" | "testnet" | "unknown";
+  network: BitcoinNetwork | "unknown";
 } {
   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 as `${string}1${string}`);
+      const network = networkForHrp(decoded.prefix);
+      if (network && decoded.words[0] === 1 && decoded.words.length === 53) {
+        return { valid: true, type: "p2tr", network };
       }
     }
 
@@ -285,19 +330,11 @@ export function isValidBitcoinAddress(address: string): {
       address.startsWith("tb1q") ||
       address.startsWith("bcrt1q")
     ) {
-      const decoded = bech32.bech32.decode(address);
-      if (decoded.words[0] === 0) {
+      const decoded = bech32.decode(address as `${string}1${string}`);
+      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 };
       }
     }
 
@@ -623,7 +660,7 @@ export function deriveTaprootAddressWithRefund(
   npk: Uint8Array,
   userRefundPubkey: Uint8Array,
   internalKey: Uint8Array,
-  network: "mainnet" | "testnet" | "regtest" = "testnet"
+  network: BitcoinNetwork = "testnet"
 ): {
   address: string;
   outputKey: Uint8Array;
@@ -672,9 +709,7 @@ export function deriveTaprootAddressWithRefund(
   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,

package/src/vk-registry.ts

@@ -293,3 +293,55 @@ export function isVkRegistryReady(
     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: SnarkjsVkeyJson,
+  registryData: Uint8Array | null | undefined,
+  nInputs: number,
+  nOutputs: number,
+): void {
+  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: Uint8Array): string {
+  return Array.from(b, (x) => x.toString(16).padStart(2, "0")).join("");
+}