@augustdigital/sdk 8.22.1 → 8.25.0

package/lib/types/api.d.ts

@@ -278,3 +278,221 @@ export interface IOracleClassification {
     rows: IOracleClassificationRow[];
     warnings: string[];
 }
+/**
+ * Strategy bucket the backend assigns to a position group (backend
+ * `StrategyCategory` enum). `Buffer / Idle` is undeployed wallet liquidity;
+ * `CeFi` positions are the only ones not inspectable on-chain.
+ */
+export type ITransparencyStrategyCategory = 'Lending' | 'Yield Trading' | 'Staking / Vaults' | 'CeFi' | 'Buffer / Idle' | 'Unclassified';
+/** Role of a token leg inside a position. Borrow legs carry NEGATIVE `usd_value` and `balance`. */
+export type ITransparencyTokenRole = 'supply' | 'borrow' | 'reward' | 'wallet';
+/** One token leg of a position (backend `TokenExposureView`). */
+export interface ITransparencyTokenExposure {
+    symbol: string;
+    /** Native token units; CeFi derivatives carry signed contract units. */
+    balance: number;
+    /** USD value; negative for borrow legs. */
+    usd_value: number;
+    role: ITransparencyTokenRole;
+}
+/** One protocol's positions inside a subaccount (backend `IntegrationGroupView`). */
+export interface ITransparencyIntegrationGroup {
+    /** Normalized DeFi slug, CeFi venue name, or `_idle` for undeployed wallet balances. */
+    protocol: string;
+    chain_id: number;
+    strategy_category: ITransparencyStrategyCategory;
+    /** Wallet that physically holds the position. */
+    holding_address: IAddress;
+    tokens: ITransparencyTokenExposure[];
+    total_usd: number;
+    /** Fraction of the subaccount total (0.25 = 25%); can exceed 1.0 slightly by rounding. */
+    pct_of_subaccount: number;
+    /** Minimum health factor across the grouped DeFi positions; null when none reports one. */
+    health_factor?: number | null;
+}
+/** One vault wallet with its positions (backend `SubaccountIntegrationsView`). */
+export interface ITransparencySubaccount {
+    subaccount_address: IAddress;
+    label: string;
+    type: 'subaccount' | 'eoa';
+    total_usd: number;
+    /** Fraction of NAV (0.25 = 25%). */
+    pct_of_nav: number;
+    integrations: ITransparencyIntegrationGroup[];
+}
+/**
+ * Latest position snapshot for a vault, grouped per wallet — the data behind
+ * the Overview tab's strategy breakdown, backing composition, vault buffer and
+ * per-wallet table (backend `VaultPositionsResponse`).
+ *
+ * `total_nav` is the mark-to-market NAV of all positions under the published
+ * pricing methodology; `reported_tvl` is the vault-reported total assets
+ * captured in the SAME snapshot (use it for a headline that matches the vault
+ * contract). The vault's own liquidity buffer is `total_nav − Σ subaccounts[].total_usd`.
+ */
+export interface ITransparencyPositions {
+    vault_address: IAddress;
+    chain_id: number;
+    /** ISO-8601 snapshot timestamp; every field on this response is from this instant. */
+    snapshot_at: string;
+    total_nav: number;
+    reported_tvl?: number | null;
+    subaccounts: ITransparencySubaccount[];
+}
+/** One point of a vault's unrealized-PnL / ratio series (backend `unrealized_pnl` record, `fields=ratio` projection). */
+export interface ITransparencyRatioPoint {
+    timestamp: string;
+    /** Backing ÷ supply; > 1 means over-collateralized. Drives the Collateral Ratio chart. */
+    adjusted_redeem_ratio: number;
+    /** Mark-to-market NAV — the "Backing Assets" series. */
+    actual_tvl: number;
+    /** Vault-reported TVL — the "Supply" series. */
+    tvl_on_vault: number;
+}
+/** One (date, protocol) allocation point (backend `AllocationPoint`). */
+export interface ITransparencyAllocationPoint {
+    /** `YYYY-MM-DD`. */
+    date: string;
+    protocol: string;
+    strategy_category: ITransparencyStrategyCategory;
+    usd_value: number;
+    /** Fraction of TVL (0.25 = 25%). */
+    pct_of_tvl: number;
+}
+/** Daily allocation history for the Performance tab's "Allocation Over Time" chart. */
+export interface ITransparencyHistoricalAllocations {
+    vault_address: IAddress;
+    chain_id: number;
+    /** ISO-8601 timestamp of the earliest snapshot, or null when there is none. */
+    history_from: string | null;
+    points: ITransparencyAllocationPoint[];
+}
+/** Vault fee configuration as shown on the Performance tab (backend `VaultFeesResponse`). `*_pct` fields are already percents (2 = 2%), unlike the `pct_of_*` fractions elsewhere. */
+export interface ITransparencyFees {
+    vault_address: IAddress;
+    chain_id: number;
+    management_fee_bps: number | null;
+    management_fee_pct: number | null;
+    performance_fee_ppm: number | null;
+    performance_fee_pct: number | null;
+    weekly_performance_fee_bps: number | null;
+    management_fee_waived_until_date: string | null;
+    management_fee_waived_until_tvl: number | null;
+    performance_fee_waived_until_date: string | null;
+    performance_fee_waived_until_tvl: number | null;
+    warnings: string[];
+}
+/** Smoothed 7D-APY series (backend `historical_apy/chart`); labels are `M/D/YYYY`, values are decimal fractions (0.0245 = 2.45%). */
+export interface ITransparencyApySeries {
+    labels: string[];
+    values: number[];
+    average_apy?: number | null;
+}
+/** Public-safe summary of one Fordefi transaction-policy rule. */
+export interface ITransparencyFordefiPolicyRule {
+    name: string;
+    transaction_types: string[];
+    recipients: string[];
+    assets: string[];
+    action: string | null;
+}
+/** One privileged address on the vault with custody enrichment (backend `VaultRoleView`). */
+export interface ITransparencyGovernanceRole {
+    role: 'owner' | 'operator';
+    address: IAddress;
+    chain_id: number;
+    is_safe: boolean;
+    safe_threshold: number | null;
+    safe_owners: IAddress[] | null;
+    safe_nonce: number | null;
+    has_fordefi_policy: boolean;
+    /** Governed by the Upshift operator-policy engine (whitelisted integrations). */
+    has_august_policy: boolean;
+    /** null = unknown/uncovered — distinct from an explicit 0. */
+    fordefi_policy_count: number | null;
+    fordefi_policies: ITransparencyFordefiPolicyRule[] | null;
+    safe_ui_url: string | null;
+}
+/** Governance tab → "Vault Roles" card (backend `VaultRolesResponse`). `warnings` lists enrichment failures (Safe / Fordefi lookups) that degraded rows rather than failing the call. */
+export interface ITransparencyGovernanceRoles {
+    vault_address: IAddress;
+    chain_id: number;
+    snapshot_at: string;
+    roles: ITransparencyGovernanceRole[];
+    warnings: string[];
+}
+/** One integration the vault's wallets may operate, with unioned scopes (backend `VaultPermissionView`). */
+export interface ITransparencyGovernancePermission {
+    integration: string;
+    protocol: string | null;
+    /** null for chainless CeFi venue integrations. */
+    chain_id: number | null;
+    tokens: string[];
+    functions: string[];
+    spenders: IAddress[];
+    wallets: IAddress[];
+    fordefi_policy_match: boolean;
+    fordefi_policies: ITransparencyFordefiPolicyRule[] | null;
+}
+/** One Fordefi transaction-policy rule attributed to the vault, with the vault wallets it targets. */
+export interface ITransparencyVaultFordefiPolicy extends ITransparencyFordefiPolicyRule {
+    wallets: IAddress[];
+}
+/** Governance tab → "Vault Permissions" table (backend `VaultPermissionsResponse`). */
+export interface ITransparencyGovernancePermissions {
+    vault_address: IAddress;
+    chain_id: number;
+    permissions: ITransparencyGovernancePermission[];
+    /** null = no policy workspace could answer (unknown, not empty). */
+    fordefi_policies: ITransparencyVaultFordefiPolicy[] | null;
+    warnings: string[];
+}
+/** Lifecycle of a timelock request (backend `TimelockStatus` enum). */
+export type ITransparencyTimelockStatus = 'scheduled' | 'executed' | 'cancelled';
+/** One request in the vault timelock (backend `VaultTimelockView`). */
+export interface ITransparencyTimelock {
+    action_id: string;
+    action_label: string;
+    target_label: string;
+    params: Record<string, unknown>;
+    status: ITransparencyTimelockStatus;
+    proposer: string | null;
+    /** Naive-UTC ISO timestamp. */
+    scheduled_at: string;
+    /** null when the timelock duration could not be read on-chain (see `warnings`). */
+    executable_at: string | null;
+    schedule_tx_hash: string;
+    execute_tx_hash: string | null;
+    cancel_tx_hash: string | null;
+    timelock_address: IAddress;
+}
+/** Governance tab → "Pending Timelocks" table (backend `VaultTimelocksResponse`). */
+export interface ITransparencyTimelocks {
+    vault_address: IAddress;
+    chain_id: number;
+    timelocks: ITransparencyTimelock[];
+    warnings: string[];
+}
+/** Category pill of an audit-log entry (backend `AuditLogCategory` enum). */
+export type ITransparencyAuditCategory = 'Strategy' | 'Role' | 'Permission' | 'Attestation';
+/** One row of the governance audit log (backend `AuditLogEntryView`). `tx_hash` is set only for on-chain-backed events. */
+export interface ITransparencyAuditLogEntry {
+    /** Naive-UTC ISO timestamp (no offset) — pass back verbatim as the `before` cursor. */
+    timestamp: string;
+    type: ITransparencyAuditCategory;
+    summary: string;
+    actor: string | null;
+    vault_address: IAddress;
+    tx_hash: string | null;
+}
+/**
+ * One page of the governance audit log, newest first. Paginate with
+ * `before` = the last entry's `timestamp` while `has_more` is true.
+ */
+export interface ITransparencyAuditLog {
+    vault_address: IAddress;
+    chain_id: number;
+    entries: ITransparencyAuditLogEntry[];
+    has_more: boolean;
+    warnings: string[];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@augustdigital/sdk",
-  "version": "8.22.1",
+  "version": "8.25.0",
   "main": "lib/index.js",
   "types": "lib/sdk.d.ts",
   "keywords": [