nara-sdk 1.0.39 → 1.0.41

package/README.md

@@ -35,12 +35,12 @@ Circuit files: `withdraw.wasm` + `withdraw_final.zkey`, `ownership.wasm` + `owne
 On-chain registry for AI agents with identity, memory, and activity tracking:
 
 - Register a unique agent ID (lowercase only, no uppercase letters allowed)
-- Optional **referral** on registration or via `setReferral` post-registration
+- **Referral system**: register with referral via `registerAgentWithReferral`, or set referral post-registration via `setReferral`
 - Store agent **bio** and **metadata** (JSON) on-chain
 - Upload persistent **memory** via chunked buffer mechanism — auto-chunked ~800-byte writes with resumable uploads
-- **Activity logging** with on-chain events — supports referral for earning referral points (Token-2022 point mint)
+- **Activity logging**: `logActivity` for standard logging, `logActivityWithReferral` for referral-based logging
 - Memory modes: `new`, `update`, `append`, `auto` (auto-detects)
-- Points are minted as **Token-2022 SPL tokens** via a point mint, not stored on the agent record
+- Points are minted as **Token-2022 SPL tokens** — separate mints for registration points (`pointMint`), referee rewards (`refereeMint`), and activity rewards (`refereeActivityMint`)
 
 ## Skills Hub
 
@@ -187,6 +187,7 @@ console.log(isValidRecipient(recipient.publicKey)); // true
 ```typescript
 import {
   registerAgent,
+  registerAgentWithReferral,
   getAgentRecord,
   getAgentInfo,
   getAgentMemory,
@@ -195,6 +196,7 @@ import {
   setMetadata,
   uploadMemory,
   logActivity,
+  logActivityWithReferral,
   setReferral,
   deleteAgent,
   Keypair,
@@ -204,10 +206,12 @@ import { Connection } from "@solana/web3.js";
 const connection = new Connection("https://mainnet-api.nara.build/", "confirmed");
 const wallet = Keypair.fromSecretKey(/* your secret key */);
 
-// 1. Register an agent (lowercase only, charges registration fee)
-//    Optional: pass referralAgentId to set referral on registration
-const { signature, agentPubkey } = await registerAgent(
-  connection, wallet, "my-agent", undefined, "referral-agent-id"
+// 1a. Register an agent (lowercase only, charges registration fee)
+const { signature, agentPubkey } = await registerAgent(connection, wallet, "my-agent");
+
+// 1b. Or register with referral
+const result = await registerAgentWithReferral(
+  connection, wallet, "my-agent", "referral-agent-id"
 );
 
 // 2. Or set referral after registration
@@ -230,9 +234,11 @@ const bytes = await getAgentMemory(connection, "my-agent");
 const extra = Buffer.from(JSON.stringify({ more: "data" }));
 await uploadMemory(connection, wallet, "my-agent", extra, {}, "append");
 
-// 7. Log activity (with optional referral agent)
+// 7a. Log activity
 await logActivity(connection, wallet, "my-agent", "gpt-4", "chat", "Answered a question");
-await logActivity(connection, wallet, "my-agent", "gpt-4", "chat", "With referral", undefined, "referral-agent-id");
+
+// 7b. Log activity with referral
+await logActivityWithReferral(connection, wallet, "my-agent", "gpt-4", "chat", "With referral", "referral-agent-id");
 
 // 8. Query agent info
 const info = await getAgentInfo(connection, "my-agent");
@@ -240,7 +246,7 @@ console.log(info.record.agentId, info.record.referralId, info.bio);
 
 // 9. Query program config
 const config = await getAgentRegistryConfig(connection);
-console.log(config.pointMint.toBase58(), config.pointsSelf, config.referralRegisterFee);
+console.log(config.pointMint.toBase58(), config.refereeMint.toBase58(), config.pointsSelf, config.activityReward);
 ```
 
 ### Skills SDK

package/index.ts

@@ -66,6 +66,7 @@ export {
   withdraw,
   transferZkId,
   transferZkIdByCommitment,
+  makeWithdrawIx,
   deriveIdSecret,
   computeIdCommitment,
   isValidRecipient,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nara-sdk",
-  "version": "1.0.39",
+  "version": "1.0.41",
   "description": "SDK for the Nara chain (Solana-compatible)",
   "module": "index.ts",
   "main": "index.ts",

package/src/quest.ts

@@ -21,22 +21,18 @@ import naraQuestIdl from "./idls/nara_quest.json";
 const BN254_FIELD =
   21888242871839275222246405745257275088696311157297823662689037894645226208583n;
 
-import { fileURLToPath } from "url";
-import { dirname, join, resolve } from "path";
-import { existsSync } from "fs";
-const __dirname: string = import.meta.url
-  ? dirname(fileURLToPath(import.meta.url))
-  : eval("__dirname") as string;
-
-function findZkFile(name: string): string {
-  const srcPath = join(__dirname, "zk", name);
-  if (existsSync(srcPath)) return srcPath;
-  return srcPath;
+// Lazily resolve default ZK circuit file paths (Node.js only).
+// In browser environments, pass circuitWasmPath/zkeyPath via QuestOptions.
+async function resolveDefaultZkPaths(): Promise<{ wasm: string; zkey: string }> {
+  const { fileURLToPath } = await import("url");
+  const { dirname, join } = await import("path");
+  const dir = dirname(fileURLToPath(import.meta.url));
+  return {
+    wasm: join(dir, "zk", "answer_proof.wasm"),
+    zkey: join(dir, "zk", "answer_proof_final.zkey"),
+  };
 }
 
-const DEFAULT_CIRCUIT_WASM = findZkFile("answer_proof.wasm");
-const DEFAULT_ZKEY = findZkFile("answer_proof_final.zkey");
-
 // ─── Types ───────────────────────────────────────────────────────
 
 export interface QuestInfo {
@@ -77,8 +73,10 @@ export interface SubmitRelayResult {
 
 export interface QuestOptions {
   programId?: string;
-  circuitWasmPath?: string;
-  zkeyPath?: string;
+  /** File path (Node.js), URL string, or pre-loaded Uint8Array (browser) */
+  circuitWasmPath?: string | Uint8Array;
+  /** File path (Node.js), URL string, or pre-loaded Uint8Array (browser) */
+  zkeyPath?: string | Uint8Array;
 }
 
 export interface ActivityLog {
@@ -90,71 +88,79 @@ export interface ActivityLog {
   referralAgentId?: string;
 }
 
-// ─── ZK utilities ────────────────────────────────────────────────
+// ─── ZK utilities (browser-compatible, no Buffer) ───────────────
+
+function hexFromBytes(bytes: Uint8Array): string {
+  return Array.from(bytes).map(b => b.toString(16).padStart(2, "0")).join("");
+}
+
+function concatBytes(...arrays: Uint8Array[]): Uint8Array {
+  const total = arrays.reduce((sum, a) => sum + a.length, 0);
+  const result = new Uint8Array(total);
+  let offset = 0;
+  for (const a of arrays) { result.set(a, offset); offset += a.length; }
+  return result;
+}
 
-function toBigEndian32(v: bigint): Buffer {
-  return Buffer.from(v.toString(16).padStart(64, "0"), "hex");
+function bigintToBytes32(v: bigint): Uint8Array {
+  const hex = v.toString(16).padStart(64, "0");
+  const bytes = new Uint8Array(32);
+  for (let i = 0; i < 32; i++) bytes[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+  return bytes;
 }
 
 function answerToField(answer: string): bigint {
-  return (
-    BigInt("0x" + Buffer.from(answer, "utf-8").toString("hex")) % BN254_FIELD
-  );
+  const encoded = new TextEncoder().encode(answer);
+  return BigInt("0x" + hexFromBytes(encoded)) % BN254_FIELD;
 }
 
 function hashBytesToFieldStr(hashBytes: number[]): string {
-  return BigInt("0x" + Buffer.from(hashBytes).toString("hex")).toString();
+  return BigInt("0x" + hexFromBytes(new Uint8Array(hashBytes))).toString();
 }
 
 function pubkeyToCircuitInputs(pubkey: PublicKey): {
   lo: string;
   hi: string;
 } {
-  const bytes = pubkey.toBuffer();
+  const bytes = pubkey.toBytes();
   return {
-    lo: BigInt("0x" + bytes.subarray(16, 32).toString("hex")).toString(),
-    hi: BigInt("0x" + bytes.subarray(0, 16).toString("hex")).toString(),
+    lo: BigInt("0x" + hexFromBytes(bytes.slice(16, 32))).toString(),
+    hi: BigInt("0x" + hexFromBytes(bytes.slice(0, 16))).toString(),
   };
 }
 
 function proofToSolana(proof: any): ZkProof {
-  const negY = (y: string) => toBigEndian32(BN254_FIELD - BigInt(y));
-  const be = (s: string) => toBigEndian32(BigInt(s));
+  const negY = (y: string) => bigintToBytes32(BN254_FIELD - BigInt(y));
+  const be = (s: string) => bigintToBytes32(BigInt(s));
   return {
-    proofA: Array.from(
-      Buffer.concat([be(proof.pi_a[0]), negY(proof.pi_a[1])])
-    ),
-    proofB: Array.from(
-      Buffer.concat([
-        be(proof.pi_b[0][1]),
-        be(proof.pi_b[0][0]),
-        be(proof.pi_b[1][1]),
-        be(proof.pi_b[1][0]),
-      ])
-    ),
-    proofC: Array.from(
-      Buffer.concat([be(proof.pi_c[0]), be(proof.pi_c[1])])
-    ),
+    proofA: Array.from(concatBytes(be(proof.pi_a[0]), negY(proof.pi_a[1]))),
+    proofB: Array.from(concatBytes(
+      be(proof.pi_b[0][1]),
+      be(proof.pi_b[0][0]),
+      be(proof.pi_b[1][1]),
+      be(proof.pi_b[1][0]),
+    )),
+    proofC: Array.from(concatBytes(be(proof.pi_c[0]), be(proof.pi_c[1]))),
   };
 }
 
 function proofToHex(proof: any): ZkProofHex {
-  const negY = (y: string) => toBigEndian32(BN254_FIELD - BigInt(y));
-  const be = (s: string) => toBigEndian32(BigInt(s));
+  const negY = (y: string) => bigintToBytes32(BN254_FIELD - BigInt(y));
+  const be = (s: string) => bigintToBytes32(BigInt(s));
   return {
-    proofA: Buffer.concat([be(proof.pi_a[0]), negY(proof.pi_a[1])]).toString("hex"),
-    proofB: Buffer.concat([
+    proofA: hexFromBytes(concatBytes(be(proof.pi_a[0]), negY(proof.pi_a[1]))),
+    proofB: hexFromBytes(concatBytes(
       be(proof.pi_b[0][1]),
       be(proof.pi_b[0][0]),
       be(proof.pi_b[1][1]),
       be(proof.pi_b[1][0]),
-    ]).toString("hex"),
-    proofC: Buffer.concat([be(proof.pi_c[0]), be(proof.pi_c[1])]).toString("hex"),
+    )),
+    proofC: hexFromBytes(concatBytes(be(proof.pi_c[0]), be(proof.pi_c[1]))),
   };
 }
 
 // Suppress console output from snarkjs WASM during proof generation.
-async function silentProve(snarkjs: any, input: Record<string, string>, wasmPath: string, zkeyPath: string) {
+async function silentProve(snarkjs: any, input: Record<string, string>, wasmPath: string | Uint8Array, zkeyPath: string | Uint8Array) {
   const savedLog = console.log;
   const savedError = console.error;
   console.log = () => {};
@@ -188,7 +194,7 @@ function createProgram(
 
 function getPoolPda(programId: PublicKey): PublicKey {
   const [pda] = PublicKey.findProgramAddressSync(
-    [Buffer.from("quest_pool")],
+    [new TextEncoder().encode("quest_pool")],
     programId
   );
   return pda;
@@ -199,7 +205,7 @@ function getWinnerRecordPda(
   user: PublicKey
 ): PublicKey {
   const [pda] = PublicKey.findProgramAddressSync(
-    [Buffer.from("quest_winner"), user.toBuffer()],
+    [new TextEncoder().encode("quest_winner"), user.toBytes()],
     programId
   );
   return pda;
@@ -279,8 +285,13 @@ export async function generateProof(
   round: string,
   options?: QuestOptions
 ): Promise<{ solana: ZkProof; hex: ZkProofHex }> {
-  const wasmPath = options?.circuitWasmPath ?? process.env.QUEST_CIRCUIT_WASM ?? DEFAULT_CIRCUIT_WASM;
-  const zkeyPath = options?.zkeyPath ?? process.env.QUEST_ZKEY ?? DEFAULT_ZKEY;
+  let wasmSource = options?.circuitWasmPath;
+  let zkeySource = options?.zkeyPath;
+  if (!wasmSource || !zkeySource) {
+    const defaults = await resolveDefaultZkPaths();
+    wasmSource ??= defaults.wasm;
+    zkeySource ??= defaults.zkey;
+  }
 
   const snarkjs = await import("snarkjs");
   const answerHashFieldStr = hashBytesToFieldStr(answerHash);
@@ -295,8 +306,8 @@ export async function generateProof(
       pubkey_hi: hi,
       round: round,
     },
-    wasmPath,
-    zkeyPath
+    wasmSource,
+    zkeySource
   );
 
   return {
@@ -455,7 +466,7 @@ export async function computeAnswerHash(answer: string): Promise<number[]> {
   const fieldVal = answerToField(answer);
   const hashRaw = poseidon([fieldVal]);
   const hashStr: string = poseidon.F.toString(hashRaw);
-  return Array.from(toBigEndian32(BigInt(hashStr)));
+  return Array.from(bigintToBytes32(BigInt(hashStr)));
 }
 
 /**

package/src/zkid.ts

@@ -7,10 +7,7 @@
  * - Ownership can be transferred via ZK proof without revealing the owner's wallet
  */
 
-import { createHash } from "crypto";
-import { fileURLToPath } from "url";
-import { dirname, join } from "path";
-import { Connection, Keypair, PublicKey } from "@solana/web3.js";
+import { Connection, Keypair, PublicKey, TransactionInstruction } from "@solana/web3.js";
 import * as anchor from "@coral-xyz/anchor";
 import { Program, AnchorProvider, Wallet } from "@coral-xyz/anchor";
 import { buildPoseidon as _buildPoseidon } from "circomlibjs";
@@ -19,16 +16,6 @@ import BN from "bn.js";
 import type { NaraZk } from "./idls/nara_zk";
 import { DEFAULT_ZKID_PROGRAM_ID } from "./constants";
 import naraZkIdl from "./idls/nara_zk.json";
-import { createRequire } from "module";
-
-// _require is used only for snarkjs (external, loaded at runtime).
-// Supports both ESM (tsx dev) and esbuild CJS bundle (import.meta.url is "" — falsy)
-const _require: NodeRequire = import.meta.url
-  ? createRequire(import.meta.url)
-  : eval("require") as NodeRequire;
-const __dirname: string = import.meta.url
-  ? dirname(fileURLToPath(import.meta.url))
-  : eval("__dirname") as string;
 
 // ─── Constants ────────────────────────────────────────────────────────────────
 
@@ -36,10 +23,22 @@ const BN254_PRIME =
   21888242871839275222246405745257275088696311157297823662689037894645226208583n;
 const MERKLE_LEVELS = 64;
 
-const WITHDRAW_WASM = join(__dirname, "zk", "withdraw.wasm");
-const WITHDRAW_ZKEY = join(__dirname, "zk", "withdraw_final.zkey");
-const OWNERSHIP_WASM = join(__dirname, "zk", "ownership.wasm");
-const OWNERSHIP_ZKEY = join(__dirname, "zk", "ownership_final.zkey");
+// Lazily resolve default ZK circuit file paths (Node.js only).
+// In browser environments, pass withdrawWasm/withdrawZkey/ownershipWasm/ownershipZkey via ZkIdOptions.
+async function resolveDefaultZkPaths(): Promise<{
+  withdrawWasm: string; withdrawZkey: string;
+  ownershipWasm: string; ownershipZkey: string;
+}> {
+  const { fileURLToPath } = await import("url");
+  const { dirname, join } = await import("path");
+  const dir = dirname(fileURLToPath(import.meta.url));
+  return {
+    withdrawWasm: join(dir, "zk", "withdraw.wasm"),
+    withdrawZkey: join(dir, "zk", "withdraw_final.zkey"),
+    ownershipWasm: join(dir, "zk", "ownership.wasm"),
+    ownershipZkey: join(dir, "zk", "ownership_final.zkey"),
+  };
+}
 
 // ─── Public types ─────────────────────────────────────────────────────────────
 
@@ -69,9 +68,36 @@ export interface ClaimableDeposit {
 
 export interface ZkIdOptions {
   programId?: string;
+  /** File path (Node.js), URL string, or pre-loaded Uint8Array (browser) */
+  withdrawWasm?: string | Uint8Array;
+  /** File path (Node.js), URL string, or pre-loaded Uint8Array (browser) */
+  withdrawZkey?: string | Uint8Array;
+  /** File path (Node.js), URL string, or pre-loaded Uint8Array (browser) */
+  ownershipWasm?: string | Uint8Array;
+  /** File path (Node.js), URL string, or pre-loaded Uint8Array (browser) */
+  ownershipZkey?: string | Uint8Array;
 }
 
-// ─── Internal crypto helpers ─────────────────────────────────────────────────
+// ─── Internal crypto helpers (browser-compatible, no Buffer) ────────────────
+
+function hexFromBytes(bytes: Uint8Array): string {
+  return Array.from(bytes).map(b => b.toString(16).padStart(2, "0")).join("");
+}
+
+function concatBytes(...arrays: Uint8Array[]): Uint8Array {
+  const total = arrays.reduce((sum, a) => sum + a.length, 0);
+  const result = new Uint8Array(total);
+  let offset = 0;
+  for (const a of arrays) { result.set(a, offset); offset += a.length; }
+  return result;
+}
+
+function bigintToBytes32(v: bigint): Uint8Array {
+  const hex = v.toString(16).padStart(64, "0");
+  const bytes = new Uint8Array(32);
+  for (let i = 0; i < 32; i++) bytes[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+  return bytes;
+}
 
 let _poseidon: any = null;
 
@@ -86,58 +112,60 @@ async function poseidonHash(inputs: bigint[]): Promise<bigint> {
   return poseidon.F.toObject(result);
 }
 
-function bigIntToBytes32BE(n: bigint): Buffer {
+function bigIntToBytes32BE(n: bigint): Uint8Array {
   if (n < 0n || n >= BN254_PRIME) {
     throw new Error(`bigint out of BN254 field range: ${n}`);
   }
-  return Buffer.from(n.toString(16).padStart(64, "0"), "hex");
+  return bigintToBytes32(n);
 }
 
-function bytes32ToBigInt(buf: Buffer | Uint8Array): bigint {
-  return BigInt("0x" + Buffer.from(buf).toString("hex"));
+function bytes32ToBigInt(buf: Uint8Array): bigint {
+  return BigInt("0x" + hexFromBytes(buf));
 }
 
-function toBytes32(buf: Buffer | Uint8Array): number[] {
+function toBytes32(buf: Uint8Array): number[] {
   return Array.from(buf.slice(0, 32));
 }
 
-function computeNameHash(name: string): Buffer {
-  return createHash("sha256").update("nara-zk:" + name).digest();
+async function computeNameHash(name: string): Promise<Uint8Array> {
+  const data = new TextEncoder().encode("nara-zk:" + name);
+  const digest = await crypto.subtle.digest("SHA-256", data);
+  return new Uint8Array(digest);
 }
 
-function denomBuf(denomination: BN): Buffer {
-  return Buffer.from(denomination.toArray("le", 8));
+function denomBuf(denomination: BN): Uint8Array {
+  const bytes = new Uint8Array(8);
+  const arr = denomination.toArray("le", 8);
+  bytes.set(arr);
+  return bytes;
 }
 
 function packProof(proof: {
   pi_a: string[];
   pi_b: string[][];
   pi_c: string[];
-}): Buffer {
+}): Uint8Array {
   const ax = BigInt(proof.pi_a[0]!);
   const ay = BigInt(proof.pi_a[1]!);
   const ay_neg = BN254_PRIME - ay; // negate y: standard G1 negation on BN254
 
-  const proofA = Buffer.concat([
-    bigIntToBytes32BE(ax),
-    bigIntToBytes32BE(ay_neg),
-  ]);
-  const proofB = Buffer.concat([
+  const proofA = concatBytes(bigIntToBytes32BE(ax), bigIntToBytes32BE(ay_neg));
+  const proofB = concatBytes(
     bigIntToBytes32BE(BigInt(proof.pi_b[0]![1]!)), // x.c1
     bigIntToBytes32BE(BigInt(proof.pi_b[0]![0]!)), // x.c0
     bigIntToBytes32BE(BigInt(proof.pi_b[1]![1]!)), // y.c1
     bigIntToBytes32BE(BigInt(proof.pi_b[1]![0]!)), // y.c0
-  ]);
-  const proofC = Buffer.concat([
+  );
+  const proofC = concatBytes(
     bigIntToBytes32BE(BigInt(proof.pi_c[0]!)),
     bigIntToBytes32BE(BigInt(proof.pi_c[1]!)),
-  ]);
-  return Buffer.concat([proofA, proofB, proofC]); // 256 bytes total
+  );
+  return concatBytes(proofA, proofB, proofC); // 256 bytes total
 }
 
 async function buildMerklePath(
   leafIndex: bigint,
-  filledSubtrees: Buffer[],
+  filledSubtrees: Uint8Array[],
   zeros: bigint[]
 ): Promise<{ pathElements: bigint[]; pathIndices: number[] }> {
   const pathElements: bigint[] = new Array(MERKLE_LEVELS);
@@ -156,10 +184,10 @@ async function buildMerklePath(
 // Suppress snarkjs WASM console noise during proof generation.
 async function silentProve(
   input: Record<string, string | string[]>,
-  wasmPath: string,
-  zkeyPath: string
+  wasmPath: string | Uint8Array,
+  zkeyPath: string | Uint8Array
 ) {
-  const snarkjs = _require("snarkjs");
+  const snarkjs: any = await import("snarkjs");
   const savedLog = console.log;
   const savedError = console.error;
   console.log = () => {};
@@ -208,31 +236,31 @@ function createReadProgram(
 
 // ─── PDA helpers ─────────────────────────────────────────────────────────────
 
-function findZkIdPda(nameHashBuf: Buffer, programId: PublicKey): [PublicKey, number] {
+function findZkIdPda(nameHashBuf: Uint8Array, programId: PublicKey): [PublicKey, number] {
   return PublicKey.findProgramAddressSync(
-    [Buffer.from("zk_id"), nameHashBuf],
+    [new TextEncoder().encode("zk_id"), nameHashBuf],
     programId
   );
 }
 
-function findInboxPda(nameHashBuf: Buffer, programId: PublicKey): [PublicKey, number] {
+function findInboxPda(nameHashBuf: Uint8Array, programId: PublicKey): [PublicKey, number] {
   return PublicKey.findProgramAddressSync(
-    [Buffer.from("inbox"), nameHashBuf],
+    [new TextEncoder().encode("inbox"), nameHashBuf],
     programId
   );
 }
 
 function findConfigPda(programId: PublicKey): [PublicKey, number] {
-  return PublicKey.findProgramAddressSync([Buffer.from("config")], programId);
+  return PublicKey.findProgramAddressSync([new TextEncoder().encode("config")], programId);
 }
 
 function findNullifierPda(
   denomination: BN,
-  nullifierHash: Buffer,
+  nullifierHash: Uint8Array,
   programId: PublicKey
 ): [PublicKey, number] {
   return PublicKey.findProgramAddressSync(
-    [Buffer.from("nullifier"), denomBuf(denomination), nullifierHash],
+    [new TextEncoder().encode("nullifier"), denomBuf(denomination), nullifierHash],
     programId
   );
 }
@@ -248,10 +276,10 @@ function findNullifierPda(
  * has a unique idSecret, preventing nullifier collisions.
  */
 export async function deriveIdSecret(keypair: Keypair, name: string): Promise<bigint> {
-  const message = Buffer.from(`nara-zk:idsecret:v1:${name}`);
+  const message = new TextEncoder().encode(`nara-zk:idsecret:v1:${name}`);
   const sig = nacl.sign.detached(message, keypair.secretKey);
-  const digest = createHash("sha256").update(sig).digest();
-  const n = BigInt("0x" + digest.toString("hex"));
+  const digest = new Uint8Array(await crypto.subtle.digest("SHA-256", sig));
+  const n = BigInt("0x" + hexFromBytes(digest));
   return (n % (BN254_PRIME - 1n)) + 1n;
 }
 
@@ -260,7 +288,7 @@ export async function deriveIdSecret(keypair: Keypair, name: string): Promise<bi
  * The ZK withdraw circuit encodes the recipient as a BN254 field element.
  */
 export function isValidRecipient(pubkey: PublicKey): boolean {
-  return bytes32ToBigInt(Buffer.from(pubkey.toBytes())) < BN254_PRIME;
+  return bytes32ToBigInt(pubkey.toBytes()) < BN254_PRIME;
 }
 
 /**
@@ -285,7 +313,7 @@ export async function getZkIdInfo(
 ): Promise<ZkIdInfo | null> {
   const program = createReadProgram(connection, options?.programId);
   const programId = new PublicKey(options?.programId ?? DEFAULT_ZKID_PROGRAM_ID);
-  const [zkIdPda] = findZkIdPda(computeNameHash(name), programId);
+  const [zkIdPda] = findZkIdPda(await computeNameHash(name), programId);
   try {
     const data = await program.account.zkIdAccount.fetch(zkIdPda);
     return {
@@ -316,7 +344,7 @@ export async function createZkId(
   const program = createProgram(connection, payer, options?.programId);
   const programId = new PublicKey(options?.programId ?? DEFAULT_ZKID_PROGRAM_ID);
 
-  const nameHashBuf = computeNameHash(name);
+  const nameHashBuf = await computeNameHash(name);
   const idCommitment = await poseidonHash([idSecret]);
   const idCommitmentBuf = bigIntToBytes32BE(idCommitment);
 
@@ -347,7 +375,7 @@ export async function deposit(
   options?: ZkIdOptions
 ): Promise<string> {
   const program = createProgram(connection, payer, options?.programId);
-  const nameHashBuf = computeNameHash(name);
+  const nameHashBuf = await computeNameHash(name);
 
   return await program.methods
     .deposit(toBytes32(nameHashBuf), denomination)
@@ -369,7 +397,7 @@ export async function scanClaimableDeposits(
 ): Promise<ClaimableDeposit[]> {
   const program = createReadProgram(connection, options?.programId);
   const programId = new PublicKey(options?.programId ?? DEFAULT_ZKID_PROGRAM_ID);
-  const nameHashBuf = computeNameHash(name);
+  const nameHashBuf = await computeNameHash(name);
 
   const [zkIdPda] = findZkIdPda(nameHashBuf, programId);
   const [inboxPda] = findInboxPda(nameHashBuf, programId);
@@ -453,19 +481,19 @@ export async function withdraw(
 
   // Fetch Merkle tree state
   const [treePda] = PublicKey.findProgramAddressSync(
-    [Buffer.from("tree"), denomBuf(denominationBN)],
+    [new TextEncoder().encode("tree"), denomBuf(denominationBN)],
     programId
   );
   const treeData = await program.account.merkleTreeAccount.fetch(treePda);
 
   const rootIdx: number = treeData.currentRootIndex;
-  const root = Buffer.from((treeData.roots as number[][])[rootIdx]!);
+  const root = new Uint8Array((treeData.roots as number[][])[rootIdx]!);
   const filledSubtrees = (treeData.filledSubtrees as number[][]).map(s =>
-    Buffer.from(s)
+    new Uint8Array(s)
   );
   // Use on-chain precomputed zeros (avoids expensive client-side computation)
   const zeros = (treeData.zeros as number[][]).map(z =>
-    bytes32ToBigInt(Buffer.from(z))
+    bytes32ToBigInt(new Uint8Array(z))
   );
 
   const { pathElements, pathIndices } = await buildMerklePath(
@@ -476,7 +504,7 @@ export async function withdraw(
 
   const nullifier = await poseidonHash([idSecret, BigInt(depositInfo.depositIndex)]);
   const nullifierHashBuf = bigIntToBytes32BE(nullifier);
-  const recipientField = bytes32ToBigInt(Buffer.from(recipient.toBytes()));
+  const recipientField = bytes32ToBigInt(recipient.toBytes());
 
   const input = {
     idSecret: idSecret.toString(),
@@ -488,12 +516,20 @@ export async function withdraw(
     recipient: recipientField.toString(),
   };
 
-  const { proof } = await silentProve(input, WITHDRAW_WASM, WITHDRAW_ZKEY);
+  let wasmSource = options?.withdrawWasm;
+  let zkeySource = options?.withdrawZkey;
+  if (!wasmSource || !zkeySource) {
+    const defaults = await resolveDefaultZkPaths();
+    wasmSource ??= defaults.withdrawWasm;
+    zkeySource ??= defaults.withdrawZkey;
+  }
+
+  const { proof } = await silentProve(input, wasmSource, zkeySource);
   const packedProof = packProof(proof);
 
   return await program.methods
     .withdraw(
-      packedProof,
+      Buffer.from(packedProof) as any,
       toBytes32(root),
       toBytes32(nullifierHashBuf),
       recipient,
@@ -506,6 +542,98 @@ export async function withdraw(
     .rpc();
 }
 
+/**
+ * Build a withdraw instruction without executing it.
+ * Useful for composing into an existing transaction.
+ *
+ * Same ZK proof generation as withdraw(), but returns a TransactionInstruction
+ * instead of sending the transaction.
+ *
+ * @param authority   - The payer/signer public key (does not need Keypair since we don't sign)
+ * @param depositInfo - From scanClaimableDeposits()
+ * @param recipient   - Destination address. Must satisfy isValidRecipient().
+ */
+export async function makeWithdrawIx(
+  connection: Connection,
+  authority: PublicKey,
+  name: string,
+  idSecret: bigint,
+  depositInfo: ClaimableDeposit,
+  recipient: PublicKey,
+  options?: ZkIdOptions
+): Promise<TransactionInstruction> {
+  if (!isValidRecipient(recipient)) {
+    throw new Error(
+      "Recipient pubkey is >= BN254 field prime. Use generateValidRecipient() to get a compatible address."
+    );
+  }
+
+  const program = createReadProgram(connection, options?.programId);
+  const programId = new PublicKey(options?.programId ?? DEFAULT_ZKID_PROGRAM_ID);
+  const denominationBN = new BN(depositInfo.denomination.toString());
+
+  // Fetch Merkle tree state
+  const [treePda] = PublicKey.findProgramAddressSync(
+    [new TextEncoder().encode("tree"), denomBuf(denominationBN)],
+    programId
+  );
+  const treeData = await program.account.merkleTreeAccount.fetch(treePda);
+
+  const rootIdx: number = treeData.currentRootIndex;
+  const root = new Uint8Array((treeData.roots as number[][])[rootIdx]!);
+  const filledSubtrees = (treeData.filledSubtrees as number[][]).map(s =>
+    new Uint8Array(s)
+  );
+  const zeros = (treeData.zeros as number[][]).map(z =>
+    bytes32ToBigInt(new Uint8Array(z))
+  );
+
+  const { pathElements, pathIndices } = await buildMerklePath(
+    depositInfo.leafIndex,
+    filledSubtrees,
+    zeros
+  );
+
+  const nullifier = await poseidonHash([idSecret, BigInt(depositInfo.depositIndex)]);
+  const nullifierHashBuf = bigIntToBytes32BE(nullifier);
+  const recipientField = bytes32ToBigInt(recipient.toBytes());
+
+  const input = {
+    idSecret: idSecret.toString(),
+    depositIndex: depositInfo.depositIndex.toString(),
+    pathElements: pathElements.map(e => e.toString()),
+    pathIndices: pathIndices.map(i => i.toString()),
+    root: bytes32ToBigInt(root).toString(),
+    nullifierHash: nullifier.toString(),
+    recipient: recipientField.toString(),
+  };
+
+  let wasmSource = options?.withdrawWasm;
+  let zkeySource = options?.withdrawZkey;
+  if (!wasmSource || !zkeySource) {
+    const defaults = await resolveDefaultZkPaths();
+    wasmSource ??= defaults.withdrawWasm;
+    zkeySource ??= defaults.withdrawZkey;
+  }
+
+  const { proof } = await silentProve(input, wasmSource, zkeySource);
+  const packedProof = packProof(proof);
+
+  return program.methods
+    .withdraw(
+      Buffer.from(packedProof) as any,
+      toBytes32(root),
+      toBytes32(nullifierHashBuf),
+      recipient,
+      denominationBN
+    )
+    .accounts({
+      payer: authority,
+      recipient,
+    } as any)
+    .instruction();
+}
+
 /**
  * Transfer ZK ID ownership to a new identity.
  *
@@ -526,13 +654,13 @@ export async function transferZkId(
 ): Promise<string> {
   const program = createProgram(connection, payer, options?.programId);
   const programId = new PublicKey(options?.programId ?? DEFAULT_ZKID_PROGRAM_ID);
-  const nameHashBuf = computeNameHash(name);
+  const nameHashBuf = await computeNameHash(name);
 
   // Fetch current id_commitment from chain
   const [zkIdPda] = findZkIdPda(nameHashBuf, programId);
   const zkId = await program.account.zkIdAccount.fetch(zkIdPda);
   const currentCommitmentField = bytes32ToBigInt(
-    Buffer.from(zkId.idCommitment as number[])
+    new Uint8Array(zkId.idCommitment as number[])
   );
 
   // Compute new id_commitment
@@ -544,14 +672,23 @@ export async function transferZkId(
     idSecret: currentIdSecret.toString(),
     idCommitment: currentCommitmentField.toString(),
   };
-  const { proof } = await silentProve(input, OWNERSHIP_WASM, OWNERSHIP_ZKEY);
+
+  let wasmSource = options?.ownershipWasm;
+  let zkeySource = options?.ownershipZkey;
+  if (!wasmSource || !zkeySource) {
+    const defaults = await resolveDefaultZkPaths();
+    wasmSource ??= defaults.ownershipWasm;
+    zkeySource ??= defaults.ownershipZkey;
+  }
+
+  const { proof } = await silentProve(input, wasmSource, zkeySource);
   const packedProof = packProof(proof);
 
   return await program.methods
     .transferZkId(
       toBytes32(nameHashBuf),
       toBytes32(newCommitmentBuf),
-      packedProof
+      Buffer.from(packedProof) as any
     )
     .accounts({ payer: payer.publicKey } as any)
     .rpc();
@@ -566,7 +703,7 @@ export async function transferZkId(
 export async function computeIdCommitment(keypair: Keypair, name: string): Promise<string> {
   const idSecret = await deriveIdSecret(keypair, name);
   const commitment = await poseidonHash([idSecret]);
-  return bigIntToBytes32BE(commitment).toString("hex");
+  return hexFromBytes(bigIntToBytes32BE(commitment));
 }
 
 /**
@@ -588,12 +725,12 @@ export async function transferZkIdByCommitment(
   options?: ZkIdOptions
 ): Promise<string> {
   const program = createProgram(connection, payer, options?.programId);
-  const nameHashBuf = computeNameHash(name);
+  const nameHashBuf = await computeNameHash(name);
 
   const [zkIdPda] = findZkIdPda(nameHashBuf, new PublicKey(options?.programId ?? DEFAULT_ZKID_PROGRAM_ID));
   const zkId = await program.account.zkIdAccount.fetch(zkIdPda);
   const currentCommitmentField = bytes32ToBigInt(
-    Buffer.from(zkId.idCommitment as number[])
+    new Uint8Array(zkId.idCommitment as number[])
   );
 
   const newCommitmentBuf = bigIntToBytes32BE(newIdCommitment);
@@ -602,14 +739,23 @@ export async function transferZkIdByCommitment(
     idSecret: currentIdSecret.toString(),
     idCommitment: currentCommitmentField.toString(),
   };
-  const { proof } = await silentProve(input, OWNERSHIP_WASM, OWNERSHIP_ZKEY);
+
+  let wasmSource = options?.ownershipWasm;
+  let zkeySource = options?.ownershipZkey;
+  if (!wasmSource || !zkeySource) {
+    const defaults = await resolveDefaultZkPaths();
+    wasmSource ??= defaults.ownershipWasm;
+    zkeySource ??= defaults.ownershipZkey;
+  }
+
+  const { proof } = await silentProve(input, wasmSource, zkeySource);
   const packedProof = packProof(proof);
 
   return await program.methods
     .transferZkId(
       toBytes32(nameHashBuf),
       toBytes32(newCommitmentBuf),
-      packedProof
+      Buffer.from(packedProof) as any
     )
     .accounts({ payer: payer.publicKey } as any)
     .rpc();
@@ -630,18 +776,19 @@ export async function getConfig(
 ): Promise<{ admin: PublicKey; feeRecipient: PublicKey; feeAmount: number }> {
   const programId = new PublicKey(options?.programId ?? DEFAULT_ZKID_PROGRAM_ID);
   const [configPda] = PublicKey.findProgramAddressSync(
-    [Buffer.from("config")],
+    [new TextEncoder().encode("config")],
     programId
   );
   const accountInfo = await connection.getAccountInfo(configPda);
   if (!accountInfo) {
     throw new Error("ZK ID config account not found");
   }
-  const buf = Buffer.from(accountInfo.data);
+  const data = accountInfo.data;
+  const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
   let offset = 8; // skip discriminator
-  const admin = new PublicKey(buf.subarray(offset, offset + 32)); offset += 32;
-  const feeRecipient = new PublicKey(buf.subarray(offset, offset + 32)); offset += 32;
-  const feeAmount = Number(buf.readBigUInt64LE(offset));
+  const admin = new PublicKey(data.subarray(offset, offset + 32)); offset += 32;
+  const feeRecipient = new PublicKey(data.subarray(offset, offset + 32)); offset += 32;
+  const feeAmount = Number(view.getBigUint64(offset, true));
   return { admin, feeRecipient, feeAmount };
 }