@obelyzk/sdk 0.5.0 → 1.0.1

package/dist/obelysk/index.d.mts

@@ -150,6 +150,41 @@ interface EpochInfo {
     phase: 'Commit' | 'Reveal' | 'Settle' | 'Closed';
     blocksRemaining: number;
 }
+interface ClaimFillParams {
+    orderId: bigint;
+    receiveCipher: {
+        c1: {
+            x: bigint;
+            y: bigint;
+        };
+        c2: {
+            x: bigint;
+            y: bigint;
+        };
+    };
+    receiveHint: bigint;
+    receiveProof: {
+        commitment: bigint;
+        challenge: bigint;
+        response: bigint;
+    };
+    spendCipher: {
+        c1: {
+            x: bigint;
+            y: bigint;
+        };
+        c2: {
+            x: bigint;
+            y: bigint;
+        };
+    };
+    spendHint: bigint;
+    spendProof: {
+        commitment: bigint;
+        challenge: bigint;
+        response: bigint;
+    };
+}
 declare class DarkPoolClient {
     private readonly obelysk;
     constructor(obelysk: ObelyskClient);
@@ -210,6 +245,72 @@ declare class DarkPoolClient {
     }): Promise<{
         txHash: string;
     }>;
+    /** Cancel an order before reveal. */
+    cancelOrder(orderId: bigint): Promise<string>;
+    /** Claim fills after epoch settlement. */
+    claimFill(params: {
+        orderId: bigint;
+        receiveCipher: {
+            c1: {
+                x: bigint;
+                y: bigint;
+            };
+            c2: {
+                x: bigint;
+                y: bigint;
+            };
+        };
+        receiveHint: bigint;
+        receiveProof: {
+            commitment: bigint;
+            challenge: bigint;
+            response: bigint;
+        };
+        spendCipher: {
+            c1: {
+                x: bigint;
+                y: bigint;
+            };
+            c2: {
+                x: bigint;
+                y: bigint;
+            };
+        };
+        spendHint: bigint;
+        spendProof: {
+            commitment: bigint;
+            challenge: bigint;
+            response: bigint;
+        };
+    }): Promise<string>;
+    /** Register your ElGamal public key with the DarkPool. */
+    registerPubkey(pubkey: {
+        x: bigint;
+        y: bigint;
+    }): Promise<string>;
+    /** Get the result of a settled epoch. */
+    getEpochResult(epochId: number): Promise<{
+        settled: boolean;
+        clearingPrices: string[];
+    } | null>;
+    /** Check if an order has been claimed. */
+    isOrderClaimed(orderId: bigint): Promise<boolean>;
+    /** Get a trader's registered public key. */
+    getTraderPubkey(address: string): Promise<{
+        x: bigint;
+        y: bigint;
+    } | null>;
+    /** Get encrypted balance for a trader and asset. */
+    getEncryptedBalance(address: string, assetId: string): Promise<{
+        c1: {
+            x: bigint;
+            y: bigint;
+        };
+        c2: {
+            x: bigint;
+            y: bigint;
+        };
+    } | null>;
 }
 
 interface StealthSendParams {
@@ -230,6 +331,30 @@ interface StealthMetaAddress {
         y: bigint;
     };
 }
+interface StealthSpendingProof {
+    commitment: bigint;
+    challenge: bigint;
+    response: bigint;
+    stealthPubkey: {
+        x: bigint;
+        y: bigint;
+    };
+}
+interface StealthAnnouncement {
+    ephemeralPubkey: {
+        x: bigint;
+        y: bigint;
+    };
+    stealthAddress: string;
+    viewTag: string;
+    token: string;
+    amount: bigint;
+}
+interface ClaimParams {
+    announcementIndex: number;
+    spendingProof: StealthSpendingProof;
+    recipient: string;
+}
 declare class StealthClient {
     private readonly obelysk;
     constructor(obelysk: ObelyskClient);
@@ -280,6 +405,64 @@ declare class StealthClient {
     }): Promise<{
         txHash: string;
     }>;
+    /** Claim a stealth payment. */
+    claim(params: {
+        announcementIndex: number;
+        spendingProof: {
+            commitment: bigint;
+            challenge: bigint;
+            response: bigint;
+            stealthPubkey: {
+                x: bigint;
+                y: bigint;
+            };
+        };
+        recipient: string;
+    }): Promise<string>;
+    /** Batch claim multiple stealth payments. */
+    batchClaim(params: {
+        announcementIndices: number[];
+        spendingProofs: Array<{
+            commitment: bigint;
+            challenge: bigint;
+            response: bigint;
+            stealthPubkey: {
+                x: bigint;
+                y: bigint;
+            };
+        }>;
+        recipient: string;
+    }): Promise<string>;
+    /** Update your stealth meta-address. */
+    updateMetaAddress(spendPubKey: {
+        x: bigint;
+        y: bigint;
+    }, viewPubKey: {
+        x: bigint;
+        y: bigint;
+    }): Promise<string>;
+    /** Get a specific announcement by index. */
+    getAnnouncement(index: number): Promise<{
+        ephemeralPubkey: {
+            x: bigint;
+            y: bigint;
+        };
+        stealthAddress: string;
+        viewTag: string;
+        token: string;
+        amount: bigint;
+    } | null>;
+    /** Get announcements in a range. */
+    getAnnouncementsRange(start: number, end: number): Promise<Array<{
+        ephemeralPubkey: {
+            x: bigint;
+            y: bigint;
+        };
+        stealthAddress: string;
+        viewTag: string;
+        token: string;
+        amount: bigint;
+    }>>;
 }
 
 /** Modular reduction (always positive) */
@@ -326,6 +509,22 @@ interface TransferParams {
     /** Token symbol */
     token: string;
 }
+interface FundParams {
+    assetId: number;
+    amount: bigint;
+    encryptionRandomness: bigint;
+    aeHint: bigint;
+}
+interface WithdrawCTParams {
+    to: string;
+    assetId: number;
+    amount: bigint;
+    proof: {
+        commitment: bigint;
+        challenge: bigint;
+        response: bigint;
+    };
+}
 declare class ConfidentialTransferClient {
     private readonly obelysk;
     constructor(obelysk: ObelyskClient);
@@ -345,6 +544,44 @@ declare class ConfidentialTransferClient {
         c1: ECPoint;
         c2: ECPoint;
     } | null>;
+    /** Register an ElGamal public key for confidential transfers. */
+    register(publicKey: {
+        x: bigint;
+        y: bigint;
+    }): Promise<string>;
+    /** Fund: deposit public tokens into encrypted balance. */
+    fund(params: {
+        assetId: number;
+        amount: bigint;
+        encryptionRandomness: bigint;
+        aeHint: bigint;
+    }): Promise<string>;
+    /** Fund another account's encrypted balance. */
+    fundFor(params: {
+        account: string;
+        assetId: number;
+        amount: bigint;
+        encryptionRandomness: bigint;
+        aeHint: bigint;
+    }): Promise<string>;
+    /** Rollover: claim pending incoming transfers into your balance. */
+    rollover(assetId: number): Promise<string>;
+    /** Withdraw: convert encrypted balance back to public tokens. */
+    withdraw(params: {
+        to: string;
+        assetId: number;
+        amount: bigint;
+        proof: {
+            commitment: bigint;
+            challenge: bigint;
+            response: bigint;
+        };
+    }): Promise<string>;
+    /** Get a registered public key. */
+    getPublicKey(address: string): Promise<{
+        x: bigint;
+        y: bigint;
+    } | null>;
 }
 
 type GpuTier = 'Consumer' | 'Professional' | 'DataCenter' | 'H100';
@@ -466,6 +703,96 @@ declare class PrivacyRouterClient {
     isLeanIMTActive(): Promise<boolean>;
     /** Get pending audit/disclosure request count. */
     getPendingRequestCount(): Promise<number>;
+    /** Register an account with the privacy router. */
+    registerAccount(publicKey: {
+        x: bigint;
+        y: bigint;
+    }): Promise<string>;
+    /** Deposit tokens into encrypted balance. */
+    deposit(params: {
+        amount: bigint;
+        encryptedAmount: {
+            c1: {
+                x: bigint;
+                y: bigint;
+            };
+            c2: {
+                x: bigint;
+                y: bigint;
+            };
+        };
+        proof: {
+            commitment: bigint;
+            challenge: bigint;
+            response: bigint;
+        };
+    }): Promise<string>;
+    /** Withdraw from encrypted balance to public. */
+    withdraw(params: {
+        amount: bigint;
+        encryptedDelta: {
+            c1: {
+                x: bigint;
+                y: bigint;
+            };
+            c2: {
+                x: bigint;
+                y: bigint;
+            };
+        };
+        proof: {
+            commitment: bigint;
+            challenge: bigint;
+            response: bigint;
+        };
+        rangeProofData?: string[];
+    }): Promise<string>;
+    /** Private transfer between accounts. */
+    privateTransfer(params: {
+        to: string;
+        senderCipher: {
+            c1: {
+                x: bigint;
+                y: bigint;
+            };
+            c2: {
+                x: bigint;
+                y: bigint;
+            };
+        };
+        receiverCipher: {
+            c1: {
+                x: bigint;
+                y: bigint;
+            };
+            c2: {
+                x: bigint;
+                y: bigint;
+            };
+        };
+        proof: {
+            commitment: bigint;
+            challenge: bigint;
+            response: bigint;
+        };
+        senderAeHint: bigint;
+        receiverAeHint: bigint;
+    }): Promise<string>;
+    /** Request disclosure of a nullifier (audit). */
+    requestDisclosure(nullifier: string, reason: string): Promise<string>;
+    /** Ragequit: emergency withdrawal with proof. */
+    ragequit(proof: string[]): Promise<string>;
+    /** Get the nullifier tree state. */
+    getNullifierTreeState(): Promise<{
+        root: string;
+        size: number;
+    }>;
+    /** Get account balance hints (for O(1) decryption). */
+    getAccountHints(address: string): Promise<{
+        balanceHint: bigint;
+        pendingInHint: bigint;
+        pendingOutHint: bigint;
+    } | null>;
 }
 
 /**
@@ -476,6 +803,18 @@ declare class PrivacyRouterClient {
  * privacy pool → swap → re-deposit flow.
  */
 
+interface ShieldedSwapParams {
+    tokenIn: string;
+    tokenOut: string;
+    amountIn: bigint;
+    minAmountOut: bigint;
+    nullifier: string;
+    merkleRoot: string;
+    merkleProof: string[];
+    newCommitment: string;
+    encryptedAmount: bigint;
+    proof: string;
+}
 declare class ShieldedSwapClient {
     private readonly obelysk;
     constructor(obelysk: ObelyskClient);
@@ -493,6 +832,452 @@ declare class ShieldedSwapClient {
     } | null>;
     /** Get contract owner. */
     getOwner(): Promise<string>;
+    /**
+     * Execute a shielded swap (privacy pool -> AMM -> re-deposit).
+     * This is the full privacy-preserving swap flow.
+     */
+    shieldedSwap(params: ShieldedSwapParams): Promise<string>;
+}
+
+/**
+ * VM31 UTXO Privacy Vault Client
+ *
+ * Wraps both on-chain VM31Pool contract reads and the VM31 relayer HTTP API
+ * for transaction submission. The VM31 system uses Poseidon2-M31 hashing
+ * with a UTXO model for confidential token transfers.
+ *
+ * On-chain reads go through `callContract()` to the VM31Pool.
+ * Transaction submissions (deposit/withdraw/transfer) go through the
+ * VM31 relayer HTTP API, which batches and proves transactions.
+ */
+
+interface PackedDigest {
+    lo: string;
+    hi: string;
+}
+type VM31AssetId = number;
+type BatchStatus = 'queued' | 'proving' | 'confirmed' | 'finalized' | 'error';
+interface VaultNote {
+    owner_pubkey: [number, number, number, number];
+    asset_id: number;
+    amount_lo: number;
+    amount_hi: number;
+    blinding: [number, number, number, number];
+}
+interface VaultMerklePath {
+    siblings: number[][];
+    index: number;
+}
+interface VaultDepositParams {
+    amount: bigint;
+    assetId: number;
+    recipientPubkey: [number, number, number, number];
+    recipientViewingKey: [number, number, number, number];
+}
+interface VaultWithdrawParams {
+    amount: bigint;
+    assetId: number;
+    note: VaultNote;
+    spendingKey: [number, number, number, number];
+    merklePath: VaultMerklePath;
+    merkleRoot: number[];
+    withdrawalBinding: number[];
+    bindingSalt?: number[];
+}
+interface VaultTransferParams {
+    amount: bigint;
+    assetId: number;
+    recipientPubkey: [number, number, number, number];
+    recipientViewingKey: [number, number, number, number];
+    senderViewingKey: [number, number, number, number];
+    inputNotes: Array<{
+        note: VaultNote;
+        spendingKey: [number, number, number, number];
+        merklePath: VaultMerklePath;
+    }>;
+    merkleRoot: number[];
+}
+interface VaultSubmitResult {
+    status: 'queued' | 'batch_triggered' | 'duplicate';
+    batchId?: string;
+    queuePosition?: number;
+    idempotencyKey?: string;
+}
+interface VaultBatchInfo {
+    id: string;
+    status: BatchStatus;
+    txCount: number;
+    proofHash?: string;
+    batchIdOnchain?: string;
+    txHash?: string;
+    createdAt?: string;
+    error?: string;
+}
+interface RelayerInfo {
+    pendingTransactions: number;
+    batchMaxSize: number;
+    batchTimeoutSecs: number;
+}
+declare class VM31VaultClient {
+    private readonly obelysk;
+    constructor(obelysk: ObelyskClient);
+    private get contractAddress();
+    private get relayerUrl();
+    private get relayerApiKey();
+    /** Cached relayer X25519 public key (fetched on first encrypted submit) */
+    private _relayerPubkey;
+    private relayerFetch;
+    /**
+     * Submit a payload to the relayer, encrypted with ECIES.
+     * Falls back to plaintext if `encrypt: false` is passed.
+     */
+    private relayerSubmit;
+    /** Get the current Merkle root of the VM31 commitment tree */
+    getMerkleRoot(): Promise<PackedDigest>;
+    /** Get the number of leaves in the commitment tree */
+    getTreeSize(): Promise<number>;
+    /** Check if a nullifier has been spent */
+    isNullifierSpent(nullifier: PackedDigest): Promise<boolean>;
+    /** Check if a Merkle root is known (valid historical root) */
+    isKnownRoot(root: PackedDigest): Promise<boolean>;
+    /** Get the total balance of an asset held in the pool */
+    getAssetBalance(assetId: number): Promise<bigint>;
+    /** Get on-chain batch status (0=NONE, 1=SUBMITTED, 2=FINALIZED, 3=CANCELLED) */
+    getBatchStatus(batchId: string): Promise<number>;
+    /** Get the currently active batch ID */
+    getActiveBatchId(): Promise<string>;
+    /** Get total transaction count in a batch */
+    getBatchTotalTxs(batchId: string): Promise<number>;
+    /** Get number of processed transactions in a batch */
+    getBatchProcessedCount(batchId: string): Promise<number>;
+    /** Get the ERC-20 token address for a VM31 asset ID */
+    getAssetToken(assetId: number): Promise<string>;
+    /** Get the VM31 asset ID for a given ERC-20 token address */
+    getTokenAsset(tokenAddress: string): Promise<number>;
+    /** Check if the VM31Pool contract is paused */
+    isPaused(): Promise<boolean>;
+    /** Get the contract owner address */
+    getOwner(): Promise<string>;
+    /** Get the authorized relayer address */
+    getRelayer(): Promise<string>;
+    /** Get batch timeout in blocks */
+    getBatchTimeoutBlocks(): Promise<number>;
+    /** Check relayer health (no auth required) */
+    getRelayerHealth(): Promise<{
+        status: string;
+        version: string;
+        service: string;
+    }>;
+    /** Get relayer queue status */
+    getRelayerStatus(): Promise<RelayerInfo>;
+    /** Get the relayer's public encryption key */
+    getRelayerPublicKey(): Promise<{
+        publicKey: string;
+        version: number;
+        algorithm: string;
+    }>;
+    /**
+     * 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)
+     */
+    submitDeposit(params: VaultDepositParams, encrypt?: boolean): Promise<VaultSubmitResult>;
+    /**
+     * Submit a withdrawal transaction to the relayer.
+     * Withdrawals are not denomination-restricted.
+     * @param encrypt - Set to false for legacy plaintext mode (default: true)
+     */
+    submitWithdraw(params: VaultWithdrawParams, encrypt?: boolean): Promise<VaultSubmitResult>;
+    /**
+     * Submit a private transfer transaction to the relayer.
+     * Transfers are not denomination-restricted.
+     * @param encrypt - Set to false for legacy plaintext mode (default: true)
+     */
+    submitTransfer(params: VaultTransferParams, encrypt?: boolean): Promise<VaultSubmitResult>;
+    /** Query batch info from the relayer */
+    queryBatch(batchId: string): Promise<VaultBatchInfo>;
+    /** Fetch Merkle path for a commitment from the relayer */
+    fetchMerklePath(commitment: string): Promise<{
+        commitment: string;
+        merklePath: VaultMerklePath | null;
+        merkleRoot: number[] | null;
+        batchId: string | null;
+        createdAt?: string;
+        status?: string;
+    }>;
+    /** Force the relayer to prove the current batch immediately */
+    forceProve(): Promise<{
+        status: string;
+        batchId?: string;
+    }>;
+    /** Encode a bigint amount into M31 lo/hi pair (31-bit limbs) */
+    static encodeAmountM31(amount: bigint): {
+        lo: number;
+        hi: number;
+    };
+    /** Decode an M31 lo/hi pair back into a bigint amount */
+    static decodeAmountM31(lo: number, hi: number): bigint;
+}
+
+/**
+ * VM31 Confidential Bridge Client
+ *
+ * Read-only views into the VM31Bridge contract, which facilitates
+ * bridging between the VM31 UTXO pool and the ElGamal-based
+ * ConfidentialTransfer system.
+ */
+
+interface AssetPair {
+    vm31AssetId: string;
+    confidentialAssetId: string;
+}
+interface BridgeConfig {
+    relayer: string;
+    vm31Pool: string;
+    confidentialTransfer: string;
+}
+declare class VM31BridgeClient {
+    private readonly obelysk;
+    constructor(obelysk: ObelyskClient);
+    private get contractAddress();
+    /** Get the authorized relayer address */
+    getRelayer(): Promise<string>;
+    /** Get the VM31Pool contract address */
+    getVM31Pool(): Promise<string>;
+    /** Get the ConfidentialTransfer contract address */
+    getConfidentialTransfer(): Promise<string>;
+    /** Get the asset pair mapping for a given token address */
+    getAssetPair(tokenAddress: string): Promise<AssetPair | null>;
+    /** Check if a bridge key has already been processed */
+    isBridgeKeyProcessed(bridgeKey: string): Promise<boolean>;
+    /** Compute a bridge key from withdrawal parameters */
+    computeBridgeKey(params: {
+        batchId: string;
+        withdrawalIdx: number;
+        payoutRecipient: string;
+        creditRecipient: string;
+        token: string;
+        amount: bigint;
+    }): Promise<string>;
+    /** Get full bridge configuration (relayer, vm31Pool, confidentialTransfer) */
+    getConfig(): Promise<BridgeConfig>;
+    /** Get pending upgrade info, if any */
+    getPendingUpgrade(): Promise<{
+        classHash: string;
+        scheduledAt: number;
+    } | null>;
+    /** Check if the bridge contract is paused */
+    isPaused(): Promise<boolean>;
+}
+
+/**
+ * OTC Orderbook Client
+ *
+ * On-chain limit/market order book for peer-to-peer token trading.
+ * Supports limit orders, market orders, batch operations, and
+ * real-time orderbook depth queries.
+ */
+
+declare enum OrderSide {
+    Buy = 0,
+    Sell = 1
+}
+declare enum OrderType {
+    Limit = 0,
+    Market = 1
+}
+declare enum OrderStatus {
+    Open = 0,
+    PartialFill = 1,
+    Filled = 2,
+    Cancelled = 3,
+    Expired = 4
+}
+interface TradingPair {
+    baseToken: string;
+    quoteToken: string;
+    minOrderSize: bigint;
+    tickSize: bigint;
+    isActive: boolean;
+}
+interface OTCOrder {
+    orderId: bigint;
+    maker: string;
+    pairId: number;
+    side: OrderSide;
+    orderType: OrderType;
+    price: bigint;
+    remaining: bigint;
+    amount: bigint;
+    status: OrderStatus;
+    createdAt: number;
+    expiresAt: number;
+}
+interface OTCTrade {
+    tradeId: bigint;
+    makerOrderId: bigint;
+    takerOrderId: bigint;
+    maker: string;
+    taker: string;
+    price: bigint;
+    amount: bigint;
+    quoteAmount: bigint;
+    executedAt: number;
+}
+interface OrderbookConfig {
+    makerFeeBps: number;
+    takerFeeBps: number;
+    defaultExpirySecs: number;
+    maxOrdersPerUser: number;
+    paused: boolean;
+}
+interface PlaceLimitOrderParams {
+    pairId: number;
+    side: OrderSide;
+    price: bigint;
+    amount: bigint;
+    /** Seconds until expiry. 0 or undefined uses the contract default. */
+    expiresIn?: number;
+}
+interface PlaceMarketOrderParams {
+    pairId: number;
+    side: OrderSide;
+    amount: bigint;
+}
+interface OrderbookDepthLevel {
+    price: bigint;
+    totalAmount: bigint;
+    orderCount: number;
+}
+interface OrderbookDepth {
+    bids: OrderbookDepthLevel[];
+    asks: OrderbookDepthLevel[];
+}
+interface Stats24h {
+    volume: bigint;
+    high: bigint;
+    low: bigint;
+    tradeCount: bigint;
+}
+declare class OTCOrderbookClient {
+    private readonly obelysk;
+    constructor(obelysk: ObelyskClient);
+    private get contractAddress();
+    /**
+     * Place a limit order on the orderbook.
+     *
+     * The contract handles internal matching against resting orders.
+     * Returns the transaction hash.
+     */
+    placeLimitOrder(params: PlaceLimitOrderParams): Promise<string>;
+    /**
+     * Place a market order that fills immediately against resting liquidity.
+     * Returns the transaction hash.
+     */
+    placeMarketOrder(params: PlaceMarketOrderParams): Promise<string>;
+    /**
+     * Cancel a single order by ID.
+     * Only the maker can cancel their own order.
+     */
+    cancelOrder(orderId: bigint): Promise<string>;
+    /**
+     * Cancel all open orders for the caller.
+     */
+    cancelAllOrders(): Promise<string>;
+    /**
+     * Place multiple limit orders in a single transaction.
+     *
+     * Cairo expects an array of (u8, OrderSide, u256, u256, u64) tuples.
+     * Calldata: [length, ...flattened orders].
+     */
+    batchPlaceOrders(orders: PlaceLimitOrderParams[]): Promise<string>;
+    /**
+     * Cancel multiple orders in a single transaction.
+     *
+     * Calldata: [length, ...flattened u256 order IDs].
+     */
+    batchCancelOrders(orderIds: bigint[]): Promise<string>;
+    /**
+     * Get a single order by ID.
+     */
+    getOrder(orderId: bigint): Promise<OTCOrder>;
+    /**
+     * Get all order IDs belonging to a user.
+     */
+    getUserOrders(user: string): Promise<bigint[]>;
+    /**
+     * Get the best (highest) bid price for a trading pair.
+     */
+    getBestBid(pairId: number): Promise<bigint>;
+    /**
+     * Get the best (lowest) ask price for a trading pair.
+     */
+    getBestAsk(pairId: number): Promise<bigint>;
+    /**
+     * Get the bid-ask spread for a trading pair.
+     */
+    getSpread(pairId: number): Promise<bigint>;
+    /**
+     * Get trading pair configuration.
+     */
+    getPair(pairId: number): Promise<TradingPair>;
+    /**
+     * Get the orderbook configuration (fees, limits, pause state).
+     */
+    getConfig(): Promise<OrderbookConfig>;
+    /**
+     * Get aggregate orderbook statistics.
+     */
+    getStats(): Promise<{
+        orderCount: bigint;
+        tradeCount: bigint;
+        totalVolume: bigint;
+        totalFees: bigint;
+    }>;
+    /**
+     * Get total number of orders ever placed.
+     */
+    getOrderCount(): Promise<bigint>;
+    /**
+     * Get total number of trades executed.
+     */
+    getTradeCount(): Promise<bigint>;
+    /**
+     * Get the time-weighted average price for a trading pair.
+     */
+    getTwap(pairId: number): Promise<bigint>;
+    /**
+     * Get 24-hour rolling statistics for a trading pair.
+     */
+    get24hStats(pairId: number): Promise<Stats24h>;
+    /**
+     * Get the most recent trade for a trading pair.
+     */
+    getLastTrade(pairId: number): Promise<{
+        price: bigint;
+        amount: bigint;
+        timestamp: number;
+    }>;
+    /**
+     * 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.
+     */
+    getOrderbookDepth(pairId: number, maxLevels: number): Promise<OrderbookDepth>;
+    /**
+     * Get active orders for a trading pair with pagination.
+     */
+    getActiveOrders(pairId: number, offset: number, limit: number): Promise<OTCOrder[]>;
+    /**
+     * Get trade history for a trading pair with pagination.
+     */
+    getTradeHistory(pairId: number, offset: number, limit: number): Promise<OTCTrade[]>;
+    /**
+     * Get the contract owner address.
+     */
+    getOwner(): Promise<string>;
 }
 
 /**
@@ -532,6 +1317,10 @@ interface ObelyskConfig {
     rpcUrl?: string;
     /** Optional privacy key pair (hex private key). If omitted, generated fresh. */
     privacyPrivateKey?: string;
+    /** VM31 relayer URL (default: https://relay.bitsage.network:3080) */
+    relayerUrl?: string;
+    /** VM31 relayer API key */
+    relayerApiKey?: string;
 }
 declare class ObelyskClient {
     readonly network: ObelyskNetwork;
@@ -541,6 +1330,8 @@ declare class ObelyskClient {
     readonly contracts: Record<string, string>;
     readonly tokens: Record<string, string>;
     readonly privacyPools: Record<string, string>;
+    readonly relayerUrl?: string;
+    readonly relayerApiKey?: string;
     /** Privacy Pool operations (deposit/withdraw shielded tokens) */
     readonly privacyPool: PrivacyPoolClient;
     /** DarkPool batch auction trading */
@@ -555,6 +1346,12 @@ declare class ObelyskClient {
     readonly router: PrivacyRouterClient;
     /** Shielded swap router (privacy-preserving AMM swaps) */
     readonly swap: ShieldedSwapClient;
+    /** VM31 UTXO privacy vault (deposits/withdrawals/transfers via relayer) */
+    readonly vm31: VM31VaultClient;
+    /** VM31 confidential bridge (bridge VM31 withdrawals to encrypted balances) */
+    readonly bridge: VM31BridgeClient;
+    /** OTC orderbook (limit/market orders, trade history) */
+    readonly otc: OTCOrderbookClient;
     constructor(config: ObelyskConfig);
     /** Get token address by symbol */
     getTokenAddress(symbol: string): string;
@@ -564,4 +1361,74 @@ declare class ObelyskClient {
     requireAccount(): Account;
 }
 
-export { type CommitOrderParams, ConfidentialTransferClient, DARKPOOL_ASSET_IDS, DarkPoolClient, type DarkPoolDepositParams, type DarkPoolOrderData, type DepositParams, type DepositResult, ECPoint, type EpochInfo, type GpuTier, MAINNET_PRIVACY_POOLS, MAINNET_TOKENS, ObelyskClient, type ObelyskConfig, type ObelyskNetwork, ObelyskPrivacy, type PrivacyNote, PrivacyPoolClient, PrivacyRouterClient, type PrivateAccount, ProverStakingClient, type RevealOrderParams, ShieldedSwapClient, type StakingConfig, StealthClient, type StealthMetaAddress, type StealthSendParams, TOKEN_DECIMALS, type TransferParams, VM31_ASSET_IDS, type WithdrawParams, type WithdrawResult, type WorkerStake, commitmentToHash, createAEHint, createEncryptionProof, deriveNullifier, ecAdd, ecMul, elgamalEncrypt, formatAmount, getContracts, getRpcUrl, mod, modInverse, parseAmount, pedersenCommit, randomScalar };
+/**
+ * ECIES Encryption for VM31 Relayer
+ *
+ * X25519 ECDH + HKDF-SHA256 + AES-256-GCM
+ * Compatible with the Obelysk VM31 relayer (Rust: x25519-dalek + aes-gcm + hkdf)
+ *
+ * Uses Web Crypto API (works in Node 20+ and all modern browsers).
+ */
+interface ECIESEnvelope {
+    ephemeral_pubkey: string;
+    ciphertext: string;
+    nonce: string;
+    version: number;
+}
+/**
+ * Encrypt a JSON payload for the VM31 relayer using ECIES.
+ *
+ * @param payload - The SubmitRequest object to encrypt
+ * @param relayerPubkeyHex - The relayer's X25519 public key (hex, 64 chars)
+ * @returns ECIES envelope ready to POST to /submit
+ */
+declare function eciesEncrypt(payload: unknown, relayerPubkeyHex: string): Promise<ECIESEnvelope>;
+
+/**
+ * VM31 Deposit Denomination Whitelists
+ *
+ * Privacy gap #7 mitigation: deposits must use standard denominations
+ * to prevent exact-amount correlation attacks.
+ *
+ * Only deposits are restricted — withdrawals and transfers are unrestricted.
+ */
+/** wBTC denominations (8 decimals) */
+declare const WBTC_DENOMINATIONS: readonly bigint[];
+/** SAGE denominations (18 decimals) */
+declare const SAGE_DENOMINATIONS: readonly bigint[];
+/** ETH denominations (18 decimals) */
+declare const ETH_DENOMINATIONS: readonly bigint[];
+/** STRK denominations (18 decimals) */
+declare const STRK_DENOMINATIONS: readonly bigint[];
+/** USDC denominations (6 decimals) */
+declare const USDC_DENOMINATIONS: readonly bigint[];
+/** All denomination lists by VM31 asset ID */
+declare const VM31_DENOMINATIONS: Record<number, readonly bigint[]>;
+/** Denomination lists by token symbol */
+declare const DENOMINATION_BY_SYMBOL: Record<string, readonly bigint[]>;
+/**
+ * Validate that a deposit amount is a standard denomination.
+ * Throws if the amount is not in the whitelist.
+ * Unknown assets pass through (forward-compatible).
+ *
+ * @param amount - Amount in base units (e.g., wei, satoshis)
+ * @param assetIdOrSymbol - VM31 asset ID (0-4) or token symbol
+ */
+declare function validateDenomination(amount: bigint, assetIdOrSymbol: number | string): void;
+/**
+ * Split an amount into the fewest standard denominations (greedy, largest first).
+ * Useful for automatically batching a deposit into multiple denomination-safe transactions.
+ *
+ * @returns denominations array and any remainder that can't be represented
+ */
+declare function splitIntoDenominations(amount: bigint, assetIdOrSymbol: number | string): {
+    denominations: bigint[];
+    remainder: bigint;
+};
+/**
+ * Get valid denominations for an asset.
+ * Returns undefined for unknown assets.
+ */
+declare function getDenominations(assetIdOrSymbol: number | string): readonly bigint[] | undefined;
+
+export { type AssetPair, type BatchStatus, type BridgeConfig, type ClaimFillParams, type ClaimParams, type CommitOrderParams, ConfidentialTransferClient, DARKPOOL_ASSET_IDS, DENOMINATION_BY_SYMBOL, DarkPoolClient, type DarkPoolDepositParams, type DarkPoolOrderData, type DepositParams, type DepositResult, type ECIESEnvelope, ECPoint, ETH_DENOMINATIONS, type EpochInfo, type FundParams, type GpuTier, MAINNET_PRIVACY_POOLS, MAINNET_TOKENS, type OTCOrder, OTCOrderbookClient, type OTCTrade, ObelyskClient, type ObelyskConfig, type ObelyskNetwork, ObelyskPrivacy, OrderSide, OrderStatus, OrderType, type OrderbookConfig, type OrderbookDepth, type OrderbookDepthLevel, type PackedDigest, type PlaceLimitOrderParams, type PlaceMarketOrderParams, type PrivacyNote, PrivacyPoolClient, PrivacyRouterClient, type PrivateAccount, ProverStakingClient, type RelayerInfo, type RevealOrderParams, SAGE_DENOMINATIONS, STRK_DENOMINATIONS, ShieldedSwapClient, type ShieldedSwapParams, type StakingConfig, type Stats24h, type StealthAnnouncement, StealthClient, type StealthMetaAddress, type StealthSendParams, type StealthSpendingProof, TOKEN_DECIMALS, type TradingPair, type TransferParams, USDC_DENOMINATIONS, type VM31AssetId, VM31BridgeClient, VM31VaultClient, VM31_ASSET_IDS, VM31_DENOMINATIONS, type VaultBatchInfo, type VaultDepositParams, type VaultMerklePath, type VaultNote, type VaultSubmitResult, type VaultTransferParams, type VaultWithdrawParams, WBTC_DENOMINATIONS, type WithdrawCTParams, type WithdrawParams, type WithdrawResult, type WorkerStake, commitmentToHash, createAEHint, createEncryptionProof, deriveNullifier, ecAdd, ecMul, eciesEncrypt, elgamalEncrypt, formatAmount, getContracts, getDenominations, getRpcUrl, mod, modInverse, parseAmount, pedersenCommit, randomScalar, splitIntoDenominations, validateDenomination };