@augustdigital/sdk 8.9.0 → 8.10.0

package/lib/core/analytics/version.d.ts

@@ -3,4 +3,4 @@
  * Generated during publish from package.json version
  * This file is gitignored and created at publish time
  */
-export declare const SDK_VERSION = "8.9.0";
+export declare const SDK_VERSION = "8.10.0";

package/lib/core/analytics/version.js

@@ -6,5 +6,5 @@ exports.SDK_VERSION = void 0;
  * Generated during publish from package.json version
  * This file is gitignored and created at publish time
  */
-exports.SDK_VERSION = '8.9.0';
+exports.SDK_VERSION = '8.10.0';
 //# sourceMappingURL=version.js.map

package/lib/core/helpers/chain-error.d.ts

@@ -45,6 +45,7 @@ export declare function isUserRejectionError(error: unknown): boolean;
  * ```
  */
 export declare function isExpectedRevertError(error: unknown): boolean;
+export declare function isInsufficientFundsError(error: unknown): boolean;
 /**
  * Log a caught chain error at the severity its category warrants, without
  * swallowing it. When `isBenign` is `true` the failure is recorded as a `warn`

package/lib/core/helpers/chain-error.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.isUserRejectionError = isUserRejectionError;
 exports.isExpectedRevertError = isExpectedRevertError;
+exports.isInsufficientFundsError = isInsufficientFundsError;
 exports.logChainError = logChainError;
 const logger_1 = require("../logger");
 /**
@@ -21,6 +22,9 @@ const logger_1 = require("../logger");
  * 2. **Expected on-chain read reverts** — reading a function a vault doesn't
  *    implement, or an address with no/incompatible bytecode, reverts. This is a
  *    routine outcome of probing heterogeneous vaults, not a defect.
+ * 3. **Underfunded sender accounts** — the node rejects the transaction because
+ *    the sender can't cover gas (or, on rollups such as Citrea, the extra L1
+ *    data-availability fee). This is a "top up your wallet" prompt, not a bug.
  *
  * These predicates let call sites demote exactly those cases to `warn` while
  * leaving genuine failures at `error`. They are intentionally dependency-free
@@ -77,6 +81,39 @@ function errorCodes(error) {
     }
     return codes;
 }
+/**
+ * Collect every human-readable message string an error-like value carries,
+ * across the nested locations providers stash them in.
+ *
+ * Why this is separate from {@link errorText}: ethers v6 flattens a rejected
+ * `eth_estimateGas`/`eth_call` to a generic *top-level* `message` (e.g.
+ * `"missing revert data"`) while preserving the node's original JSON-RPC error
+ * one level down at `info.error.message`. The real reason (an insufficient-funds
+ * report, say) is therefore invisible to a top-level `.message` read. We scan
+ * the top-level message plus `error.message`, `info.error.message`,
+ * `cause.message`, and `cause.info.error.message` so a caller catches the reason
+ * whether it holds the raw provider error or an SDK error that wrapped it as
+ * `cause`.
+ *
+ * @param error - The caught value, of unknown type.
+ * @returns Every non-empty message string found (possibly empty array).
+ */
+function nestedMessages(error) {
+    const out = [];
+    const push = (value) => {
+        if (typeof value === 'string' && value.length > 0)
+            out.push(value);
+    };
+    push(errorText(error));
+    if (error && typeof error === 'object') {
+        const e = error;
+        push(e.error?.message);
+        push(e.info?.error?.message);
+        push(e.cause?.message);
+        push(e.cause?.info?.error?.message);
+    }
+    return out;
+}
 /**
  * Is this error a wallet/user rejection of a transaction or signature request?
  *
@@ -143,6 +180,65 @@ function isExpectedRevertError(error) {
         msg.includes('call revert exception') ||
         msg.includes('reverted'));
 }
+/**
+ * Is this error the chain node reporting that the sender can't afford the
+ * transaction's gas/fee — i.e. the account needs topping up, not a defect?
+ *
+ * This is distinct from a contract revert, and easy to misclassify. When the
+ * node rejects `eth_estimateGas` for an underfunded account, ethers v6 discards
+ * the node's reason and surfaces a generic `CALL_EXCEPTION` / `"missing revert
+ * data"` at the top level — which {@link isExpectedRevertError} matches. The
+ * real reason survives only in the nested JSON-RPC error, so this predicate
+ * scans there (via `nestedMessages`). On a write path, check this **before**
+ * {@link isExpectedRevertError}, or a genuine funds shortfall reads as a benign
+ * revert.
+ *
+ * Matching is anchored to the node's pre-execution funds-check phrasings (see
+ * `INSUFFICIENT_FUNDS_PHRASES`), each of which carries a `for <purpose>`
+ * qualifier — `insufficient funds for gas`, `insufficient funds for transfer`,
+ * `not enough funds for L1 fee` (Citrea's data-availability fee), etc. This is
+ * deliberately narrower than a bare `"insufficient funds"` substring: a
+ * *contract revert reason* that merely contains the word "funds" (e.g.
+ * `execution reverted: insufficient funds in pool`) must stay a genuine failure,
+ * not be demoted to an ACCOUNT_NOT_FUNDED "top up gas" prompt.
+ *
+ * @param error - The caught value, of unknown type.
+ * @returns `true` when the failure is an unfunded/underfunded sender account.
+ *
+ * @example
+ * ```ts
+ * try { await vault.requestRedeem(...); }
+ * catch (e) {
+ *   if (isInsufficientFundsError(e))
+ *     throw new AugustValidationError(
+ *       'ACCOUNT_NOT_FUNDED',
+ *       'Add gas to continue',
+ *       { cause: e },
+ *     );
+ *   throw e;
+ * }
+ * ```
+ */
+/**
+ * The node pre-execution funds-check phrasings {@link isInsufficientFundsError}
+ * recognises, lower-cased. Each keeps the `for <purpose>` qualifier so the match
+ * is anchored to a funding rejection and can't be tripped by a contract revert
+ * reason that merely mentions "funds". `insufficient funds for gas` covers the
+ * geth/reth `"... for gas * price + value"` message; `not enough funds for l1
+ * fee` is the rollup (Citrea) data-availability-fee shortfall.
+ */
+const INSUFFICIENT_FUNDS_PHRASES = [
+    'insufficient funds for gas',
+    'insufficient funds for transfer',
+    'insufficient funds for intrinsic transaction cost',
+    'not enough funds for l1 fee',
+];
+function isInsufficientFundsError(error) {
+    return nestedMessages(error).some((raw) => {
+        const msg = raw.toLowerCase();
+        return INSUFFICIENT_FUNDS_PHRASES.some((phrase) => msg.includes(phrase));
+    });
+}
 /**
  * Log a caught chain error at the severity its category warrants, without
  * swallowing it. When `isBenign` is `true` the failure is recorded as a `warn`

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

@@ -185,6 +185,39 @@ async function tryRecoverTxHash(error, signer, wait) {
     }
     return txHash;
 }
+/**
+ * Rethrow a caught write-path error as a typed {@link AugustValidationError}
+ * when it is the chain node reporting the sender can't afford the transaction's
+ * gas/fee (see {@link isInsufficientFundsError}).
+ *
+ * Why: for an underfunded account ethers surfaces an opaque `CALL_EXCEPTION` /
+ * "missing revert data" that gives the caller no stable way to tell "user needs
+ * gas" apart from a genuine on-chain failure. Converting it to the
+ * `ACCOUNT_NOT_FUNDED` code lets a consuming UI branch on `err.code` (e.g. show
+ * a "top up to cover network fees" prompt) instead of string-matching. Every
+ * write path shares this so the classification is identical across
+ * deposit/redeem/approve rather than drifting per call site.
+ *
+ * A no-op when `isInsufficient` is `false`, so callers fall through to their
+ * existing handling unchanged. The caller passes the already-computed
+ * classification (it also feeds the telemetry-demotion decision) so
+ * {@link isInsufficientFundsError} runs once per catch, not twice.
+ *
+ * @param isInsufficient - Result of {@link isInsufficientFundsError} for
+ *   `error`, computed once by the caller and shared with the benign-log flag.
+ * @param operation - Human-readable label for the attempted write (e.g.
+ *   `'Request redeem'`), used verbatim in the thrown error's message.
+ * @param error - The caught value, of unknown type, preserved as the thrown
+ *   error's `cause`.
+ * @param context - Structured context attached to the thrown error for logging.
+ * @throws {AugustValidationError} with code `ACCOUNT_NOT_FUNDED` when
+ *   `isInsufficient` is `true`.
+ */
+function throwIfInsufficientFunds(isInsufficient, operation, error, context) {
+    if (!isInsufficient)
+        return;
+    throw new core_1.AugustValidationError('ACCOUNT_NOT_FUNDED', `${operation} failed: insufficient native balance to cover gas/network fees`, { cause: error, context });
+}
 async function approveCore(signer, options) {
     const { wallet, target, wait, amount, depositAsset } = options;
     const [goodWallet, goodPool] = [
@@ -293,7 +326,12 @@ async function approveCore(signer, options) {
             throw e;
         // A user declining the approval in their wallet is product behaviour, not
         // an SDK fault — demote it to a breadcrumb so it doesn't bill as an issue.
-        (0, core_1.logChainError)('vaultApprove', e, (0, core_1.isUserRejectionError)(e), {
+        const insufficientFunds = (0, core_1.isInsufficientFundsError)(e);
+        (0, core_1.logChainError)('vaultApprove', e, (0, core_1.isUserRejectionError)(e) || insufficientFunds, {
+            target,
+            amount,
+        });
+        throwIfInsufficientFunds(insufficientFunds, 'Approval', e, {
             target,
             amount,
         });
@@ -601,7 +639,13 @@ async function vaultDeposit(signer, options) {
         if (e instanceof core_1.AugustSDKError)
             throw e;
         // User-cancelled deposits are normal; only genuine failures stay at error.
-        (0, core_1.logChainError)('deposit', e, (0, core_1.isUserRejectionError)(e), {
+        const insufficientFunds = (0, core_1.isInsufficientFundsError)(e);
+        (0, core_1.logChainError)('deposit', e, (0, core_1.isUserRejectionError)(e) || insufficientFunds, {
+            target,
+            amount,
+            depositAsset,
+        });
+        throwIfInsufficientFunds(insufficientFunds, 'Deposit', e, {
             target,
             amount,
             depositAsset,
@@ -754,7 +798,12 @@ async function vaultRequestRedeem(signer, options) {
         if (e instanceof core_1.AugustSDKError)
             throw e;
         // User-cancelled redeem requests are normal; only genuine failures stay at error.
-        (0, core_1.logChainError)('requestRedeem', e, (0, core_1.isUserRejectionError)(e), {
+        const insufficientFunds = (0, core_1.isInsufficientFundsError)(e);
+        (0, core_1.logChainError)('requestRedeem', e, (0, core_1.isUserRejectionError)(e) || insufficientFunds, {
+            target,
+            amount,
+        });
+        throwIfInsufficientFunds(insufficientFunds, 'Request redeem', e, {
             target,
             amount,
         });
@@ -801,7 +850,15 @@ async function vaultRedeem(signer, options) {
         if (e instanceof core_1.AugustSDKError)
             throw e;
         // User-cancelled redeems are normal; only genuine failures stay at error.
-        (0, core_1.logChainError)('redeem', e, (0, core_1.isUserRejectionError)(e), {
+        const insufficientFunds = (0, core_1.isInsufficientFundsError)(e);
+        (0, core_1.logChainError)('redeem', e, (0, core_1.isUserRejectionError)(e) || insufficientFunds, {
+            target,
+            year,
+            month,
+            day,
+            receiverIndex,
+        });
+        throwIfInsufficientFunds(insufficientFunds, 'Redeem', e, {
             target,
             year,
             month,
@@ -899,7 +956,13 @@ async function depositNative(signer, options) {
         if (e instanceof core_1.AugustSDKError)
             throw e;
         // User-cancelled native deposits are normal; only genuine failures stay at error.
-        (0, core_1.logChainError)('depositNative', e, (0, core_1.isUserRejectionError)(e), {
+        const insufficientFunds = (0, core_1.isInsufficientFundsError)(e);
+        (0, core_1.logChainError)('depositNative', e, (0, core_1.isUserRejectionError)(e) || insufficientFunds, {
+            wrapperAddress,
+            receiver,
+            amount,
+        });
+        throwIfInsufficientFunds(insufficientFunds, 'Deposit native', e, {
             wrapperAddress,
             receiver,
             amount,
@@ -978,7 +1041,14 @@ async function rwaRedeemAsset(signer, options) {
         if (e instanceof core_1.AugustSDKError)
             throw e;
         // User-cancelled RWA redeems are normal; only genuine failures stay at error.
-        (0, core_1.logChainError)('rwaRedeemAsset', e, (0, core_1.isUserRejectionError)(e), {
+        const insufficientFunds = (0, core_1.isInsufficientFundsError)(e);
+        (0, core_1.logChainError)('rwaRedeemAsset', e, (0, core_1.isUserRejectionError)(e) || insufficientFunds, {
+            target,
+            asset,
+            amount,
+            minOut,
+        });
+        throwIfInsufficientFunds(insufficientFunds, 'RWA redeem', e, {
             target,
             asset,
             amount,

package/lib/sdk.d.ts

@@ -20191,6 +20191,8 @@ export declare function depositNative(signer: Signer | Wallet, options: INativeD
             */
            export declare function isHubOnlyReceipt(vault: IAddress): boolean;
 
+           export declare function isInsufficientFundsError(error: unknown): boolean;
+
            /**
             * True when `NODE_ENV` is `'development'` or `'test'`. The SDK auto-disables
             * analytics in these environments so partners' local dev runs and Jest suites

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@augustdigital/sdk",
-  "version": "8.9.0",
+  "version": "8.10.0",
   "main": "lib/index.js",
   "types": "lib/sdk.d.ts",
   "keywords": [