@augustdigital/sdk 8.3.1 → 8.5.0

package/lib/modules/vaults/read.actions.d.ts

@@ -1,19 +1,55 @@
 import { IAddress, IContractRunner, INormalizedNumber } from '../../types';
 import { IContractWriteOptions } from './write.actions';
+/**
+ * Function to fetch instant redemption fee
+ * @param signer - signer / provider object
+ * @param options - object including pool contract address, user wallet address
+ * @returns normalized number object of the instant redemption fee
+ */
 export declare function fetchInstantRedemptionFee(signer: IContractRunner, options: IContractWriteOptions): Promise<INormalizedNumber>;
+/**
+ * allowance checks user's current allowance per pool
+ * @param signer - signer / provider object
+ * @param options - object including pool contract address, user wallet address
+ * @returns normalized number object of the user's current allowance
+ */
 export declare function vaultAllowance(signer: IContractRunner, options: IContractWriteOptions): Promise<INormalizedNumber>;
+/**
+ * Fetches the senders whitelist contract address from a whitelisted allocation vault
+ * @param signer - signer / provider object
+ * @param options - object including vault contract address
+ * @returns the senders whitelist contract address
+ */
 export declare function sendersWhitelistAddress(signer: IContractRunner, options: {
     vault: IAddress;
 }): Promise<IAddress | undefined>;
+/**
+ * Checks if an address is whitelisted on a whitelist contract
+ * @param signer - signer / provider object
+ * @param options - object including whitelist contract address and wallet address to check
+ * @returns boolean indicating if the address is whitelisted
+ */
 export declare function isWhitelisted(signer: IContractRunner, options: {
     whitelist: IAddress;
     wallet: IAddress;
 }): Promise<boolean | undefined>;
+/**
+ * Fetches the total amount deposited by an address on a whitelist contract
+ * @param signer - signer / provider object
+ * @param options - object including whitelist contract address, wallet address, and vault address
+ * @returns normalized number of the deposited amount
+ */
 export declare function getDeposited(signer: IContractRunner, options: {
     whitelist: IAddress;
     wallet: IAddress;
     vault: IAddress;
 }): Promise<INormalizedNumber | undefined>;
+/**
+ * Fetches the remaining allocation for an address on a whitelist contract
+ * @param signer - signer / provider object
+ * @param options - object including whitelist contract address, wallet address, vault address, and optional deposit cap amount
+ * @returns the remaining allocation as normalized number
+ */
 export declare function getRemainingAllocations(signer: IContractRunner, options: {
     whitelist: IAddress;
     wallet: IAddress;
@@ -21,37 +57,169 @@ export declare function getRemainingAllocations(signer: IContractRunner, options
     depositCapAmount?: bigint;
 }): Promise<INormalizedNumber | undefined>;
 export type IPreviewRwaRedemptionOptions = {
+    /** RwaRedeemSubaccount contract address */
     target: IAddress;
+    /** Redeemable asset address (e.g. USDC, USDT) */
     asset: IAddress;
+    /** Amount of vault shares to preview */
     amount: string | bigint | number;
+    /** Decimals of the vault share token */
     decimals: number;
+    /** Decimals of the output/redeemable asset */
     outputDecimals: number;
 };
+/**
+ * Preview the output amount for an RWA instant redemption via the RwaRedeemSubaccount contract.
+ * @param signer - signer / provider object
+ * @param options - object including subaccount address, asset, amount, decimals, and outputDecimals
+ * @returns normalized number of the expected output amount (in output asset decimals)
+ */
 export declare function previewRwaRedemption(signer: IContractRunner, options: IPreviewRwaRedemptionOptions): Promise<INormalizedNumber | undefined>;
+/** Options for {@link previewDeposit}. */
 export type IPreviewDepositOptions = {
+    /** Vault contract address. */
     vault: IAddress;
+    /** Deposit amount in the deposit asset's smallest unit (raw bigint-shaped). */
     amount: string | bigint | number;
+    /**
+     * Optional deposit asset. Required for multi-asset vaults (EVM-2); ignored
+     * for single-asset vaults where the underlying is implicit.
+     */
     asset?: IAddress;
 };
+/** Options for {@link previewRedeem}. */
 export type IPreviewRedeemOptions = {
+    /** Vault contract address. */
     vault: IAddress;
+    /** Share amount in the vault share token's smallest unit (raw bigint-shaped). */
     shares: string | bigint | number;
 };
+/** Options for {@link allowance}. */
 export type IAllowanceOptions = {
+    /** Spender contract — usually the vault address. */
     vault: IAddress;
+    /** Owner whose ERC-20 allowance is being queried. */
     owner: IAddress;
+    /**
+     * Token whose allowance is queried. Defaults to the vault's underlying
+     * asset, resolved via `IERC4626.asset()`.
+     */
     asset?: IAddress;
 };
+/** Options for {@link balanceOf}. */
 export type IBalanceOfOptions = {
+    /** ERC-20 token address. */
     asset: IAddress;
+    /** Owner whose balance is queried. */
     owner: IAddress;
 };
+/** Options for {@link maxDeposit}. */
 export type IMaxDepositOptions = {
+    /** Vault contract address. */
     vault: IAddress;
+    /**
+     * Receiver address — passed to ERC-4626 `maxDeposit(address)` on single-
+     * asset vaults. Ignored by EVM-2 multi-asset vaults which expose a vault-
+     * level `maxDepositAmount()` without a receiver argument.
+     */
     receiver?: IAddress;
 };
+/**
+ * Preview the number of shares that would be minted for a deposit, without
+ * touching on-chain state. Routes between single-asset ERC-4626 and EVM-2
+ * multi-asset vaults using the vault version detected from backend metadata.
+ *
+ * @returns The number of shares (raw on-chain units, share-token decimals).
+ * @throws AugustValidationError on invalid vault address or amount.
+ * @throws AugustSDKError when the underlying contract call fails.
+ *
+ * @example
+ * ```ts
+ * const shares = await augustSdk.evm.previewDeposit({
+ *   vault: '0xE9B725010A9E419412ed67d0fA5f3A5f40159D32',
+ *   amount: 1_000_000n,           // 1 USDC (6 decimals)
+ * });
+ * ```
+ */
 export declare function previewDeposit(signer: IContractRunner, options: IPreviewDepositOptions): Promise<bigint>;
+/**
+ * Preview the number of underlying assets returned by redeeming a given
+ * number of shares, without touching on-chain state. Routes between single-
+ * asset ERC-4626 (`previewRedeem`) and EVM-2 multi-asset
+ * (`previewRedemption(shares, isInstant=false)`) using the vault version.
+ *
+ * @returns The assets that would be redeemed (raw on-chain units, asset
+ *   decimals).
+ * @throws AugustValidationError on invalid vault or share input.
+ * @throws AugustSDKError when the underlying contract call fails.
+ *
+ * @example
+ * ```ts
+ * const assets = await augustSdk.evm.previewRedeem({
+ *   vault: '0xE9B725010A9E419412ed67d0fA5f3A5f40159D32',
+ *   shares: 1_000_000_000_000_000_000n, // 1 share (18 decimals)
+ * });
+ * ```
+ */
 export declare function previewRedeem(signer: IContractRunner, options: IPreviewRedeemOptions): Promise<bigint>;
+/**
+ * Read the ERC-20 allowance an `owner` has granted to a vault (the spender).
+ * If `asset` is omitted, the vault's underlying asset is resolved via
+ * `IERC4626.asset()` and used as the token.
+ *
+ * Returns a raw `bigint` to keep BigInt math precise — call
+ * {@link toNormalizedBn} if you need a UI-shaped {@link INormalizedNumber}.
+ *
+ * @returns Allowance in raw on-chain units of `asset`.
+ * @throws AugustValidationError on invalid addresses.
+ * @throws AugustSDKError when the underlying contract call fails.
+ *
+ * @example
+ * ```ts
+ * const raw = await augustSdk.evm.allowance({
+ *   vault: '0xE9B725010A9E419412ed67d0fA5f3A5f40159D32',
+ *   owner: walletAddress,
+ * });
+ * if (raw < requiredAmount) {
+ *   await augustSdk.evm.vaultApprove({
+ *     target: vault,
+ *     wallet: walletAddress,
+ *     amount: requiredAmount.toString(),
+ *   });
+ * }
+ * ```
+ */
 export declare function allowance(signer: IContractRunner, options: IAllowanceOptions): Promise<bigint>;
+/**
+ * Read an ERC-20 balance directly. Returns the raw on-chain value as
+ * `bigint`; call {@link toNormalizedBn} if you need a {@link INormalizedNumber}.
+ *
+ * @returns Balance in raw on-chain units of `asset`.
+ * @throws AugustValidationError on invalid asset / owner addresses.
+ * @throws AugustSDKError when the underlying contract call fails.
+ *
+ * @example
+ * ```ts
+ * const raw = await augustSdk.evm.balanceOf({
+ *   asset: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', // USDC
+ *   owner: walletAddress,
+ * });
+ * ```
+ */
 export declare function balanceOf(signer: IContractRunner, options: IBalanceOfOptions): Promise<bigint>;
+/**
+ * Read the maximum deposit currently accepted by a vault. Routes between
+ * single-asset ERC-4626 (`maxDeposit(receiver)`) and EVM-2 multi-asset
+ * (`maxDepositAmount()`, vault-level cap, no receiver dependence).
+ *
+ * @returns Max deposit in raw on-chain units of the deposit asset.
+ * @throws AugustValidationError on invalid vault address.
+ * @throws AugustSDKError when the underlying contract call fails.
+ *
+ * @example
+ * ```ts
+ * const cap = await augustSdk.evm.maxDeposit({ vault });
+ * if (cap === 0n) showVaultIsFullToast();
+ * ```
+ */
 export declare function maxDeposit(signer: IContractRunner, options: IMaxDepositOptions): Promise<bigint>;

package/lib/modules/vaults/read.actions.js

@@ -14,6 +14,12 @@ exports.balanceOf = balanceOf;
 exports.maxDeposit = maxDeposit;
 const abis_1 = require("../../abis");
 const core_1 = require("../../core");
+/**
+ * Function to fetch instant redemption fee
+ * @param signer - signer / provider object
+ * @param options - object including pool contract address, user wallet address
+ * @returns normalized number object of the instant redemption fee
+ */
 async function fetchInstantRedemptionFee(signer, options) {
     const { wallet, target } = options;
     const [goodWallet, goodPool] = [
@@ -38,6 +44,12 @@ async function fetchInstantRedemptionFee(signer, options) {
         throw new Error(`Failed to fetch instant redeem fee for ${target}: ${e instanceof Error ? e.message : 'Unknown error'}`);
     }
 }
+/**
+ * allowance checks user's current allowance per pool
+ * @param signer - signer / provider object
+ * @param options - object including pool contract address, user wallet address
+ * @returns normalized number object of the user's current allowance
+ */
 async function vaultAllowance(signer, options) {
     const { wallet, target } = options;
     const [goodWallet, goodPool] = [
@@ -47,16 +59,19 @@ async function vaultAllowance(signer, options) {
     if (!goodWallet || !goodPool)
         return;
     try {
+        // ERC4626 vault
         const poolContract = (0, core_1.createContract)({
             address: target,
             abi: abis_1.ABI_LENDING_POOLS,
             provider: signer,
         });
+        // get vault asset address and decimals
         const [asset, rawDecimals] = await Promise.all([
             poolContract.asset(),
             poolContract.decimals(),
         ]);
         const decimals = Number(rawDecimals);
+        // check amount vault approves user for
         const depositTokenContract = (0, core_1.createContract)({
             address: asset,
             abi: abis_1.ABI_ERC20,
@@ -72,6 +87,12 @@ async function vaultAllowance(signer, options) {
         throw new Error(`Failed to fetch allowance: ${e instanceof Error ? e.message : 'Unknown error'}`);
     }
 }
+/**
+ * Fetches the senders whitelist contract address from a whitelisted allocation vault
+ * @param signer - signer / provider object
+ * @param options - object including vault contract address
+ * @returns the senders whitelist contract address
+ */
 async function sendersWhitelistAddress(signer, options) {
     const { vault } = options;
     const goodTarget = (0, core_1.checkAddress)(vault, console);
@@ -92,6 +113,12 @@ async function sendersWhitelistAddress(signer, options) {
         throw new Error(`Failed to fetch senders whitelist address: ${e instanceof Error ? e.message : 'Unknown error'}`);
     }
 }
+/**
+ * Checks if an address is whitelisted on a whitelist contract
+ * @param signer - signer / provider object
+ * @param options - object including whitelist contract address and wallet address to check
+ * @returns boolean indicating if the address is whitelisted
+ */
 async function isWhitelisted(signer, options) {
     const { whitelist, wallet } = options;
     const [goodWhitelist, goodWallet] = [
@@ -115,6 +142,12 @@ async function isWhitelisted(signer, options) {
         throw new Error(`Failed to check whitelist status: ${e instanceof Error ? e.message : 'Unknown error'}`);
     }
 }
+/**
+ * Fetches the total amount deposited by an address on a whitelist contract
+ * @param signer - signer / provider object
+ * @param options - object including whitelist contract address, wallet address, and vault address
+ * @returns normalized number of the deposited amount
+ */
 async function getDeposited(signer, options) {
     const { whitelist, wallet, vault } = options;
     const [goodWhitelist, goodWallet, goodVault] = [
@@ -154,6 +187,12 @@ async function getDeposited(signer, options) {
         throw new Error(`Failed to fetch deposited amount: ${e instanceof Error ? e.message : 'Unknown error'}`);
     }
 }
+/**
+ * Fetches the remaining allocation for an address on a whitelist contract
+ * @param signer - signer / provider object
+ * @param options - object including whitelist contract address, wallet address, vault address, and optional deposit cap amount
+ * @returns the remaining allocation as normalized number
+ */
 async function getRemainingAllocations(signer, options) {
     const { whitelist, wallet, vault, depositCapAmount } = options;
     const [goodWhitelist, goodWallet, goodVault] = [
@@ -174,6 +213,7 @@ async function getRemainingAllocations(signer, options) {
             abi: abis_1.ABI_TOKENIZED_VAULT_V2_SENDER_ALLOCATION_WHITELIST,
             provider: signer,
         });
+        // Fetch depositCap if not provided, along with asset address
         const [capAmount, asset] = await Promise.all([
             depositCapAmount !== undefined
                 ? Promise.resolve(depositCapAmount)
@@ -196,6 +236,12 @@ async function getRemainingAllocations(signer, options) {
         throw new Error(`Failed to fetch remaining allocations: ${e instanceof Error ? e.message : 'Unknown error'}`);
     }
 }
+/**
+ * Preview the output amount for an RWA instant redemption via the RwaRedeemSubaccount contract.
+ * @param signer - signer / provider object
+ * @param options - object including subaccount address, asset, amount, decimals, and outputDecimals
+ * @returns normalized number of the expected output amount (in output asset decimals)
+ */
 async function previewRwaRedemption(signer, options) {
     const { target, asset, amount, decimals, outputDecimals } = options;
     const goodTarget = (0, core_1.checkAddress)(target, console, 'contract');
@@ -255,6 +301,23 @@ function toRawBigInt(value, label) {
     }
     throw new core_1.AugustValidationError('INVALID_INPUT', `${label}: amount must be a string, bigint, or number`);
 }
+/**
+ * Preview the number of shares that would be minted for a deposit, without
+ * touching on-chain state. Routes between single-asset ERC-4626 and EVM-2
+ * multi-asset vaults using the vault version detected from backend metadata.
+ *
+ * @returns The number of shares (raw on-chain units, share-token decimals).
+ * @throws AugustValidationError on invalid vault address or amount.
+ * @throws AugustSDKError when the underlying contract call fails.
+ *
+ * @example
+ * ```ts
+ * const shares = await augustSdk.evm.previewDeposit({
+ *   vault: '0xE9B725010A9E419412ed67d0fA5f3A5f40159D32',
+ *   amount: 1_000_000n,           // 1 USDC (6 decimals)
+ * });
+ * ```
+ */
 async function previewDeposit(signer, options) {
     const { vault, amount, asset } = options;
     if (!(0, core_1.checkAddress)(vault, console, 'contract')) {
@@ -275,6 +338,7 @@ async function previewDeposit(signer, options) {
                 abi: abis_1.ABI_TOKENIZED_VAULT_V2,
             });
             const result = await contract.previewDeposit(asset, amountRaw);
+            // TokenizedVaultV2 previewDeposit returns (shares, _); take shares.
             const shares = Array.isArray(result) ? result[0] : result;
             return BigInt(shares);
         }
@@ -294,6 +358,25 @@ async function previewDeposit(signer, options) {
         throw new core_1.AugustSDKError('UNKNOWN', `previewDeposit failed: ${e instanceof Error ? e.message : 'Unknown error'}`, { cause: e, context: { vault, amount: amount.toString() } });
     }
 }
+/**
+ * Preview the number of underlying assets returned by redeeming a given
+ * number of shares, without touching on-chain state. Routes between single-
+ * asset ERC-4626 (`previewRedeem`) and EVM-2 multi-asset
+ * (`previewRedemption(shares, isInstant=false)`) using the vault version.
+ *
+ * @returns The assets that would be redeemed (raw on-chain units, asset
+ *   decimals).
+ * @throws AugustValidationError on invalid vault or share input.
+ * @throws AugustSDKError when the underlying contract call fails.
+ *
+ * @example
+ * ```ts
+ * const assets = await augustSdk.evm.previewRedeem({
+ *   vault: '0xE9B725010A9E419412ed67d0fA5f3A5f40159D32',
+ *   shares: 1_000_000_000_000_000_000n, // 1 share (18 decimals)
+ * });
+ * ```
+ */
 async function previewRedeem(signer, options) {
     const { vault, shares } = options;
     if (!(0, core_1.checkAddress)(vault, console, 'contract')) {
@@ -311,6 +394,7 @@ async function previewRedeem(signer, options) {
                 abi: abis_1.ABI_TOKENIZED_VAULT_V2,
             });
             const result = await contract.previewRedemption(sharesRaw, false);
+            // EVM-2 previewRedemption returns (assetsAmount, assetsAfterFee); take gross.
             const assets = Array.isArray(result) ? result[0] : result;
             return BigInt(assets);
         }
@@ -333,6 +417,33 @@ async function previewRedeem(signer, options) {
         throw new core_1.AugustSDKError('UNKNOWN', `previewRedeem failed: ${e instanceof Error ? e.message : 'Unknown error'}`, { cause: e, context: { vault, shares: shares.toString() } });
     }
 }
+/**
+ * Read the ERC-20 allowance an `owner` has granted to a vault (the spender).
+ * If `asset` is omitted, the vault's underlying asset is resolved via
+ * `IERC4626.asset()` and used as the token.
+ *
+ * Returns a raw `bigint` to keep BigInt math precise — call
+ * {@link toNormalizedBn} if you need a UI-shaped {@link INormalizedNumber}.
+ *
+ * @returns Allowance in raw on-chain units of `asset`.
+ * @throws AugustValidationError on invalid addresses.
+ * @throws AugustSDKError when the underlying contract call fails.
+ *
+ * @example
+ * ```ts
+ * const raw = await augustSdk.evm.allowance({
+ *   vault: '0xE9B725010A9E419412ed67d0fA5f3A5f40159D32',
+ *   owner: walletAddress,
+ * });
+ * if (raw < requiredAmount) {
+ *   await augustSdk.evm.vaultApprove({
+ *     target: vault,
+ *     wallet: walletAddress,
+ *     amount: requiredAmount.toString(),
+ *   });
+ * }
+ * ```
+ */
 async function allowance(signer, options) {
     const { vault, owner, asset } = options;
     if (!(0, core_1.checkAddress)(vault, console, 'contract')) {
@@ -373,6 +484,22 @@ async function allowance(signer, options) {
         throw new core_1.AugustSDKError('UNKNOWN', `allowance failed: ${e instanceof Error ? e.message : 'Unknown error'}`, { cause: e, context: { vault, owner, asset } });
     }
 }
+/**
+ * Read an ERC-20 balance directly. Returns the raw on-chain value as
+ * `bigint`; call {@link toNormalizedBn} if you need a {@link INormalizedNumber}.
+ *
+ * @returns Balance in raw on-chain units of `asset`.
+ * @throws AugustValidationError on invalid asset / owner addresses.
+ * @throws AugustSDKError when the underlying contract call fails.
+ *
+ * @example
+ * ```ts
+ * const raw = await augustSdk.evm.balanceOf({
+ *   asset: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', // USDC
+ *   owner: walletAddress,
+ * });
+ * ```
+ */
 async function balanceOf(signer, options) {
     const { asset, owner } = options;
     if (!(0, core_1.checkAddress)(asset, console, 'contract')) {
@@ -398,6 +525,21 @@ async function balanceOf(signer, options) {
         throw new core_1.AugustSDKError('UNKNOWN', `balanceOf failed: ${e instanceof Error ? e.message : 'Unknown error'}`, { cause: e, context: { asset, owner } });
     }
 }
+/**
+ * Read the maximum deposit currently accepted by a vault. Routes between
+ * single-asset ERC-4626 (`maxDeposit(receiver)`) and EVM-2 multi-asset
+ * (`maxDepositAmount()`, vault-level cap, no receiver dependence).
+ *
+ * @returns Max deposit in raw on-chain units of the deposit asset.
+ * @throws AugustValidationError on invalid vault address.
+ * @throws AugustSDKError when the underlying contract call fails.
+ *
+ * @example
+ * ```ts
+ * const cap = await augustSdk.evm.maxDeposit({ vault });
+ * if (cap === 0n) showVaultIsFullToast();
+ * ```
+ */
 async function maxDeposit(signer, options) {
     const { vault, receiver } = options;
     if (!(0, core_1.checkAddress)(vault, console, 'contract')) {
@@ -424,6 +566,7 @@ async function maxDeposit(signer, options) {
             provider: signer,
             abi: abis_1.ABI_LENDING_POOLS,
         });
+        // Zero-address default: vaults that require a receiver arg won't revert.
         const target = receiver ?? '0x0000000000000000000000000000000000000000';
         const raw = (await contract.maxDeposit(target));
         return BigInt(raw);

package/lib/modules/vaults/types.d.ts

@@ -1,14 +1,38 @@
 import type { Connection } from '@solana/web3.js';
 import type { IAddress, IEnv, IWSMonitorHeaders } from '../../types';
+/**
+ * Structural interface for the Solana adapter surface used by vault operations.
+ * Avoids importing the concrete SolanaAdapter class to prevent circular dependencies.
+ */
 export interface ISolanaService {
     connection: Connection;
     getVaultState: (vaultProgramId: any, idl: any, vaultAddress?: any) => Promise<any>;
     fetchUserShareBalance: (publicKey: any, shareMint: any) => Promise<any>;
+    /**
+     * Raw (BigInt-safe) variant. Required — `fetchUserShareBalance` alone
+     * returns a JS-number `uiAmount` which is lossy and silently encodes
+     * against 18 decimals when fed back through `toNormalizedBn` without an
+     * explicit decimals argument. Every consumer that needs a correct
+     * `walletBalance.raw` (positions, redemptions, max actions) MUST use this
+     * entry point.
+     *
+     * Returns `{ amount, decimals }`:
+     *   - `amount` is the on-chain u64 as a base-units string (always set;
+     *     `'0'` when no balance / no account / no args / RPC failure).
+     *   - `decimals` matches the mint when a parsed `tokenAmount` is
+     *     available; otherwise **`null`**. `decimals === null` is the
+     *     "scale unknown" signal — callers must substitute a known decimals
+     *     value (typically the deposit mint's decimals from backend metadata)
+     *     before constructing an `INormalizedNumber`. Never throws.
+     */
     fetchUserShareBalanceRaw: (publicKey: any, shareMint: any) => Promise<{
         amount: string;
         decimals: number | null;
     }>;
 }
+/**
+ * Base configuration for vault operations.
+ */
 export interface IVaultBaseOptions {
     rpcUrl: string;
     env?: IEnv;
@@ -17,7 +41,17 @@ export interface IVaultBaseOptions {
     chainId?: number;
     solanaService?: ISolanaService;
     headers?: IWSMonitorHeaders;
+    /**
+     * Portfolio mode: when true, the per-vault EVM getter does NOT null out a
+     * closed + invisible vault. Needed so a user's position in a closed,
+     * invisible vault can still resolve its metadata. Defaults to undefined
+     * (false) so marketplace/discovery reads keep hiding closed staging vaults.
+     */
+    includeClosed?: boolean;
 }
+/**
+ * Optional enrichment options for vault queries.
+ */
 export interface IVaultCustomOptions {
     loans?: boolean;
     allocations?: boolean;

package/lib/modules/vaults/utils/call-data-decoder.d.ts

@@ -1,3 +1,9 @@
+/**
+ * Withdrawal Processing Transaction Decoder
+ *
+ * Decodes transaction calldata to extract which (year, month, day) cluster
+ * was processed when a WithdrawalProcessed event was emitted.
+ */
 import { ContractTransactionReceipt, Interface } from 'ethers';
 export interface ProcessingCallData {
     functionName: 'processAllClaimsByDate' | 'claim' | 'unknown';
@@ -8,7 +14,48 @@ export interface ProcessingCallData {
     receiverAddr?: string;
     error?: string;
 }
+/**
+ * Decode withdrawal processing transaction calldata.
+ * Handles both processAllClaimsByDate() and claim() functions.
+ *
+ * Both functions have the same first 3 parameters: (year, month, day)
+ *
+ * @param txData - Raw transaction data (tx.data from provider.getTransaction())
+ * @param iface - ethers Interface initialized with vault ABI
+ * @returns Decoded parameters or error
+ */
 export declare function decodeWithdrawalProcessing(txData: string, iface: Interface): ProcessingCallData;
+/**
+ * Fallback: Parse receipt logs if calldata decoding fails.
+ *
+ * This handles the multicall wrapper case where the outer tx.data
+ * is the multicall wrapper, not the vault function. By parsing logs,
+ * we can infer what happened on-chain.
+ *
+ * Note: This is a best-effort fallback. Ideal solution is Option 2
+ * (subgraph indexing) to avoid RPC calls altogether.
+ *
+ * @param receipt - Transaction receipt from provider
+ * @param vaultAddress - Expected vault address
+ * @param iface - ethers Interface with vault ABI
+ * @returns Decoded parameters from logs, or error
+ */
 export declare function decodeFromReceiptLogs(receipt: ContractTransactionReceipt | null, vaultAddress: string, iface: Interface): Promise<ProcessingCallData>;
+/**
+ * Detect if this is a multicall/batch transaction.
+ * Common patterns:
+ * - Uniswap Multicall: 0x1f0464f6
+ * - Gnosis Safe: 0x6a761202
+ * - 1inch Aggregator: 0x7c025200
+ *
+ * @param functionName - Function name from parsed decoded tx
+ * @returns true if this appears to be a batch/multicall
+ */
 export declare function isMulticall(functionName: string): boolean;
+/**
+ * Detect if the decoded function is one we care about for withdrawal processing.
+ *
+ * @param functionName - Function name from decoding
+ * @returns true if this is a withdrawal processing function
+ */
 export declare function isWithdrawalProcessingFunction(functionName: string): boolean;