@augustdigital/sdk 8.17.0 → 8.20.1

package/lib/core/base.class.d.ts

@@ -1,6 +1,7 @@
 import type { ISolanaConfig, IStellarConfig, IAddress, IChainId, IEnv, IProvidersConfig, IWSMonitorHeaders } from '../types';
 import { type IAnalyticsConfig } from './analytics';
 import { type IVersionCheckConfig } from './version-check';
+import { type IAttributionConfig } from './attribution';
 interface IKeys {
     august?: string;
     graph?: string;
@@ -83,6 +84,21 @@ export interface IAugustBase {
      * 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;
 }
 interface IActiveNetwork {
     chainId: IChainId;
@@ -107,7 +123,7 @@ export declare class AugustBase {
      * @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

package/lib/core/base.class.js

@@ -6,6 +6,7 @@ const logger_1 = require("./logger");
 const analytics_1 = require("./analytics");
 const version_check_1 = require("./version-check");
 const fetcher_1 = require("./fetcher");
+const attribution_1 = require("./attribution");
 /**
  * Validate an appName at SDK construction time.
  *
@@ -55,7 +56,7 @@ class AugustBase {
      * @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, }) {
+    constructor({ appName, providers = {}, keys, monitoring, analytics, versionCheck, timeoutMs, publicApiBaseUrl, attribution, }) {
         // Validate first so the failure mode is a clear, actionable error before
         // any provider / analytics side effects run.
         this.appName = validateAppName(appName);
@@ -95,6 +96,10 @@ class AugustBase {
         // prior staging instance would leak into a later prod instance in the same
         // process — the inverse of the isolation this option exists to provide.
         (0, fetcher_1.setPublicApiBaseUrl)(publicApiBaseUrl ?? null);
+        // ERC-8021 attribution follows the same reset-on-omit contract as
+        // `publicApiBaseUrl`: called unconditionally so a prior instance's
+        // builder codes never leak into a later instance in the same process.
+        (0, attribution_1.setAttribution)(attribution ?? null);
     }
     /**
      * Verify API keys and authorize SDK usage.

package/lib/core/constants/core.js

@@ -5,6 +5,33 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DEFAULT_FETCH_OPTIONS = exports.WEBSERVER_ENDPOINTS = exports.WEBSERVER_URL = exports.PRICE_SERVER_URL = exports.REQUEST_TIMEOUT_MS = void 0;
 const ethers_1 = require("ethers");
+/**
+ * Build the path segment for a subaccount identifier.
+ *
+ * Why this exists: subaccounts are not EVM-only. Vault operators and loan
+ * borrowers can be Solana base58 keys or Stellar `G…`/`C…` addresses, and the
+ * backend keys those records by their native string form. Calling ethers'
+ * `getAddress()` on them throws `INVALID_ARGUMENT` before the request is ever
+ * made — which is how a Solana borrower turned every
+ * `getVaultAllocations` call for a mixed-chain vault into a
+ * `TypeError: invalid address` (see `getVaultAllocations:cefi` /
+ * `:otc` in Sentry).
+ *
+ * EVM addresses are still checksummed, because the backend expects the
+ * checksummed form for those and case-normalising avoids cache misses.
+ * Everything else is passed through URL-encoded so a malformed value can never
+ * inject extra path segments.
+ *
+ * @param subaccount - Subaccount identifier: EVM hex address, Solana base58
+ *   public key, or Stellar strkey. Not validated beyond the EVM branch — the
+ *   backend is the authority on whether a non-EVM identifier exists.
+ * @returns A single URL path segment safe to interpolate into an endpoint.
+ */
+function subaccountSegment(subaccount) {
+    return (0, ethers_1.isAddress)(subaccount)
+        ? (0, ethers_1.getAddress)(subaccount)
+        : encodeURIComponent(subaccount);
+}
 /**
  * Request timeout in milliseconds.
  * Set to 90 seconds to accommodate slow API responses.
@@ -34,22 +61,22 @@ exports.WEBSERVER_ENDPOINTS = {
     },
     subaccount: {
         list: (offset = 0, limit = 100) => `/subaccount?offset=${offset}&limit=${limit}`,
-        rewards: (subaccount) => `/subaccount/${(0, ethers_1.getAddress)(subaccount)}/rewards`,
-        tokens: (subaccount) => `/subaccount/${(0, ethers_1.getAddress)(subaccount)}/tokens`,
+        rewards: (subaccount) => `/subaccount/${subaccountSegment(subaccount)}/rewards`,
+        tokens: (subaccount) => `/subaccount/${subaccountSegment(subaccount)}/tokens`,
         twap: {
-            create: (subaccount) => `/subaccount/${(0, ethers_1.getAddress)(subaccount)}/twap`,
-            stop: (subaccount, id) => `/subaccount/${(0, ethers_1.getAddress)(subaccount)}/twap/${id}/stop`,
-            fills: (subaccount, id) => `/subaccount/${(0, ethers_1.getAddress)(subaccount)}/twap/${id}/fills`,
+            create: (subaccount) => `/subaccount/${subaccountSegment(subaccount)}/twap`,
+            stop: (subaccount, id) => `/subaccount/${subaccountSegment(subaccount)}/twap/${id}/stop`,
+            fills: (subaccount, id) => `/subaccount/${subaccountSegment(subaccount)}/twap/${id}/fills`,
         },
-        debank: (subaccount) => `/subaccount/${(0, ethers_1.getAddress)(subaccount)}/debank`,
-        health_factor: (subaccount) => `/subaccount/${(0, ethers_1.getAddress)(subaccount)}/health_factor`,
-        summary: (subaccount) => `/subaccount/${(0, ethers_1.getAddress)(subaccount)}/summary`,
-        batch: (subaccount) => `/subaccount/${(0, ethers_1.getAddress)(subaccount)}/tx_batcher_integrations`,
-        loans: (subaccount, side = 'BOTH', active = true) => `/subaccount/${(0, ethers_1.getAddress)(subaccount)}/loans?side=${side}&active=${active}`,
-        cefi: (subaccount) => `/subaccount/${(0, ethers_1.getAddress)(subaccount)}/cefi_position`,
-        otc_positions: (subaccount) => `/subaccount/${(0, ethers_1.getAddress)(subaccount)}/otc_positions`,
+        debank: (subaccount) => `/subaccount/${subaccountSegment(subaccount)}/debank`,
+        health_factor: (subaccount) => `/subaccount/${subaccountSegment(subaccount)}/health_factor`,
+        summary: (subaccount) => `/subaccount/${subaccountSegment(subaccount)}/summary`,
+        batch: (subaccount) => `/subaccount/${subaccountSegment(subaccount)}/tx_batcher_integrations`,
+        loans: (subaccount, side = 'BOTH', active = true) => `/subaccount/${subaccountSegment(subaccount)}/loans?side=${side}&active=${active}`,
+        cefi: (subaccount) => `/subaccount/${subaccountSegment(subaccount)}/cefi_position`,
+        otc_positions: (subaccount) => `/subaccount/${subaccountSegment(subaccount)}/otc_positions`,
         loanByAddress: (loanAddress, chainId) => `/subaccount/loans/${encodeURIComponent(loanAddress)}?chain_id=${chainId}`,
-        _: (subaccount) => `/subaccount/${(0, ethers_1.getAddress)(subaccount)}`,
+        _: (subaccount) => `/subaccount/${subaccountSegment(subaccount)}`,
     },
     transactions: {
         v2: (subaccount, startTime, endTime) => {
@@ -108,7 +135,7 @@ exports.WEBSERVER_ENDPOINTS = {
     },
     prices: (symbol) => `/prices/${symbol}`,
     metrics: {
-        pnl: (subaccount, startTime, endTime) => `/metrics/pnl?subaccount_address=${(0, ethers_1.getAddress)(subaccount)}${startTime && endTime ? `&start=${startTime}&end=${endTime}` : ''}`,
+        pnl: (subaccount, startTime, endTime) => `/metrics/pnl?subaccount_address=${subaccountSegment(subaccount)}${startTime && endTime ? `&start=${startTime}&end=${endTime}` : ''}`,
         vaultPerformanceFees: (params) => {
             const q = new URLSearchParams({
                 vault_address: params.vaultAddress,
@@ -126,7 +153,7 @@ exports.WEBSERVER_ENDPOINTS = {
     public: {
         integrations: {
             morpho: {
-                apy: (subaccount, vaultAddress) => `/integrations/morpho/apy?subaccount_address=${(0, ethers_1.getAddress)(subaccount)}&vault_address=${(0, ethers_1.getAddress)(vaultAddress)}`,
+                apy: (subaccount, vaultAddress) => `/integrations/morpho/apy?subaccount_address=${subaccountSegment(subaccount)}&vault_address=${(0, ethers_1.getAddress)(vaultAddress)}`,
             },
         },
         tokenizedVault: {

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

@@ -11,6 +11,23 @@ export declare const SPECIAL_CHAINS: {
         explorer: string;
     };
 };
+/**
+ * Chain ID used to address Sui vaults.
+ *
+ * Unlike Solana (`-1`) and Stellar (`-3`), Sui does not use a synthetic
+ * negative ID — `101` is the SLIP-44-derived value the Sui adapter has always
+ * used. It lives here rather than in `adapters/sui/constants.ts` so that
+ * `core/` can recognise it without importing the adapter layer (which would
+ * create a `core → adapters` back-edge); the adapter re-exports it.
+ */
+export declare const SUI_CHAIN_ID = 101;
+/**
+ * Chain IDs the SDK understands that are **not** served by an EVM JSON-RPC
+ * provider. Callers may legitimately pass these to vault methods without a
+ * matching entry in the `providers` map — the request routes through the
+ * Solana / Stellar / Sui adapter instead.
+ */
+export declare const NON_EVM_CHAIN_IDS: ReadonlySet<number>;
 export declare const NATIVE_ADDRESS = "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE";
 /**
  * Decimal precision of the native gas token on every EVM chain this SDK

package/lib/core/constants/web3.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.FALLBACK_RPC_URLS = exports.FALLBACK_CHAINID = exports.FALLBACK_DECIMALS = exports.MULTICALL3_VERIFIED_CHAINS = exports.MULTICALL3_ADDRESS = exports.AVAILABLE_CHAINS = exports.NETWORKS = exports.ORACLE_CONTRACTS = exports.MIN_ABIS = exports.EVM_NATIVE_DECIMALS = exports.NATIVE_ADDRESS = exports.SPECIAL_CHAINS = void 0;
+exports.FALLBACK_RPC_URLS = exports.FALLBACK_CHAINID = exports.FALLBACK_DECIMALS = exports.MULTICALL3_VERIFIED_CHAINS = exports.MULTICALL3_ADDRESS = exports.AVAILABLE_CHAINS = exports.NETWORKS = exports.ORACLE_CONTRACTS = exports.MIN_ABIS = exports.EVM_NATIVE_DECIMALS = exports.NATIVE_ADDRESS = exports.NON_EVM_CHAIN_IDS = exports.SUI_CHAIN_ID = exports.SPECIAL_CHAINS = void 0;
 // Special Chains
 exports.SPECIAL_CHAINS = {
     solana: {
@@ -14,6 +14,27 @@ exports.SPECIAL_CHAINS = {
         explorer: 'https://stellar.expert',
     },
 };
+/**
+ * Chain ID used to address Sui vaults.
+ *
+ * Unlike Solana (`-1`) and Stellar (`-3`), Sui does not use a synthetic
+ * negative ID — `101` is the SLIP-44-derived value the Sui adapter has always
+ * used. It lives here rather than in `adapters/sui/constants.ts` so that
+ * `core/` can recognise it without importing the adapter layer (which would
+ * create a `core → adapters` back-edge); the adapter re-exports it.
+ */
+exports.SUI_CHAIN_ID = 101;
+/**
+ * Chain IDs the SDK understands that are **not** served by an EVM JSON-RPC
+ * provider. Callers may legitimately pass these to vault methods without a
+ * matching entry in the `providers` map — the request routes through the
+ * Solana / Stellar / Sui adapter instead.
+ */
+exports.NON_EVM_CHAIN_IDS = new Set([
+    exports.SPECIAL_CHAINS.solana.chainId,
+    exports.SPECIAL_CHAINS.stellar.chainId,
+    exports.SUI_CHAIN_ID,
+]);
 // General
 exports.NATIVE_ADDRESS = '0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE';
 /**

package/lib/core/fetcher.js

@@ -23,6 +23,7 @@ const ethers_1 = require("ethers");
 const abis_1 = require("../abis");
 const lru_cache_1 = require("lru-cache");
 const chain_address_1 = require("./helpers/chain-address");
+const chain_error_1 = require("./helpers/chain-error");
 const fetcher_1 = require("../services/coingecko/fetcher");
 const logger_1 = require("./logger");
 const ethers_2 = require("ethers");
@@ -705,7 +706,15 @@ async function _fetchTokenPriceInternal(symbol, provider, coinGeckoKey, headers)
     if (foundVaultLpAsset?.vault && provider && version === 'evm-2') {
         try {
             const vaultContract = new ethers_2.Contract((0, ethers_1.getAddress)(foundVaultLpAsset?.vault), abis_1.ABI_TOKENIZED_VAULT_V2, provider);
-            const receiptAddress = (await vaultContract.lpTokenAddress());
+            // Same bounded, no-fallback retry the write paths use for this selector
+            // (`getReceiptTokenAddressOrThrow` in `core/helpers/web3`). It cannot be
+            // reused here: `helpers/web3` imports `fetchTokenizedVault` from this
+            // module, so importing it back would be a circular dependency (CLAUDE.md
+            // §9). A transient empty `eth_call` response is absorbed; a vault that
+            // genuinely lacks `lpTokenAddress()` still falls into the catch below
+            // after the attempts are spent.
+            const receiptAddress = await (0, chain_error_1.retryOnTransientRpc)('fetchTokenPrice:receiptToken', () => vaultContract.lpTokenAddress(), { vault: foundVaultLpAsset.vault }, (error) => (0, chain_error_1.isRetryableRpcError)(error) ||
+                (0, chain_error_1.isEmptyViewResponse)(error, chain_error_1.LP_TOKEN_ADDRESS_SELECTOR));
             const receiptContract = new ethers_2.Contract(receiptAddress, [web3_1.MIN_ABIS.decimals], provider);
             const decimals = Number(await receiptContract.decimals());
             const sharePrice = await vaultContract.getSharePrice();

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

@@ -46,6 +46,146 @@ export declare function isUserRejectionError(error: unknown): boolean;
  */
 export declare function isExpectedRevertError(error: unknown): boolean;
 export declare function isInsufficientFundsError(error: unknown): 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;
+/**
+ * `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";
+/**
+ * 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;
+/**
+ * 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>;
 /**
  * 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`