@upshiftfinance/sdk 0.0.0-stage → 0.1.0

package/lib/core/attribution.js

@@ -0,0 +1,194 @@
+"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 IUpshiftBase.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.isStrictOrigin = isStrictOrigin;
+exports.getOriginCode = getOriginCode;
+exports.isAttributionEnabled = isAttributionEnabled;
+exports.getAttributionSuffix = getAttributionSuffix;
+exports.appendAttributionSuffix = appendAttributionSuffix;
+const swap_router_1 = require("./constants/swap-router");
+const errors_1 = require("./errors");
+/**
+ * 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('Upshift 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(`Upshift 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(`Upshift 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;
+let activeOriginCode = null;
+let activeStrictOrigin = false;
+/**
+ * Set (or clear) the process-global attribution config.
+ *
+ * Called unconditionally on every `UpshiftSDK` construction — an instance
+ * that omits `attribution` passes `null` and RESETS the state, so a prior
+ * instance's builder codes or origin code 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.
+ * @throws {@link UpshiftValidationError} when `originCode` is not a 32-byte
+ *   hex string.
+ */
+function setAttribution(config) {
+    if (!config) {
+        activeSuffix = null;
+        activeChains = null;
+        activeOriginCode = null;
+        activeStrictOrigin = false;
+        return;
+    }
+    const { originCode } = config;
+    if (originCode !== undefined && !swap_router_1.ORIGIN_CODE_PATTERN.test(originCode)) {
+        throw new errors_1.UpshiftValidationError('INVALID_INPUT', `Upshift SDK: attribution.originCode must be a 32-byte hex string (0x + 64 hex chars), got ${String(originCode).length} chars. Pass the bytes32 code registered on the SwapRouter via addOrigin.`, { context: { expectedLength: 66 } });
+    }
+    activeSuffix =
+        config.builderCodes === undefined
+            ? null
+            : buildAttributionSuffix(config.builderCodes);
+    activeChains =
+        Array.isArray(config.chains) && config.chains.length > 0
+            ? config.chains
+            : null;
+    activeOriginCode = originCode ?? null;
+    activeStrictOrigin = config.strictOrigin === true;
+}
+/**
+ * Whether {@link IAttributionConfig.strictOrigin} is set on the SDK instance.
+ *
+ * @returns `true` when an unregistered origin code must fail a deposit.
+ */
+function isStrictOrigin() {
+    return activeStrictOrigin;
+}
+/**
+ * The SwapRouter origin code configured on the SDK instance via
+ * {@link IAttributionConfig.originCode}.
+ *
+ * @returns The `bytes32` code, or `null` when none is configured.
+ */
+function getOriginCode() {
+    return activeOriginCode;
+}
+/**
+ * Whether attribution is configured at all, independent of any chain gate.
+ *
+ * Call sites that need to know whether to resolve a chain ID before asking
+ * for the suffix use this; {@link getAttributionSuffix} applies the gate.
+ *
+ * @returns `true` when builder codes are configured.
+ */
+function isAttributionEnabled() {
+    return activeSuffix !== null;
+}
+/**
+ * Return the active ERC-8021 suffix for a write on the given chain, or
+ * `undefined` when attribution is off or the chain is not attributed.
+ *
+ * @param chainId EVM chain ID of the transaction, when the call site knows
+ *   it. When a `chains` restriction is configured, gating is fail-closed: an
+ *   omitted chain ID yields no suffix, since a suffix on an unattributed
+ *   chain buys nothing and breaks hardware-wallet clear-signing (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) {
+        if (typeof chainId !== 'number')
+            return undefined;
+        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
+ * not attributed (including an unknown chain under a `chains` restriction),
+ * `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 verifyUpshiftKey(key: string): Promise<boolean>;

package/lib/core/auth/verify.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.verifyInfuraKey = verifyInfuraKey;
+exports.verifyUpshiftKey = verifyUpshiftKey;
+const analytics_1 = require("../analytics");
+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 verifyUpshiftKey(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 saves a request the backend would reject with a 401.
+    if (!key)
+        return false;
+    try {
+        const verify = await (0, fetcher_1.fetchUpshiftWithKey)(key, core_1.WEBSERVER_ENDPOINTS.auth.verify);
+        const success = verify.status === 200;
+        (0, analytics_1.trackKeyVerification)('upshift', success);
+        return success;
+    }
+    catch {
+        // Network errors, timeouts, and any future thrown auth errors all
+        // resolve to "key not verified" here. Callers handle this as a boolean.
+        (0, analytics_1.trackKeyVerification)('upshift', false);
+        return false;
+    }
+}
+//# sourceMappingURL=verify.js.map

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

@@ -0,0 +1,193 @@
+import type { ISolanaConfig, IStellarConfig, ISuiConfig, IAddress, IChainId, IEnv, IProvidersConfig, IWSMonitorHeaders } from '../types';
+import { type IAnalyticsConfig } from './analytics';
+import { type IVersionCheckConfig } from './version-check';
+import { type IAttributionConfig } from './attribution';
+import { type ICuratorAlertsConfig } from './logger/curator-alert';
+interface IKeys {
+    upshift?: string;
+    graph?: string;
+    coingecko?: string;
+}
+interface IMonitoring extends IWSMonitorHeaders {
+    slackWebhookUrl?: string;
+    env?: IEnv;
+    /**
+     * Curator notifications for failed vault redemptions. Enabled by default
+     * (opt-out model, like `analytics`).
+     *
+     * Stellar vaults are instant-redeem only, so when a redemption fails the
+     * vault's curator has no other way to learn about it. The SDK relays the
+     * failure to Upshift's notification service, which routes it to that curator's
+     * own channel — no credentials or curator identities are held here.
+     *
+     * Set `enabled: false` (or, in Node, the
+     * `UPSHIFT_SDK_DISABLE_CURATOR_ALERTS` env var) to stop emitting; set
+     * `endpoint` only to point a non-prod deployment at a test relay. Nothing is
+     * emitted unless `monitoring.env` is `PROD`, `NODE_ENV` is neither
+     * `development` nor `test`, and — in a browser, where `NODE_ENV` is not
+     * readable — the page is not served from localhost.
+     *
+     * `enabled: true` is the one exception: it bypasses all three gates, so a
+     * `DEV` or test integration that sets it can page a real curator. See
+     * {@link ICuratorAlertsConfig}.
+     */
+    curatorAlerts?: ICuratorAlertsConfig;
+}
+export interface IUpshiftBase {
+    /**
+     * 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 Upshift 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 UpshiftValidationError synchronously from the constructor if
+     *   missing, empty, or malformed.
+     *
+     * @example
+     * ```typescript
+     * const sdk = new UpshiftSDK({
+     *   appName: 'acme-trader',
+     *   providers: { 1: 'https://...' },
+     *   keys: { upshift: '...' },
+     * });
+     * ```
+     */
+    appName: string;
+    providers?: IProvidersConfig;
+    solana?: ISolanaConfig;
+    stellar?: IStellarConfig;
+    /**
+     * Sui configuration (network and an optional RPC endpoint). Omit to target
+     * Sui mainnet.
+     */
+    sui?: ISuiConfig;
+    /**
+     * Provider keys. Optional: vault reads and vault-linked sub-account reads
+     * work without an Upshift key. Supply `upshift` for admin and curator methods,
+     * for authenticated-user reads such as `getDiscountFactors`, and for
+     * sub-account reads where the subaccount is not linked to a vault.
+     */
+    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
+     * `UPSHIFT_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` (15 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 `UpshiftSDK` 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 `UpshiftSDK` 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).
+     *
+     * `attribution.originCode` sets the SwapRouter origin (referral /
+     * fee-sharing) code that every Ethereum mainnet SwapRouter deposit made
+     * through the SDK carries unless the call passes its own.
+     *
+     * Note: this is a process-global override applied on EVERY construction —
+     * the last `UpshiftSDK` 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}.
+     * @throws UpshiftValidationError synchronously from the constructor when
+     *   `originCode` is not a 32-byte hex string.
+     */
+    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 UpshiftBase {
+    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 UpshiftValidationError if `appName` is missing, malformed, or
+     *   out of the allowed length range — see {@link IUpshiftBase.appName}.
+     */
+    constructor({ appName, providers, keys, monitoring, analytics, versionCheck, timeoutMs, publicApiBaseUrl, attribution, }: IUpshiftBase);
+    /**
+     * Verify the configured Upshift API key and mark this instance as authorized.
+     * Only for SDKs built with `keys.upshift`; a keyless SDK skips `init()`.
+     * @throws Error when `keys.upshift` is missing or rejected by the API.
+     */
+    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 {};

package/lib/core/base.class.js

@@ -0,0 +1,163 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UpshiftBase = void 0;
+const auth_1 = require("./auth");
+const logger_1 = require("./logger");
+const analytics_1 = require("./analytics");
+const app_name_1 = require("./analytics/app-name");
+const version_check_1 = require("./version-check");
+const fetcher_1 = require("./fetcher");
+const attribution_1 = require("./attribution");
+const curator_alert_1 = require("./logger/curator-alert");
+/**
+ * Base class providing core SDK functionality including provider management,
+ * network switching, and authentication state.
+ */
+class UpshiftBase {
+    keys;
+    monitoring = {
+        'x-user-id': undefined,
+        'x-environment': undefined,
+    };
+    authorized;
+    activeNetwork;
+    providers;
+    /** Validated app-name slug from the constructor. */
+    appName;
+    /**
+     * Initialize base SDK with provider configuration and API keys.
+     * Sets up the first provider as the active network by default.
+     *
+     * @throws UpshiftValidationError if `appName` is missing, malformed, or
+     *   out of the allowed length range — see {@link IUpshiftBase.appName}.
+     */
+    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 = (0, app_name_1.validateAppName)(appName);
+        // TODO: change this to false later when upshift key is required
+        this.authorized = true;
+        this.providers = providers;
+        // Set active network from the first provider (if any).
+        // An empty providers map is valid for backend-only chains (e.g. Stellar).
+        if (Object.keys(providers).length > 0) {
+            this.activeNetwork = {
+                chainId: Number(Object.keys(providers)[0]),
+                rpcUrl: Object.values(providers)[0],
+            };
+        }
+        // Default to an empty set so the api and sub-account modules can read
+        // `this.keys.upshift` (undefined) instead of throwing on a keyless SDK.
+        this.keys = keys ?? {};
+        // Set environment (defaults to PROD for safety)
+        const environment = monitoring?.env || monitoring?.['x-environment'] || 'PROD';
+        this.monitoring = {
+            ...monitoring,
+            'x-environment': environment,
+        };
+        // Set dev mode for logging (only true if explicitly set to DEV)
+        logger_1.Logger.setDevMode(environment === 'DEV');
+        // Initialize analytics (pass API key for hashed identification + the
+        // appName so events can be filtered by consuming application).
+        (0, analytics_1.initializeSentry)(analytics ?? { enabled: true }, environment, this.appName, monitoring?.['x-user-id'], keys?.upshift);
+        // Best-effort version nudge — fire-and-forget, never blocks init, no
+        // network call in production. See `core/version-check.ts` for details.
+        (0, version_check_1.runVersionCheck)(versionCheck);
+        if (typeof timeoutMs === 'number') {
+            (0, fetcher_1.setSdkRequestTimeout)(timeoutMs);
+        }
+        // Repoint the unauthenticated `public` vault-catalog API when a non-prod
+        // deployment supplies an isolated backend. Called UNCONDITIONALLY so each
+        // instance is authoritative: an instance that omits `publicApiBaseUrl`
+        // passes `null` and RESETS to the compiled-in prod default. Without this a
+        // 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);
+        // Every backend request from this process now identifies the app
+        // (`x-august-app`) — same last-instance-wins contract as the base URL.
+        (0, fetcher_1.setSdkAppName)(this.appName);
+        // 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);
+        // Same reset-on-omit contract, for the same reason: an instance that says
+        // nothing about curator alerts gets the default (on in production), not
+        // whatever a previously-constructed instance asked for.
+        // Reports follow the API this instance reads from — resolved AFTER
+        // `setPublicApiBaseUrl` above, so a staging deployment alerts staging.
+        (0, curator_alert_1.configureCuratorAlerts)(monitoring?.curatorAlerts ?? null, {
+            appName: this.appName,
+            environment: environment,
+            apiBaseUrl: (0, fetcher_1.getPublicApiBaseUrl)(),
+        });
+    }
+    /**
+     * Verify the configured Upshift API key and mark this instance as authorized.
+     * Only for SDKs built with `keys.upshift`; a keyless SDK skips `init()`.
+     * @throws Error when `keys.upshift` is missing or rejected by the API.
+     */
+    async init() {
+        const [upshiftCheck] = await Promise.all([
+            (0, auth_1.verifyUpshiftKey)(this.keys?.upshift),
+        ]);
+        if (!upshiftCheck)
+            throw new Error('Upshift API key is invalid.');
+        this.authorized = true;
+        logger_1.Logger.log.info('init', 'Upshift SDK successfully initialized');
+        return;
+    }
+    /**
+     * Return the active network or throw a clear error.
+     * Use this in methods that require an EVM provider.
+     */
+    requireActiveNetwork() {
+        if (!this.activeNetwork) {
+            throw new Error('No active network configured. This operation requires an EVM provider. ' +
+                'Pass at least one provider in the SDK constructor, or call switchNetwork() first.');
+        }
+        return this.activeNetwork;
+    }
+    /**
+     * Switch the active blockchain network.
+     * Updates both chain ID and RPC URL for subsequent operations.
+     */
+    switchNetwork(chainId) {
+        if (!this.providers[chainId]) {
+            throw new Error(`No provider configured for chainId ${chainId}. Available chains: ${Object.keys(this.providers).join(', ')}`);
+        }
+        this.activeNetwork = {
+            chainId,
+            rpcUrl: this.providers[chainId],
+        };
+    }
+    /**
+     * Set active wallet address and update monitoring headers.
+     * Preserves existing environment setting.
+     */
+    updateWallet(address) {
+        if (!address)
+            return;
+        const lowercasedAddress = address.toLowerCase();
+        this.monitoring = {
+            ...this.monitoring,
+            'x-user-id': lowercasedAddress,
+        };
+        // Update analytics user identity
+        (0, analytics_1.updateUser)(lowercasedAddress, this.monitoring['x-environment']);
+    }
+    /**
+     * Remove wallet address from SDK state and monitoring headers.
+     */
+    clearWallet() {
+        if (this.monitoring) {
+            this.monitoring = {
+                ...this.monitoring,
+                'x-user-id': undefined,
+            };
+        }
+        // Clear wallet from analytics user identity
+        (0, analytics_1.clearUser)();
+    }
+}
+exports.UpshiftBase = UpshiftBase;
+//# sourceMappingURL=base.class.js.map

package/lib/core/cache.d.ts

@@ -0,0 +1,9 @@
+import { LRUCache } from 'lru-cache';
+/**
+ * Process-wide LRU used by core helpers for memoizing RPC / fetch results.
+ * Kept in a leaf module so importers don't pull in the broader `core/fetcher.ts`
+ * graph (which would cycle through `core/helpers/web3.ts`).
+ */
+export declare const CACHE: LRUCache<string, any, unknown>;
+export declare const getSafeCache: <T>(key: string) => Promise<T | null>;
+export declare const setSafeCache: <T>(key: string, value: T) => Promise<void>;

package/lib/core/cache.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setSafeCache = exports.getSafeCache = exports.CACHE = void 0;
+const lru_cache_1 = require("lru-cache");
+/**
+ * Process-wide LRU used by core helpers for memoizing RPC / fetch results.
+ * Kept in a leaf module so importers don't pull in the broader `core/fetcher.ts`
+ * graph (which would cycle through `core/helpers/web3.ts`).
+ */
+// biome-ignore lint/suspicious/noExplicitAny: shared heterogeneous cache keyed by string; a concrete value type would force casts at every call site and risk a dependency cycle through core/helpers/web3.ts.
+exports.CACHE = new lru_cache_1.LRUCache({
+    max: 1000,
+    ttl: 1000 * 60 * 60 * 24,
+    allowStale: true,
+});
+const getSafeCache = async (key) => {
+    if (!key)
+        return null;
+    if (exports.CACHE.has(key)) {
+        return exports.CACHE.get(key);
+    }
+    return null;
+};
+exports.getSafeCache = getSafeCache;
+const setSafeCache = async (key, value) => {
+    if (key && value) {
+        exports.CACHE.set(key, value);
+    }
+};
+exports.setSafeCache = setSafeCache;
+//# sourceMappingURL=cache.js.map