@augustdigital/sdk 8.24.0 → 8.26.0

package/lib/modules/api/main.js

@@ -1,6 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AugustApi = void 0;
+/**
+ * The August backend API Module — read-only client for public backend
+ * endpoints (transparency dashboard, unrealized PnL) and authenticated
+ * loan-book / risk / OTC reads. Accessible as `sdk.apiModule`.
+ *
+ * @module AugustApi
+ */
 const ethers_1 = require("ethers");
 const fetcher_1 = require("./fetcher");
 const base_class_1 = require("../../core/base.class");
@@ -32,6 +39,71 @@ function assertVaultAddress(vault, method) {
         throw new errors_1.AugustValidationError('INVALID_ADDRESS', `${method}: "${vault}" is not a valid vault address — pass the vault's EVM (0x…), Solana, or Stellar address.`);
     }
 }
+/** Transparency endpoints are EVM-only and require a positive integer chain id. */
+function assertTransparencyArgs(method, vault, chainId) {
+    if (!(0, ethers_1.isAddress)(vault)) {
+        throw new errors_1.AugustValidationError('INVALID_ADDRESS', `${method}: vault must be an EVM address (transparency endpoints are EVM-only), got ${String(vault)}.`);
+    }
+    if (!Number.isInteger(chainId) || chainId <= 0) {
+        throw new errors_1.AugustValidationError('INVALID_CHAIN', `${method}: chainId must be a positive integer EVM chain id, got ${chainId}. Transparency endpoints are EVM-only.`);
+    }
+}
+const ISO_DATE = /^\d{4}-\d{2}-\d{2}$/;
+/** Date-window params are plain `YYYY-MM-DD` strings; anything else is rejected before the request. */
+function assertIsoDate(method, name, value) {
+    if (value !== undefined && !ISO_DATE.test(value)) {
+        throw new errors_1.AugustValidationError('INVALID_INPUT', `${method}: ${name} must be YYYY-MM-DD, got "${value}".`);
+    }
+}
+/**
+ * Cheap contract-drift guard for the chain-scoped transparency responses.
+ * Every one of them (`positions`, `historical_allocations`, `fees`,
+ * `governance/*`) is an object keyed by `vault_address` + `chain_id`; if the
+ * body is not that, the backend contract has changed and partner code must
+ * not receive a silently-malformed object. Leaves are deliberately NOT
+ * validated — full validation of eight nested shapes is not worth the
+ * weight, and the top-level check catches the common drift (envelope
+ * wrapping, error-object-over-200, renamed root).
+ */
+function assertTransparencyEnvelope(data, method) {
+    const valid = data !== null &&
+        typeof data === 'object' &&
+        !Array.isArray(data) &&
+        typeof data.vault_address === 'string' &&
+        typeof data.chain_id === 'number';
+    if (!valid) {
+        throw new errors_1.AugustServerError(200, `${method}: unexpected response shape from the August API — expected an object with vault_address and chain_id. The backend contract may have changed; refresh packages/sdk/api-spec and update the SDK.`);
+    }
+}
+/**
+ * Same guard for the backing-series endpoint, whose body is a bare array of
+ * ratio points (no envelope). Anything else is contract drift.
+ */
+function assertTransparencyArray(data, method) {
+    if (!Array.isArray(data)) {
+        throw new errors_1.AugustServerError(200, `${method}: unexpected response shape from the August API — expected an array of ratio points. The backend contract may have changed; refresh packages/sdk/api-spec and update the SDK.`);
+    }
+}
+/** Runtime mirror of {@link ITransparencyTimelockStatus} (+ `'all'`) — plain-JS callers bypass the type. */
+const TRANSPARENCY_TIMELOCK_STATUSES = [
+    'scheduled',
+    'executed',
+    'cancelled',
+    'all',
+];
+/** Runtime mirror of {@link ITransparencyAuditCategory} — plain-JS callers bypass the type. */
+const TRANSPARENCY_AUDIT_CATEGORIES = [
+    'Strategy',
+    'Role',
+    'Permission',
+    'Attestation',
+];
+/** Rejects a filter value outside its allowlist before any request is made (types only guard TS callers). */
+function assertOneOf(method, name, value, allowed) {
+    if (value !== undefined && !allowed.includes(value)) {
+        throw new errors_1.AugustValidationError('INVALID_INPUT', `${method}: ${name} must be one of ${allowed.map((v) => `'${v}'`).join(', ')}, got "${String(value)}".`);
+    }
+}
 function assertAddressArg(value, label, method) {
     const valid = typeof value === 'string' &&
         value.length > 0 &&
@@ -70,20 +142,15 @@ function assertSnapshotArray(data, method) {
 }
 /**
  * Read-only client for August backend REST endpoints that have no on-chain
- * equivalent — currently the unrealized-PnL series the backend computes
- * from periodic vault snapshots.
- *
- * Every method makes exactly one HTTPS request to the public
- * (unauthenticated) August API and zero RPC calls. Responses are not cached
- * by the SDK: this is time-sensitive PnL state where staleness is worse
- * than request latency.
+ * equivalent: the unrealized-PnL series, the transparency dashboard
+ * (position snapshot, backing series, smoothed APY, allocations, fee config,
+ * governance), plus authenticated loan-book / risk / OTC reads.
  *
- * Accessible as `apiModule` on the SDK instance; the same methods are also
- * exposed directly on the SDK class.
- *
- * A subset of methods (loan book, risk) hit authenticated admin-only backend
- * endpoints and require an admin-scoped August API key on the SDK
- * constructor; each such method documents the requirement.
+ * Every public method makes exactly one HTTPS request to the August API and
+ * zero RPC calls. Responses are not cached by the SDK: this is time-sensitive
+ * state where staleness is worse than a request. Accessible as
+ * `sdk.apiModule`; only the unrealized-PnL methods are also mirrored on the
+ * root `AugustSDK` class.
  */
 class AugustApi extends base_class_1.AugustBase {
     headers = null;
@@ -421,6 +488,365 @@ class AugustApi extends base_class_1.AugustBase {
         }
         return (0, fetcher_1.fetchVaultOracleClassification)(vault, chainId, this.headers ?? undefined);
     }
+    // -------------------------------------------------------------------------
+    // Transparency dashboard
+    //
+    // One method per card/tab of the Upshift per-vault transparency page so a
+    // partner can compose exactly the subset they want (e.g. Performance without
+    // the collateral-ratio card). Every method: public endpoint, no API key, one
+    // HTTPS request, zero RPC, snapshot-backed (hourly-ish; cache ≥60s).
+    // -------------------------------------------------------------------------
+    /**
+     * Fetch the latest position snapshot for a vault, grouped per wallet — the
+     * data behind the transparency Overview tab (strategy breakdown, backing
+     * composition, vault buffer, per-wallet table, headline TVL).
+     *
+     * Public `GET /upshift/positions/{vault_address}`; no API key. One HTTPS
+     * request, no RPC. Snapshots land hourly; every field is from the single
+     * `snapshot_at` instant. Vault buffer = `total_nav − Σ subaccounts[].total_usd`;
+     * `reported_tvl` is the vault-contract-reported total assets from the same snapshot.
+     *
+     * @param params.vault EVM vault address.
+     * @param params.chainId Numeric chain id the vault lives on.
+     * @returns {@link ITransparencyPositions}.
+     * @throws AugustValidationError When arguments fail validation (no request is made).
+     * @throws AugustServerError When the API responds non-2xx (e.g. unknown vault 404, non-EVM vault 422).
+     * @throws AugustServerError (status 200) When the body is not the documented shape — backend contract drift.
+     * @throws AugustRateLimitError When the API responds 429.
+     * @throws AugustTimeoutError When the request exceeds the SDK request timeout.
+     * @example
+     * ```ts
+     * const p = await sdk.apiModule.getVaultPositionSnapshot({ vault: '0x36eDbF0C834591BFdfCaC0Ef9605528c75c406aA', chainId: 143 });
+     * const buffer = p.total_nav - p.subaccounts.reduce((a, s) => a + s.total_usd, 0);
+     * ```
+     */
+    async getVaultPositionSnapshot(params) {
+        const method = 'getVaultPositionSnapshot';
+        assertTransparencyArgs(method, params.vault, params.chainId);
+        const data = await (0, fetcher_1.fetchTransparencyPositions)(params.vault, params.chainId, this.headers ?? undefined);
+        assertTransparencyEnvelope(data, method);
+        return data;
+    }
+    /**
+     * Fetch the backing / supply / collateral-ratio time series behind the
+     * Performance tab's "Backing vs Supply" and "Collateral Ratio" charts, and
+     * the Overview sidebar's 7-day deltas.
+     *
+     * Public `GET /upshift/unrealized_pnl?fields=ratio`; no API key. One HTTPS
+     * request, no RPC. Points are hourly, returned newest-first — sort before
+     * charting. `actual_tvl` = backing (mark-to-market), `tvl_on_vault` = supply
+     * (vault-reported), `adjusted_redeem_ratio` = collateral ratio.
+     *
+     * Unlike the chain-scoped transparency endpoints (positions, fees,
+     * governance…), this one is keyed by vault address only and accepts
+     * non-EVM (Solana / Stellar) vaults — same contract as
+     * {@link AugustApi.getVaultUnrealizedPnlHistory}, which it shares a route with.
+     *
+     * @param params.vault Vault address (EVM, Solana, or Stellar).
+     * @param params.startDate Optional inclusive lower bound, `YYYY-MM-DD`.
+     * @param params.endDate Optional inclusive upper bound, `YYYY-MM-DD`.
+     * @param params.limit Optional max points.
+     * @returns Array of {@link ITransparencyRatioPoint}; empty when no history.
+     * @throws AugustValidationError When arguments fail validation (no request is made).
+     * @throws AugustServerError When the API responds non-2xx (e.g. unknown vault 404, non-EVM vault 422).
+     * @throws AugustServerError (status 200) When the body is not the documented shape — backend contract drift.
+     * @throws AugustRateLimitError When the API responds 429.
+     * @throws AugustTimeoutError When the request exceeds the SDK request timeout.
+     * @example
+     * ```ts
+     * const pts = await sdk.apiModule.getVaultBackingSeries({ vault, startDate: '2026-08-01' });
+     * const ratio = pts.map((p) => p.adjusted_redeem_ratio * 100); // percent
+     * ```
+     */
+    async getVaultBackingSeries(params) {
+        const method = 'getVaultBackingSeries';
+        assertVaultAddress(params.vault, method);
+        assertIsoDate(method, 'startDate', params.startDate);
+        assertIsoDate(method, 'endDate', params.endDate);
+        if (params.limit !== undefined &&
+            (!Number.isInteger(params.limit) ||
+                params.limit < 1 ||
+                params.limit > 1000)) {
+            throw new errors_1.AugustValidationError('INVALID_INPUT', `${method}: limit must be an integer between 1 and 1000, got ${params.limit}.`);
+        }
+        const data = await (0, fetcher_1.fetchTransparencyRatioSeries)(params.vault, params.startDate, params.endDate, params.limit, this.headers ?? undefined);
+        assertTransparencyArray(data, method);
+        return data;
+    }
+    /**
+     * Fetch the smoothed 7-day APY series — the exact series the Upshift app
+     * charts (Overview "APY last 30 days" and Performance "APY Over Time").
+     *
+     * Public `GET /upshift/historical_apy/chart`; no API key. One HTTPS request,
+     * no RPC. The backend marks this route deprecated in its OpenAPI spec but it
+     * remains the series the Upshift app itself charts; this wrapper tracks it.
+     * The backend applies a rolling-median/mean smoothing filter server-side
+     * when `applySmoothing` is true (the app default); computing APY locally from
+     * raw share ratios will NOT match the published figures.
+     *
+     * Unlike the chain-scoped transparency endpoints (positions, fees,
+     * governance…), this one is keyed by vault address only and accepts
+     * non-EVM (Solana / Stellar) vaults.
+     *
+     * @param params.vault Vault address (EVM, Solana, or Stellar).
+     * @param params.daysAgo Window length in days; pass `-1` for the full history since inception. Default 30.
+     * @param params.averagingPeriodDays Rolling window for the annualized return; must be ≥ 2. Default 7 (the app's "7D APY").
+     * @param params.applySmoothing Apply the backend smoothing filter. Default true.
+     * @returns {@link ITransparencyApySeries} — `labels` are `M/D/YYYY`, `values` are decimal fractions (0.0245 = 2.45%). Empty arrays when the vault has no data.
+     * @throws AugustValidationError When arguments fail validation (no request is made).
+     * @throws AugustServerError When the API responds non-2xx (e.g. unknown vault 404, non-EVM vault 422).
+     * @throws AugustServerError (status 200) When the body is not the documented shape — backend contract drift.
+     * @throws AugustRateLimitError When the API responds 429.
+     * @throws AugustTimeoutError When the request exceeds the SDK request timeout.
+     * @example
+     * ```ts
+     * const apy = await sdk.apiModule.getVaultSmoothedApy({ vault, daysAgo: 30 });
+     * console.log(apy.values.at(-1)); // latest 7D APY as a fraction
+     * ```
+     */
+    async getVaultSmoothedApy(params) {
+        const method = 'getVaultSmoothedApy';
+        assertVaultAddress(params.vault, method);
+        const daysAgo = params.daysAgo ?? 30;
+        // `0` is deliberately rejected: the backend happens to treat `days_ago=0`
+        // as "full history" (same as -1) but only -1 is documented, and a caller
+        // passing 0 almost certainly means "today", not "everything". Forcing the
+        // explicit sentinel avoids silently returning the whole series.
+        if (!Number.isInteger(daysAgo) || (daysAgo < 1 && daysAgo !== -1)) {
+            throw new errors_1.AugustValidationError('INVALID_INPUT', `${method}: daysAgo must be a positive integer (≥ 1) or -1 for full history, got ${params.daysAgo}. 0 is not accepted — pass -1 for the full series.`);
+        }
+        const averaging = params.averagingPeriodDays ?? 7;
+        if (!Number.isInteger(averaging) || averaging < 2) {
+            throw new errors_1.AugustValidationError('INVALID_INPUT', `${method}: averagingPeriodDays must be an integer ≥ 2, got ${params.averagingPeriodDays}.`);
+        }
+        const envelope = await (0, fetcher_1.fetchTransparencySmoothedApy)(params.vault, daysAgo, averaging, params.applySmoothing ?? true, this.headers ?? undefined);
+        // The endpoint reports not-found / bad-args IN-BODY over HTTP 200. The
+        // live shape for those is
+        //   { data: { labels: [], values: [] }, average_apy: null, status: 404|400, error: "…" }
+        // i.e. `data` is never null — it passes `shapeOk` below and falls through
+        // to the normal return as an empty series (charts render their empty
+        // state). The `!shapeOk && status 404/400` branch is a defensive mirror
+        // in case the backend ever sends `data: null` with those statuses.
+        // `data: null` with `status: 200` has never been observed; if it shows up
+        // it IS a contract change and must fail loudly rather than hand partners
+        // a bogus empty chart.
+        const data = envelope?.data;
+        const shapeOk = data !== null &&
+            typeof data === 'object' &&
+            Array.isArray(data.labels) &&
+            Array.isArray(data.values);
+        if (!shapeOk) {
+            if (envelope?.status === 404 || envelope?.status === 400) {
+                return { labels: [], values: [], average_apy: null };
+            }
+            throw new errors_1.AugustServerError(200, `${method}: unexpected response shape from the August API — expected { data: { labels, values } }. The backend contract may have changed; refresh packages/sdk/api-spec and update the SDK.`);
+        }
+        return {
+            labels: data.labels,
+            values: data.values,
+            // average_apy sits at the envelope top level, beside `data`.
+            average_apy: envelope?.average_apy ?? null,
+        };
+    }
+    /**
+     * Fetch daily allocation history per protocol — the Performance tab's
+     * "Allocation Over Time" chart.
+     *
+     * Public `GET /upshift/historical_allocations/{vault_address}`; no API key.
+     * One HTTPS request, no RPC.
+     *
+     * @param params.vault EVM vault address.
+     * @param params.chainId Numeric chain id.
+     * @param params.startDate Optional inclusive lower bound, `YYYY-MM-DD`.
+     * @param params.endDate Optional inclusive upper bound, `YYYY-MM-DD`.
+     * @returns {@link ITransparencyHistoricalAllocations}.
+     * @throws AugustValidationError When arguments fail validation (no request is made).
+     * @throws AugustServerError When the API responds non-2xx (e.g. unknown vault 404, non-EVM vault 422).
+     * @throws AugustServerError (status 200) When the body is not the documented shape — backend contract drift.
+     * @throws AugustRateLimitError When the API responds 429.
+     * @throws AugustTimeoutError When the request exceeds the SDK request timeout.
+     * @example
+     * ```ts
+     * const h = await sdk.apiModule.getVaultHistoricalAllocations({ vault, chainId: 143, startDate: '2026-08-01' });
+     * const byDate = Map.groupBy(h.points, (p) => p.date);
+     * ```
+     */
+    async getVaultHistoricalAllocations(params) {
+        const method = 'getVaultHistoricalAllocations';
+        assertTransparencyArgs(method, params.vault, params.chainId);
+        assertIsoDate(method, 'startDate', params.startDate);
+        assertIsoDate(method, 'endDate', params.endDate);
+        const data = await (0, fetcher_1.fetchTransparencyHistoricalAllocations)(params.vault, params.chainId, params.startDate, params.endDate, this.headers ?? undefined);
+        assertTransparencyEnvelope(data, method);
+        return data;
+    }
+    /**
+     * Fetch a vault's fee configuration — the Performance tab's fee card.
+     *
+     * Public `GET /upshift/fees/{vault_address}`; no API key. One HTTPS
+     * request, no RPC. Percent fields are already scaled (`management_fee_pct`
+     * of `1.5` means 1.5%).
+     *
+     * @param params.vault EVM vault address.
+     * @param params.chainId Numeric chain id.
+     * @returns {@link ITransparencyFees}.
+     * @throws AugustValidationError When arguments fail validation (no request is made).
+     * @throws AugustServerError When the API responds non-2xx (e.g. unknown vault 404, non-EVM vault 422).
+     * @throws AugustServerError (status 200) When the body is not the documented shape — backend contract drift.
+     * @throws AugustRateLimitError When the API responds 429.
+     * @throws AugustTimeoutError When the request exceeds the SDK request timeout.
+     * @example
+     * ```ts
+     * const fees = await sdk.apiModule.getVaultFeeConfig({ vault, chainId: 143 });
+     * console.log(`${fees.management_fee_pct}% mgmt / ${fees.performance_fee_pct}% perf`);
+     * ```
+     */
+    async getVaultFeeConfig(params) {
+        const method = 'getVaultFeeConfig';
+        assertTransparencyArgs(method, params.vault, params.chainId);
+        const data = await (0, fetcher_1.fetchTransparencyFees)(params.vault, params.chainId, this.headers ?? undefined);
+        assertTransparencyEnvelope(data, method);
+        return data;
+    }
+    /**
+     * Fetch the vault's privileged addresses (owner / operators) with custody
+     * enrichment — the Governance tab's "Vault Roles" card.
+     *
+     * Public `GET /upshift/governance/{vault_address}/roles`; no API key. One
+     * HTTPS request from the SDK (the backend performs the on-chain reads).
+     * Third-party enrichment failures (Safe / Fordefi) degrade rows and append
+     * to `warnings` rather than failing.
+     *
+     * @param params.vault EVM vault address.
+     * @param params.chainId Numeric chain id.
+     * @returns {@link ITransparencyGovernanceRoles}.
+     * @throws AugustValidationError When arguments fail validation (no request is made).
+     * @throws AugustServerError When the API responds non-2xx (e.g. unknown vault 404, non-EVM vault 422).
+     * @throws AugustServerError (status 200) When the body is not the documented shape — backend contract drift.
+     * @throws AugustRateLimitError When the API responds 429.
+     * @throws AugustTimeoutError When the request exceeds the SDK request timeout.
+     * @example
+     * ```ts
+     * const { roles, warnings } = await sdk.apiModule.getVaultGovernanceRoles({ vault, chainId: 143 });
+     * const owner = roles.find((r) => r.role === 'owner'); // owner?.is_safe → Safe threshold in safe_threshold
+     * ```
+     */
+    async getVaultGovernanceRoles(params) {
+        const method = 'getVaultGovernanceRoles';
+        assertTransparencyArgs(method, params.vault, params.chainId);
+        const data = await (0, fetcher_1.fetchTransparencyGovernanceRoles)(params.vault, params.chainId, this.headers ?? undefined);
+        assertTransparencyEnvelope(data, method);
+        return data;
+    }
+    /**
+     * Fetch the integrations each vault wallet is whitelisted to operate —
+     * the Governance tab's "Vault Permissions" table.
+     *
+     * Public `GET /upshift/governance/{vault_address}/permissions`; no API key.
+     * One HTTPS request, no RPC.
+     *
+     * @param params.vault EVM vault address.
+     * @param params.chainId Numeric chain id.
+     * @returns {@link ITransparencyGovernancePermissions}.
+     * @throws AugustValidationError When arguments fail validation (no request is made).
+     * @throws AugustServerError When the API responds non-2xx (e.g. unknown vault 404, non-EVM vault 422).
+     * @throws AugustServerError (status 200) When the body is not the documented shape — backend contract drift.
+     * @throws AugustRateLimitError When the API responds 429.
+     * @throws AugustTimeoutError When the request exceeds the SDK request timeout.
+     * @example
+     * ```ts
+     * const { permissions } = await sdk.apiModule.getVaultGovernancePermissions({ vault, chainId: 143 });
+     * for (const p of permissions) console.log(p.integration, p.functions.join(','));
+     * ```
+     */
+    async getVaultGovernancePermissions(params) {
+        const method = 'getVaultGovernancePermissions';
+        assertTransparencyArgs(method, params.vault, params.chainId);
+        const data = await (0, fetcher_1.fetchTransparencyGovernancePermissions)(params.vault, params.chainId, this.headers ?? undefined);
+        assertTransparencyEnvelope(data, method);
+        return data;
+    }
+    /**
+     * Fetch the vault's timelock queue — the Governance tab's "Pending
+     * Timelocks" table. Defaults to pending (`scheduled`) requests.
+     *
+     * Public `GET /upshift/governance/{vault_address}/timelocks`; no API key.
+     * `executable_at` is `scheduled_at + TIMELOCK_DURATION()` read live from
+     * the timelock contract; null (plus a warning) when that read failed.
+     * The default filter is pending only — the list is often empty; pass
+     * `status: 'all'` for history. `getTimelockRequests` returns the raw
+     * backend rows; this returns the dashboard view (labels, `executable_at`,
+     * warnings).
+     *
+     * @param params.vault EVM vault address.
+     * @param params.chainId Numeric chain id.
+     * @param params.status Filter: a single {@link ITransparencyTimelockStatus} or `'all'`. Default `'scheduled'`. Any other string is rejected with `AugustValidationError` before a request is made.
+     * @returns {@link ITransparencyTimelocks}.
+     * @throws AugustValidationError When arguments fail validation (no request is made).
+     * @throws AugustServerError When the API responds non-2xx (e.g. unknown vault 404, non-EVM vault 422).
+     * @throws AugustServerError (status 200) When the body is not the documented shape — backend contract drift.
+     * @throws AugustRateLimitError When the API responds 429.
+     * @throws AugustTimeoutError When the request exceeds the SDK request timeout.
+     * @example
+     * ```ts
+     * const { timelocks } = await sdk.apiModule.getVaultGovernanceTimelocks({ vault, chainId: 1 }); // pending only
+     * const ready = timelocks.filter((t) => t.executable_at && Date.parse(`${t.executable_at}Z`) <= Date.now());
+     * ```
+     */
+    async getVaultGovernanceTimelocks(params) {
+        const method = 'getVaultGovernanceTimelocks';
+        assertTransparencyArgs(method, params.vault, params.chainId);
+        assertOneOf(method, 'status', params.status, TRANSPARENCY_TIMELOCK_STATUSES);
+        const data = await (0, fetcher_1.fetchTransparencyGovernanceTimelocks)(params.vault, params.chainId, params.status, this.headers ?? undefined);
+        assertTransparencyEnvelope(data, method);
+        return data;
+    }
+    /**
+     * Fetch one page of the vault's governance audit log, newest first — the
+     * Governance tab's "Audit Log" timeline. Merges live timelock events with
+     * manually recorded entries (attestations, permission changes).
+     *
+     * Public `GET /upshift/governance/{vault_address}/audit_log`; no API key.
+     * Paginate with `before` = the last returned entry's `timestamp` while
+     * `has_more` is true (exclusive cursor; ties at the exact boundary
+     * timestamp are skipped, never duplicated).
+     *
+     * @param params.vault EVM vault address.
+     * @param params.chainId Numeric chain id.
+     * @param params.category Optional {@link ITransparencyAuditCategory} filter. Any other string is rejected with `AugustValidationError` before a request is made.
+     * @param params.before Optional exclusive cursor — pass the previous page's last `entry.timestamp` back verbatim (naive-UTC, no offset).
+     * @param params.limit Page size, 1–200. Backend default 50.
+     * @returns {@link ITransparencyAuditLog}.
+     * @throws AugustValidationError When arguments fail validation (no request is made).
+     * @throws AugustServerError When the API responds non-2xx (e.g. unknown vault 404, non-EVM vault 422).
+     * @throws AugustServerError (status 200) When the body is not the documented shape — backend contract drift.
+     * @throws AugustRateLimitError When the API responds 429.
+     * @throws AugustTimeoutError When the request exceeds the SDK request timeout.
+     * @example
+     * ```ts
+     * // Walk the whole log, newest first.
+     * let before: string | undefined;
+     * do {
+     *   const page = await sdk.apiModule.getVaultGovernanceAuditLog({ vault, chainId: 1, before, limit: 50 });
+     *   for (const e of page.entries) console.log(e.timestamp, e.type, e.summary);
+     *   before = page.has_more ? page.entries.at(-1)?.timestamp : undefined;
+     * } while (before);
+     * ```
+     */
+    async getVaultGovernanceAuditLog(params) {
+        const method = 'getVaultGovernanceAuditLog';
+        assertTransparencyArgs(method, params.vault, params.chainId);
+        assertOneOf(method, 'category', params.category, TRANSPARENCY_AUDIT_CATEGORIES);
+        if (params.limit !== undefined &&
+            (!Number.isInteger(params.limit) ||
+                params.limit < 1 ||
+                params.limit > 200)) {
+            throw new errors_1.AugustValidationError('INVALID_INPUT', `${method}: limit must be an integer between 1 and 200, got ${params.limit}.`);
+        }
+        const data = await (0, fetcher_1.fetchTransparencyGovernanceAuditLog)(params.vault, params.chainId, params.category, params.before, params.limit, this.headers ?? undefined);
+        assertTransparencyEnvelope(data, method);
+        return data;
+    }
     /**
      * Fetch the historical unrealized-PnL series for a vault, newest first,
      * as computed by the August backend from periodic vault snapshots.

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

@@ -1,4 +1,4 @@
-import { type IAddress, type IHistoricalTimeseriesResponse, type INormalizedNumber, type ISubgraphWithdrawProccessed, type IVault, type IVaultAllocations, type IVaultAnnualizedApy, type IVaultAvailableRedemption, type IVaultLoan, type IVaultPosition, type IVaultRedemptionHistoryItem, type IVaultSummary, type IVaultWithdrawals, type IVaultPendingRedemptions, type IActiveStakingPosition, type IVaultHistoricalParams, type IVaultUserLifetimePnl, type IVaultBorrowerHealthFactor, type IVaultPnl, type VaultAddress } from '../../types';
+import { type IAddress, type IHistoricalTimeseriesResponse, type INormalizedNumber, type ITokenizedVault, type ISubgraphWithdrawProccessed, type IVault, type IVaultAllocations, type IVaultAnnualizedApy, type IVaultAvailableRedemption, type IVaultLoan, type IVaultPosition, type IVaultRedemptionHistoryItem, type IVaultSummary, type IVaultWithdrawals, type IVaultPendingRedemptions, type IActiveStakingPosition, type IVaultHistoricalParams, type IVaultUserLifetimePnl, type IVaultBorrowerHealthFactor, type IVaultPnl, type VaultAddress } from '../../types';
 import type { IVaultBaseOptions } from './types';
 /**
  * Vault Data Getters
@@ -23,15 +23,22 @@ import type { IVaultBaseOptions } from './types';
  * @param loans - Include active loan data
  * @param allocations - Include DeFi/CeFi allocation breakdowns
  * @param options - RPC and service configuration
+ * @param tokenizedVault - Optional pre-fetched backend row for `vault`. When a
+ *   caller already holds the row (e.g. `getVaults` fetched the whole list one
+ *   call earlier), passing it skips this function's own
+ *   `GET /tokenized_vault/{address}` — a pure de-duplication of backend
+ *   traffic. The row must have been fetched with the same
+ *   `loadSubaccounts`/`loadSnapshots` flags the caller passes here.
  * @returns Complete vault object with optional enrichments
  */
-export declare function getVault({ vault, loans, allocations, options, loadSubaccounts, loadSnapshots, }: {
+export declare function getVault({ vault, loans, allocations, options, loadSubaccounts, loadSnapshots, tokenizedVault: prefetchedRow, }: {
     vault: IAddress;
     loans?: boolean;
     allocations?: boolean;
     options: IVaultBaseOptions;
     loadSubaccounts?: boolean;
     loadSnapshots?: boolean;
+    tokenizedVault?: ITokenizedVault;
 }): Promise<IVault>;
 /**
  * Vault Loans

package/lib/modules/vaults/getters.js

@@ -112,13 +112,19 @@ const errors_1 = require("../../core/errors");
  * @param loans - Include active loan data
  * @param allocations - Include DeFi/CeFi allocation breakdowns
  * @param options - RPC and service configuration
+ * @param tokenizedVault - Optional pre-fetched backend row for `vault`. When a
+ *   caller already holds the row (e.g. `getVaults` fetched the whole list one
+ *   call earlier), passing it skips this function's own
+ *   `GET /tokenized_vault/{address}` — a pure de-duplication of backend
+ *   traffic. The row must have been fetched with the same
+ *   `loadSubaccounts`/`loadSnapshots` flags the caller passes here.
  * @returns Complete vault object with optional enrichments
  */
-async function getVault({ vault, loans = false, allocations = false, options, loadSubaccounts, loadSnapshots, }) {
+async function getVault({ vault, loans = false, allocations = false, options, loadSubaccounts, loadSnapshots, tokenizedVault: prefetchedRow, }) {
     let returnedVault;
     try {
-        const tokenizedVaultRaw = await (0, core_1.fetchTokenizedVault)(vault, undefined, loadSubaccounts, loadSnapshots);
-        const tokenizedVault = tokenizedVaultRaw?.[0];
+        const tokenizedVault = prefetchedRow ??
+            (await (0, core_1.fetchTokenizedVault)(vault, undefined, loadSubaccounts, loadSnapshots))?.[0];
         const vaultVersion = (0, core_1.getVaultVersionV2)(tokenizedVault);
         switch (vaultVersion) {
             case 'sol-0': {

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

@@ -13,8 +13,8 @@ import { AugustBase, type IAugustBase } from '../../core';
 import SuiAdapter from '../../adapters/sui';
 import { type IContractWriteOptions, type INativeDepositOptions } from './write.actions';
 import type { Signer, Wallet } from 'ethers';
-import type { IVaultBaseOptions, IVaultCustomOptions } from './types';
-export type { IVaultBaseOptions, IVaultCustomOptions } from './types';
+import type { IGetVaultsOptions, IVaultBaseOptions, IVaultCustomOptions } from './types';
+export type { IGetVaultsOptions, IVaultBaseOptions, IVaultCustomOptions, } from './types';
 /**
  * Vault operations class handling multi-chain vault queries and user positions.
  * Supports both EVM and Solana vaults with unified interface.
@@ -64,32 +64,7 @@ export declare class AugustVaults extends AugustBase {
      * @param options Filtering and enrichment configuration
      * @returns Array of vault objects with optional loans/allocations/positions
      */
-    getVaults(options?: {
-        chainIds?: number[];
-        loadSubaccounts?: boolean;
-        loadSnapshots?: boolean;
-        /**
-         * Portfolio mode: include closed vaults in the result.
-         *
-         * By default (`false`) closed vaults are excluded, so marketplace /
-         * discovery callers never receive a `status: 'closed'` vault. When set,
-         * closed vaults are returned regardless of `is_visible` (closed +
-         * invisible vaults bucket as closed), so a consumer joining user
-         * positions can render a position held in a closed vault on the
-         * portfolio page.
-         *
-         * In this mode, loans/allocations enrichment is also skipped for closed
-         * vaults: they have none, and the per-vault enrichment
-         * (`getVault` → `getVaultAllocations`) otherwise re-throws when a closed
-         * vault has no live strategy/debank data or no subaccounts, which would
-         * land the vault in the `failed` bucket and silently drop it before it
-         * reaches the filter. Skipping enrichment lets the vault survive on its
-         * backend metadata + base on-chain read.
-         *
-         * @default false
-         */
-        includeClosed?: boolean;
-    } & IVaultCustomOptions): Promise<import("../../types").IVault[]>;
+    getVaults(options?: IGetVaultsOptions): Promise<import("../../types").IVault[]>;
     /**
      * Calculate total deposited across all tokenized vaults by summing latest_reported_tvl.
      * Uses the /tokenized_vault endpoint which returns latest_reported_tvl in USD.