@augustdigital/sdk 8.5.0 → 8.6.0

package/lib/adapters/stellar/submit.js

@@ -10,12 +10,67 @@ const stellar_sdk_1 = require("@stellar/stellar-sdk");
 const core_1 = require("../../core");
 const soroban_1 = require("./soroban");
 const constants_1 = require("./constants");
+/**
+ * Best-effort decode of the transaction-level result code (the XDR union
+ * discriminant, e.g. `"txBadSeq"`, `"txTooLate"`) from a Soroban
+ * `TransactionResult`. Typed `unknown` and probed structurally so it stays
+ * robust to RPC/SDK shape drift; returns `undefined` for anything that isn't a
+ * decoded union, so callers fall back to the stringified XDR in the message.
+ */
+function extractTxResultCode(result) {
+    try {
+        const decoded = result;
+        if (typeof decoded?.result !== 'function')
+            return undefined;
+        // `|| undefined`: an empty discriminant shares the clean "no code" path.
+        return decoded.result().switch().name || undefined;
+    }
+    catch (e) {
+        // Only reached on a malformed / shape-drifted union (the non-union case
+        // already returned above). Breadcrumb it so decoder rot stays detectable;
+        // the caller still throws with the stringified XDR in the message.
+        core_1.Logger.log.warn('extractTxResultCode', { decodeError: String(e) });
+        return undefined;
+    }
+}
+/**
+ * `JSON.stringify` that never throws. A real `xdr.TransactionResult` can hold
+ * `bigint` fields (e.g. `feeCharged`), which make `JSON.stringify` throw a
+ * `TypeError` — that would escape and replace the `AugustSDKError` this detail
+ * is only meant to enrich. Returns `''` on failure so the caller falls back to
+ * the status; the decoded `resultCode` still carries the precise reason.
+ */
+function safeStringify(value) {
+    try {
+        return JSON.stringify(value) ?? '';
+    }
+    catch {
+        return '';
+    }
+}
 /**
  * Submit a signed Soroban transaction and poll until confirmed.
  *
- * @param signedXdr Base64-encoded XDR of the signed transaction
- * @param network Stellar network name
- * @returns Transaction hash on success
+ * @param signedXdr - Base64-encoded XDR of the signed transaction
+ * @param network - Stellar network name
+ * @returns The transaction hash once the network confirms it as successful
+ * @throws {@link AugustTimeoutError} when the transaction is not confirmed
+ *   within the poll budget (`MAX_POLL_ATTEMPTS`).
+ * @throws {@link AugustSDKError} when the RPC rejects the submission or the
+ *   transaction confirms as failed. Its `context` carries `{ network, status }`
+ *   plus, when the result XDR decodes, a `resultCode` string holding the
+ *   transaction-level reason (e.g. `"txBadSeq"`, `"txTooLate"`); `resultCode`
+ *   is `undefined` when the code cannot be decoded.
+ * @example
+ * ```ts
+ * try {
+ *   const hash = await submitStellarTransaction(signedXdr, 'mainnet');
+ * } catch (err) {
+ *   if (err instanceof AugustSDKError && err.context?.resultCode === 'txBadSeq') {
+ *     // stale sequence number — rebuild the transaction and resubmit
+ *   }
+ * }
+ * ```
  */
 async function submitStellarTransaction(signedXdr, network) {
     const { rpcUrl, passphrase } = (0, soroban_1.resolveNetworkConfig)(network);
@@ -23,11 +78,13 @@ async function submitStellarTransaction(signedXdr, network) {
     const tx = stellar_sdk_1.TransactionBuilder.fromXDR(signedXdr, passphrase);
     const sendResult = await server.sendTransaction(tx);
     if (sendResult.status === 'ERROR') {
-        const detail = 'errorResult' in sendResult ? JSON.stringify(sendResult.errorResult) : '';
+        const errorResult = 'errorResult' in sendResult ? sendResult.errorResult : undefined;
+        const resultCode = extractTxResultCode(errorResult);
+        const detail = errorResult ? safeStringify(errorResult) : '';
         const msg = `Transaction submission failed: ${detail || sendResult.status}`;
-        core_1.Logger.log.error('submitStellarTransaction', msg, { network });
+        core_1.Logger.log.error('submitStellarTransaction', msg, { network, resultCode });
         throw new core_1.AugustSDKError('UNKNOWN', msg, {
-            context: { network, status: sendResult.status },
+            context: { network, status: sendResult.status, resultCode },
         });
     }
     // Only PENDING (and DUPLICATE) mean the tx was accepted by the RPC.
@@ -66,14 +123,23 @@ async function submitStellarTransaction(signedXdr, network) {
     if (getResult.status === 'SUCCESS') {
         return sendResult.hash;
     }
-    const failDetail = 'resultXdr' in getResult ? ` (${JSON.stringify(getResult.resultXdr)})` : '';
+    const resultXdr = 'resultXdr' in getResult ? getResult.resultXdr : undefined;
+    const resultCode = extractTxResultCode(resultXdr);
+    const detail = resultXdr ? safeStringify(resultXdr) : '';
+    const failDetail = detail ? ` (${detail})` : '';
     const msg = `Transaction failed: ${getResult.status}${failDetail}`;
     core_1.Logger.log.error('submitStellarTransaction', msg, {
         hash: sendResult.hash,
         network,
+        resultCode,
     });
     throw new core_1.AugustSDKError('UNKNOWN', msg, {
-        context: { hash: sendResult.hash, network, status: getResult.status },
+        context: {
+            hash: sendResult.hash,
+            network,
+            status: getResult.status,
+            resultCode,
+        },
     });
 }
 //# sourceMappingURL=submit.js.map

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

@@ -1,4 +1,4 @@
-import { IEmberVault, IFetchEmberVaultsOptions } from './types';
+import type { IEmberVault, IFetchEmberVaultsOptions } from './types';
 /**
  * Fetch Ember vaults from API
  */

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

@@ -7,7 +7,7 @@ import * as SuiConstants from './constants';
 import * as SuiGetters from './getters';
 import * as SuiUtils from './utils';
 import { transformEmberVaultToIVault, transformEmberVaultsToIVaults } from './transformer';
-import { IEmberVault, IFetchEmberVaultsOptions } from './types';
+import type { IEmberVault, IFetchEmberVaultsOptions } from './types';
 export declare const Sui: {
     utils: typeof SuiUtils;
     constants: typeof SuiConstants;

package/lib/adapters/sui/index.js

@@ -60,6 +60,8 @@ exports.Sui = {
  * ```
  */
 class SuiAdapter {
+    _apiBaseUrl;
+    _chainId;
     constructor(apiBaseUrl = SuiConstants.EMBER_API_BASE_URL, chainId = SuiConstants.SUI_CHAIN_ID) {
         this._apiBaseUrl = apiBaseUrl;
         this._chainId = chainId;

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

@@ -1,5 +1,5 @@
-import { IVault } from '../../types';
-import { IEmberVault } from './types';
+import type { IVault } from '../../types';
+import type { IEmberVault } from './types';
 /**
  * Transform Ember vault to IVault format
  */

package/lib/adapters/sui/transformer.js

@@ -59,6 +59,7 @@ function transformEmberVaultToIVault(emberVault) {
             multiplier: 0,
             multipliers: [],
             additionalPoints: [],
+            additionalPointsDetailed: [],
         },
         version: constants_1.EMBER_DEFAULTS.VERSION,
         description: emberVault.description || '',

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

@@ -1,4 +1,4 @@
-import { IHIstoricalSnapshot } from '../../types';
+import type { IHIstoricalSnapshot } from '../../types';
 export interface IEmberVault {
     address: string;
     id: string;

package/lib/core/analytics/sentry-runtime.js

@@ -13,7 +13,7 @@ function detectRuntime() {
             return 'browser';
         }
         if (typeof process !== 'undefined' &&
-            !!process.versions?.node &&
+            process.versions?.node &&
             typeof window === 'undefined') {
             return 'node';
         }

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

@@ -1,6 +1,6 @@
 import type * as Sentry from '@sentry/browser';
-import { IEnv } from '../../types';
-import { IAnalyticsConfig } from './types';
+import type { IEnv } from '../../types';
+import type { IAnalyticsConfig } from './types';
 /**
  * Initialize Sentry with SDK-specific configuration. Idempotent: re-calls
  * only refresh user identity and the cached API-key hash.

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

@@ -1,4 +1,4 @@
-import { IEnv } from '../../types';
+import type { IEnv } from '../../types';
 /**
  * Configuration for SDK analytics/telemetry.
  * Analytics are enabled by default (opt-out model).

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

@@ -1,5 +1,5 @@
-import { IEnv } from '../../types';
-import { IUserIdentity } from './types';
+import type { IEnv } from '../../types';
+import type { IUserIdentity } from './types';
 /**
  * Mask an API key, keeping only the last 5 characters visible.
  * Example: "abcdefghij12345" -> "**********12345"

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

@@ -95,7 +95,7 @@ function generateFingerprint() {
  * @returns User identity object
  */
 function createUserIdentity(apiKey, walletAddress, environment = 'PROD') {
-    let domain = undefined;
+    let domain;
     try {
         if (typeof window !== 'undefined' && window.location) {
             domain = window.location.hostname;

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.5.0";
+export declare const SDK_VERSION = "8.6.0";

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.5.0';
+exports.SDK_VERSION = '8.6.0';
 //# sourceMappingURL=version.js.map

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

@@ -1,6 +1,6 @@
-import { ISolanaConfig, IAddress, IChainId, IEnv, IProvidersConfig, IWSMonitorHeaders } from '../types';
-import { IAnalyticsConfig } from './analytics';
-import { IVersionCheckConfig } from './version-check';
+import type { ISolanaConfig, IAddress, IChainId, IEnv, IProvidersConfig, IWSMonitorHeaders } from '../types';
+import { type IAnalyticsConfig } from './analytics';
+import { type IVersionCheckConfig } from './version-check';
 interface IKeys {
     august?: string;
     graph?: string;

package/lib/core/base.class.js

@@ -38,6 +38,16 @@ function validateAppName(value) {
  * network switching, and authentication state.
  */
 class AugustBase {
+    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.
@@ -46,10 +56,6 @@ class AugustBase {
      *   length range — see {@link IAugustBase.appName}.
      */
     constructor({ appName, providers = {}, keys, monitoring, analytics, versionCheck, timeoutMs, }) {
-        this.monitoring = {
-            'x-user-id': undefined,
-            'x-environment': undefined,
-        };
         // Validate first so the failure mode is a clear, actionable error before
         // any provider / analytics side effects run.
         this.appName = validateAppName(appName);

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

@@ -4,7 +4,7 @@
  * This file contains configurations for vaults that support deposits with alternative tokens
  * through wrapper contracts, swap adapters, or native token deposits.
  */
-import { IVaultAdapterConfig, IAddress } from '../../types';
+import type { IVaultAdapterConfig, IAddress } from '../../types';
 /**
  * Pool/Vault names for adapter routing
  */

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

@@ -70,6 +70,8 @@ export declare const WEBSERVER_ENDPOINTS: {
             summary: (vaultAddress: IAddress) => string;
             withdrawals: (chain: string, vaultAddress: IAddress) => string;
             debank: (vaultAddress: IAddress) => string;
+            userHistory: (vaultAddress: IAddress, wallet: IAddress) => string;
+            archivedVaults: string;
         };
         points: {
             byUserAddress: (userAddress: IAddress) => string;

package/lib/core/constants/core.js

@@ -73,6 +73,12 @@ exports.WEBSERVER_ENDPOINTS = {
             summary: (vaultAddress) => `/tokenized_vault/vault_summary/${(0, ethers_1.getAddress)(vaultAddress)}`,
             withdrawals: (chain, vaultAddress) => `/withdrawals/${chain}/${(0, ethers_1.getAddress)(vaultAddress)}`,
             debank: (vaultAddress) => `/tokenized_vault/${(0, ethers_1.getAddress)(vaultAddress)}/debank`,
+            // Mongo-backed deposit/withdraw history for archived vaults whose
+            // subgraph has been (or will be) retired. See fetchArchivedVaults.
+            userHistory: (vaultAddress, wallet) => `/upshift/vault_history/${(0, ethers_1.getAddress)(vaultAddress)}?wallet=${(0, ethers_1.getAddress)(wallet)}`,
+            // Vaults whose history is served from the snapshot (source of truth for
+            // routing — a vault appears only after its backfill completes).
+            archivedVaults: '/upshift/vault_history/archived',
         },
         points: {
             byUserAddress: (userAddress) => `/upshift/points/${(0, ethers_1.getAddress)(userAddress)}`,

package/lib/core/constants/swap-router.d.ts

@@ -1,4 +1,4 @@
-import { IAddress } from '../../types';
+import type { IAddress } from '../../types';
 /**
  * Address of the `SwapRouter` periphery contract on each supported chain.
  *
@@ -52,3 +52,39 @@ export declare const SWAP_ROUTER_MAX_SWAPS = 9;
  * the contract's `depositNativeToken` / `swapAndDepositNativeToken` accept.
  */
 export declare const SWAP_ROUTER_WRAPPED_NATIVE: Readonly<Record<number, IAddress>>;
+/**
+ * The DEX aggregator whitelisted on each chain's `SwapRouter` via
+ * `enableRouter`, plus the single aggregator contract method every swap leg is
+ * pinned to and that method's 4-byte selector.
+ *
+ * This is the single source of truth tying the off-chain swap-leg builder to
+ * the on-chain router whitelist. The two MUST agree or `swapAndDeposit` reverts
+ * with `InvalidRouter()` (router not whitelisted) or `InvalidNotWhitelisted()`
+ * (selector not authorized). It is consumed in three places:
+ *
+ * - `dispatchViaSwapRouter` asks {@link fetchSwapQuote} to pin the aggregator to
+ *   `contractMethod`, then asserts the returned quote's `router` and payload
+ *   selector match this entry before broadcasting — failing closed rather than
+ *   letting the user pay gas for a transaction the contract will reject.
+ * - The CI check `scripts/verify-swap-router-aggregator.mjs` asserts the
+ *   deployed `SwapRouter` actually has `tokenTransferProxies[router] != 0` and
+ *   `isAuthorizedSelector(router, selector) == true` for every entry here, so
+ *   config drift is caught at release time, not by a user's failed deposit.
+ *
+ * Pinning to one generic method matters: the aggregator otherwise picks a route
+ * method per quote (e.g. a direct `swapExactAmountInOnUniswapV3`) that varies
+ * with market conditions, producing a different selector each time. Pinning
+ * collapses that to one stable selector so the on-chain whitelist needs only
+ * that selector and never drifts as routing changes.
+ *
+ * `router` is the address the aggregator's calldata targets (ParaSwap v6.2
+ * pulls tokens to the Augustus contract itself, so the SwapRouter's
+ * `tokenTransferProxies[router]` is the router address). `selector` is
+ * `bytes4(keccak256("<contractMethod>(...)"))`. Verify both against the
+ * deployed router before adding a chain — a wrong value reverts at deposit time.
+ */
+export declare const SWAP_ROUTER_DEX_AGGREGATOR: Readonly<Record<number, {
+    router: IAddress;
+    contractMethod: string;
+    selector: `0x${string}`;
+}>>;

package/lib/core/constants/swap-router.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SWAP_ROUTER_WRAPPED_NATIVE = exports.SWAP_ROUTER_MAX_SWAPS = exports.ORIGIN_CODES = exports.VAULTS_USING_SWAP_ROUTER = exports.SWAP_ROUTER_ADDRESSES = void 0;
+exports.SWAP_ROUTER_DEX_AGGREGATOR = exports.SWAP_ROUTER_WRAPPED_NATIVE = exports.SWAP_ROUTER_MAX_SWAPS = exports.ORIGIN_CODES = exports.VAULTS_USING_SWAP_ROUTER = exports.SWAP_ROUTER_ADDRESSES = void 0;
 /**
  * Address of the `SwapRouter` periphery contract on each supported chain.
  *
@@ -65,4 +65,44 @@ exports.SWAP_ROUTER_MAX_SWAPS = 9;
 exports.SWAP_ROUTER_WRAPPED_NATIVE = {
     1: '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2',
 };
+/**
+ * The DEX aggregator whitelisted on each chain's `SwapRouter` via
+ * `enableRouter`, plus the single aggregator contract method every swap leg is
+ * pinned to and that method's 4-byte selector.
+ *
+ * This is the single source of truth tying the off-chain swap-leg builder to
+ * the on-chain router whitelist. The two MUST agree or `swapAndDeposit` reverts
+ * with `InvalidRouter()` (router not whitelisted) or `InvalidNotWhitelisted()`
+ * (selector not authorized). It is consumed in three places:
+ *
+ * - `dispatchViaSwapRouter` asks {@link fetchSwapQuote} to pin the aggregator to
+ *   `contractMethod`, then asserts the returned quote's `router` and payload
+ *   selector match this entry before broadcasting — failing closed rather than
+ *   letting the user pay gas for a transaction the contract will reject.
+ * - The CI check `scripts/verify-swap-router-aggregator.mjs` asserts the
+ *   deployed `SwapRouter` actually has `tokenTransferProxies[router] != 0` and
+ *   `isAuthorizedSelector(router, selector) == true` for every entry here, so
+ *   config drift is caught at release time, not by a user's failed deposit.
+ *
+ * Pinning to one generic method matters: the aggregator otherwise picks a route
+ * method per quote (e.g. a direct `swapExactAmountInOnUniswapV3`) that varies
+ * with market conditions, producing a different selector each time. Pinning
+ * collapses that to one stable selector so the on-chain whitelist needs only
+ * that selector and never drifts as routing changes.
+ *
+ * `router` is the address the aggregator's calldata targets (ParaSwap v6.2
+ * pulls tokens to the Augustus contract itself, so the SwapRouter's
+ * `tokenTransferProxies[router]` is the router address). `selector` is
+ * `bytes4(keccak256("<contractMethod>(...)"))`. Verify both against the
+ * deployed router before adding a chain — a wrong value reverts at deposit time.
+ */
+exports.SWAP_ROUTER_DEX_AGGREGATOR = {
+    // ParaSwap AugustusV6.2 (Velora). `swapExactAmountIn` is the generic
+    // executor method; its selector is 0xe3ead59e.
+    1: {
+        router: '0x6A000F20005980200259B80c5102003040001068',
+        contractMethod: 'swapExactAmountIn',
+        selector: '0xe3ead59e',
+    },
+};
 //# sourceMappingURL=swap-router.js.map

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

@@ -1,4 +1,4 @@
-import { IAddress, IPoolFunctions } from '../../types';
+import type { IAddress, IPoolFunctions } from '../../types';
 /**
  * Table of Contents
  * - Hardcoded Addresses

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

@@ -1,4 +1,4 @@
-import { IChainId, IChainObj } from '../../types';
+import type { IChainId, IChainObj } from '../../types';
 export declare const SPECIAL_CHAINS: {
     solana: {
         name: string;

package/lib/core/constants/web3.js

@@ -145,8 +145,5 @@ exports.FALLBACK_RPC_URLS = {
     747474: ['https://rpc.katana.network'],
     4114: ['https://rpc.mainnet.citrea.xyz'],
     25363: ['https://rpc.fluent.xyz'],
-    // [-1]: [
-    //   "https://devnet.helius-rpc.com/?api-key=5f652958-74ed-42e4-a874-0ac8056ac02c"
-    // ]
 };
 //# sourceMappingURL=web3.js.map

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

@@ -15,7 +15,7 @@
  * ```
  */
 /** Stable error codes attached to SDK errors. */
-export type AugustErrorCode = 'AUTH_MISSING_KEY' | 'AUTH_INVALID_KEY' | 'AUTH_FORBIDDEN' | 'AUTH_UNAUTHORIZED' | 'INVALID_URL' | 'INVALID_INPUT' | 'INVALID_CHAIN' | 'INVALID_ADDRESS' | 'NETWORK_ERROR' | 'TIMEOUT' | 'RATE_LIMITED' | 'SERVER_ERROR' | 'UNKNOWN';
+export type AugustErrorCode = 'AUTH_MISSING_KEY' | 'AUTH_INVALID_KEY' | 'AUTH_FORBIDDEN' | 'AUTH_UNAUTHORIZED' | 'INVALID_URL' | 'INVALID_INPUT' | 'INVALID_CHAIN' | 'INVALID_ADDRESS' | 'ACCOUNT_NOT_FUNDED' | 'NETWORK_ERROR' | 'TIMEOUT' | 'RATE_LIMITED' | 'SERVER_ERROR' | 'UNKNOWN';
 /** Options accepted by every SDK error constructor. */
 export interface AugustErrorOptions {
     /** Original error preserved for stack-trace chaining. */
@@ -54,7 +54,7 @@ export declare class AugustTimeoutError extends AugustSDKError {
 }
 /** Caller-side input failed validation. */
 export declare class AugustValidationError extends AugustSDKError {
-    constructor(code: Extract<AugustErrorCode, 'INVALID_URL' | 'INVALID_INPUT' | 'INVALID_CHAIN' | 'INVALID_ADDRESS'>, message: string, options?: AugustErrorOptions);
+    constructor(code: Extract<AugustErrorCode, 'INVALID_URL' | 'INVALID_INPUT' | 'INVALID_CHAIN' | 'INVALID_ADDRESS' | 'ACCOUNT_NOT_FUNDED'>, message: string, options?: AugustErrorOptions);
 }
 /** Backend rate-limited the request (HTTP 429 or equivalent). */
 export declare class AugustRateLimitError extends AugustSDKError {

package/lib/core/errors/index.js

@@ -20,6 +20,9 @@ exports.AugustServerError = exports.AugustRateLimitError = exports.AugustValidat
 exports.isAugustSDKError = isAugustSDKError;
 /** Base class for all SDK errors. */
 class AugustSDKError extends Error {
+    code;
+    correlationId;
+    context;
     constructor(code, message, options = {}) {
         super(message);
         this.name = 'AugustSDKError';
@@ -77,6 +80,8 @@ class AugustNetworkError extends AugustSDKError {
 exports.AugustNetworkError = AugustNetworkError;
 /** Request exceeded its deadline. */
 class AugustTimeoutError extends AugustSDKError {
+    /** Time elapsed (ms) before the request was aborted. */
+    timeoutMs;
     constructor(message, timeoutMs, options) {
         super('TIMEOUT', message, options);
         this.name = 'AugustTimeoutError';
@@ -97,6 +102,8 @@ class AugustValidationError extends AugustSDKError {
 exports.AugustValidationError = AugustValidationError;
 /** Backend rate-limited the request (HTTP 429 or equivalent). */
 class AugustRateLimitError extends AugustSDKError {
+    /** Suggested wait before retrying, in milliseconds. */
+    retryAfterMs;
     constructor(message, options) {
         super('RATE_LIMITED', message, options);
         this.name = 'AugustRateLimitError';
@@ -112,6 +119,8 @@ class AugustRateLimitError extends AugustSDKError {
 exports.AugustRateLimitError = AugustRateLimitError;
 /** Backend returned a non-OK status that isn't auth, rate-limit, or timeout. */
 class AugustServerError extends AugustSDKError {
+    /** HTTP status code returned by the backend. */
+    status;
     constructor(status, message, options) {
         super('SERVER_ERROR', message, options);
         this.name = 'AugustServerError';