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

package/src/solana/connection.ts

@@ -0,0 +1,189 @@
+/**
+ * Connection Adapter Factory
+ *
+ * Creates ConnectionAdapter instances for use with SDK functions.
+ * Supports both @solana/kit and @solana/web3.js connections.
+ */
+
+import type { ConnectionAdapter } from "../stealth";
+import { base64ToBinaryString } from "../utils/encoding";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export interface RpcConfig {
+  /** RPC endpoint URL */
+  endpoint: string;
+  /** Commitment level */
+  commitment?: "processed" | "confirmed" | "finalized";
+}
+
+/**
+ * Minimal interface for @solana/web3.js Connection-like objects
+ */
+export interface Web3Connection {
+  getAccountInfo(
+    publicKey: { toBase58(): string } | string,
+    commitment?: string
+  ): Promise<{ data: Buffer | Uint8Array } | null>;
+}
+
+/**
+ * Minimal interface for @solana/kit Rpc-like objects
+ */
+export interface KitRpc {
+  getAccountInfo(
+    address: string,
+    config?: { encoding: string }
+  ): { send(): Promise<{ value: { data: string | string[] } | null }> };
+}
+
+// =============================================================================
+// Connection Adapter Factory
+// =============================================================================
+
+/**
+ * Create a ConnectionAdapter using fetch (works everywhere)
+ *
+ * This is the most portable option - works in browser, Node.js, and React Native.
+ *
+ * @param endpoint - Solana RPC endpoint URL
+ * @returns ConnectionAdapter instance
+ */
+export function createFetchConnectionAdapter(endpoint: string): ConnectionAdapter {
+  return {
+    getAccountInfo: async (address: string) => {
+      const response = await fetch(endpoint, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          jsonrpc: "2.0",
+          id: 1,
+          method: "getAccountInfo",
+          params: [address, { encoding: "base64" }],
+        }),
+      });
+
+      const result = await response.json();
+
+      if (!result.result?.value) {
+        return null;
+      }
+
+      // Decode base64 data
+      const base64Data = Array.isArray(result.result.value.data)
+        ? result.result.value.data[0]
+        : result.result.value.data;
+
+      if (!base64Data) {
+        return { data: new Uint8Array() };
+      }
+
+      // Decode base64 (works in browser and Node.js)
+      const binaryString = base64ToBinaryString(base64Data);
+
+      const bytes = new Uint8Array(binaryString.length);
+      for (let i = 0; i < binaryString.length; i++) {
+        bytes[i] = binaryString.charCodeAt(i);
+      }
+
+      return { data: bytes };
+    },
+  };
+}
+
+/**
+ * Create a ConnectionAdapter from @solana/web3.js Connection
+ *
+ * Use this when you already have a Connection instance from wallet adapter.
+ *
+ * @param connection - @solana/web3.js Connection instance
+ * @returns ConnectionAdapter instance
+ */
+export function createConnectionAdapterFromWeb3(
+  connection: Web3Connection
+): ConnectionAdapter {
+  return {
+    getAccountInfo: async (address: string) => {
+      // Handle both string and PublicKey-like objects
+      const info = await connection.getAccountInfo(address);
+      if (!info) return null;
+      return { data: new Uint8Array(info.data) };
+    },
+  };
+}
+
+/**
+ * Create a ConnectionAdapter from @solana/kit Rpc
+ *
+ * Use this when using the modern @solana/kit library.
+ *
+ * @param rpc - @solana/kit Rpc instance
+ * @returns ConnectionAdapter instance
+ */
+export function createConnectionAdapterFromKit(rpc: KitRpc): ConnectionAdapter {
+  return {
+    getAccountInfo: async (address: string) => {
+      const result = await rpc
+        .getAccountInfo(address, { encoding: "base64" })
+        .send();
+
+      if (!result.value) {
+        return null;
+      }
+
+      // Decode base64 data
+      const base64Data = typeof result.value.data === "string"
+        ? result.value.data
+        : result.value.data[0];
+
+      if (!base64Data) {
+        return { data: new Uint8Array() };
+      }
+
+      // Decode base64
+      const binaryString = base64ToBinaryString(base64Data);
+
+      const bytes = new Uint8Array(binaryString.length);
+      for (let i = 0; i < binaryString.length; i++) {
+        bytes[i] = binaryString.charCodeAt(i);
+      }
+
+      return { data: bytes };
+    },
+  };
+}
+
+// =============================================================================
+// Cached Connection Adapter
+// =============================================================================
+
+let cachedAdapter: ConnectionAdapter | null = null;
+let cachedEndpoint: string | null = null;
+
+/**
+ * Get or create a cached ConnectionAdapter
+ *
+ * Caches the adapter for the given endpoint to avoid creating multiple instances.
+ *
+ * @param endpoint - Solana RPC endpoint URL
+ * @returns ConnectionAdapter instance
+ */
+export function getConnectionAdapter(endpoint: string): ConnectionAdapter {
+  if (cachedAdapter && cachedEndpoint === endpoint) {
+    return cachedAdapter;
+  }
+
+  cachedAdapter = createFetchConnectionAdapter(endpoint);
+  cachedEndpoint = endpoint;
+  return cachedAdapter;
+}
+
+/**
+ * Clear the cached ConnectionAdapter
+ */
+export function clearConnectionAdapterCache(): void {
+  cachedAdapter = null;
+  cachedEndpoint = null;
+}

package/src/solana/priority-fee.ts

@@ -0,0 +1,201 @@
+/**
+ * Priority Fee Estimation
+ *
+ * Utilities for estimating Solana transaction priority fees.
+ * Supports Helius API for accurate fee estimation.
+ */
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export interface PriorityFeeConfig {
+  /** Helius API key (optional, falls back to default fees without it) */
+  heliusApiKey?: string;
+  /** RPC endpoint (defaults to Helius if API key provided) */
+  rpcEndpoint?: string;
+  /** Default compute unit limit */
+  defaultComputeUnits?: number;
+  /** Default priority fee in microLamports (fallback) */
+  defaultPriorityFee?: number;
+}
+
+export interface PriorityFeeEstimate {
+  /** Recommended priority fee in microLamports */
+  priorityFee: number;
+  /** Compute unit limit to set */
+  computeUnits: number;
+}
+
+export interface PriorityFeeInstructions {
+  /** SetComputeUnitLimit instruction data */
+  setComputeUnitLimit: {
+    discriminator: number;
+    units: number;
+  };
+  /** SetComputeUnitPrice instruction data (null if no priority fee) */
+  setComputeUnitPrice: {
+    discriminator: number;
+    microLamports: bigint;
+  } | null;
+}
+
+// =============================================================================
+// Constants
+// =============================================================================
+
+/** Default compute unit limit for UTXOpia transactions */
+export const DEFAULT_COMPUTE_UNITS = 200_000;
+
+/** Default priority fee in microLamports when estimation fails */
+export const DEFAULT_PRIORITY_FEE = 1000;
+
+/** ComputeBudgetProgram discriminators */
+export const COMPUTE_BUDGET_DISCRIMINATORS = {
+  SET_COMPUTE_UNIT_LIMIT: 2,
+  SET_COMPUTE_UNIT_PRICE: 3,
+} as const;
+
+// =============================================================================
+// Priority Fee Estimation
+// =============================================================================
+
+/**
+ * Estimate priority fee using Helius API
+ *
+ * @param accountKeys - Array of account public key strings involved in the transaction
+ * @param config - Configuration options
+ * @returns Priority fee estimate
+ */
+export async function estimatePriorityFee(
+  accountKeys: string[],
+  config: PriorityFeeConfig = {}
+): Promise<PriorityFeeEstimate> {
+  const {
+    heliusApiKey,
+    rpcEndpoint,
+    defaultComputeUnits = DEFAULT_COMPUTE_UNITS,
+    defaultPriorityFee = DEFAULT_PRIORITY_FEE,
+  } = config;
+
+  // Determine endpoint
+  const endpoint = rpcEndpoint || (heliusApiKey
+    ? `https://mainnet.helius-rpc.com/?api-key=${heliusApiKey}`
+    : null);
+
+  if (!endpoint) {
+    // No API available, return defaults
+    return {
+      priorityFee: defaultPriorityFee,
+      computeUnits: defaultComputeUnits,
+    };
+  }
+
+  try {
+    const response = await fetch(endpoint, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        jsonrpc: "2.0",
+        id: "priority-fee",
+        method: "getPriorityFeeEstimate",
+        params: [{
+          accountKeys,
+          options: { recommended: true },
+        }],
+      }),
+    });
+
+    const data = await response.json();
+    const priorityFee = data?.result?.priorityFeeEstimate || defaultPriorityFee;
+
+    return {
+      priorityFee: Math.round(priorityFee),
+      computeUnits: defaultComputeUnits,
+    };
+  } catch (error) {
+    console.warn("Failed to get priority fee estimate:", error);
+    return {
+      priorityFee: defaultPriorityFee,
+      computeUnits: defaultComputeUnits,
+    };
+  }
+}
+
+/**
+ * Build priority fee instruction data
+ *
+ * Returns raw instruction data for ComputeBudgetProgram instructions.
+ * Use this when building transactions manually.
+ *
+ * @param accountKeys - Array of account public key strings
+ * @param config - Configuration options
+ * @returns Instruction data for compute budget instructions
+ */
+export async function buildPriorityFeeInstructionData(
+  accountKeys: string[],
+  config: PriorityFeeConfig = {}
+): Promise<PriorityFeeInstructions> {
+  const estimate = await estimatePriorityFee(accountKeys, config);
+
+  return {
+    setComputeUnitLimit: {
+      discriminator: COMPUTE_BUDGET_DISCRIMINATORS.SET_COMPUTE_UNIT_LIMIT,
+      units: estimate.computeUnits,
+    },
+    setComputeUnitPrice: estimate.priorityFee > 0
+      ? {
+          discriminator: COMPUTE_BUDGET_DISCRIMINATORS.SET_COMPUTE_UNIT_PRICE,
+          microLamports: BigInt(estimate.priorityFee),
+        }
+      : null,
+  };
+}
+
+/**
+ * Encode SetComputeUnitLimit instruction
+ */
+export function encodeSetComputeUnitLimit(units: number): Uint8Array {
+  const data = new Uint8Array(5);
+  data[0] = COMPUTE_BUDGET_DISCRIMINATORS.SET_COMPUTE_UNIT_LIMIT;
+  // Little-endian u32
+  data[1] = units & 0xff;
+  data[2] = (units >> 8) & 0xff;
+  data[3] = (units >> 16) & 0xff;
+  data[4] = (units >> 24) & 0xff;
+  return data;
+}
+
+/**
+ * Encode SetComputeUnitPrice instruction
+ */
+export function encodeSetComputeUnitPrice(microLamports: bigint): Uint8Array {
+  const data = new Uint8Array(9);
+  data[0] = COMPUTE_BUDGET_DISCRIMINATORS.SET_COMPUTE_UNIT_PRICE;
+  // Little-endian u64
+  for (let i = 0; i < 8; i++) {
+    data[1 + i] = Number((microLamports >> BigInt(i * 8)) & 0xffn);
+  }
+  return data;
+}
+
+/**
+ * Get RPC URL with Helius API key
+ *
+ * @param network - "devnet" or "mainnet"
+ * @param heliusApiKey - Optional Helius API key
+ * @returns RPC URL
+ */
+export function getHeliusRpcUrl(
+  network: "devnet" | "mainnet",
+  heliusApiKey?: string
+): string {
+  if (heliusApiKey) {
+    return network === "mainnet"
+      ? `https://mainnet.helius-rpc.com/?api-key=${heliusApiKey}`
+      : `https://devnet.helius-rpc.com/?api-key=${heliusApiKey}`;
+  }
+  return network === "mainnet"
+    ? "https://api.mainnet-beta.solana.com"
+    : "https://api.devnet.solana.com";
+}

package/src/spend-doc.ts

@@ -0,0 +1,163 @@
+/**
+ * "What am I proving?" — a canonical sentence for a shielded spend.
+ *
+ * The text is not the point. The point is that `renderSpendDoc` recomputes the
+ * proof's public signals from the numbers it is about to print and throws if
+ * they disagree, so a UI cannot caption a proof with an amount or a destination
+ * the proof does not actually contain.
+ *
+ * Nothing here changes the circuit. Every value below is already bound to the
+ * user's spending key by the in-circuit EdDSA over
+ * Poseidon(merkleRoot, boundParamsHash, nullifiers.., commitmentsOut..).
+ */
+
+import {
+  computeSolanaDomainBoundParamsHash,
+  createRedeemBoundParams,
+  createTransferBoundParams,
+  createUnshieldBoundParams,
+  type SolanaPrivacyDomainContext,
+} from "./bound-params";
+
+export interface SpendDoc {
+  mode: "transfer" | "unshield" | "redeem";
+  /** Display label, e.g. "Solana Devnet". */
+  network: string;
+  /** Display label, e.g. "zkBTC". */
+  asset: string;
+  decimals: number;
+  /** Destination as shown to the user (a .sol name, a BTC address, a pubkey). */
+  recipient: string;
+  /**
+   * The destination bytes actually folded into boundParamsHash: 32-byte Solana
+   * owner for `unshield`, raw scriptPubKey for `redeem`. Omitted for `transfer`,
+   * where the destination is private and provably absent from the signals.
+   */
+  recipientBytes?: Uint8Array;
+  /** Raw units the recipient receives. */
+  amount: bigint;
+  relayerFee: bigint;
+  change: bigint;
+}
+
+/** The public signals of the proof about to be generated, plus what built them. */
+export interface SpendSignals {
+  /** `outputs.map(o => o.value)` from JoinSplitProofInputs. */
+  outputValues: bigint[];
+  /** The boundParamsHash going into the proof. */
+  boundParamsHash: bigint;
+  stealthDataHash: Uint8Array;
+  chainId: bigint;
+  domain: SolanaPrivacyDomainContext;
+  /** Redeem only: the on-chain requester bound into the proof. */
+  requester?: Uint8Array;
+  treeNumber?: number;
+}
+
+export class SpendDocMismatch extends Error {}
+
+function fmt(raw: bigint, decimals: number): string {
+  const neg = raw < 0n;
+  const s = (neg ? -raw : raw).toString().padStart(decimals + 1, "0");
+  const whole = s.slice(0, s.length - decimals);
+  const frac = decimals === 0 ? "" : s.slice(s.length - decimals).replace(/0+$/, "");
+  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(",");
+}
+
+function expectedBoundParamsHash(doc: SpendDoc, s: SpendSignals): bigint {
+  const tree = s.treeNumber ?? 0;
+  switch (doc.mode) {
+    case "transfer":
+      return computeSolanaDomainBoundParamsHash(
+        createTransferBoundParams(s.stealthDataHash, s.chainId, tree),
+        s.domain,
+      );
+    case "unshield":
+      if (!doc.recipientBytes) throw new SpendDocMismatch("unshield doc has no recipientBytes");
+      return computeSolanaDomainBoundParamsHash(
+        createUnshieldBoundParams(doc.recipientBytes, s.stealthDataHash, s.chainId, tree),
+        s.domain,
+      );
+    case "redeem":
+      if (!doc.recipientBytes) throw new SpendDocMismatch("redeem doc has no recipientBytes");
+      if (!s.requester) throw new SpendDocMismatch("redeem doc has no requester");
+      return computeSolanaDomainBoundParamsHash(
+        createRedeemBoundParams(doc.recipientBytes, s.stealthDataHash, s.requester, s.chainId, tree),
+        s.domain,
+      );
+  }
+}
+
+/**
+ * The statement itself. Show this before the user commits; pass the same `doc`
+ * to `renderSpendDoc` when the proof is built so the string they read is the
+ * string that gets checked.
+ */
+export function formatSpendDoc(doc: SpendDoc): string {
+  const amt = (v: bigint) => `${fmt(v, doc.decimals)} ${doc.asset}`;
+  const action =
+    doc.mode === "redeem"
+      ? `Withdraw ${amt(doc.amount)} to Bitcoin`
+      : doc.mode === "unshield"
+        ? `Unshield ${amt(doc.amount)}`
+        : `Send ${amt(doc.amount)} privately`;
+
+  const lines = [
+    "UTXOpia Proof",
+    "",
+    "I AM PROVING",
+    action,
+    "",
+    "DETAILS",
+    `Network: ${doc.network}`,
+    `Amount leaving the pool: ${amt(doc.amount)}`,
+    `To: ${doc.recipient}`,
+  ];
+  if (doc.recipientBytes) lines.push(`Bound destination: ${hex(doc.recipientBytes)}`);
+  if (doc.relayerFee > 0n) lines.push(`Relayer fee: ${amt(doc.relayerFee)}`);
+  if (doc.change > 0n) lines.push(`Change back to me: ${amt(doc.change)}`);
+  lines.push(
+    "",
+    "ENFORCED BY THE PROOF",
+    "Amounts: these are every output this proof creates",
+    doc.mode === "transfer"
+      ? "Destination: private — not in the public signals. Confirm it with the recipient."
+      : "Destination: bound into boundParamsHash and re-derived onchain",
+  );
+  if (doc.mode !== "transfer") {
+    lines.push(
+      "Protocol fee: deducted onchain from pool policy, not part of this statement",
+    );
+  }
+  lines.push("", "Protocol: utxopia-spend-doc-v1");
+  return lines.join("\n");
+}
+
+/**
+ * Render the statement, or throw if it does not describe `signals`.
+ *
+ * Checked: every amount on screen is an output value of the proof and there are
+ * no other outputs; the destination reproduces boundParamsHash.
+ * Not checked: that `recipient` (a label) names `recipientBytes` — the doc
+ * prints the bound bytes so that stays verifiable by eye.
+ */
+export function renderSpendDoc(doc: SpendDoc, signals: SpendSignals): string {
+  const shown = [doc.amount, doc.relayerFee, doc.change].filter((v) => v > 0n);
+  if (sortedValues(shown) !== sortedValues(signals.outputValues)) {
+    throw new SpendDocMismatch(
+      `amounts do not match the proof outputs: doc [${sortedValues(shown)}] vs proof [${sortedValues(signals.outputValues)}]`,
+    );
+  }
+  const expected = expectedBoundParamsHash(doc, signals);
+  if (expected !== signals.boundParamsHash) {
+    throw new SpendDocMismatch("destination does not match the proof's boundParamsHash");
+  }
+
+  return formatSpendDoc(doc);
+}