@0xmonaco/core 0.8.7-develop.5d0e403 → 0.8.7-develop.a107b34

package/dist/api/vault/api.d.ts

@@ -23,9 +23,21 @@
  * console.log(`Deposit transaction: ${result.hash}`);
  * ```
  */
-import type { ApplicationsAPI, Balance, ProfileAPI, TransactionResult, VaultAPI, WithdrawResult } from "@0xmonaco/types";
+import type { ApplicationsAPI, Balance, DepositTarget, ProfileAPI, TransactionResult, VaultAPI, WithdrawalRetryOptions, WithdrawalSource, WithdrawResult } from "@0xmonaco/types";
 import { type Address, type Chain, type PublicClient, type WalletClient } from "viem";
 import { BaseAPI } from "../base";
+/**
+ * Encode the on-chain `applicationData` for a deposit.
+ *
+ * For `"spot"` (the default) this stays the bare `clientId` string — byte-for-byte
+ * identical to the legacy encoding, so existing deposits are unchanged. For
+ * `"margin"` it emits a small JSON routing hint the indexer decodes to credit the
+ * deposit to margin collateral.
+ *
+ * MUST stay in sync with the indexer decoder in
+ * `indexer/src/listeners/deposit_routing.rs`.
+ */
+export declare function encodeDepositApplicationData(clientId: string, target: DepositTarget): string;
 export declare class VaultAPIImpl extends BaseAPI implements VaultAPI {
     private readonly publicClient;
     private readonly chain;
@@ -121,6 +133,10 @@ export declare class VaultAPIImpl extends BaseAPI implements VaultAPI {
      * @param assetId - The asset identifier (UUID) to deposit
      * @param amount - The amount of tokens to deposit (as bigint)
      * @param autoWait - Whether to automatically wait for transaction confirmation (defaults to true)
+     * @param target - Destination ledger: `"spot"` (default) credits the spot
+     *   wallet; `"margin"` routes the deposit into the parent margin account's
+     *   collateral (auto-creating the account if needed). Margin deposits that
+     *   cannot be routed safely fall back to spot.
      * @returns Promise resolving to TransactionResult with transaction details
      * @throws {ContractError} When deposit fails or approval is insufficient
      * @throws {APIError} When the asset is not found or the assetId is invalid
@@ -136,6 +152,14 @@ export declare class VaultAPIImpl extends BaseAPI implements VaultAPI {
      * console.log(`Deposit transaction: ${result.hash}`);
      * console.log(`Status: ${result.status}`); // "confirmed" if successful
      *
+     * // Deposit straight into margin collateral
+     * const marginDeposit = await vaultAPI.deposit(
+     *   "123e4567-e89b-12d3-a456-426614174000",
+     *   parseUnits("100", 6),
+     *   true,
+     *   "margin"
+     * );
+     *
      * // Or skip auto-waiting
      * const result = await vaultAPI.deposit(
      *   "123e4567-e89b-12d3-a456-426614174000",
@@ -146,23 +170,41 @@ export declare class VaultAPIImpl extends BaseAPI implements VaultAPI {
      * const receipt = await sdk.waitForTransaction(result.hash);
      * ```
      */
-    deposit(assetId: string, amount: bigint, autoWait?: boolean): Promise<TransactionResult>;
+    deposit(assetId: string, amount: bigint, autoWait?: boolean, target?: DepositTarget): Promise<TransactionResult>;
+    /**
+     * Polls `GET /api/v1/withdrawals/{index}` until the gateway can serve the
+     * `executeWithdrawal` calldata, then returns it with the vault address.
+     *
+     * The calldata only exists once the withdrawal's root is confirmed on-chain
+     * and its merkle proof is persisted. Until then the gateway returns 404 (the
+     * row is written asynchronously by the persistor after `initiate`) or 409
+     * (the proof is not confirmed yet); both are transient for a freshly-allocated
+     * index, so we retry on each until ready or the timeout elapses.
+     *
+     * @throws {APIError} On non-transient errors, or when the timeout elapses
+     * before the proof is available.
+     */
+    private pollWithdrawalCalldata;
     /**
-     * Initiates a withdrawal through the API Gateway and submits the resulting
-     * pre-signed calldata on-chain via the connected wallet.
+     * Initiates a withdrawal through the API Gateway, waits for its on-chain
+     * confirmation, then submits the resulting `executeWithdrawal` calldata via
+     * the connected wallet.
      *
-     * The gateway allocates a `withdrawalIndex` via the matching engine and returns
-     * ABI-encoded calldata for `executeSignedWithdrawal(...)` signed by the
-     * server-side `WITHDRAWAL_SIGNER`. The user's wallet pays gas to submit it,
-     * but the contract authenticates against the embedded signature — not the
-     * `msg.sender`. The connected wallet's address is sent as the on-chain
-     * `destination`.
+     * The gateway allocates a `withdrawalIndex` via the matching engine and debits
+     * the balance immediately, but the executable calldata needs the withdrawal's
+     * merkle proof, which only exists once its root is confirmed on-chain. This
+     * method polls until the calldata is available (see `retry`), then submits it.
+     * The connected wallet pays gas; the contract authorises the withdrawal
+     * against the merkle proof embedded in the calldata. The wallet's address is
+     * sent as the on-chain `destination`.
      *
      * @param assetId - The asset identifier (UUID) to withdraw
      * @param amount - The raw token amount to withdraw (as bigint)
      * @param autoWait - Whether to automatically wait for transaction confirmation (defaults to true)
+     * @param sourceOrRetry - Source ledger (`"spot"` or `"margin"`) or legacy retry options
+     * @param retry - Polling cadence/timeout while waiting for the proof when a source is supplied
      * @returns Promise resolving to `{ withdrawalIndex, transaction }`
-     * @throws {APIError} When the asset is not found or the request is rejected
+     * @throws {APIError} When the asset is not found, the request is rejected, or the proof never becomes available within the timeout
      * @throws {ContractError} When the on-chain submission fails
      * @throws {InvalidConfigError} When wallet account is not available
      *
@@ -176,36 +218,38 @@ export declare class VaultAPIImpl extends BaseAPI implements VaultAPI {
      * console.log(`Withdrawal index: ${result.withdrawalIndex}`);
      * console.log(`Tx hash: ${result.hash}, status: ${result.status}`);
      *
-     * // Or skip auto-waiting and finalise later
+     * // Custom polling (check every 10s, wait up to an hour)
      * const result = await vaultAPI.withdraw(
      *   "123e4567-e89b-12d3-a456-426614174000",
      *   parseUnits("50", 6),
-     *   false,
+     *   true,
+     *   { pollIntervalMs: 10_000, timeoutMs: 3_600_000 },
      * );
-     * const receipt = await sdk.waitForTransaction(result.hash);
      * ```
      */
-    withdraw(assetId: string, amount: bigint, autoWait?: boolean): Promise<WithdrawResult>;
+    withdraw(assetId: string, amount: bigint, autoWait?: boolean, sourceOrRetry?: WithdrawalSource | WithdrawalRetryOptions, retry?: WithdrawalRetryOptions): Promise<WithdrawResult>;
     /**
-     * Retries a previously-initiated withdrawal whose on-chain submission never
-     * landed — e.g. the wallet rejected the tx, the page reloaded before the
-     * receipt came back, or a stuck mempool entry needs resending.
+     * Submits (or resubmits) a previously-initiated withdrawal on-chain.
      *
-     * Re-fetches the same `executeSignedWithdrawal` calldata the gateway
-     * generated when the withdrawal was initiated, then submits it through the
-     * connected wallet. Does NOT initiate a new withdrawal — the matching engine
-     * already debited the balance and allocated the index. The contract is
-     * idempotent against double-submission of a settled withdrawal: it will
-     * revert once the index is consumed on-chain.
+     * Use this when the original `withdraw()` could not complete — e.g. the proof
+     * was not yet confirmed within its polling window, the wallet rejected the tx,
+     * the page reloaded before the receipt came back, or a stuck mempool entry
+     * needs resending. Polls `GET /withdrawals/{index}` for the
+     * `executeWithdrawal` calldata (retrying while it is not yet confirmed), then
+     * submits it through the connected wallet. Does NOT initiate a new withdrawal
+     * — the matching engine already debited the balance and allocated the index.
+     * The contract is idempotent against double-submission of a settled
+     * withdrawal: it reverts once the index is consumed on-chain.
      *
      * @param withdrawalIndex - The index returned by the original `withdraw()` call
      * @param autoWait - Whether to await on-chain confirmation (defaults to true)
+     * @param retry - Polling cadence/timeout while waiting for the proof
      * @returns Promise resolving to `{ withdrawalIndex, ...transaction }`
-     * @throws {APIError} When the index doesn't exist
+     * @throws {APIError} When the index doesn't exist or the proof never becomes available within the timeout
      * @throws {ContractError} When the on-chain submission fails
      * @throws {InvalidConfigError} When wallet account is not available
      */
-    retryWithdrawal(withdrawalIndex: number, autoWait?: boolean): Promise<WithdrawResult>;
+    retryWithdrawal(withdrawalIndex: number, autoWait?: boolean, retry?: WithdrawalRetryOptions): Promise<WithdrawResult>;
     /**
      * Retrieves the user's token balance in the vault.
      *

package/dist/api/vault/api.js

@@ -28,6 +28,25 @@ import { ApproveTokenSchema, DepositSchema, validate, WithdrawSchema } from "@0x
 import { erc20Abi, zeroAddress } from "viem";
 import { APIError, ContractError, InvalidConfigError } from "../../errors";
 import { BaseAPI } from "../base";
+/** Default delay between polls while waiting for a withdrawal's proof. */
+const DEFAULT_WITHDRAWAL_POLL_INTERVAL_MS = 5_000;
+/** Default total wait for a withdrawal's proof (1 minute). */
+const DEFAULT_WITHDRAWAL_TIMEOUT_MS = 60_000;
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+ * Encode the on-chain `applicationData` for a deposit.
+ *
+ * For `"spot"` (the default) this stays the bare `clientId` string — byte-for-byte
+ * identical to the legacy encoding, so existing deposits are unchanged. For
+ * `"margin"` it emits a small JSON routing hint the indexer decodes to credit the
+ * deposit to margin collateral.
+ *
+ * MUST stay in sync with the indexer decoder in
+ * `indexer/src/listeners/deposit_routing.rs`.
+ */
+export function encodeDepositApplicationData(clientId, target) {
+    return target === "margin" ? JSON.stringify({ clientId, depositTarget: "MARGIN" }) : clientId;
+}
 export class VaultAPIImpl extends BaseAPI {
     publicClient;
     chain;
@@ -196,6 +215,10 @@ export class VaultAPIImpl extends BaseAPI {
      * @param assetId - The asset identifier (UUID) to deposit
      * @param amount - The amount of tokens to deposit (as bigint)
      * @param autoWait - Whether to automatically wait for transaction confirmation (defaults to true)
+     * @param target - Destination ledger: `"spot"` (default) credits the spot
+     *   wallet; `"margin"` routes the deposit into the parent margin account's
+     *   collateral (auto-creating the account if needed). Margin deposits that
+     *   cannot be routed safely fall back to spot.
      * @returns Promise resolving to TransactionResult with transaction details
      * @throws {ContractError} When deposit fails or approval is insufficient
      * @throws {APIError} When the asset is not found or the assetId is invalid
@@ -211,6 +234,14 @@ export class VaultAPIImpl extends BaseAPI {
      * console.log(`Deposit transaction: ${result.hash}`);
      * console.log(`Status: ${result.status}`); // "confirmed" if successful
      *
+     * // Deposit straight into margin collateral
+     * const marginDeposit = await vaultAPI.deposit(
+     *   "123e4567-e89b-12d3-a456-426614174000",
+     *   parseUnits("100", 6),
+     *   true,
+     *   "margin"
+     * );
+     *
      * // Or skip auto-waiting
      * const result = await vaultAPI.deposit(
      *   "123e4567-e89b-12d3-a456-426614174000",
@@ -221,14 +252,17 @@ export class VaultAPIImpl extends BaseAPI {
      * const receipt = await sdk.waitForTransaction(result.hash);
      * ```
      */
-    async deposit(assetId, amount, autoWait = true) {
+    async deposit(assetId, amount, autoWait = true, target = "spot") {
         if (!this.walletClient) {
             throw new InvalidConfigError("Wallet client not set. Connect a wallet first.", "walletClient");
         }
         // Validate inputs
-        validate(DepositSchema, { assetId, amount, autoWait });
+        validate(DepositSchema, { assetId, amount, autoWait, target });
         const vaultAddress = await this.getVaultAddress();
         const clientId = await this.getClientId();
+        // The on-chain applicationData carries the client id plus, for margin
+        // deposits, the routing hint the indexer decodes.
+        const applicationData = encodeDepositApplicationData(clientId, target);
         const { tokenAddress, isNativeToken } = await this.resolveAsset(assetId);
         if (!isNativeToken) {
             // Check if approval is needed before proceeding
@@ -250,7 +284,7 @@ export class VaultAPIImpl extends BaseAPI {
                 address: vaultAddress,
                 abi: CONTRACT_ABIS.vault,
                 functionName: "depositNative",
-                args: [walletAccount.address, clientId],
+                args: [walletAccount.address, applicationData],
                 account: walletAccount,
                 chain: this.chain,
                 value: amount,
@@ -261,7 +295,7 @@ export class VaultAPIImpl extends BaseAPI {
                 address: vaultAddress,
                 abi: CONTRACT_ABIS.vault,
                 functionName: "depositERC20",
-                args: [walletAccount.address, clientId, tokenAddress, amount],
+                args: [walletAccount.address, applicationData, tokenAddress, amount],
                 account: walletAccount,
                 chain: this.chain,
             });
@@ -275,21 +309,65 @@ export class VaultAPIImpl extends BaseAPI {
         return await this.waitForTransaction(txResult, autoWait);
     }
     /**
-     * Initiates a withdrawal through the API Gateway and submits the resulting
-     * pre-signed calldata on-chain via the connected wallet.
+     * Polls `GET /api/v1/withdrawals/{index}` until the gateway can serve the
+     * `executeWithdrawal` calldata, then returns it with the vault address.
      *
-     * The gateway allocates a `withdrawalIndex` via the matching engine and returns
-     * ABI-encoded calldata for `executeSignedWithdrawal(...)` signed by the
-     * server-side `WITHDRAWAL_SIGNER`. The user's wallet pays gas to submit it,
-     * but the contract authenticates against the embedded signature — not the
-     * `msg.sender`. The connected wallet's address is sent as the on-chain
-     * `destination`.
+     * The calldata only exists once the withdrawal's root is confirmed on-chain
+     * and its merkle proof is persisted. Until then the gateway returns 404 (the
+     * row is written asynchronously by the persistor after `initiate`) or 409
+     * (the proof is not confirmed yet); both are transient for a freshly-allocated
+     * index, so we retry on each until ready or the timeout elapses.
+     *
+     * @throws {APIError} On non-transient errors, or when the timeout elapses
+     * before the proof is available.
+     */
+    async pollWithdrawalCalldata(withdrawalIndex, retry) {
+        const pollIntervalMs = retry?.pollIntervalMs ?? DEFAULT_WITHDRAWAL_POLL_INTERVAL_MS;
+        const timeoutMs = retry?.timeoutMs ?? DEFAULT_WITHDRAWAL_TIMEOUT_MS;
+        const deadline = Date.now() + timeoutMs;
+        for (;;) {
+            try {
+                const { vault_address: vaultAddress, calldata } = await this.makePublicRequest(`/api/v1/withdrawals/${withdrawalIndex}`);
+                // Ready: non-empty calldata. (Defensively treat an empty/`0x` body as
+                // not-ready too, though the gateway returns an error in that case.)
+                if (calldata && calldata !== "0x") {
+                    return { vaultAddress, calldata };
+                }
+            }
+            catch (error) {
+                // 404 (row not persisted yet) and 409 (proof not confirmed yet) are
+                // transient for a valid index — keep polling. Anything else is fatal.
+                const isTransient = error instanceof APIError && (error.statusCode === 404 || error.statusCode === 409);
+                if (!isTransient) {
+                    throw error;
+                }
+            }
+            if (Date.now() + pollIntervalMs > deadline) {
+                throw new APIError(`Withdrawal ${withdrawalIndex} proof not available after ${timeoutMs}ms; it may not be confirmed on-chain yet — retry later via retryWithdrawal(${withdrawalIndex})`, { statusCode: 409 });
+            }
+            await sleep(pollIntervalMs);
+        }
+    }
+    /**
+     * Initiates a withdrawal through the API Gateway, waits for its on-chain
+     * confirmation, then submits the resulting `executeWithdrawal` calldata via
+     * the connected wallet.
+     *
+     * The gateway allocates a `withdrawalIndex` via the matching engine and debits
+     * the balance immediately, but the executable calldata needs the withdrawal's
+     * merkle proof, which only exists once its root is confirmed on-chain. This
+     * method polls until the calldata is available (see `retry`), then submits it.
+     * The connected wallet pays gas; the contract authorises the withdrawal
+     * against the merkle proof embedded in the calldata. The wallet's address is
+     * sent as the on-chain `destination`.
      *
      * @param assetId - The asset identifier (UUID) to withdraw
      * @param amount - The raw token amount to withdraw (as bigint)
      * @param autoWait - Whether to automatically wait for transaction confirmation (defaults to true)
+     * @param sourceOrRetry - Source ledger (`"spot"` or `"margin"`) or legacy retry options
+     * @param retry - Polling cadence/timeout while waiting for the proof when a source is supplied
      * @returns Promise resolving to `{ withdrawalIndex, transaction }`
-     * @throws {APIError} When the asset is not found or the request is rejected
+     * @throws {APIError} When the asset is not found, the request is rejected, or the proof never becomes available within the timeout
      * @throws {ContractError} When the on-chain submission fails
      * @throws {InvalidConfigError} When wallet account is not available
      *
@@ -303,16 +381,16 @@ export class VaultAPIImpl extends BaseAPI {
      * console.log(`Withdrawal index: ${result.withdrawalIndex}`);
      * console.log(`Tx hash: ${result.hash}, status: ${result.status}`);
      *
-     * // Or skip auto-waiting and finalise later
+     * // Custom polling (check every 10s, wait up to an hour)
      * const result = await vaultAPI.withdraw(
      *   "123e4567-e89b-12d3-a456-426614174000",
      *   parseUnits("50", 6),
-     *   false,
+     *   true,
+     *   { pollIntervalMs: 10_000, timeoutMs: 3_600_000 },
      * );
-     * const receipt = await sdk.waitForTransaction(result.hash);
      * ```
      */
-    async withdraw(assetId, amount, autoWait = true) {
+    async withdraw(assetId, amount, autoWait = true, sourceOrRetry, retry) {
         if (!this.walletClient) {
             throw new InvalidConfigError("Wallet client not set. Connect a wallet first.", "walletClient");
         }
@@ -321,21 +399,26 @@ export class VaultAPIImpl extends BaseAPI {
             throw new InvalidConfigError("No account available in wallet client", "account");
         }
         const destination = walletAccount.address.toLowerCase();
-        validate(WithdrawSchema, { assetId, amount, destination, autoWait });
-        // 1. Gateway allocates withdrawal_index + returns pre-signed
-        // executeSignedWithdrawal calldata along with the vault address to send
-        // it to. Sourcing the vault address from this response (instead of
-        // GET /applications/config) keeps the calldata + target contract in
-        // lockstep and avoids an extra round-trip.
-        const { withdrawal_index: withdrawalIndex, vault_address: vaultAddress, calldata, } = await this.makeAuthenticatedRequest("/api/v1/withdrawals", {
+        const source = typeof sourceOrRetry === "string" ? sourceOrRetry : "spot";
+        const retryOptions = typeof sourceOrRetry === "string" ? retry : sourceOrRetry;
+        validate(WithdrawSchema, { assetId, amount, destination, autoWait, source });
+        // 1. Gateway allocates the withdrawal_index and debits the balance. No
+        // executable calldata yet — it needs the merkle proof, available only once
+        // the withdrawal root is confirmed on-chain.
+        const { withdrawal_index: withdrawalIndex } = await this.makeAuthenticatedRequest("/api/v1/withdrawals", {
             method: "POST",
             body: JSON.stringify({
                 asset_id: assetId,
                 amount: amount.toString(),
                 destination,
+                source,
             }),
         });
-        // 2. Submit the calldata on-chain through the connected wallet.
+        // 2. Poll for the executeWithdrawal calldata until the proof is confirmed.
+        // The vault address comes back with it, keeping calldata + target contract
+        // in lockstep.
+        const { vaultAddress, calldata } = await this.pollWithdrawalCalldata(withdrawalIndex, retryOptions);
+        // 3. Submit the calldata on-chain through the connected wallet.
         let hash;
         try {
             hash = await this.walletClient.sendTransaction({
@@ -346,7 +429,7 @@ export class VaultAPIImpl extends BaseAPI {
             });
         }
         catch (error) {
-            throw new ContractError(`Failed to submit executeSignedWithdrawal for withdrawal ${withdrawalIndex}: ${error instanceof Error ? error.message : "unknown error"}`, { cause: error instanceof Error ? error : undefined });
+            throw new ContractError(`Failed to submit executeWithdrawal for withdrawal ${withdrawalIndex}: ${error instanceof Error ? error.message : "unknown error"}`, { cause: error instanceof Error ? error : undefined });
         }
         const nonce = walletAccount.getNonce ? await walletAccount.getNonce() : 0n;
         const txResult = {
@@ -358,25 +441,27 @@ export class VaultAPIImpl extends BaseAPI {
         return { ...settled, withdrawalIndex };
     }
     /**
-     * Retries a previously-initiated withdrawal whose on-chain submission never
-     * landed — e.g. the wallet rejected the tx, the page reloaded before the
-     * receipt came back, or a stuck mempool entry needs resending.
+     * Submits (or resubmits) a previously-initiated withdrawal on-chain.
      *
-     * Re-fetches the same `executeSignedWithdrawal` calldata the gateway
-     * generated when the withdrawal was initiated, then submits it through the
-     * connected wallet. Does NOT initiate a new withdrawal — the matching engine
-     * already debited the balance and allocated the index. The contract is
-     * idempotent against double-submission of a settled withdrawal: it will
-     * revert once the index is consumed on-chain.
+     * Use this when the original `withdraw()` could not complete — e.g. the proof
+     * was not yet confirmed within its polling window, the wallet rejected the tx,
+     * the page reloaded before the receipt came back, or a stuck mempool entry
+     * needs resending. Polls `GET /withdrawals/{index}` for the
+     * `executeWithdrawal` calldata (retrying while it is not yet confirmed), then
+     * submits it through the connected wallet. Does NOT initiate a new withdrawal
+     * — the matching engine already debited the balance and allocated the index.
+     * The contract is idempotent against double-submission of a settled
+     * withdrawal: it reverts once the index is consumed on-chain.
      *
      * @param withdrawalIndex - The index returned by the original `withdraw()` call
      * @param autoWait - Whether to await on-chain confirmation (defaults to true)
+     * @param retry - Polling cadence/timeout while waiting for the proof
      * @returns Promise resolving to `{ withdrawalIndex, ...transaction }`
-     * @throws {APIError} When the index doesn't exist
+     * @throws {APIError} When the index doesn't exist or the proof never becomes available within the timeout
      * @throws {ContractError} When the on-chain submission fails
      * @throws {InvalidConfigError} When wallet account is not available
      */
-    async retryWithdrawal(withdrawalIndex, autoWait = true) {
+    async retryWithdrawal(withdrawalIndex, autoWait = true, retry) {
         if (!this.walletClient) {
             throw new InvalidConfigError("Wallet client not set. Connect a wallet first.", "walletClient");
         }
@@ -384,7 +469,7 @@ export class VaultAPIImpl extends BaseAPI {
         if (!walletAccount) {
             throw new InvalidConfigError("No account available in wallet client", "account");
         }
-        const { vault_address: vaultAddress, calldata } = await this.makePublicRequest(`/api/v1/withdrawals/${withdrawalIndex}`);
+        const { vaultAddress, calldata } = await this.pollWithdrawalCalldata(withdrawalIndex, retry);
         let hash;
         try {
             hash = await this.walletClient.sendTransaction({
@@ -395,7 +480,7 @@ export class VaultAPIImpl extends BaseAPI {
             });
         }
         catch (error) {
-            throw new ContractError(`Failed to resubmit executeSignedWithdrawal for withdrawal ${withdrawalIndex}: ${error instanceof Error ? error.message : "unknown error"}`, { cause: error instanceof Error ? error : undefined });
+            throw new ContractError(`Failed to resubmit executeWithdrawal for withdrawal ${withdrawalIndex}: ${error instanceof Error ? error.message : "unknown error"}`, { cause: error instanceof Error ? error : undefined });
         }
         const nonce = walletAccount.getNonce ? await walletAccount.getNonce() : 0n;
         const txResult = {

package/dist/api/vault/index.d.ts

@@ -1,4 +1,4 @@
 /**
  * Vault API Module
  */
-export { VaultAPIImpl } from "./api";
+export { encodeDepositApplicationData, VaultAPIImpl } from "./api";

package/dist/api/vault/index.js

@@ -1,4 +1,4 @@
 /**
  * Vault API Module
  */
-export { VaultAPIImpl } from "./api";
+export { encodeDepositApplicationData, VaultAPIImpl } from "./api";

package/dist/api/withdrawals/api.d.ts

@@ -4,10 +4,12 @@ import { BaseAPI } from "../base";
  * Low-level withdrawals client.
  *
  * `initiateWithdrawal` debits the caller's balance via the matching engine and
- * returns the target vault address plus pre-signed `executeSignedWithdrawal`
- * calldata; `getWithdrawal` re-fetches that calldata for a previously-initiated
- * index. Neither submits on-chain — use the high-level vault API for the flow
- * that also broadcasts the transaction.
+ * allocates a `withdrawal_index` (its `calldata` is empty — the proof is not
+ * available until the withdrawal root is confirmed on-chain). `getWithdrawal`
+ * returns the `executeWithdrawal` calldata once that proof is ready, and throws
+ * an `APIError` (404 not-persisted-yet / 409 not-confirmed-yet) while it is not.
+ * Neither submits on-chain — use the high-level vault API, which polls for the
+ * calldata and broadcasts the transaction.
  */
 export declare class WithdrawalsAPIImpl extends BaseAPI implements WithdrawalsAPI {
     initiateWithdrawal(request: InitiateWithdrawalRequest): Promise<WithdrawalResponse>;

package/dist/api/withdrawals/api.js

@@ -4,10 +4,12 @@ import { perpRoutes } from "../perp";
  * Low-level withdrawals client.
  *
  * `initiateWithdrawal` debits the caller's balance via the matching engine and
- * returns the target vault address plus pre-signed `executeSignedWithdrawal`
- * calldata; `getWithdrawal` re-fetches that calldata for a previously-initiated
- * index. Neither submits on-chain — use the high-level vault API for the flow
- * that also broadcasts the transaction.
+ * allocates a `withdrawal_index` (its `calldata` is empty — the proof is not
+ * available until the withdrawal root is confirmed on-chain). `getWithdrawal`
+ * returns the `executeWithdrawal` calldata once that proof is ready, and throws
+ * an `APIError` (404 not-persisted-yet / 409 not-confirmed-yet) while it is not.
+ * Neither submits on-chain — use the high-level vault API, which polls for the
+ * calldata and broadcasts the transaction.
  */
 export class WithdrawalsAPIImpl extends BaseAPI {
     async initiateWithdrawal(request) {
@@ -17,6 +19,7 @@ export class WithdrawalsAPIImpl extends BaseAPI {
                 asset_id: request.assetId,
                 amount: request.amount,
                 destination: request.destination,
+                source: request.source ?? "spot",
             }),
         });
     }

package/dist/coverage.d.ts

@@ -1,7 +1,92 @@
+/** operationId → the @0xmonaco/core client method that covers it. */
+export declare const COVERED: {
+    add_position_margin: string;
+    attach_position_tp_sl: string;
+    batch_cancel_all: string;
+    batch_cancel_all_by_pair: string;
+    batch_cancel_orders: string;
+    batch_close_all_positions: string;
+    batch_create_orders: string;
+    batch_replace_orders: string;
+    cancel_conditional_order: string;
+    cancel_order: string;
+    close_position: string;
+    create_challenge: string;
+    create_delegated_session: string;
+    create_order: string;
+    create_sub_account_limit: string;
+    delete_sub_account_limit: string;
+    get_application_config: string;
+    get_application_stats: string;
+    get_available_collateral: string;
+    get_candles: string;
+    get_funding_state: string;
+    get_index_price: string;
+    get_margin_account_movements: string;
+    get_margin_account_summary: string;
+    get_mark_price: string;
+    get_market_metadata: string;
+    get_market_stats: string;
+    get_open_interest: string;
+    get_order_by_id: string;
+    get_orderbook_snapshot: string;
+    get_orders: string;
+    get_perp_market_config: string;
+    get_perp_market_summary: string;
+    get_portfolio_chart: string;
+    get_portfolio_stats: string;
+    get_position: string;
+    get_position_risk: string;
+    get_parent_margin_account_movements: string;
+    get_parent_margin_account_summary: string;
+    get_screener: string;
+    get_sub_account_limits: string;
+    get_trade_by_id: string;
+    get_trades: string;
+    get_trading_pair_by_id: string;
+    get_user_balance_by_asset: string;
+    get_user_balances: string;
+    get_user_movements: string;
+    get_user_profile: string;
+    get_user_trades: string;
+    get_withdrawal: string;
+    initiate_withdrawal: string;
+    list_application_balances: string;
+    list_application_movements: string;
+    list_application_orders: string;
+    list_application_users: string;
+    list_conditional_orders: string;
+    list_delegated_agent_owners: string;
+    list_delegated_agents: string;
+    list_funding_history: string;
+    list_funding_payments: string;
+    list_margin_accounts: string;
+    list_position_history: string;
+    list_positions: string;
+    list_sub_accounts_with_balances: string;
+    list_trading_pairs: string;
+    mint_tokens: string;
+    reduce_position_margin: string;
+    refresh_session: string;
+    replace_order: string;
+    revoke_delegated_agent: string;
+    revoke_session: string;
+    simulate_risk_bucket_order_risk: string;
+    simulate_fees: string;
+    simulate_order_risk: string;
+    simulate_parent_margin_order_risk: string;
+    submit_whitelist: string;
+    transfer_collateral_from_parent_margin_account: string;
+    transfer_collateral_from_margin_account: string;
+    transfer_collateral_to_margin_account: string;
+    transfer_collateral_to_parent_margin_account: string;
+    transfer_collateral_to_risk_bucket: string;
+    update_sub_account_limit: string;
+    upsert_delegated_agent: string;
+    verify_signature: string;
+};
 /** operationId → reason it is intentionally not covered by @0xmonaco/core. */
 export declare const INTENTIONALLY_EXCLUDED: {
     authenticate_backend: string;
     health_check: string;
-    list_funding_payments: string;
-    list_user_trades: string;
 };