@augustdigital/sdk 8.17.0 → 8.20.1

package/lib/adapters/evm/index.js

@@ -57,8 +57,10 @@ class EVMAdapter {
         if (this.signer) {
             return this.signer;
         }
-        // Normalize and cache the signer
-        this.signer = await (0, signer_1.normalizeSigner)(this.rawSigner);
+        // Normalize and cache the signer. The attribution wrap is unconditional
+        // and reads the process-global config at send time, so a cached signer
+        // honors attribution enabled or reset after caching.
+        this.signer = (0, signer_1.wrapSignerWithAttribution)(await (0, signer_1.normalizeSigner)(this.rawSigner));
         return this.signer;
     }
     // Core EVM operations

package/lib/adapters/stellar/soroban.d.ts

@@ -58,9 +58,14 @@ export declare function getHealthyServer(config: ISorobanNetworkConfig): Promise
  * Exported so an operation with different semantics (e.g. an idempotency-aware
  * submission path) can compose or replace this policy via
  * {@link FailoverOptions.isRetryable} — extension without editing the core.
+ *
+ * Named distinctly from `core/helpers/chain-error`'s `isRetryableRpcError`
+ * (the EVM transport classifier, deliberately public) — the internal-dts
+ * leak check matches `@internal` tags by name across the whole `src.ts` tree,
+ * so a same-named pair would make it flag the public EVM one as a leak.
  * @internal
  */
-export declare function isRetryableRpcError(err: unknown): boolean;
+export declare function isRetryableSorobanRpcError(err: unknown): boolean;
 /**
  * Whether a simulation *error* string is a node/infrastructure failure (which
  * clears on another endpoint) rather than a genuine contract revert (which
@@ -76,7 +81,7 @@ export declare function isRetryableSimulationError(errorText: string): boolean;
  * failover core (Open/Closed at the call site).
  */
 export interface FailoverOptions {
-    /** Which thrown errors get the next endpoint. Defaults to {@link isRetryableRpcError}. */
+    /** Which thrown errors get the next endpoint. Defaults to {@link isRetryableSorobanRpcError}. */
     isRetryable?: (err: unknown) => boolean;
     /** Per-attempt timeout in ms. Defaults to {@link RPC_OPERATION_TIMEOUT_MS}. */
     timeoutMs?: number;
@@ -92,7 +97,7 @@ export interface FailoverOptions {
  * the health-gated server first (the fast, cached path) and, on a retryable
  * failure, drop that cached choice and retry the op against every endpoint in
  * priority order. Deterministic contract/domain errors short-circuit (see
- * {@link isRetryableRpcError}); each attempt is time-boxed so a hung node can't
+ * {@link isRetryableSorobanRpcError}); each attempt is time-boxed so a hung node can't
  * stall the loop.
  *
  * The `operation` is a strategy (dependency-injected), so new read/build calls

package/lib/adapters/stellar/soroban.js

@@ -11,7 +11,7 @@ exports.resolveNetworkConfig = resolveNetworkConfig;
 exports.resetHealthyServerCache = resetHealthyServerCache;
 exports.redactRpcUrl = redactRpcUrl;
 exports.getHealthyServer = getHealthyServer;
-exports.isRetryableRpcError = isRetryableRpcError;
+exports.isRetryableSorobanRpcError = isRetryableSorobanRpcError;
 exports.isRetryableSimulationError = isRetryableSimulationError;
 exports.withEndpointFailover = withEndpointFailover;
 exports.toBigIntAmount = toBigIntAmount;
@@ -291,9 +291,14 @@ async function probeHealthyServer(rpcUrls, cacheKey) {
  * Exported so an operation with different semantics (e.g. an idempotency-aware
  * submission path) can compose or replace this policy via
  * {@link FailoverOptions.isRetryable} — extension without editing the core.
+ *
+ * Named distinctly from `core/helpers/chain-error`'s `isRetryableRpcError`
+ * (the EVM transport classifier, deliberately public) — the internal-dts
+ * leak check matches `@internal` tags by name across the whole `src.ts` tree,
+ * so a same-named pair would make it flag the public EVM one as a leak.
  * @internal
  */
-function isRetryableRpcError(err) {
+function isRetryableSorobanRpcError(err) {
     return !(err instanceof core_1.AugustValidationError || err instanceof core_1.AugustSDKError);
 }
 /**
@@ -334,7 +339,7 @@ function dropCachedServer(rpcUrls) {
  * the health-gated server first (the fast, cached path) and, on a retryable
  * failure, drop that cached choice and retry the op against every endpoint in
  * priority order. Deterministic contract/domain errors short-circuit (see
- * {@link isRetryableRpcError}); each attempt is time-boxed so a hung node can't
+ * {@link isRetryableSorobanRpcError}); each attempt is time-boxed so a hung node can't
  * stall the loop.
  *
  * The `operation` is a strategy (dependency-injected), so new read/build calls
@@ -345,7 +350,7 @@ function dropCachedServer(rpcUrls) {
  * @internal
  */
 async function withEndpointFailover(config, method, operation, options = {}) {
-    const isRetryable = options.isRetryable ?? isRetryableRpcError;
+    const isRetryable = options.isRetryable ?? isRetryableSorobanRpcError;
     const timeoutMs = options.timeoutMs ?? RPC_OPERATION_TIMEOUT_MS;
     const rpcUrls = config.rpcUrls && config.rpcUrls.length > 0
         ? config.rpcUrls

package/lib/adapters/sui/constants.d.ts

@@ -1,4 +1,4 @@
-export declare const SUI_CHAIN_ID = 101;
+export { SUI_CHAIN_ID } from '../../core/constants/web3';
 export declare const EMBER_API_BASE_URL = "https://vaults.api.sui-prod.bluefin.io/api/v1/vaults";
 export declare const EMBER_ENDPOINTS: {
     readonly VAULTS: "/";

package/lib/adapters/sui/constants.js

@@ -1,7 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ALLOWED_SUI_VAULT_ADDRESSES = exports.EMBER_DEFAULTS = exports.EMBER_ENDPOINTS = exports.EMBER_API_BASE_URL = exports.SUI_CHAIN_ID = void 0;
-exports.SUI_CHAIN_ID = 101;
+// Canonical definition lives in `core/constants/web3.ts` so `core/` can
+// recognise the Sui chain ID without importing the adapter layer. Re-exported
+// here to keep `adapters/sui/constants` import sites (and the published API)
+// unchanged.
+var web3_1 = require("../../core/constants/web3");
+Object.defineProperty(exports, "SUI_CHAIN_ID", { enumerable: true, get: function () { return web3_1.SUI_CHAIN_ID; } });
 exports.EMBER_API_BASE_URL = 'https://vaults.api.sui-prod.bluefin.io/api/v1/vaults';
 exports.EMBER_ENDPOINTS = {
     VAULTS: '/',

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

@@ -2,4 +2,4 @@
  * Sentry DSN for SDK analytics.
  * This is an internal constant - not exposed to SDK users.
  */
-export declare const SENTRY_DSN = "https://d73b6a85fe14960b8dac8ac61a743a94@o4507215496609792.ingest.de.sentry.io/4510699327389776";
+export declare const SENTRY_DSN = "https://ca39246016d0b43154f0640314cbd3b5@o4507215496609792.ingest.de.sentry.io/4511864614813776";

package/lib/core/analytics/constants.js

@@ -5,5 +5,5 @@ exports.SENTRY_DSN = void 0;
  * Sentry DSN for SDK analytics.
  * This is an internal constant - not exposed to SDK users.
  */
-exports.SENTRY_DSN = 'https://d73b6a85fe14960b8dac8ac61a743a94@o4507215496609792.ingest.de.sentry.io/4510699327389776';
+exports.SENTRY_DSN = 'https://ca39246016d0b43154f0640314cbd3b5@o4507215496609792.ingest.de.sentry.io/4511864614813776';
 //# sourceMappingURL=constants.js.map

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

@@ -1,6 +1,13 @@
 import type * as Sentry from '@sentry/browser';
 import type { IEnv } from '../../types';
 import type { IAnalyticsConfig } from './types';
+/**
+ * Clear the error dedupe bookkeeping. Test-only — the rate limiter is process
+ * lifetime state and would otherwise leak between test cases.
+ *
+ * @internal
+ */
+export declare function resetErrorDedupe(): void;
 /**
  * Initialize Sentry with SDK-specific configuration. Idempotent: re-calls
  * only refresh user identity and the cached API-key hash.

package/lib/core/analytics/sentry.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.resetErrorDedupe = resetErrorDedupe;
 exports.initializeSentry = initializeSentry;
 exports.updateUser = updateUser;
 exports.clearUser = clearUser;
@@ -78,6 +79,164 @@ function safeSetUser(user) {
         // Silently fail - analytics should never break SDK
     }
 }
+/**
+ * Chains whose errors are dropped before reaching Sentry.
+ *
+ * Mezo is muted by request: its public dRPC endpoint is unreliable enough that
+ * its failures dominated the error stream without ever describing an SDK
+ * defect. This is a deliberate blind spot — Mezo bugs (bad vault data, reverts,
+ * decode failures) are silenced along with the transport noise. Remove the
+ * entry to restore reporting; nothing else needs to change.
+ *
+ * Keyed by both the `chainIdToTagValue` slug and the numeric chain ID, because
+ * the two arrive on different events.
+ */
+const MUTED_CHAIN_SLUGS = new Set(['mezo']);
+/** Numeric chain IDs matching {@link MUTED_CHAIN_SLUGS}. */
+const MUTED_CHAIN_IDS = new Set(['31612']);
+/**
+ * Substrings that identify an event as Mezo-related regardless of tags.
+ *
+ * Tag-based matching alone is not enough: `sdk.chain` / `sdk.last_chainId`
+ * record the last *instrumented method's* chain, not the chain of the RPC that
+ * actually failed — the production Mezo batch-rejection events are tagged
+ * `sdk.chain: ethereum` while carrying `"requestUrl": "https://mezo.drpc.org"`
+ * in the message. Matching the message body catches those.
+ */
+const MUTED_CHAIN_MESSAGE_PATTERNS = [/mezo/i];
+/**
+ * Whether an event belongs to a muted chain and must not be sent.
+ *
+ * Checks, in order: the chain tags, then the event message and every exception
+ * value/type in the chain (an RPC failure's identifying detail often lives in a
+ * wrapped inner error rather than the top-level message).
+ *
+ * @param event - The Sentry event about to be sent.
+ * @returns `true` when the event should be dropped.
+ */
+function isMutedChainEvent(event) {
+    const chainTag = event.tags?.['sdk.chain'];
+    if (typeof chainTag === 'string' && MUTED_CHAIN_SLUGS.has(chainTag)) {
+        return true;
+    }
+    const chainIdTag = event.tags?.['sdk.last_chainId'];
+    if (typeof chainIdTag === 'string' && MUTED_CHAIN_IDS.has(chainIdTag)) {
+        return true;
+    }
+    const haystacks = [];
+    if (typeof event.message === 'string')
+        haystacks.push(event.message);
+    for (const exception of event.exception?.values ?? []) {
+        if (typeof exception.value === 'string')
+            haystacks.push(exception.value);
+        if (typeof exception.type === 'string')
+            haystacks.push(exception.type);
+    }
+    return haystacks.some((text) => MUTED_CHAIN_MESSAGE_PATTERNS.some((pattern) => pattern.test(text)));
+}
+/**
+ * Rolling window, in milliseconds, over which identical errors are counted.
+ */
+const ERROR_DEDUPE_WINDOW_MS = 60_000;
+/**
+ * Maximum captures of one error signature per {@link ERROR_DEDUPE_WINDOW_MS}.
+ * Chosen so a genuine, ongoing failure is still visible (and its rate
+ * observable via `sdk.suppressed_since_last`) while a hot loop hammering a
+ * broken RPC or a 404-per-borrower fan-out cannot bill thousands of identical
+ * events. Beyond this, further captures in the window are dropped.
+ */
+const ERROR_DEDUPE_MAX_PER_WINDOW = 3;
+/** Hard cap on tracked signatures, so the map cannot grow without bound. */
+const ERROR_DEDUPE_MAX_KEYS = 500;
+/**
+ * Per-signature capture bookkeeping for the dedupe window.
+ *
+ * Deliberately process-global, matching the Sentry client it feeds: the client
+ * is a singleton, so every `AugustSDK` instance in the process shares one
+ * event stream and one quota. The signature intentionally omits partner/app
+ * identity — a host serving several partners reports an identical upstream
+ * failure ≤{@link ERROR_DEDUPE_MAX_PER_WINDOW} times per window in aggregate,
+ * not per partner, because the failure is one event regardless of how many
+ * tenants observed it. Per-tenant attribution comes from the `partner.id` tag
+ * on the events that are sent, and `sdk.suppressed_since_last` preserves the
+ * true rate. `resetAnalytics()` clears this map for the whole process.
+ */
+const errorDedupeState = new Map();
+/**
+ * Build a low-cardinality signature for an error.
+ *
+ * Message tails carry the variable parts (addresses, block ranges, response
+ * bodies), so only the leading 120 characters participate — enough to separate
+ * distinct failure modes without splitting one failure mode into thousands of
+ * unique keys.
+ *
+ * @param error - The normalized error being captured.
+ * @param origin - The `sdk.origin` call-site tag, when present.
+ * @returns A stable key identifying this class of failure.
+ */
+function errorSignature(error, origin) {
+    const tag = typeof origin === 'string' ? origin : '';
+    return `${tag}|${error.name}|${(error.message || '').slice(0, 120)}`;
+}
+/**
+ * Decide whether an error should be sent to Sentry, applying a per-signature
+ * rolling rate limit.
+ *
+ * Why this exists: the SDK is called from server-rendered pages that fan out
+ * per vault and per borrower, so a single upstream condition (a 502 from the
+ * backend, an RPC rejecting a batch) reproduces on every iteration of every
+ * request. Those are the same event, and paying Sentry per copy buys no extra
+ * signal.
+ *
+ * Side effect: mutates {@link errorDedupeState}.
+ *
+ * @param error - The normalized error about to be captured.
+ * @param origin - The `sdk.origin` call-site tag, when present.
+ * @returns `send: false` to drop the event. When `send: true`, `suppressed` is
+ *   the number of copies dropped since the last event that was sent, and is
+ *   attached to the outgoing event so the true rate stays recoverable.
+ */
+function admitError(error, origin) {
+    const key = errorSignature(error, origin);
+    const now = Date.now();
+    const entry = errorDedupeState.get(key);
+    // Touch the key on every access so iteration order is true
+    // least-recently-used, not first-inserted: a Map's `set` on an existing key
+    // does NOT reorder it, so without the delete a signature that keeps
+    // recurring would hold its original position and be evicted ahead of a stale
+    // one-shot signature registered after it — silently handing the hot
+    // signature a fresh allowance every time it churned out of the map.
+    errorDedupeState.delete(key);
+    if (!entry || now - entry.windowStart >= ERROR_DEDUPE_WINDOW_MS) {
+        // Bound the map: drop the least-recently-used signature before inserting.
+        if (errorDedupeState.size >= ERROR_DEDUPE_MAX_KEYS) {
+            const oldest = errorDedupeState.keys().next();
+            if (!oldest.done)
+                errorDedupeState.delete(oldest.value);
+        }
+        const suppressed = entry?.suppressed ?? 0;
+        errorDedupeState.set(key, { windowStart: now, captured: 1, suppressed: 0 });
+        return { send: true, suppressed };
+    }
+    errorDedupeState.set(key, entry);
+    if (entry.captured < ERROR_DEDUPE_MAX_PER_WINDOW) {
+        // `suppressed` can only be non-zero once the allowance is exhausted, so
+        // inside the allowance there is never a carried count to report.
+        entry.captured += 1;
+        return { send: true, suppressed: 0 };
+    }
+    entry.suppressed += 1;
+    return { send: false, suppressed: entry.suppressed };
+}
+/**
+ * Clear the error dedupe bookkeeping. Test-only — the rate limiter is process
+ * lifetime state and would otherwise leak between test cases.
+ *
+ * @internal
+ */
+function resetErrorDedupe() {
+    errorDedupeState.clear();
+}
 /**
  * Build the SDK's internal Sentry sink — the bridge that forwards
  * `Logger.log.*` output to the resolved Sentry SDK. Errors are captured as
@@ -95,6 +254,12 @@ function createSentrySink() {
                 const sdk = (0, sentry_runtime_1.getSentrySDK)();
                 if (!sdk)
                     return;
+                const normalized = error instanceof Error ? error : new Error(String(error));
+                // Rate-limit identical failures before touching Sentry at all — the
+                // scope work and the event payload are both wasted if it is dropped.
+                const admission = admitError(normalized, context?.tag);
+                if (!admission.send)
+                    return;
                 sdk.withScope((scope) => {
                     // `beforeSend` drops any event not tagged as ours; the tag is global
                     // already, but set it on the scope defensively in case a future
@@ -115,7 +280,10 @@ function createSentrySink() {
                             }
                         }
                     }
-                    const normalized = error instanceof Error ? error : new Error(String(error));
+                    // Preserve the true failure rate even though copies were dropped.
+                    if (admission.suppressed > 0) {
+                        scope.setExtra('sdk.suppressed_since_last', admission.suppressed);
+                    }
                     sdk.captureException(normalized);
                 });
             }
@@ -243,12 +411,22 @@ function initializeSentry(config, environment, walletAddress, apiKey, appName) {
                 // Local dev/test node leaking into a prod DSN: :8545 is the canonical
                 // Anvil/Hardhat port and is never a production RPC endpoint.
                 /ECONNREFUSED .*:8545/,
+                // AugustHistoryUnavailableError is a designed, documented outcome:
+                // the getter refuses to return a fabricated number when the indexer
+                // has no deposit/withdrawal history. It is thrown to the caller, who
+                // renders "temporarily unavailable" — the SDK is behaving correctly,
+                // so it is not an SDK issue. Indexer health is monitored separately.
+                /transaction history unavailable/i,
             ],
             beforeSend(event) {
                 // Only send events tagged as SDK-related
                 if (event.tags?.sdk !== 'august-digital') {
                     return null;
                 }
+                // Muted chains (see MUTED_CHAIN_SLUGS) are dropped wholesale.
+                if (isMutedChainEvent(event)) {
+                    return null;
+                }
                 return event;
             },
             beforeSendTransaction(transaction) {
@@ -383,6 +561,9 @@ function resetAnalytics() {
     cachedApiKey = undefined;
     logger_1.Logger.setSentrySink(null);
     (0, sentry_runtime_1.resetSentryRuntime)();
+    // The error rate limiter is process-lifetime state; a reset analytics layer
+    // must not inherit a half-full dedupe window from the previous one.
+    resetErrorDedupe();
 }
 /**
  * Capture an exception into Sentry with SDK-specific context. Use from

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

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

package/lib/core/analytics/version.js

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

package/lib/core/attribution.d.ts

@@ -0,0 +1,111 @@
+/**
+ * ERC-8021 transaction attribution (Base Builder Codes).
+ *
+ * ERC-8021 appends an attribution suffix to transaction calldata. Contracts
+ * decode their ABI-encoded arguments normally and ignore the trailing bytes,
+ * while offchain indexers (e.g. base.dev analytics for Base Builder Codes)
+ * read the suffix to attribute the transaction to the originating app.
+ *
+ * This is a leaf module: process-global state configured once via
+ * {@link IAugustBase.attribution} in the SDK constructor and read by the
+ * EVM write paths (the normalized-signer wrap in the EVM adapter and the
+ * cross-chain vault `writeContract` calls).
+ *
+ * @module attribution
+ */
+/**
+ * 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";
+/**
+ * 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 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[];
+}
+/**
+ * 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;
+/**
+ * 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;
+/**
+ * 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;
+/**
+ * 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;

package/lib/core/attribution.js

@@ -0,0 +1,142 @@
+"use strict";
+/**
+ * ERC-8021 transaction attribution (Base Builder Codes).
+ *
+ * ERC-8021 appends an attribution suffix to transaction calldata. Contracts
+ * decode their ABI-encoded arguments normally and ignore the trailing bytes,
+ * while offchain indexers (e.g. base.dev analytics for Base Builder Codes)
+ * read the suffix to attribute the transaction to the originating app.
+ *
+ * This is a leaf module: process-global state configured once via
+ * {@link IAugustBase.attribution} in the SDK constructor and read by the
+ * EVM write paths (the normalized-signer wrap in the EVM adapter and the
+ * cross-chain vault `writeContract` calls).
+ *
+ * @module attribution
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ERC8021_MARKER = void 0;
+exports.buildAttributionSuffix = buildAttributionSuffix;
+exports.setAttribution = setAttribution;
+exports.getAttributionSuffix = getAttributionSuffix;
+exports.appendAttributionSuffix = appendAttributionSuffix;
+/**
+ * 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.
+ */
+exports.ERC8021_MARKER = '80218021802180218021802180218021';
+/**
+ * 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'
+ * ```
+ */
+function buildAttributionSuffix(codes) {
+    if (!Array.isArray(codes) || codes.length === 0) {
+        throw new Error('August SDK: attribution.builderCodes must be a non-empty array of builder-code strings (e.g. ["bc_abc123"]). Register at https://base.dev to obtain one.');
+    }
+    for (const code of codes) {
+        if (typeof code !== 'string' ||
+            code.length === 0 ||
+            code.length > 64 ||
+            !/^[\x21-\x7e]+$/.test(code) ||
+            code.includes(',')) {
+            throw new Error(`August SDK: invalid builder code "${code}". Codes must be 1-64 printable ASCII characters with no commas or whitespace.`);
+        }
+    }
+    const joined = codes.join(',');
+    if (joined.length > 255) {
+        throw new Error(`August SDK: attribution builder codes exceed 255 bytes when comma-joined (got ${joined.length}). Use fewer or shorter codes.`);
+    }
+    let hex = '';
+    for (let i = 0; i < joined.length; i++) {
+        hex += joined.charCodeAt(i).toString(16).padStart(2, '0');
+    }
+    const length = joined.length.toString(16).padStart(2, '0');
+    return `0x${hex}${length}00${exports.ERC8021_MARKER}`;
+}
+let activeSuffix = null;
+let activeChains = null;
+/**
+ * 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.
+ */
+function setAttribution(config) {
+    if (!config) {
+        activeSuffix = null;
+        activeChains = null;
+        return;
+    }
+    activeSuffix = buildAttributionSuffix(config.builderCodes);
+    activeChains =
+        Array.isArray(config.chains) && config.chains.length > 0
+            ? config.chains
+            : null;
+}
+/**
+ * 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.
+ */
+function getAttributionSuffix(chainId) {
+    if (!activeSuffix)
+        return undefined;
+    if (activeChains && typeof chainId === 'number') {
+        if (!activeChains.includes(chainId))
+            return undefined;
+    }
+    return activeSuffix;
+}
+/**
+ * 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.
+ */
+function appendAttributionSuffix(data, chainId) {
+    const suffix = getAttributionSuffix(chainId);
+    if (!suffix)
+        return data;
+    if (typeof data !== 'string' || data === '' || data === '0x')
+        return data;
+    if (data.toLowerCase().endsWith(exports.ERC8021_MARKER))
+        return data;
+    return data + suffix.slice(2);
+}
+//# sourceMappingURL=attribution.js.map