@augustdigital/sdk 8.17.0 → 8.20.1

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

package/lib/core/helpers/web3.d.ts

@@ -33,7 +33,26 @@ export declare const determineSecondsPerBlock: (chain: number) => number;
  * @param chain Chain ID
  * @returns Block interval for pagination
  */
-export declare const determineBlockSkipInternal: (chain: number) => 1000 | 8000 | 50000;
+export declare const determineBlockSkipInternal: (chain: number) => 1000 | 8000 | 10000;
+/**
+ * Maximum JSON-RPC calls ethers may coalesce into a single batched HTTP
+ * request for a given endpoint.
+ *
+ * Providers advertise wildly different batch limits and reject the whole batch
+ * — not the excess — when exceeded, so one oversized batch fails every call
+ * inside it. dRPC's free tier caps batches at 3, which made every Mezo read
+ * fail with `server response 500 … "Batch of more than 3 requests are not
+ * allowed"` (the single highest-volume SDK error in production).
+ *
+ * Detection is host-based rather than chain-based because the limit is a
+ * property of the endpoint, not the chain: the same chain served by a
+ * self-hosted node has no such cap.
+ *
+ * @param rpcUrl - The RPC endpoint URL. Unparseable values fall back to the
+ *   conservative default rather than throwing.
+ * @returns Batch size cap to pass to ethers as `batchMaxCount`.
+ */
+export declare const determineRpcBatchMaxCount: (rpcUrl: string) => number;
 /**
  * Retrieve chain ID from web3 provider.
  * Handles both initialized and uninitialized provider states.
@@ -75,11 +94,84 @@ export { explorerLink } from './explorer-link';
 /**
  * Fetch token decimals from contract or Solana mint.
  * Results are cached to minimize RPC calls.
+ *
+ * **Never throws** — a failed read logs at error level and resolves
+ * `undefined`. Callers that must not silently proceed on an unknown scale (any
+ * path that encodes an amount) should use {@link getDecimalsOrThrow} instead:
+ * feeding `undefined` into `toNormalizedBn` silently defaults to 18 decimals.
+ *
  * @param provider Web3 provider
  * @param address Token contract address or Solana mint
- * @returns Number of decimals for the token
+ * @param isVault Resolve `address` as a vault (evm-2 vaults redirect to the
+ *   receipt token) rather than reading it as a plain ERC-20. Defaults to `true`.
+ * @returns Number of decimals for the token, or `undefined` when the read failed.
  */
 export declare const getDecimals: (provider: IContractRunner, address: IAddress, isVault?: boolean) => Promise<number>;
+/**
+ * Read a token's `decimals()` with the **same cache and stampede protection as
+ * {@link getDecimals}**, but surfacing failures instead of swallowing them, and
+ * retrying the transient ones.
+ *
+ * Two reasons this exists rather than a flag on `getDecimals`:
+ *
+ * 1. **`getDecimals` must keep returning `undefined` on failure** — a dozen
+ *    read paths depend on that. Amount-encoding paths need the opposite: an
+ *    `undefined` reaching `toNormalizedBn` silently means 18 decimals, which
+ *    misencodes the transaction. Here the original error propagates, so the
+ *    caller's `AugustSDKError` keeps its cause and its Sentry grouping.
+ * 2. **Retry.** Providers intermittently return an empty response to
+ *    `decimals()`, which ethers reports as
+ *    `missing revert data (action="call", data="0x313ce567", …)` — a shape a
+ *    deployed ERC-20 cannot legitimately produce, since `decimals()` takes no
+ *    arguments. That is retried here via {@link isEmptyViewResponse} scoped to
+ *    this exact selector, alongside ordinary transport faults
+ *    ({@link isRetryableRpcError}). The empty-view widening applies **only**
+ *    here; everywhere else the strict transport definition stands. A genuine
+ *    revert (`CALL_EXCEPTION` carrying revert data) is never retried.
+ *
+ * Cache is shared with `getDecimals`, so a read-then-write flow against the
+ * same token costs one `decimals()` RPC in total, and N concurrent callers for
+ * an uncached token collapse to one.
+ *
+ * **Exception — an unresolvable chain scope bypasses the cache entirely.** When
+ * {@link resolveProviderScope} cannot determine the chain (a runner with no
+ * resolved network and no connection URL, e.g. a browser provider before its
+ * first request), the only available key is the shared `unknown` bucket. Read
+ * paths happily use that bucket, and this function deliberately does not: the
+ * two paths have different blast radii. A wrong cached `decimals` on a read
+ * renders a wrong number on screen; on a write it misencodes an amount the user
+ * then *signs*. The collision needed — the same address being a different token
+ * with different decimals on two chains, within one process, across a
+ * mid-session chain switch — is narrow, but "no worse than the read path" is
+ * not the bar for a value that ends up in a transaction. In that case the read
+ * is neither served from nor written to the cache, and it also skips the
+ * in-flight dedup map, since joining another caller under an untrusted key
+ * would reintroduce exactly the collision being avoided. Retries still apply;
+ * the only thing forgone is the RPC saving.
+ *
+ * RPC cost: 1 on a cache miss, 0 on a hit, up to 3 on a miss that keeps
+ * faulting (~750ms of added latency in the worst case before it gives up).
+ * Always ≥1 when the chain scope is unresolvable.
+ *
+ * @param runner - Provider or signer to read through. A signer is unwrapped to
+ *   its provider for cache scoping, so it shares entries with reads on the
+ *   same chain.
+ * @param address - Token address. Read directly as an ERC-20 — pass the
+ *   receipt-token address yourself for an `evm-2` vault's share scale.
+ * @param tag - Low-cardinality label for retry breadcrumbs (e.g.
+ *   `'vaultDeposit:poolDecimals'`).
+ * @returns The token's decimals.
+ * @throws The underlying read error once retries are exhausted, or immediately
+ *   when the failure is neither a transport fault nor an empty view response.
+ *
+ * @example
+ * ```ts
+ * // Amount encoding must not proceed on a guessed scale.
+ * const decimals = await getDecimalsOrThrow(signer, token, 'deposit:decimals');
+ * const amount = toNormalizedBn(userInput, decimals);
+ * ```
+ */
+export declare const getDecimalsOrThrow: (runner: IContractRunner, address: IAddress, tag: string) => Promise<number>;
 /**
  * Fetch the whitelisted deposit-asset addresses from a vault's whitelist
  * contract. Cached with a 5-minute TTL; a fresh fetch fans out into N
@@ -87,12 +179,89 @@ export declare const getDecimals: (provider: IContractRunner, address: IAddress,
  * @internal
  */
 export declare const getWhitelistedAssets: (provider: IContractRunner, whitelistAddress: IAddress) => Promise<IAddress[]>;
+/**
+ * Read an `evm-2` vault's receipt (LP) token address via `lpTokenAddress()`,
+ * retrying only the transient transport faults and surfacing everything else
+ * unchanged.
+ *
+ * Why this exists: `lpTokenAddress()` sits immediately before the receipt-token
+ * `decimals()` read on every `evm-2` write path (approve / deposit / request
+ * redeem / swap-router deposit). Those `decimals()` reads were hardened against
+ * provider blips ({@link getDecimalsOrThrow}); the `lpTokenAddress()` read one
+ * line above them was not, so a single truncated `eth_call` response still
+ * failed the whole write with
+ * `missing revert data (action="call", data="0xf5ae497a", …)` — observed in
+ * production against a mainnet vault whose `lpTokenAddress()` demonstrably
+ * returns a real address when the provider is healthy.
+ *
+ * **This must never hide a misrouted vault, and does not.** `lpTokenAddress()`
+ * exists *only* on `evm-2` vaults. A vault wrongly classified as `evm-2` returns
+ * empty returndata for it, deterministically and forever, and that empty
+ * response is byte-identical to the transient one — it is the *only* signal the
+ * SDK gets that its version routing was wrong. So the retry here is deliberately
+ * shaped to preserve that signal:
+ *
+ * - it is **bounded** (3 attempts, ~750ms of backoff in total — see
+ *   `retryOnTransientRpc`), never open-ended;
+ * - on exhaustion it **rethrows the original error object**, with its identity,
+ *   message, `code` and `transaction.data` intact, so the caller's
+ *   `AugustSDKError` cause and Sentry grouping are exactly what they are today;
+ * - it has **no fallback**: it never substitutes another address, never resolves
+ *   the vault address itself, and never resolves `null`/`undefined`. It either
+ *   returns a real receipt-token address or throws.
+ *
+ * Net effect: a blip costs a retry, a misroute costs three `eth_call`s and then
+ * fails exactly as loudly as before.
+ *
+ * **Deliberately not cached.** Unlike `decimals()`, the vault→receipt-token
+ * mapping is not memoized here. Caching it would make a misroute's first
+ * (failed) probe and every subsequent one diverge, and would put a
+ * vault-identity mapping in the cache on the money path. The lenient, cached
+ * reader is {@link getReceiptTokenAddress} — use that on read paths that can
+ * tolerate `undefined`.
+ *
+ * RPC cost: exactly 1 `eth_call` on success; at most 3 when the provider keeps
+ * faulting.
+ *
+ * @param runner - Provider or signer to read through.
+ * @param vault - Address of the `evm-2` tokenized vault.
+ * @param tag - Low-cardinality label for retry breadcrumbs (e.g.
+ *   `'vaultRequestRedeem:receiptToken'`).
+ * @returns The vault's receipt (LP) token address. Never `null`/`undefined`.
+ * @throws The underlying read error, unmodified, once the bounded retries are
+ *   exhausted — or immediately when the failure is neither a transport fault nor
+ *   an empty response to this exact selector (e.g. a genuine revert carrying
+ *   revert data).
+ *
+ * @example
+ * ```ts
+ * const receiptToken = await getReceiptTokenAddressOrThrow(
+ *   signer,
+ *   vault,
+ *   'vaultRequestRedeem:receiptToken',
+ * );
+ * const decimals = await getDecimalsOrThrow(signer, receiptToken, 'tag');
+ * ```
+ */
+export declare const getReceiptTokenAddressOrThrow: (runner: IContractRunner, vault: IAddress, tag: string) => Promise<IAddress>;
 /**
  * Fetch receipt token address from tokenized vault contract.
  * Results are cached to minimize RPC calls.
+ *
+ * **Never throws** — a failed read logs at error level and resolves
+ * `undefined`, which several read paths depend on. The underlying
+ * `lpTokenAddress()` call is made through
+ * {@link getReceiptTokenAddressOrThrow}, so a transient provider blip is
+ * absorbed by a bounded retry before that happens; a deterministic failure (a
+ * vault that has no `lpTokenAddress()` because it is not `evm-2`) still resolves
+ * `undefined` after the attempts are spent, exactly as before. Callers on a
+ * money path must use {@link getReceiptTokenAddressOrThrow} directly instead —
+ * an `undefined` receipt-token address there would silently mis-address a
+ * `decimals()` read.
+ *
  * @param provider Web3 provider
  * @param address Tokenized vault contract address
- * @returns Receipt token address
+ * @returns Receipt token address, or `undefined` when the read failed.
  */
 export declare const getReceiptTokenAddress: (provider: IContractRunner, address: IAddress) => Promise<`0x${string}`>;
 /**