@augustdigital/sdk 9.3.0 → 9.4.0

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

@@ -13,6 +13,7 @@ exports.approve = approve;
 exports.vaultDeposit = vaultDeposit;
 exports.vaultRequestRedeem = vaultRequestRedeem;
 exports.vaultRedeem = vaultRedeem;
+exports.claimWithdrawal = claimWithdrawal;
 exports.depositNative = depositNative;
 exports.rwaRedeemAsset = rwaRedeemAsset;
 exports.swapAndDeposit = swapAndDeposit;
@@ -861,12 +862,14 @@ async function vaultDeposit(signer, options) {
 }
 /**
  * Request to redeem vault shares. For EVM-1 vaults this queues a standard
- * redemption (claimable later via `vaultRedeem`); for EVM-2 vaults this
- * also handles the receipt-token allowance automatically. Pass
- * `isInstantRedeem: true` for vaults that support instant settlement.
+ * redemption (claimable later via `vaultRedeem`). For EVM-2 vaults the queued
+ * `requestRedeem` escrows the shares in the vault via `transferFrom`, so this
+ * also approves the receipt token when its allowance is short; the instant
+ * path (`isInstantRedeem: true`) burns the caller's shares directly and sends
+ * no approval.
  *
- * Approval of the receipt token (EVM-2) is always waited on before the
- * redeem call, regardless of the caller's `wait` flag.
+ * The receipt-token approval (EVM-2 queued path) is always waited on before
+ * the redeem call, regardless of the caller's `wait` flag.
  *
  * @param signer ethers Signer / Wallet (or viem WalletClient via {@link setSigner})
  * @param options Vault address, wallet, amount, optional `isInstantRedeem`,
@@ -932,25 +935,26 @@ async function vaultRequestRedeem(signer, options) {
             // misroute (a non-evm-2 vault reaching this branch) still throws the
             // original error. See getReceiptTokenAddressOrThrow.
             const receiptTokenAddr = await (0, core_1.getReceiptTokenAddressOrThrow)(signer, target, 'vaultRequestRedeem:receiptToken');
-            const receiptContract = (0, core_1.createContract)({
-                address: receiptTokenAddr,
-                provider: signer,
-                abi: abis_1.ABI_ERC20,
-            });
             decimals = await (0, core_1.getDecimalsOrThrow)(signer, receiptTokenAddr, 'vaultRequestRedeem:receiptDecimals');
-            // Convert amount to bignumber
-            const normalizedAmt = (0, core_1.toNormalizedBn)(amount, decimals);
-            // EVM-2 lp/receipt token is a separate ERC-20: vault.transferFrom(lp)
-            // needs explicit allowance even on self-redeem (msg.sender on the lp
-            // token is the vault, not the user — no ERC-4626 owner-shortcut).
-            const allowance = await receiptContract.allowance(wallet, target);
-            if (safeBigInt(allowance, 'vaultRequestRedeem:allowance') <
-                BigInt(normalizedAmt.raw)) {
-                const { hash: approveHash } = await safeSendTx(() => receiptContract.connect(signer).approve(target, normalizedAmt.raw), signer, true);
-                core_1.Logger.log.info('approve:receipt_token:tx_hash', approveHash);
+            // Queued requestRedeem escrows the shares in the vault through
+            // receipt.transferFrom(user → vault): the vault is the spender, so it
+            // needs an explicit allowance even on self-redeem (without it the call
+            // reverts with ERC20InsufficientAllowance). instantRedeem burns the
+            // caller's shares directly and needs none.
+            if (!options.isInstantRedeem) {
+                const receiptContract = (0, core_1.createContract)({
+                    address: receiptTokenAddr,
+                    provider: signer,
+                    abi: abis_1.ABI_ERC20,
+                });
+                const sharesRaw = (0, core_1.toNormalizedBn)(amount, decimals).raw;
+                const allowance = await receiptContract.allowance(wallet, target);
+                if (safeBigInt(allowance, 'vaultRequestRedeem:allowance') <
+                    BigInt(sharesRaw)) {
+                    const { hash: approveHash } = await safeSendTx(() => receiptContract.connect(signer).approve(target, sharesRaw), signer, true);
+                    core_1.Logger.log.info('approve:receipt_token:tx_hash', approveHash);
+                }
             }
-            // For evm-2, use vaultContract for both instant and standard redeem
-            // ABI_TOKENIZED_VAULT_V2 has both instantRedeem (2 params) and requestRedeem
             poolContract = vaultContract;
         }
         else {
@@ -1026,7 +1030,6 @@ async function vaultRequestRedeem(signer, options) {
     }
 }
 /**
- * @TODO
  * @description withdraw funds from the specified pool including accrued rewards
  * @param signer signer / wallet object
  * @param options object including pool contract address, user wallet address, and more
@@ -1090,6 +1093,113 @@ async function vaultRedeem(signer, options) {
         });
     }
 }
+/**
+ * Claim a previously-requested queued withdrawal on an EVM-2 (Tokenized
+ * Vault V2) vault, once its withdrawal epoch has passed.
+ *
+ * EVM-2 only — v1/v0 vaults use a different claim path ({@link vaultRedeem}).
+ * The vault's on-chain `claim(year, month, day, receiverAddr)` reverts if the
+ * epoch has not yet elapsed, or if the vault's idle reserve has not been
+ * refilled from subaccounts to cover the queue for that date; neither
+ * condition is checked client-side before sending.
+ *
+ * @param signer ethers Signer / Wallet.
+ * @param options.target EVM-2 vault contract address.
+ * @param options.wallet Wallet initiating the claim; receives the withdrawn assets unless `receiver` is set.
+ * @param options.year Withdrawal-epoch year from `requestRedeem`.
+ * @param options.month Withdrawal-epoch month from `requestRedeem`.
+ * @param options.day Withdrawal-epoch day from `requestRedeem`.
+ * @param options.receiver Address receiving the withdrawn assets. Defaults to `wallet`.
+ * @param options.wait Wait for transaction confirmation.
+ * @returns Claim transaction hash.
+ * @throws AugustValidationError on invalid address input, missing or non-integer date fields, or a non-EVM-2 vault.
+ * @throws AugustSDKError when the on-chain claim call fails.
+ *
+ * @worstCaseRpcCalls 2 — one vault-version lookup, one claim transaction.
+ *
+ * @example
+ * ```ts
+ * const { year, month, day } = await augustSdk.evm.vaultRequestRedeem({
+ *   target: vaultAddress,
+ *   wallet: walletAddress,
+ *   amount: '10',
+ * });
+ * // ...after the withdrawal epoch has elapsed...
+ * await augustSdk.evm.claimWithdrawal({
+ *   target: vaultAddress,
+ *   wallet: walletAddress,
+ *   year,
+ *   month,
+ *   day,
+ *   wait: true,
+ * });
+ * ```
+ */
+async function claimWithdrawal(signer, options) {
+    const { wallet, target, wait, year, month, day, receiver } = options;
+    const [goodWallet, goodTarget] = [
+        (0, core_1.checkAddress)(wallet, console, 'wallet'),
+        (0, core_1.checkAddress)(target, console),
+    ];
+    if (!goodWallet || !goodTarget) {
+        throw new core_1.AugustValidationError('INVALID_ADDRESS', `claimWithdrawal: invalid ${!goodWallet ? 'wallet' : 'target'} address`);
+    }
+    if (receiver !== undefined && !(0, core_1.checkAddress)(receiver, console, 'wallet')) {
+        throw new core_1.AugustValidationError('INVALID_ADDRESS', 'claimWithdrawal: invalid receiver address');
+    }
+    if (year === undefined || month === undefined || day === undefined) {
+        throw new core_1.AugustValidationError('INVALID_INPUT', 'claimWithdrawal: year, month, and day are required');
+    }
+    const yearRaw = (0, core_1.toRawBigInt)(year, 'claimWithdrawal', 'year');
+    const monthRaw = (0, core_1.toRawBigInt)(month, 'claimWithdrawal', 'month');
+    const dayRaw = (0, core_1.toRawBigInt)(day, 'claimWithdrawal', 'day');
+    try {
+        const tokenizedVault = (await (0, core_1.fetchTokenizedVault)(target))?.[0];
+        const vaultVersion = (0, core_1.getVaultVersionV2)(tokenizedVault);
+        if (vaultVersion !== 'evm-2') {
+            throw new core_1.AugustValidationError('INVALID_INPUT', `claimWithdrawal: only EVM-2 (Tokenized Vault V2) vaults expose claim() — ${target} resolved to ${vaultVersion}`);
+        }
+        const vaultContract = (0, core_1.createContract)({
+            address: target,
+            provider: signer,
+            abi: abis_1.ABI_TOKENIZED_VAULT_V2,
+        });
+        const { hash: claimHash } = await safeSendTx(() => vaultContract
+            .connect(signer)
+            .claim(yearRaw, monthRaw, dayRaw, receiver ?? wallet), signer, wait);
+        core_1.Logger.log.info('claim:tx_hash', claimHash);
+        return claimHash;
+    }
+    catch (e) {
+        const recovered = await tryRecoverTxHash(e, signer, wait);
+        if (recovered) {
+            core_1.Logger.log.warn('claim:nonce-fallback', { hash: recovered });
+            return recovered;
+        }
+        if (e instanceof core_1.AugustSDKError)
+            throw e;
+        const broadcast = errorTxBroadcastContext(e);
+        const insufficientFunds = (0, core_1.isInsufficientFundsError)(e);
+        (0, core_1.logChainError)('claim', e, (0, core_1.isUserRejectionError)(e) || insufficientFunds, {
+            target,
+            year,
+            month,
+            day,
+            ...broadcast,
+        });
+        throwIfInsufficientFunds(insufficientFunds, 'Claim withdrawal', e, {
+            target,
+            year,
+            month,
+            day,
+            ...broadcast,
+        });
+        throw new core_1.AugustSDKError('UNKNOWN', `Claim withdrawal failed: ${e instanceof Error ? e.message : 'Unknown error'}`, {
+            cause: e,
+            context: { target, year, month, day, ...broadcast },
+        });
+    }
+}
 /**
  * Deposit a native token (ETH / AVAX / etc.) into a vault via the
  * `MultiAssetNativeDepositWrapper`. The wrapper forwards `msg.value` to