@obelyzk/sdk 0.5.0 → 1.0.1

package/dist/obelysk/index.mjs

@@ -4,11 +4,12 @@ import {
   GENERATOR_G,
   GENERATOR_H,
   ObelyskPrivacy,
+  __require,
   ecAdd,
   ecMul,
   invMod,
   randomScalar
-} from "../chunk-O2PF7VJA.mjs";
+} from "../chunk-CGPFHXUF.mjs";
 
 // src/obelysk/client.ts
 import { RpcProvider } from "starknet";
@@ -686,6 +687,124 @@ var DarkPoolClient = class {
     await this.obelysk.provider.waitForTransaction(result.transaction_hash);
     return { txHash: result.transaction_hash };
   }
+  /** Cancel an order before reveal. */
+  async cancelOrder(orderId) {
+    const account = this.obelysk.requireAccount();
+    const low = (orderId & (1n << 128n) - 1n).toString();
+    const high = (orderId >> 128n).toString();
+    const result = await account.execute([{
+      contractAddress: this.darkPoolAddress,
+      entrypoint: "cancel_order",
+      calldata: [low, high]
+    }]);
+    return result.transaction_hash;
+  }
+  /** Claim fills after epoch settlement. */
+  async claimFill(params) {
+    const account = this.obelysk.requireAccount();
+    const oLow = (params.orderId & (1n << 128n) - 1n).toString();
+    const oHigh = (params.orderId >> 128n).toString();
+    const result = await account.execute([{
+      contractAddress: this.darkPoolAddress,
+      entrypoint: "claim_fill",
+      calldata: [
+        oLow,
+        oHigh,
+        params.receiveCipher.c1.x.toString(),
+        params.receiveCipher.c1.y.toString(),
+        params.receiveCipher.c2.x.toString(),
+        params.receiveCipher.c2.y.toString(),
+        params.receiveHint.toString(),
+        params.receiveProof.commitment.toString(),
+        params.receiveProof.challenge.toString(),
+        params.receiveProof.response.toString(),
+        params.spendCipher.c1.x.toString(),
+        params.spendCipher.c1.y.toString(),
+        params.spendCipher.c2.x.toString(),
+        params.spendCipher.c2.y.toString(),
+        params.spendHint.toString(),
+        params.spendProof.commitment.toString(),
+        params.spendProof.challenge.toString(),
+        params.spendProof.response.toString()
+      ]
+    }]);
+    return result.transaction_hash;
+  }
+  /** Register your ElGamal public key with the DarkPool. */
+  async registerPubkey(pubkey) {
+    const account = this.obelysk.requireAccount();
+    const result = await account.execute([{
+      contractAddress: this.darkPoolAddress,
+      entrypoint: "register_pubkey",
+      calldata: [pubkey.x.toString(), pubkey.y.toString()]
+    }]);
+    return result.transaction_hash;
+  }
+  /** Get the result of a settled epoch. */
+  async getEpochResult(epochId) {
+    try {
+      const result = await this.obelysk.provider.callContract({
+        contractAddress: this.darkPoolAddress,
+        entrypoint: "get_epoch_result",
+        calldata: [epochId.toString()]
+      });
+      if (result.length < 2) return null;
+      const settled = BigInt(result[0]) !== 0n;
+      const priceCount = Number(BigInt(result[1]));
+      const clearingPrices = result.slice(2, 2 + priceCount);
+      return { settled, clearingPrices };
+    } catch {
+      return null;
+    }
+  }
+  /** Check if an order has been claimed. */
+  async isOrderClaimed(orderId) {
+    try {
+      const low = (orderId & (1n << 128n) - 1n).toString();
+      const high = (orderId >> 128n).toString();
+      const result = await this.obelysk.provider.callContract({
+        contractAddress: this.darkPoolAddress,
+        entrypoint: "is_order_claimed",
+        calldata: [low, high]
+      });
+      return BigInt(result[0]) !== 0n;
+    } catch {
+      return false;
+    }
+  }
+  /** Get a trader's registered public key. */
+  async getTraderPubkey(address) {
+    try {
+      const result = await this.obelysk.provider.callContract({
+        contractAddress: this.darkPoolAddress,
+        entrypoint: "get_trader_pubkey",
+        calldata: [address]
+      });
+      const x = BigInt(result[0]);
+      const y = BigInt(result[1]);
+      if (x === 0n && y === 0n) return null;
+      return { x, y };
+    } catch {
+      return null;
+    }
+  }
+  /** Get encrypted balance for a trader and asset. */
+  async getEncryptedBalance(address, assetId) {
+    try {
+      const result = await this.obelysk.provider.callContract({
+        contractAddress: this.darkPoolAddress,
+        entrypoint: "get_encrypted_balance",
+        calldata: [address, assetId]
+      });
+      if (result.length < 4) return null;
+      return {
+        c1: { x: BigInt(result[0]), y: BigInt(result[1]) },
+        c2: { x: BigInt(result[2]), y: BigInt(result[3]) }
+      };
+    } catch {
+      return null;
+    }
+  }
 };
 
 // src/obelysk/stealth.ts
@@ -845,6 +964,102 @@ var StealthClient = class {
     await this.obelysk.provider.waitForTransaction(result.transaction_hash);
     return { txHash: result.transaction_hash };
   }
+  /** Claim a stealth payment. */
+  async claim(params) {
+    const account = this.obelysk.requireAccount();
+    const p = params.spendingProof;
+    const result = await account.execute([{
+      contractAddress: this.registryAddress,
+      entrypoint: "claim_stealth_payment",
+      calldata: [
+        params.announcementIndex.toString(),
+        p.commitment.toString(),
+        p.challenge.toString(),
+        p.response.toString(),
+        p.stealthPubkey.x.toString(),
+        p.stealthPubkey.y.toString(),
+        params.recipient
+      ]
+    }]);
+    return result.transaction_hash;
+  }
+  /** Batch claim multiple stealth payments. */
+  async batchClaim(params) {
+    const account = this.obelysk.requireAccount();
+    const calldata = [
+      params.announcementIndices.length.toString(),
+      ...params.announcementIndices.map((i) => i.toString()),
+      params.spendingProofs.length.toString(),
+      ...params.spendingProofs.flatMap((p) => [
+        p.commitment.toString(),
+        p.challenge.toString(),
+        p.response.toString(),
+        p.stealthPubkey.x.toString(),
+        p.stealthPubkey.y.toString()
+      ]),
+      params.recipient
+    ];
+    const result = await account.execute([{
+      contractAddress: this.registryAddress,
+      entrypoint: "batch_claim_stealth_payments",
+      calldata
+    }]);
+    return result.transaction_hash;
+  }
+  /** Update your stealth meta-address. */
+  async updateMetaAddress(spendPubKey, viewPubKey) {
+    const account = this.obelysk.requireAccount();
+    const result = await account.execute([{
+      contractAddress: this.registryAddress,
+      entrypoint: "update_meta_address",
+      calldata: [spendPubKey.x.toString(), spendPubKey.y.toString(), viewPubKey.x.toString(), viewPubKey.y.toString()]
+    }]);
+    return result.transaction_hash;
+  }
+  /** Get a specific announcement by index. */
+  async getAnnouncement(index) {
+    try {
+      const result = await this.obelysk.provider.callContract({
+        contractAddress: this.registryAddress,
+        entrypoint: "get_announcement",
+        calldata: [index.toString()]
+      });
+      return {
+        ephemeralPubkey: { x: BigInt(result[0]), y: BigInt(result[1]) },
+        stealthAddress: result[2],
+        viewTag: result[3],
+        token: result[4],
+        amount: BigInt(result[5])
+      };
+    } catch {
+      return null;
+    }
+  }
+  /** Get announcements in a range. */
+  async getAnnouncementsRange(start, end) {
+    try {
+      const result = await this.obelysk.provider.callContract({
+        contractAddress: this.registryAddress,
+        entrypoint: "get_announcements_range",
+        calldata: [start.toString(), end.toString()]
+      });
+      const count = Number(BigInt(result[0]));
+      const items = [];
+      for (let i = 0; i < count; i++) {
+        const base = 1 + i * 6;
+        items.push({
+          ephemeralPubkey: { x: BigInt(result[base]), y: BigInt(result[base + 1]) },
+          stealthAddress: result[base + 2],
+          viewTag: result[base + 3],
+          token: result[base + 4],
+          amount: BigInt(result[base + 5])
+        });
+      }
+      return items;
+    } catch {
+      return [];
+    }
+  }
 };
 
 // src/obelysk/confidentialTransfer.ts
@@ -937,6 +1152,78 @@ var ConfidentialTransferClient = class {
       return null;
     }
   }
+  /** Register an ElGamal public key for confidential transfers. */
+  async register(publicKey) {
+    const account = this.obelysk.requireAccount();
+    const result = await account.execute([{
+      contractAddress: this.contractAddress,
+      entrypoint: "register",
+      calldata: [publicKey.x.toString(), publicKey.y.toString()]
+    }]);
+    return result.transaction_hash;
+  }
+  /** Fund: deposit public tokens into encrypted balance. */
+  async fund(params) {
+    const account = this.obelysk.requireAccount();
+    const low = (params.amount & (1n << 128n) - 1n).toString();
+    const high = (params.amount >> 128n).toString();
+    const result = await account.execute([{
+      contractAddress: this.contractAddress,
+      entrypoint: "fund",
+      calldata: [params.assetId.toString(), low, high, params.encryptionRandomness.toString(), params.aeHint.toString()]
+    }]);
+    return result.transaction_hash;
+  }
+  /** Fund another account's encrypted balance. */
+  async fundFor(params) {
+    const signer = this.obelysk.requireAccount();
+    const low = (params.amount & (1n << 128n) - 1n).toString();
+    const high = (params.amount >> 128n).toString();
+    const result = await signer.execute([{
+      contractAddress: this.contractAddress,
+      entrypoint: "fund_for",
+      calldata: [params.account, params.assetId.toString(), low, high, params.encryptionRandomness.toString(), params.aeHint.toString()]
+    }]);
+    return result.transaction_hash;
+  }
+  /** Rollover: claim pending incoming transfers into your balance. */
+  async rollover(assetId) {
+    const account = this.obelysk.requireAccount();
+    const result = await account.execute([{
+      contractAddress: this.contractAddress,
+      entrypoint: "rollover",
+      calldata: [assetId.toString()]
+    }]);
+    return result.transaction_hash;
+  }
+  /** Withdraw: convert encrypted balance back to public tokens. */
+  async withdraw(params) {
+    const account = this.obelysk.requireAccount();
+    const low = (params.amount & (1n << 128n) - 1n).toString();
+    const high = (params.amount >> 128n).toString();
+    const result = await account.execute([{
+      contractAddress: this.contractAddress,
+      entrypoint: "withdraw",
+      calldata: [params.to, params.assetId.toString(), low, high, params.proof.commitment.toString(), params.proof.challenge.toString(), params.proof.response.toString()]
+    }]);
+    return result.transaction_hash;
+  }
+  /** Get a registered public key. */
+  async getPublicKey(address) {
+    try {
+      const result = await this.obelysk.provider.callContract({
+        contractAddress: this.contractAddress,
+        entrypoint: "get_public_key",
+        calldata: [address]
+      });
+      const x = BigInt(result[0]);
+      const y = BigInt(result[1]);
+      if (x === 0n && y === 0n) return null;
+      return { x, y };
+    } catch {
+      return null;
+    }
+  }
 };
 
 // src/obelysk/proverStaking.ts
@@ -1281,6 +1568,133 @@ var PrivacyRouterClient = class {
     });
     return Number(BigInt(result[0]));
   }
+  /** Register an account with the privacy router. */
+  async registerAccount(publicKey) {
+    const account = this.obelysk.requireAccount();
+    const result = await account.execute([{
+      contractAddress: this.contractAddress,
+      entrypoint: "register_account",
+      calldata: [publicKey.x.toString(), publicKey.y.toString()]
+    }]);
+    return result.transaction_hash;
+  }
+  /** Deposit tokens into encrypted balance. */
+  async deposit(params) {
+    const account = this.obelysk.requireAccount();
+    const low = (params.amount & (1n << 128n) - 1n).toString();
+    const high = (params.amount >> 128n).toString();
+    const result = await account.execute([{
+      contractAddress: this.contractAddress,
+      entrypoint: "deposit",
+      calldata: [
+        low,
+        high,
+        params.encryptedAmount.c1.x.toString(),
+        params.encryptedAmount.c1.y.toString(),
+        params.encryptedAmount.c2.x.toString(),
+        params.encryptedAmount.c2.y.toString(),
+        params.proof.commitment.toString(),
+        params.proof.challenge.toString(),
+        params.proof.response.toString()
+      ]
+    }]);
+    return result.transaction_hash;
+  }
+  /** Withdraw from encrypted balance to public. */
+  async withdraw(params) {
+    const account = this.obelysk.requireAccount();
+    const low = (params.amount & (1n << 128n) - 1n).toString();
+    const high = (params.amount >> 128n).toString();
+    const calldata = [
+      low,
+      high,
+      params.encryptedDelta.c1.x.toString(),
+      params.encryptedDelta.c1.y.toString(),
+      params.encryptedDelta.c2.x.toString(),
+      params.encryptedDelta.c2.y.toString(),
+      params.proof.commitment.toString(),
+      params.proof.challenge.toString(),
+      params.proof.response.toString()
+    ];
+    if (params.rangeProofData) calldata.push(...params.rangeProofData);
+    const result = await account.execute([{
+      contractAddress: this.contractAddress,
+      entrypoint: "withdraw",
+      calldata
+    }]);
+    return result.transaction_hash;
+  }
+  /** Private transfer between accounts. */
+  async privateTransfer(params) {
+    const account = this.obelysk.requireAccount();
+    const result = await account.execute([{
+      contractAddress: this.contractAddress,
+      entrypoint: "private_transfer",
+      calldata: [
+        params.to,
+        params.senderCipher.c1.x.toString(),
+        params.senderCipher.c1.y.toString(),
+        params.senderCipher.c2.x.toString(),
+        params.senderCipher.c2.y.toString(),
+        params.receiverCipher.c1.x.toString(),
+        params.receiverCipher.c1.y.toString(),
+        params.receiverCipher.c2.x.toString(),
+        params.receiverCipher.c2.y.toString(),
+        params.proof.commitment.toString(),
+        params.proof.challenge.toString(),
+        params.proof.response.toString(),
+        params.senderAeHint.toString(),
+        params.receiverAeHint.toString()
+      ]
+    }]);
+    return result.transaction_hash;
+  }
+  /** Request disclosure of a nullifier (audit). */
+  async requestDisclosure(nullifier, reason) {
+    const account = this.obelysk.requireAccount();
+    const result = await account.execute([{
+      contractAddress: this.contractAddress,
+      entrypoint: "request_disclosure",
+      calldata: [nullifier, reason]
+    }]);
+    return result.transaction_hash;
+  }
+  /** Ragequit: emergency withdrawal with proof. */
+  async ragequit(proof) {
+    const account = this.obelysk.requireAccount();
+    const result = await account.execute([{
+      contractAddress: this.contractAddress,
+      entrypoint: "ragequit",
+      calldata: proof
+    }]);
+    return result.transaction_hash;
+  }
+  /** Get the nullifier tree state. */
+  async getNullifierTreeState() {
+    const result = await this.obelysk.provider.callContract({
+      contractAddress: this.contractAddress,
+      entrypoint: "get_nullifier_tree_state",
+      calldata: []
+    });
+    return { root: result[0], size: Number(BigInt(result[1])) };
+  }
+  /** Get account balance hints (for O(1) decryption). */
+  async getAccountHints(address) {
+    try {
+      const result = await this.obelysk.provider.callContract({
+        contractAddress: this.contractAddress,
+        entrypoint: "get_account_hints",
+        calldata: [address]
+      });
+      return {
+        balanceHint: BigInt(result[0]),
+        pendingInHint: BigInt(result[1]),
+        pendingOutHint: BigInt(result[2])
+      };
+    } catch {
+      return null;
+    }
+  }
 };
 
 // src/obelysk/shieldedSwap.ts
@@ -1349,6 +1763,1157 @@ var ShieldedSwapClient = class {
     });
     return result[0];
   }
+  /**
+   * Execute a shielded swap (privacy pool -> AMM -> re-deposit).
+   * This is the full privacy-preserving swap flow.
+   */
+  async shieldedSwap(params) {
+    const account = this.obelysk.requireAccount();
+    const result = await account.execute([{
+      contractAddress: this.contractAddress,
+      entrypoint: "shielded_swap",
+      calldata: [
+        params.tokenIn,
+        params.tokenOut,
+        params.amountIn.toString(),
+        params.minAmountOut.toString(),
+        params.nullifier,
+        params.merkleRoot,
+        ...params.merkleProof,
+        params.newCommitment,
+        params.encryptedAmount.toString(),
+        params.proof
+      ]
+    }]);
+    return result.transaction_hash;
+  }
+};
+
+// src/obelysk/ecies.ts
+var HKDF_INFO = "obelysk-ecies-v1";
+var ECIES_VERSION = 1;
+async function eciesEncrypt(payload, relayerPubkeyHex) {
+  const subtle = getCrypto();
+  const relayerPubkeyBytes = hexToBytes(relayerPubkeyHex);
+  if (relayerPubkeyBytes.length !== 32) {
+    throw new Error(`Invalid relayer public key length: ${relayerPubkeyBytes.length} (expected 32)`);
+  }
+  const relayerPubkey = await subtle.importKey(
+    "raw",
+    relayerPubkeyBytes.buffer,
+    { name: "X25519" },
+    false,
+    []
+  );
+  const ephemeralKeyPair = await subtle.generateKey(
+    { name: "X25519" },
+    true,
+    ["deriveBits"]
+  );
+  const sharedBits = await subtle.deriveBits(
+    { name: "X25519", public: relayerPubkey },
+    ephemeralKeyPair.privateKey,
+    256
+  );
+  const sharedKey = await subtle.importKey(
+    "raw",
+    sharedBits,
+    { name: "HKDF" },
+    false,
+    ["deriveKey"]
+  );
+  const aesKey = await subtle.deriveKey(
+    {
+      name: "HKDF",
+      hash: "SHA-256",
+      salt: new ArrayBuffer(0),
+      info: new TextEncoder().encode(HKDF_INFO)
+    },
+    sharedKey,
+    { name: "AES-GCM", length: 256 },
+    false,
+    ["encrypt"]
+  );
+  const nonce = getRandomBytes(12);
+  const plaintext = new TextEncoder().encode(JSON.stringify(payload));
+  const ciphertext = await subtle.encrypt(
+    { name: "AES-GCM", iv: nonce },
+    aesKey,
+    plaintext
+  );
+  const ephPubRaw = await subtle.exportKey("raw", ephemeralKeyPair.publicKey);
+  return {
+    ephemeral_pubkey: bytesToHex(new Uint8Array(ephPubRaw)),
+    ciphertext: bytesToBase64(new Uint8Array(ciphertext)),
+    nonce: bytesToHex(nonce),
+    version: ECIES_VERSION
+  };
+}
+function getCrypto() {
+  if (typeof globalThis.crypto?.subtle !== "undefined") {
+    return globalThis.crypto.subtle;
+  }
+  try {
+    const { webcrypto } = __require("crypto");
+    return webcrypto.subtle;
+  } catch {
+    throw new Error("ECIES requires Web Crypto API (Node 20+ or a modern browser)");
+  }
+}
+function getRandomBytes(n) {
+  if (typeof globalThis.crypto?.getRandomValues !== "undefined") {
+    return globalThis.crypto.getRandomValues(new Uint8Array(n));
+  }
+  const { randomBytes } = __require("crypto");
+  return new Uint8Array(randomBytes(n));
+}
+function hexToBytes(hex) {
+  const clean = hex.startsWith("0x") ? hex.slice(2) : hex;
+  const bytes = new Uint8Array(clean.length / 2);
+  for (let i = 0; i < bytes.length; i++) {
+    bytes[i] = parseInt(clean.slice(i * 2, i * 2 + 2), 16);
+  }
+  return bytes;
+}
+function bytesToHex(bytes) {
+  return Array.from(bytes).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+function bytesToBase64(bytes) {
+  if (typeof btoa === "function") {
+    return btoa(String.fromCharCode(...bytes));
+  }
+  return Buffer.from(bytes).toString("base64");
+}
+
+// src/obelysk/denominations.ts
+var WBTC_DENOMINATIONS = [
+  50000n,
+  // 0.0005 BTC
+  100000n,
+  // 0.001 BTC
+  500000n,
+  // 0.005 BTC
+  1000000n,
+  // 0.01 BTC
+  5000000n,
+  // 0.05 BTC
+  10000000n
+  // 0.1 BTC
+];
+var SAGE_DENOMINATIONS = [
+  10000000000000000n,
+  // 0.01 SAGE
+  50000000000000000n,
+  // 0.05 SAGE
+  100000000000000000n,
+  // 0.1 SAGE
+  500000000000000000n,
+  // 0.5 SAGE
+  1000000000000000000n,
+  // 1 SAGE
+  5000000000000000000n
+  // 5 SAGE
+];
+var ETH_DENOMINATIONS = [
+  1000000000000000n,
+  // 0.001 ETH
+  5000000000000000n,
+  // 0.005 ETH
+  10000000000000000n,
+  // 0.01 ETH
+  50000000000000000n,
+  // 0.05 ETH
+  100000000000000000n,
+  // 0.1 ETH
+  500000000000000000n
+  // 0.5 ETH
+];
+var STRK_DENOMINATIONS = [
+  50000000000000000n,
+  // 0.05 STRK
+  100000000000000000n,
+  // 0.1 STRK
+  500000000000000000n,
+  // 0.5 STRK
+  1000000000000000000n,
+  // 1 STRK
+  5000000000000000000n
+  // 5 STRK
+];
+var USDC_DENOMINATIONS = [
+  1000000n,
+  // 1 USDC
+  5000000n,
+  // 5 USDC
+  10000000n,
+  // 10 USDC
+  50000000n,
+  // 50 USDC
+  100000000n,
+  // 100 USDC
+  500000000n
+  // 500 USDC
+];
+var VM31_DENOMINATIONS = {
+  0: WBTC_DENOMINATIONS,
+  1: SAGE_DENOMINATIONS,
+  2: ETH_DENOMINATIONS,
+  3: STRK_DENOMINATIONS,
+  4: USDC_DENOMINATIONS
+};
+var DENOMINATION_BY_SYMBOL = {
+  wbtc: WBTC_DENOMINATIONS,
+  sage: SAGE_DENOMINATIONS,
+  eth: ETH_DENOMINATIONS,
+  strk: STRK_DENOMINATIONS,
+  usdc: USDC_DENOMINATIONS
+};
+function validateDenomination(amount, assetIdOrSymbol) {
+  let denoms;
+  if (typeof assetIdOrSymbol === "number") {
+    denoms = VM31_DENOMINATIONS[assetIdOrSymbol];
+  } else {
+    denoms = DENOMINATION_BY_SYMBOL[assetIdOrSymbol.toLowerCase()];
+  }
+  if (!denoms) return;
+  if (!denoms.includes(amount)) {
+    throw new Error(
+      `Deposit must use a standard denomination for asset ${assetIdOrSymbol}. Got ${amount}. Valid: [${denoms.join(", ")}]`
+    );
+  }
+}
+function splitIntoDenominations(amount, assetIdOrSymbol) {
+  let denoms;
+  if (typeof assetIdOrSymbol === "number") {
+    denoms = VM31_DENOMINATIONS[assetIdOrSymbol];
+  } else {
+    denoms = DENOMINATION_BY_SYMBOL[assetIdOrSymbol.toLowerCase()];
+  }
+  if (!denoms) return { denominations: [amount], remainder: 0n };
+  const sorted = [...denoms].sort((a, b) => b > a ? 1 : b < a ? -1 : 0);
+  const result = [];
+  let remaining = amount;
+  for (const denom of sorted) {
+    while (remaining >= denom) {
+      result.push(denom);
+      remaining -= denom;
+    }
+  }
+  return { denominations: result, remainder: remaining };
+}
+function getDenominations(assetIdOrSymbol) {
+  if (typeof assetIdOrSymbol === "number") {
+    return VM31_DENOMINATIONS[assetIdOrSymbol];
+  }
+  return DENOMINATION_BY_SYMBOL[assetIdOrSymbol.toLowerCase()];
+}
+
+// src/obelysk/vm31Vault.ts
+var VM31VaultClient = class {
+  constructor(obelysk) {
+    this.obelysk = obelysk;
+  }
+  get contractAddress() {
+    return this.obelysk.contracts.vm31_pool;
+  }
+  get relayerUrl() {
+    return this.obelysk.relayerUrl ?? "https://relay.bitsage.network:3080";
+  }
+  get relayerApiKey() {
+    return this.obelysk.relayerApiKey;
+  }
+  /** Cached relayer X25519 public key (fetched on first encrypted submit) */
+  _relayerPubkey = null;
+  async relayerFetch(path, init) {
+    const url = `${this.relayerUrl}${path}`;
+    const headers = { "Content-Type": "application/json" };
+    if (this.relayerApiKey) headers["x-api-key"] = this.relayerApiKey;
+    const res = await fetch(url, { ...init, headers: { ...headers, ...init?.headers } });
+    if (!res.ok) {
+      const body = await res.text().catch(() => "");
+      throw new Error(`VM31 relayer ${res.status}: ${body}`);
+    }
+    return res.json();
+  }
+  /**
+   * Submit a payload to the relayer, encrypted with ECIES.
+   * Falls back to plaintext if `encrypt: false` is passed.
+   */
+  async relayerSubmit(payload, encrypt = true) {
+    if (!encrypt) {
+      return this.relayerFetch("/submit", {
+        method: "POST",
+        body: JSON.stringify(payload)
+      });
+    }
+    if (!this._relayerPubkey) {
+      const keyInfo = await this.getRelayerPublicKey();
+      this._relayerPubkey = keyInfo.publicKey;
+    }
+    const envelope = await eciesEncrypt(payload, this._relayerPubkey);
+    return this.relayerFetch("/submit", {
+      method: "POST",
+      body: JSON.stringify(envelope)
+    });
+  }
+  // --------------------------------------------------------------------------
+  // On-chain reads (callContract to vm31_pool)
+  // --------------------------------------------------------------------------
+  /** Get the current Merkle root of the VM31 commitment tree */
+  async getMerkleRoot() {
+    const result = await this.obelysk.provider.callContract({
+      contractAddress: this.contractAddress,
+      entrypoint: "get_merkle_root",
+      calldata: []
+    });
+    return { lo: result[0], hi: result[1] };
+  }
+  /** Get the number of leaves in the commitment tree */
+  async getTreeSize() {
+    const result = await this.obelysk.provider.callContract({
+      contractAddress: this.contractAddress,
+      entrypoint: "get_tree_size",
+      calldata: []
+    });
+    return Number(BigInt(result[0]));
+  }
+  /** Check if a nullifier has been spent */
+  async isNullifierSpent(nullifier) {
+    const result = await this.obelysk.provider.callContract({
+      contractAddress: this.contractAddress,
+      entrypoint: "is_nullifier_spent",
+      calldata: [nullifier.lo, nullifier.hi]
+    });
+    return BigInt(result[0]) !== 0n;
+  }
+  /** Check if a Merkle root is known (valid historical root) */
+  async isKnownRoot(root) {
+    const result = await this.obelysk.provider.callContract({
+      contractAddress: this.contractAddress,
+      entrypoint: "is_known_root",
+      calldata: [root.lo, root.hi]
+    });
+    return BigInt(result[0]) !== 0n;
+  }
+  /** Get the total balance of an asset held in the pool */
+  async getAssetBalance(assetId) {
+    const result = await this.obelysk.provider.callContract({
+      contractAddress: this.contractAddress,
+      entrypoint: "get_asset_balance",
+      calldata: [assetId.toString()]
+    });
+    return BigInt(result[0]);
+  }
+  /** Get on-chain batch status (0=NONE, 1=SUBMITTED, 2=FINALIZED, 3=CANCELLED) */
+  async getBatchStatus(batchId) {
+    const result = await this.obelysk.provider.callContract({
+      contractAddress: this.contractAddress,
+      entrypoint: "get_batch_status",
+      calldata: [batchId]
+    });
+    return Number(BigInt(result[0]));
+  }
+  /** Get the currently active batch ID */
+  async getActiveBatchId() {
+    const result = await this.obelysk.provider.callContract({
+      contractAddress: this.contractAddress,
+      entrypoint: "get_active_batch_id",
+      calldata: []
+    });
+    return result[0];
+  }
+  /** Get total transaction count in a batch */
+  async getBatchTotalTxs(batchId) {
+    const result = await this.obelysk.provider.callContract({
+      contractAddress: this.contractAddress,
+      entrypoint: "get_batch_total_txs",
+      calldata: [batchId]
+    });
+    return Number(BigInt(result[0]));
+  }
+  /** Get number of processed transactions in a batch */
+  async getBatchProcessedCount(batchId) {
+    const result = await this.obelysk.provider.callContract({
+      contractAddress: this.contractAddress,
+      entrypoint: "get_batch_processed_count",
+      calldata: [batchId]
+    });
+    return Number(BigInt(result[0]));
+  }
+  /** Get the ERC-20 token address for a VM31 asset ID */
+  async getAssetToken(assetId) {
+    const result = await this.obelysk.provider.callContract({
+      contractAddress: this.contractAddress,
+      entrypoint: "get_asset_token",
+      calldata: [assetId.toString()]
+    });
+    return result[0];
+  }
+  /** Get the VM31 asset ID for a given ERC-20 token address */
+  async getTokenAsset(tokenAddress) {
+    const result = await this.obelysk.provider.callContract({
+      contractAddress: this.contractAddress,
+      entrypoint: "get_token_asset",
+      calldata: [tokenAddress]
+    });
+    return Number(BigInt(result[0]));
+  }
+  /** Check if the VM31Pool contract is paused */
+  async isPaused() {
+    const result = await this.obelysk.provider.callContract({
+      contractAddress: this.contractAddress,
+      entrypoint: "is_paused",
+      calldata: []
+    });
+    return BigInt(result[0]) !== 0n;
+  }
+  /** Get the contract owner address */
+  async getOwner() {
+    const result = await this.obelysk.provider.callContract({
+      contractAddress: this.contractAddress,
+      entrypoint: "get_owner",
+      calldata: []
+    });
+    return result[0];
+  }
+  /** Get the authorized relayer address */
+  async getRelayer() {
+    const result = await this.obelysk.provider.callContract({
+      contractAddress: this.contractAddress,
+      entrypoint: "get_relayer",
+      calldata: []
+    });
+    return result[0];
+  }
+  /** Get batch timeout in blocks */
+  async getBatchTimeoutBlocks() {
+    const result = await this.obelysk.provider.callContract({
+      contractAddress: this.contractAddress,
+      entrypoint: "get_batch_timeout_blocks",
+      calldata: []
+    });
+    return Number(BigInt(result[0]));
+  }
+  // --------------------------------------------------------------------------
+  // Relayer HTTP calls
+  // --------------------------------------------------------------------------
+  /** Check relayer health (no auth required) */
+  async getRelayerHealth() {
+    return this.relayerFetch("/health");
+  }
+  /** Get relayer queue status */
+  async getRelayerStatus() {
+    const data = await this.relayerFetch("/status");
+    return {
+      pendingTransactions: data.pending_transactions,
+      batchMaxSize: data.batch_max_size,
+      batchTimeoutSecs: data.batch_timeout_secs
+    };
+  }
+  /** Get the relayer's public encryption key */
+  async getRelayerPublicKey() {
+    const data = await this.relayerFetch("/public-key");
+    return {
+      publicKey: data.public_key,
+      version: data.version,
+      algorithm: data.algorithm
+    };
+  }
+  /**
+   * Submit a deposit transaction to the relayer.
+   * Validates denomination (privacy gap #7) and encrypts with ECIES by default.
+   * @param encrypt - Set to false for legacy plaintext mode (default: true)
+   */
+  async submitDeposit(params, encrypt = true) {
+    validateDenomination(params.amount, params.assetId);
+    return this.relayerSubmit({
+      type: "deposit",
+      amount: Number(params.amount),
+      asset_id: params.assetId,
+      recipient_pubkey: params.recipientPubkey,
+      recipient_viewing_key: params.recipientViewingKey
+    }, encrypt);
+  }
+  /**
+   * Submit a withdrawal transaction to the relayer.
+   * Withdrawals are not denomination-restricted.
+   * @param encrypt - Set to false for legacy plaintext mode (default: true)
+   */
+  async submitWithdraw(params, encrypt = true) {
+    return this.relayerSubmit({
+      type: "withdraw",
+      amount: Number(params.amount),
+      asset_id: params.assetId,
+      note: {
+        owner_pubkey: params.note.owner_pubkey,
+        asset_id: params.note.asset_id,
+        amount_lo: params.note.amount_lo,
+        amount_hi: params.note.amount_hi,
+        blinding: params.note.blinding
+      },
+      spending_key: params.spendingKey,
+      merkle_path: params.merklePath,
+      merkle_root: params.merkleRoot,
+      withdrawal_binding: params.withdrawalBinding,
+      binding_salt: params.bindingSalt
+    }, encrypt);
+  }
+  /**
+   * Submit a private transfer transaction to the relayer.
+   * Transfers are not denomination-restricted.
+   * @param encrypt - Set to false for legacy plaintext mode (default: true)
+   */
+  async submitTransfer(params, encrypt = true) {
+    return this.relayerSubmit({
+      type: "transfer",
+      amount: Number(params.amount),
+      asset_id: params.assetId,
+      recipient_pubkey: params.recipientPubkey,
+      recipient_viewing_key: params.recipientViewingKey,
+      sender_viewing_key: params.senderViewingKey,
+      input_notes: params.inputNotes.map((n) => ({
+        note: n.note,
+        spending_key: n.spendingKey,
+        merkle_path: n.merklePath
+      })),
+      merkle_root: params.merkleRoot
+    }, encrypt);
+  }
+  /** Query batch info from the relayer */
+  async queryBatch(batchId) {
+    const data = await this.relayerFetch(`/batch/${batchId}`);
+    return {
+      id: data.id,
+      status: data.status,
+      txCount: data.tx_count,
+      proofHash: data.proof_hash,
+      batchIdOnchain: data.batch_id_onchain,
+      txHash: data.tx_hash,
+      createdAt: data.created_at,
+      error: data.error
+    };
+  }
+  /** Fetch Merkle path for a commitment from the relayer */
+  async fetchMerklePath(commitment) {
+    const data = await this.relayerFetch(`/merkle-path/${commitment}`);
+    return {
+      commitment: data.commitment,
+      merklePath: data.merkle_path ?? null,
+      merkleRoot: data.merkle_root ?? null,
+      batchId: data.batch_id ?? null,
+      createdAt: data.created_at,
+      status: data.status
+    };
+  }
+  /** Force the relayer to prove the current batch immediately */
+  async forceProve() {
+    const data = await this.relayerFetch("/prove", { method: "POST" });
+    return {
+      status: data.status,
+      batchId: data.batch_id
+    };
+  }
+  // --------------------------------------------------------------------------
+  // Helpers
+  // --------------------------------------------------------------------------
+  /** Encode a bigint amount into M31 lo/hi pair (31-bit limbs) */
+  static encodeAmountM31(amount) {
+    const lo = Number(amount & 0x7FFFFFFFn);
+    const hi = Number(amount >> 31n);
+    return { lo, hi };
+  }
+  /** Decode an M31 lo/hi pair back into a bigint amount */
+  static decodeAmountM31(lo, hi) {
+    return BigInt(lo) + BigInt(hi) * (1n << 31n);
+  }
+};
+
+// src/obelysk/vm31Bridge.ts
+var VM31BridgeClient = class {
+  constructor(obelysk) {
+    this.obelysk = obelysk;
+  }
+  get contractAddress() {
+    return this.obelysk.contracts.vm31_bridge;
+  }
+  /** Get the authorized relayer address */
+  async getRelayer() {
+    const result = await this.obelysk.provider.callContract({
+      contractAddress: this.contractAddress,
+      entrypoint: "get_relayer",
+      calldata: []
+    });
+    return result[0];
+  }
+  /** Get the VM31Pool contract address */
+  async getVM31Pool() {
+    const result = await this.obelysk.provider.callContract({
+      contractAddress: this.contractAddress,
+      entrypoint: "get_vm31_pool",
+      calldata: []
+    });
+    return result[0];
+  }
+  /** Get the ConfidentialTransfer contract address */
+  async getConfidentialTransfer() {
+    const result = await this.obelysk.provider.callContract({
+      contractAddress: this.contractAddress,
+      entrypoint: "get_confidential_transfer",
+      calldata: []
+    });
+    return result[0];
+  }
+  /** Get the asset pair mapping for a given token address */
+  async getAssetPair(tokenAddress) {
+    try {
+      const result = await this.obelysk.provider.callContract({
+        contractAddress: this.contractAddress,
+        entrypoint: "get_asset_pair",
+        calldata: [tokenAddress]
+      });
+      return {
+        vm31AssetId: result[0],
+        confidentialAssetId: result[1]
+      };
+    } catch {
+      return null;
+    }
+  }
+  /** Check if a bridge key has already been processed */
+  async isBridgeKeyProcessed(bridgeKey) {
+    const result = await this.obelysk.provider.callContract({
+      contractAddress: this.contractAddress,
+      entrypoint: "is_bridge_key_processed",
+      calldata: [bridgeKey]
+    });
+    return BigInt(result[0]) !== 0n;
+  }
+  /** Compute a bridge key from withdrawal parameters */
+  async computeBridgeKey(params) {
+    const low = params.amount & (1n << 128n) - 1n;
+    const high = params.amount >> 128n;
+    const result = await this.obelysk.provider.callContract({
+      contractAddress: this.contractAddress,
+      entrypoint: "compute_bridge_key",
+      calldata: [
+        params.batchId,
+        params.withdrawalIdx.toString(),
+        params.payoutRecipient,
+        params.creditRecipient,
+        params.token,
+        low.toString(),
+        high.toString()
+      ]
+    });
+    return result[0];
+  }
+  /** Get full bridge configuration (relayer, vm31Pool, confidentialTransfer) */
+  async getConfig() {
+    const [relayer, vm31Pool, confidentialTransfer] = await Promise.all([
+      this.getRelayer(),
+      this.getVM31Pool(),
+      this.getConfidentialTransfer()
+    ]);
+    return { relayer, vm31Pool, confidentialTransfer };
+  }
+  /** Get pending upgrade info, if any */
+  async getPendingUpgrade() {
+    const result = await this.obelysk.provider.callContract({
+      contractAddress: this.contractAddress,
+      entrypoint: "get_pending_upgrade",
+      calldata: []
+    });
+    const classHash = result[0];
+    if (classHash === "0x0") return null;
+    return {
+      classHash,
+      scheduledAt: Number(BigInt(result[1]))
+    };
+  }
+  /** Check if the bridge contract is paused */
+  async isPaused() {
+    try {
+      const result = await this.obelysk.provider.callContract({
+        contractAddress: this.contractAddress,
+        entrypoint: "is_paused",
+        calldata: []
+      });
+      return BigInt(result[0]) !== 0n;
+    } catch {
+      return false;
+    }
+  }
+};
+
+// src/obelysk/otcOrderbook.ts
+var OrderSide = /* @__PURE__ */ ((OrderSide2) => {
+  OrderSide2[OrderSide2["Buy"] = 0] = "Buy";
+  OrderSide2[OrderSide2["Sell"] = 1] = "Sell";
+  return OrderSide2;
+})(OrderSide || {});
+var OrderType = /* @__PURE__ */ ((OrderType2) => {
+  OrderType2[OrderType2["Limit"] = 0] = "Limit";
+  OrderType2[OrderType2["Market"] = 1] = "Market";
+  return OrderType2;
+})(OrderType || {});
+var OrderStatus = /* @__PURE__ */ ((OrderStatus2) => {
+  OrderStatus2[OrderStatus2["Open"] = 0] = "Open";
+  OrderStatus2[OrderStatus2["PartialFill"] = 1] = "PartialFill";
+  OrderStatus2[OrderStatus2["Filled"] = 2] = "Filled";
+  OrderStatus2[OrderStatus2["Cancelled"] = 3] = "Cancelled";
+  OrderStatus2[OrderStatus2["Expired"] = 4] = "Expired";
+  return OrderStatus2;
+})(OrderStatus || {});
+var U128_MASK = (1n << 128n) - 1n;
+function splitU256(value) {
+  return {
+    low: (value & U128_MASK).toString(),
+    high: (value >> 128n).toString()
+  };
+}
+function parseU256(result, offset) {
+  return BigInt(result[offset]) + (BigInt(result[offset + 1]) << 128n);
+}
+var ORDER_SIDE_VALUES = [0 /* Buy */, 1 /* Sell */];
+var ORDER_TYPE_VALUES = [0 /* Limit */, 1 /* Market */];
+var ORDER_STATUS_VALUES = [
+  0 /* Open */,
+  1 /* PartialFill */,
+  2 /* Filled */,
+  3 /* Cancelled */,
+  4 /* Expired */
+];
+var ORDER_FELT_COUNT = 15;
+function parseOrder(result, offset) {
+  return {
+    orderId: parseU256(result, offset),
+    maker: result[offset + 2],
+    pairId: Number(BigInt(result[offset + 3])),
+    side: ORDER_SIDE_VALUES[Number(BigInt(result[offset + 4]))] ?? 0 /* Buy */,
+    orderType: ORDER_TYPE_VALUES[Number(BigInt(result[offset + 5]))] ?? 0 /* Limit */,
+    price: parseU256(result, offset + 6),
+    amount: parseU256(result, offset + 8),
+    remaining: parseU256(result, offset + 10),
+    status: ORDER_STATUS_VALUES[Number(BigInt(result[offset + 12]))] ?? 0 /* Open */,
+    createdAt: Number(BigInt(result[offset + 13])),
+    expiresAt: Number(BigInt(result[offset + 14]))
+  };
+}
+var TRADE_FELT_COUNT = 15;
+function parseTrade(result, offset) {
+  return {
+    tradeId: parseU256(result, offset),
+    makerOrderId: parseU256(result, offset + 2),
+    takerOrderId: parseU256(result, offset + 4),
+    maker: result[offset + 6],
+    taker: result[offset + 7],
+    price: parseU256(result, offset + 8),
+    amount: parseU256(result, offset + 10),
+    quoteAmount: parseU256(result, offset + 12),
+    executedAt: Number(BigInt(result[offset + 14]))
+  };
+}
+var OTCOrderbookClient = class {
+  constructor(obelysk) {
+    this.obelysk = obelysk;
+  }
+  get contractAddress() {
+    const addr = this.obelysk.contracts.otc_orderbook;
+    if (!addr) throw new Error("OTC Orderbook contract not configured for this network");
+    return addr;
+  }
+  // --------------------------------------------------------------------------
+  // Write operations
+  // --------------------------------------------------------------------------
+  /**
+   * Place a limit order on the orderbook.
+   *
+   * The contract handles internal matching against resting orders.
+   * Returns the transaction hash.
+   */
+  async placeLimitOrder(params) {
+    const account = this.obelysk.requireAccount();
+    const { low: pLow, high: pHigh } = splitU256(params.price);
+    const { low: aLow, high: aHigh } = splitU256(params.amount);
+    const result = await account.execute([
+      {
+        contractAddress: this.contractAddress,
+        entrypoint: "place_limit_order",
+        calldata: [
+          params.pairId.toString(),
+          params.side.toString(),
+          pLow,
+          pHigh,
+          aLow,
+          aHigh,
+          (params.expiresIn ?? 0).toString()
+        ]
+      }
+    ]);
+    return result.transaction_hash;
+  }
+  /**
+   * Place a market order that fills immediately against resting liquidity.
+   * Returns the transaction hash.
+   */
+  async placeMarketOrder(params) {
+    const account = this.obelysk.requireAccount();
+    const { low: aLow, high: aHigh } = splitU256(params.amount);
+    const result = await account.execute([
+      {
+        contractAddress: this.contractAddress,
+        entrypoint: "place_market_order",
+        calldata: [
+          params.pairId.toString(),
+          params.side.toString(),
+          aLow,
+          aHigh
+        ]
+      }
+    ]);
+    return result.transaction_hash;
+  }
+  /**
+   * Cancel a single order by ID.
+   * Only the maker can cancel their own order.
+   */
+  async cancelOrder(orderId) {
+    const account = this.obelysk.requireAccount();
+    const { low, high } = splitU256(orderId);
+    const result = await account.execute([
+      {
+        contractAddress: this.contractAddress,
+        entrypoint: "cancel_order",
+        calldata: [low, high]
+      }
+    ]);
+    return result.transaction_hash;
+  }
+  /**
+   * Cancel all open orders for the caller.
+   */
+  async cancelAllOrders() {
+    const account = this.obelysk.requireAccount();
+    const result = await account.execute([
+      {
+        contractAddress: this.contractAddress,
+        entrypoint: "cancel_all_orders",
+        calldata: []
+      }
+    ]);
+    return result.transaction_hash;
+  }
+  /**
+   * Place multiple limit orders in a single transaction.
+   *
+   * Cairo expects an array of (u8, OrderSide, u256, u256, u64) tuples.
+   * Calldata: [length, ...flattened orders].
+   */
+  async batchPlaceOrders(orders) {
+    const account = this.obelysk.requireAccount();
+    const calldata = [orders.length.toString()];
+    for (const order of orders) {
+      const { low: pLow, high: pHigh } = splitU256(order.price);
+      const { low: aLow, high: aHigh } = splitU256(order.amount);
+      calldata.push(
+        order.pairId.toString(),
+        order.side.toString(),
+        pLow,
+        pHigh,
+        aLow,
+        aHigh,
+        (order.expiresIn ?? 0).toString()
+      );
+    }
+    const result = await account.execute([
+      {
+        contractAddress: this.contractAddress,
+        entrypoint: "batch_place_orders",
+        calldata
+      }
+    ]);
+    return result.transaction_hash;
+  }
+  /**
+   * Cancel multiple orders in a single transaction.
+   *
+   * Calldata: [length, ...flattened u256 order IDs].
+   */
+  async batchCancelOrders(orderIds) {
+    const account = this.obelysk.requireAccount();
+    const calldata = [orderIds.length.toString()];
+    for (const id of orderIds) {
+      const { low, high } = splitU256(id);
+      calldata.push(low, high);
+    }
+    const result = await account.execute([
+      {
+        contractAddress: this.contractAddress,
+        entrypoint: "batch_cancel_orders",
+        calldata
+      }
+    ]);
+    return result.transaction_hash;
+  }
+  // --------------------------------------------------------------------------
+  // Read operations
+  // --------------------------------------------------------------------------
+  /**
+   * Get a single order by ID.
+   */
+  async getOrder(orderId) {
+    const { low, high } = splitU256(orderId);
+    const result = await this.obelysk.provider.callContract({
+      contractAddress: this.contractAddress,
+      entrypoint: "get_order",
+      calldata: [low, high]
+    });
+    return parseOrder(result, 0);
+  }
+  /**
+   * Get all order IDs belonging to a user.
+   */
+  async getUserOrders(user) {
+    const result = await this.obelysk.provider.callContract({
+      contractAddress: this.contractAddress,
+      entrypoint: "get_user_orders",
+      calldata: [user]
+    });
+    const len = Number(BigInt(result[0]));
+    const ids = [];
+    for (let i = 0; i < len; i++) {
+      ids.push(parseU256(result, 1 + i * 2));
+    }
+    return ids;
+  }
+  /**
+   * Get the best (highest) bid price for a trading pair.
+   */
+  async getBestBid(pairId) {
+    const result = await this.obelysk.provider.callContract({
+      contractAddress: this.contractAddress,
+      entrypoint: "get_best_bid",
+      calldata: [pairId.toString()]
+    });
+    return parseU256(result, 0);
+  }
+  /**
+   * Get the best (lowest) ask price for a trading pair.
+   */
+  async getBestAsk(pairId) {
+    const result = await this.obelysk.provider.callContract({
+      contractAddress: this.contractAddress,
+      entrypoint: "get_best_ask",
+      calldata: [pairId.toString()]
+    });
+    return parseU256(result, 0);
+  }
+  /**
+   * Get the bid-ask spread for a trading pair.
+   */
+  async getSpread(pairId) {
+    const result = await this.obelysk.provider.callContract({
+      contractAddress: this.contractAddress,
+      entrypoint: "get_spread",
+      calldata: [pairId.toString()]
+    });
+    return parseU256(result, 0);
+  }
+  /**
+   * Get trading pair configuration.
+   */
+  async getPair(pairId) {
+    const result = await this.obelysk.provider.callContract({
+      contractAddress: this.contractAddress,
+      entrypoint: "get_pair",
+      calldata: [pairId.toString()]
+    });
+    return {
+      baseToken: result[0],
+      quoteToken: result[1],
+      minOrderSize: parseU256(result, 2),
+      tickSize: parseU256(result, 4),
+      isActive: BigInt(result[6]) !== 0n
+    };
+  }
+  /**
+   * Get the orderbook configuration (fees, limits, pause state).
+   */
+  async getConfig() {
+    const result = await this.obelysk.provider.callContract({
+      contractAddress: this.contractAddress,
+      entrypoint: "get_config",
+      calldata: []
+    });
+    return {
+      makerFeeBps: Number(BigInt(result[0])),
+      takerFeeBps: Number(BigInt(result[1])),
+      defaultExpirySecs: Number(BigInt(result[2])),
+      maxOrdersPerUser: Number(BigInt(result[3])),
+      paused: BigInt(result[4]) !== 0n
+    };
+  }
+  /**
+   * Get aggregate orderbook statistics.
+   */
+  async getStats() {
+    const result = await this.obelysk.provider.callContract({
+      contractAddress: this.contractAddress,
+      entrypoint: "get_stats",
+      calldata: []
+    });
+    return {
+      orderCount: parseU256(result, 0),
+      tradeCount: parseU256(result, 2),
+      totalVolume: parseU256(result, 4),
+      totalFees: parseU256(result, 6)
+    };
+  }
+  /**
+   * Get total number of orders ever placed.
+   */
+  async getOrderCount() {
+    const result = await this.obelysk.provider.callContract({
+      contractAddress: this.contractAddress,
+      entrypoint: "get_order_count",
+      calldata: []
+    });
+    return parseU256(result, 0);
+  }
+  /**
+   * Get total number of trades executed.
+   */
+  async getTradeCount() {
+    const result = await this.obelysk.provider.callContract({
+      contractAddress: this.contractAddress,
+      entrypoint: "get_trade_count",
+      calldata: []
+    });
+    return parseU256(result, 0);
+  }
+  /**
+   * Get the time-weighted average price for a trading pair.
+   */
+  async getTwap(pairId) {
+    const result = await this.obelysk.provider.callContract({
+      contractAddress: this.contractAddress,
+      entrypoint: "get_twap",
+      calldata: [pairId.toString()]
+    });
+    return parseU256(result, 0);
+  }
+  /**
+   * Get 24-hour rolling statistics for a trading pair.
+   */
+  async get24hStats(pairId) {
+    const result = await this.obelysk.provider.callContract({
+      contractAddress: this.contractAddress,
+      entrypoint: "get_24h_stats",
+      calldata: [pairId.toString()]
+    });
+    return {
+      volume: parseU256(result, 0),
+      high: parseU256(result, 2),
+      low: parseU256(result, 4),
+      tradeCount: parseU256(result, 6)
+    };
+  }
+  /**
+   * Get the most recent trade for a trading pair.
+   */
+  async getLastTrade(pairId) {
+    const result = await this.obelysk.provider.callContract({
+      contractAddress: this.contractAddress,
+      entrypoint: "get_last_trade",
+      calldata: [pairId.toString()]
+    });
+    return {
+      price: parseU256(result, 0),
+      amount: parseU256(result, 2),
+      timestamp: Number(BigInt(result[4]))
+    };
+  }
+  /**
+   * Get the orderbook depth (price levels) for a trading pair.
+   *
+   * Returns up to `maxLevels` aggregated price levels for both
+   * bids and asks. Each level contains price, total amount, and
+   * number of orders at that price.
+   */
+  async getOrderbookDepth(pairId, maxLevels) {
+    const result = await this.obelysk.provider.callContract({
+      contractAddress: this.contractAddress,
+      entrypoint: "get_orderbook_depth",
+      calldata: [pairId.toString(), maxLevels.toString()]
+    });
+    let offset = 0;
+    const bidCount = Number(BigInt(result[offset]));
+    offset += 1;
+    const bids = [];
+    for (let i = 0; i < bidCount; i++) {
+      bids.push({
+        price: parseU256(result, offset),
+        totalAmount: parseU256(result, offset + 2),
+        orderCount: Number(BigInt(result[offset + 4]))
+      });
+      offset += 5;
+    }
+    const askCount = Number(BigInt(result[offset]));
+    offset += 1;
+    const asks = [];
+    for (let i = 0; i < askCount; i++) {
+      asks.push({
+        price: parseU256(result, offset),
+        totalAmount: parseU256(result, offset + 2),
+        orderCount: Number(BigInt(result[offset + 4]))
+      });
+      offset += 5;
+    }
+    return { bids, asks };
+  }
+  /**
+   * Get active orders for a trading pair with pagination.
+   */
+  async getActiveOrders(pairId, offset, limit) {
+    const result = await this.obelysk.provider.callContract({
+      contractAddress: this.contractAddress,
+      entrypoint: "get_active_orders",
+      calldata: [pairId.toString(), offset.toString(), limit.toString()]
+    });
+    const len = Number(BigInt(result[0]));
+    const orders = [];
+    for (let i = 0; i < len; i++) {
+      orders.push(parseOrder(result, 1 + i * ORDER_FELT_COUNT));
+    }
+    return orders;
+  }
+  /**
+   * Get trade history for a trading pair with pagination.
+   */
+  async getTradeHistory(pairId, offset, limit) {
+    const result = await this.obelysk.provider.callContract({
+      contractAddress: this.contractAddress,
+      entrypoint: "get_trade_history",
+      calldata: [pairId.toString(), offset.toString(), limit.toString()]
+    });
+    const len = Number(BigInt(result[0]));
+    const trades = [];
+    for (let i = 0; i < len; i++) {
+      trades.push(parseTrade(result, 1 + i * TRADE_FELT_COUNT));
+    }
+    return trades;
+  }
+  /**
+   * Get the contract owner address.
+   */
+  async getOwner() {
+    const result = await this.obelysk.provider.callContract({
+      contractAddress: this.contractAddress,
+      entrypoint: "owner",
+      calldata: []
+    });
+    return result[0];
+  }
 };
 
 // src/obelysk/client.ts
@@ -1360,6 +2925,8 @@ var ObelyskClient = class {
   contracts;
   tokens;
   privacyPools;
+  relayerUrl;
+  relayerApiKey;
   /** Privacy Pool operations (deposit/withdraw shielded tokens) */
   privacyPool;
   /** DarkPool batch auction trading */
@@ -1374,6 +2941,12 @@ var ObelyskClient = class {
   router;
   /** Shielded swap router (privacy-preserving AMM swaps) */
   swap;
+  /** VM31 UTXO privacy vault (deposits/withdrawals/transfers via relayer) */
+  vm31;
+  /** VM31 confidential bridge (bridge VM31 withdrawals to encrypted balances) */
+  bridge;
+  /** OTC orderbook (limit/market orders, trade history) */
+  otc;
   constructor(config) {
     this.network = config.network;
     this.provider = new RpcProvider({ nodeUrl: config.rpcUrl ?? getRpcUrl(config.network) });
@@ -1381,6 +2954,8 @@ var ObelyskClient = class {
     this.contracts = getContracts(config.network);
     this.tokens = this.contracts.tokens ?? MAINNET_TOKENS;
     this.privacyPools = config.network === "mainnet" ? MAINNET_PRIVACY_POOLS : {};
+    this.relayerUrl = config.relayerUrl;
+    this.relayerApiKey = config.relayerApiKey;
     this.privacy = new ObelyskPrivacy();
     if (config.privacyPrivateKey) {
       const pk = BigInt(config.privacyPrivateKey);
@@ -1393,6 +2968,9 @@ var ObelyskClient = class {
     this.staking = new ProverStakingClient(this);
     this.router = new PrivacyRouterClient(this);
     this.swap = new ShieldedSwapClient(this);
+    this.vm31 = new VM31VaultClient(this);
+    this.bridge = new VM31BridgeClient(this);
+    this.otc = new OTCOrderbookClient(this);
   }
   /** Get token address by symbol */
   getTokenAddress(symbol) {
@@ -1416,34 +2994,51 @@ export {
   CURVE_ORDER,
   ConfidentialTransferClient,
   DARKPOOL_ASSET_IDS,
+  DENOMINATION_BY_SYMBOL,
   DarkPoolClient,
+  ETH_DENOMINATIONS,
   FIELD_PRIME,
   GENERATOR_G,
   GENERATOR_H,
   MAINNET_PRIVACY_POOLS,
   MAINNET_TOKENS,
+  OTCOrderbookClient,
   ObelyskClient,
   ObelyskPrivacy,
+  OrderSide,
+  OrderStatus,
+  OrderType,
   PrivacyPoolClient,
   PrivacyRouterClient,
   ProverStakingClient,
+  SAGE_DENOMINATIONS,
+  STRK_DENOMINATIONS,
   ShieldedSwapClient,
   StealthClient,
   TOKEN_DECIMALS,
+  USDC_DENOMINATIONS,
+  VM31BridgeClient,
+  VM31VaultClient,
   VM31_ASSET_IDS,
+  VM31_DENOMINATIONS,
+  WBTC_DENOMINATIONS,
   commitmentToHash,
   createAEHint,
   createEncryptionProof,
   deriveNullifier,
   ecAdd2 as ecAdd,
   ecMul2 as ecMul,
+  eciesEncrypt,
   elgamalEncrypt,
   formatAmount,
   getContracts,
+  getDenominations,
   getRpcUrl,
   mod,
   modInverse,
   parseAmount,
   pedersenCommit,
-  randomScalar2 as randomScalar
+  randomScalar2 as randomScalar,
+  splitIntoDenominations,
+  validateDenomination
 };