@paxoslabs/earn-sdk
Version:
Paxos Labs Earn SDK
226 lines (222 loc) • 6.56 kB
text/typescript
import { Address } from 'viem';
/**
* Type definitions for Earn SDK API integration
*
* These types define the data structures returned by the Earn SDK backend API
* and internal cache structures used by the SDK.
*
* @module types/earn-sdk-api
*/
/**
* Yield strategy type for a vault
*/
type YieldType = "PRIME" | "TBILL" | "LENDING";
/**
* Nucleus smart contract configuration for a vault
*
* Contains all contract addresses required for vault operations:
* - boringVaultAddressId: Main vault contract
* - tellerAddressId: Handles deposits and withdrawals
* - accountantAddressId: Manages accounting logic
* - managerAddressId: Controls strategy execution
* - rolesAuthorityAddressId: Enforces role-based access
* - baseTokenAddressId: Deposit token address (correlation key with SupportedAsset)
* - baseTokenStandInId: Optional stand-in token
* - communityCodeDepositorAddressId: Optional community depositor contract
*/
interface NucleusContracts {
boringVaultAddressId: Address;
tellerAddressId: Address;
accountantAddressId: Address;
managerAddressId: Address;
rolesAuthorityAddressId: Address;
baseTokenAddressId: Address;
baseTokenStandInId?: Address;
communityCodeDepositorAddressId?: Address;
}
/**
* Earn vault configuration
*
* Represents a single vault with contract addresses, yield type, and deposit token.
* Multiple vaults can share the same baseTokenAddressId (different chains/yield types).
*
* @example
* ```typescript
* const vault: EarnVault = {
* id: "config-eth-prime-001",
* chainId: 1,
* yieldType: "PRIME",
* Nucleus: {
* boringVaultAddressId: "0x8a5Fb0Eb3E1a90AF81C5DFF9f2e5D0e7b8D4E5F6",
* tellerAddressId: "0x7B8C9D0E1F2A3B4C5D6E7F8A9B0C1D2E3F4A5B6C",
* accountantAddressId: "0x6A7B8C9D0E1F2A3B4C5D6E7F8A9B0C1D2E3F4A5B",
* managerAddressId: "0x5A6B7C8D9E0F1A2B3C4D5E6F7A8B9C0D1E2F3A4B",
* rolesAuthorityAddressId: "0x4A5B6C7D8E9F0A1B2C3D4E5F6A7B8C9D0E1F2A3B",
* baseTokenAddressId: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
* }
* };
* ```
*/
interface EarnVault {
/** Unique identifier for the vault configuration */
id: string;
/** Chain ID where the vault is deployed (e.g., 1 for Ethereum) */
chainId: number;
/** Token address of supported asset */
depositTokenAddressId: Address;
/** Yield strategy type */
yieldType: YieldType;
/** Nucleus smart contract addresses */
Nucleus: NucleusContracts;
}
/**
* Supported asset (token) metadata
*
* Represents a cryptocurrency token with metadata and chain support.
* Joins with EarnVault via address == EarnVault.Nucleus.baseTokenAddressId
*
* @example
* ```typescript
* const asset: SupportedAsset = {
* address: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
* symbol: "USDC",
* name: "USD Coin",
* decimals: 6,
* supportedChains: [1, 137, 8453, 42161]
* };
* ```
*/
interface SupportedAsset {
/** Token contract address (correlation key with EarnVault.Nucleus.baseTokenAddressId) */
address: string;
/** Token symbol (e.g., USDC, USDT) */
symbol: string;
/** Full token name (e.g., USD Coin) */
name: string;
/** Number of decimal places (e.g., 6 for USDC, 18 for DAI) */
decimals: number;
/** Array of chain IDs where this token is supported */
supportedChains: number[];
}
/**
* Filter options for vault queries
*
* Used to filter vaults by chain, yield type, or deposit token.
* All filters are optional and can be combined.
*
* @example
* ```typescript
* // Get all PRIME vaults on Ethereum
* const options: VaultFilterOptions = {
* chainId: 1,
* yieldType: "PRIME"
* };
*
* // Get all vaults accepting USDC
* const usdcOptions: VaultFilterOptions = {
* depositTokenAddress: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
* };
* ```
*/
interface VaultFilterOptions {
/** Filter by chain ID */
chainId?: number;
/** Filter by yield type */
yieldType?: YieldType;
/** Filter by deposit token address */
depositTokenAddress?: string;
}
/**
* Filter options for asset queries
*
* Used to filter supported assets by chain or symbol.
* All filters are optional and can be combined.
*
* @example
* ```typescript
* // Get all assets supported on Ethereum
* const options: AssetFilterOptions = {
* chainId: 1
* };
*
* // Get USDC asset info
* const usdcOptions: AssetFilterOptions = {
* symbol: "USDC"
* };
* ```
*/
interface AssetFilterOptions {
/** Filter by chain ID (assets with this chain in supportedChains array) */
chainId?: number;
/** Filter by token symbol */
symbol?: string;
/** Filter by token address */
address?: string;
}
/**
* API error with descriptive messages
*
* Thrown when API requests fail due to network errors, server errors,
* or malformed responses.
*
* @example
* ```typescript
* throw new APIError("Failed to fetch vaults: Network timeout", {
* statusCode: 408,
* endpoint: "/v1/earn-sdk/vaults"
* });
* ```
*/
declare class APIError extends Error {
/**
* HTTP status code (if available)
*/
statusCode?: number;
/**
* API endpoint that failed
*/
endpoint?: string;
/**
* Original error cause
*/
cause?: unknown;
constructor(message: string, options?: {
statusCode?: number;
endpoint?: string;
cause?: unknown;
});
}
/**
* Supported asset information for withdrawal
*
* Asset grouped with available vaults that support withdrawal of that asset.
*
* @example
* ```typescript
* const asset: WithdrawSupportedAsset = {
* address: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
* symbol: "USDC",
* decimals: 6,
* vaults: [
* { id: "prime-usdc-eth", yieldType: "PRIME", chainId: 1, vaultId: "..." },
* { id: "prime-usdc-boba", yieldType: "PRIME", chainId: 288, vaultId: "..." },
* ],
* };
* ```
*/
interface WithdrawSupportedAsset {
/** Token contract address */
address: Address;
/** Token symbol (e.g., "USDC", "ETH") */
symbol: string;
/** Number of decimal places for this token */
decimals: number;
/** Array of vaults that support withdrawals of this asset */
vaults: Array<{
id: string;
yieldType: YieldType;
chainId: number;
vaultId: string;
}>;
}
export { type AssetFilterOptions as A, type EarnVault as E, type SupportedAsset as S, type VaultFilterOptions as V, type WithdrawSupportedAsset as W, type YieldType as Y, APIError as a };