@orbinum/sdk 0.4.2 → 0.5.0

package/dist/index.mjs

@@ -41,6 +41,7 @@ var SubstrateClient = class _SubstrateClient {
   constructor(_papi) {
     this._papi = _papi;
   }
+  _papi;
   _dynamicBuilder = null;
   _extDecoder = null;
   /**
@@ -240,6 +241,14 @@ var SubstrateClient = class _SubstrateClient {
   submitAndWatch(signedHex) {
     return this._papi.submitAndWatch(signedHex);
   }
+  /**
+   * Submits a bare (unsigned) extrinsic hex and waits for finalization.
+   * Used for gasless private_transfer and unshield transactions.
+   * The bare tx hex is produced by `tx.getBareTx()` from polkadot-api.
+   */
+  async submitUnsignedAndWatch(bareTxHex) {
+    return this._papi.submit(bareTxHex);
+  }
   /**
    * Convenience: wrap raw call bytes and sign+submit in one step.
    */
@@ -291,15 +300,14 @@ var SubstrateClient = class _SubstrateClient {
   }
   static _buildDataProxy(value) {
     const formatValue = (v) => {
-      if (v instanceof Uint8Array) return fromHex(v).toString();
+      if (v instanceof Uint8Array) return toHex(v);
       if (typeof v === "bigint") return v.toString();
       return String(v);
     };
     const jsonifyValue = (v) => {
       if (v === null || v === void 0) return v;
       if (typeof v === "bigint") return v.toString();
-      if (v instanceof Uint8Array)
-        return `0x${Array.from(v).map((b) => b.toString(16).padStart(2, "0")).join("")}`;
+      if (v instanceof Uint8Array) return toHex(v);
       if (Array.isArray(v)) return v.map(jsonifyValue);
       if (typeof v === "object") {
         const obj = v;
@@ -403,11 +411,14 @@ var SubstrateClient = class _SubstrateClient {
 
 // src/evm/EvmClient.ts
 var EvmClient = class {
+  /** @param rpcUrl - HTTP URL of the EVM JSON-RPC endpoint (e.g. `"http://localhost:9933"`). */
   constructor(rpcUrl) {
     this.rpcUrl = rpcUrl;
   }
+  rpcUrl;
   /**
-   * Performs a single JSON-RPC call.
+   * Performs a single JSON-RPC call and returns the typed result.
+   * Throws on HTTP errors, RPC-level errors, or a `null` result.
    */
   async request(method, params = []) {
     const res = await fetch(this.rpcUrl, {
@@ -427,6 +438,7 @@ var EvmClient = class {
   }
   /**
    * Performs multiple JSON-RPC calls in a single HTTP request (batch).
+   * Results are returned in the same order as `calls`, as a typed tuple.
    */
   async batchRequest(calls) {
     const body = calls.map((c, i) => ({
@@ -471,30 +483,22 @@ var EvmClient = class {
     const hex = await this.request("eth_gasPrice", []);
     return hexToBigint(hex);
   }
-  /**
-   * Submits a signed raw transaction. Returns the transaction hash.
-   */
+  /** Submits a signed raw transaction. Returns the transaction hash. */
   async sendRawTransaction(signedHex) {
     return this.request("eth_sendRawTransaction", [signedHex]);
   }
-  /**
-   * Executes a read-only call without creating a transaction.
-   */
+  /** Executes a read-only call without creating a transaction. Returns the raw ABI-encoded response. */
   async call(to, data, from) {
     const txObj = { to, data };
     if (from) txObj["from"] = from;
     return this.request("eth_call", [txObj, "latest"]);
   }
-  /**
-   * Estimates the gas for a transaction.
-   */
+  /** Estimates the gas required for a transaction. Returns the estimate in wei as a `bigint`. */
   async estimateGas(params) {
     const hex = await this.request("eth_estimateGas", [params]);
     return hexToBigint(hex);
   }
-  /**
-   * Returns a transaction receipt by hash, or null if not yet mined.
-   */
+  /** Returns a transaction receipt by hash, or `null` if the transaction has not been mined yet. */
   async getTransactionReceipt(txHash) {
     const res = await fetch(this.rpcUrl, {
       method: "POST",
@@ -513,6 +517,56 @@ var EvmClient = class {
     }
     return json.result ?? null;
   }
+  /**
+   * Polls `eth_getTransactionReceipt` until the transaction is included in a block.
+   *
+   * @param txHash - The transaction hash to wait for.
+   * @param intervalMs - Polling interval in milliseconds (default: 500).
+   * @param timeoutMs - Maximum time to wait in milliseconds (default: 60_000).
+   * @returns The transaction receipt once mined.
+   * @throws If the transaction is not mined within `timeoutMs` or if it reverted (`status == 0x0`).
+   */
+  async waitForReceipt(txHash, intervalMs = 500, timeoutMs = 6e4) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+      const receipt = await this.getTransactionReceipt(txHash);
+      if (receipt !== null) {
+        if (receipt["status"] === "0x0") {
+          let revertDetail = "";
+          const nodeReason = receipt["revertReason"];
+          if (nodeReason) revertDetail = ` | revertReason: ${nodeReason}`;
+          if (!revertDetail) {
+            try {
+              const blockParam = receipt["blockNumber"] ?? "latest";
+              const rawTx = await this.request(
+                "eth_getTransactionByHash",
+                [txHash]
+              ).catch(() => null);
+              if (rawTx) {
+                const calldata = rawTx["input"] ?? rawTx["data"];
+                if (calldata) {
+                  const revertData = await this.request("eth_call", [
+                    { from: rawTx["from"], to: rawTx["to"], data: calldata },
+                    blockParam
+                  ]).catch(
+                    (err) => err instanceof Error ? err.message : String(err)
+                  );
+                  revertDetail = ` | eth_call: ${revertData}`;
+                }
+              }
+            } catch {
+            }
+          }
+          throw new Error(
+            `Transaction reverted on-chain: ${txHash}${revertDetail} | receipt: ${JSON.stringify(receipt)}`
+          );
+        }
+        return receipt;
+      }
+      await new Promise((resolve) => setTimeout(resolve, intervalMs));
+    }
+    throw new Error(`Transaction not mined within ${timeoutMs}ms: ${txHash}`);
+  }
 };
 
 // src/utils/format.ts
@@ -585,10 +639,13 @@ function formatORB(raw, precision = 6) {
 
 // src/evm-explorer/EvmExplorer.ts
 var EvmExplorer = class _EvmExplorer {
+  /** @param evm - Underlying `EvmClient` used for all RPC calls. */
   constructor(evm) {
     this.evm = evm;
   }
+  evm;
   // --- Blocks ---
+  /** Returns the `count` most recent blocks in descending order (latest first). */
   async getLatestBlocks(count = 10) {
     const latest = await this.evm.getBlockNumber();
     const nums = Array.from({ length: Math.min(count, latest + 1) }, (_, i) => latest - i);
@@ -602,10 +659,12 @@ var EvmExplorer = class _EvmExplorer {
     );
     return results.filter((b) => b !== null && !!b.hash).map((b) => this.parseBlock(b));
   }
+  /** Returns a single block by number or hash, or `null` if not found. */
   async getBlock(hashOrNumber) {
     const b = await this.fetchBlock(hashOrNumber, false);
     return b ? this.parseBlock(b) : null;
   }
+  /** Returns all transactions in a block (with receipts), or `[]` if the block is not found. */
   async getBlockTransactions(hashOrNumber) {
     try {
       const b = await this.fetchBlock(hashOrNumber, true);
@@ -618,6 +677,7 @@ var EvmExplorer = class _EvmExplorer {
     }
   }
   // --- Transactions ---
+  /** Returns a single transaction with its receipt, or `null` if not found. */
   async getTransaction(hash) {
     try {
       const [tx, receipt] = await Promise.all([
@@ -630,6 +690,10 @@ var EvmExplorer = class _EvmExplorer {
       return null;
     }
   }
+  /**
+   * Returns lightweight summaries of all transactions sent from or to `address`
+   * within the last `maxBlocks` blocks, sorted by block number descending.
+   */
   async getTransactionsByAddress(address, maxBlocks = 300) {
     const addr = address.toLowerCase();
     const latest = await this.evm.getBlockNumber();
@@ -681,6 +745,10 @@ var EvmExplorer = class _EvmExplorer {
     return results;
   }
   // --- Address ---
+  /**
+   * Returns aggregated on-chain data for an EVM address: balance, nonce,
+   * bytecode (truncated), and up to 50 recent logs from the last 5 000 blocks.
+   */
   async getAddressInfo(address) {
     const latest = await this.evm.getBlockNumber().catch(() => 0);
     const fromBlock = `0x${Math.max(0, latest - 5e3).toString(16)}`;
@@ -711,6 +779,7 @@ var EvmExplorer = class _EvmExplorer {
       recentLogs
     };
   }
+  /** Returns the native token balance of `address`, formatted as a decimal string (no symbol). */
   async getBalance(address) {
     try {
       const val = await this.evm.getBalance(address);
@@ -719,6 +788,7 @@ var EvmExplorer = class _EvmExplorer {
       return "0";
     }
   }
+  /** Returns the current transaction count (nonce) for `address`, or `0` on error. */
   async getNonce(address) {
     try {
       return await this.evm.getTransactionCount(address);
@@ -726,6 +796,7 @@ var EvmExplorer = class _EvmExplorer {
       return 0;
     }
   }
+  /** Returns `true` when `address` has non-empty deployed bytecode. */
   async getIsContract(address) {
     try {
       const code = await this.evm.request("eth_getCode", [address, "latest"]);
@@ -735,6 +806,10 @@ var EvmExplorer = class _EvmExplorer {
     }
   }
   // --- Tokens ---
+  /**
+   * Fetches ERC-20 metadata for a token contract via ABI calls.
+   * Returns `null` when the address does not look like an ERC-20 token.
+   */
   async getTokenInfo(address) {
     const addr = address.toLowerCase();
     const [name, symbol, decimals, totalSupply] = await this.evm.batchRequest([
@@ -754,6 +829,10 @@ var EvmExplorer = class _EvmExplorer {
       isErc20
     };
   }
+  /**
+   * Returns ERC-20 `Transfer` events for `address` from the last 5 000 blocks.
+   * When `holderAddress` is provided, restricts results to transfers sent or received by that address.
+   */
   async getTokenTransfers(address, holderAddress) {
     const TRANSFER = "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef";
     const latest = await this.evm.getBlockNumber().catch(() => 0);
@@ -781,12 +860,14 @@ var EvmExplorer = class _EvmExplorer {
       logIndex: hexToNumber(l.logIndex)
     }));
   }
+  /** Returns the raw ERC-20 balance of `holderAddress` for the token at `tokenAddress` (0x-prefixed hex). */
   async getTokenBalance(tokenAddress, holderAddress) {
     const padded = holderAddress.replace(/^0x/, "").toLowerCase().padStart(64, "0");
     const result = await this.ethCall(tokenAddress, `0x70a08231${padded}`);
     return result ?? "0x0";
   }
   // --- Private: parsers ---
+  /** Maps a raw RPC block object to the public `EvmBlock` shape. */
   parseBlock(b) {
     return {
       hash: b.hash,
@@ -799,6 +880,7 @@ var EvmExplorer = class _EvmExplorer {
       parentHash: b.parentHash
     };
   }
+  /** Maps a raw RPC transaction + optional receipt to the public `EvmTransaction` shape. */
   parseTx(tx, receipt) {
     const parsed = {
       hash: tx.hash,
@@ -818,6 +900,10 @@ var EvmExplorer = class _EvmExplorer {
     return parsed;
   }
   // --- Private: fetch helpers ---
+  /**
+   * Fetches a raw block by number or hash. Accepts a plain integer, a decimal string,
+   * or a 0x-prefixed hash. Returns `null` on any RPC error.
+   */
   async fetchBlock(hashOrNumber, withTxObjects) {
     try {
       if (typeof hashOrNumber === "number" || /^\d+$/.test(String(hashOrNumber))) {
@@ -835,6 +921,7 @@ var EvmExplorer = class _EvmExplorer {
       return null;
     }
   }
+  /** Executes a read-only `eth_call` and returns the raw hex result, or `null` on error. */
   async ethCall(to, data) {
     try {
       return await this.evm.call(to, data);
@@ -843,6 +930,7 @@ var EvmExplorer = class _EvmExplorer {
     }
   }
   // --- Private static: ABI decoders ---
+  /** Decodes an ABI-encoded `string` return value from a raw 0x-prefixed hex string. */
   static decodeAbiString(hex) {
     if (!hex || hex === "0x") return "";
     const data = hex.startsWith("0x") ? hex.slice(2) : hex;
@@ -857,11 +945,13 @@ var EvmExplorer = class _EvmExplorer {
       return "";
     }
   }
+  /** Decodes an ABI-encoded `uint256` return value to a `bigint`. */
   static decodeAbiUint(hex) {
     if (!hex || hex === "0x") return 0n;
     const clean = hex.startsWith("0x") ? hex.slice(2) : hex;
     return BigInt(`0x${clean || "0"}`);
   }
+  /** Converts a 0x-prefixed hex number to its decimal string representation. Returns `'0'` on parse error. */
   static hexToDecimalStr(hex) {
     try {
       return BigInt(hex).toString();
@@ -896,6 +986,24 @@ var IndexerClient = class {
     }
     return res.json();
   }
+  async post(path, body) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+    try {
+      const res = await fetch(`${this.baseUrl}${path}`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(body),
+        signal: controller.signal
+      });
+      if (!res.ok) {
+        throw new Error(`IndexerClient: HTTP ${res.status} for POST ${path}`);
+      }
+      return res.json();
+    } finally {
+      clearTimeout(timer);
+    }
+  }
   async getOrNull(path) {
     const res = await this._fetchResponse(path);
     if (res.status === 404) return null;
@@ -931,6 +1039,21 @@ var IndexerClient = class {
       `/shielded/commitments/${encodeURIComponent(hex)}`
     );
   }
+  /**
+   * Returns a paginated list of stealth scan hints ordered ascending by leafIndex.
+   * Each hint contains only the fields required for ECDH triage and decryption:
+   * leafIndex, commitmentHex, assetId, ephPkHex, encryptedMemo.
+   *
+   * Use `sinceLeafIndex` for incremental scans (cursor = last seen leafIndex + 1).
+   */
+  async getScanHints(params) {
+    const qs = this.buildQuery({
+      page: params?.page,
+      limit: params?.limit,
+      since_leaf_index: params?.sinceLeafIndex
+    });
+    return this.get(`/shielded/scan-hints${qs}`);
+  }
   // ─── Nullifiers ────────────────────────────────────────────────────────────
   /** Returns a paginated list of spent nullifiers. */
   async getNullifiers(params) {
@@ -943,11 +1066,50 @@ var IndexerClient = class {
       `/shielded/nullifier/${encodeURIComponent(hex)}/status`
     );
   }
+  /**
+   * Batch-checks which of the given nullifiers are spent.
+   * Returns only the nullifiers that exist in the spent set.
+   * Accepts up to 100 nullifiers (0x-prefixed hex).
+   */
+  async getNullifiersBatch(nullifiers) {
+    if (nullifiers.length === 0) return [];
+    const res = await this.post("/shielded/nullifiers/batch", {
+      nullifiers: nullifiers.map((n) => n.toLowerCase())
+    });
+    return res.data;
+  }
   // ─── Private transfers ─────────────────────────────────────────────────────
-  /** Returns a paginated list of private transfer events. */
-  async getTransfers(params) {
-    const qs = this.buildQuery({ page: params?.page, limit: params?.limit });
-    return this.get(`/shielded/transfers${qs}`);
+  /**
+   * Returns temporal metadata for private transfers that spent any of the given nullifiers.
+   * Only blockNumber, extrinsicIndex, timestampMs, and hash are returned — no cross-link
+   * between inputs and outputs to prevent graph reconstruction.
+   * Accepts up to 50 nullifiers (0x-prefixed hex).
+   */
+  async getTransfersByNullifiers(nullifiers) {
+    if (nullifiers.length === 0) return [];
+    const qs = this.buildQuery({
+      nullifiers: nullifiers.map((n) => n.toLowerCase()).join(",")
+    });
+    const res = await this.get(
+      `/shielded/transfers/by-nullifiers${qs}`
+    );
+    return res.data;
+  }
+  /**
+   * Returns temporal metadata for private transfers that produced any of the given commitments.
+   * Only blockNumber, extrinsicIndex, timestampMs, and hash are returned — no cross-link
+   * between outputs and inputs to prevent graph reconstruction.
+   * Accepts up to 50 commitments (0x-prefixed hex).
+   */
+  async getTransfersByCommitments(commitments) {
+    if (commitments.length === 0) return [];
+    const qs = this.buildQuery({
+      commitments: commitments.map((c) => c.toLowerCase()).join(",")
+    });
+    const res = await this.get(
+      `/shielded/transfers/by-commitments${qs}`
+    );
+    return res.data;
   }
   // ─── Unshields ─────────────────────────────────────────────────────────────
   /** Returns a paginated list of unshield events. */
@@ -1007,6 +1169,16 @@ var IndexerClient = class {
       `/address/${encodeURIComponent(address.toLowerCase())}/shielded${qs}`
     );
   }
+  /**
+   * Returns a paginated list of unshield events where the given address is the recipient.
+   * Accepts a 0x-prefixed EVM address or an SS58 Substrate address.
+   */
+  async getAddressUnshields(address, params) {
+    const qs = this.buildQuery({ page: params?.page, limit: params?.limit });
+    return this.get(
+      `/address/${encodeURIComponent(address)}/unshields${qs}`
+    );
+  }
   /**
    * Returns a paginated list of all shielded activity (commitments, unshields,
    * private transfers) associated with the given address.
@@ -1042,10 +1214,24 @@ var IndexerClient = class {
   }
 };
 
-// src/shielded-pool/ShieldedPoolModule.ts
+// src/shielded-pool/pallet/ShieldedPoolModule.ts
 import { Binary as Binary2 } from "polkadot-api";
 
 // src/utils/tx.ts
+function formatDispatchError(err) {
+  if (err.type === "Module") {
+    const inner = err.value;
+    if (inner?.type) {
+      return `Module(${inner.type})`;
+    }
+  }
+  try {
+    const detail = JSON.stringify(err.value);
+    return detail && detail !== "null" ? `${err.type}(${detail})` : err.type;
+  } catch {
+    return err.type;
+  }
+}
 function toTxResult(payload) {
   const base = {
     txHash: payload.txHash,
@@ -1054,13 +1240,18 @@ function toTxResult(payload) {
     ok: payload.ok
   };
   if (!payload.ok) {
-    return { ...base, error: payload.dispatchError.type };
+    return { ...base, error: formatDispatchError(payload.dispatchError) };
   }
   return base;
 }
 function callUnsafeTx(txEntry, ...args) {
   return txEntry(...args);
 }
+async function submitBareTx(tx, client) {
+  const bareTxHex = await tx.getBareTx();
+  const payload = await client.submitUnsignedAndWatch(bareTxHex);
+  return toTxResult(payload);
+}
 function resolveTx(unsafe, pallet, call) {
   const u = unsafe;
   const p = u["tx"]?.[pallet];
@@ -1071,9 +1262,10 @@ function resolveTx(unsafe, pallet, call) {
   return entry;
 }
 
-// src/shielded-pool/EncryptedMemo.ts
+// src/shielded-pool/protocol/EncryptedMemo.ts
 import { chacha20poly1305 } from "@noble/ciphers/chacha.js";
 import { randomBytes } from "@noble/ciphers/utils.js";
+import { mulPointEscalar, Base8, packPoint, unpackPoint } from "@zk-kit/baby-jubjub";
 
 // src/utils/bytes.ts
 function bigintTo32Le(n) {
@@ -1120,77 +1312,114 @@ function computePathIndices(leafIndex, depth) {
   return indices;
 }
 function leHexToBigint(hex) {
-  const h = hex.startsWith("0x") ? hex.slice(2) : hex;
-  const bytes = new Uint8Array(h.length / 2);
-  for (let i = 0; i < bytes.length; i++) {
-    bytes[i] = parseInt(h.slice(i * 2, i * 2 + 2), 16);
-  }
-  return bytesToBigintLE(bytes);
+  return bytesToBigintLE(fromHex(hex));
 }
 
-// src/shielded-pool/helpers.ts
+// src/utils/crypto-constants.ts
+var BN254_R = 21888242871839275222246405745257275088548364400416034343698204186575808495617n;
+var BABYJUB_SUBORDER = 2736030358979909402780800718157159386076813972158567259200215660948447373041n;
+
+// src/shielded-pool/protocol/memo.ts
 import { sha256 } from "@noble/hashes/sha2.js";
 var KEY_DOMAIN = new TextEncoder().encode("orbinum-note-encryption-v1");
-var MEMO_PLAINTEXT_SIZE = 76;
-function serializeMemo(value, ownerPk, blinding, assetId) {
+var MEMO_PLAINTEXT_SIZE = 116;
+function serializeMemo(value, ownerPk, blinding, assetId, counterpartyPk) {
   const buf = new Uint8Array(MEMO_PLAINTEXT_SIZE);
   const view = new DataView(buf.buffer);
   view.setBigUint64(0, value & 0xffffffffffffffffn, true);
-  buf.set(ownerPk.slice(0, 32), 8);
-  buf.set(blinding.slice(0, 32), 40);
-  view.setUint32(72, assetId >>> 0, true);
+  view.setBigUint64(8, value >> 64n & 0xffffffffffffffffn, true);
+  buf.set(ownerPk.slice(0, 32), 16);
+  buf.set(blinding.slice(0, 32), 48);
+  view.setUint32(80, assetId >>> 0, true);
+  buf.set(counterpartyPk.slice(0, 32), 84);
   return buf;
 }
-function deriveEncryptionKey(viewingKey, commitment) {
+function deriveEncryptionKey(sharedSecret, commitment) {
   const h = sha256.create();
-  h.update(viewingKey);
+  h.update(sharedSecret);
   h.update(commitment);
   h.update(KEY_DOMAIN);
   return h.digest();
 }
-function toBase64(buf) {
-  const bytes = buf instanceof Uint8Array ? buf : new Uint8Array(buf);
-  let str = "";
-  for (const b of bytes) str += String.fromCharCode(b);
-  return btoa(str);
-}
-function fromBase64(b64) {
-  const bin = atob(b64);
-  const out = new Uint8Array(bin.length);
-  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
-  return out;
-}
 
-// src/shielded-pool/EncryptedMemo.ts
+// src/shielded-pool/protocol/EncryptedMemo.ts
 var NONCE_SIZE = 12;
-var ENCRYPTED_MEMO_SIZE = 104;
+var CIPHERTEXT_SIZE = 132;
+var EPH_PK_SIZE = 32;
+var ENCRYPTED_MEMO_SIZE = NONCE_SIZE + CIPHERTEXT_SIZE + EPH_PK_SIZE;
+function bytesToBjjScalar(bytes) {
+  const hex = Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+  return BigInt("0x" + hex) % BABYJUB_SUBORDER || 1n;
+}
+function parsePlaintext(nonce, ciphertextWithMac, encKey) {
+  try {
+    const cipher = chacha20poly1305(encKey, nonce);
+    const plaintext = cipher.decrypt(ciphertextWithMac);
+    const view = new DataView(plaintext.buffer, plaintext.byteOffset, plaintext.byteLength);
+    const valueLo = view.getBigUint64(0, true);
+    const valueHi = view.getBigUint64(8, true);
+    const value = valueLo | valueHi << 64n;
+    const ownerPk = bytesToBigintLE(plaintext.slice(16, 48));
+    const blinding = bytesToBigintLE(plaintext.slice(48, 80));
+    const assetId = BigInt(view.getUint32(80, true));
+    const counterpartyPk = bytesToBigintLE(plaintext.slice(84, 116));
+    return { value, ownerPk, blinding, assetId, counterpartyPk };
+  } catch {
+    return null;
+  }
+}
 var EncryptedMemo = {
   /**
-   * Build and encrypt a memo for a note.
+   * Build and encrypt a memo for a note using ECDH (v2, 168 bytes).
    *
-   * @param value       Note value in planck.
-   * @param ownerPk     32-byte owner public key (little-endian).
-   * @param blinding    32-byte blinding scalar (little-endian).
-   * @param assetId     Asset identifier.
-   * @param commitment  32-byte commitment bytes (little-endian).
-   * @param recipientVk 32-byte recipient viewing key — pass `new Uint8Array(32)`
-   *                    for a publicly-readable (dummy) memo.
-   * @returns 104-byte encrypted memo (nonce || ciphertext).
-   */
-  encrypt(value, ownerPk, blinding, assetId, commitment, recipientVk) {
+   * @param value              Note value in planck.
+   * @param ownerPk            32-byte owner public key (LE).
+   * @param blinding           32-byte blinding scalar (LE).
+   * @param assetId            Asset identifier.
+   * @param commitment         32-byte commitment bytes (LE).
+   * @param recipientIvkPacked 32-byte LE-encoded packed BJJ viewing public key
+   *                           (from PrivacyKeyManager.getViewingPublicKeyPacked() or
+   *                           decoded from a privacy address).
+   *                           Pass `new Uint8Array(32)` (all zeros) for a publicly-readable memo.
+   * @param counterpartyPk     32-byte counterparty BJJ Ax. Default: all zeros.
+   * @returns 168-byte encrypted memo: nonce(12) || ciphertext+MAC(124) || ephPk(32).
+   */
+  encrypt(value, ownerPk, blinding, assetId, commitment, recipientIvkPacked, counterpartyPk = new Uint8Array(32), ephSkOverride) {
     const nonce = randomBytes(NONCE_SIZE);
-    const key = deriveEncryptionKey(recipientVk, commitment);
-    const plaintext = serializeMemo(value, ownerPk, blinding, assetId);
-    const cipher = chacha20poly1305(key, nonce);
+    const plaintext = serializeMemo(value, ownerPk, blinding, assetId, counterpartyPk);
+    const isZeroKey = recipientIvkPacked.every((b) => b === 0);
+    let sharedSecret;
+    let ephPkPackedBytes;
+    if (isZeroKey) {
+      sharedSecret = new Uint8Array(32);
+      ephPkPackedBytes = new Uint8Array(EPH_PK_SIZE);
+    } else {
+      const ephSkBytes = ephSkOverride ?? randomBytes(32);
+      if (ephSkBytes.length !== 32)
+        throw new Error("EncryptedMemo.encrypt: ephSkOverride must be 32 bytes");
+      const ephSkScalar = bytesToBjjScalar(ephSkBytes);
+      const ephPkPoint = mulPointEscalar(Base8, ephSkScalar);
+      ephPkPackedBytes = bigintTo32Le(packPoint(ephPkPoint));
+      const ivkPackedBigint = bytesToBigintLE(recipientIvkPacked);
+      const ivkPoint = unpackPoint(ivkPackedBigint);
+      if (!ivkPoint)
+        throw new Error("EncryptedMemo.encrypt: invalid recipient viewing public key");
+      const sharedPoint = mulPointEscalar(ivkPoint, ephSkScalar);
+      sharedSecret = bigintTo32Le(sharedPoint[0]);
+    }
+    const encKey = deriveEncryptionKey(sharedSecret, commitment);
+    const cipher = chacha20poly1305(encKey, nonce);
     const ciphertext = cipher.encrypt(plaintext);
-    const result = new Uint8Array(NONCE_SIZE + ciphertext.length);
+    const result = new Uint8Array(ENCRYPTED_MEMO_SIZE);
     result.set(nonce, 0);
     result.set(ciphertext, NONCE_SIZE);
+    result.set(ephPkPackedBytes, NONCE_SIZE + CIPHERTEXT_SIZE);
     return result;
   },
   /**
-   * Returns a 104-byte public memo with a zero recipient viewing key.
-   * The memo is still readable by anyone who holds the viewing key (zeros).
+   * Returns a 168-byte public memo encrypted with a zero viewing key.
+   * Decryptable by anyone with `decrypt(memo, commitment, new Uint8Array(32))`.
+   * Convenience alias for `encrypt(..., new Uint8Array(32))`.
    */
   encryptPublic(value, ownerPk, blinding, assetId, commitment) {
     return EncryptedMemo.encrypt(
@@ -1203,226 +1432,89 @@ var EncryptedMemo = {
     );
   },
   /**
-   * Returns a 104-byte zeroed dummy memo (no information, always valid on-chain).
+   * Returns a 168-byte zeroed dummy memo (no information, always valid on-chain).
    */
   dummy() {
     return new Uint8Array(ENCRYPTED_MEMO_SIZE);
   },
   /**
-   * Decrypt an on-chain EncryptedMemo.
+   * Validates that `bytes` is a properly-sized encrypted memo.
+   * Throws an Error if the length is not ENCRYPTED_MEMO_SIZE (168 bytes).
    *
-   * Returns `null` if decryption fails — wrong key, bad MAC, or malformed memo.
-   * Never throws; safe for scan loops.
+   * Call this at system boundaries (extrinsic builders, precompile encoders)
+   * to catch malformed memos before they reach the chain and fail on-chain.
    *
-   * @param memoBytes   104-byte encrypted memo.
-   * @param commitment  32-byte note commitment (little-endian).
-   * @param recipientVk 32-byte recipient viewing key.
+   * @param bytes   The memo bytes to validate.
+   * @param context Optional context string included in the error (e.g. 'shield', 'output[0]').
    */
-  decrypt(memoBytes, commitment, recipientVk) {
-    if (memoBytes.length !== ENCRYPTED_MEMO_SIZE) return null;
-    try {
-      const nonce = memoBytes.slice(0, NONCE_SIZE);
-      const ciphertext = memoBytes.slice(NONCE_SIZE);
-      const key = deriveEncryptionKey(recipientVk, commitment);
-      const cipher = chacha20poly1305(key, nonce);
-      const plaintext = cipher.decrypt(ciphertext);
-      const view = new DataView(plaintext.buffer, plaintext.byteOffset, plaintext.byteLength);
-      const value = view.getBigUint64(0, true);
-      const ownerPk = bytesToBigintLE(plaintext.slice(8, 40));
-      const blinding = bytesToBigintLE(plaintext.slice(40, 72));
-      const assetId = BigInt(view.getUint32(72, true));
-      return { value, ownerPk, blinding, assetId };
-    } catch {
-      return null;
+  validate(bytes, context) {
+    if (bytes.length !== ENCRYPTED_MEMO_SIZE) {
+      const ctx = context ? ` (${context})` : "";
+      throw new Error(
+        `EncryptedMemo: invalid size${ctx} \u2014 expected ${ENCRYPTED_MEMO_SIZE} bytes, got ${bytes.length}`
+      );
     }
-  }
-};
-
-// src/shielded-pool/NoteBuilder.ts
-import { poseidon2, poseidon4 } from "poseidon-lite";
-var NoteBuilder = class {
+  },
   /**
-   * Build a ZkNote from the given inputs.
+   * Decrypt an on-chain EncryptedMemo using the recipient's viewing secret key.
+   * Returns null if decryption fails — wrong key, bad MAC, or malformed memo.
+   * Never throws; safe for scan loops.
    *
-   * @param input.value       Amount in planck (required).
-   * @param input.assetId     Asset ID — default 0n (native ORB-Privacy).
-   * @param input.ownerPk     BabyJubJub Ax — default 0n.
-   * @param input.blinding    Random scalar — defaults to BigInt(Date.now()).
-   * @param input.spendingKey Secret key for nullifier — default 0n.
+   * @param memoBytes        168-byte encrypted memo.
+   * @param commitment       32-byte note commitment (LE).
+   * @param viewingSecretKey 32-byte HKDF viewing secret key from deriveViewingSecretKey().
    */
-  static async build(input) {
-    const value = input.value;
-    const assetId = input.assetId ?? 0n;
-    const ownerPk = input.ownerPk ?? 0n;
-    const blinding = input.blinding ?? BigInt(Date.now());
-    const spendingKey = input.spendingKey ?? 0n;
-    const commitment = poseidon4([value, assetId, ownerPk, blinding]);
-    const nullifier = poseidon2([commitment, spendingKey]);
-    const commitmentBytes = bigintTo32Le(commitment);
-    const nullifierBytes = bigintTo32Le(nullifier);
-    const memo = input.viewingKey !== void 0 ? Array.from(
-      EncryptedMemo.encrypt(
-        value,
-        bigintTo32Le(ownerPk),
-        bigintTo32Le(blinding),
-        Number(assetId),
-        commitmentBytes,
-        input.viewingKey
-      )
-    ) : Array.from(EncryptedMemo.dummy());
-    const note = {
-      value,
-      assetId,
-      ownerPk,
-      blinding,
-      spendingKey,
-      spent: false,
-      spentAt: null,
-      commitment,
-      nullifier,
-      commitmentHex: toHex(commitmentBytes),
-      nullifierHex: toHex(nullifierBytes),
-      memo
-    };
-    return note;
-  }
+  decrypt(memoBytes, commitment, viewingSecretKey) {
+    if (memoBytes.length !== ENCRYPTED_MEMO_SIZE) return null;
+    return EncryptedMemo._decrypt(memoBytes, commitment, viewingSecretKey);
+  },
   /**
-   * Build the 104-byte encrypted memo for a note.
+   * Extract the ECDH shared secret from an encrypted memo using the recipient's viewing secret key.
    *
-   * Pure TypeScript implementation — no WASM dependency.
-   * Uses ChaCha20-Poly1305 with SHA-256 key derivation.
+   * Used by NoteDecryptor to obtain the shared secret needed for stealth address derivation
+   * without re-running the full decrypt path. Safe to call on any 168-byte memo.
    *
-   * @param note         The ZkNote whose fields populate the plaintext.
-   * @param recipientVk  32-byte recipient viewing key.
-   *                     Pass `new Uint8Array(32)` (default) for a public/dummy memo.
-   */
-  static buildMemo(note, recipientVk) {
-    return EncryptedMemo.encrypt(
-      note.value,
-      bigintTo32Le(note.ownerPk),
-      bigintTo32Le(note.blinding),
-      Number(note.assetId),
-      bigintTo32Le(note.commitment),
-      recipientVk ?? new Uint8Array(32)
-    );
-  }
-};
-
-// src/shielded-pool/ShieldedPoolModule.ts
-var ShieldedPoolModule = class {
-  constructor(substrate) {
-    this.substrate = substrate;
-  }
-  // ─── Extrinsics ────────────────────────────────────────────────────────────
-  /**
-   * Deposits tokens into the shielded pool.
-   * Extrinsic: shieldedPool.shield(assetId, amount, commitment, encryptedMemo)
-   */
-  async shield(params, signer) {
-    const memo = params.encryptedMemo ?? EncryptedMemo.dummy();
-    const entry = resolveTx(this.substrate.unsafe, "shieldedPool", "shield");
-    const tx = callUnsafeTx(
-      entry,
-      params.assetId,
-      params.amount.toString(),
-      Binary2.fromHex(params.commitment),
-      Binary2.fromBytes(memo)
-    );
-    return toTxResult(await tx.signAndSubmit(signer));
-  }
-  /**
-   * Build a ZkNote locally and submit shieldedPool.shield in one call.
-   *
-   * Returns both the on-chain result and the note — **save the note locally**,
-   * it cannot be recovered after the fact.
+   * Returns `new Uint8Array(32)` (all zeros) for public/dummy memos (zero ephPk).
+   * Returns `null` if the memo is malformed or the ephPk is not a valid BJJ point.
+   * Never throws; safe for scan loops.
    *
-   * @param params.value       Amount in planck (required).
-   * @param params.assetId     Asset ID — default 0 (native ORB-Privacy).
-   * @param params.ownerPk     BabyJubJub Ax (default 0n).
-   * @param params.blinding    Random blinding scalar (default BigInt(Date.now())).
-   * @param params.spendingKey Secret spending key (default 0n).
-   */
-  async buildAndShield(params, signer) {
-    const noteInput = {
-      value: params.value,
-      ...params.assetId !== void 0 && { assetId: BigInt(params.assetId) },
-      ...params.ownerPk !== void 0 && { ownerPk: params.ownerPk },
-      ...params.blinding !== void 0 && { blinding: params.blinding },
-      ...params.spendingKey !== void 0 && { spendingKey: params.spendingKey }
-    };
-    const note = await NoteBuilder.build(noteInput);
-    const memo = NoteBuilder.buildMemo(note);
-    const txResult = await this.shield(
-      {
-        assetId: Number(note.assetId),
-        amount: note.value,
-        commitment: note.commitmentHex,
-        encryptedMemo: memo
-      },
-      signer
-    );
-    return { txResult, note };
-  }
-  /**
-   * Withdraws tokens from the shielded pool to a public address.
-   * Extrinsic: shieldedPool.unshield(proof, merkleRoot, nullifier, assetId, amount, recipient)
-   */
-  async unshield(params, signer) {
-    const entry = resolveTx(this.substrate.unsafe, "shieldedPool", "unshield");
-    const tx = callUnsafeTx(
-      entry,
-      Binary2.fromBytes(params.proof),
-      Binary2.fromHex(params.merkleRoot),
-      Binary2.fromHex(params.nullifier),
-      params.assetId,
-      params.amount.toString(),
-      Binary2.fromHex(params.recipientAddress)
-    );
-    return toTxResult(await tx.signAndSubmit(signer));
-  }
-  /**
-   * Performs a private (shielded) transfer between two notes.
-   * Extrinsic: shieldedPool.privateTransfer(inputs, outputs, proof, merkleRoot)
-   */
-  async privateTransfer(params, signer) {
-    const inputs = params.inputs.map((inp) => ({
-      nullifier: Binary2.fromHex(inp.nullifier),
-      commitment: Binary2.fromHex(inp.commitment)
-    }));
-    const outputs = params.outputs.map((out) => ({
-      commitment: Binary2.fromHex(out.commitment),
-      memo: Binary2.fromBytes(out.encryptedMemo ?? EncryptedMemo.dummy())
-    }));
-    const entry = resolveTx(this.substrate.unsafe, "shieldedPool", "privateTransfer");
-    const tx = callUnsafeTx(
-      entry,
-      inputs,
-      outputs,
-      Binary2.fromBytes(params.proof),
-      Binary2.fromHex(params.merkleRoot)
-    );
-    return toTxResult(await tx.signAndSubmit(signer));
-  }
-  /**
-   * Deposits multiple notes into the shielded pool in a single extrinsic.
-   * Extrinsic: shieldedPool.shieldBatch(operations) — max 20 items.
+   * @param memoBytes        168-byte encrypted memo.
+   * @param viewingSecretKey 32-byte HKDF viewing secret key from deriveViewingSecretKey().
    */
-  async shieldBatch(params, signer) {
-    const operations = params.items.map((item) => ({
-      assetId: item.assetId,
-      amount: item.amount.toString(),
-      commitment: Binary2.fromHex(item.commitment),
-      encryptedMemo: Binary2.fromBytes(item.encryptedMemo ?? EncryptedMemo.dummy())
-    }));
-    const entry = resolveTx(this.substrate.unsafe, "shieldedPool", "shieldBatch");
-    const tx = callUnsafeTx(entry, operations);
-    return toTxResult(await tx.signAndSubmit(signer));
+  extractSharedSecret(memoBytes, viewingSecretKey) {
+    if (memoBytes.length !== ENCRYPTED_MEMO_SIZE) return null;
+    const ephPkPackedBytes = memoBytes.slice(NONCE_SIZE + CIPHERTEXT_SIZE);
+    const ephPkPackedBigint = bytesToBigintLE(ephPkPackedBytes);
+    if (ephPkPackedBigint === 0n) {
+      return new Uint8Array(32);
+    }
+    const ephPkPoint = unpackPoint(ephPkPackedBigint);
+    if (!ephPkPoint) return null;
+    const ivskScalar = bytesToBjjScalar(viewingSecretKey);
+    const sharedPoint = mulPointEscalar(ephPkPoint, ivskScalar);
+    return bigintTo32Le(sharedPoint[0]);
+  },
+  /** @internal */
+  _decrypt(memoBytes, commitment, viewingSecretKey) {
+    const nonce = memoBytes.slice(0, NONCE_SIZE);
+    const ciphertextWithMac = memoBytes.slice(NONCE_SIZE, NONCE_SIZE + CIPHERTEXT_SIZE);
+    const ephPkPackedBytes = memoBytes.slice(NONCE_SIZE + CIPHERTEXT_SIZE);
+    const ephPkPackedBigint = bytesToBigintLE(ephPkPackedBytes);
+    let sharedSecret;
+    if (ephPkPackedBigint === 0n) {
+      sharedSecret = new Uint8Array(32);
+    } else {
+      const ephPkPoint = unpackPoint(ephPkPackedBigint);
+      if (!ephPkPoint) return null;
+      const ivskScalar = bytesToBjjScalar(viewingSecretKey);
+      const sharedPoint = mulPointEscalar(ephPkPoint, ivskScalar);
+      sharedSecret = bigintTo32Le(sharedPoint[0]);
+    }
+    const encKey = deriveEncryptionKey(sharedSecret, commitment);
+    return parsePlaintext(nonce, ciphertextWithMac, encKey);
   }
 };
 
-// src/account-mapping/AccountMappingModule.ts
-import { Binary as Binary3 } from "polkadot-api";
-
 // src/utils/address.ts
 import { decodeAddress, encodeAddress } from "@polkadot/util-crypto";
 function normalizeEvmAddress(addr) {
@@ -1559,6 +1651,242 @@ function addressToAccountIdHex(addr) {
   return substrateSs58ToAccountIdHex(addr);
 }
 
+// src/shielded-pool/pallet/ShieldedPoolModule.ts
+var ShieldedPoolModule = class {
+  constructor(substrate) {
+    this.substrate = substrate;
+  }
+  substrate;
+  // ─── Extrinsics ────────────────────────────────────────────────────────────
+  /**
+   * Deposits tokens into the shielded pool.
+   * Extrinsic: shieldedPool.shield(assetId, amount, commitment, encryptedMemo)
+   *
+   * Shield is always a signed (public) transaction — the caller's address
+   * appears on-chain as the depositor.
+   */
+  async shield(params, signer, txOptions) {
+    EncryptedMemo.validate(params.encryptedMemo, "shield.encryptedMemo");
+    const entry = resolveTx(this.substrate.unsafe, "ShieldedPool", "shield");
+    const tx = callUnsafeTx(entry, {
+      asset_id: params.assetId,
+      amount: params.amount,
+      commitment: Binary2.fromHex(params.commitment),
+      encrypted_memo: Binary2.fromBytes(params.encryptedMemo)
+    });
+    return toTxResult(
+      await (txOptions !== void 0 ? tx.signAndSubmit(signer, txOptions) : tx.signAndSubmit(signer))
+    );
+  }
+  /**
+   * Withdraws tokens from the shielded pool to a public address.
+   * Submits as an UNSIGNED (gasless) transaction — fee is embedded in the ZK proof.
+   * Pass a `signer` to fall back to signed submission (e.g. for testing).
+   * Extrinsic: shieldedPool.unshield(proof, merkleRoot, nullifier, assetId, amount, recipient, fee)
+   */
+  async unshield(params, signer, txOptions) {
+    const entry = resolveTx(this.substrate.unsafe, "ShieldedPool", "unshield");
+    const recipientSs58 = accountIdHexToSs58(params.recipientAddress);
+    if (!recipientSs58) throw new Error(`Invalid recipientAddress: ${params.recipientAddress}`);
+    const changeCommitment = params.changeCommitment ?? "0x" + "00".repeat(32);
+    let changeEncryptedMemo;
+    if (params.changeEncryptedMemo && params.changeEncryptedMemo.length > 0) {
+      EncryptedMemo.validate(params.changeEncryptedMemo, "changeEncryptedMemo");
+      changeEncryptedMemo = Binary2.fromBytes(params.changeEncryptedMemo);
+    } else {
+      changeEncryptedMemo = Binary2.fromBytes(new Uint8Array(0));
+    }
+    const tx = callUnsafeTx(entry, {
+      proof: Binary2.fromBytes(params.proof),
+      merkle_root: Binary2.fromHex(params.merkleRoot),
+      nullifier: Binary2.fromHex(params.nullifier),
+      asset_id: params.assetId,
+      amount: params.amount,
+      recipient: recipientSs58,
+      fee: params.fee ?? 0n,
+      change_commitment: Binary2.fromHex(changeCommitment),
+      change_encrypted_memo: changeEncryptedMemo,
+      relayer: void 0
+      // Option<H160> — None for direct Substrate submissions
+    });
+    if (signer) {
+      return toTxResult(
+        await (txOptions !== void 0 ? tx.signAndSubmit(signer, txOptions) : tx.signAndSubmit(signer))
+      );
+    }
+    return submitBareTx(tx, this.substrate);
+  }
+  /**
+   * Performs a private (shielded) transfer between two notes.
+   * Submits as an UNSIGNED (gasless) transaction — fee is embedded in the ZK proof.
+   * Pass a `signer` to fall back to signed submission (e.g. for testing).
+   * Extrinsic: shieldedPool.privateTransfer(proof, merkleRoot, nullifiers, commitments, memos, assetId, fee)
+   */
+  async privateTransfer(params, signer, txOptions) {
+    const nullifiers = params.inputs.map((inp) => Binary2.fromHex(inp.nullifier));
+    const commitments = params.outputs.map((out) => Binary2.fromHex(out.commitment));
+    const memos = params.outputs.map((out, i) => {
+      EncryptedMemo.validate(
+        out.encryptedMemo,
+        `privateTransfer.outputs[${i}].encryptedMemo`
+      );
+      return Binary2.fromBytes(out.encryptedMemo);
+    });
+    const entry = resolveTx(this.substrate.unsafe, "ShieldedPool", "private_transfer");
+    const tx = callUnsafeTx(entry, {
+      proof: Binary2.fromBytes(params.proof),
+      merkle_root: Binary2.fromHex(params.merkleRoot),
+      nullifiers,
+      commitments,
+      encrypted_memos: memos,
+      asset_id: params.assetId,
+      fee: params.fee ?? 0n,
+      relayer: void 0
+      // Option<H160> — None for direct Substrate submissions
+    });
+    if (signer) {
+      return toTxResult(
+        await (txOptions !== void 0 ? tx.signAndSubmit(signer, txOptions) : tx.signAndSubmit(signer))
+      );
+    }
+    return submitBareTx(tx, this.substrate);
+  }
+  /**
+   * Deposits multiple notes into the shielded pool in a single extrinsic.
+   * Extrinsic: shieldedPool.shieldBatch(operations) — max 20 items.
+   */
+  async shieldBatch(params, signer, txOptions) {
+    const operations = params.items.map((item, i) => {
+      EncryptedMemo.validate(item.encryptedMemo, `shieldBatch.items[${i}].encryptedMemo`);
+      return {
+        assetId: item.assetId,
+        amount: item.amount.toString(),
+        commitment: Binary2.fromHex(item.commitment),
+        encryptedMemo: Binary2.fromBytes(item.encryptedMemo)
+      };
+    });
+    const entry = resolveTx(this.substrate.unsafe, "ShieldedPool", "shield_batch");
+    const tx = callUnsafeTx(entry, operations);
+    return toTxResult(
+      await (txOptions !== void 0 ? tx.signAndSubmit(signer, txOptions) : tx.signAndSubmit(signer))
+    );
+  }
+  /**
+   * Claims accrued relay fees into the shielded pool.
+   * This is a SIGNED transaction — the relayer must sign it with their wallet.
+   * Before calling this, generate a ZK disclosure proof with generateFeeClaimProof().
+   *
+   * Extrinsic: shieldedPool.claim_shielded_fees(commitment, amount, asset_id, memo, proof, public_signals)
+   */
+  async claimShieldedFees(params, signer, txOptions) {
+    EncryptedMemo.validate(params.encryptedMemo, "claimShieldedFees.encryptedMemo");
+    const entry = resolveTx(this.substrate.unsafe, "ShieldedPool", "claim_shielded_fees");
+    const tx = callUnsafeTx(entry, {
+      commitment: Binary2.fromHex(params.commitment),
+      amount: params.amount,
+      asset_id: params.assetId,
+      encrypted_memo: Binary2.fromBytes(params.encryptedMemo),
+      proof: Binary2.fromBytes(params.proof),
+      public_signals: Binary2.fromBytes(params.publicSignals)
+    });
+    return toTxResult(
+      await (txOptions !== void 0 ? tx.signAndSubmit(signer, txOptions) : tx.signAndSubmit(signer))
+    );
+  }
+  // ─── Selective Disclosure ──────────────────────────────────────────────────
+  /**
+   * Requests a selective disclosure from a target account for a specific commitment.
+   * The auditor's Baby Jubjub public key is included so the note owner knows
+   * which key to encrypt to when generating the proof.
+   * Extrinsic: shieldedPool.request_disclosure(target, commitment, required_fields,
+   *                                             reason, auditor_bjj_pk_x, auditor_bjj_pk_y)
+   */
+  async requestDisclosure(params, signer, txOptions) {
+    const entry = resolveTx(this.substrate.unsafe, "ShieldedPool", "request_disclosure");
+    const tx = callUnsafeTx(entry, {
+      target: params.target,
+      commitment: Binary2.fromBytes(new Uint8Array(params.commitment)),
+      required_fields: {
+        value: params.requiredFields.value,
+        asset_id: params.requiredFields.assetId,
+        owner: params.requiredFields.owner
+      },
+      reason: Binary2.fromText(params.reason),
+      auditor_bjj_pk_x: Binary2.fromBytes(new Uint8Array(params.auditorBjjPkX)),
+      auditor_bjj_pk_y: Binary2.fromBytes(new Uint8Array(params.auditorBjjPkY))
+    });
+    return toTxResult(
+      await (txOptions !== void 0 ? tx.signAndSubmit(signer, txOptions) : tx.signAndSubmit(signer))
+    );
+  }
+  /**
+   * Submits a Groth16 ZK disclosure proof for a note commitment.
+   * The proof reveals the selected fields (value, asset_id, owner_hash) on-chain.
+   * Use generateDisclosureProof() + buildDisclosurePublicSignals() before calling this.
+   * Extrinsic: shieldedPool.disclose(commitment, proof_bytes, public_signals, auditor)
+   */
+  async disclose(params, signer, txOptions) {
+    const entry = resolveTx(this.substrate.unsafe, "ShieldedPool", "disclose");
+    const tx = callUnsafeTx(entry, {
+      commitment: Binary2.fromBytes(new Uint8Array(params.commitment)),
+      proof_bytes: Binary2.fromBytes(new Uint8Array(params.proofBytes)),
+      public_signals: Binary2.fromBytes(new Uint8Array(params.publicSignals)),
+      auditor: params.auditor
+    });
+    return toTxResult(
+      await (txOptions !== void 0 ? tx.signAndSubmit(signer, txOptions) : tx.signAndSubmit(signer))
+    );
+  }
+  /**
+   * Rejects a pending disclosure request from an auditor for a specific commitment.
+   * Extrinsic: shieldedPool.reject_disclosure(auditor, commitment, reason)
+   */
+  async rejectDisclosure(params, signer, txOptions) {
+    const entry = resolveTx(this.substrate.unsafe, "ShieldedPool", "reject_disclosure");
+    const tx = callUnsafeTx(entry, {
+      auditor: params.auditor,
+      commitment: Binary2.fromBytes(new Uint8Array(params.commitment)),
+      reason: Binary2.fromText(params.reason)
+    });
+    return toTxResult(
+      await (txOptions !== void 0 ? tx.signAndSubmit(signer, txOptions) : tx.signAndSubmit(signer))
+    );
+  }
+  /**
+   * Cleans up a disclosure request that has passed its expiration block.
+   * Permissionless — any account can prune expired requests.
+   * Extrinsic: shieldedPool.prune_expired_request(target, auditor, commitment)
+   */
+  async pruneExpiredRequest(params, signer, txOptions) {
+    const entry = resolveTx(this.substrate.unsafe, "ShieldedPool", "prune_expired_request");
+    const tx = callUnsafeTx(entry, {
+      target: params.target,
+      auditor: params.auditor,
+      commitment: Binary2.fromBytes(new Uint8Array(params.commitment))
+    });
+    return toTxResult(
+      await (txOptions !== void 0 ? tx.signAndSubmit(signer, txOptions) : tx.signAndSubmit(signer))
+    );
+  }
+  /**
+   * Revokes a previously submitted voluntary disclosure record.
+   * Only applies to self-disclosures (auditor = None). Auditor-requested records are permanent.
+   * Extrinsic: shieldedPool.revoke_disclosure_record(commitment)
+   */
+  async revokeDisclosureRecord(params, signer, txOptions) {
+    const entry = resolveTx(this.substrate.unsafe, "ShieldedPool", "revoke_disclosure_record");
+    const tx = callUnsafeTx(entry, {
+      commitment: Binary2.fromBytes(new Uint8Array(params.commitment))
+    });
+    return toTxResult(
+      await (txOptions !== void 0 ? tx.signAndSubmit(signer, txOptions) : tx.signAndSubmit(signer))
+    );
+  }
+};
+
+// src/account-mapping/AccountMappingModule.ts
+import { Binary as Binary3 } from "polkadot-api";
+
 // src/account-mapping/helpers.ts
 function mapRawScheme(raw) {
   if (raw === "Eip191" || raw === "eip191") return "Eip191";
@@ -1571,6 +1899,7 @@ var AccountMappingModule = class {
   constructor(substrate) {
     this.substrate = substrate;
   }
+  substrate;
   // ─── Address resolution ─────────────────────────────────────────────────────
   /**
    * Returns the explicitly mapped (or fallback) Substrate AccountId32 hex for
@@ -1956,6 +2285,7 @@ var PrivacyModule = class {
   constructor(substrate) {
     this.substrate = substrate;
   }
+  substrate;
   /** Returns the current Merkle tree root. */
   async getMerkleRoot() {
     return this.substrate.request("privacy_getMerkleRoot", []);
@@ -1973,14 +2303,23 @@ var PrivacyModule = class {
   }
   /**
    * Returns the Merkle inclusion proof for a given commitment hex,
-   * bundled with the current Merkle root.
+   * bundled with the Merkle root.
+   *
+   * Uses `privacy_getMerkleProofByCommitment` which resolves root and proof
+   * under the **same block hash**, guaranteeing that the returned path is
+   * consistent with the returned root.
    */
   async getMerkleProofByCommitment(commitmentHex) {
-    const [proof, root] = await Promise.all([
-      this.getMerkleProof(commitmentHex),
-      this.getMerkleRoot()
-    ]);
-    return { ...proof, root };
+    const raw = await this.substrate.request(
+      "privacy_getMerkleProofByCommitment",
+      [commitmentHex]
+    );
+    return {
+      path: raw.path,
+      leafIndex: raw.leaf_index,
+      treeDepth: raw.tree_depth,
+      root: raw.root
+    };
   }
   /** Returns the spend status of a nullifier. */
   async getNullifierStatus(nullifier) {
@@ -1999,6 +2338,7 @@ var PrivacyModule = class {
     return {
       merkleRoot: raw.merkle_root,
       commitmentCount: raw.commitment_count,
+      nullifierCount: raw.nullifier_count,
       totalBalance: raw.total_balance.toString(),
       assetBalances: raw.asset_balances.map(mapAssetBalance),
       treeDepth: raw.tree_depth
@@ -2024,6 +2364,7 @@ var ZkVerifierModule = class {
   constructor(substrate) {
     this.substrate = substrate;
   }
+  substrate;
   /** Returns basic version info for all registered circuits. */
   async getAllCircuitVersions() {
     const raw = await this.substrate.request(
@@ -2042,6 +2383,48 @@ var ZkVerifierModule = class {
   }
 };
 
+// src/relayer/RelayerStatusModule.ts
+var RelayerStatusModule = class {
+  constructor(substrate) {
+    this.substrate = substrate;
+  }
+  substrate;
+  /**
+   * Returns true if the given SS58 address is a registered relayer.
+   */
+  async isRelayer(ss58Address) {
+    return this.substrate.request("relayer_isRelayer", [ss58Address]);
+  }
+  /**
+   * Returns the pending fees (in planck) for the given account and asset.
+   * The node returns the value as a decimal string to avoid u128 overflow.
+   */
+  async pendingFees(ss58Address, assetId) {
+    const raw = await this.substrate.request("relayer_pendingFees", [
+      ss58Address,
+      assetId
+    ]);
+    return BigInt(raw);
+  }
+  /**
+   * Returns the registered EVM address (0x-prefixed) for the given account,
+   * or null if the account is not a registered relayer.
+   */
+  async registeredEvmAddress(ss58Address) {
+    return this.substrate.request("relayer_registeredEvmAddress", [ss58Address]);
+  }
+  /**
+   * Convenience method: returns relayer registry info for an account.
+   */
+  async getRelayerInfo(ss58Address) {
+    const [isRelayer, evmAddress] = await Promise.all([
+      this.isRelayer(ss58Address),
+      this.registeredEvmAddress(ss58Address)
+    ]);
+    return { isRelayer, evmAddress };
+  }
+};
+
 // src/precompiles/helpers.ts
 var STATIC_TYPES = /* @__PURE__ */ new Set(["uint", "bytes32", "address", "bool"]);
 function concat(arrays) {
@@ -2185,10 +2568,6 @@ function decodeBytes(data, slotOffset = 0) {
 function decodeString(data, slotOffset = 0) {
   return new TextDecoder().decode(decodeBytes(data, slotOffset));
 }
-function hexToBytes(hex) {
-  if (hex === "0x" || hex === "") return new Uint8Array(0);
-  return fromHex(hex.startsWith("0x") ? hex : "0x" + hex);
-}
 
 // src/precompiles/addresses.ts
 var PRECOMPILE_ADDR = {
@@ -2247,12 +2626,20 @@ var AM_SEL = {
   SET_ACCOUNT_METADATA: new Uint8Array([119, 108, 249, 255])
 };
 var SP_SEL = {
-  // shield(uint32,uint256,bytes32,bytes)                                  → 0x781442b9
-  SHIELD: new Uint8Array([120, 20, 66, 185]),
-  // privateTransfer(bytes,bytes32,bytes32[],bytes32[],bytes[])            → 0xdcd5b898
-  PRIVATE_TRANSFER: new Uint8Array([220, 213, 184, 152]),
-  // unshield(bytes,bytes32,bytes32,uint32,uint256,bytes32)                → 0xdcf1bff2
-  UNSHIELD: new Uint8Array([220, 241, 191, 242])
+  // shield(uint32,bytes32,bytes)                                               → 0x9feb22ea  (payable, amount = msg.value)
+  SHIELD: new Uint8Array([159, 235, 34, 234]),
+  // privateTransfer(bytes,bytes32,bytes32[],bytes32[],bytes[],uint32,uint256)    → 0x8c0f5d24
+  PRIVATE_TRANSFER: new Uint8Array([140, 15, 93, 36]),
+  // unshield(bytes,bytes32,bytes32,uint32,uint256,bytes32,uint256,bytes32)               → 0xd21d9a79
+  UNSHIELD: new Uint8Array([210, 29, 154, 121]),
+  // requestDisclosure(bytes32,bytes32,bool,bool,bool,bytes,bytes32,bytes32)      → 0xe7022933  (caller = auditor)
+  REQUEST_DISCLOSURE: new Uint8Array([231, 2, 41, 51]),
+  // disclose(bytes32,bytes,bytes,bytes32)                                        → 0xea8a4165  (caller = note owner)
+  DISCLOSE: new Uint8Array([234, 138, 65, 101]),
+  // rejectDisclosure(bytes32,bytes32,bytes)                                      → 0x72b895a9  (caller = target)
+  REJECT_DISCLOSURE: new Uint8Array([114, 184, 149, 169]),
+  // pruneExpiredRequest(bytes32,bytes32,bytes32)                                 → 0x0c338dcf  (permissionless)
+  PRUNE_EXPIRED_REQUEST: new Uint8Array([12, 51, 141, 207])
 };
 var KNOWN_PRECOMPILES = {
   // ── Ethereum standard (EIP) ─────────────────────────────────────────────
@@ -2295,9 +2682,13 @@ var KNOWN_PRECOMPILES = {
   "0x0000000000000000000000000000000000000801": {
     name: "ShieldedPool",
     functions: {
-      "781442b9": "shield(uint32,uint256,bytes32,bytes)",
-      dcd5b898: "privateTransfer(bytes,bytes32,bytes32[],bytes32[],bytes[])",
-      dcf1bff2: "unshield(bytes,bytes32,bytes32,uint32,uint256,bytes32)"
+      "9feb22ea": "shield(uint32,bytes32,bytes)",
+      "8c0f5d24": "privateTransfer(bytes,bytes32,bytes32[],bytes32[],bytes[],uint32,uint256)",
+      d21d9a79: "unshield(bytes,bytes32,bytes32,uint32,uint256,bytes32,uint256,bytes32)",
+      e7022933: "requestDisclosure(bytes32,bytes32,bool,bool,bool,bytes,bytes32,bytes32)",
+      ea8a4165: "disclose(bytes32,bytes,bytes,bytes32)",
+      "72b895a9": "rejectDisclosure(bytes32,bytes32,bytes)",
+      "0c338dcf": "pruneExpiredRequest(bytes32,bytes32,bytes32)"
     }
   }
 };
@@ -2311,43 +2702,58 @@ var ShieldedPoolPrecompile = class {
   constructor(evm) {
     this.evm = evm;
   }
+  evm;
   addr = PRECOMPILE_ADDR.SHIELDED_POOL;
   // ─── shield ────────────────────────────────────────────────────────────────
   /**
-   * Returns the ABI-encoded calldata for `shield(uint32, uint256, bytes32, bytes)`.
-   * Useful when you need to inspect or batch the calldata before sending.
+   * Returns the ABI-encoded calldata for `shield(uint32, bytes32, bytes)`.
+   * The token amount must be sent as `msg.value` (the `value` field of the EVM
+   * transaction) — this is what MetaMask and other wallets display to the user.
    */
   buildShieldCalldata(params) {
-    const memo = params.encryptedMemo ?? EncryptedMemo.dummy();
+    EncryptedMemo.validate(params.encryptedMemo, "buildShieldCalldata.encryptedMemo");
     const commitment = fromHex(params.commitment);
     return encodeHex(
       SP_SEL.SHIELD,
       { type: "uint", value: BigInt(params.assetId) },
-      { type: "uint", value: params.amount },
       { type: "bytes32", value: commitment },
-      { type: "bytes", value: memo }
+      { type: "bytes", value: params.encryptedMemo }
     );
   }
   /**
-   * Deposits tokens into the shielded pool from an EVM transaction.
+   * Deposits tokens into the shielded pool from a payable EVM transaction.
    *
-   * The EVM caller's address is deterministically mapped to a Substrate
-   * AccountId32 (`H160 ++ [0x00; 12]`). The pool deducts from that account.
+   * The token amount is sent as `msg.value` so EVM wallets (MetaMask, etc.) display
+   * the correct amount on the confirmation screen. The precompile dispatches
+   * `shieldedPool.shield` with its own address as origin, so the funds flow:
+   *   caller → precompile (via msg.value, handled by EVM)
+   *   precompile → pool (via pallet transfer)
+   * This avoids double-deduction while keeping the displayed amount accurate.
    *
    * Extrinsic: `shieldedPool.shield(assetId, amount, commitment, encryptedMemo)`
    */
   async shield(params, signer) {
-    return signer({ to: this.addr, data: this.buildShieldCalldata(params) });
+    return signer({
+      to: this.addr,
+      data: this.buildShieldCalldata(params),
+      value: params.amount
+    });
   }
   // ─── privateTransfer ───────────────────────────────────────────────────────
   /**
    * Returns the ABI-encoded calldata for
-   * `privateTransfer(bytes, bytes32, bytes32[], bytes32[], bytes[])`.
+   * `privateTransfer(bytes, bytes32, bytes32[], bytes32[], bytes[], uint32, uint256)`.
    */
   buildPrivateTransferCalldata(params) {
     const nullifiers = params.inputs.map((i) => fromHex(i.nullifier));
     const commitments = params.outputs.map((o) => fromHex(o.commitment));
-    const memos = params.outputs.map((o) => o.encryptedMemo ?? EncryptedMemo.dummy());
+    const memos = params.outputs.map((o, i) => {
+      EncryptedMemo.validate(
+        o.encryptedMemo,
+        `buildPrivateTransferCalldata.outputs[${i}].encryptedMemo`
+      );
+      return o.encryptedMemo;
+    });
     const root = fromHex(params.merkleRoot);
     return encodeHex(
       SP_SEL.PRIVATE_TRANSFER,
@@ -2355,7 +2761,9 @@ var ShieldedPoolPrecompile = class {
       { type: "bytes32", value: root },
       { type: "bytes32[]", value: nullifiers },
       { type: "bytes32[]", value: commitments },
-      { type: "bytes[]", value: memos }
+      { type: "bytes[]", value: memos },
+      { type: "uint", value: BigInt(params.assetId) },
+      { type: "uint", value: params.fee ?? 0n }
     );
   }
   /**
@@ -2383,6 +2791,9 @@ var ShieldedPoolPrecompile = class {
     const recipientBytes = fromHex(
       "0x" + (recipientRaw.length === 64 ? recipientRaw : recipientRaw.padEnd(64, "0"))
     );
+    const changeCommitmentHex = params.changeCommitment ?? "0x" + "00".repeat(32);
+    const changeCommitment = fromHex(changeCommitmentHex);
+    const changeEncryptedMemo = params.changeEncryptedMemo ?? new Uint8Array();
     return encodeHex(
       SP_SEL.UNSHIELD,
       { type: "bytes", value: proof },
@@ -2390,7 +2801,10 @@ var ShieldedPoolPrecompile = class {
       { type: "bytes32", value: nullifier },
       { type: "uint", value: BigInt(params.assetId) },
       { type: "uint", value: params.amount },
-      { type: "bytes32", value: recipientBytes }
+      { type: "bytes32", value: recipientBytes },
+      { type: "uint", value: params.fee ?? 0n },
+      { type: "bytes32", value: changeCommitment },
+      { type: "bytes", value: changeEncryptedMemo }
     );
   }
   /**
@@ -2418,24 +2832,151 @@ var ShieldedPoolPrecompile = class {
     });
   }
   /**
-   * Estimates the EVM gas for a `privateTransfer` call.
+   * Estimates the EVM gas for a `privateTransfer` call.
+   */
+  async estimatePrivateTransferGas(params, from) {
+    return this.evm.estimateGas({
+      from,
+      to: this.addr,
+      data: this.buildPrivateTransferCalldata(params)
+    });
+  }
+  /**
+   * Estimates the EVM gas for an `unshield` call.
+   */
+  async estimateUnshieldGas(params, from) {
+    return this.evm.estimateGas({
+      from,
+      to: this.addr,
+      data: this.buildUnshieldCalldata(params)
+    });
+  }
+  // ─── requestDisclosure ─────────────────────────────────────────────────────
+  /**
+   * Returns the ABI-encoded calldata for
+   * `requestDisclosure(bytes32,bytes32,bool,bool,bool,bytes,bytes32,bytes32)`.
+   *
+   * The **EVM caller** of the resulting transaction is treated as the **auditor**
+   * on-chain. No explicit auditor argument is needed.
+   */
+  buildRequestDisclosureCalldata(params) {
+    if (params.auditorBjjPkX.length !== 32)
+      throw new RangeError("requestDisclosure: auditorBjjPkX must be 32 bytes");
+    if (params.auditorBjjPkY.length !== 32)
+      throw new RangeError("requestDisclosure: auditorBjjPkY must be 32 bytes");
+    const target = fromHex(params.target);
+    const commitment = fromHex(params.commitment);
+    const reasonBytes = new TextEncoder().encode(params.reason);
+    return encodeHex(
+      SP_SEL.REQUEST_DISCLOSURE,
+      { type: "bytes32", value: target },
+      { type: "bytes32", value: commitment },
+      { type: "bool", value: params.disclosedValue },
+      { type: "bool", value: params.disclosedAssetId },
+      { type: "bool", value: params.disclosedOwner },
+      { type: "bytes", value: reasonBytes },
+      { type: "bytes32", value: params.auditorBjjPkX },
+      { type: "bytes32", value: params.auditorBjjPkY }
+    );
+  }
+  /**
+   * Requests selective disclosure of a specific commitment.
+   *
+   * The EVM caller is recorded as the auditor on-chain. The note owner can
+   * respond with `disclose()` or reject with `rejectDisclosure()`.
+   *
+   * Extrinsic: `shieldedPool.requestDisclosure(target, commitment, requiredFields, reason, bjjPkX, bjjPkY)`
+   */
+  async requestDisclosure(params, signer) {
+    return signer({ to: this.addr, data: this.buildRequestDisclosureCalldata(params) });
+  }
+  // ─── disclose ──────────────────────────────────────────────────────────────
+  /**
+   * Returns the ABI-encoded calldata for `disclose(bytes32,bytes,bytes,bytes32)`.
+   *
+   * The **EVM caller** is treated as the **note owner** on-chain.
+   * `params.proofBytes` must be exactly 128 bytes; `params.publicSignals` exactly 256 bytes.
+   */
+  buildDiscloseCalldata(params) {
+    if (params.proofBytes.length !== 128)
+      throw new RangeError("disclose: proofBytes must be exactly 128 bytes");
+    if (params.publicSignals.length !== 256)
+      throw new RangeError("disclose: publicSignals must be exactly 256 bytes");
+    const commitment = fromHex(params.commitment);
+    const auditor = fromHex(params.auditor);
+    return encodeHex(
+      SP_SEL.DISCLOSE,
+      { type: "bytes32", value: commitment },
+      { type: "bytes", value: params.proofBytes },
+      { type: "bytes", value: params.publicSignals },
+      { type: "bytes32", value: auditor }
+    );
+  }
+  /**
+   * Submits a selective disclosure proof for a commitment.
+   *
+   * The EVM caller is treated as the note owner on-chain. The Groth16 proof is
+   * verified by the runtime; on success the encrypted signals are stored for
+   * the auditor to decrypt off-chain.
+   *
+   * Extrinsic: `shieldedPool.disclose(commitment, proofBytes, publicSignals, auditor)`
+   */
+  async disclose(params, signer) {
+    return signer({ to: this.addr, data: this.buildDiscloseCalldata(params) });
+  }
+  // ─── rejectDisclosure ──────────────────────────────────────────────────────
+  /**
+   * Returns the ABI-encoded calldata for `rejectDisclosure(bytes32,bytes32,bytes)`.
+   *
+   * The **EVM caller** is treated as the **target** (note owner) on-chain.
+   */
+  buildRejectDisclosureCalldata(params) {
+    const auditor = fromHex(params.auditor);
+    const commitment = fromHex(params.commitment);
+    const reasonBytes = new TextEncoder().encode(params.reason);
+    return encodeHex(
+      SP_SEL.REJECT_DISCLOSURE,
+      { type: "bytes32", value: auditor },
+      { type: "bytes32", value: commitment },
+      { type: "bytes", value: reasonBytes }
+    );
+  }
+  /**
+   * Rejects a pending disclosure request.
+   *
+   * The EVM caller is treated as the note owner (target) on-chain.
+   *
+   * Extrinsic: `shieldedPool.rejectDisclosure(auditor, commitment, reason)`
+   */
+  async rejectDisclosure(params, signer) {
+    return signer({ to: this.addr, data: this.buildRejectDisclosureCalldata(params) });
+  }
+  // ─── pruneExpiredRequest ───────────────────────────────────────────────────
+  /**
+   * Returns the ABI-encoded calldata for `pruneExpiredRequest(bytes32,bytes32,bytes32)`.
+   *
+   * Permissionless: any EVM caller can prune an expired request.
    */
-  async estimatePrivateTransferGas(params, from) {
-    return this.evm.estimateGas({
-      from,
-      to: this.addr,
-      data: this.buildPrivateTransferCalldata(params)
-    });
+  buildPruneExpiredRequestCalldata(params) {
+    const target = fromHex(params.target);
+    const auditor = fromHex(params.auditor);
+    const commitment = fromHex(params.commitment);
+    return encodeHex(
+      SP_SEL.PRUNE_EXPIRED_REQUEST,
+      { type: "bytes32", value: target },
+      { type: "bytes32", value: auditor },
+      { type: "bytes32", value: commitment }
+    );
   }
   /**
-   * Estimates the EVM gas for an `unshield` call.
+   * Removes an expired disclosure request from storage.
+   *
+   * Permissionless: any EVM account can call this once `expires_at` has passed.
+   *
+   * Extrinsic: `shieldedPool.pruneExpiredRequest(target, auditor, commitment)`
    */
-  async estimateUnshieldGas(params, from) {
-    return this.evm.estimateGas({
-      from,
-      to: this.addr,
-      data: this.buildUnshieldCalldata(params)
-    });
+  async pruneExpiredRequest(params, signer) {
+    return signer({ to: this.addr, data: this.buildPruneExpiredRequestCalldata(params) });
   }
 };
 
@@ -2444,6 +2985,7 @@ var AccountMappingPrecompile = class {
   constructor(evm) {
     this.evm = evm;
   }
+  evm;
   addr = PRECOMPILE_ADDR.ACCOUNT_MAPPING;
   // ─── Read-only ─────────────────────────────────────────────────────────────
   /**
@@ -2455,7 +2997,7 @@ var AccountMappingPrecompile = class {
   async resolveAlias(alias) {
     try {
       const data = encodeHex(AM_SEL.RESOLVE_ALIAS, { type: "string", value: alias });
-      const raw = hexToBytes(await this.evm.call(this.addr, data));
+      const raw = fromHex(await this.evm.call(this.addr, data));
       if (raw.length < 64) return null;
       const owner = decodeAddress2(raw, 0);
       const evm = decodeAddress2(raw, 32);
@@ -2478,7 +3020,7 @@ var AccountMappingPrecompile = class {
         type: "address",
         value: normalizeEvmAddress(evmAddress)
       });
-      const raw = hexToBytes(await this.evm.call(this.addr, data));
+      const raw = fromHex(await this.evm.call(this.addr, data));
       if (raw.length === 0) return null;
       const alias = decodeString(raw, 0);
       return alias.length > 0 ? alias : null;
@@ -2498,7 +3040,7 @@ var AccountMappingPrecompile = class {
         { type: "string", value: alias },
         { type: "bytes32", value: commitmentBytes }
       );
-      const raw = hexToBytes(await this.evm.call(this.addr, data));
+      const raw = fromHex(await this.evm.call(this.addr, data));
       if (raw.length < 32) return false;
       return decodeBool(raw, 0);
     } catch {
@@ -2703,6 +3245,7 @@ var CryptoPrecompiles = class {
   constructor(evm) {
     this.evm = evm;
   }
+  evm;
   // ─── ECRecover (0x0001) ───────────────────────────────────────────────────
   /**
    * Recovers the Ethereum address from an ECDSA signature.
@@ -2718,7 +3261,7 @@ var CryptoPrecompiles = class {
     input[63] = v;
     input.set(r.slice(0, 32), 64);
     input.set(s.slice(0, 32), 96);
-    const raw = hexToBytes(await this.evm.call(PRECOMPILE_ADDR.EC_RECOVER, toHex(input)));
+    const raw = fromHex(await this.evm.call(PRECOMPILE_ADDR.EC_RECOVER, toHex(input)));
     if (raw.length < 32) return "0x" + "00".repeat(20);
     return "0x" + toHex(raw.slice(12, 32)).slice(2);
   }
@@ -2734,7 +3277,7 @@ var CryptoPrecompiles = class {
     input[63] = v;
     input.set(r.slice(0, 32), 64);
     input.set(s.slice(0, 32), 96);
-    return hexToBytes(await this.evm.call(PRECOMPILE_ADDR.EC_RECOVER_PUBKEY, toHex(input)));
+    return fromHex(await this.evm.call(PRECOMPILE_ADDR.EC_RECOVER_PUBKEY, toHex(input)));
   }
   // ─── SHA-256 (0x0002) ─────────────────────────────────────────────────────
   /**
@@ -2742,7 +3285,7 @@ var CryptoPrecompiles = class {
    * Returns a 32-byte digest.
    */
   async sha256(data) {
-    return hexToBytes(await this.evm.call(PRECOMPILE_ADDR.SHA256, toHex(data)));
+    return fromHex(await this.evm.call(PRECOMPILE_ADDR.SHA256, toHex(data)));
   }
   // ─── RIPEMD-160 (0x0003) ──────────────────────────────────────────────────
   /**
@@ -2750,7 +3293,7 @@ var CryptoPrecompiles = class {
    * Returns the 20-byte digest right-padded to 32 bytes (standard ABI output).
    */
   async ripemd160(data) {
-    const raw = hexToBytes(await this.evm.call(PRECOMPILE_ADDR.RIPEMD160, toHex(data)));
+    const raw = fromHex(await this.evm.call(PRECOMPILE_ADDR.RIPEMD160, toHex(data)));
     return raw.length >= 32 ? raw.slice(12, 32) : raw;
   }
   // ─── Identity (0x0004) ────────────────────────────────────────────────────
@@ -2759,7 +3302,7 @@ var CryptoPrecompiles = class {
    * Mainly useful for gas benchmarking.
    */
   async identity(data) {
-    return hexToBytes(await this.evm.call(PRECOMPILE_ADDR.IDENTITY, toHex(data)));
+    return fromHex(await this.evm.call(PRECOMPILE_ADDR.IDENTITY, toHex(data)));
   }
   // ─── SHA3-FIPS-256 / Keccak-256 (0x0400) ─────────────────────────────────
   /**
@@ -2767,7 +3310,7 @@ var CryptoPrecompiles = class {
    * Returns a 32-byte digest.
    */
   async keccak256(data) {
-    return hexToBytes(await this.evm.call(PRECOMPILE_ADDR.SHA3_FIPS256, toHex(data)));
+    return fromHex(await this.evm.call(PRECOMPILE_ADDR.SHA3_FIPS256, toHex(data)));
   }
   // ─── Curve25519 / Ristretto (0x0402, 0x0403) ─────────────────────────────
   /**
@@ -2790,7 +3333,7 @@ var CryptoPrecompiles = class {
       }
       input.set(pt, i * 32);
     }
-    return hexToBytes(await this.evm.call(PRECOMPILE_ADDR.CURVE25519_ADD, toHex(input)));
+    return fromHex(await this.evm.call(PRECOMPILE_ADDR.CURVE25519_ADD, toHex(input)));
   }
   /**
    * Multiplies a Ristretto compressed point by a scalar via EVM precompile.
@@ -2806,39 +3349,44 @@ var CryptoPrecompiles = class {
     const input = new Uint8Array(64);
     input.set(scalar, 0);
     input.set(point, 32);
-    return hexToBytes(await this.evm.call(PRECOMPILE_ADDR.CURVE25519_SCALAR_MUL, toHex(input)));
+    return fromHex(await this.evm.call(PRECOMPILE_ADDR.CURVE25519_SCALAR_MUL, toHex(input)));
   }
 };
 
 // src/client/OrbinumClient.ts
 var OrbinumClient = class _OrbinumClient {
-  /** Raw access to the Substrate WebSocket connection and RPC. */
+  /** Raw Substrate WebSocket connection — use for custom RPC calls or low-level access. */
   substrate;
-  /** Raw access to the EVM HTTP JSON-RPC endpoint (if configured). */
+  /** Raw EVM HTTP JSON-RPC client. `null` when `evmRpc` is not configured. */
   evm;
   /**
-   * High-level EVM block and transaction explorer (if `evmRpc` is configured).
+   * High-level EVM block and transaction explorer.
    * Provides enriched queries for blocks, transactions, addresses, and token transfers.
+   * `null` when `evmRpc` is not configured.
    */
   evmExplorer;
   /**
-   * HTTP client for the Orbinum indexer REST API (if `indexerUrl` is configured).
+   * HTTP client for the Orbinum indexer REST API.
    * Provides paginated access to indexed blocks, extrinsics, shielded events, and nullifiers.
+   * `null` when `indexerUrl` is not configured.
    */
   indexer;
-  /** Shielded-pool operations: shield, unshield, privateTransfer, and merkle queries. */
+  /** Shielded-pool extrinsics and Merkle tree queries (`shield`, `unshield`, `privateTransfer`, …). */
   shieldedPool;
-  /** Account mapping: aliases, chain links, metadata, marketplace, and identity extrinsics. */
+  /** Account-mapping extrinsics: aliases, chain links, metadata, marketplace, and identity. */
   accountMapping;
-  /** Typed access to Orbinum `privacy_*` RPC endpoints. */
+  /** Typed access to `privacy_*` custom RPC endpoints. */
   privacy;
-  /** Typed access to zkVerifier_* RPC endpoints. */
+  /** Typed access to `zkVerifier_*` custom RPC endpoints. */
   zkVerifier;
+  /** Typed access to `relayer_*` RPC endpoints (registry lookup and pending fee queries). */
+  relayerStatus;
   /**
-   * EVM precompiles: shielded pool + account mapping callable from an EVM wallet.
-   * Only available when `evmRpc` is configured. Methods throw if `evm` is null.
+   * Precompile modules for interacting with Orbinum contracts from an EVM wallet.
+   * `null` when `evmRpc` is not configured. Methods on each sub-module throw if `evm` is `null`.
    */
   precompiles;
+  /** @internal Use `OrbinumClient.connect()` to obtain an instance. */
   constructor(substrate, evm, indexer) {
     this.substrate = substrate;
     this.evm = evm;
@@ -2848,6 +3396,7 @@ var OrbinumClient = class _OrbinumClient {
     this.accountMapping = new AccountMappingModule(substrate);
     this.privacy = new PrivacyModule(substrate);
     this.zkVerifier = new ZkVerifierModule(substrate);
+    this.relayerStatus = new RelayerStatusModule(substrate);
     this.precompiles = evm ? {
       shieldedPool: new ShieldedPoolPrecompile(evm),
       accountMapping: new AccountMappingPrecompile(evm),
@@ -2855,8 +3404,10 @@ var OrbinumClient = class _OrbinumClient {
     } : null;
   }
   /**
-   * Connects to an Orbinum node and returns a ready-to-use `OrbinumClient`.
-   * Throws if the Substrate node is unreachable within `connectTimeoutMs`.
+   * Creates and connects an `OrbinumClient` from the given configuration.
+   *
+   * Establishes the Substrate WebSocket connection and, if configured, instantiates
+   * the EVM and indexer clients. Throws if the node is unreachable within `connectTimeoutMs`.
    */
   static async connect(config) {
     const substrate = await SubstrateClient.connect(
@@ -2867,7 +3418,7 @@ var OrbinumClient = class _OrbinumClient {
     const indexer = config.indexerUrl ? new IndexerClient({ baseUrl: config.indexerUrl }) : null;
     return new _OrbinumClient(substrate, evm, indexer);
   }
-  /** Closes the WebSocket connection to the Substrate node. */
+  /** Closes the underlying Substrate WebSocket connection and releases all resources. */
   destroy() {
     this.substrate.destroy();
   }
@@ -2896,6 +3447,7 @@ var OrbinumClientProvider = class {
   _reconnectAttempt = 0;
   // ─── Events ─────────────────────────────────────────────────────────────
   _listeners = /* @__PURE__ */ new Set();
+  /** Creates a new provider with the given configuration. Does not connect automatically — call `connect()` to initiate. */
   constructor(config) {
     this.config = config;
     this.connectTimeoutMs = config.connectTimeoutMs ?? DEFAULT_CONNECT_TIMEOUT_MS;
@@ -2905,9 +3457,11 @@ var OrbinumClientProvider = class {
     this.reconnectMaxMs = config.reconnectMaxMs ?? DEFAULT_RECONNECT_MAX_MS;
   }
   // ─── Status ─────────────────────────────────────────────────────────────
+  /** Current connection status. Reflects the last state set by the provider internals. */
   get status() {
     return this._status;
   }
+  /** Updates internal status and notifies all registered listeners. Swallows listener exceptions to avoid cascading failures. */
   setStatus(status, error) {
     this._status = status;
     const event = { status, ...error ? { error } : {} };
@@ -2918,6 +3472,10 @@ var OrbinumClientProvider = class {
       }
     });
   }
+  /**
+   * Registers a listener that is called on every status transition.
+   * Returns an unsubscribe function — call it to stop receiving events.
+   */
   onStatusChange(listener) {
     this._listeners.add(listener);
     return () => {
@@ -2925,10 +3483,18 @@ var OrbinumClientProvider = class {
     };
   }
   // ─── Lifecycle ──────────────────────────────────────────────────────────
+  /**
+   * Initiates the first connection attempt. No-op if the provider is not in `'idle'` state.
+   * Call this once after constructing the provider.
+   */
   connect() {
     if (this._status !== "idle") return;
     this.startConnectAttempt();
   }
+  /**
+   * Tears down the active client and any pending reconnect timers,
+   * then resets the provider back to `'idle'` so `connect()` can be called again.
+   */
   reset() {
     this.cancelReconnect();
     this.teardownClient();
@@ -2936,6 +3502,7 @@ var OrbinumClientProvider = class {
     this.setStatus("idle");
   }
   // ─── Internal connection flow ───────────────────────────────────────────
+  /** Transitions to `'connecting'`, kicks off `attemptConnect`, and schedules a reconnect if it fails. */
   startConnectAttempt() {
     this.setStatus("connecting");
     this._connectingPromise = this.attemptConnect();
@@ -2943,6 +3510,11 @@ var OrbinumClientProvider = class {
       if (this._status !== "idle") this.scheduleReconnect();
     });
   }
+  /**
+   * Performs a single connection attempt race against `connectTimeoutMs`.
+   * On success: stores the client, starts the heartbeat, and returns it.
+   * On failure: destroys any orphaned client and transitions to `'disconnected'`.
+   */
   async attemptConnect() {
     let timeoutId = null;
     let orphanClient = null;
@@ -2990,6 +3562,7 @@ var OrbinumClientProvider = class {
     }
   }
   // ─── Heartbeat ──────────────────────────────────────────────────────────
+  /** Starts the periodic heartbeat loop. Replaces any existing timer. */
   startHeartbeat() {
     this.stopHeartbeat();
     this._heartbeatTimer = setInterval(async () => {
@@ -3002,12 +3575,17 @@ var OrbinumClientProvider = class {
       }
     }, this.heartbeatIntervalMs);
   }
+  /** Clears the heartbeat interval timer if active. */
   stopHeartbeat() {
     if (this._heartbeatTimer) {
       clearInterval(this._heartbeatTimer);
       this._heartbeatTimer = null;
     }
   }
+  /**
+   * Sends a `system_health` RPC ping and waits up to `heartbeatTimeoutMs`.
+   * Returns `true` if the node responds in time, `false` otherwise.
+   */
   async probe() {
     if (!this._orbinumClient) return false;
     try {
@@ -3023,6 +3601,10 @@ var OrbinumClientProvider = class {
     }
   }
   // ─── Reconnection ───────────────────────────────────────────────────────
+  /**
+   * Schedules the next connection attempt using exponential backoff
+   * (capped at `reconnectMaxMs`), then transitions to `'reconnecting'`.
+   */
   scheduleReconnect() {
     if (this._reconnectTimer) clearTimeout(this._reconnectTimer);
     const delay = Math.min(
@@ -3036,6 +3618,7 @@ var OrbinumClientProvider = class {
       if (this._status !== "idle") this.startConnectAttempt();
     }, delay);
   }
+  /** Clears any pending reconnect timer without triggering a new attempt. */
   cancelReconnect() {
     if (this._reconnectTimer) {
       clearTimeout(this._reconnectTimer);
@@ -3043,6 +3626,7 @@ var OrbinumClientProvider = class {
     }
   }
   // ─── Client teardown ────────────────────────────────────────────────────
+  /** Stops the heartbeat, destroys the active client, and clears all in-progress promises. */
   teardownClient() {
     this.stopHeartbeat();
     try {
@@ -3053,11 +3637,19 @@ var OrbinumClientProvider = class {
     this._connectingPromise = null;
   }
   // ─── Client access ──────────────────────────────────────────────────────
+  /**
+   * Returns the active `OrbinumClient`, or awaits the in-progress connection attempt.
+   * Throws if the provider is `'idle'`, `'disconnected'`, or `'reconnecting'`.
+   */
   async getOrbinumClient() {
     if (this._orbinumClient) return this._orbinumClient;
     if (this._connectingPromise) return this._connectingPromise;
     throw new Error(`OrbinumClientProvider: cannot get client in status '${this._status}'`);
   }
+  /**
+   * Same as `getOrbinumClient()` but returns `null` instead of throwing.
+   * Useful in contexts where a missing client is an acceptable no-op.
+   */
   async tryGetOrbinumClient() {
     try {
       return await this.getOrbinumClient();
@@ -3066,15 +3658,28 @@ var OrbinumClientProvider = class {
     }
   }
   // ─── Convenience RPC helpers ────────────────────────────────────────────
+  /**
+   * Sends a single Substrate JSON-RPC request and returns the typed result.
+   * Waits for the client to be ready before dispatching.
+   */
   async rpcSend(method, params = []) {
     const client = await this.getOrbinumClient();
     return client.substrate.request(method, params);
   }
+  /**
+   * Sends a single EVM JSON-RPC request and returns the typed result.
+   * Throws if `evmRpc` was not configured.
+   */
   async evmRpc(method, params = []) {
     const client = await this.getOrbinumClient();
     if (!client.evm) throw new Error("EVM RPC not configured");
     return client.evm.request(method, params);
   }
+  /**
+   * Sends multiple EVM JSON-RPC calls as a single batch request.
+   * Returns a tuple of typed results in the same order as `calls`.
+   * Throws if `evmRpc` was not configured.
+   */
   async evmRpcBatch(calls) {
     const client = await this.getOrbinumClient();
     if (!client.evm) throw new Error("EVM RPC not configured");
@@ -3082,102 +3687,471 @@ var OrbinumClientProvider = class {
   }
 };
 
-// src/shielded-pool/NoteDecryptor.ts
+// src/utils/stealth.ts
+import { sha256 as sha2562 } from "@noble/hashes/sha2.js";
+import { hkdf } from "@noble/hashes/hkdf.js";
+import { mulPointEscalar as mulPointEscalar2, Base8 as Base82, addPoint } from "@zk-kit/baby-jubjub";
+var STEALTH_INFO = new TextEncoder().encode("orbinum-stealth-v1");
+function deriveStealthScalar(sharedSecret, ownerPkBigint) {
+  const salt = bigintTo32Le(ownerPkBigint);
+  const stealthBytes = hkdf(sha2562, sharedSecret, salt, STEALTH_INFO, 32);
+  return bytesToBigintLE(stealthBytes) % BABYJUB_SUBORDER || 1n;
+}
+function deriveStealthOwnerPk(sharedSecret, ownerPkBigint, ownerPkPoint) {
+  const stealthScalar = deriveStealthScalar(sharedSecret, ownerPkBigint);
+  const stealthPt = addPoint(mulPointEscalar2(Base82, stealthScalar), ownerPkPoint);
+  return stealthPt[0];
+}
+function deriveStealthSk(sharedSecret, ownerPkBigint, spendingKey) {
+  const stealthScalar = deriveStealthScalar(sharedSecret, ownerPkBigint);
+  return (stealthScalar + spendingKey) % BABYJUB_SUBORDER || 1n;
+}
+
+// src/utils/bjj.ts
+import { mulPointEscalar as mulPointEscalar3 } from "@zk-kit/baby-jubjub";
+var BJJ_A = 168700n;
+var BJJ_D = 168696n;
+function _modpow(base, exp, mod) {
+  let result = 1n;
+  base = base % mod;
+  while (exp > 0n) {
+    if (exp & 1n) result = result * base % mod;
+    exp >>= 1n;
+    base = base * base % mod;
+  }
+  return result;
+}
+function _sqrtModP(y2) {
+  if (y2 === 0n) return 0n;
+  if (_modpow(y2, (BN254_R - 1n) / 2n, BN254_R) !== 1n) return null;
+  let s = 0n;
+  let q = BN254_R - 1n;
+  while ((q & 1n) === 0n) {
+    q >>= 1n;
+    s++;
+  }
+  if (s === 1n) return _modpow(y2, (BN254_R + 1n) / 4n, BN254_R);
+  let z = 2n;
+  while (_modpow(z, (BN254_R - 1n) / 2n, BN254_R) === 1n) z++;
+  let m = s;
+  let c = _modpow(z, q, BN254_R);
+  let t = _modpow(y2, q, BN254_R);
+  let r = _modpow(y2, (q + 1n) / 2n, BN254_R);
+  for (; ; ) {
+    if (t === 1n) return r;
+    let i = 1n;
+    let tmp = t * t % BN254_R;
+    while (tmp !== 1n) {
+      tmp = tmp * tmp % BN254_R;
+      i++;
+    }
+    const b = _modpow(c, 1n << m - i - 1n, BN254_R);
+    m = i;
+    c = b * b % BN254_R;
+    t = t * c % BN254_R;
+    r = r * b % BN254_R;
+  }
+}
+function recoverOwnerPkPoint(ax) {
+  const x2 = ax * ax % BN254_R;
+  const num = ((1n - BJJ_A * x2) % BN254_R + BN254_R) % BN254_R;
+  const den = ((1n - BJJ_D * x2) % BN254_R + BN254_R) % BN254_R;
+  if (den === 0n) return null;
+  const denInv = _modpow(den, BN254_R - 2n, BN254_R);
+  const y2 = num * denInv % BN254_R;
+  const y = _sqrtModP(y2);
+  if (y === null) return null;
+  const yAlt = BN254_R - y;
+  try {
+    const check = mulPointEscalar3([ax, y], BABYJUB_SUBORDER);
+    return check[0] === 0n && check[1] === 1n ? [ax, y] : [ax, yAlt];
+  } catch {
+    return [ax, yAlt];
+  }
+}
+
+// src/shielded-pool/protocol/NoteBuilder.ts
+import { mulPointEscalar as mulPointEscalar4, unpackPoint as unpackPoint2 } from "@zk-kit/baby-jubjub";
+import { randomBytes as randomBytes2 } from "@noble/ciphers/utils.js";
+import { poseidon2, poseidon4 } from "poseidon-lite";
+var NoteBuilder = class {
+  /**
+   * Build a ZkNote from the given inputs.
+   *
+   * @param input.value            Amount in planck (required).
+   * @param input.assetId          Asset ID — default 0n (native ORB-Privacy).
+   * @param input.ownerPk          Sender's or recipient's global BabyJubJub Ax — default 0n.
+   * @param input.blinding         Random scalar — defaults to BigInt(Date.now()).
+   * @param input.spendingKey      Secret key for nullifier — default 0n.
+   * @param input.viewingPublicKey Recipient's 32-byte LE packed BJJ ivk. Triggers memo encryption.
+   * @param input.recipientOwnerPk Recipient's global ownerPk. Required with viewingPublicKey
+   *                               to enable stealth address derivation. Without it, the
+   *                               commitment uses ownerPk directly (no stealth).
+   */
+  static async build(input) {
+    const value = input.value;
+    const assetId = input.assetId ?? 0n;
+    const ownerPk = input.ownerPk ?? 0n;
+    const blinding = input.blinding ?? BigInt(Date.now());
+    const spendingKey = input.spendingKey ?? 0n;
+    const counterpartyPk = input.counterpartyPk ?? 0n;
+    const useStealth = input.viewingPublicKey !== void 0 && input.recipientOwnerPk !== void 0;
+    let memo;
+    if (useStealth) {
+      const recipientOwnerPk = input.recipientOwnerPk;
+      const recipientIvkPacked = input.viewingPublicKey;
+      const ephSk = randomBytes2(32);
+      const ivkPackedBigint = bytesToBigintLE(recipientIvkPacked);
+      const ivkPoint = unpackPoint2(ivkPackedBigint);
+      if (!ivkPoint)
+        throw new Error("NoteBuilder.build: invalid recipient viewing public key");
+      const ephSkScalar = BigInt(toHex(ephSk)) % BABYJUB_SUBORDER || 1n;
+      const sharedPoint = mulPointEscalar4(ivkPoint, ephSkScalar);
+      const sharedSecret = bigintTo32Le(sharedPoint[0]);
+      const recipientPkPoint = recoverOwnerPkPoint(recipientOwnerPk);
+      if (!recipientPkPoint)
+        throw new Error(
+          "NoteBuilder.build: recipientOwnerPk is not a valid BJJ x-coordinate"
+        );
+      const effectiveOwnerPk = deriveStealthOwnerPk(
+        sharedSecret,
+        recipientOwnerPk,
+        recipientPkPoint
+      );
+      const stealthCommitment = poseidon4([value, assetId, effectiveOwnerPk, blinding]);
+      const stealthCommitmentBytes = bigintTo32Le(stealthCommitment);
+      memo = Array.from(
+        EncryptedMemo.encrypt(
+          value,
+          bigintTo32Le(effectiveOwnerPk),
+          bigintTo32Le(blinding),
+          Number(assetId),
+          stealthCommitmentBytes,
+          recipientIvkPacked,
+          bigintTo32Le(counterpartyPk),
+          ephSk
+        )
+      );
+      const commitment2 = stealthCommitment;
+      const nullifier2 = poseidon2([commitment2, spendingKey]);
+      const commitmentBytes2 = stealthCommitmentBytes;
+      const nullifierBytes2 = bigintTo32Le(nullifier2);
+      if (memo.length !== ENCRYPTED_MEMO_SIZE)
+        throw new Error(
+          `NoteBuilder.build: invariant violated \u2014 memo must be ${ENCRYPTED_MEMO_SIZE} bytes, got ${memo.length}`
+        );
+      return {
+        value,
+        assetId,
+        ownerPk: effectiveOwnerPk,
+        blinding,
+        spendingKey,
+        spent: false,
+        spentAt: null,
+        commitment: commitment2,
+        nullifier: nullifier2,
+        commitmentHex: toHex(commitmentBytes2),
+        nullifierHex: toHex(nullifierBytes2),
+        memo,
+        counterpartyPk
+      };
+    }
+    const commitment = poseidon4([value, assetId, ownerPk, blinding]);
+    const nullifier = poseidon2([commitment, spendingKey]);
+    const commitmentBytes = bigintTo32Le(commitment);
+    const nullifierBytes = bigintTo32Le(nullifier);
+    memo = input.viewingPublicKey !== void 0 ? Array.from(
+      EncryptedMemo.encrypt(
+        value,
+        bigintTo32Le(ownerPk),
+        bigintTo32Le(blinding),
+        Number(assetId),
+        commitmentBytes,
+        input.viewingPublicKey,
+        bigintTo32Le(counterpartyPk)
+      )
+    ) : Array.from(EncryptedMemo.dummy());
+    if (memo.length !== ENCRYPTED_MEMO_SIZE)
+      throw new Error(
+        `NoteBuilder.build: invariant violated \u2014 memo must be ${ENCRYPTED_MEMO_SIZE} bytes, got ${memo.length}`
+      );
+    return {
+      value,
+      assetId,
+      ownerPk,
+      blinding,
+      spendingKey,
+      spent: false,
+      spentAt: null,
+      commitment,
+      nullifier,
+      commitmentHex: toHex(commitmentBytes),
+      nullifierHex: toHex(nullifierBytes),
+      memo,
+      counterpartyPk
+    };
+  }
+  /**
+   * Build the 168-byte ECDH-encrypted memo for a note.
+   *
+   * Pure TypeScript implementation — no WASM dependency.
+   * Uses ChaCha20-Poly1305 with ECDH key agreement (BabyJubJub ephemeral keypair).
+   *
+   * @param note                    The ZkNote whose fields populate the plaintext.
+   * @param recipientIvkPacked      32-byte LE packed BJJ viewing public key of the recipient.
+   *                                Pass `new Uint8Array(32)` (default) for a public/dummy memo.
+   * @param counterpartyPk          32-byte counterparty BabyJubJub Ax.
+   *                                Pass `new Uint8Array(32)` (default) for no counterparty.
+   */
+  static buildMemo(note, recipientIvkPacked, counterpartyPk) {
+    return EncryptedMemo.encrypt(
+      note.value,
+      bigintTo32Le(note.ownerPk),
+      bigintTo32Le(note.blinding),
+      Number(note.assetId),
+      bigintTo32Le(note.commitment),
+      recipientIvkPacked ?? new Uint8Array(32),
+      counterpartyPk ?? bigintTo32Le(note.counterpartyPk ?? 0n)
+    );
+  }
+};
+
+// src/shielded-pool/protocol/NoteDecryptor.ts
 import { poseidon2 as poseidon22, poseidon4 as poseidon42 } from "poseidon-lite";
-function tryDecryptNote(commitment, viewingKey, spendingKey) {
-  if (!commitment.encryptedMemo) return null;
+function computeNullifier(commitment, spendingKey) {
+  return poseidon22([commitment, spendingKey]);
+}
+function tryDecryptNote(commitment, viewingSecretKey, spendingKey, ownOwnerPk = 0n) {
+  return tryDecryptNoteVerbose(commitment, viewingSecretKey, spendingKey, ownOwnerPk).note;
+}
+function tryDecryptNoteVerbose(commitment, viewingSecretKey, spendingKey, ownOwnerPk = 0n) {
+  if (!commitment.encryptedMemo) return { note: null, reason: "no_memo" };
   let commitmentBytes;
   let memoBytes;
   try {
     commitmentBytes = fromHex(commitment.commitmentHex);
     memoBytes = fromHex(commitment.encryptedMemo);
   } catch {
-    return null;
+    return { note: null, reason: "hex_parse_error" };
+  }
+  if (memoBytes.length !== ENCRYPTED_MEMO_SIZE) {
+    return {
+      note: null,
+      reason: `memo_size_mismatch:got_${memoBytes.length}_expected_${ENCRYPTED_MEMO_SIZE}`
+    };
+  }
+  const plaintext = EncryptedMemo.decrypt(memoBytes, commitmentBytes, viewingSecretKey);
+  if (!plaintext) return { note: null, reason: "decrypt_failed:wrong_key_or_corrupt_mac" };
+  let effectiveOwnerPk = plaintext.ownerPk;
+  let effectiveSpendingKey = spendingKey;
+  if (ownOwnerPk !== 0n && plaintext.ownerPk !== ownOwnerPk) {
+    const sharedSecret = EncryptedMemo.extractSharedSecret(memoBytes, viewingSecretKey);
+    if (!sharedSecret) return { note: null, reason: "stealth_shared_secret_failed" };
+    const ownPkPoint = recoverOwnerPkPoint(ownOwnerPk);
+    if (!ownPkPoint) return { note: null, reason: "stealth_invalid_own_owner_pk" };
+    const stealthOwnerPk = deriveStealthOwnerPk(sharedSecret, ownOwnerPk, ownPkPoint);
+    if (stealthOwnerPk !== plaintext.ownerPk) {
+      return { note: null, reason: "commitment_mismatch" };
+    }
+    effectiveOwnerPk = stealthOwnerPk;
+    effectiveSpendingKey = deriveStealthSk(sharedSecret, ownOwnerPk, spendingKey);
   }
-  const plaintext = EncryptedMemo.decrypt(memoBytes, commitmentBytes, viewingKey);
-  if (!plaintext) return null;
   const recomputed = poseidon42([
     plaintext.value,
     plaintext.assetId,
-    plaintext.ownerPk,
+    effectiveOwnerPk,
     plaintext.blinding
   ]);
-  if (recomputed !== bytesToBigintLE(commitmentBytes)) return null;
-  const nullifier = poseidon22([recomputed, spendingKey]);
+  if (recomputed !== bytesToBigintLE(commitmentBytes)) {
+    return { note: null, reason: "commitment_mismatch" };
+  }
+  const nullifier = poseidon22([recomputed, effectiveSpendingKey]);
   return {
-    value: plaintext.value,
-    assetId: plaintext.assetId,
-    ownerPk: plaintext.ownerPk,
-    blinding: plaintext.blinding,
-    spendingKey,
-    spent: false,
-    spentAt: null,
-    commitment: recomputed,
-    nullifier,
-    commitmentHex: toHex(bigintTo32Le(recomputed)),
-    nullifierHex: toHex(bigintTo32Le(nullifier)),
-    memo: Array.from(memoBytes)
+    note: {
+      value: plaintext.value,
+      assetId: plaintext.assetId,
+      ownerPk: effectiveOwnerPk,
+      blinding: plaintext.blinding,
+      spendingKey: effectiveSpendingKey,
+      spent: false,
+      spentAt: null,
+      commitment: recomputed,
+      nullifier,
+      commitmentHex: toHex(bigintTo32Le(recomputed)),
+      nullifierHex: toHex(bigintTo32Le(nullifier)),
+      memo: Array.from(memoBytes),
+      counterpartyPk: plaintext.counterpartyPk
+    }
   };
 }
 
-// src/shielded-pool/PrivacyKeys.ts
-import { hkdf } from "@noble/hashes/hkdf.js";
-import { sha256 as sha2562 } from "@noble/hashes/sha2.js";
-import { mulPointEscalar, Base8 } from "@zk-kit/baby-jubjub";
+// src/shielded-pool/protocol/coinSelection.ts
+var TRANSFER_TREE_DEPTH = 20;
+function selectNotes(notes, needed) {
+  const unspent = notes.filter((n) => !n.spent && n.value > 0n);
+  const sorted = [...unspent].sort((a, b) => a.value < b.value ? -1 : 1);
+  const single = sorted.find((n) => n.value >= needed);
+  if (single) return [single, null];
+  for (let i = 0; i < sorted.length; i++) {
+    for (let j = i + 1; j < sorted.length; j++) {
+      const a = sorted[i];
+      const b = sorted[j];
+      if (a !== void 0 && b !== void 0 && a.value + b.value >= needed) {
+        return [a, b];
+      }
+    }
+  }
+  return null;
+}
+function buildDummyTransferInput(assetId) {
+  const zeroSibling = "0x" + "00".repeat(32);
+  return {
+    nullifier: 0n,
+    // Constraint 9: nullifier * is_dummy.out === 0 → must be 0
+    value: 0n,
+    // triggers is_dummy[i].out = 1 in the circuit
+    assetId,
+    // must match real note (Constraint 7)
+    ownerPk: 0n,
+    blinding: 0n,
+    spendingKey: 1n,
+    // arbitrary; EdDSA is disabled (enabled = 0) for dummy inputs
+    pathSiblings: Array(TRANSFER_TREE_DEPTH).fill(zeroSibling),
+    leafIndex: 0
+  };
+}
 
-// src/shielded-pool/constants.ts
-var BN254_R = 21888242871839275222246405745257275088548364400416034343698204186575808495617n;
+// src/shielded-pool/protocol/disclosure.ts
+import {
+  generateDisclosureProof
+} from "@orbinum/proof-generator";
+import { mulPointEscalar as mulPointEscalar5, Base8 as Base83 } from "@zk-kit/baby-jubjub";
+import { poseidon1, poseidon3 } from "poseidon-lite";
+function hexFieldToBytes32(hex) {
+  const clean = hex.startsWith("0x") || hex.startsWith("0X") ? hex.slice(2) : hex;
+  return fromHex(clean.padStart(64, "0"));
+}
+function deriveBabyJubjubKeypair(substrateSigningKey) {
+  let keyBigInt = 0n;
+  for (let i = 0; i < substrateSigningKey.length; i++) {
+    keyBigInt = keyBigInt << 8n | BigInt(substrateSigningKey[i]);
+  }
+  const sk = poseidon1([keyBigInt]);
+  const pk = mulPointEscalar5(Base83, sk);
+  return { sk, pkX: pk[0], pkY: pk[1] };
+}
+function buildDisclosurePublicSignals(commitment, auditorPkX, auditorPkY, proofOutput) {
+  const buf = new Uint8Array(256);
+  buf.set(hexFieldToBytes32(commitment), 0);
+  buf.set(bigintTo32Le(auditorPkX), 32);
+  buf.set(bigintTo32Le(auditorPkY), 64);
+  buf.set(hexFieldToBytes32(proofOutput.encryptedData.epkX), 96);
+  buf.set(hexFieldToBytes32(proofOutput.encryptedData.epkY), 128);
+  buf.set(hexFieldToBytes32(proofOutput.encryptedData.encValue), 160);
+  buf.set(hexFieldToBytes32(proofOutput.encryptedData.encAssetId), 192);
+  buf.set(hexFieldToBytes32(proofOutput.encryptedData.encOwnerHash), 224);
+  return Array.from(buf);
+}
+function decryptDisclosureSignals(auditorBjjSk, enc) {
+  const shared = mulPointEscalar5([enc.epkX, enc.epkY], auditorBjjSk);
+  const sharedX = shared[0];
+  const sharedY = shared[1];
+  const k0 = poseidon3([sharedX, sharedY, 0n]);
+  const k1 = poseidon3([sharedX, sharedY, 1n]);
+  const k2 = poseidon3([sharedX, sharedY, 2n]);
+  return {
+    value: (enc.encValue - k0 + BN254_R) % BN254_R,
+    assetId: (enc.encAssetId - k1 + BN254_R) % BN254_R,
+    ownerHash: (enc.encOwnerHash - k2 + BN254_R) % BN254_R
+  };
+}
 
-// src/shielded-pool/PrivacyKeys.ts
+// src/utils/blinding.ts
+function randomBlinding() {
+  const buf = new Uint8Array(32);
+  crypto.getRandomValues(buf);
+  const n = bytesToBigintLE(buf);
+  return n === 0n ? 1n : n % BN254_R;
+}
+
+// src/privacy-keys/PrivacyKeys.ts
+import { hkdf as hkdf2 } from "@noble/hashes/hkdf.js";
+import { sha256 as sha2563 } from "@noble/hashes/sha2.js";
+import { mulPointEscalar as mulPointEscalar6, Base8 as Base84, packPoint as packPoint2 } from "@zk-kit/baby-jubjub";
 var IVK_DOMAIN = new TextEncoder().encode("orbinum-ivk-v1");
 function deriveSpendingKeyMessage(chainId, address) {
   return `orbinum-spending-key-v1
 ${chainId}
 ${address.toLowerCase()}`;
 }
-async function deriveSpendingKeyFromSignature(signatureHex, chainId, address) {
-  const hex = signatureHex.startsWith("0x") ? signatureHex.slice(2) : signatureHex;
-  const sigBytes = new Uint8Array((hex.match(/.{2}/g) ?? []).map((b) => parseInt(b, 16)));
+async function deriveMasterKeyBytes(signatureHex, chainId, address) {
+  const sigBytes = fromHex(signatureHex);
   const info = new TextEncoder().encode(`orbinum-sk-v1:${chainId}:${address.toLowerCase()}`);
-  const skBytes = hkdf(sha2562, sigBytes, new Uint8Array(0), info, 32);
-  const skBigint = BigInt(
-    "0x" + Array.from(skBytes).map((b) => b.toString(16).padStart(2, "0")).join("")
-  ) % BN254_R;
+  return hkdf2(sha2563, sigBytes, new Uint8Array(0), info, 32);
+}
+async function deriveSpendingKeyFromSignature(signatureHex, chainId, address) {
+  const masterBytes = await deriveMasterKeyBytes(signatureHex, chainId, address);
+  const skBigint = BigInt(toHex(masterBytes)) % BABYJUB_SUBORDER;
   return skBigint === 0n ? 1n : skBigint;
 }
-function deriveViewingKey(spendingKey) {
+function deriveViewingSecretKey(spendingKey) {
   const ikm = bigintTo32Le(spendingKey);
-  return hkdf(sha2562, ikm, void 0, IVK_DOMAIN, 32);
+  return hkdf2(sha2563, ikm, void 0, IVK_DOMAIN, 32);
+}
+function deriveViewingPublicKey(ivsk) {
+  const ivskScalar = BigInt(toHex(ivsk)) % BABYJUB_SUBORDER || 1n;
+  const ivkPoint = mulPointEscalar6(Base84, ivskScalar);
+  const packed = packPoint2(ivkPoint);
+  return bigintTo32Le(packed);
 }
 function deriveOwnerPk(spendingKey) {
   try {
-    const pubPoint = mulPointEscalar(Base8, spendingKey);
+    const pubPoint = mulPointEscalar6(Base84, spendingKey);
     return pubPoint[0];
   } catch {
     return 0n;
   }
 }
 
-// src/shielded-pool/PrivacyKeyManager.ts
+// src/privacy-keys/PrivacyKeyManager.ts
 var PrivacyKeyManager = class {
   _state = {
     spendingKey: null,
-    viewingKey: null,
+    masterBytes: null,
+    viewingSecretKey: null,
+    viewingPublicKeyPacked: null,
     ownerPk: null
   };
   /**
-   * Load a spending key into the in-memory session.
-   * Derives viewingKey and ownerPk immediately.
+   * Load a spending key and its corresponding master bytes into the in-memory session.
+   * Derives viewingSecretKey, viewingPublicKeyPacked, and ownerPk immediately.
    * Replaces any previously loaded key.
+   *
+   * @param spendingKey  Circuit scalar: BigInt(masterBytes) % BABYJUB_SUBORDER, clamped to [1, ∞).
+   * @param masterBytes  Raw 32-byte HKDF output before modular reduction. Used to derive
+   *                     the stable vault key (HKDF(masterBytes, info="orbinum-vault-key-v1")).
    */
-  async load(spendingKey) {
-    const viewingKey = deriveViewingKey(spendingKey);
+  async load(spendingKey, masterBytes) {
+    const viewingSecretKey = deriveViewingSecretKey(spendingKey);
+    const viewingPublicKeyPacked = deriveViewingPublicKey(viewingSecretKey);
     const ownerPk = deriveOwnerPk(spendingKey);
-    this._state = { spendingKey, viewingKey, ownerPk };
+    this._state = {
+      spendingKey,
+      masterBytes,
+      viewingSecretKey,
+      viewingPublicKeyPacked,
+      ownerPk
+    };
   }
   /** Clear all key material from memory. Call on vault lock / sign-out. */
   clear() {
-    this._state = { spendingKey: null, viewingKey: null, ownerPk: null };
+    this._state = {
+      spendingKey: null,
+      masterBytes: null,
+      viewingSecretKey: null,
+      viewingPublicKeyPacked: null,
+      ownerPk: null
+    };
   }
   /** Returns true if a spending key has been loaded. */
   isLoaded() {
@@ -3190,12 +4164,29 @@ var PrivacyKeyManager = class {
     }
     return this._state.spendingKey;
   }
-  /** Returns the 32-byte viewing key. Throws if not loaded. */
-  getViewingKey() {
-    if (this._state.viewingKey === null) {
+  /**
+   * Returns the 32-byte viewing secret key (ivsk).
+   * Used internally for decrypting received notes during rescan.
+   * SECURITY: never expose this in addresses or network requests.
+   * Throws if not loaded.
+   */
+  getViewingSecretKey() {
+    if (this._state.viewingSecretKey === null) {
+      throw new Error("PrivacyKeyManager: no key loaded. Call load() first.");
+    }
+    return this._state.viewingSecretKey;
+  }
+  /**
+   * Returns the 32-byte LE-encoded packed BJJ viewing public key (ivk).
+   * This is the component embedded in the privacy address and passed to senders
+   * so they can encrypt memos only the recipient can decrypt.
+   * Throws if not loaded.
+   */
+  getViewingPublicKeyPacked() {
+    if (this._state.viewingPublicKeyPacked === null) {
       throw new Error("PrivacyKeyManager: no key loaded. Call load() first.");
     }
-    return this._state.viewingKey;
+    return this._state.viewingPublicKeyPacked;
   }
   /** Returns the BabyJubJub owner public key (x-coordinate). Throws if not loaded. */
   getOwnerPk() {
@@ -3208,24 +4199,86 @@ var PrivacyKeyManager = class {
   getSpendingKeyBytes() {
     return bigintTo32Le(this.getSpendingKey());
   }
-  /** Exports the spending key as a 0x-prefixed 64-char hex string. Throws if not loaded. */
+  /**
+   * Returns the 32-byte master key bytes (pre-modulus HKDF output).
+   * Used to derive the stable vault AES key. Throws if not loaded.
+   */
+  getMasterBytes() {
+    if (this._state.masterBytes === null) {
+      throw new Error("PrivacyKeyManager: no key loaded. Call load() first.");
+    }
+    return this._state.masterBytes;
+  }
+  /**
+   * Exports the master key bytes as a "mk:0x{hex}" string.
+   * Storing masterBytes (not the sk scalar) ensures the vault key and
+   * rescan can always be reconstructed regardless of any future modulus change.
+   * Throws if not loaded.
+   */
   exportHex() {
-    return "0x" + this.getSpendingKey().toString(16).padStart(64, "0");
+    const mb = this.getMasterBytes();
+    return "mk:0x" + Array.from(mb, (b) => b.toString(16).padStart(2, "0")).join("");
+  }
+  /**
+   * Exports a shareable privacy address encoding the owner public key and
+   * viewing PUBLIC key of the currently loaded identity.
+   *
+   * Format: `orbpriv1:{ownerPk_hex}:{viewingPublicKey_hex}`
+   *
+   * The recipient uses this address so the sender can:
+   *  1. Embed `ownerPk` in the note commitment (Poseidon4 input).
+   *  2. Encrypt the memo via ECDH with the recipient's `viewingPublicKey`.
+   *
+   * SECURITY: Only the viewing PUBLIC key is embedded — the viewing secret key
+   * (used for decryption) is never exported. Holders of this address cannot
+   * decrypt the recipient's notes.
+   *
+   * Throws if no key is loaded.
+   */
+  encodePrivacyAddress() {
+    const ownerPk = this.getOwnerPk();
+    const ivkPacked = this.getViewingPublicKeyPacked();
+    const ownerPkHex = "0x" + ownerPk.toString(16).padStart(64, "0");
+    const ivkHex = "0x" + Array.from(ivkPacked, (b) => b.toString(16).padStart(2, "0")).join("");
+    return `orbpriv1:${ownerPkHex}:${ivkHex}`;
   }
   /**
-   * Load a spending key from a 0x-prefixed or bare hex string.
-   * Validates the key is in the valid range [1, BN254_R).
+   * Decode a privacy address of the form `orbpriv1:{ownerPk_hex}:{viewingPublicKey_hex}`.
+   * Returns `{ ownerPkHex, viewingPublicKeyHex }` on success, or `null` if the input
+   * does not match the expected format.
+   */
+  static decodePrivacyAddress(address) {
+    if (!address.startsWith("orbpriv1:")) return null;
+    const parts = address.split(":");
+    if (parts.length !== 3) return null;
+    const ownerPkHex = parts[1];
+    const viewingPublicKeyHex = parts[2];
+    if (!ownerPkHex || !viewingPublicKeyHex) return null;
+    return { ownerPkHex, viewingPublicKeyHex };
+  }
+  /**
+   * Load keys from a cached "mk:0x{masterBytes_hex}" string produced by exportHex().
+   * Throws if the format is invalid or masterBytes length is not 32 bytes.
    */
   async importFromHex(hex) {
-    const key = BigInt(hex.startsWith("0x") ? hex : "0x" + hex);
-    if (key === 0n || key >= BN254_R) {
-      throw new Error("PrivacyKeyManager: invalid spending key \u2014 out of BN254 range.");
+    if (!hex.startsWith("mk:")) {
+      throw new Error(
+        'PrivacyKeyManager: invalid cache format. Expected "mk:0x{masterBytes_hex}".'
+      );
+    }
+    const raw = hex.slice(3);
+    const h = raw.startsWith("0x") ? raw.slice(2) : raw;
+    const masterBytes = new Uint8Array((h.match(/.{2}/g) ?? []).map((b) => parseInt(b, 16)));
+    if (masterBytes.length !== 32) {
+      throw new Error("PrivacyKeyManager: invalid master bytes \u2014 expected 32 bytes.");
     }
-    await this.load(key);
+    const masterBigint = BigInt("0x" + h);
+    const sk = masterBigint % BABYJUB_SUBORDER || 1n;
+    await this.load(sk, masterBytes);
   }
 };
 
-// src/shielded-pool/VaultCrypto.ts
+// src/vault/VaultJson.ts
 function vaultReplacer(_key, value) {
   if (typeof value === "bigint") return { __bigint: value.toString() };
   return value;
@@ -3236,16 +4289,28 @@ function vaultReviver(_key, value) {
   }
   return value;
 }
+
+// src/utils/encoding.ts
+function toBase64(buf) {
+  const bytes = buf instanceof Uint8Array ? buf : new Uint8Array(buf);
+  let str = "";
+  for (const b of bytes) str += String.fromCharCode(b);
+  return btoa(str);
+}
+function fromBase64(b64) {
+  const bin = atob(b64);
+  const out = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+  return out;
+}
+
+// src/vault/VaultCrypto.ts
 var VAULT_KEY_INFO = new TextEncoder().encode("orbinum-vault-key-v1");
 var IV_BYTES = 12;
-async function deriveVaultKey(spendingKeyBytes) {
-  const keyMaterial = await crypto.subtle.importKey(
-    "raw",
-    spendingKeyBytes.slice(0),
-    "HKDF",
-    false,
-    ["deriveKey"]
-  );
+async function deriveVaultKey(masterBytes) {
+  const keyMaterial = await crypto.subtle.importKey("raw", masterBytes.slice(0), "HKDF", false, [
+    "deriveKey"
+  ]);
   return crypto.subtle.deriveKey(
     {
       name: "HKDF",
@@ -3274,6 +4339,177 @@ async function decryptJson(key, iv, ciphertext) {
   return JSON.parse(new TextDecoder().decode(plainBuf), vaultReviver);
 }
 
+// src/vault/errors.ts
+var VaultLockedError = class extends Error {
+  constructor(message = "Vault is locked. Connect your wallet to unlock it.") {
+    super(message);
+    this.name = "VaultLockedError";
+  }
+};
+
+// src/vault/noteOps.ts
+function applyNoteStatus(note, status) {
+  return {
+    ...note,
+    spent: status?.spent ?? note.spent ?? false,
+    spentAt: status?.spentAt ?? note.spentAt ?? null
+  };
+}
+async function encryptNote(key, note) {
+  const { iv, ciphertext } = await encryptJson(key, note);
+  return {
+    commitmentHex: note.commitmentHex,
+    iv,
+    ciphertext,
+    nullifierHex: note.nullifierHex,
+    assetId: note.assetId.toString(),
+    spent: note.spent,
+    spentAt: note.spentAt,
+    updatedAt: Date.now()
+  };
+}
+async function decryptNoteRecord(key, rec) {
+  const note = await decryptJson(key, rec.iv, rec.ciphertext);
+  return applyNoteStatus(note, {
+    ...rec.spent !== void 0 && { spent: rec.spent },
+    spentAt: rec.spentAt ?? null
+  });
+}
+
+// src/proof-generator/unshield.ts
+import {
+  CircuitType,
+  generateProof,
+  WebArtifactProvider
+} from "@orbinum/proof-generator";
+import { randomBytes as randomBytes3 } from "@noble/ciphers/utils.js";
+import { mulPointEscalar as mulPointEscalar7, Base8 as Base85 } from "@zk-kit/baby-jubjub";
+import { poseidon4 as poseidon43 } from "poseidon-lite";
+
+// src/proof-generator/merkle.ts
+function merkleProofToCircuit(siblings, leafIndex) {
+  const elements = siblings.map((h) => leHexToBigint(h).toString());
+  const depth = siblings.length;
+  const indices = computePathIndices(leafIndex, depth).map(String);
+  return { elements, indices };
+}
+
+// src/proof-generator/unshield.ts
+async function generateUnshieldProof(inputs, options = {}) {
+  const { elements, indices } = merkleProofToCircuit(inputs.pathSiblings, inputs.leafIndex);
+  const fee = inputs.fee ?? 0n;
+  const changeValue = inputs.changeValue ?? 0n;
+  const noteValue = inputs.amount + fee + changeValue;
+  if (inputs.amount <= 0n) {
+    throw new Error("Unshield amount must be greater than zero.");
+  }
+  if (changeValue < 0n) {
+    throw new Error("changeValue must be >= 0.");
+  }
+  const changeOwnerPubkey = inputs.changeOwnerPubkey ?? mulPointEscalar7(Base85, inputs.spendingKey)[0];
+  const changeBlinding = inputs.changeBlinding ?? (changeValue > 0n ? bytesToBigintLE(randomBytes3(32)) : 0n);
+  const changeCommitment = changeValue > 0n ? poseidon43([changeValue, inputs.assetId, changeOwnerPubkey, changeBlinding]) : 0n;
+  const circuitInputs = {
+    merkle_root: leHexToBigint(inputs.merkleRoot).toString(),
+    nullifier: inputs.nullifier.toString(),
+    amount: inputs.amount.toString(),
+    recipient: inputs.recipient.toString(),
+    asset_id: inputs.assetId.toString(),
+    fee: fee.toString(),
+    change_commitment: changeCommitment.toString(),
+    note_value: noteValue.toString(),
+    note_asset_id: inputs.assetId.toString(),
+    note_blinding: inputs.blinding.toString(),
+    spending_key: inputs.spendingKey.toString(),
+    path_elements: elements,
+    path_indices: indices,
+    change_value: changeValue.toString(),
+    change_blinding: changeBlinding.toString(),
+    change_owner_pubkey: changeOwnerPubkey.toString()
+  };
+  const provider = options.provider ?? new WebArtifactProvider();
+  const opts = { provider };
+  if (options.verbose !== void 0) opts.verbose = options.verbose;
+  const proofResult = await generateProof(CircuitType.Unshield, circuitInputs, opts);
+  return { ...proofResult, changeCommitment, changeValue, changeBlinding, changeOwnerPubkey };
+}
+
+// src/proof-generator/transfer.ts
+import {
+  CircuitType as CircuitType2,
+  generateProof as generateProof2,
+  WebArtifactProvider as WebArtifactProvider2
+} from "@orbinum/proof-generator";
+async function generateTransferProof(params, options = {}) {
+  const root = leHexToBigint(params.merkleRoot).toString();
+  const [i0, i1] = params.inputs;
+  const [o0, o1] = params.outputs;
+  const fee = params.fee ?? 0n;
+  const path0 = merkleProofToCircuit(i0.pathSiblings, i0.leafIndex);
+  const path1 = merkleProofToCircuit(i1.pathSiblings, i1.leafIndex);
+  const circuitInputs = {
+    merkle_root: root,
+    nullifiers: [i0.nullifier.toString(), i1.nullifier.toString()],
+    commitments: [o0.commitment.toString(), o1.commitment.toString()],
+    asset_id: i0.assetId.toString(),
+    fee: fee.toString(),
+    input_values: [i0.value.toString(), i1.value.toString()],
+    input_asset_ids: [i0.assetId.toString(), i1.assetId.toString()],
+    input_blindings: [i0.blinding.toString(), i1.blinding.toString()],
+    spending_keys: [i0.spendingKey.toString(), i1.spendingKey.toString()],
+    input_path_elements: [path0.elements, path1.elements],
+    input_path_indices: [path0.indices, path1.indices],
+    output_values: [o0.value.toString(), o1.value.toString()],
+    output_asset_ids: [o0.assetId.toString(), o1.assetId.toString()],
+    output_owner_pubkeys: [o0.ownerPk.toString(), o1.ownerPk.toString()],
+    output_blindings: [o0.blinding.toString(), o1.blinding.toString()]
+  };
+  const provider = options.provider ?? new WebArtifactProvider2();
+  const opts = { provider };
+  if (options.verbose !== void 0) opts.verbose = options.verbose;
+  return generateProof2(CircuitType2.Transfer, circuitInputs, opts);
+}
+
+// src/proof-generator/fee-claim.ts
+import {
+  generateDisclosureProof as generateDisclosureProof2
+} from "@orbinum/proof-generator";
+function hexSignalToBytes(hex) {
+  const clean = hex.startsWith("0x") || hex.startsWith("0X") ? hex.slice(2) : hex;
+  const padded = clean.padStart(64, "0");
+  const bytes = new Uint8Array(32);
+  for (let i = 0; i < 32; i++) {
+    bytes[i] = parseInt(padded.slice(i * 2, i * 2 + 2), 16);
+  }
+  return bytes;
+}
+async function generateFeeClaimProof(inputs, options = {}) {
+  const result = await generateDisclosureProof2(
+    inputs.amount,
+    inputs.ownerPubkey,
+    inputs.blinding,
+    inputs.assetId,
+    inputs.commitment,
+    // Baby Jubjub base point G — placeholder, no real auditor for fee claiming
+    5299619240641551281634865583518297030282874472190772894086521144482721001553n,
+    16950150798460657717958625567821834550301663161624707787222815936182638968203n,
+    1n,
+    // r — placeholder ephemeral scalar (NOT cryptographically secure)
+    { discloseValue: true, discloseAssetId: true, discloseOwner: false },
+    options
+  );
+  const [, , sigEncValue, sigEncAssetId, sigEncOwnerHash, sigCommitment] = result.publicSignals.map(hexSignalToBytes);
+  const compact = new Uint8Array(76);
+  compact.set(sigCommitment);
+  compact.set(sigEncValue.subarray(0, 8), 32);
+  compact.set(sigEncAssetId.subarray(0, 4), 40);
+  compact.set(sigEncOwnerHash, 44);
+  return {
+    proof: result.proof,
+    publicSignals: Array.from(compact)
+  };
+}
+
 // src/account-mapping/types/index.ts
 var SignatureScheme = {
   Eip191: "Eip191",
@@ -3290,7 +4526,7 @@ function decodePrecompileCalldata(address, input) {
   if (!fnSig) return null;
   if (fnSig.startsWith("registerAlias")) {
     try {
-      const data = hexToBytes(input.slice(10));
+      const data = fromHex(input.slice(10));
       const alias = decodeString(data, 0);
       return { fnSig, args: { alias } };
     } catch {
@@ -3299,37 +4535,43 @@ function decodePrecompileCalldata(address, input) {
   }
   if (fnSig.startsWith("shield(")) {
     try {
-      const data = hexToBytes(input.slice(10));
+      const data = fromHex(input.slice(10));
       const assetId = decodeUint(data, 0);
-      const amount = decodeUint(data, 32);
-      const commitment = toHex(data.slice(64, 96));
-      return { fnSig, args: { assetId, amount, commitment } };
+      const commitment = toHex(data.slice(32, 64));
+      return { fnSig, args: { assetId, commitment } };
     } catch {
       return { fnSig, args: {} };
     }
   }
   if (fnSig.startsWith("unshield(")) {
     try {
-      const data = hexToBytes(input.slice(10));
+      const data = fromHex(input.slice(10));
       const root = toHex(data.slice(32, 64));
       const nullifier = toHex(data.slice(64, 96));
       const assetId = decodeUint(data, 96);
       const amount = decodeUint(data, 128);
       const recipient = toHex(data.slice(160, 192));
-      return { fnSig, args: { root, nullifier, assetId, amount, recipient } };
+      const fee = decodeUint(data, 192);
+      const changeCommitment = toHex(data.slice(224, 256));
+      return {
+        fnSig,
+        args: { root, nullifier, assetId, amount, recipient, fee, changeCommitment }
+      };
     } catch {
       return { fnSig, args: {} };
     }
   }
   if (fnSig.startsWith("privateTransfer(")) {
     try {
-      const data = hexToBytes(input.slice(10));
+      const data = fromHex(input.slice(10));
       const root = toHex(data.slice(32, 64));
       const nullOffset = Number(decodeUint(data, 64));
       const commOffset = Number(decodeUint(data, 96));
       const nullifiers = Number(decodeUint(data, nullOffset));
       const commitments = Number(decodeUint(data, commOffset));
-      return { fnSig, args: { root, nullifiers, commitments } };
+      const assetId = decodeUint(data, 160);
+      const fee = decodeUint(data, 192);
+      return { fnSig, args: { root, nullifiers, commitments, assetId, fee } };
     } catch {
       return { fnSig, args: {} };
     }
@@ -3542,7 +4784,11 @@ function mapExtrinsicArgs(section, method, args) {
     if (m_norm === "requestdisclosure") {
       return {
         target: get(0, "target"),
-        reason: get(1, "reason")
+        commitment: get(1, "commitment"),
+        required_fields: get(2, "required_fields"),
+        reason: get(3, "reason"),
+        auditor_bjj_pk_x: get(4, "auditor_bjj_pk_x"),
+        auditor_bjj_pk_y: get(5, "auditor_bjj_pk_y")
       };
     }
     if (m_norm === "disclose") {
@@ -3556,7 +4802,8 @@ function mapExtrinsicArgs(section, method, args) {
     if (m_norm === "rejectdisclosure") {
       return {
         auditor: get(0, "auditor"),
-        reason: get(1, "reason")
+        commitment: get(1, "commitment"),
+        reason: get(2, "reason")
       };
     }
     if (m_norm === "registerasset") {
@@ -3579,7 +4826,8 @@ function mapExtrinsicArgs(section, method, args) {
     if (m_norm === "pruneexpiredrequest") {
       return {
         target: get(0, "target"),
-        auditor: get(1, "auditor")
+        auditor: get(1, "auditor"),
+        commitment: get(2, "commitment")
       };
     }
     if (m_norm === "revokedisclosurerecord") {
@@ -3816,29 +5064,35 @@ function mapZkEventData(method, data) {
   }
   if (m_norm === "disclosed") {
     return {
-      who: get(0, "who"),
-      commitment: get(1, "commitment"),
-      auditor: get(2, "auditor")
+      target: get(0, "target"),
+      auditor: get(1, "auditor"),
+      commitment: get(2, "commitment"),
+      signals: get(3, "signals")
     };
   }
   if (m_norm === "disclosurerequested") {
     return {
       target: get(0, "target"),
       auditor: get(1, "auditor"),
-      reason: get(2, "reason")
+      commitment: get(2, "commitment"),
+      required_fields: get(3, "required_fields"),
+      auditor_bjj_pk_x: get(4, "auditor_bjj_pk_x"),
+      auditor_bjj_pk_y: get(5, "auditor_bjj_pk_y")
     };
   }
   if (m_norm === "disclosurerejected") {
     return {
       target: get(0, "target"),
       auditor: get(1, "auditor"),
-      reason: get(2, "reason")
+      commitment: get(2, "commitment"),
+      reason: get(3, "reason")
     };
   }
   if (m_norm === "disclosurerequestexpired") {
     return {
       target: get(0, "target"),
-      auditor: get(1, "auditor")
+      auditor: get(1, "auditor"),
+      commitment: get(2, "commitment")
     };
   }
   if (m_norm === "disclosurerecordrevoked") {
@@ -4100,9 +5354,13 @@ export {
   AccountId2 as AccountId,
   AccountMappingModule,
   AccountMappingPrecompile,
+  BABYJUB_SUBORDER,
+  BN254_R,
   Blake2256,
   CircuitId,
+  CircuitType,
   CryptoPrecompiles,
+  ENCRYPTED_MEMO_SIZE,
   EncryptedMemo,
   EvmClient,
   EvmExplorer,
@@ -4115,30 +5373,45 @@ export {
   PRECOMPILE_ADDR,
   PrivacyKeyManager,
   PrivacyModule,
+  RelayerStatusModule,
   SLIP0044_NAMESPACE,
   ShieldedPoolModule,
   ShieldedPoolPrecompile,
   SignatureScheme,
   Storage,
   SubstrateClient,
+  VaultLockedError,
+  WebArtifactProvider,
   ZkVerifierModule,
   accountIdHexToSs58,
   addressToAccountIdHex,
+  applyNoteStatus,
   base58,
   bigintTo32Be,
   bigintTo32Le,
   bigintTo32LeArr,
+  buildDisclosurePublicSignals,
+  buildDummyTransferInput,
   bytesToBigintLE,
+  computeNullifier,
   computePathIndices,
   connectInjectedExtension,
   decodePrecompileCalldata,
+  decryptDisclosureSignals,
   decryptJson,
+  decryptNoteRecord,
+  deriveBabyJubjubKeypair,
+  deriveMasterKeyBytes,
   deriveOwnerPk,
   deriveSpendingKeyFromSignature,
   deriveSpendingKeyMessage,
+  deriveStealthOwnerPk,
+  deriveStealthSk,
   deriveVaultKey,
-  deriveViewingKey,
+  deriveViewingPublicKey,
+  deriveViewingSecretKey,
   encryptJson,
+  encryptNote,
   ensureHexPrefix,
   evmAddressToAccountId,
   evmToImplicitSubstrate,
@@ -4148,6 +5421,10 @@ export {
   formatORB,
   fromBase64,
   fromHex,
+  generateDisclosureProof,
+  generateFeeClaimProof,
+  generateTransferProof,
+  generateUnshieldProof,
   getInjectedExtensions,
   getPolkadotSigner,
   getPolkadotSignerFromPjs,
@@ -4165,6 +5442,9 @@ export {
   mapExtrinsicArgs,
   mapZkEventData,
   normalizeEvmAddress,
+  randomBlinding,
+  recoverOwnerPkPoint,
+  selectNotes,
   shortHash,
   substrateSs58ToAccountIdHex,
   substrateToEvm,
@@ -4173,6 +5453,7 @@ export {
   toTxResult,
   truncateMiddle,
   tryDecryptNote,
+  tryDecryptNoteVerbose,
   u128,
   u64,
   vaultReplacer,