@utxopia/sdk 0.1.0-alpha.3 → 0.1.0-alpha.5

package/src/instructions.ts

@@ -2191,124 +2191,6 @@ export { hexToBytes, bytesToHex } from "./crypto";
 // Permissioned Pool Builders
 // =============================================================================
 
-// ---------------------------------------------------------------------------
-// initializePermissioned (disc=21)
-// ---------------------------------------------------------------------------
-
-/** initializePermissioned instruction options */
-export interface InitializePermissionedOptions {
-  /** PDA bump for pool state */
-  poolBump: number;
-  /** PDA bump for commitment tree */
-  treeBump: number;
-  /** Deposit fee in basis points (u16 LE) */
-  depositFeeBps: number;
-  /** Withdrawal fee in basis points (u16 LE) */
-  withdrawalFeeBps: number;
-  /** Auditor's Solana pubkey (32 bytes) */
-  auditor: Uint8Array;
-  /** Auditor's viewing public key (32 bytes) */
-  auditorViewingPubkey: Uint8Array;
-  /** Account addresses — same layout as initialize (disc=0) */
-  accounts: {
-    /** 0. pool_state (writable) */
-    poolState: Address;
-    /** 1. commitment_tree (writable) */
-    commitmentTree: Address;
-    /** 2. zkbtc_mint (writable) */
-    zkbtcMint: Address;
-    /** 3. pool_vault (writable) */
-    poolVault: Address;
-    /** 4. deposit_vault (writable) */
-    depositVault: Address;
-    /** 5. authority (signer, writable — pays for storage) */
-    authority: Address;
-    /** 6. system_program (readonly) */
-    systemProgram: Address;
-  };
-}
-
-/**
- * Build initializePermissioned instruction data (disc=21).
- *
- * Layout (after disc byte — same as initialize plus two 32-byte fields):
- *   pool_bump(1) + tree_bump(1) + deposit_fee_bps(2 LE) + withdrawal_fee_bps(2 LE)
- *   + auditor(32) + auditor_viewing_pubkey(32)
- *   = 70 bytes of payload; 71 bytes total with disc.
- */
-export function buildInitializePermissionedInstructionData(options: {
-  poolBump: number;
-  treeBump: number;
-  depositFeeBps: number;
-  withdrawalFeeBps: number;
-  auditor: Uint8Array;
-  auditorViewingPubkey: Uint8Array;
-}): Uint8Array {
-  if (options.auditor.length !== 32) {
-    throw new Error(`auditor must be 32 bytes, got ${options.auditor.length}`);
-  }
-  if (options.auditorViewingPubkey.length !== 32) {
-    throw new Error(`auditorViewingPubkey must be 32 bytes, got ${options.auditorViewingPubkey.length}`);
-  }
-
-  // disc(1) + pool_bump(1) + tree_bump(1) + deposit_fee_bps(2) + withdrawal_fee_bps(2) + auditor(32) + auditor_viewing_pubkey(32) = 71
-  const data = new Uint8Array(71);
-  const view = new DataView(data.buffer);
-  let offset = 0;
-
-  data[offset++] = PERMISSIONED_DISC.INITIALIZE_PERMISSIONED; // disc = 21
-  data[offset++] = options.poolBump;
-  data[offset++] = options.treeBump;
-  view.setUint16(offset, options.depositFeeBps, true); offset += 2;
-  view.setUint16(offset, options.withdrawalFeeBps, true); offset += 2;
-  data.set(options.auditor, offset); offset += 32;
-  data.set(options.auditorViewingPubkey, offset);
-
-  return data;
-}
-
-/**
- * Build a complete initializePermissioned instruction (disc=21).
- *
- * Initializes a pool in permissioned mode; deposits/shields require auditor co-signing.
- *
- * Accounts (identical to initialize, disc=0):
- * 0. pool_state          (writable)
- * 1. commitment_tree     (writable)
- * 2. zkbtc_mint          (writable)
- * 3. pool_vault          (writable)
- * 4. deposit_vault       (writable)
- * 5. authority           (writable signer)
- * 6. system_program      (readonly)
- */
-export function buildInitializePermissionedInstruction(
-  options: InitializePermissionedOptions,
-): Instruction {
-  const config = getConfig();
-  const data = buildInitializePermissionedInstructionData({
-    poolBump: options.poolBump,
-    treeBump: options.treeBump,
-    depositFeeBps: options.depositFeeBps,
-    withdrawalFeeBps: options.withdrawalFeeBps,
-    auditor: options.auditor,
-    auditorViewingPubkey: options.auditorViewingPubkey,
-  });
-
-  return {
-    programAddress: config.utxopiaProgramId,
-    accounts: [
-      { address: options.accounts.poolState,      role: AccountRole.WRITABLE },
-      { address: options.accounts.commitmentTree, role: AccountRole.WRITABLE },
-      { address: options.accounts.zkbtcMint,      role: AccountRole.WRITABLE },
-      { address: options.accounts.poolVault,      role: AccountRole.WRITABLE },
-      { address: options.accounts.depositVault,   role: AccountRole.WRITABLE },
-      { address: options.accounts.authority,      role: AccountRole.WRITABLE_SIGNER },
-      { address: options.accounts.systemProgram,  role: AccountRole.READONLY },
-    ],
-    data,
-  };
-}
-
 // ---------------------------------------------------------------------------
 // completeDepositPermissioned (disc=22)
 // ---------------------------------------------------------------------------
@@ -2681,102 +2563,6 @@ export function buildRegisterExitDestinationInstruction(options: {
   };
 }
 
-// ---------------------------------------------------------------------------
-// setAuditorFrozen (disc=28)
-// ---------------------------------------------------------------------------
-
-/** setAuditorFrozen instruction options */
-export interface SetAuditorFrozenOptions {
-  /** true = freeze the auditor role; false = un-freeze */
-  frozen: boolean;
-  accounts: {
-    /** 0. pool_state (writable) */
-    poolState: Address;
-    /** 1. auditor (signer) */
-    auditor: Address;
-  };
-}
-
-/**
- * Build setAuditorFrozen instruction data (disc=28).
- *
- * Layout: disc(1) + frozen(1)  — frozen byte: 0 = not frozen, 1 = frozen.
- */
-export function buildSetAuditorFrozenInstructionData(frozen: boolean): Uint8Array {
-  return new Uint8Array([INSTRUCTION.SET_AUDITOR_FROZEN, frozen ? 1 : 0]);
-}
-
-/**
- * Build a complete setAuditorFrozen instruction (disc=28).
- *
- * Accounts:
- * 0. pool_state (writable)
- * 1. auditor    (signer)
- */
-export function buildSetAuditorFrozenInstruction(options: SetAuditorFrozenOptions): Instruction {
-  const config = getConfig();
-  return {
-    programAddress: config.utxopiaProgramId,
-    accounts: [
-      { address: options.accounts.poolState, role: AccountRole.WRITABLE },
-      { address: options.accounts.auditor,   role: AccountRole.READONLY_SIGNER },
-    ],
-    data: buildSetAuditorFrozenInstructionData(options.frozen),
-  };
-}
-
-// ---------------------------------------------------------------------------
-// setAuditorViewingPubkey (disc=29)
-// ---------------------------------------------------------------------------
-
-/** setAuditorViewingPubkey instruction options */
-export interface SetAuditorViewingPubkeyOptions {
-  /** New 32-byte viewing pubkey for the auditor */
-  viewingPubkey: Uint8Array;
-  accounts: {
-    /** 0. pool_state (writable) */
-    poolState: Address;
-    /** 1. auditor (signer) */
-    auditor: Address;
-  };
-}
-
-/**
- * Build setAuditorViewingPubkey instruction data (disc=29).
- *
- * Layout: disc(1) + viewing_pubkey(32) = 33 bytes.
- */
-export function buildSetAuditorViewingPubkeyInstructionData(viewingPubkey: Uint8Array): Uint8Array {
-  if (viewingPubkey.length !== 32) {
-    throw new Error(`viewingPubkey must be 32 bytes, got ${viewingPubkey.length}`);
-  }
-  const data = new Uint8Array(33);
-  data[0] = INSTRUCTION.SET_AUDITOR_VIEWING_PUBKEY;
-  data.set(viewingPubkey, 1);
-  return data;
-}
-
-/**
- * Build a complete setAuditorViewingPubkey instruction (disc=29).
- *
- * Accounts:
- * 0. pool_state (writable)
- * 1. auditor    (signer)
- */
-export function buildSetAuditorViewingPubkeyInstruction(
-  options: SetAuditorViewingPubkeyOptions,
-): Instruction {
-  const config = getConfig();
-  return {
-    programAddress: config.utxopiaProgramId,
-    accounts: [
-      { address: options.accounts.poolState, role: AccountRole.WRITABLE },
-      { address: options.accounts.auditor,   role: AccountRole.READONLY_SIGNER },
-    ],
-    data: buildSetAuditorViewingPubkeyInstructionData(options.viewingPubkey),
-  };
-}
-
 // ---------------------------------------------------------------------------
 // rotateAuditor (disc=35)
 // ---------------------------------------------------------------------------

package/src/poseidon.ts

@@ -164,12 +164,3 @@ export function computeTokenId(mintBytes: Uint8Array): bigint {
   const reduced = reduceToField(mintBytes);
   return poseidonHashSync([reduced, 0n]);
 }
-
-/**
- * Convenience: compute token_id from a Solana address string
- */
-export function computeTokenIdFromAddress(mintAddress: string): bigint {
-  // Base58 decode — import from @solana/kit if available, otherwise use raw bytes
-  // For now, caller should pass raw bytes via computeTokenId
-  throw new Error("Use computeTokenId(mintBytes) with raw pubkey bytes");
-}

package/src/prover/index.ts

@@ -9,11 +9,3 @@
 
 // Re-export everything from the web prover (default for browser/Node.js)
 export * from "./web";
-
-// Re-export types
-export type {
-  MerkleProofInput,
-  ProofData,
-  CircuitType,
-  JoinSplitProofInputs,
-} from "./web";

package/src/prover/web.ts

@@ -15,7 +15,7 @@ import {
   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";
@@ -60,13 +60,6 @@ export interface ProofData {
 
 export type CircuitType = `joinsplit_${number}x${number}`;
 
-/** Names of non-JoinSplit auxiliary circuits (selective disclosure). */
-export type AuxCircuitName =
-  | "ownership"
-  | "range_sum"
-  | "range_sum_4"
-  | "range_sum_16";
-
 // Environment detection
 const isBrowser = typeof window !== "undefined";
 const isNode = typeof process !== "undefined" && process.versions?.node;
@@ -85,13 +78,6 @@ export function setCircuitPath(path: string): void {
   artifactDownloadCache.clear();
 }
 
-/**
- * Get the current circuit base path
- */
-export function getCircuitPath(): string {
-  return circuitBasePath;
-}
-
 // Lazy-loaded snarkjs module
 let snarkjs: any = null;
 
@@ -164,9 +150,6 @@ export function setCircuitArtifactDigests(digests: Record<string, string> | null
   artifactBytesCache.clear();
 }
 
-const toHex = (buf: ArrayBuffer) =>
-  Array.from(new Uint8Array(buf), (b) => b.toString(16).padStart(2, "0")).join("");
-
 async function verifyArtifactBytes(url: string, bytes: Uint8Array): Promise<void> {
   if (!artifactDigests) return;
   // Key by path-under-base so one manifest works across origins (local dev vs CDN).
@@ -177,8 +160,8 @@ async function verifyArtifactBytes(url: string, bytes: Uint8Array): Promise<void
         `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) as ArrayBuffer),
+  const actual = bytesToHex(
+    new Uint8Array(await crypto.subtle.digest("SHA-256", bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength) as ArrayBuffer)),
   );
   if (actual !== artifactDigests[key]) {
     throw new Error(
@@ -717,55 +700,3 @@ export async function cleanup(): Promise<void> {
 // ==========================================================================
 // Solana Instruction Building (for Groth16 on-chain verification)
 // ==========================================================================
-
-/**
- * Groth16 verifier program ID (from current config)
- */
-export function getGroth16VerifierProgramId(): Address {
-  const config = getConfig();
-  return config.groth16VerifierProgramId;
-}
-
-/**
- * Build instruction data for Groth16 verification
- */
-export function buildVerifyInstructionData(
-  proof: Uint8Array,
-  publicSignals: string[],
-  vkHash: string
-): Uint8Array {
-  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/src/psbt.ts

@@ -12,7 +12,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, type BitcoinNetwork } from "./taproot";
 
 // =============================================================================
 // Types
@@ -41,13 +41,20 @@ export interface BuildDepositPsbtParams {
   /** Deposit amount in satoshis */
   depositAmountSats: number;
   /** Compact deposit OP_RETURN payload (from buildDepositOpReturn) */
-  opReturnPayload: Uint8Array;
+  /**
+   * 73-byte deposit metadata, for the OP_RETURN flow.
+   *
+   * Omit it for an OP_RETURN-free deposit (`verify_deposit`), where the address
+   * itself binds the note keys through its tapleaf. The transaction is then a
+   * plain payment, which is what lets an exchange withdrawal fund it.
+   */
+  opReturnPayload?: Uint8Array;
   /** Change address (same type as sender) */
   changeAddress: string;
   /** Fee rate in sats/vbyte */
   feeRate: number;
   /** Bitcoin network */
-  network?: "mainnet" | "testnet" | "signet";
+  network?: BitcoinNetwork;
 }
 
 /** Result of PSBT construction */
@@ -98,15 +105,17 @@ export function estimateDepositFee(
   feeRate: number,
   inputType: "p2tr" | "p2wpkh" = "p2tr",
   hasChange: boolean = true,
+  /** An OP_RETURN-free deposit has one output fewer; defaults true for callers
+   *  written before that flow existed. */
+  hasOpReturn: boolean = true,
 ): number {
   const inputVbytes = inputType === "p2tr" ? P2TR_INPUT_VBYTES : P2WPKH_INPUT_VBYTES;
-  const outputCount = hasChange ? 3 : 2; // deposit + OP_RETURN + optional change
 
   const vsize =
     TX_OVERHEAD_VBYTES +
     numInputs * inputVbytes +
     P2TR_OUTPUT_VBYTES + // deposit output
-    OP_RETURN_OUTPUT_VBYTES + // OP_RETURN output
+    (hasOpReturn ? OP_RETURN_OUTPUT_VBYTES : 0) +
     (hasChange ? P2TR_OUTPUT_VBYTES : 0); // change output
 
   return Math.ceil(vsize * feeRate);
@@ -138,11 +147,16 @@ export function buildDepositPsbt(params: BuildDepositPsbtParams): BuildDepositPs
   if (depositAmountSats < DUST_LIMIT) {
     throw new Error(`Deposit amount ${depositAmountSats} is below dust limit ${DUST_LIMIT}`);
   }
-  if (opReturnPayload.length !== DEPOSIT_OP_RETURN_SIZE) {
+  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);
@@ -152,11 +166,11 @@ export function buildDepositPsbt(params: BuildDepositPsbtParams): BuildDepositPs
   const inputType = firstScript[0] === 0x51 ? "p2tr" : "p2wpkh";
 
   // Estimate fee with change
-  const feeWithChange = estimateDepositFee(senderUtxos.length, feeRate, inputType, true);
+  const feeWithChange = estimateDepositFee(senderUtxos.length, feeRate, inputType, true, Boolean(opReturnPayload));
   const changeAmount = totalInput - depositAmountSats - feeWithChange;
 
   // Check if we have enough funds
-  const feeWithoutChange = estimateDepositFee(senderUtxos.length, feeRate, inputType, false);
+  const feeWithoutChange = estimateDepositFee(senderUtxos.length, feeRate, inputType, false, Boolean(opReturnPayload));
   if (totalInput < depositAmountSats + feeWithoutChange) {
     throw new Error(
       `Insufficient funds: have ${totalInput} sats, need ${depositAmountSats + feeWithoutChange} sats (including fee)`,
@@ -203,12 +217,15 @@ export function buildDepositPsbt(params: BuildDepositPsbtParams): BuildDepositPs
   // Output 1: P2TR deposit
   tx.addOutputAddress(depositAddress, BigInt(depositAmountSats), btcNetwork);
 
-  // Output 2: OP_RETURN with compact deposit payload.
-  const opReturnScript = createOpReturnScriptFromPayload(opReturnPayload);
-  tx.addOutput({
-    script: opReturnScript,
-    amount: 0n,
-  });
+  // Output 2: OP_RETURN with compact deposit payload — only for that flow. A
+  // tweak-bound deposit adds nothing here, so the transaction is indistinguishable
+  // from an ordinary payment.
+  if (opReturnPayload) {
+    tx.addOutput({
+      script: createOpReturnScriptFromPayload(opReturnPayload),
+      amount: 0n,
+    });
+  }
 
   // Output 3: Change (if above dust)
   if (hasChange) {

package/src/spend-doc.ts

@@ -18,6 +18,7 @@ import {
   createUnshieldBoundParams,
   type SolanaPrivacyDomainContext,
 } from "./bound-params";
+import { bytesToHex as hex } from "./crypto";
 
 export interface SpendDoc {
   mode: "transfer" | "unshield" | "redeem";
@@ -64,8 +65,6 @@ function fmt(raw: bigint, decimals: number): string {
   return `${neg ? "-" : ""}${whole}${frac ? `.${frac}` : ""}`;
 }
 
-const hex = (b: Uint8Array) => Array.from(b, (x) => x.toString(16).padStart(2, "0")).join("");
-
 function sortedValues(v: bigint[]): string {
   return [...v].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0)).join(",");
 }

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)
  */