@augustdigital/sdk 8.14.0 → 8.16.0

package/lib/types/vaults.d.ts

@@ -154,14 +154,38 @@ export interface IVaultAllocations {
         positions: any[];
     }>;
 }
+/**
+ * A vault's APY breakdown.
+ *
+ * **Unit contract: every rate on this type is a PERCENTAGE, not a decimal
+ * fraction.** `7.95` means 7.95%. The backend reports these as decimal fractions
+ * (`0.0795`); the SDK multiplies by 100 exactly once, uniformly across every rate
+ * field, before returning them. Consumers must therefore divide by 100 at most once
+ * — and must apply the same treatment to `apy`, `liquidApy`, `pointsApy`,
+ * `campaignApy` and `underlyingApy`, because they all arrive in the same unit.
+ *
+ * This is stated explicitly because the convention going undocumented let a
+ * consumer scale a subset of these fields twice, making them contribute 1/100th of
+ * their value to a displayed total (AUGUST-6967). The unit is uniform here by
+ * design; treating some of these fields as decimals and others as percentages is
+ * always a bug on the consumer side.
+ */
 export interface IVaultApy {
+    /** Base vault APY as a percentage (7.95 = 7.95%). */
     apy: number;
+    /** Human-readable note on how the APY is derived; empty or null when unset. */
     explainer: string;
+    /** Liquid-yield component as a percentage. */
     liquidApy: number;
+    /** Points-program APY as a percentage, or null when the vault has no points. */
     pointsApy: number | null;
+    /** Campaign-boost APY as a percentage, or null when no campaign is running. */
     campaignApy: number | null;
+    /** Claimable rewards, in the reward token's own units — not a percentage. */
     rewardsClaimable: number;
+    /** Compounded rewards, in the reward token's own units — not a percentage. */
     rewardsCompounded: number;
+    /** Underlying-asset APY as a percentage (e.g. staking yield on the deposit asset). */
     underlyingApy: number;
 }
 export interface IVaultStrategist {
@@ -188,9 +212,73 @@ export interface IVaultAdapterConfig {
     tokens?: IAddress[];
     bridgeId?: number;
 }
+/**
+ * Provenance timestamps for a vault's server-side data, mapped from the backend
+ * `freshness` object.
+ *
+ * A vault's share price and its APY come from two different pipelines: the SDK
+ * reads share price live from chain (`totalAssets()/totalSupply()`), while APY is a
+ * backend column recomputed on a schedule. These stamps make the remaining gap
+ * visible so a UI can render "data as of X" instead of implying both numbers are
+ * equally current.
+ *
+ * The three fields are **independently nullable and independently meaningful** —
+ * none of them is a fallback for another. In particular, when
+ * `shareRatioSnapshotAt` is later than `apyComputedAt`, a share-price snapshot has
+ * landed that the APY has not yet been recomputed from: that ordering is the
+ * staleness signal.
+ *
+ * Every value is an RFC 3339 UTC string with a trailing `Z`, exactly as the backend
+ * sends it — the SDK does not reformat or reinterpret them. Keep the `Z` if you
+ * pass these anywhere: `new Date('2026-07-25T00:01:46')` (no `Z`) is parsed as
+ * *local* time and silently shifts by the viewer's UTC offset.
+ *
+ * @example
+ * ```ts
+ * const vault = await sdk.vaults.getVault(address);
+ * const { apyComputedAt, shareRatioSnapshotAt } = vault.freshness ?? {};
+ * // Only comparable when BOTH are present.
+ * const apyLagsSharePrice =
+ *   !!apyComputedAt &&
+ *   !!shareRatioSnapshotAt &&
+ *   new Date(shareRatioSnapshotAt) > new Date(apyComputedAt);
+ * ```
+ */
+export interface IVaultFreshness {
+    /**
+     * When the backend last recomputed `historical_apy`, TVL and drawdown for this
+     * vault. Null if never computed.
+     */
+    apyComputedAt: string | null;
+    /**
+     * Timestamp of the newest persisted share-price snapshot the backend holds. Null
+     * only when the vault has no snapshot yet.
+     *
+     * Populated regardless of whether the read loaded snapshots — the backend stamps
+     * it from a scalar `max(snapshot_datetime)`, so it is present even on
+     * `load_snapshots=false` reads (the basic and sub-accounts views). When it is
+     * null, treat it as absent: do not fall back to `apyComputedAt` or `cachedAt` in
+     * its place.
+     */
+    shareRatioSnapshotAt: string | null;
+    /**
+     * When the backend assembled the response body this vault came from, before its
+     * own response cache. Note this does **not** account for the SDK's client-side
+     * LRU (10–15 min on `fetchTokenizedVault` / `fetchTokenizedVaults`), so a vault
+     * served from that cache can be older than this stamp suggests is possible.
+     */
+    cachedAt: string | null;
+}
 export interface IVault {
     max_drawdown?: number | null;
     historical_apy?: Record<number, number> | null;
+    /**
+     * Compound-annualized historical APY keyed by horizon in days (1/7/30), as
+     * decimal fractions. Same shape and per-horizon null semantics as
+     * `historical_apy`. Display is opted in per vault via
+     * `apyOverride.is_show_compound_apy`; absent on older/cached responses.
+     */
+    historical_compound_apy?: Record<number, number> | null;
     /** @deprecated Use getVaultHistoricalTimeseries instead */
     historical_snapshots?: IHIstoricalSnapshot[];
     depositCap?: INormalizedNumber;
@@ -271,6 +359,13 @@ export interface IVault {
     defaultApyHorizon?: 7 | 30 | null;
     latest_reported_tvl?: number | null;
     cachedAt?: string | null;
+    /**
+     * Provenance timestamps for the vault's server-side data — when its APY was last
+     * recomputed, when its newest share-price snapshot was taken, and when the
+     * backend built the response. Null (or a null member) when the backend did not
+     * report that stamp; see {@link IVaultFreshness}.
+     */
+    freshness?: IVaultFreshness | null;
     showCapFilled?: boolean | null;
     /** Controls how the vault's APY is displayed; null when the backend has not set an override. */
     apyOverride?: IApyOverride | null;

package/lib/types/webserver.d.ts

@@ -427,6 +427,9 @@ export interface ITokenizedVaultEoaOperator {
  * Controls how the vault's APY is displayed in the UI.
  * When `is_show_target_apy` is true, the UI should show a target/projected APY.
  * When `is_show_hardcoded_apy` is true, `hardcoded_apy` overrides the computed APY.
+ * When `is_show_compound_apy` is true, the UI should render the
+ * compound-annualized historical APY (`historical_compound_apy`) instead of
+ * the simple one.
  */
 export interface IApyOverride {
     /** Whether to display a target APY rather than historical performance. */
@@ -435,6 +438,54 @@ export interface IApyOverride {
     is_show_hardcoded_apy: boolean;
     /** The fixed APY value to display when `is_show_hardcoded_apy` is true, or null. */
     hardcoded_apy: number | null;
+    /**
+     * Whether to display the compound-annualized historical APY
+     * (`historical_compound_apy`) instead of the simple `historical_apy`.
+     * Absent (older/cached responses) or false means simple. Independent of the
+     * target/hardcoded flags above, which keep their existing precedence.
+     */
+    is_show_compound_apy?: boolean;
+}
+/**
+ * Per-vault provenance timestamps returned by the backend on every tokenized-vault
+ * read (list and single-vault, on both the `api.augustdigital.io/tokenized_vault`
+ * and `api.upshift.finance/tokenized_vaults` surfaces).
+ *
+ * The three stamps describe *different* pipelines and are independently nullable —
+ * one of them cannot stand in for another. Consumers use the ordering between them
+ * to detect that the vault's share price has moved ahead of its APY: a
+ * `share_ratio_snapshot_at` later than `apy_computed_at` means a share-price
+ * snapshot has landed that the APY has not yet been recomputed from.
+ *
+ * All values are RFC 3339 UTC strings with a trailing `Z` (e.g.
+ * `'2026-07-25T00:01:46Z'`). The trailing `Z` matters: `new Date()` parses an
+ * offset-less date-time as *local* time, which would silently shift the stamp by
+ * the viewer's UTC offset.
+ *
+ * @see ITokenizedVault.freshness
+ */
+export interface ITokenizedVaultFreshness {
+    /**
+     * When `historical_apy`, TVL and drawdown were last recomputed, or null if they
+     * have never been computed for this vault.
+     */
+    apy_computed_at: string | null;
+    /**
+     * `snapshot_datetime` of the newest persisted share-price snapshot, or null when
+     * the vault has no snapshot yet.
+     *
+     * The backend stamps this from a scalar `max(snapshot_datetime)`, so it is
+     * populated independently of `load_snapshots` — including on the basic and
+     * sub-accounts views (`load_snapshots=false`), which is what every app call site
+     * sends. Never substitute another timestamp for it.
+     */
+    share_ratio_snapshot_at: string | null;
+    /**
+     * When the backend assembled the response body, before it entered the backend's
+     * own response cache. Distinct from the top-level `cached_at` only in scope:
+     * this one travels with the vault object.
+     */
+    cached_at: string | null;
 }
 export interface ITokenizedVaultStrategist {
     strategist_name: string;
@@ -574,12 +625,24 @@ export interface ITokenizedVault {
     stellar_vault_metadata?: IStellarVaultMetadata | null;
     lagDuration: number;
     historical_apy: Record<number, number> | null;
+    /**
+     * Compound-annualized historical APY keyed by horizon in days (1/7/30), as
+     * decimal fractions (0.0795 = 7.95%). Same shape and per-horizon null
+     * semantics as `historical_apy`. Absent on older/cached responses.
+     */
+    historical_compound_apy?: Record<number, number> | null;
     /** @deprecated Use getVaultHistoricalTimeseries instead */
     historical_snapshots?: IHIstoricalSnapshot[];
     max_drawdown: number | null;
     daily_pnl_per_share: Record<string, number>;
     latest_reported_tvl: number | null;
     cached_at?: string | null;
+    /**
+     * Per-vault provenance timestamps (APY recompute, newest share-price snapshot,
+     * response assembly). Absent on older/cached responses predating the backend
+     * change that added it.
+     */
+    freshness?: ITokenizedVaultFreshness | null;
     instant_redeem_config: null | {
         subaccount_address: string;
         output_asset_symbol: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@augustdigital/sdk",
-  "version": "8.14.0",
+  "version": "8.16.0",
   "main": "lib/index.js",
   "types": "lib/sdk.d.ts",
   "keywords": [
@@ -66,6 +66,7 @@
     "test:jest:watch": "jest --config jest.config.unit.js --watch",
     "test:jest:coverage": "jest --config jest.config.unit.js --coverage",
     "test:forknet": "node tests/forknet/run.mjs",
+    "test:solana-idl": "jest --config jest.config.idl-drift.js",
     "clean": "rm -rf ./lib",
     "format": "biome check --write .",
     "lint-sdk": "lint-staged",