@upshiftfinance/sdk 0.0.0-stage → 0.2.0

package/lib/core/constants/web3.js

@@ -0,0 +1,251 @@
+"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.NON_EVM_CHAIN_IDS = exports.SUI_CHAIN_ID = exports.SPECIAL_CHAINS = void 0;
+// Special Chains
+/**
+ * Non-EVM chains the SDK routes to its own adapters, keyed by adapter name.
+ *
+ * Each gets a synthetic negative `chainId` so it can share numeric chain-ID
+ * parameters with EVM chains without ever colliding with a real EVM ID. The
+ * IDs match the backend's `chain` column (Solana `-1`, Sui `-2`, Stellar `-3`),
+ * so a backend vault row's `chain` can be compared to these directly.
+ */
+exports.SPECIAL_CHAINS = {
+    solana: {
+        name: 'Solana',
+        chainId: -1,
+        explorer: 'https://solscan.io',
+    },
+    sui: {
+        name: 'Sui',
+        chainId: -2,
+        explorer: 'https://suiscan.xyz',
+    },
+    stellar: {
+        name: 'Stellar',
+        chainId: -3,
+        explorer: 'https://stellar.expert',
+    },
+};
+/**
+ * Chain ID used to address Sui vaults: `-2`, the same synthetic ID the backend
+ * stores for Sui vault rows (see {@link SPECIAL_CHAINS}).
+ *
+ * Kept as its own export because callers and the Sui adapter import it by
+ * name. It lives in `core/` rather than `adapters/sui/constants.ts` so `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 = exports.SPECIAL_CHAINS.sui.chainId;
+/**
+ * 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.sui.chainId,
+    exports.SPECIAL_CHAINS.stellar.chainId,
+]);
+// General
+exports.NATIVE_ADDRESS = '0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE';
+/**
+ * Decimal precision of the native gas token on every EVM chain this SDK
+ * supports (ETH, Base, Arbitrum, Avalanche, Polygon, BNB, HyperEVM, Unichain,
+ * Mezo, Monad, Plasma, Ink, Flare, Katana, Citrea, Fluent, Tempo, X Layer —
+ * whose native OKB is also 18 decimals).
+ *
+ * All of them use 18-decimal native tokens, so this is a single constant rather
+ * than a per-chain map. It exists because the native token has no ERC-20
+ * `decimals()` to read on-chain: when a subgraph row denominates an amount in
+ * the native token it is flagged with a sentinel address ({@link NATIVE_ADDRESS}
+ * or the zero address) instead of a real contract, and callers must substitute
+ * this value rather than attempting (and failing) a `decimals()` read.
+ *
+ * Non-EVM natives differ (SOL is 9, XLM is 7) and are handled by their own
+ * adapters — those chains never flow through the EVM `decimals()` path this
+ * constant serves.
+ */
+exports.EVM_NATIVE_DECIMALS = 18;
+exports.MIN_ABIS = {
+    name: 'function name() view returns (string)',
+    symbol: 'function symbol() view returns (string)',
+    decimals: 'function decimals() view returns (uint8)',
+    totalSupply: 'function totalSupply() view returns (uint256)',
+    approve: 'function approve(address spender, uint256 value) external returns (bool success)',
+    allowance: 'function allowance(address owner, address spender) external view returns (uint256)',
+    managementFeePercent: 'function managementFeePercent() view returns (uint256)',
+};
+// Search: New Chain
+exports.ORACLE_CONTRACTS = {
+    1: '0xA4E24C498D5B28517787D8407eFdcB157A4FbF50', // mainnet
+    43114: '0x755537Cb5C76E06Bb492CF7c73567e252769c5f5', // avax
+    42161: '0x24F7BC5CA6E4b53cF7311dE1f5bF8Ba528400E1e', // arbitrum
+    8453: '0x07858dF2D8D9aB1DCAAA8b743eb80C6250DFA947', // base
+    10: '0xe0049eBCCB23Cb81c3d4C9Fa175b32876b70C2AB', // OP
+};
+// Networks
+// Search: New Chain
+// @todo: this should be used for wagmi configs
+exports.NETWORKS = {
+    1: {
+        name: 'Ethereum',
+        chainId: 1,
+        explorer: 'https://etherscan.io',
+    },
+    42161: {
+        name: 'Arbitrum One',
+        chainId: 42161,
+        explorer: 'https://arbiscan.io',
+    },
+    8453: {
+        name: 'Base',
+        chainId: 8453,
+        explorer: 'https://basescan.org',
+    },
+    43114: {
+        name: 'Avalanche',
+        chainId: 43114,
+        explorer: 'https://snowscan.xyz',
+    },
+    137: {
+        name: 'Polygon',
+        chainId: 137,
+        explorer: 'https://polygonscan.com',
+    },
+    56: {
+        name: 'BNB Smart Chain',
+        chainId: 56,
+        explorer: 'https://bscscan.com',
+    },
+    999: {
+        name: 'HyperEVM',
+        chainId: 999,
+        explorer: 'https://hyperevmscan.io',
+    },
+    130: {
+        name: 'Unichain',
+        chainId: 130,
+        explorer: 'https://uniscan.xyz',
+    },
+    31612: {
+        name: 'Mezo',
+        chainId: 31612,
+        explorer: 'https://explorer.mezo.org',
+    },
+    143: {
+        name: 'Monad',
+        chainId: 143,
+        explorer: 'https://monadscan.com',
+    },
+    9745: {
+        name: 'Plasma',
+        chainId: 9745,
+        explorer: 'https://plasmascan.to',
+    },
+    57073: {
+        name: 'Ink',
+        chainId: 57073,
+        explorer: 'https://explorer.inkonchain.com',
+    },
+    14: {
+        name: 'Flare',
+        chainId: 14,
+        explorer: 'https://flarescan.com',
+    },
+    747474: {
+        name: 'Katana',
+        chainId: 747474,
+        explorer: 'https://explorer.katanarpc.com',
+    },
+    4114: {
+        name: 'Citrea',
+        chainId: 4114,
+        explorer: 'https://explorer.mainnet.citrea.xyz',
+    },
+    25363: {
+        name: 'Fluent',
+        chainId: 25363,
+        explorer: 'https://fluentscan.xyz',
+    },
+    4217: {
+        name: 'Tempo',
+        chainId: 4217,
+        explorer: 'https://explore.tempo.xyz',
+    },
+    196: {
+        name: 'X Layer',
+        chainId: 196,
+        explorer: 'https://xlayerscan.com',
+    },
+};
+exports.AVAILABLE_CHAINS = Object.keys(exports.NETWORKS).map((c) => Number(c));
+/**
+ * Canonical [Multicall3](https://github.com/mds1/multicall) address, deployed
+ * via the deterministic deployer to the same address on most EVM chains.
+ * @internal
+ */
+exports.MULTICALL3_ADDRESS = '0xcA11bde05977b3631167028862bE2a173976CA11';
+/**
+ * Chains where the canonical Multicall3 deployment was **verified on-chain**
+ * (`eth_getCode` returned the 3808-byte runtime at {@link MULTICALL3_ADDRESS};
+ * checked per chain on 2026-07-14, Tempo checked separately on 2026-07-15,
+ * X Layer on 2026-08-11) —
+ * deterministic-deployer presence is NOT assumed. Chains outside this set
+ * keep the per-call read path.
+ *
+ * Deliberately excluded from `NETWORKS`:
+ * - 4114 (Citrea) — `eth_getCode` returned `0x` (not deployed).
+ * - -1 (Solana), -3 (Stellar) — non-EVM, no Multicall3.
+ * @internal
+ */
+exports.MULTICALL3_VERIFIED_CHAINS = new Set([
+    1, // Ethereum
+    42161, // Arbitrum One
+    8453, // Base
+    43114, // Avalanche
+    137, // Polygon
+    56, // BNB Smart Chain
+    999, // HyperEVM
+    130, // Unichain
+    31612, // Mezo
+    143, // Monad
+    9745, // Plasma
+    57073, // Ink
+    14, // Flare
+    747474, // Katana
+    25363, // Fluent
+    4217, // Tempo
+    196, // X Layer
+]);
+/**
+ * Fallbacks
+ */
+exports.FALLBACK_DECIMALS = 18;
+exports.FALLBACK_CHAINID = 42161;
+exports.FALLBACK_RPC_URLS = {
+    // Ethereum Mainnet
+    1: ['https://ethereum-rpc.publicnode.com'],
+    42161: ['https://arbitrum-one-rpc.publicnode.com'],
+    8453: ['https://base-rpc.publicnode.com'],
+    43114: ['https://avalanche-c-chain-rpc.publicnode.com'],
+    143: ['https://monad-mainnet.g.alchemy.com/v2/public'],
+    999: ['https://rpc.hyperliquid.xyz/evm'],
+    239: ['https://rpc.ankr.com/tac'],
+    80094: ['https://berachain-rpc.publicnode.com'],
+    59144: ['https://linea-rpc.publicnode.com'],
+    43111: ['https://rpc.hemi.network/rpc'],
+    146: ['https://rpc.soniclabs.com'],
+    534352: ['https://scroll.api.onfinality.io/public'],
+    10: ['https://optimism-mainnet.public.blastapi.io'],
+    9745: ['https://rpc.plasma.to'],
+    57073: ['https://rpc-gel.inkonchain.com'],
+    14: ['https://flare-api.flare.network/ext/C/rpc'],
+    747474: ['https://rpc.katana.network'],
+    4114: ['https://rpc.mainnet.citrea.xyz'],
+    25363: ['https://rpc.fluent.xyz'],
+    4217: ['https://rpc.mainnet.tempo.xyz'],
+    196: ['https://rpc.xlayer.tech'],
+};
+//# sourceMappingURL=web3.js.map

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

@@ -0,0 +1,177 @@
+/**
+ * Error class hierarchy for the SDK. All subclasses extend `UpshiftSDKError`,
+ * which extends the native `Error`.
+ *
+ * ```ts
+ * import { UpshiftAuthError, UpshiftTimeoutError } from '@upshiftfinance/sdk';
+ *
+ * try {
+ *   await sdk.getVault(...);
+ * } catch (err) {
+ *   if (err instanceof UpshiftAuthError) refreshKey();
+ *   else if (err instanceof UpshiftTimeoutError) retry();
+ *   else throw err;
+ * }
+ * ```
+ */
+/** Stable error codes attached to SDK errors. */
+export type UpshiftErrorCode = 'AUTH_MISSING_KEY' | 'AUTH_INVALID_KEY' | 'AUTH_FORBIDDEN' | 'AUTH_UNAUTHORIZED' | 'INVALID_URL' | 'INVALID_INPUT' | 'INVALID_CHAIN' | 'INVALID_ADDRESS' | 'ACCOUNT_NOT_FUNDED' | 'NO_SIGNER' | 'NETWORK_ERROR' | 'TIMEOUT' | 'RATE_LIMITED' | 'SERVER_ERROR' | 'TRANSACTION_UNCONFIRMED' | 'HISTORY_UNAVAILABLE' | 'PRICE_UNAVAILABLE' | 'UNKNOWN';
+/** Options accepted by every SDK error constructor. */
+export interface UpshiftErrorOptions {
+    /** Original error preserved for stack-trace chaining. */
+    cause?: unknown;
+    /** Set from the response `x-correlation-id` header when available. */
+    correlationId?: string;
+    /** Structured context attached to the error for logging. */
+    context?: Record<string, unknown>;
+}
+/** Base class for all SDK errors. */
+export declare class UpshiftSDKError extends Error {
+    readonly code: UpshiftErrorCode;
+    readonly correlationId?: string;
+    readonly context?: Record<string, unknown>;
+    constructor(code: UpshiftErrorCode, message: string, options?: UpshiftErrorOptions);
+    /**
+     * Serialize own properties to a plain object. Native `Error` enumerates
+     * nothing, so `JSON.stringify(err)` returns `"{}"` without this.
+     */
+    toJSON(): Record<string, unknown>;
+}
+/** Authentication/authorization failure: missing key, invalid key, forbidden. */
+export declare class UpshiftAuthError extends UpshiftSDKError {
+    constructor(code: Extract<UpshiftErrorCode, 'AUTH_MISSING_KEY' | 'AUTH_INVALID_KEY' | 'AUTH_FORBIDDEN' | 'AUTH_UNAUTHORIZED'>, message: string, options?: UpshiftErrorOptions);
+}
+/** Network-level failure: connection refused, DNS, fetch failed. */
+export declare class UpshiftNetworkError extends UpshiftSDKError {
+    constructor(message: string, options?: UpshiftErrorOptions);
+}
+/** Request exceeded its deadline. */
+export declare class UpshiftTimeoutError extends UpshiftSDKError {
+    /** Time elapsed (ms) before the request was aborted. */
+    readonly timeoutMs: number;
+    constructor(message: string, timeoutMs: number, options?: UpshiftErrorOptions);
+    toJSON(): Record<string, unknown>;
+}
+/** Caller-side input failed validation. */
+export declare class UpshiftValidationError extends UpshiftSDKError {
+    constructor(code: Extract<UpshiftErrorCode, 'INVALID_URL' | 'INVALID_INPUT' | 'INVALID_CHAIN' | 'INVALID_ADDRESS' | 'ACCOUNT_NOT_FUNDED'>, message: string, options?: UpshiftErrorOptions);
+}
+/** Backend rate-limited the request (HTTP 429 or equivalent). */
+export declare class UpshiftRateLimitError extends UpshiftSDKError {
+    /** Suggested wait before retrying, in milliseconds. */
+    readonly retryAfterMs?: number;
+    constructor(message: string, options?: UpshiftErrorOptions & {
+        retryAfterMs?: number;
+    });
+    toJSON(): Record<string, unknown>;
+}
+/** Backend returned a non-OK status that isn't auth, rate-limit, or timeout. */
+export declare class UpshiftServerError extends UpshiftSDKError {
+    /** HTTP status code returned by the backend. */
+    readonly status: number;
+    constructor(status: number, message: string, options?: UpshiftErrorOptions);
+    toJSON(): Record<string, unknown>;
+}
+/**
+ * Transaction/position history required to compute a value could not be
+ * retrieved or was empty, so the computed result would be wrong rather than
+ * merely missing.
+ *
+ * Motivation — the 2026-07-09 lifetime-PnL over-inflation incident. Lifetime
+ * PnL is `currentPosition + totalWithdrawn - totalDeposited`. Every
+ * history-fetch failure (deleted subgraph, subgraph deployed against the wrong
+ * ABI, missing archive backfill, deposits indexed on a different
+ * chain/contract) collapses the deposit/withdrawal history to empty. With
+ * `deposited = 0` and `withdrawn = 0` but a live on-chain `position > 0`, the
+ * formula degenerates to reporting the entire position as profit. Throwing this
+ * typed error makes that unrecoverable state fail loudly instead of returning
+ * an inflated number that looks plausible.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await sdk.vaults.getVaultUserLifetimePnl({ vault, wallet, options });
+ * } catch (err) {
+ *   if (err instanceof UpshiftHistoryUnavailableError) {
+ *     // History backfill is broken — surface "temporarily unavailable",
+ *     // never a fabricated PnL number.
+ *     showUnavailable(err.context);
+ *   } else throw err;
+ * }
+ * ```
+ */
+export declare class UpshiftHistoryUnavailableError extends UpshiftSDKError {
+    /**
+     * @param message - Human-readable description of the missing history. Callers
+     *   pass the same `#<method>::<vault>::<wallet>` prefix the surrounding getter
+     *   uses so log grouping stays consistent.
+     * @param options - Standard SDK error options. `context` should carry the
+     *   `{ vault, wallet }` (or equivalent) identifiers that scope the failure.
+     */
+    constructor(message: string, options?: UpshiftErrorOptions);
+}
+/**
+ * The USD price needed to convert a computed value could not be resolved, so
+ * any USD figure derived from it would be fabricated rather than merely
+ * missing.
+ *
+ * Motivation — `getVaultUserLifetimePnl` used to substitute a price of `1`
+ * whenever the price server returned nothing, which reported every
+ * USD field of a non-dollar vault (lsETH, tETH, BTC) at $1 per asset: a
+ * position worth ~$40k read as ~$13, indistinguishable from a real result.
+ * Throwing this typed error makes a missing price explicit so callers can hide
+ * the USD value instead of displaying a wrong one.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await sdk.getVaultUserLifetimePnl({ vault, wallet, chainId });
+ * } catch (err) {
+ *   if (err instanceof UpshiftPriceUnavailableError) {
+ *     // No USD price for the vault asset — hide the USD figures rather than
+ *     // show a fabricated one.
+ *     hideUsd(err.context);
+ *   } else throw err;
+ * }
+ * ```
+ */
+export declare class UpshiftPriceUnavailableError extends UpshiftSDKError {
+    /**
+     * @param message - Human-readable description of the missing price. Callers
+     *   pass the same `#<method>::<vault>::<wallet>` prefix the surrounding getter
+     *   uses so log grouping stays consistent.
+     * @param options - Standard SDK error options. `context` should carry the
+     *   identifiers that scope the failure (e.g. `{ vault, wallet, asset }`).
+     */
+    constructor(message: string, options?: UpshiftErrorOptions);
+}
+/**
+ * A transaction was sent but its outcome could not be established
+ * (`TRANSACTION_UNCONFIRMED`). It may have landed: check {@link signature}
+ * before resubmitting, or a deposit or redeem can execute twice.
+ * `context.reason` says what was seen (e.g. `expired_not_found`: the blockhash
+ * expired and no lookup found it, so it very likely never landed).
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await sdk.solana.vaultDeposit(programId, idl, wallet, amount, undefined, vault);
+ * } catch (err) {
+ *   if (err instanceof UpshiftTransactionError) showPending(err.signature);
+ *   else throw err;
+ * }
+ * ```
+ */
+export declare class UpshiftTransactionError extends UpshiftSDKError {
+    /** Signature of the transaction that was sent. */
+    readonly signature: string;
+    /**
+     * @param message - Human-readable description, naming the signature.
+     * @param signature - Signature of the transaction that was sent.
+     * @param options - Standard SDK error options.
+     */
+    constructor(message: string, signature: string, options?: UpshiftErrorOptions);
+    toJSON(): Record<string, unknown>;
+}
+/** Type guard. Works across realms (e.g. Web Worker / VM contexts). */
+export declare function isUpshiftSDKError(err: unknown): err is UpshiftSDKError;

package/lib/core/errors/index.js

@@ -0,0 +1,257 @@
+"use strict";
+/**
+ * Error class hierarchy for the SDK. All subclasses extend `UpshiftSDKError`,
+ * which extends the native `Error`.
+ *
+ * ```ts
+ * import { UpshiftAuthError, UpshiftTimeoutError } from '@upshiftfinance/sdk';
+ *
+ * try {
+ *   await sdk.getVault(...);
+ * } catch (err) {
+ *   if (err instanceof UpshiftAuthError) refreshKey();
+ *   else if (err instanceof UpshiftTimeoutError) retry();
+ *   else throw err;
+ * }
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UpshiftTransactionError = exports.UpshiftPriceUnavailableError = exports.UpshiftHistoryUnavailableError = exports.UpshiftServerError = exports.UpshiftRateLimitError = exports.UpshiftValidationError = exports.UpshiftTimeoutError = exports.UpshiftNetworkError = exports.UpshiftAuthError = exports.UpshiftSDKError = void 0;
+exports.isUpshiftSDKError = isUpshiftSDKError;
+/** Base class for all SDK errors. */
+class UpshiftSDKError extends Error {
+    code;
+    correlationId;
+    context;
+    constructor(code, message, options = {}) {
+        super(message);
+        this.name = 'UpshiftSDKError';
+        this.code = code;
+        this.correlationId = options.correlationId;
+        this.context = options.context;
+        if (options.cause !== undefined) {
+            this.cause = options.cause;
+        }
+        // Restore prototype chain for transpilation targets that downlevel `extends Error`.
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+    /**
+     * Serialize own properties to a plain object. Native `Error` enumerates
+     * nothing, so `JSON.stringify(err)` returns `"{}"` without this.
+     */
+    toJSON() {
+        const out = {
+            name: this.name,
+            message: this.message,
+            code: this.code,
+        };
+        if (this.correlationId !== undefined)
+            out.correlationId = this.correlationId;
+        if (this.context !== undefined)
+            out.context = this.context;
+        if (this.stack !== undefined)
+            out.stack = this.stack;
+        const cause = this.cause;
+        if (cause !== undefined) {
+            out.cause =
+                cause instanceof Error
+                    ? { name: cause.name, message: cause.message }
+                    : cause;
+        }
+        return out;
+    }
+}
+exports.UpshiftSDKError = UpshiftSDKError;
+/** Authentication/authorization failure: missing key, invalid key, forbidden. */
+class UpshiftAuthError extends UpshiftSDKError {
+    constructor(code, message, options) {
+        super(code, message, options);
+        this.name = 'UpshiftAuthError';
+    }
+}
+exports.UpshiftAuthError = UpshiftAuthError;
+/** Network-level failure: connection refused, DNS, fetch failed. */
+class UpshiftNetworkError extends UpshiftSDKError {
+    constructor(message, options) {
+        super('NETWORK_ERROR', message, options);
+        this.name = 'UpshiftNetworkError';
+    }
+}
+exports.UpshiftNetworkError = UpshiftNetworkError;
+/** Request exceeded its deadline. */
+class UpshiftTimeoutError extends UpshiftSDKError {
+    /** Time elapsed (ms) before the request was aborted. */
+    timeoutMs;
+    constructor(message, timeoutMs, options) {
+        super('TIMEOUT', message, options);
+        this.name = 'UpshiftTimeoutError';
+        this.timeoutMs = timeoutMs;
+    }
+    toJSON() {
+        return { ...super.toJSON(), timeoutMs: this.timeoutMs };
+    }
+}
+exports.UpshiftTimeoutError = UpshiftTimeoutError;
+/** Caller-side input failed validation. */
+class UpshiftValidationError extends UpshiftSDKError {
+    constructor(code, message, options) {
+        super(code, message, options);
+        this.name = 'UpshiftValidationError';
+    }
+}
+exports.UpshiftValidationError = UpshiftValidationError;
+/** Backend rate-limited the request (HTTP 429 or equivalent). */
+class UpshiftRateLimitError extends UpshiftSDKError {
+    /** Suggested wait before retrying, in milliseconds. */
+    retryAfterMs;
+    constructor(message, options) {
+        super('RATE_LIMITED', message, options);
+        this.name = 'UpshiftRateLimitError';
+        this.retryAfterMs = options?.retryAfterMs;
+    }
+    toJSON() {
+        const base = super.toJSON();
+        if (this.retryAfterMs !== undefined)
+            base.retryAfterMs = this.retryAfterMs;
+        return base;
+    }
+}
+exports.UpshiftRateLimitError = UpshiftRateLimitError;
+/** Backend returned a non-OK status that isn't auth, rate-limit, or timeout. */
+class UpshiftServerError extends UpshiftSDKError {
+    /** HTTP status code returned by the backend. */
+    status;
+    constructor(status, message, options) {
+        super('SERVER_ERROR', message, options);
+        this.name = 'UpshiftServerError';
+        this.status = status;
+    }
+    toJSON() {
+        return { ...super.toJSON(), status: this.status };
+    }
+}
+exports.UpshiftServerError = UpshiftServerError;
+/**
+ * Transaction/position history required to compute a value could not be
+ * retrieved or was empty, so the computed result would be wrong rather than
+ * merely missing.
+ *
+ * Motivation — the 2026-07-09 lifetime-PnL over-inflation incident. Lifetime
+ * PnL is `currentPosition + totalWithdrawn - totalDeposited`. Every
+ * history-fetch failure (deleted subgraph, subgraph deployed against the wrong
+ * ABI, missing archive backfill, deposits indexed on a different
+ * chain/contract) collapses the deposit/withdrawal history to empty. With
+ * `deposited = 0` and `withdrawn = 0` but a live on-chain `position > 0`, the
+ * formula degenerates to reporting the entire position as profit. Throwing this
+ * typed error makes that unrecoverable state fail loudly instead of returning
+ * an inflated number that looks plausible.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await sdk.vaults.getVaultUserLifetimePnl({ vault, wallet, options });
+ * } catch (err) {
+ *   if (err instanceof UpshiftHistoryUnavailableError) {
+ *     // History backfill is broken — surface "temporarily unavailable",
+ *     // never a fabricated PnL number.
+ *     showUnavailable(err.context);
+ *   } else throw err;
+ * }
+ * ```
+ */
+class UpshiftHistoryUnavailableError extends UpshiftSDKError {
+    /**
+     * @param message - Human-readable description of the missing history. Callers
+     *   pass the same `#<method>::<vault>::<wallet>` prefix the surrounding getter
+     *   uses so log grouping stays consistent.
+     * @param options - Standard SDK error options. `context` should carry the
+     *   `{ vault, wallet }` (or equivalent) identifiers that scope the failure.
+     */
+    constructor(message, options) {
+        super('HISTORY_UNAVAILABLE', message, options);
+        this.name = 'UpshiftHistoryUnavailableError';
+    }
+}
+exports.UpshiftHistoryUnavailableError = UpshiftHistoryUnavailableError;
+/**
+ * The USD price needed to convert a computed value could not be resolved, so
+ * any USD figure derived from it would be fabricated rather than merely
+ * missing.
+ *
+ * Motivation — `getVaultUserLifetimePnl` used to substitute a price of `1`
+ * whenever the price server returned nothing, which reported every
+ * USD field of a non-dollar vault (lsETH, tETH, BTC) at $1 per asset: a
+ * position worth ~$40k read as ~$13, indistinguishable from a real result.
+ * Throwing this typed error makes a missing price explicit so callers can hide
+ * the USD value instead of displaying a wrong one.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await sdk.getVaultUserLifetimePnl({ vault, wallet, chainId });
+ * } catch (err) {
+ *   if (err instanceof UpshiftPriceUnavailableError) {
+ *     // No USD price for the vault asset — hide the USD figures rather than
+ *     // show a fabricated one.
+ *     hideUsd(err.context);
+ *   } else throw err;
+ * }
+ * ```
+ */
+class UpshiftPriceUnavailableError extends UpshiftSDKError {
+    /**
+     * @param message - Human-readable description of the missing price. Callers
+     *   pass the same `#<method>::<vault>::<wallet>` prefix the surrounding getter
+     *   uses so log grouping stays consistent.
+     * @param options - Standard SDK error options. `context` should carry the
+     *   identifiers that scope the failure (e.g. `{ vault, wallet, asset }`).
+     */
+    constructor(message, options) {
+        super('PRICE_UNAVAILABLE', message, options);
+        this.name = 'UpshiftPriceUnavailableError';
+    }
+}
+exports.UpshiftPriceUnavailableError = UpshiftPriceUnavailableError;
+/**
+ * A transaction was sent but its outcome could not be established
+ * (`TRANSACTION_UNCONFIRMED`). It may have landed: check {@link signature}
+ * before resubmitting, or a deposit or redeem can execute twice.
+ * `context.reason` says what was seen (e.g. `expired_not_found`: the blockhash
+ * expired and no lookup found it, so it very likely never landed).
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await sdk.solana.vaultDeposit(programId, idl, wallet, amount, undefined, vault);
+ * } catch (err) {
+ *   if (err instanceof UpshiftTransactionError) showPending(err.signature);
+ *   else throw err;
+ * }
+ * ```
+ */
+class UpshiftTransactionError extends UpshiftSDKError {
+    /** Signature of the transaction that was sent. */
+    signature;
+    /**
+     * @param message - Human-readable description, naming the signature.
+     * @param signature - Signature of the transaction that was sent.
+     * @param options - Standard SDK error options.
+     */
+    constructor(message, signature, options) {
+        super('TRANSACTION_UNCONFIRMED', message, options);
+        this.name = 'UpshiftTransactionError';
+        this.signature = signature;
+    }
+    toJSON() {
+        return { ...super.toJSON(), signature: this.signature };
+    }
+}
+exports.UpshiftTransactionError = UpshiftTransactionError;
+/** Type guard. Works across realms (e.g. Web Worker / VM contexts). */
+function isUpshiftSDKError(err) {
+    return (err instanceof UpshiftSDKError ||
+        (err instanceof Error &&
+            typeof err.code === 'string' &&
+            err.name.startsWith('Upshift')));
+}
+//# sourceMappingURL=index.js.map