@0xmonaco/core 0.7.7 → 0.7.8

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

@@ -0,0 +1,261 @@
+/**
+ * Vault API Implementation
+ *
+ * Handles vault operations including deposits, withdrawals, and ERC20 approvals.
+ * Implements the signature flow for deposit/withdraw operations via API Gateway.
+ *
+ * This class provides a complete interface for interacting with the Monaco vault contract,
+ * including token approvals, deposits, withdrawals, and balance queries. All operations
+ * use EIP-712 signatures for security and go through the API Gateway for validation.
+ *
+ * @example
+ * ```typescript
+ * const vaultAPI = new VaultAPIImpl(
+ *   publicClient,
+ *   walletClient,
+ *   vaultAddress,
+ *   apiUrl,
+ *   chain
+ * );
+ *
+ * // Deposit tokens
+ * const result = await vaultAPI.deposit(tokenAddress, parseEther("100"));
+ * console.log(`Deposit transaction: ${result.hash}`);
+ * ```
+ */
+import type { ApplicationsAPI, Balance, ProfileAPI, TransactionResult, VaultAPI, WithdrawResult } from "@0xmonaco/types";
+import { type Address, type Chain, type PublicClient, type WalletClient } from "viem";
+import { BaseAPI } from "../base";
+export declare class VaultAPIImpl extends BaseAPI implements VaultAPI {
+    private readonly publicClient;
+    private readonly chain;
+    private applicationsAPI;
+    private profileAPI;
+    private walletClient;
+    /**
+     * Creates a new VaultAPI instance.
+     *
+     * @param publicClient - The viem public client for reading blockchain state
+     * @param walletClient - The viem wallet client for signing transactions (optional)
+     * @param chain - The blockchain network configuration
+     * @param applicationsAPI - The applications API instance for fetching vault address
+     * @param profileAPI - The profile API instance for fetching asset information
+     * @param apiUrl - The base URL for the Monaco API Gateway
+     */
+    constructor(publicClient: PublicClient, walletClient: WalletClient | undefined, chain: Chain, applicationsAPI: ApplicationsAPI, profileAPI: ProfileAPI, apiUrl: string);
+    /**
+     * Sets the wallet client for signing transactions.
+     * Used when the wallet becomes available after SDK initialization.
+     */
+    setWalletClient(walletClient: WalletClient): void;
+    /**
+     * Fetches the vault contract address from the applications API.
+     *
+     * @returns Promise resolving to the vault contract address
+     * @throws {APIError} When vault address cannot be retrieved
+     * @private
+     */
+    getVaultAddress(): Promise<Address>;
+    /**
+     * Fetches the application's client ID from the applications API.
+     * The client ID is embedded in on-chain deposit calls so the indexer can
+     * attribute the deposit to the correct application.
+     *
+     * @returns Promise resolving to the application client ID
+     * @private
+     */
+    private getClientId;
+    /**
+     * Resolves an asset ID to its token address and determines if it's a native token.
+     *
+     * @param assetId - The asset identifier (UUID) to resolve
+     * @returns Promise resolving to object with tokenAddress and isNativeToken flag
+     * @throws {ContractError} When asset ID cannot be resolved
+     * @private
+     */
+    private resolveAsset;
+    /**
+     * Approves the vault contract to spend tokens on behalf of the user.
+     *
+     * This method creates and sends an ERC20 approve transaction to allow the vault
+     * to transfer tokens from the user's wallet. Approval is required before any
+     * deposit operations can be performed.
+     *
+     * @param assetId - The asset identifier (UUID) to approve
+     * @param amount - The maximum amount of tokens the vault can spend (as bigint)
+     * @param autoWait - Whether to automatically wait for transaction confirmation (defaults to true)
+     * @returns Promise resolving to TransactionResult with transaction details
+     * @throws {ContractError} When approval transaction fails or asset not found
+     * @throws {InvalidConfigError} When wallet account is not available
+     *
+     * @example
+     * ```typescript
+     * // Approve vault to spend up to 1000 USDC (auto-waits by default)
+     * const result = await vaultAPI.approve(
+     *   "123e4567-e89b-12d3-a456-426614174000",
+     *   parseUnits("1000", 6)
+     * );
+     * console.log(`Approval transaction: ${result.hash}`);
+     * console.log(`Status: ${result.status}`); // "confirmed" if successful
+     *
+     * // Or skip auto-waiting
+     * const result = await vaultAPI.approve(
+     *   "123e4567-e89b-12d3-a456-426614174000",
+     *   parseUnits("1000", 6),
+     *   false
+     * );
+     * // Then manually wait later if needed
+     * const receipt = await sdk.waitForTransaction(result.hash);
+     * ```
+     */
+    approve(assetId: string, amount: bigint, autoWait?: boolean): Promise<TransactionResult>;
+    /**
+     * Deposits tokens into the Monaco vault.
+     *
+     * Deposits the specified amount of tokens into the vault contract. The method
+     * first checks if sufficient approval exists, then obtains a signature from the
+     * API Gateway, and finally executes the deposit transaction on-chain.
+     *
+     * Note: This method requires prior approval via the `approve()` method.
+     *
+     * @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)
+     * @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
+     * @throws {InvalidConfigError} When wallet account is not available
+     *
+     * @example
+     * ```typescript
+     * // Deposit 100 USDC into the vault (auto-waits by default)
+     * const result = await vaultAPI.deposit(
+     *   "123e4567-e89b-12d3-a456-426614174000",
+     *   parseUnits("100", 6)
+     * );
+     * console.log(`Deposit transaction: ${result.hash}`);
+     * console.log(`Status: ${result.status}`); // "confirmed" if successful
+     *
+     * // Or skip auto-waiting
+     * const result = await vaultAPI.deposit(
+     *   "123e4567-e89b-12d3-a456-426614174000",
+     *   parseUnits("100", 6),
+     *   false
+     * );
+     * // Then manually wait later if needed
+     * const receipt = await sdk.waitForTransaction(result.hash);
+     * ```
+     */
+    deposit(assetId: string, amount: bigint, autoWait?: boolean): Promise<TransactionResult>;
+    /**
+     * Initiates a withdrawal through the API Gateway and submits the resulting
+     * pre-signed calldata on-chain 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`.
+     *
+     * @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)
+     * @returns Promise resolving to `{ withdrawalIndex, transaction }`
+     * @throws {APIError} When the asset is not found or the request is rejected
+     * @throws {ContractError} When the on-chain submission fails
+     * @throws {InvalidConfigError} When wallet account is not available
+     *
+     * @example
+     * ```typescript
+     * // Withdraw 50 USDC, wait for on-chain confirmation
+     * const result = await vaultAPI.withdraw(
+     *   "123e4567-e89b-12d3-a456-426614174000",
+     *   parseUnits("50", 6),
+     * );
+     * console.log(`Withdrawal index: ${result.withdrawalIndex}`);
+     * console.log(`Tx hash: ${result.hash}, status: ${result.status}`);
+     *
+     * // Or skip auto-waiting and finalise later
+     * const result = await vaultAPI.withdraw(
+     *   "123e4567-e89b-12d3-a456-426614174000",
+     *   parseUnits("50", 6),
+     *   false,
+     * );
+     * const receipt = await sdk.waitForTransaction(result.hash);
+     * ```
+     */
+    withdraw(assetId: string, amount: bigint, autoWait?: boolean): 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.
+     *
+     * 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.
+     *
+     * @param withdrawalIndex - The index returned by the original `withdraw()` call
+     * @param autoWait - Whether to await on-chain confirmation (defaults to true)
+     * @returns Promise resolving to `{ withdrawalIndex, ...transaction }`
+     * @throws {APIError} When the index doesn't exist
+     * @throws {ContractError} When the on-chain submission fails
+     * @throws {InvalidConfigError} When wallet account is not available
+     */
+    retryWithdrawal(withdrawalIndex: number, autoWait?: boolean): Promise<WithdrawResult>;
+    /**
+     * Retrieves the user's token balance in the vault.
+     *
+     * @param _assetId - The asset identifier (UUID) to check balance for
+     * @returns Promise that always rejects with deprecation error
+     * @throws {APIError} Always throws - this method is deprecated
+     * @deprecated Use `profileAPI.getUserBalances()` or `profileAPI.getUserBalanceByAssetId()` instead.
+     */
+    getBalance(_assetId: string): Promise<Balance>;
+    /**
+     * Retrieves the current allowance for a token.
+     *
+     * Queries the ERC20 token contract to get the current allowance granted to the
+     * vault contract for spending tokens on behalf of the user.
+     *
+     * @param assetId - The asset identifier (UUID) to check allowance for
+     * @returns Promise resolving to the current allowance amount as bigint
+     * @throws {ContractError} When allowance retrieval fails or asset not found
+     *
+     * @example
+     * ```typescript
+     * const allowance = await vaultAPI.getAllowance("123e4567-e89b-12d3-a456-426614174000");
+     * console.log(`Current allowance: ${formatUnits(allowance, 6)} USDC`);
+     * ```
+     */
+    getAllowance(assetId: string): Promise<bigint>;
+    /**
+     * Checks if approval is needed for a specific amount.
+     *
+     * Compares the current allowance with the requested amount to determine if
+     * the user needs to approve more tokens before performing operations.
+     *
+     * @param assetId - The asset identifier (UUID) to check for
+     * @param amount - The amount to check approval for (as bigint)
+     * @returns Promise resolving to true if approval is needed, false otherwise
+     * @throws {ContractError} When approval check fails or asset not found
+     *
+     * @example
+     * ```typescript
+     * const needsApproval = await vaultAPI.needsApproval(
+     *   "123e4567-e89b-12d3-a456-426614174000",
+     *   parseUnits("100", 6)
+     * );
+     *
+     * if (needsApproval) {
+     *   console.log("Approval required before deposit");
+     *   await vaultAPI.approve("123e4567-e89b-12d3-a456-426614174000", parseUnits("100", 6));
+     * }
+     * ```
+     */
+    needsApproval(assetId: string, amount: bigint): Promise<boolean>;
+    private waitForTransaction;
+}