@augustdigital/sdk 8.17.0 → 8.19.0

package/lib/sdk.d.ts

@@ -15015,6 +15015,21 @@ export declare const ADAPTER_ABIS: {
  */
 export declare function allowance(signer: IContractRunner, options: IAllowanceOptions): Promise<bigint>;
 
+/**
+ * Append the active attribution suffix to calldata.
+ *
+ * No-ops (returns `data` unchanged) when attribution is off, the chain is
+ * excluded, `data` is empty/absent (plain value transfers are never
+ * attributed), or `data` already ends with the ERC-8021 marker (guards
+ * against double-appending when an upstream layer — e.g. a wagmi config
+ * `dataSuffix` — already attributed the transaction).
+ *
+ * @param data `0x`-prefixed calldata of the outgoing transaction.
+ * @param chainId EVM chain ID of the transaction, when known.
+ * @returns Calldata with the suffix appended, or the input unchanged.
+ */
+export declare function appendAttributionSuffix(data: string | undefined | null, chainId?: number): string | undefined | null;
+
 /**
  * Same approval logic as {@link vaultApprove} but returns a discriminated
  * union so callers can tell `sent` apart from `sufficient` and `native`
@@ -15486,7 +15501,7 @@ declare function assertNotStellar(address: string, operation: string): void;
       * @throws If `appName` is missing, malformed, or out of the allowed
       *   length range — see {@link IAugustBase.appName}.
       */
-     constructor({ appName, providers, keys, monitoring, analytics, versionCheck, timeoutMs, publicApiBaseUrl, }: IAugustBase);
+     constructor({ appName, providers, keys, monitoring, analytics, versionCheck, timeoutMs, publicApiBaseUrl, attribution, }: IAugustBase);
      /**
       * Verify API keys and authorize SDK usage.
       * TODO: initialize class with appropriate keys and verify august key
@@ -16977,6 +16992,26 @@ declare function assertNotStellar(address: string, operation: string): void;
   */
  export declare function balanceOf(signer: IContractRunner, options: IBalanceOfOptions): Promise<bigint>;
 
+ /**
+  * Build an ERC-8021 schema-0 attribution suffix from builder codes.
+  *
+  * Layout (appended to calldata, read back-to-front by parsers):
+  * `ascii(codes.join(','))` ∥ codesLength (1 byte) ∥ schemaId `0x00` ∥
+  * 16-byte marker `0x80218021802180218021802180218021`.
+  *
+  * @param codes Builder codes as printable-ASCII strings (e.g. `bc_abc123`),
+  *   each 1–64 chars, no commas; the comma-joined list must be ≤ 255 bytes.
+  * @returns `0x`-prefixed hex suffix ready to concatenate onto calldata.
+  * @throws Error when `codes` is empty, a code contains a comma or
+  *   non-printable/non-ASCII characters, or the joined list exceeds 255 bytes.
+  * @example
+  * ```typescript
+  * buildAttributionSuffix(['baseapp', 'morpho']);
+  * // '0x626173656170702c6d6f7270686f0e0080218021802180218021802180218021'
+  * ```
+  */
+ export declare function buildAttributionSuffix(codes: string[]): string;
+
  /**
   * Build a base IVault from backend data, shared across non-EVM adapters (Solana, Stellar).
   * Chain-specific fields (chainId, version, name, totalAssets, totalSupply, depositAssets, receipt)
@@ -17426,6 +17461,13 @@ declare function assertNotStellar(address: string, operation: string): void;
     */
    export declare const determineSecondsPerBlock: (chain: number) => number;
 
+   /**
+    * The 16-byte ERC-8021 suffix terminator. The last 16 bytes of an attributed
+    * transaction's calldata are always this marker; parsers read backwards from
+    * it to recover the schema ID and builder codes.
+    */
+   export declare const ERC8021_MARKER = "80218021802180218021802180218021";
+
    export declare const ERC_20_PERMIT_HASH = "0x6e71edae12b1b97f4d1f60370fef10105fa2faae0126114a169c64845d6126c9";
 
    declare function error(options: {
@@ -18143,6 +18185,19 @@ declare function assertNotStellar(address: string, operation: string): void;
             /** Classify an address by chain family (evm / solana / stellar / sui). */
             export declare function getAddressChainType(address: string): ChainType;
 
+            /**
+             * Return the active ERC-8021 suffix for a write on the given chain, or
+             * `undefined` when attribution is off or the chain is excluded.
+             *
+             * @param chainId EVM chain ID of the transaction, when the call site knows
+             *   it. When omitted and a `chains` restriction is configured, the suffix is
+             *   returned anyway (over-attribution is harmless; see
+             *   {@link IAttributionConfig.chains}).
+             * @returns `0x`-prefixed hex suffix, or `undefined` when nothing should be
+             *   appended.
+             */
+            export declare function getAttributionSuffix(chainId?: number): string | undefined;
+
             /**
              * Get all chain IDs that a vault supports (hub + all spokes).
              */
@@ -18180,12 +18235,86 @@ declare function assertNotStellar(address: string, operation: string): void;
             /**
              * 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>;
+
             /**
              * Previously fabricated a Goldsky subgraph URL from the chain name and vault
              * symbol. That guess is unreliable and produced dead endpoints:
@@ -18384,12 +18513,90 @@ declare function assertNotStellar(address: string, operation: string): void;
             /**
              * 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}`>;
 
+            /**
+             * 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>;
+
             /**
              * Fetches the remaining allocation for an address on a whitelist contract
              * @param signer - signer / provider object
@@ -19293,6 +19500,37 @@ declare function assertNotStellar(address: string, operation: string): void;
                  is_show_compound_apy?: boolean;
              }
 
+             /**
+              * Configuration for ERC-8021 calldata-suffix attribution (Base Builder Codes).
+              *
+              * @example
+              * ```typescript
+              * const sdk = new AugustSDK({
+              *   appName: 'my-app',
+              *   providers: { 8453: 'https://...' },
+              *   keys: { august: '...' },
+              *   attribution: { builderCodes: ['bc_abc123'] },
+              * });
+              * ```
+              */
+             export declare interface IAttributionConfig {
+                 /**
+                  * Builder codes to embed in the suffix, e.g. from base.dev registration
+                  * (`bc_…`). ASCII strings of 1–64 characters each; the comma-joined list
+                  * must fit in 255 bytes (schema 0 length prefix is a single byte).
+                  */
+                 builderCodes: string[];
+                 /**
+                  * EVM chain IDs to attribute. Omit to attribute writes on every EVM chain
+                  * (the suffix is inert on chains without an ERC-8021 indexer and costs
+                  * ~16 gas per non-zero byte). When set, writes on other chains are sent
+                  * without the suffix; call sites that cannot determine their chain ID
+                  * append the suffix regardless, since over-attribution is harmless and
+                  * under-attribution loses data.
+                  */
+                 chains?: number[];
+             }
+
              export declare interface IAugustBase {
                  /**
                   * Identifier-shaped name for the integrating application. Required.
@@ -19366,6 +19604,21 @@ declare function assertNotStellar(address: string, operation: string): void;
                   * a stale cross-environment base is higher blast-radius than a stale timeout.)
                   */
                  publicApiBaseUrl?: string;
+                 /**
+                  * ERC-8021 calldata-suffix attribution (Base Builder Codes). When set,
+                  * every EVM write sent through the SDK — ethers vault writes and the
+                  * cross-chain (OVault) viem writes — carries the attribution suffix so
+                  * offchain indexers (base.dev) can credit the transaction to your app.
+                  * Omit to send unattributed transactions (the default).
+                  *
+                  * Note: this is a process-global override applied on EVERY construction —
+                  * the last `AugustSDK` instantiated is authoritative, and one that omits
+                  * `attribution` RESETS it (same semantics as `publicApiBaseUrl`).
+                  *
+                  * @throws Throws synchronously from the constructor when the builder codes
+                  *   are malformed — see {@link IAttributionConfig}.
+                  */
+                 attribution?: IAttributionConfig;
              }
 
              /** Options for {@link balanceOf}. */
@@ -20725,6 +20978,54 @@ declare function assertNotStellar(address: string, operation: string): void;
 
              export declare function isEarlierThanNow(startTime: Date): boolean;
 
+             /**
+              * 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
+              * }
+              * ```
+              */
+             export declare function isEmptyViewResponse(error: unknown, expectedSelector?: string): boolean;
+
              /**
               * Is this error a routine on-chain read revert rather than a real failure?
               *
@@ -20886,6 +21187,51 @@ declare function assertNotStellar(address: string, operation: string): void;
               */
              export declare function isRetryableError(error: Error): boolean;
 
+             /**
+              * 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);
+              * }
+              * ```
+              */
+             export declare function isRetryableRpcError(error: unknown): boolean;
+
              /**
               * Check if a string is a valid Solana base58 address (including PDAs).
               * Returns `false` for EVM hex addresses.
@@ -23023,6 +23369,14 @@ declare function assertNotStellar(address: string, operation: string): void;
               */
              export declare function lookupSelector(selector: string): Promise<string[]>;
 
+             /**
+              * `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.
+              */
+             export declare const LP_TOKEN_ADDRESS_SELECTOR = "0xf5ae497a";
+
              /**
               * Map composability integrations from backend format to vault format.
               * Shared across all chain adapters.
@@ -23528,6 +23882,49 @@ declare function assertNotStellar(address: string, operation: string): void;
 
               /* Excluded from this release type: resolveSpender */
 
+              /**
+               * 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 },
+               * );
+               * ```
+               */
+              export declare function retryOnTransientRpc<T>(tag: string, operation: () => Promise<T>, context?: Record<string, unknown>, isRetryable?: (error: unknown) => boolean): Promise<T>;
+
               export declare const REWARD_DISTRIBUTOR_ADDRESS: (chainId: number) => string[];
 
               /**
@@ -24378,6 +24775,22 @@ declare function assertNotStellar(address: string, operation: string): void;
                   vault: IAddress;
               }): Promise<IAddress | undefined>;
 
+              /**
+               * Set (or clear) the process-global attribution config.
+               *
+               * Called unconditionally on every `AugustSDK` construction — an instance
+               * that omits `attribution` passes `null` and RESETS the state, so a prior
+               * instance's builder codes never leak into a later instance in the same
+               * process (same semantics as `setPublicApiBaseUrl`).
+               *
+               * @param config Attribution config from the SDK constructor, or `null` to
+               *   disable attribution.
+               * @throws Error when the config's builder codes fail validation — thrown
+               *   synchronously from the constructor so misconfiguration is caught at
+               *   init, not on the first write.
+               */
+              export declare function setAttribution(config: IAttributionConfig | null): void;
+
               declare function setDevMode(devMode: boolean): void;
 
               declare function setLogger(customLogger: SDKLogger): void;
@@ -26139,4 +26552,26 @@ declare function assertNotStellar(address: string, operation: string): void;
                                        1: IAddress;
                                    };
 
+                                   /**
+                                    * 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;
+
                                    export { }