@0xmonaco/core 0.0.0-develop-20260120180031

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

@@ -0,0 +1,257 @@
+/**
+ * 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
+ * );
+ *
+ * // Check balance
+ * const balance = await vaultAPI.getBalance(tokenAddress);
+ * console.log(`Balance: ${balance.formatted} ${balance.symbol}`);
+ *
+ * // Deposit tokens
+ * const result = await vaultAPI.deposit(tokenAddress, parseEther("100"));
+ * console.log(`Deposit transaction: ${result.hash}`);
+ * ```
+ */
+import type { ApplicationsAPI, Balance, ProfileAPI, TransactionResult, VaultAPI } 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 walletClient;
+    private readonly chain;
+    private applicationsAPI;
+    private profileAPI;
+    /**
+     * Creates a new VaultAPI instance.
+     *
+     * @param publicClient - The viem public client for reading blockchain state
+     * @param walletClient - The viem wallet client for signing transactions
+     * @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, chain: Chain, applicationsAPI: ApplicationsAPI, profileAPI: ProfileAPI, apiUrl: string);
+    /**
+     * 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>;
+    /**
+     * 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>;
+    /**
+     * Withdraws tokens from the Monaco vault.
+     *
+     * Withdraws the specified amount of tokens from the vault contract back to the
+     * user's wallet. The method obtains a signature from the API Gateway and then
+     * executes the withdrawal transaction on-chain.
+     *
+     * @param assetId - The asset identifier (UUID) to withdraw
+     * @param amount - The amount of tokens to withdraw (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 withdrawal fails
+     * @throws {APIError} When signature retrieval fails or the asset is not found/assetId is invalid
+     * @throws {InvalidConfigError} When wallet account is not available
+     *
+     * @example
+     * ```typescript
+     * // Withdraw 50 USDC from the vault (auto-waits by default)
+     * const result = await vaultAPI.withdraw(
+     *   "123e4567-e89b-12d3-a456-426614174000",
+     *   parseUnits("50", 6)
+     * );
+     * console.log(`Withdrawal transaction: ${result.hash}`);
+     * console.log(`Status: ${result.status}`); // "confirmed" if successful
+     *
+     * // Or skip auto-waiting
+     * const result = await vaultAPI.withdraw(
+     *   "123e4567-e89b-12d3-a456-426614174000",
+     *   parseUnits("50", 6),
+     *   false
+     * );
+     * // Then manually wait later if needed
+     * const receipt = await sdk.waitForTransaction(result.hash);
+     * ```
+     */
+    withdraw(assetId: string, amount: bigint, autoWait?: boolean): Promise<TransactionResult>;
+    /**
+     * Retrieves the user's token balance in the vault.
+     *
+     * Queries the vault contract to get the current balance of a specific token
+     * for the connected wallet. Returns both raw amount and formatted display values.
+     *
+     * @param assetId - The asset identifier (UUID) to check balance for
+     * @returns Promise resolving to Balance with token balance details
+     * @throws {ContractError} When balance retrieval fails or asset not found
+     *
+     * @example
+     * ```typescript
+     * const balance = await vaultAPI.getBalance("123e4567-e89b-12d3-a456-426614174000");
+     * console.log(`Vault balance: ${balance.formatted} ${balance.symbol}`);
+     * console.log(`Raw amount: ${balance.amount}`);
+     * ```
+     */
+    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>;
+    /**
+     * Retrieves a deposit signature from the API Gateway.
+     *
+     * Internal method that communicates with the Monaco API Gateway to obtain
+     * the cryptographic signature required for deposit transactions. The signature
+     * validates the deposit request and ensures proper authorization.
+     *
+     * @param assetId - The asset identifier (UUID) to deposit
+     * @param amount - The amount to deposit (as bigint)
+     * @returns Promise resolving to object containing seed and signature
+     * @throws {APIError} When signature retrieval fails
+     * @private
+     */
+    private getDepositSignature;
+    /**
+     * Retrieves a withdrawal signature from the API Gateway.
+     *
+     * Internal method that communicates with the Monaco API Gateway to obtain
+     * the cryptographic signature required for withdrawal transactions. The signature
+     * validates the withdrawal request and ensures proper authorization.
+     *
+     * @param assetId - The asset identifier (UUID) to withdraw
+     * @param amount - The amount to withdraw (as bigint)
+     * @returns Promise resolving to object containing seed and signature
+     * @throws {APIError} When signature retrieval fails
+     * @private
+     */
+    private getWithdrawSignature;
+    private waitForTransaction;
+}
+//# sourceMappingURL=api.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../../../src/api/vault/api.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAGH,OAAO,KAAK,EAAE,eAAe,EAAE,OAAO,EAAE,UAAU,EAAE,iBAAiB,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAEzG,OAAO,EAAE,KAAK,OAAO,EAAE,KAAK,KAAK,EAAgD,KAAK,YAAY,EAAE,KAAK,YAAY,EAAE,MAAM,MAAM,CAAC;AAEpI,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAElC,qBAAa,YAAa,SAAQ,OAAQ,YAAW,QAAQ;IAezD,OAAO,CAAC,QAAQ,CAAC,YAAY;IAC7B,OAAO,CAAC,QAAQ,CAAC,YAAY;IAC7B,OAAO,CAAC,QAAQ,CAAC,KAAK;IAhBxB,OAAO,CAAC,eAAe,CAAkB;IACzC,OAAO,CAAC,UAAU,CAAa;IAE/B;;;;;;;;;OASG;gBAEgB,YAAY,EAAE,YAAY,EAC1B,YAAY,EAAE,YAAY,EAC1B,KAAK,EAAE,KAAK,EAC7B,eAAe,EAAE,eAAe,EAChC,UAAU,EAAE,UAAU,EACtB,MAAM,EAAE,MAAM;IAOhB;;;;;;OAMG;IACG,eAAe,IAAI,OAAO,CAAC,OAAO,CAAC;IAKzC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACG,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,GAAE,OAAc,GAAG,OAAO,CAAC,iBAAiB,CAAC;IA8CpG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAoCG;IACG,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,GAAE,OAAc,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAuEpG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAkCG;IACG,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,GAAE,OAAc,GAAG,OAAO,CAAC,iBAAiB,CAAC;IA4DrG;;;;;;;;;;;;;;;;OAgBG;IACG,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IA8CnD;;;;;;;;;;;;;;;OAeG;IACG,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAwBpD;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACG,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAKtE;;;;;;;;;;;;OAYG;YACW,mBAAmB;IAiBjC;;;;;;;;;;;;OAYG;YACW,oBAAoB;YAiBpB,kBAAkB;CA8BjC"}