@augustdigital/sdk 8.15.0 → 8.16.0

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

@@ -19,7 +19,7 @@ export declare const Solana: {
         isSolanaAddress: typeof import("./utils").isSolanaAddress;
         isSolana: (signature: string) => boolean;
         getProgram: ({ provider, idl, programId, network, }: {
-            idl: any;
+            idl?: any;
             programId?: string;
         } & import("./types").ISolanaConnectionOptions) => import("@coral-xyz/anchor").Program<any>;
         getProvider: ({ connection, publicKey, signTransaction, }: {
@@ -83,9 +83,6 @@ export declare const Solana: {
             "mainnet-beta": {
                 vault: string;
             };
-            testnet: {
-                vault: string;
-            };
             localnet: {
                 vault: string;
             };
@@ -128,7 +125,36 @@ declare class SolanaAdapter {
     get connection(): web3.Connection;
     get provider(): AnchorProvider;
     setWalletProvider(_publicKey: PublicKey | string, signTransaction: (<T extends Transaction | web3.VersionedTransaction>(transaction: T) => Promise<T>) | undefined): void;
-    getProgram(programIdl: any): import("@coral-xyz/anchor").Program<any>;
+    /**
+     * Build an Anchor `Program` bound to this adapter's provider and network.
+     *
+     * The program id is resolved as: explicit `programId` → the `address` carried
+     * by a custom `programIdl` → the canonical deployment for this adapter's
+     * network. A copy of the SDK's bundled `vaultIdl` defers to the network
+     * default (its embedded `address` is a build stamp, not network-aware), so
+     * forwarding it on devnet never silently targets the mainnet program.
+     *
+     * @param programIdl - Anchor IDL to bind. Defaults to the SDK's bundled
+     *   `august_vault` IDL. A custom IDL's `address` is honoured when it differs
+     *   from the bundled build stamp.
+     * @param programId - Base58 program id that overrides both the IDL's address
+     *   and the network default. Use this to target a non-canonical deployment.
+     * @returns An Anchor `Program` for the resolved program id. No RPC is made —
+     *   construction is offline.
+     * @throws {@link AugustValidationError} if no program id can be resolved
+     *   because this adapter's network has no canonical deployment (e.g.
+     *   `testnet`) and neither `programId` nor a custom IDL address was supplied.
+     *
+     * @example
+     * ```ts
+     * // canonical program on the adapter's network
+     * const program = sdk.solana.getProgram();
+     *
+     * // a different deployment, same interface
+     * const legacy = sdk.solana.getProgram(vaultIdl, '7B8n9vL51b6ibqRAd1adZsi3x3kxtq5NZaondh22Vkyq');
+     * ```
+     */
+    getProgram(programIdl?: any, programId?: string): import("@coral-xyz/anchor").Program<any>;
     getVaultState(vaultProgramId: PublicKey | string, idl: any, vaultAddress?: PublicKey | string): Promise<{
         vaultState: unknown | null;
         depositMintDecimals: number | null;
@@ -193,6 +219,15 @@ declare class SolanaAdapter {
      * @param redeemShares  `bigint` (raw share units) or `number` (UI amount).
      */
     vaultRedeem(vaultProgramId: PublicKey | string, idl: any, publicKey: PublicKey | string, redeemShares: number | bigint, sendTransaction: (transaction: Transaction | web3.VersionedTransaction, connection: Connection, options?: SendTransactionOptions) => Promise<web3.TransactionSignature>, vaultAddress?: PublicKey | string): Promise<any>;
+    /**
+     * Canonical program id for a program type on this adapter's network.
+     *
+     * @param type - Program to look up. Only `'vault'` (august_vault) exists today.
+     * @returns The base58 program id.
+     * @throws {@link AugustValidationError} if the canonical program is not
+     *   deployed on this adapter's network (e.g. `testnet`). Previously an
+     *   unmapped network threw a bare `TypeError`.
+     */
     getProgramId(type: 'vault'): string;
 }
 export default SolanaAdapter;

package/lib/adapters/solana/index.js

@@ -46,6 +46,7 @@ const web3_js_1 = require("@solana/web3.js");
 const utils_1 = require("./utils");
 const vault_actions_1 = require("./vault.actions");
 const constants_1 = require("./constants");
+const core_1 = require("../../core");
 exports.Solana = {
     utils: utils_1.SolanaUtils,
     constants: SolanaConstants,
@@ -108,11 +109,41 @@ class SolanaAdapter {
             });
         }
     }
-    getProgram(programIdl) {
+    /**
+     * Build an Anchor `Program` bound to this adapter's provider and network.
+     *
+     * The program id is resolved as: explicit `programId` → the `address` carried
+     * by a custom `programIdl` → the canonical deployment for this adapter's
+     * network. A copy of the SDK's bundled `vaultIdl` defers to the network
+     * default (its embedded `address` is a build stamp, not network-aware), so
+     * forwarding it on devnet never silently targets the mainnet program.
+     *
+     * @param programIdl - Anchor IDL to bind. Defaults to the SDK's bundled
+     *   `august_vault` IDL. A custom IDL's `address` is honoured when it differs
+     *   from the bundled build stamp.
+     * @param programId - Base58 program id that overrides both the IDL's address
+     *   and the network default. Use this to target a non-canonical deployment.
+     * @returns An Anchor `Program` for the resolved program id. No RPC is made —
+     *   construction is offline.
+     * @throws {@link AugustValidationError} if no program id can be resolved
+     *   because this adapter's network has no canonical deployment (e.g.
+     *   `testnet`) and neither `programId` nor a custom IDL address was supplied.
+     *
+     * @example
+     * ```ts
+     * // canonical program on the adapter's network
+     * const program = sdk.solana.getProgram();
+     *
+     * // a different deployment, same interface
+     * const legacy = sdk.solana.getProgram(vaultIdl, '7B8n9vL51b6ibqRAd1adZsi3x3kxtq5NZaondh22Vkyq');
+     * ```
+     */
+    getProgram(programIdl, programId) {
         return utils_1.SolanaUtils.getProgram({
             network: this._network,
             provider: this._provider,
             idl: programIdl,
+            programId,
         });
     }
     async getVaultState(vaultProgramId, idl, vaultAddress) {
@@ -238,9 +269,22 @@ class SolanaAdapter {
             sendTransaction,
         });
     }
+    /**
+     * Canonical program id for a program type on this adapter's network.
+     *
+     * @param type - Program to look up. Only `'vault'` (august_vault) exists today.
+     * @returns The base58 program id.
+     * @throws {@link AugustValidationError} if the canonical program is not
+     *   deployed on this adapter's network (e.g. `testnet`). Previously an
+     *   unmapped network threw a bare `TypeError`.
+     */
     getProgramId(type) {
-        const network = this._network;
-        return constants_1.programIds[network][type];
+        const deployment = (0, constants_1.getDeployedProgramIds)(this._network);
+        if (!deployment) {
+            throw new core_1.AugustValidationError('INVALID_INPUT', `No canonical august_vault deployment for Solana network '${this._network}'. ` +
+                `Deployed networks: ${Object.keys(constants_1.programIds).join(', ')}.`);
+        }
+        return deployment[type];
     }
 }
 exports.default = SolanaAdapter;

package/lib/adapters/solana/utils.d.ts

@@ -9,7 +9,7 @@ import { isSolanaAddress } from '../../core/helpers/chain-address';
 export { isSolanaAddress };
 declare function isSolana(signature: string): boolean;
 declare function getProgram({ provider, idl, programId, network, }: {
-    idl: any;
+    idl?: any;
     programId?: string;
 } & ISolanaConnectionOptions): Program<any>;
 declare function getBestRpcEndpoint({ endpoint, network, connection, }: ISolanaConnectionOptions): Promise<"http://127.0.0.1:8899" | `https://${string}`>;
@@ -132,9 +132,6 @@ export declare const SolanaUtils: {
         "mainnet-beta": {
             vault: string;
         };
-        testnet: {
-            vault: string;
-        };
         localnet: {
             vault: string;
         };

package/lib/adapters/solana/utils.js

@@ -39,18 +39,32 @@ function isSolana(signature) {
     return (signature.length >= 80 && signature.length <= 100);
 }
 function getProgram({ provider, idl, programId, network, }) {
-    if (!idl) {
-        return new anchor_1.Program(constants_1.vaultIdl, provider);
+    const baseIdl = idl ?? constants_1.vaultIdl;
+    // Precedence: explicit `programId` → a custom IDL's `address` → the network
+    // default → the bundled IDL's embedded `address`.
+    //
+    // The custom-address check compares by VALUE, not reference. Keying off
+    // `idl === vaultIdl` broke for a structurally-identical-but-not-reference-equal
+    // copy (second bundle instance, or JSON round-tripped), silently retargeting
+    // devnet callers at mainnet. Every copy carries the same build stamp, so it
+    // still defers to the network default — but a genuinely custom IDL is honoured.
+    const suppliedAddress = typeof baseIdl?.address === 'string' && baseIdl.address !== constants_1.vaultIdl.address
+        ? baseIdl.address
+        : undefined;
+    const explicitId = programId ?? suppliedAddress;
+    if (explicitId) {
+        return new anchor_1.Program({ ...baseIdl, address: explicitId }, provider);
     }
-    // If programId is provided, create a modified IDL with the correct address
-    if (programId) {
-        const modifiedIdl = {
-            ...idl,
-            address: programId,
-        };
-        return new anchor_1.Program(modifiedIdl, provider);
+    if (network) {
+        const networkDefault = (0, constants_1.getDeployedProgramIds)(network)?.vault;
+        if (!networkDefault) {
+            throw new core_1.AugustValidationError('INVALID_INPUT', `No canonical august_vault deployment for Solana network '${network}'. ` +
+                `Deployed networks: ${Object.keys(constants_1.programIds).join(', ')}. ` +
+                `Pass an explicit \`programId\` (or an IDL carrying the target \`address\`) to target a program on this network.`);
+        }
+        return new anchor_1.Program({ ...baseIdl, address: networkDefault }, provider);
     }
-    return new anchor_1.Program(idl, provider);
+    return new anchor_1.Program(baseIdl, provider);
 }
 // ============================================================================
 // SOLANA PROVIDERS

package/lib/core/analytics/method-taxonomy.js

@@ -77,6 +77,10 @@ exports.METHOD_CATEGORIES = {
     fetchUserTokenBalance: 'read.solana',
     fetchUserShareBalance: 'read.solana',
     fetchUserShareBalanceRaw: 'read.solana',
+    // Both are offline resolvers (no RPC) — classified so the partner dashboard
+    // sees program-targeting calls instead of dropping them into 'unknown'.
+    getProgram: 'read.solana',
+    getProgramId: 'read.solana',
     // submitTransaction broadcasts a signed Soroban tx — it mutates on-chain
     // state and belongs in the write bucket even though Stellar adapter call
     // shape mirrors the read helpers (returns a hash, takes signed XDR).

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.15.0";
+export declare const SDK_VERSION = "8.16.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.15.0';
+exports.SDK_VERSION = '8.16.0';
 //# sourceMappingURL=version.js.map

package/lib/modules/vaults/utils.d.ts

@@ -1,4 +1,4 @@
-import type { IAddress, IContractRunner, INormalizedNumber, IPoolFunctions, ITokenizedVault, IVault } from '../../types';
+import type { IAddress, IContractRunner, INormalizedNumber, IPoolFunctions, ITokenizedVault, IVault, IVaultFreshness } from '../../types';
 import { ethers } from 'ethers';
 import type { WalletClient } from 'viem';
 /**
@@ -59,6 +59,24 @@ export declare function getYieldLastRealizedOn(provider: IContractRunner, vaultA
  * Shared across all chain adapters (EVM, Solana, Stellar).
  */
 export declare function formatVaultApy(tokenizedVault: ITokenizedVault): IVault['apy'];
+/**
+ * Map the backend `freshness` object onto the camelCased {@link IVaultFreshness}
+ * shape carried on `IVault`. Shared across all chain adapters (EVM, Solana,
+ * Stellar) so every surface reports provenance identically.
+ *
+ * Each of the three stamps is passed through independently: a missing member
+ * becomes `null` and is never defaulted from one of the others. That is the point
+ * of the object — `apy_computed_at` and `share_ratio_snapshot_at` describe two
+ * different pipelines, and collapsing them would erase the very staleness signal
+ * (snapshot newer than APY) the field exists to expose.
+ *
+ * @param tokenizedVault - Backend tokenized-vault payload. `freshness` is absent on
+ *   responses predating the backend change, and may be explicitly null.
+ * @returns The mapped freshness object, or `null` when the backend reported none.
+ *   Values are the backend's RFC 3339 UTC strings verbatim — no reformatting, so
+ *   the trailing `Z` is preserved.
+ */
+export declare function mapVaultFreshness(tokenizedVault: ITokenizedVault | undefined | null): IVaultFreshness | null;
 /**
  * Map strategists from backend subaccounts or hardcoded list.
  * Shared across all chain adapters.

package/lib/modules/vaults/utils.js

@@ -6,6 +6,7 @@ exports.getVaultRewards = getVaultRewards;
 exports.getIdleAssets = getIdleAssets;
 exports.getYieldLastRealizedOn = getYieldLastRealizedOn;
 exports.formatVaultApy = formatVaultApy;
+exports.mapVaultFreshness = mapVaultFreshness;
 exports.mapStrategists = mapStrategists;
 exports.mapComposabilityIntegrations = mapComposabilityIntegrations;
 exports.backendTvlToNormalizedBn = backendTvlToNormalizedBn;
@@ -235,6 +236,33 @@ function formatVaultApy(tokenizedVault) {
         underlyingApy: (reported_apy?.underlying_apy ?? 0) * 100,
     };
 }
+/**
+ * Map the backend `freshness` object onto the camelCased {@link IVaultFreshness}
+ * shape carried on `IVault`. Shared across all chain adapters (EVM, Solana,
+ * Stellar) so every surface reports provenance identically.
+ *
+ * Each of the three stamps is passed through independently: a missing member
+ * becomes `null` and is never defaulted from one of the others. That is the point
+ * of the object — `apy_computed_at` and `share_ratio_snapshot_at` describe two
+ * different pipelines, and collapsing them would erase the very staleness signal
+ * (snapshot newer than APY) the field exists to expose.
+ *
+ * @param tokenizedVault - Backend tokenized-vault payload. `freshness` is absent on
+ *   responses predating the backend change, and may be explicitly null.
+ * @returns The mapped freshness object, or `null` when the backend reported none.
+ *   Values are the backend's RFC 3339 UTC strings verbatim — no reformatting, so
+ *   the trailing `Z` is preserved.
+ */
+function mapVaultFreshness(tokenizedVault) {
+    const freshness = tokenizedVault?.freshness;
+    if (!freshness)
+        return null;
+    return {
+        apyComputedAt: freshness.apy_computed_at ?? null,
+        shareRatioSnapshotAt: freshness.share_ratio_snapshot_at ?? null,
+        cachedAt: freshness.cached_at ?? null,
+    };
+}
 /**
  * Map strategists from backend subaccounts or hardcoded list.
  * Shared across all chain adapters.
@@ -398,6 +426,7 @@ function buildBackendVault(tokenizedVault, overrides) {
         composabilityIntegrations: mapComposabilityIntegrations(tokenizedVault),
         strategists: mapStrategists(tokenizedVault),
         cachedAt: tokenizedVault.cached_at ?? null,
+        freshness: mapVaultFreshness(tokenizedVault),
         dailyPnlPerShare: mapDailyPnlPerShare(tokenizedVault.daily_pnl_per_share),
         enabled_historical_price_horizons: tokenizedVault.enabled_historical_price_horizons || [],
         latest_reported_tvl: tokenizedVault.latest_reported_tvl,
@@ -615,6 +644,7 @@ async function buildFormattedVault(provider, tokenizedVault, contractCalls) {
         defaultApyHorizon: tokenizedVault?.default_apy_horizon ?? null,
         latest_reported_tvl: tokenizedVault?.latest_reported_tvl,
         cachedAt: tokenizedVault?.cached_at ?? null,
+        freshness: mapVaultFreshness(tokenizedVault),
         showCapFilled: tokenizedVault?.show_cap_filled ?? null,
         apyOverride: tokenizedVault?.apy_override ?? null,
     };