@augustdigital/sdk 8.17.0 → 8.19.0

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

@@ -1,8 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.LP_TOKEN_ADDRESS_SELECTOR = void 0;
 exports.isUserRejectionError = isUserRejectionError;
 exports.isExpectedRevertError = isExpectedRevertError;
 exports.isInsufficientFundsError = isInsufficientFundsError;
+exports.isRetryableRpcError = isRetryableRpcError;
+exports.isEmptyViewResponse = isEmptyViewResponse;
+exports.retryOnTransientRpc = retryOnTransientRpc;
 exports.logChainError = logChainError;
 const logger_1 = require("../logger");
 /**
@@ -239,6 +243,414 @@ function isInsufficientFundsError(error) {
         return INSUFFICIENT_FUNDS_PHRASES.some((phrase) => msg.includes(phrase));
     });
 }
+/**
+ * Collect the HTTP status codes an error-like value may carry. Transport
+ * failures that reach us through ethers' `FetchRequest` keep the upstream
+ * status on the error (`status`), on the wrapped fetch response
+ * (`info.status` / `response.status`), or on a `statusCode` alias depending on
+ * which layer produced it. We scan all of them so a caller needn't know.
+ *
+ * @param error - The caught value, of unknown type.
+ * @returns Every numeric status found (possibly empty).
+ */
+function errorStatuses(error) {
+    const out = [];
+    const push = (value) => {
+        if (typeof value === 'number' && Number.isFinite(value))
+            out.push(value);
+    };
+    if (error && typeof error === 'object') {
+        const e = error;
+        push(e.status);
+        push(e.statusCode);
+        push(e.info?.status);
+        push(e.info?.statusCode);
+        push(e.response?.status);
+        push(e.response?.statusCode);
+    }
+    return out;
+}
+/**
+ * Does this error carry evidence that the EVM actually executed and reverted?
+ *
+ * Used as a **veto** by {@link isRetryableRpcError}: nodes reuse the generic
+ * JSON-RPC codes (`-32603`, `-32000`) for genuine execution reverts as well as
+ * for internal/transport faults, so a positive transport match must never win
+ * over a real revert. Evidence of real execution is:
+ *
+ * - a `CALL_EXCEPTION` that carries non-empty revert `data` (the ABI-encoded
+ *   custom error / `Error(string)` payload),
+ * - an `execution reverted` / `call revert exception` message anywhere in the
+ *   nested error chain,
+ * - an attached receipt with `status === 0` (the tx mined and failed).
+ *
+ * Note that a bare `CALL_EXCEPTION` with **no** revert data (ethers' `missing
+ * revert data`) is deliberately *not* evidence — see {@link isRetryableRpcError}.
+ *
+ * @param error - The caught value, of unknown type.
+ * @returns `true` when the error proves on-chain execution reverted.
+ */
+function hasRevertEvidence(error) {
+    if (error && typeof error === 'object') {
+        const e = error;
+        const codes = errorCodes(error);
+        if (codes.includes('CALL_EXCEPTION') &&
+            typeof e.data === 'string' &&
+            e.data.length > 2) {
+            return true;
+        }
+        if (e.receipt?.status === 0)
+            return true;
+    }
+    return nestedMessages(error).some((raw) => {
+        const msg = raw.toLowerCase();
+        return (msg.includes('execution reverted') ||
+            msg.includes('call revert exception'));
+    });
+}
+/**
+ * JSON-RPC error codes that indicate the *node or its transport* failed, not
+ * that the EVM rejected the call. `-32603` is the spec's "Internal error" and
+ * `-32000` the de-facto "Server error" both Alchemy and Infura emit for
+ * transient upstream faults (including while serving
+ * `eth_getTransactionReceipt` for a freshly broadcast tx).
+ */
+const RETRYABLE_RPC_CODES = [
+    -32603,
+    -32000,
+    'NETWORK_ERROR',
+    'SERVER_ERROR',
+    'TIMEOUT',
+    'ETIMEDOUT',
+    'ECONNRESET',
+    'ECONNREFUSED',
+    'ENOTFOUND',
+    'EAI_AGAIN',
+];
+/**
+ * Message fragments (lower-cased) that identify a transient transport failure.
+ *
+ * `could not coalesce error` is ethers v6's catch-all when it cannot map a
+ * node's JSON-RPC payload onto a typed error — in practice this is what a
+ * flaky provider looks like from inside `tx.wait()`. `eth_gettransactionreceipt`
+ * is included because a failure *naming that method* is by definition a receipt
+ * poll, which is safe to repeat: the transaction is already broadcast and
+ * polling is idempotent.
+ *
+ * `missing revert data` is deliberately **absent**. It is a `CALL_EXCEPTION`,
+ * not a transport frame, and {@link isExpectedRevertError} already treats it as
+ * a revert — having this predicate disagree would make the two classifiers
+ * contradict each other. The narrow subset of `missing revert data` that really
+ * is a transport artefact (an empty response to an argument-free view call) has
+ * its own predicate: {@link isEmptyViewResponse}.
+ */
+const RETRYABLE_RPC_PHRASES = [
+    'could not coalesce error',
+    'eth_gettransactionreceipt',
+    'timeout',
+    'timed out',
+    'etimedout',
+    'econnreset',
+    'econnrefused',
+    'enotfound',
+    'socket hang up',
+    'network error',
+    'network request failed',
+    'failed to fetch',
+    'fetch failed',
+    'load failed',
+    'connection closed',
+    'connection reset',
+    'too many requests',
+    'rate limit',
+    'service unavailable',
+    'bad gateway',
+    'gateway timeout',
+    'internal server error',
+    'internal error',
+    'server error',
+];
+/**
+ * Is this error a transient RPC **transport** failure that is safe to retry,
+ * rather than a decision the chain made?
+ *
+ * Why this exists: the SDK's write paths poll `eth_getTransactionReceipt` to
+ * confirm a broadcast transaction. When the provider hiccups mid-poll, ethers
+ * surfaces `could not coalesce error (error={ "code": -32603, … "method":
+ * "eth_getTransactionReceipt" … })`. Historically that propagated out of
+ * `safeWaitForTx` and the SDK reported the write as **failed** — even though
+ * the transaction was broadcast, its hash was known, and it mined fine. Users
+ * then retried and hit `ERC20InsufficientBalance` because the first attempt had
+ * in fact succeeded. Classifying the failure as transport-level lets callers
+ * re-poll instead of lying to the user.
+ *
+ * Matches, in order of precedence:
+ * 1. **Veto** — anything with revert evidence ({@link hasRevertEvidence}:
+ *    `CALL_EXCEPTION` carrying revert `data`, an `execution reverted` message,
+ *    or an attached `receipt.status === 0`) returns `false`. Nodes reuse
+ *    `-32603`/`-32000` for real reverts, so the veto must come first.
+ * 2. JSON-RPC / ethers transport codes — see `RETRYABLE_RPC_CODES`.
+ * 3. HTTP `429` and any `5xx` carried on the error.
+ * 4. Transport message fragments — see `RETRYABLE_RPC_PHRASES`.
+ *
+ * Retrying is only safe for **idempotent** work: re-reading an immutable value
+ * (`decimals()`) or re-polling a receipt for a hash that is already on the
+ * wire. Never use this to re-send a transaction.
+ *
+ * @param error - The caught value, of unknown type.
+ * @returns `true` when the failure is a transient transport fault worth
+ *   retrying with backoff; `false` for chain-level decisions (reverts) and for
+ *   anything unrecognised — the safe default is to surface the error.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   return await provider.waitForTransaction(hash, 1, 120_000);
+ * } catch (e) {
+ *   if (!isRetryableRpcError(e)) throw e; // real revert — surface it
+ *   await sleep(250);
+ *   return await provider.waitForTransaction(hash, 1, 120_000);
+ * }
+ * ```
+ */
+function isRetryableRpcError(error) {
+    if (error === null || error === undefined)
+        return false;
+    // A chain-level decision is never a transport fault. Check first: nodes
+    // reuse -32603/-32000 for genuine execution reverts.
+    if (hasRevertEvidence(error))
+        return false;
+    const codes = errorCodes(error);
+    if (codes.some((code) => RETRYABLE_RPC_CODES.includes(code)))
+        return true;
+    // 429 (rate limited) and any 5xx are upstream faults, not our request being
+    // wrong — 4xx other than 429 means retrying would fail identically.
+    if (errorStatuses(error).some((status) => status === 429 || (status >= 500 && status < 600))) {
+        return true;
+    }
+    return nestedMessages(error).some((raw) => {
+        const msg = raw.toLowerCase();
+        return RETRYABLE_RPC_PHRASES.some((phrase) => msg.includes(phrase));
+    });
+}
+/**
+ * `lpTokenAddress()` — `keccak256("lpTokenAddress()")[0..4]`. The August `evm-2`
+ * tokenized vault's receipt-token getter, exported so the readers that invoke it
+ * can scope {@link isEmptyViewResponse} to exactly this call instead of
+ * duplicating the literal.
+ */
+exports.LP_TOKEN_ADDRESS_SELECTOR = '0xf5ae497a';
+/**
+ * Four-byte selectors for the argument-free view functions that a correctly
+ * addressed contract **cannot** legitimately revert on. Each is
+ * `keccak256(signature)[0..4]`.
+ *
+ * These are the only calls for which an empty RPC response is unambiguously a
+ * provider artefact rather than a contract decision — the metadata they return
+ * is fixed at deployment and takes no arguments, so there is no input that
+ * could make them fail.
+ *
+ * **Caveat for `lpTokenAddress()`.** The four ERC-20 entries hold that property
+ * absolutely: any deployed, conforming token implements them. `lpTokenAddress()`
+ * holds it only *given correct routing* — the function exists on `evm-2` vaults
+ * and nowhere else, so a vault wrongly routed into the `evm-2` branch returns
+ * empty returndata **deterministically**, producing a byte-identical error to a
+ * provider blip. That ambiguity is resolved not by this predicate but by the
+ * caller: every reader that retries on this selector is bounded (3 attempts) and
+ * rethrows the original error once they are spent, so a deterministic misroute
+ * still surfaces unchanged — only a transient blip is absorbed. Never pair this
+ * selector with an unbounded retry or a fallback value.
+ */
+const ARGUMENT_FREE_VIEW_SELECTORS = new Set([
+    '0x313ce567', // decimals()
+    '0x95d89b41', // symbol()
+    '0x06fdde03', // name()
+    '0x18160ddd', // totalSupply()
+    exports.LP_TOKEN_ADDRESS_SELECTOR, // lpTokenAddress()
+]);
+/**
+ * Extract the 4-byte selector of the call an ethers `CALL_EXCEPTION` describes.
+ *
+ * ethers v6 attaches the attempted call as `error.transaction.data`, and also
+ * embeds it in the human-readable message as `data="0x…"`. We read the
+ * structured field first and fall back to the message so the predicate still
+ * works on an error that has been serialized and rehydrated (which is how these
+ * arrive from a logging pipeline).
+ *
+ * @param error - The caught value, of unknown type.
+ * @returns The lower-cased `0x`-prefixed 4-byte selector, or `null` when the
+ *   error does not name a call.
+ */
+function callSelector(error) {
+    if (error && typeof error === 'object') {
+        const e = error;
+        const data = e.transaction?.data;
+        if (typeof data === 'string' && /^0x[0-9a-fA-F]{8}/.test(data)) {
+            return data.slice(0, 10).toLowerCase();
+        }
+    }
+    // ethers renders the same field two ways depending on nesting depth:
+    // `data="0x313ce567"` at the top level and `"data": "0x313ce567"` inside the
+    // serialized `transaction={…}` blob. Accept both.
+    for (const raw of nestedMessages(error)) {
+        const match = raw.match(/data"?\s*[:=]\s*"(0x[0-9a-fA-F]{8})/);
+        if (match?.[1])
+            return match[1].toLowerCase();
+    }
+    return null;
+}
+/**
+ * Is this error an **empty RPC response to an argument-free view call** —
+ * i.e. a transport artefact wearing a revert's clothes?
+ *
+ * Why this is separate from {@link isRetryableRpcError}: when a provider
+ * truncates or 500s a response to `eth_call`, ethers reports
+ * `missing revert data (action="call", data="0x313ce567", …)` with a `null`
+ * `data` field. That is byte-for-byte the shape of a genuine revert with no
+ * reason string, so a general "transport" predicate cannot safely claim it —
+ * doing so would retry every data-less `CALL_EXCEPTION` in the SDK. This
+ * predicate narrows the claim to the one case where the ambiguity resolves:
+ * a **deployed ERC-20's `decimals()`/`symbol()`/`name()`/`totalSupply()` cannot
+ * legitimately revert**, because it takes no arguments and returns state fixed
+ * at deployment. An empty response there is the provider's fault, full stop.
+ *
+ * A match requires all of:
+ * 1. no revert evidence ({@link hasRevertEvidence}) — anything carrying real
+ *    revert `data`, an `execution reverted` message, or a failed receipt is out;
+ * 2. a `missing revert data` message;
+ * 3. an `action` of `call` or `staticCall` — a read, never a state change;
+ * 4. **when a selector is derivable** from the error, that it is
+ *    `expectedSelector` (if given) or one of
+ *    {@link ARGUMENT_FREE_VIEW_SELECTORS}. When no selector can be recovered,
+ *    conditions 1–3 stand on their own.
+ *
+ * Note the cost of a false positive is bounded and small: the caller retries an
+ * idempotent read a couple of times before surfacing the same error. The cost
+ * of a false negative is the production flood this predicate exists to stop.
+ *
+ * @param error - The caught value, of unknown type.
+ * @param expectedSelector - Optional `0x`-prefixed 4-byte selector the caller
+ *   knows it invoked (e.g. `'0x313ce567'` for `decimals()`). When supplied, the
+ *   error's own selector must match it — this stops a `decimals()` retry from
+ *   firing on an unrelated view call that happened to fail the same way.
+ * @returns `true` when the failure is an empty provider response to a view call
+ *   that cannot revert, and is therefore safe to retry.
+ *
+ * @example
+ * ```ts
+ * try { return Number(await erc20.decimals()); }
+ * catch (e) {
+ *   if (!isEmptyViewResponse(e, '0x313ce567')) throw e; // real problem
+ *   return Number(await erc20.decimals());              // provider blip
+ * }
+ * ```
+ */
+function isEmptyViewResponse(error, expectedSelector) {
+    if (error === null || error === undefined)
+        return false;
+    if (hasRevertEvidence(error))
+        return false;
+    const messages = nestedMessages(error).map((raw) => raw.toLowerCase());
+    if (!messages.some((msg) => msg.includes('missing revert data')))
+        return false;
+    // The call must be a read. ethers exposes this as a structured `action`
+    // ('call' | 'estimateGas' | 'sendTransaction' | …) and mirrors it in the
+    // message as action="call".
+    const action = error && typeof error === 'object'
+        ? error.action
+        : undefined;
+    const isRead = action === 'call' ||
+        action === 'staticCall' ||
+        messages.some((msg) => msg.includes('action="call"') || msg.includes('action="staticcall"'));
+    if (!isRead)
+        return false;
+    const selector = callSelector(error);
+    // Nothing to check against — conditions 1-3 already establish "empty response
+    // to a read", which is the signal we act on.
+    if (!selector)
+        return true;
+    if (expectedSelector)
+        return selector === expectedSelector.toLowerCase();
+    return ARGUMENT_FREE_VIEW_SELECTORS.has(selector);
+}
+/**
+ * How many times an idempotent RPC read is attempted in total (1 initial call +
+ * 2 retries) before the transport error is surfaced. Deliberately small:
+ * CLAUDE.md §4.2 — retrying harder during a provider outage amplifies load
+ * rather than recovering from it.
+ */
+const RPC_RETRY_ATTEMPTS = 3;
+/**
+ * Base backoff between retry attempts, in milliseconds. Doubles per attempt
+ * (250ms, then 500ms), so a fully-failed read costs ~750ms of added latency.
+ */
+const RPC_RETRY_BASE_DELAY_MS = 250;
+/**
+ * Run an **idempotent** RPC read, retrying with exponential backoff while the
+ * failure classifies as a transient transport fault
+ * ({@link isRetryableRpcError}).
+ *
+ * Lives next to the classifiers it consumes so there is exactly one retry
+ * implementation in the SDK: both the receipt-poll fallback in the vault write
+ * paths and the cached `decimals()` reader in `core/helpers/web3.ts` call this.
+ *
+ * Only safe for operations that can be repeated without side effects: polling
+ * `eth_getTransactionReceipt` for an already-broadcast hash, or re-reading an
+ * immutable value such as `decimals()`. **Never wrap a transaction send in
+ * this.**
+ *
+ * Anything that is not a transport fault (a genuine revert, a user rejection,
+ * an insufficient-funds rejection) is rethrown on the first attempt with no
+ * delay, so real failures still fail fast.
+ *
+ * @param tag - Low-cardinality log label for the retry breadcrumb.
+ * @param operation - The idempotent async read to run.
+ * @param context - Extra structured context for the retry breadcrumb (e.g.
+ *   `{ hash }`). Sanitized by the logger before transport.
+ * @param isRetryable - Predicate deciding whether a caught error warrants
+ *   another attempt. Defaults to the strict transport definition
+ *   ({@link isRetryableRpcError}); pass a wider one only where the call site
+ *   can prove the extra shape is also a provider artefact — the only such case
+ *   today is the selector-scoped {@link isEmptyViewResponse} used by
+ *   `getDecimalsOrThrow`.
+ * @returns Whatever `operation` resolves to on the first successful attempt.
+ * @throws The last error thrown by `operation` once retries are exhausted, or
+ *   immediately when the error is not retryable.
+ *
+ * @example
+ * ```ts
+ * const receipt = await retryOnTransientRpc(
+ *   'safeWaitForTx:transport-retry',
+ *   () => provider.waitForTransaction(hash, 1, 120_000),
+ *   { hash },
+ * );
+ * ```
+ */
+async function retryOnTransientRpc(tag, operation, context = {}, isRetryable = isRetryableRpcError) {
+    let lastError;
+    for (let attempt = 1; attempt <= RPC_RETRY_ATTEMPTS; attempt += 1) {
+        try {
+            return await operation();
+        }
+        catch (error) {
+            lastError = error;
+            if (!isRetryable(error) || attempt === RPC_RETRY_ATTEMPTS) {
+                throw error;
+            }
+            const delayMs = RPC_RETRY_BASE_DELAY_MS * 2 ** (attempt - 1);
+            logger_1.Logger.log.warn(tag, 'transient RPC error; retrying', {
+                ...context,
+                attempt,
+                attempts: RPC_RETRY_ATTEMPTS,
+                delayMs,
+                message: error instanceof Error ? error.message : String(error),
+            });
+            await new Promise((resolve) => setTimeout(resolve, delayMs));
+        }
+    }
+    // Unreachable: the loop either returns or throws on its final attempt.
+    throw lastError;
+}
 /**
  * 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/signer.d.ts

@@ -29,3 +29,24 @@ export declare function normalizeSigner(signer: Signer | Wallet | any): Promise<
  * Type that represents either an ethers signer or a viem wallet client
  */
 export type CompatibleSigner = Signer | Wallet | any;
+/**
+ * Wrap an ethers signer so every transaction it sends carries the active
+ * ERC-8021 attribution suffix (Base Builder Codes).
+ *
+ * Every ethers write in the SDK funnels through the wrapped signer's
+ * `sendTransaction`, so this single wrap attributes all vault writes. The
+ * wrapper is a Proxy — the caller's signer object is never mutated, so a
+ * signer reused outside the SDK sends unattributed transactions. Attribution
+ * state is read at send time, not wrap time; when no attribution is
+ * configured (see `IAugustBase.attribution`) the wrapper is a pass-through.
+ *
+ * Plain value transfers (no calldata) are never attributed, and calldata
+ * already ending in the ERC-8021 marker is left untouched. When the
+ * configured `chains` list requires a chain check and the transaction does
+ * not carry a `chainId`, the signer's provider network is consulted (one
+ * cached RPC call).
+ *
+ * @param signer Normalized ethers Signer or Wallet.
+ * @returns A proxied signer with an attribution-aware `sendTransaction`.
+ */
+export declare function wrapSignerWithAttribution<T extends Signer | Wallet>(signer: T): T;

package/lib/core/helpers/signer.js

@@ -3,7 +3,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.isViemWalletClient = isViemWalletClient;
 exports.viemToEthersSigner = viemToEthersSigner;
 exports.normalizeSigner = normalizeSigner;
+exports.wrapSignerWithAttribution = wrapSignerWithAttribution;
 const ethers_1 = require("ethers");
+const attribution_1 = require("../attribution");
 /**
  * Signer Compatibility Helpers
  *
@@ -90,4 +92,54 @@ async function normalizeSigner(signer) {
     // If we can't determine the type, throw an error
     throw new Error('Invalid signer type. Expected ethers Signer, ethers Wallet, or viem WalletClient');
 }
+/**
+ * Wrap an ethers signer so every transaction it sends carries the active
+ * ERC-8021 attribution suffix (Base Builder Codes).
+ *
+ * Every ethers write in the SDK funnels through the wrapped signer's
+ * `sendTransaction`, so this single wrap attributes all vault writes. The
+ * wrapper is a Proxy — the caller's signer object is never mutated, so a
+ * signer reused outside the SDK sends unattributed transactions. Attribution
+ * state is read at send time, not wrap time; when no attribution is
+ * configured (see `IAugustBase.attribution`) the wrapper is a pass-through.
+ *
+ * Plain value transfers (no calldata) are never attributed, and calldata
+ * already ending in the ERC-8021 marker is left untouched. When the
+ * configured `chains` list requires a chain check and the transaction does
+ * not carry a `chainId`, the signer's provider network is consulted (one
+ * cached RPC call).
+ *
+ * @param signer Normalized ethers Signer or Wallet.
+ * @returns A proxied signer with an attribution-aware `sendTransaction`.
+ */
+function wrapSignerWithAttribution(signer) {
+    return new Proxy(signer, {
+        get(target, prop) {
+            if (prop === 'sendTransaction') {
+                return async (tx) => {
+                    if (!(0, attribution_1.getAttributionSuffix)() || typeof tx?.data !== 'string') {
+                        return target.sendTransaction(tx);
+                    }
+                    let chainId = tx.chainId != null ? Number(tx.chainId) : undefined;
+                    if (chainId === undefined && target.provider) {
+                        try {
+                            chainId = Number((await target.provider.getNetwork()).chainId);
+                        }
+                        catch {
+                            // Unknown chain: fall through with chainId undefined, which
+                            // appends regardless of a `chains` restriction —
+                            // over-attribution is harmless, under-attribution loses data.
+                        }
+                    }
+                    const data = (0, attribution_1.appendAttributionSuffix)(tx.data, chainId);
+                    return target.sendTransaction(data === tx.data ? tx : { ...tx, data });
+                };
+            }
+            // `this`-bind reads to the target, not the proxy — ethers classes use
+            // private fields, which throw when methods run with a Proxy receiver.
+            const value = Reflect.get(target, prop, target);
+            return typeof value === 'function' ? value.bind(target) : value;
+        },
+    });
+}
 //# sourceMappingURL=signer.js.map