@upshiftfinance/sdk 0.0.0-stage → 0.1.0

package/lib/types/api.d.ts

@@ -0,0 +1,498 @@
+import type { IAddress } from './web3';
+/**
+ * A whitelisted token as embedded in loan-book records by the backend
+ * `WhitelistedTokenModel` schema. `chain` is the numeric Upshift chain id
+ * (backend `Chain` IntEnum value, e.g. `1` for Ethereum mainnet).
+ */
+export interface IWhitelistedToken {
+    chain: number;
+    name: string;
+    token_type: string;
+    address: IAddress;
+    decimals: number;
+    symbol: string;
+    discount_factor: number;
+    img_url: string | null;
+    price: number | null;
+}
+/**
+ * The amount and due date of a loan's next scheduled payment, as serialized
+ * by the backend `UpcomingPayment` schema. `due_date` is an ISO-8601 datetime
+ * string.
+ */
+export interface ILoanUpcomingPayment {
+    amount: number;
+    due_date: string;
+}
+/**
+ * One loan-book entry from the admin loan-book endpoints (backend
+ * `LoanBookInfo` schema). Amounts are decimal-adjusted floats; monetary
+ * fields are denominated in the loan's principal token. `deployed_date` is an
+ * ISO-8601 datetime string; `state` is the backend `LoanStateStr` value
+ * (e.g. `"ACTIVE"`).
+ */
+export interface ILoanBookInfo {
+    address: IAddress;
+    lender: IAddress;
+    borrower: IAddress;
+    state: string;
+    total_repaid: number;
+    principal_token: IWhitelistedToken;
+    principal_amount: number;
+    interest_amount: number;
+    upcoming_payment: ILoanUpcomingPayment;
+    apr: number;
+    initial_principal_amount: number;
+    deployed_date: string;
+    payment_interval: number;
+    total_interest_payment_fees: number;
+    lender_apr: number;
+}
+/**
+ * A token's discount-factor ladder from `GET /risk/discount_factors`
+ * (backend `DiscountFactorRead` schema). `steps` are ascending notional
+ * thresholds (in the token's smallest unit) and `factors` the corresponding
+ * ascending haircut multipliers in `[0, 1]`; the two arrays are equal length.
+ * `chain` is the numeric Upshift chain id.
+ */
+export interface IDiscountFactorLadder {
+    steps: number[] | null;
+    factors: number[] | null;
+    address: IAddress;
+    chain: number;
+}
+/**
+ * Result of `GET /risk/collateral_excess_or_deficit` (backend
+ * `CollateralExcessOrDeficit` schema). A positive value is excess collateral
+ * that could be withdrawn; a negative value is the shortfall that must be
+ * deposited to reach the target health factor.
+ */
+export interface ICollateralExcessOrDeficit {
+    amount_usd: number;
+    amount_token: number;
+}
+/**
+ * Request body for `POST /risk/collateral_simulation` (backend
+ * `CollateralSimulation` schema). Chain fields are numeric Upshift chain ids.
+ * `collateral_tokens` is a list of `[chain, address]` pairs and
+ * `collateral_token_allocation` the matching per-token weights (normalized
+ * server-side, so relative magnitudes are what matter). When `on_platform`
+ * is `true`, both `loan_redeployed_token_*` fields are required by the
+ * backend.
+ */
+export interface ICollateralSimulationInput {
+    loan_token_chain: number;
+    loan_token_address: IAddress;
+    loan_amount: number;
+    on_platform?: boolean;
+    loan_redeployed_token_chain?: number | null;
+    loan_redeployed_token_address?: IAddress | null;
+    collateral_tokens: [number, IAddress][];
+    collateral_token_allocation: number[];
+    target_health_factor?: number;
+}
+/**
+ * Per-collateral-token breakdown within a collateral simulation (backend
+ * `CollateralDetailsResult` schema). `chain` is the numeric Upshift chain id.
+ */
+export interface ICollateralDetailsResult {
+    chain: number;
+    token_address: IAddress;
+    price: number;
+    allocation: number;
+    collateral_value_from_redeployed_loan_usd: number;
+    collateral_value_usd: number;
+    amount_usd: number;
+    amount_token: number;
+    effective_discount_factor: number;
+    is_top_up: boolean;
+}
+/**
+ * Result of `POST /risk/collateral_simulation` (backend
+ * `CollateralSimulationResults` schema). `collateral_details` is keyed by
+ * `"<symbol>_<chainName>"`.
+ */
+export interface ICollateralSimulationResults {
+    total_debt_usd: number;
+    total_required_collateral_usd: number;
+    total_collateral_value_from_redeployed_loan_usd: number;
+    health_factor: number;
+    collateral_details: Record<string, ICollateralDetailsResult>;
+}
+/**
+ * Result of the public `GET /revert_reason` endpoint (backend `RevertResponse`
+ * schema) — the decoded failure reasons for a reverted transaction, collected
+ * from a `debug_traceTransaction` call tree. All three arrays are empty when
+ * no matching signal was found in the trace.
+ */
+export interface IRevertReason {
+    error_messages: string[];
+    revert_reasons: string[];
+    universal_subaccount_errors: string[];
+}
+/**
+ * One transaction record from `GET /transactions/v2` (backend
+ * `TransactionAPIRead` schema). `chain` is the numeric Upshift chain id;
+ * `value` is decimal-adjusted; `timestamp` is a Unix epoch (seconds).
+ * `from_` mirrors the backend field name (`from` is reserved). Nested
+ * `logs` / `transfers` / `function_signature` / `otc_cashflow` are passed
+ * through as-is. `transaction_name` is the resolved function name (or the raw
+ * selector when unknown).
+ */
+export interface ISubaccountTransaction {
+    id: string;
+    tx_hash: string;
+    chain: number;
+    from_: IAddress;
+    to: IAddress;
+    value: number;
+    block_number: number;
+    timestamp: number;
+    selector: string | null;
+    logs: unknown[];
+    transfers: unknown[];
+    function_signature: Record<string, unknown> | null;
+    otc_cashflow: Record<string, unknown> | null;
+    transaction_name: string | null;
+}
+/**
+ * DeBank positions and tokens for a single account (backend
+ * `DebankAccountData` schema). `positions`, `app_positions`, and `tokens`
+ * are passed through as raw DeBank objects.
+ */
+export interface ISubaccountDebankData {
+    positions: unknown[];
+    app_positions: unknown[];
+    tokens: unknown[];
+}
+/**
+ * Cross-chain DeBank protocol positions for a subaccount and its associated
+ * strategies (backend `SubaccountDebankAccountData` schema). `strategies` is
+ * keyed by strategy address. This endpoint is slow (300-second server-side
+ * cache) as it fans out across every supported chain.
+ */
+export interface ISubaccountDebank {
+    subaccount: ISubaccountDebankData;
+    strategies: Record<string, ISubaccountDebankData>;
+}
+/**
+ * A tracked position from `GET /otc/position` (backend `IPositionRead`
+ * schema). `configs` is a free-form JSON object of position-specific
+ * settings; `category` is the position category (e.g. `"otc"`).
+ */
+export interface IOtcPositionRead {
+    id: string;
+    slug: string;
+    position_class: string | null;
+    configs: Record<string, unknown> | null;
+    category: string | null;
+    position_discount_factor: number | null;
+}
+/**
+ * An OTC margin requirement from `GET /otc/margin_requirement` (backend
+ * `IOTCMarginRequirementRead` schema) — the margin the `payer` must post to
+ * the given counterparty.
+ */
+export interface IOtcMarginRequirement {
+    otc_counter_party_id: string;
+    margin_requirement: number;
+    payer: IAddress;
+}
+/**
+ * On-chain whitelist status of one subaccount linked to a vault, from
+ * `GET /curator/vaults/{vault_address}/whitelist` (backend
+ * `WhitelistStatusResponse` schema). EVM vaults only.
+ */
+export interface ICuratorWhitelistStatus {
+    address: IAddress;
+    is_whitelisted: boolean;
+}
+/**
+ * One timelock request from `GET /timelock-requests` (backend
+ * `ITimelockRequestRead` schema). `chain_id` is the numeric chain id;
+ * `status` is one of `"scheduled" | "executed" | "cancelled"`; `params` is a
+ * free-form JSON object; datetime fields are ISO-8601 strings.
+ */
+export interface ITimelockRequest {
+    id: string;
+    hash: string;
+    vault_address: IAddress;
+    timelock_address: IAddress;
+    chain_id: number;
+    action_id: string;
+    params: Record<string, unknown>;
+    status: string;
+    schedule_tx_hash: string;
+    execute_tx_hash: string | null;
+    cancel_tx_hash: string | null;
+    submitted_by: string | null;
+    scheduled_at: string;
+    resolved_at: string | null;
+    created_at: string | null;
+    updated_at: string | null;
+}
+/**
+ * Performance-fee computation for a vault from
+ * `GET /metrics/vault_performance_fees` (backend `UpshiftVaultPerformanceFees`
+ * schema). High/low water marks are share-price levels; `*_datetime` fields
+ * are ISO-8601 strings. `calculation_period` is `"YearToDate"` /
+ * `"MonthToDate"` (null when a custom date range was supplied).
+ */
+export interface IVaultPerformanceFees {
+    previous_water_mark: number;
+    previous_water_mark_datetime: string;
+    last_water_mark: number;
+    last_water_mark_datetime: string;
+    is_in_drawdown: boolean;
+    asset_symbol: string | null;
+    total_pnl_in_asset: number;
+    total_perf_fees_asset: number;
+    calculation_period: string | null;
+    annualized_fees_pct: number;
+    underlying_asset_vs_native_perf: number | null;
+    native_token_symbol: string | null;
+}
+/**
+ * One row of a vault's NAV-oracle classification table (backend
+ * `OracleClassificationRow` schema) — how a single position/token is priced
+ * and its USD value.
+ */
+export interface IOracleClassificationRow {
+    position: string;
+    type: string;
+    oracle_source: string;
+    usd_value: number;
+}
+/**
+ * A vault's NAV-oracle classification from the public
+ * `GET /upshift/oracle_classification/{vault_address}` endpoint (backend
+ * `OracleClassificationResponse` schema). `warnings` lists tokens that could
+ * not be resolved (`"unresolved:<symbol>"`). `snapshot_at` is an ISO-8601
+ * datetime string.
+ */
+export interface IOracleClassification {
+    vault_address: IAddress;
+    chain_id: number;
+    snapshot_at: string;
+    methodology: string;
+    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/lib/types/api.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=api.js.map

package/lib/types/index.d.ts

@@ -0,0 +1,12 @@
+export type IEnv = 'DEV' | 'PROD';
+export * from './web3';
+export * from './typed-contract';
+export * from './user';
+export * from './webserver';
+export * from './pools';
+export * from './staking';
+export * from './subgraph';
+export * from './vaults';
+export * from './points';
+export * from './sub-accounts';
+export * from './api';

package/lib/types/index.js

@@ -0,0 +1,28 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./web3"), exports);
+__exportStar(require("./typed-contract"), exports);
+__exportStar(require("./user"), exports);
+__exportStar(require("./webserver"), exports);
+__exportStar(require("./pools"), exports);
+__exportStar(require("./staking"), exports);
+__exportStar(require("./subgraph"), exports);
+__exportStar(require("./vaults"), exports);
+__exportStar(require("./points"), exports);
+__exportStar(require("./sub-accounts"), exports);
+__exportStar(require("./api"), exports);
+//# sourceMappingURL=index.js.map

package/lib/types/points.d.ts

@@ -0,0 +1,28 @@
+export interface IUserPoints {
+    totalPoints?: number;
+    referralEarnings?: number;
+    pools?: Record<string, {
+        amountDepositedInUsd?: number;
+        nativeAmountDeposited?: number;
+        totalPoints?: number;
+        hasPendingRewards?: boolean;
+    }>;
+    external?: Record<string, {
+        protocol?: string;
+        externalName?: string;
+        amountDepositedInUsd?: number;
+        nativeAmountDeposited?: number;
+        totalPoints?: number;
+    }>;
+    referrals?: Record<string, {
+        totalPoints?: number;
+        amountDepositedInUsd?: number;
+        nativeAmountDeposited?: number;
+    }>;
+    topVault?: {
+        lifetimeDeposit?: number;
+        address?: string;
+    } | null;
+    streak?: number;
+    rank?: number | null;
+}

package/lib/types/points.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=points.js.map