Types Reference

The verbatim public types of @arkonix.xyz/arkonix-vault-sdk v2.3.0. The inline comments carry semantics — read them as part of the contract.

Core

type TxState = 'idle' | 'approving' | 'pending' | 'confirming' | 'success' | 'error';

// 'ASYNC': requestDeposit + requestRedeem are both async.
// 'SYNC_DEPOSIT_ASYNC_REDEEM': deposit is synchronous (ERC-4626), redeem is async.
type VaultType = 'ASYNC' | 'SYNC_DEPOSIT_ASYNC_REDEEM';

interface TransactionRequest {
  to: Address;
  data: `0x${string}`;
  value: bigint;
}

interface VaultMetadata {
  asset: Address;           // deposit asset address (e.g. USDC)
  share: Address;           // share token address
  assetDecimals: number;    // e.g. 6 for USDC (18 on BSC!)
  shareDecimals: number;    // e.g. 18
  assetSymbol: string;
  shareSymbol: string;
  poolId: bigint;
  vaultKind: number;        // on-chain: 0 → ASYNC, otherwise SYNC_DEPOSIT_ASYNC_REDEEM
  vaultType: VaultType;
  totalAssets: bigint;      // on-chain TVL in asset units
}

interface VaultUserState {
  isLoading: boolean;

  // Position
  shareBalance: bigint;
  positionValueFormatted: string;        // share balance valued in assets, formatted

  // Deposit flow (ASYNC vaults only)
  hasPendingDeposit: boolean;
  pendingDepositAssets: bigint;
  pendingDepositFormatted: string;
  hasClaimableDeposit: boolean;
  claimableDepositAssets: bigint;
  claimableDepositFormatted: string;

  // Redeem flow (both vault types)
  hasPendingRedeem: boolean;
  pendingRedeemShares: bigint;
  pendingRedeemAssetsFormatted: string;   // estimated at current price
  hasClaimableRedeem: boolean;
  claimableRedeemShares: bigint;
  claimableRedeemAssetsFormatted: string; // locked at epoch price (via maxWithdraw)

  // Cancel redeem
  hasPendingCancelRedeem: boolean;
  claimableCancelRedeemShares: bigint;
  hasClaimableCancelRedeem: boolean;

  // Cancel deposit (ASYNC vaults only)
  hasPendingCancelDeposit: boolean;
  claimableCancelDepositAssets: bigint;
  claimableCancelDepositFormatted: string;
  hasClaimableCancelDeposit: boolean;
}

All *Formatted strings are formatUnits(value, depositAssetDecimals) — asset-denominated.

Financial data (Arkonix API)

interface ArkonixAPIConfig { baseUrl: string; timeout?: number; }

interface ArkonixVaultRef { vaultAddress: string; chainId: number; chainName?: string; }

interface VaultFinancials {
  shareClassId: string;          // hex id; keys all share-class-scoped endpoints
  name: string;
  symbol: string;
  shareTokenAddress?: string;
  sharePrice: number | null;     // NAV per share; null until first price update
  tvlUsd: number;                // total value locked (the NAV), USD
  return7d: number | null;       // CUMULATIVE % over window — NOT annualized
  return30d: number | null;
  return90d: number | null;
  returnAllTime: number | null;  // ANNUALIZED since inception (≥30d old), else cumulative
  vaults: ArkonixVaultRef[];     // sibling deployments of the same share class
}

interface ReturnHistoryPoint {
  timestamp: number;                              // unix seconds
  sharePrice: number;
  cumulativeReturnPct: number;                    // vs FIRST point of the window (resets per `days`)
  cumulativeReturnSinceInceptionPct: number | null; // absolute since launch — use for all-time charts
}

interface ReturnHistory {
  shareClassId: string;
  symbol: string | null;
  days: number;
  return7d: number | null;       // same semantics as VaultFinancials
  return30d: number | null;
  return90d: number | null;
  returnAllTime: number | null;
  currentSharePrice: number;     // live; 0 if unset
  points: ReturnHistoryPoint[];  // ~50 points, oldest → newest; [] when no history
}

interface TvlHistoryPoint { timestamp: number; tvlUsd: number; sharePrice: number; totalSupply: number | null; }
interface TvlHistory { shareClassId: string; symbol: string | null; days: number; currentTvlUsd: number; points: TvlHistoryPoint[]; }

interface SharePricePoint { blockNumber: number; timestamp: number | null; sharePrice: number; txHash: string; }
interface SharePriceHistory { vaultAddress: string; chainId: number; currentPrice: number | null; points: SharePricePoint[]; }

interface HistoryQueryParams { days?: number; }  // default 30, range 1..365; window of `points` only

Return-field semantics

null on any return* field means insufficient history — not zero. return7d/30d/90d are cumulative; only returnAllTime is annualized. See Working with Financial Data before rendering these.

Activity, distribution, fees (new in 2.3.0)

// DEPOSIT / WITHDRAWAL are settled (a claim settles as WITHDRAWAL);
// *_REQUEST rows are submitted but not yet settled by the epoch.
type VaultTransactionType = 'DEPOSIT' | 'WITHDRAWAL' | 'DEPOSIT_REQUEST' | 'REDEEM_REQUEST';

interface VaultTransaction {
  type: VaultTransactionType;
  userAddress: string;          // the controller this row belongs to
  amount: number;               // asset amount, human-readable; 0 where not applicable
  shares: number;               // share amount, human-readable; 0 where not applicable
  sharePrice: number;           // NAV per share at the time
  txHash: string | null;        // null for a pending-request row
  blockNumber: number | null;   // null until on-chain
  timestamp: string | null;     // ISO-8601; null if unknown
}

interface VaultTransactions {
  vaultAddress: string;
  totalTransactions: number;    // may exceed transactions.length when paginated
  transactions: VaultTransaction[];  // order NOT guaranteed — sort by timestamp client-side
}

interface VaultTransactionsQueryParams {
  userAddress?: string;                            // scope to one user
  transactionType?: VaultTransactionType | 'ALL';  // default 'ALL'
  limit?: number;
  offset?: number;
}

interface VaultHoldingAsset {
  symbol: string;
  amountHuman: number;   // already decimal-adjusted
  valueUsd: number;
  pctOfTvl: number;      // % of vault total value (42.5 = 42.5%) — backend-computed
}

interface VaultAssetDistribution {
  shareClassId: string;
  symbol: string | null;
  name: string | null;
  totalValueUsd: number;
  assets: VaultHoldingAsset[];
  partial: boolean;          // true when some holdings couldn't be priced/included
  partialReasons: string[];  // human-readable reasons when partial
}

interface ShareClassFeeConfig {
  managementFeeBps: number;    // 100 bps = 1%
  performanceFeeBps: number;
  managementFeePct: string;    // e.g. "1.00"
  performanceFeePct: string;   // e.g. "10.00"
}

interface ShareClassFees {
  shareClassId: string;
  symbol: string | null;
  feeRecipient: string | null;   // null if unset
  isInitialized: boolean;        // false = fee manager not initialized
  config: ShareClassFeeConfig | null; // null when uninitialized — "no fees configured", not zero
}

Centrifuge types

interface CentrifugeAsset { id?: string; name: string; symbol: string; decimals?: number; address?: string; }

interface CentrifugeHoldingEscrow {
  id?: string; poolId: string; tokenId: string; assetId?: string;
  assetAmount: string; assetPrice: string; asset?: CentrifugeAsset;
  createdAt?: string; updatedAt?: string;
}

interface CentrifugeVault {
  id: string;              // vault contract address
  poolId: string; tokenId: string; centrifugeId: string;
  assetAddress: string; isActive: boolean; status?: string;
  blockchain?: { chainId?: number; network?: string };
}

interface HoldingsQueryParams {
  poolId?: string; tokenId?: string; centrifugeId?: string; assetId?: string;
  assetAddress?: string; limit?: number; orderBy?: string; orderDirection?: 'asc' | 'desc';
}

interface VaultsQueryParams {
  poolId?: string; tokenId?: string; centrifugeId?: string; id?: string; // vault address
  isActive?: boolean; assetAddress?: string; limit?: number;
  orderBy?: string; orderDirection?: 'asc' | 'desc';
}

interface CentrifugeAPIConfig { apiUrl?: string; timeout?: number; }

Wallet & context

interface WalletAdapter {
  platform: "web" | "native";
  connect(): Promise<Address>;
  disconnect(): Promise<void>;
  getAddress(): Promise<Address | null>;
  sendTransaction(tx: TransactionRequest): Promise<string>;
  isConnected(): boolean;
}

interface AddTokenParams { address: Address; symbol: string; decimals: number; image?: string; }

interface VaultContextValue {
  config: VaultSDKConfig;
  walletAdapter: WalletAdapter;
  publicClient: PublicClient;
  arkonixAPIClient?: ArkonixAPIClient;
  centrifugeAPIClient?: CentrifugeAPIClient;
}

For VaultSDKConfig and VaultProviderProps, see Configuration. For SendTransactionFn, DepositResult, and TxResult, see the Core Reference.