upshift-sdk 8.20.1

package/lib/core/analytics/user-identity.d.ts

@@ -0,0 +1,41 @@
+import type { IEnv } from '../../types';
+import type { IUserIdentity } from './types';
+/**
+ * Mask an API key, keeping only the last 5 characters visible.
+ * Example: "abcdefghij12345" -> "**********12345"
+ *
+ * @param apiKey - The raw API key to mask
+ * @returns Masked API key with last 5 characters visible
+ */
+export declare function hashApiKey(apiKey: string): string;
+/**
+ * Generate a session ID that persists for the SDK instance lifetime.
+ * Provides user continuity even when wallet is not connected.
+ *
+ * @returns UUID v4 session identifier
+ */
+export declare function getSessionId(): string;
+/**
+ * Generate a browser/environment fingerprint for cross-session tracking.
+ * Falls back gracefully in different environments.
+ *
+ * @returns Base64 encoded fingerprint string or undefined if unavailable
+ */
+export declare function generateFingerprint(): string | undefined;
+/**
+ * Create a composite user identity for analytics.
+ *
+ * @param apiKey - Optional API key (will be hashed, never stored raw)
+ * @param walletAddress - Optional wallet address
+ * @param environment - Current environment (DEV or PROD)
+ * @returns User identity object
+ */
+export declare function createUserIdentity(apiKey?: string, walletAddress?: string, environment?: IEnv): IUserIdentity;
+/**
+ * Generate a unique user ID for Sentry from identity components.
+ * Priority: apiKeyHash > wallet > fingerprint > session
+ *
+ * @param identity - User identity object
+ * @returns Prefixed user ID string
+ */
+export declare function getUserId(identity: IUserIdentity): string;

package/lib/core/analytics/user-identity.js

@@ -0,0 +1,141 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hashApiKey = hashApiKey;
+exports.getSessionId = getSessionId;
+exports.generateFingerprint = generateFingerprint;
+exports.createUserIdentity = createUserIdentity;
+exports.getUserId = getUserId;
+const crypto_1 = require("crypto");
+const uuid_1 = require("uuid");
+/** Session ID persists for SDK instance lifetime */
+let sessionId = null;
+/** Cached masked API key */
+let cachedMaskedApiKey = null;
+/**
+ * Mask an API key, keeping only the last 5 characters visible.
+ * Example: "abcdefghij12345" -> "**********12345"
+ *
+ * @param apiKey - The raw API key to mask
+ * @returns Masked API key with last 5 characters visible
+ */
+function hashApiKey(apiKey) {
+    if (!apiKey)
+        return '';
+    // Use cached masked key if available
+    if (cachedMaskedApiKey)
+        return cachedMaskedApiKey;
+    const visibleChars = 5;
+    if (apiKey.length <= visibleChars) {
+        cachedMaskedApiKey = apiKey;
+    }
+    else {
+        const masked = '*'.repeat(apiKey.length - visibleChars);
+        const visible = apiKey.slice(-visibleChars);
+        cachedMaskedApiKey = masked + visible;
+    }
+    return cachedMaskedApiKey;
+}
+/**
+ * Generate a session ID that persists for the SDK instance lifetime.
+ * Provides user continuity even when wallet is not connected.
+ *
+ * @returns UUID v4 session identifier
+ */
+function getSessionId() {
+    if (!sessionId) {
+        sessionId = (0, uuid_1.v4)();
+    }
+    return sessionId;
+}
+/**
+ * Generate a browser/environment fingerprint for cross-session tracking.
+ * Falls back gracefully in different environments.
+ *
+ * @returns Base64 encoded fingerprint string or undefined if unavailable
+ */
+function generateFingerprint() {
+    try {
+        // Browser environment
+        if (typeof window !== 'undefined' && typeof navigator !== 'undefined') {
+            const components = [
+                navigator.userAgent,
+                navigator.language,
+                new Date().getTimezoneOffset().toString(),
+                typeof screen !== 'undefined' ? screen.width?.toString() : '',
+                typeof screen !== 'undefined' ? screen.height?.toString() : '',
+                typeof screen !== 'undefined' ? screen.colorDepth?.toString() : '',
+            ].filter(Boolean);
+            // Create a simple hash from components
+            const hash = (0, crypto_1.createHash)('sha256')
+                .update(components.join('|'))
+                .digest('hex');
+            return hash.substring(0, 32);
+        }
+        // Node.js environment
+        if (typeof process !== 'undefined' && process.platform) {
+            const components = [process.platform, process.arch, process.version];
+            const hash = (0, crypto_1.createHash)('sha256')
+                .update(components.join('|'))
+                .digest('hex');
+            return hash.substring(0, 32);
+        }
+    }
+    catch {
+        // Silently fail if fingerprinting is not possible
+        return undefined;
+    }
+    return undefined;
+}
+/**
+ * Create a composite user identity for analytics.
+ *
+ * @param apiKey - Optional API key (will be hashed, never stored raw)
+ * @param walletAddress - Optional wallet address
+ * @param environment - Current environment (DEV or PROD)
+ * @returns User identity object
+ */
+function createUserIdentity(apiKey, walletAddress, environment = 'PROD') {
+    let domain;
+    try {
+        if (typeof window !== 'undefined' && window.location) {
+            domain = window.location.hostname;
+        }
+        else if (typeof process !== 'undefined' && process.env) {
+            domain = process.env.VERCEL_PROJECT_PRODUCTION_URL || undefined;
+        }
+    }
+    catch {
+        // Silently fail - domain is optional
+    }
+    return {
+        apiKeyHash: apiKey ? hashApiKey(apiKey) : undefined,
+        walletAddress: walletAddress?.toLowerCase(),
+        sessionId: getSessionId(),
+        fingerprint: generateFingerprint(),
+        environment,
+        domain,
+    };
+}
+/**
+ * Generate a unique user ID for Sentry from identity components.
+ * Priority: apiKeyHash > wallet > fingerprint > session
+ *
+ * @param identity - User identity object
+ * @returns Prefixed user ID string
+ */
+function getUserId(identity) {
+    if (identity.domain) {
+        return `domain:${identity.domain}`;
+    }
+    if (identity.apiKeyHash) {
+        return `apikey:${identity.apiKeyHash}`;
+    }
+    if (identity.walletAddress) {
+        return `wallet:${identity.walletAddress}`;
+    }
+    if (identity.fingerprint) {
+        return `fp:${identity.fingerprint}`;
+    }
+    return `session:${identity.sessionId}`;
+}
+//# sourceMappingURL=user-identity.js.map

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

@@ -0,0 +1,6 @@
+/**
+ * AUTO-GENERATED FILE - DO NOT EDIT
+ * Generated during publish from package.json version
+ * This file is gitignored and created at publish time
+ */
+export declare const SDK_VERSION = "8.20.1";

package/lib/core/analytics/version.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SDK_VERSION = void 0;
+/**
+ * AUTO-GENERATED FILE - DO NOT EDIT
+ * Generated during publish from package.json version
+ * This file is gitignored and created at publish time
+ */
+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

package/lib/core/auth/index.d.ts

@@ -0,0 +1 @@
+export * from './verify';

package/lib/core/auth/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./verify"), exports);
+//# sourceMappingURL=index.js.map

package/lib/core/auth/verify.d.ts

@@ -0,0 +1,2 @@
+export declare function verifyInfuraKey(key: string): Promise<boolean>;
+export declare function verifyAugustKey(key: string): Promise<boolean>;

package/lib/core/auth/verify.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.verifyInfuraKey = verifyInfuraKey;
+exports.verifyAugustKey = verifyAugustKey;
+const core_1 = require("../constants/core");
+const fetcher_1 = require("../fetcher");
+async function verifyInfuraKey(key) {
+    if (key.length !== 32)
+        return false;
+    const regex = /[a-z0-9]+/i;
+    if (!regex.test(key))
+        return false;
+    return true;
+}
+async function verifyAugustKey(key) {
+    // Fast path: no key means no verification possible. Returning false here
+    // preserves the historical contract (`init()` throws a generic "API key is invalid")
+    // and avoids letting an AUTH_MISSING_KEY error bubble up from the fetcher.
+    if (!key)
+        return false;
+    try {
+        const verify = await (0, fetcher_1.fetchAugustWithKey)(key, core_1.WEBSERVER_ENDPOINTS.auth.verify);
+        return verify.status === 200;
+    }
+    catch {
+        // Network errors, timeouts, and any future thrown auth errors all
+        // resolve to "key not verified" here. Callers handle this as a boolean.
+        return false;
+    }
+}
+//# sourceMappingURL=verify.js.map

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

@@ -0,0 +1,152 @@
+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;
+    coingecko?: string;
+}
+interface IMonitoring extends IWSMonitorHeaders {
+    slackWebhookUrl?: string;
+    env?: IEnv;
+}
+export interface IAugustBase {
+    /**
+     * Identifier-shaped name for the integrating application. Required.
+     *
+     * Pick a stable, kebab-case slug that identifies your product (e.g.
+     * `"acme-trader"`, `"my-defi-app"`). The SDK includes it on outbound
+     * analytics events so August Digital can see who's hitting which methods
+     * and reach out about breaking changes or critical bugs.
+     *
+     * Despite the friendly `appName` label, the value is used as a Sentry
+     * tag and HTTP header, so it must be identifier-shaped:
+     * 3–64 characters, `[a-zA-Z0-9._-]` only. Use a slug ("acme-trader"),
+     * not a display name ("Acme Trader").
+     *
+     * @throws Throws synchronously from the constructor if missing or empty.
+     *
+     * @example
+     * ```typescript
+     * const sdk = new AugustSDK({
+     *   appName: 'acme-trader',
+     *   providers: { 1: 'https://...' },
+     *   keys: { august: '...' },
+     * });
+     * ```
+     */
+    appName: string;
+    providers?: IProvidersConfig;
+    solana?: ISolanaConfig;
+    stellar?: IStellarConfig;
+    keys: IKeys;
+    monitoring?: IMonitoring;
+    /** Analytics configuration. Enabled by default (opt-out model). */
+    analytics?: IAnalyticsConfig;
+    /**
+     * Best-effort npm-registry version check. Enabled by default in
+     * non-production environments; never runs in `NODE_ENV=production`.
+     * Set `enabled: false` to disable entirely (or set the
+     * `AUGUST_SDK_DISABLE_VERSION_CHECK` env var).
+     */
+    versionCheck?: IVersionCheckConfig;
+    /**
+     * Default request timeout (in milliseconds) for backend API calls made by
+     * this SDK instance. Falls back to the SDK's compiled-in
+     * `REQUEST_TIMEOUT_MS` (90 s) when omitted.
+     *
+     * Per-call `timeoutMs` (when threaded through to the fetcher) still wins
+     * over this value. Setting this only changes the default that's used when
+     * no per-call value is supplied.
+     *
+     * Note: this is a process-global override on the underlying fetcher
+     * helpers, so the last `AugustSDK` instantiated wins if you create several
+     * with different timeouts in the same process.
+     */
+    timeoutMs?: number;
+    /**
+     * Override the base URL for the SDK's unauthenticated `public` vault-catalog
+     * API (what `getVault` / `getVaults` / `fetchTokenizedVault` read from).
+     * Defaults to the compiled-in prod base
+     * (`https://api.augustdigital.io/api/v1`) when omitted — so production apps
+     * pass nothing and behaviour is unchanged.
+     *
+     * Set this ONLY for a non-prod deployment that runs against an isolated
+     * backend (e.g. a staging API serving staging-only vaults). Must be an
+     * absolute http(s) URL including any base path, e.g.
+     * `https://api.staging.augustdigital.io/api/v1`. Invalid values are ignored.
+     *
+     * Note: this is a process-global override on the underlying fetcher helpers,
+     * applied on EVERY construction — so the last `AugustSDK` instantiated is
+     * authoritative, and one that omits `publicApiBaseUrl` RESETS to the prod
+     * default. (Stricter than `timeoutMs`, which stays sticky when omitted, since
+     * 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;
+    rpcUrl: string;
+}
+/**
+ * Base class providing core SDK functionality including provider management,
+ * network switching, and authentication state.
+ */
+export declare class AugustBase {
+    keys: IKeys;
+    monitoring: IMonitoring;
+    authorized: boolean;
+    activeNetwork?: IActiveNetwork;
+    providers: IProvidersConfig;
+    /** Validated app-name slug from the constructor. */
+    appName: string;
+    /**
+     * Initialize base SDK with provider configuration and API keys.
+     * Sets up the first provider as the active network by default.
+     *
+     * @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, attribution, }: IAugustBase);
+    /**
+     * Verify API keys and authorize SDK usage.
+     * TODO: initialize class with appropriate keys and verify august key
+     */
+    init(): Promise<void>;
+    /**
+     * Return the active network or throw a clear error.
+     * Use this in methods that require an EVM provider.
+     */
+    protected requireActiveNetwork(): IActiveNetwork;
+    /**
+     * Switch the active blockchain network.
+     * Updates both chain ID and RPC URL for subsequent operations.
+     */
+    switchNetwork(chainId: IChainId): void;
+    /**
+     * Set active wallet address and update monitoring headers.
+     * Preserves existing environment setting.
+     */
+    updateWallet(address: IAddress): void;
+    /**
+     * Remove wallet address from SDK state and monitoring headers.
+     */
+    clearWallet(): void;
+}
+export {};