augustdigital-sdk 8.20.1

package/lib/core/base.class.js

@@ -0,0 +1,172 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AugustBase = void 0;
+const auth_1 = require("./auth");
+const logger_1 = require("./logger");
+const analytics_1 = require("./analytics");
+const version_check_1 = require("./version-check");
+const fetcher_1 = require("./fetcher");
+const attribution_1 = require("./attribution");
+/**
+ * Validate an appName at SDK construction time.
+ *
+ * Rules (kept intentionally narrow so the value is safe to use as a Sentry
+ * tag, an HTTP header value, and a filesystem-safe identifier — this is
+ * why we accept slugs only, not display names):
+ *  - non-empty after trim
+ *  - 3..64 characters
+ *  - only `[a-zA-Z0-9._-]`
+ *
+ * Throws a descriptive Error that names the failed rule and includes a
+ * remediation hint pointing at the docs link.
+ */
+function validateAppName(value) {
+    const docsHint = 'See https://docs.augustdigital.io/developers/typescript-sdk#app-name';
+    if (typeof value !== 'string' || value.trim().length === 0) {
+        throw new Error(`August SDK: \`appName\` is required. Pass a stable kebab-case slug identifying your application (e.g. "acme-trader"). ${docsHint}`);
+    }
+    const trimmed = value.trim();
+    if (trimmed.length < 3 || trimmed.length > 64) {
+        throw new Error(`August SDK: \`appName\` must be 3-64 characters (got ${trimmed.length}). ${docsHint}`);
+    }
+    if (!/^[a-zA-Z0-9._-]+$/.test(trimmed)) {
+        throw new Error(`August SDK: \`appName\` may only contain letters, digits, '.', '_' and '-' (got "${trimmed}"). Use a slug like "acme-trader", not a display name. ${docsHint}`);
+    }
+    return trimmed;
+}
+/**
+ * Base class providing core SDK functionality including provider management,
+ * 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.
+     *
+     * @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, }) {
+        // Validate first so the failure mode is a clear, actionable error before
+        // any provider / analytics side effects run.
+        this.appName = validateAppName(appName);
+        // TODO: change this to false later when august 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],
+            };
+        }
+        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, monitoring?.['x-user-id'], keys?.august, this.appName);
+        // 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);
+        // 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);
+    }
+    /**
+     * Verify API keys and authorize SDK usage.
+     * TODO: initialize class with appropriate keys and verify august key
+     */
+    async init() {
+        const [augustCheck] = await Promise.all([
+            (0, auth_1.verifyAugustKey)(this.keys?.august),
+        ]);
+        if (!augustCheck)
+            throw new Error('August Digital API key is invalid.');
+        this.authorized = true;
+        logger_1.Logger.log.info('init', 'August Digital 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.AugustBase = AugustBase;
+//# 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

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

@@ -0,0 +1,103 @@
+/**
+ * Adapter Configurations for Vaults
+ *
+ * This file contains configurations for vaults that support deposits with alternative tokens
+ * through wrapper contracts, swap adapters, or native token deposits.
+ */
+import type { IVaultAdapterConfig, IAddress } from '../../types';
+/**
+ * Pool/Vault names for adapter routing
+ */
+export declare const POOL_NAMES: {
+    readonly ETH_TREEHOUSE_GROWTH: "Treehouse Growth";
+    readonly AVAX_AVAX: "AVAX Strategy";
+    readonly ETH_KELP_TAC_RSETH: "Kelp TAC rsETH";
+};
+/**
+ * Adapter ABIs for wrapper contracts
+ */
+export declare const ADAPTER_ABIS: {
+    readonly NATIVE_DEPOSIT_AVAX: readonly [{
+        readonly inputs: readonly [];
+        readonly name: "depositETH";
+        readonly outputs: readonly [];
+        readonly stateMutability: "payable";
+        readonly type: "function";
+    }];
+    readonly NATIVE_DEPOSIT_ETH_WITH_REFERRAL: readonly [{
+        readonly inputs: readonly [{
+            readonly internalType: "address";
+            readonly name: "referralId";
+            readonly type: "address";
+        }];
+        readonly name: "depositETH";
+        readonly outputs: readonly [];
+        readonly stateMutability: "payable";
+        readonly type: "function";
+    }, {
+        readonly inputs: readonly [{
+            readonly internalType: "uint256";
+            readonly name: "amount";
+            readonly type: "uint256";
+        }, {
+            readonly internalType: "address";
+            readonly name: "referralId";
+            readonly type: "address";
+        }];
+        readonly name: "depositWETH";
+        readonly outputs: readonly [];
+        readonly stateMutability: "nonpayable";
+        readonly type: "function";
+    }];
+    readonly KELP_RSETH_ADAPTER: readonly [{
+        readonly inputs: readonly [{
+            readonly internalType: "address";
+            readonly name: "referralId";
+            readonly type: "address";
+        }];
+        readonly name: "getRSETHWithETH";
+        readonly outputs: readonly [];
+        readonly stateMutability: "payable";
+        readonly type: "function";
+    }, {
+        readonly inputs: readonly [{
+            readonly internalType: "address";
+            readonly name: "asset";
+            readonly type: "address";
+        }, {
+            readonly internalType: "uint256";
+            readonly name: "depositAmount";
+            readonly type: "uint256";
+        }, {
+            readonly internalType: "string";
+            readonly name: "referralId";
+            readonly type: "string";
+        }];
+        readonly name: "getRSETHWithERC20";
+        readonly outputs: readonly [];
+        readonly stateMutability: "nonpayable";
+        readonly type: "function";
+    }, {
+        readonly inputs: readonly [{
+            readonly internalType: "address";
+            readonly name: "asset";
+            readonly type: "address";
+        }, {
+            readonly internalType: "uint256";
+            readonly name: "depositAmount";
+            readonly type: "uint256";
+        }];
+        readonly name: "getRsETHAmountToMint";
+        readonly outputs: readonly [{
+            readonly internalType: "uint256";
+            readonly name: "rsETHAmount";
+            readonly type: "uint256";
+        }];
+        readonly stateMutability: "view";
+        readonly type: "function";
+    }];
+};
+/**
+ * Vault adapter configurations mapping vault addresses to their adapter settings
+ */
+export declare const VAULT_ADAPTER_CONFIGS: Record<IAddress, IVaultAdapterConfig>;

package/lib/core/constants/adapters.js

@@ -0,0 +1,180 @@
+"use strict";
+/**
+ * Adapter Configurations for Vaults
+ *
+ * This file contains configurations for vaults that support deposits with alternative tokens
+ * through wrapper contracts, swap adapters, or native token deposits.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VAULT_ADAPTER_CONFIGS = exports.ADAPTER_ABIS = exports.POOL_NAMES = void 0;
+const ethers_1 = require("ethers");
+/**
+ * Pool/Vault names for adapter routing
+ */
+exports.POOL_NAMES = {
+    ETH_TREEHOUSE_GROWTH: 'Treehouse Growth',
+    AVAX_AVAX: 'AVAX Strategy',
+    ETH_KELP_TAC_RSETH: 'Kelp TAC rsETH',
+};
+/**
+ * Adapter ABIs for wrapper contracts
+ */
+exports.ADAPTER_ABIS = {
+    NATIVE_DEPOSIT_AVAX: [
+        {
+            inputs: [],
+            name: 'depositETH',
+            outputs: [],
+            stateMutability: 'payable',
+            type: 'function',
+        },
+    ],
+    NATIVE_DEPOSIT_ETH_WITH_REFERRAL: [
+        {
+            inputs: [
+                { internalType: 'address', name: 'referralId', type: 'address' },
+            ],
+            name: 'depositETH',
+            outputs: [],
+            stateMutability: 'payable',
+            type: 'function',
+        },
+        {
+            inputs: [
+                { internalType: 'uint256', name: 'amount', type: 'uint256' },
+                { internalType: 'address', name: 'referralId', type: 'address' },
+            ],
+            name: 'depositWETH',
+            outputs: [],
+            stateMutability: 'nonpayable',
+            type: 'function',
+        },
+    ],
+    KELP_RSETH_ADAPTER: [
+        {
+            inputs: [
+                { internalType: 'address', name: 'referralId', type: 'address' },
+            ],
+            name: 'getRSETHWithETH',
+            outputs: [],
+            stateMutability: 'payable',
+            type: 'function',
+        },
+        {
+            inputs: [
+                {
+                    internalType: 'address',
+                    name: 'asset',
+                    type: 'address',
+                },
+                {
+                    internalType: 'uint256',
+                    name: 'depositAmount',
+                    type: 'uint256',
+                },
+                {
+                    internalType: 'string',
+                    name: 'referralId',
+                    type: 'string',
+                },
+            ],
+            name: 'getRSETHWithERC20',
+            outputs: [],
+            stateMutability: 'nonpayable',
+            type: 'function',
+        },
+        {
+            inputs: [
+                {
+                    internalType: 'address',
+                    name: 'asset',
+                    type: 'address',
+                },
+                {
+                    internalType: 'uint256',
+                    name: 'depositAmount',
+                    type: 'uint256',
+                },
+            ],
+            name: 'getRsETHAmountToMint',
+            outputs: [
+                {
+                    internalType: 'uint256',
+                    name: 'rsETHAmount',
+                    type: 'uint256',
+                },
+            ],
+            stateMutability: 'view',
+            type: 'function',
+        },
+    ],
+};
+/**
+ * Vault adapter configurations mapping vault addresses to their adapter settings
+ */
+exports.VAULT_ADAPTER_CONFIGS = {
+    // Multi-asset vault with view adapter
+    '0x18EE038C114a07f4B08b420fb1E4149a4F357249': {
+        viewAdapter: '0x72f3cf0d87e9688fad77711d02d86c68334fb275',
+        lpTokenAddress: '0xeF866BfbD0eEc6D6b42C37d8acC0D5fd26828376',
+        isNativeTokenDeposit: false,
+        isWrappedTokenDeposit: false,
+    },
+    // BTC multi-token vault with Paraswap bridge
+    '0x8AcA0841993ef4C87244d519166e767f49362C21': {
+        isNativeTokenDeposit: false,
+        isWrappedTokenDeposit: false,
+        wrappedTokenAddress: '0x2260FAC5E5542a773Aa44fBCfeDf7C193bc2C599',
+        wrapperAddress: '0xfa3f6f36e3D178A538B2B1Fa5f1a5291C901A884',
+        bridgeId: 2,
+        abi: [],
+        tokens: [
+            '0x2260FAC5E5542a773Aa44fBCfeDf7C193bc2C599', // WBTC
+            '0xcbB7C0000aB88B473b1f5aFd9ef808440eed33Bf', // cbBTC
+            '0x18084fbA666a33d37592fA2633fD49a74DD93a88',
+        ],
+    },
+    // AVAX native deposit vault
+    '0xB2bFb52cfc40584AC4e9e2B36a5B8d6554A56e0b': {
+        isNativeTokenDeposit: true,
+        isWrappedTokenDeposit: false,
+        wrappedTokenAddress: '0xB31f66AA3C1e785363F0875A1B74E27b85FD66c7',
+        wrapperAddress: '0xb2C57614B93c41A7Ec3B91980C0Bb7453904c6e8',
+        abi: exports.ADAPTER_ABIS.NATIVE_DEPOSIT_AVAX,
+        tokens: [
+            '0xB31f66AA3C1e785363F0875A1B74E27b85FD66c7', // WAVAX
+            ethers_1.ZeroAddress,
+        ],
+    },
+    // ETH Treehouse Growth - native deposit with referral
+    '0x5Fde59415625401278c4d41C6beFCe3790eb357f': {
+        isNativeTokenDeposit: true,
+        isWrappedTokenDeposit: true,
+        wrappedTokenAddress: '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2',
+        referralId: '0x849ECeE35EdD45aFA3Bd731531427B5661f57d87',
+        wrapperAddress: '0x6B6b27F08B84c186626D5A64614B5192a8ef71a9',
+        abi: exports.ADAPTER_ABIS.NATIVE_DEPOSIT_ETH_WITH_REFERRAL,
+        tokens: [
+            '0x7f39C581F595B53c5cb19bD0b3f8dA6c935E2Ca0', // wstETH
+            '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2', // WETH
+            ethers_1.ZeroAddress,
+        ],
+    },
+    // Kelp TAC rsETH - native deposit with custom adapter
+    '0x419386E3Ef42368e602720CC458e00c0B28c47A7': {
+        isNativeTokenDeposit: true,
+        isWrappedTokenDeposit: true,
+        wrappedTokenAddress: '0xae7ab96520DE3A18E5e111B5EaAb095312D7fE84',
+        referralId: '',
+        wrapperAddress: '0xa7f3a4d8395d62DF12bf35Afb4ab8db42F12926F',
+        viewAdapter: '0x036676389e48133B63a802f8635AD39E752D375D',
+        abi: exports.ADAPTER_ABIS.KELP_RSETH_ADAPTER,
+        tokens: [
+            '0xae7ab96520DE3A18E5e111B5EaAb095312D7fE84', // stETH
+            '0xA35b1B31Ce002FBF2058D22F30f95D405200A15b', // ETHx
+            '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2', // WETH
+            ethers_1.ZeroAddress,
+        ],
+    },
+};
+//# sourceMappingURL=adapters.js.map

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

@@ -0,0 +1,133 @@
+/**
+ * August Digital
+ */
+import type { IAddress, VaultAddress } from '../../types';
+/**
+ * Request timeout in milliseconds.
+ * Set to 90 seconds to accommodate slow API responses.
+ */
+export declare const REQUEST_TIMEOUT_MS = 90000;
+export declare const PRICE_SERVER_URL = "https://prices.augustdigital.io";
+export declare const WEBSERVER_URL: {
+    production: string;
+    staging: string;
+    development: string;
+    localhost: string;
+    qa: string;
+    public: string;
+    upshift: string;
+};
+export declare const WEBSERVER_ENDPOINTS: {
+    default: {
+        hello: string;
+        protected: string;
+    };
+    auth: {
+        verify: string;
+        sign: string;
+        login: string;
+        nonce: string;
+        refresh: string;
+    };
+    subaccount: {
+        list: (offset?: number, limit?: number) => string;
+        rewards: (subaccount: IAddress) => string;
+        tokens: (subaccount: IAddress) => string;
+        twap: {
+            create: (subaccount: IAddress) => string;
+            stop: (subaccount: IAddress, id: string) => string;
+            fills: (subaccount: IAddress, id: string) => string;
+        };
+        debank: (subaccount: IAddress) => string;
+        health_factor: (subaccount: IAddress) => string;
+        summary: (subaccount: IAddress) => string;
+        batch: (subaccount: IAddress) => string;
+        loans: (subaccount: IAddress, side?: "BORROWER" | "LENDER" | "BOTH", active?: boolean) => string;
+        cefi: (subaccount: IAddress) => string;
+        otc_positions: (subaccount: IAddress) => string;
+        loanByAddress: (loanAddress: string, chainId: number) => string;
+        _: (subaccount: IAddress) => string;
+    };
+    transactions: {
+        v2: (subaccount: string, startTime?: string, endTime?: string) => string;
+    };
+    otc: {
+        positions: string;
+        marginRequirements: (otcCounterpartyId?: string, payer?: string) => string;
+    };
+    curator: {
+        vaultSubaccounts: (vaultAddress: string) => string;
+        vaultWhitelist: (vaultAddress: string) => string;
+    };
+    timelockRequests: (vaultAddress: string, chainId: number, status?: string) => string;
+    users: {
+        get: string;
+    };
+    dashboard: {
+        loans: string;
+    };
+    risk: {
+        discountFactors: string;
+        collateralExcessOrDeficit: (subaccount: string, tokenAddress: string, tokenChain: number, targetHealthFactor?: number) => string;
+        collateralSimulation: string;
+    };
+    prices: (symbol: string) => string;
+    metrics: {
+        pnl: (subaccount: IAddress, startTime?: string, endTime?: string) => string;
+        vaultPerformanceFees: (params: {
+            vaultAddress: string;
+            annualizedFeesPct: number;
+            nativeDenominated: boolean;
+            calculationPeriod: string;
+            startDate?: string;
+            endDate?: string;
+        }) => string;
+    };
+    public: {
+        integrations: {
+            morpho: {
+                apy: (subaccount: IAddress, vaultAddress: IAddress) => string;
+            };
+        };
+        tokenizedVault: {
+            loans: (vaultAddress: VaultAddress, chainId: number, active: boolean) => string;
+            subaccountLoans: (vaultAddress: VaultAddress, chainId: number, active: boolean) => string;
+            list: string;
+            byVaultAddress: (vaultAddress: VaultAddress) => string;
+            historicalApy: (vaultAddress: IAddress) => string;
+            historicalTimeseries: (vaultAddress: IAddress, nDays?: number) => string;
+            annualizedApy: (vaultAddress: IAddress) => string;
+            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;
+            register: string;
+            leaderboard: string;
+        };
+        vaults: {
+            pendingRedemptions: (vaultAddress: IAddress) => string;
+        };
+        pnl: {
+            unrealizedHistory: (vaultAddress: VaultAddress, limit?: number) => string;
+            unrealizedLatest: string;
+        };
+        revertReason: (txHash: string, chain: number) => string;
+        oracleClassification: (vaultAddress: string, chainId: number) => string;
+    };
+    upshift: {
+        vaults: {
+            metadata: string;
+        };
+    };
+};
+export declare const DEFAULT_FETCH_OPTIONS: {
+    readonly method: "GET";
+    readonly headers: {
+        readonly Accept: "application/json";
+        readonly 'Content-Type': "application/json";
+    };
+};