@stablechain/sdk 0.1.1 → 1.0.1

package/dist/index.d.cts

@@ -1,5 +1,9 @@
 import { Account, Transport, WalletClient, Address, BaseError } from 'viem';
 
+interface EarnConfig {
+    /** MetaMorpho V2 vault address */
+    vault: string;
+}
 interface StableConfig {
     /** Target network — defaults to Network.Mainnet */
     network?: Network;
@@ -11,6 +15,8 @@ interface StableConfig {
     transport?: Transport;
     /** Pre-configured viem WalletClient — takes precedence over account/transport. */
     walletClient?: WalletClient;
+    /** Earn (Morpho V2 vault) configuration — required to use stable.earn.* methods. */
+    earn?: EarnConfig;
 }
 /**
  * Unified result for transfer, bridge, and swap.
@@ -98,6 +104,181 @@ interface BridgeParams {
     /** Pre-fetched quote from quoteBridge() — skips the quote fetch when passed to bridge() */
     quote?: BridgeQuote;
 }
+interface EarnDepositParams {
+    /** Amount of underlying assets to deposit (human-readable) */
+    amount: number;
+    /** Vault address — overrides the vault set in StableConfig. Required when using bulkDeposit across multiple vaults. */
+    vault?: string;
+    /** Underlying asset decimals — fetched on-chain if omitted */
+    tokenDecimals?: number;
+    /**
+     * Slippage tolerance as a decimal (e.g. 0.003 = 0.3%).
+     * Defaults to Morpho's built-in default (0.03%).
+     */
+    slippageTolerance?: number;
+    /** Deduplication key: if an operation with this key is already in flight, the same Promise is returned. */
+    idempotencyKey?: string;
+    /**
+     * Maximum fraction of the vault's idle liquidity that this deposit may consume (e.g. 0.8 = 80%).
+     * The SDK throws StableValidationError before sending the transaction if the amount exceeds the cap.
+     * Must be > 0 and ≤ 1. Omit to disable the check.
+     */
+    depositBuffer?: number;
+}
+interface EarnWithdrawParams {
+    /** Amount of underlying assets to withdraw (human-readable) */
+    amount: number;
+    /** Underlying asset decimals — fetched on-chain if omitted */
+    tokenDecimals?: number;
+    /** Deduplication key */
+    idempotencyKey?: string;
+}
+interface EarnRedeemParams {
+    /** Number of vault shares to redeem (human-readable, uses vault's share decimals) */
+    shares: number;
+    /** Vault share decimals — fetched on-chain if omitted */
+    shareDecimals?: number;
+    /** Deduplication key */
+    idempotencyKey?: string;
+}
+interface EarnResult {
+    txHash: string;
+    idempotencyKey?: string;
+}
+type BulkEarnResultItem = {
+    status: "fulfilled";
+    txHash: string;
+    vault?: string;
+    idempotencyKey?: string;
+} | {
+    status: "rejected";
+    error: string;
+    vault?: string;
+    idempotencyKey?: string;
+};
+interface BulkEarnResult {
+    results: BulkEarnResultItem[];
+    /** Number of deposits that succeeded */
+    succeeded: number;
+    /** Number of deposits that failed */
+    failed: number;
+    idempotencyKey?: string;
+}
+interface BulkDepositOptions {
+    /** Batch-level deduplication key — if this batch is already in flight, the same Promise is returned. */
+    idempotencyKey?: string;
+    /**
+     * When true, the batch halts on the first failure and rejects.
+     * When false (default), all deposits are attempted and partial results are returned.
+     */
+    stopOnError?: boolean;
+}
+interface BulkWithdrawOptions {
+    /** Batch-level deduplication key — if this batch is already in flight, the same Promise is returned. */
+    idempotencyKey?: string;
+    /**
+     * When true, the batch halts on the first failure and rejects.
+     * When false (default), all withdrawals are attempted and partial results are returned.
+     */
+    stopOnError?: boolean;
+}
+/**
+ * A single adapter position to forcibly deallocate before a force withdraw/redeem.
+ * `amount` is in underlying asset units (human-readable).
+ * `marketParams` is required only for Morpho Blue market adapters; omit for vault adapters.
+ */
+interface ForceDeallocation {
+    adapter: string;
+    amount: number;
+    marketParams?: {
+        loanToken: string;
+        collateralToken: string;
+        oracle: string;
+        irm: string;
+        /** LLTV scaled by WAD (1e18) */
+        lltv: bigint;
+    };
+}
+interface ForceWithdrawParams {
+    /** Amount of underlying assets to withdraw (human-readable) */
+    amount: number;
+    /** Underlying asset decimals — fetched on-chain if omitted */
+    tokenDecimals?: number;
+    /** Adapter positions to deallocate before the withdrawal */
+    deallocations: ForceDeallocation[];
+    /** Deduplication key */
+    idempotencyKey?: string;
+}
+interface ForceRedeemParams {
+    /** Number of vault shares to redeem (human-readable) */
+    shares: number;
+    /** Vault share decimals — fetched on-chain if omitted */
+    shareDecimals?: number;
+    /** Underlying asset decimals for deallocation amounts — fetched on-chain if omitted */
+    tokenDecimals?: number;
+    /** Adapter positions to deallocate before the redemption */
+    deallocations: ForceDeallocation[];
+    /** Deduplication key */
+    idempotencyKey?: string;
+}
+interface VaultYieldReward {
+    /** Reward token symbol (e.g. "MORPHO") */
+    symbol: string;
+    /** Reward token contract address */
+    address: string;
+    /** APR contribution from this reward token as a decimal (e.g. 0.02 = 2%) */
+    apr: number;
+}
+interface VaultYield {
+    /** Total net APY after all fees, including rewards, as a decimal (e.g. 0.05 = 5%) */
+    apy: number;
+    /** Native yield component — underlying market rates after fees, excluding reward boosts */
+    native: number;
+    /** Per-token reward boosts */
+    rewards: VaultYieldReward[];
+    /** Performance fee as a decimal (e.g. 0.1 = 10%) */
+    performanceFee: number;
+    /** Management fee as a decimal */
+    managementFee: number;
+}
+interface VaultPosition {
+    /** Raw vault share balance */
+    shares: bigint;
+    /** Human-readable share balance (shares formatted by shareDecimals) */
+    sharesFormatted: number;
+    /** Vault share token decimals */
+    shareDecimals: number;
+    /** Asset value of shares (human-readable) */
+    assets: number;
+    /** Underlying asset decimals */
+    tokenDecimals: number;
+    /** Underlying asset contract address */
+    assetAddress: string;
+}
+interface YieldPreview {
+    /** Expected yield over the period, in asset units (human-readable) */
+    projectedYield: number;
+    /** Annual percentage yield as a decimal (e.g. 0.05 = 5%) */
+    apy: number;
+    horizonDays: number;
+}
+interface WithdrawStatus {
+    /** True when the full amount can be withdrawn from idle vault liquidity immediately */
+    isInstant: boolean;
+    /** Instantly available liquidity in asset units (human-readable) */
+    availableLiquidity: number;
+    tokenDecimals: number;
+}
+interface StableReaderConfig {
+    /** Target network — defaults to Network.Mainnet */
+    network?: Network;
+    /** Optional RPC override */
+    rpc?: string;
+    /** Earn configuration — required for reader.earn.* methods */
+    earn?: EarnConfig;
+    /** Address of the user whose position to read */
+    address: string;
+}
 
 interface StableClient {
     transfer(params: TransferParams): Promise<OperationResult>;
@@ -105,8 +286,36 @@ interface StableClient {
     bridge(params: BridgeParams): Promise<OperationResult>;
     quoteSwap(params: SwapParams): Promise<SwapQuote>;
     swap(params: SwapParams): Promise<OperationResult>;
+    earn: {
+        deposit(params: EarnDepositParams): Promise<EarnResult>;
+        bulkDeposit(items: EarnDepositParams[], options?: BulkDepositOptions): Promise<BulkEarnResult>;
+        withdraw(params: EarnWithdrawParams): Promise<EarnResult>;
+        bulkWithdraw(items: EarnWithdrawParams[], options?: BulkWithdrawOptions): Promise<BulkEarnResult>;
+        redeem(params: EarnRedeemParams): Promise<EarnResult>;
+        forceWithdraw(params: ForceWithdrawParams): Promise<EarnResult>;
+        forceRedeem(params: ForceRedeemParams): Promise<EarnResult>;
+    };
+}
+interface StableReader {
+    earn: {
+        /** Current net APY for the configured vault. */
+        getYield(): Promise<VaultYield>;
+        /** Current vault position (shares + asset value) for the configured user address. */
+        position(): Promise<VaultPosition>;
+        /** Projected yield over a given horizon, using Morpho's live net APY. */
+        preview(params: {
+            amount: number;
+            horizonDays: number;
+        }): Promise<YieldPreview>;
+        /** Whether a given withdrawal amount can be fulfilled instantly from idle liquidity. */
+        withdrawability(params: {
+            amount: number;
+            tokenDecimals?: number;
+        }): Promise<WithdrawStatus>;
+    };
 }
-declare function createStable({ network, rpc: rpcOverride, account, transport, walletClient, }: StableConfig): StableClient;
+declare function createStable({ network, rpc: rpcOverride, account, transport, walletClient, earn: earnConfig, }: StableConfig): StableClient;
+declare function createStableReader(config: StableReaderConfig): StableReader;
 
 interface ChainConfig {
     id: number;
@@ -117,6 +326,9 @@ interface ChainConfig {
 }
 declare const CHAIN_CONFIGS: Partial<Record<Chain, ChainConfig>>;
 
+declare const STABLE_USDT_ADDRESS: Address;
+declare const STABLE_VAULT_ADDRESS: Address;
+
 declare class StableError extends BaseError {
 }
 declare class StableValidationError extends StableError {
@@ -162,5 +374,16 @@ declare class StableNetworkError extends StableError {
         cause?: Error;
     });
 }
+declare class StableBulkError extends StableError {
+    results: BulkEarnResultItem[];
+    succeeded: number;
+    failed: number;
+    constructor(args: {
+        shortMessage: string;
+        results: BulkEarnResultItem[];
+        succeeded: number;
+        failed: number;
+    });
+}
 
-export { type BridgeParams, type BridgeQuote, CHAIN_CONFIGS, Chain, type ChainConfig, Network, type OperationResult, type StableClient, type StableConfig, StableError, StableNetworkError, StableQuoteError, StableTransactionError, StableValidationError, type SwapParams, type SwapQuote, type TransferParams, createStable };
+export { type BridgeParams, type BridgeQuote, type BulkDepositOptions, type BulkEarnResult, type BulkEarnResultItem, type BulkWithdrawOptions, CHAIN_CONFIGS, Chain, type ChainConfig, type EarnConfig, type EarnDepositParams, type EarnRedeemParams, type EarnResult, type EarnWithdrawParams, type ForceDeallocation, type ForceRedeemParams, type ForceWithdrawParams, Network, type OperationResult, STABLE_USDT_ADDRESS, STABLE_VAULT_ADDRESS, StableBulkError, type StableClient, type StableConfig, StableError, StableNetworkError, StableQuoteError, type StableReader, type StableReaderConfig, StableTransactionError, StableValidationError, type SwapParams, type SwapQuote, type TransferParams, type VaultPosition, type VaultYield, type VaultYieldReward, type WithdrawStatus, type YieldPreview, createStable, createStableReader };

package/dist/index.d.ts

@@ -1,5 +1,9 @@
 import { Account, Transport, WalletClient, Address, BaseError } from 'viem';
 
+interface EarnConfig {
+    /** MetaMorpho V2 vault address */
+    vault: string;
+}
 interface StableConfig {
     /** Target network — defaults to Network.Mainnet */
     network?: Network;
@@ -11,6 +15,8 @@ interface StableConfig {
     transport?: Transport;
     /** Pre-configured viem WalletClient — takes precedence over account/transport. */
     walletClient?: WalletClient;
+    /** Earn (Morpho V2 vault) configuration — required to use stable.earn.* methods. */
+    earn?: EarnConfig;
 }
 /**
  * Unified result for transfer, bridge, and swap.
@@ -98,6 +104,181 @@ interface BridgeParams {
     /** Pre-fetched quote from quoteBridge() — skips the quote fetch when passed to bridge() */
     quote?: BridgeQuote;
 }
+interface EarnDepositParams {
+    /** Amount of underlying assets to deposit (human-readable) */
+    amount: number;
+    /** Vault address — overrides the vault set in StableConfig. Required when using bulkDeposit across multiple vaults. */
+    vault?: string;
+    /** Underlying asset decimals — fetched on-chain if omitted */
+    tokenDecimals?: number;
+    /**
+     * Slippage tolerance as a decimal (e.g. 0.003 = 0.3%).
+     * Defaults to Morpho's built-in default (0.03%).
+     */
+    slippageTolerance?: number;
+    /** Deduplication key: if an operation with this key is already in flight, the same Promise is returned. */
+    idempotencyKey?: string;
+    /**
+     * Maximum fraction of the vault's idle liquidity that this deposit may consume (e.g. 0.8 = 80%).
+     * The SDK throws StableValidationError before sending the transaction if the amount exceeds the cap.
+     * Must be > 0 and ≤ 1. Omit to disable the check.
+     */
+    depositBuffer?: number;
+}
+interface EarnWithdrawParams {
+    /** Amount of underlying assets to withdraw (human-readable) */
+    amount: number;
+    /** Underlying asset decimals — fetched on-chain if omitted */
+    tokenDecimals?: number;
+    /** Deduplication key */
+    idempotencyKey?: string;
+}
+interface EarnRedeemParams {
+    /** Number of vault shares to redeem (human-readable, uses vault's share decimals) */
+    shares: number;
+    /** Vault share decimals — fetched on-chain if omitted */
+    shareDecimals?: number;
+    /** Deduplication key */
+    idempotencyKey?: string;
+}
+interface EarnResult {
+    txHash: string;
+    idempotencyKey?: string;
+}
+type BulkEarnResultItem = {
+    status: "fulfilled";
+    txHash: string;
+    vault?: string;
+    idempotencyKey?: string;
+} | {
+    status: "rejected";
+    error: string;
+    vault?: string;
+    idempotencyKey?: string;
+};
+interface BulkEarnResult {
+    results: BulkEarnResultItem[];
+    /** Number of deposits that succeeded */
+    succeeded: number;
+    /** Number of deposits that failed */
+    failed: number;
+    idempotencyKey?: string;
+}
+interface BulkDepositOptions {
+    /** Batch-level deduplication key — if this batch is already in flight, the same Promise is returned. */
+    idempotencyKey?: string;
+    /**
+     * When true, the batch halts on the first failure and rejects.
+     * When false (default), all deposits are attempted and partial results are returned.
+     */
+    stopOnError?: boolean;
+}
+interface BulkWithdrawOptions {
+    /** Batch-level deduplication key — if this batch is already in flight, the same Promise is returned. */
+    idempotencyKey?: string;
+    /**
+     * When true, the batch halts on the first failure and rejects.
+     * When false (default), all withdrawals are attempted and partial results are returned.
+     */
+    stopOnError?: boolean;
+}
+/**
+ * A single adapter position to forcibly deallocate before a force withdraw/redeem.
+ * `amount` is in underlying asset units (human-readable).
+ * `marketParams` is required only for Morpho Blue market adapters; omit for vault adapters.
+ */
+interface ForceDeallocation {
+    adapter: string;
+    amount: number;
+    marketParams?: {
+        loanToken: string;
+        collateralToken: string;
+        oracle: string;
+        irm: string;
+        /** LLTV scaled by WAD (1e18) */
+        lltv: bigint;
+    };
+}
+interface ForceWithdrawParams {
+    /** Amount of underlying assets to withdraw (human-readable) */
+    amount: number;
+    /** Underlying asset decimals — fetched on-chain if omitted */
+    tokenDecimals?: number;
+    /** Adapter positions to deallocate before the withdrawal */
+    deallocations: ForceDeallocation[];
+    /** Deduplication key */
+    idempotencyKey?: string;
+}
+interface ForceRedeemParams {
+    /** Number of vault shares to redeem (human-readable) */
+    shares: number;
+    /** Vault share decimals — fetched on-chain if omitted */
+    shareDecimals?: number;
+    /** Underlying asset decimals for deallocation amounts — fetched on-chain if omitted */
+    tokenDecimals?: number;
+    /** Adapter positions to deallocate before the redemption */
+    deallocations: ForceDeallocation[];
+    /** Deduplication key */
+    idempotencyKey?: string;
+}
+interface VaultYieldReward {
+    /** Reward token symbol (e.g. "MORPHO") */
+    symbol: string;
+    /** Reward token contract address */
+    address: string;
+    /** APR contribution from this reward token as a decimal (e.g. 0.02 = 2%) */
+    apr: number;
+}
+interface VaultYield {
+    /** Total net APY after all fees, including rewards, as a decimal (e.g. 0.05 = 5%) */
+    apy: number;
+    /** Native yield component — underlying market rates after fees, excluding reward boosts */
+    native: number;
+    /** Per-token reward boosts */
+    rewards: VaultYieldReward[];
+    /** Performance fee as a decimal (e.g. 0.1 = 10%) */
+    performanceFee: number;
+    /** Management fee as a decimal */
+    managementFee: number;
+}
+interface VaultPosition {
+    /** Raw vault share balance */
+    shares: bigint;
+    /** Human-readable share balance (shares formatted by shareDecimals) */
+    sharesFormatted: number;
+    /** Vault share token decimals */
+    shareDecimals: number;
+    /** Asset value of shares (human-readable) */
+    assets: number;
+    /** Underlying asset decimals */
+    tokenDecimals: number;
+    /** Underlying asset contract address */
+    assetAddress: string;
+}
+interface YieldPreview {
+    /** Expected yield over the period, in asset units (human-readable) */
+    projectedYield: number;
+    /** Annual percentage yield as a decimal (e.g. 0.05 = 5%) */
+    apy: number;
+    horizonDays: number;
+}
+interface WithdrawStatus {
+    /** True when the full amount can be withdrawn from idle vault liquidity immediately */
+    isInstant: boolean;
+    /** Instantly available liquidity in asset units (human-readable) */
+    availableLiquidity: number;
+    tokenDecimals: number;
+}
+interface StableReaderConfig {
+    /** Target network — defaults to Network.Mainnet */
+    network?: Network;
+    /** Optional RPC override */
+    rpc?: string;
+    /** Earn configuration — required for reader.earn.* methods */
+    earn?: EarnConfig;
+    /** Address of the user whose position to read */
+    address: string;
+}
 
 interface StableClient {
     transfer(params: TransferParams): Promise<OperationResult>;
@@ -105,8 +286,36 @@ interface StableClient {
     bridge(params: BridgeParams): Promise<OperationResult>;
     quoteSwap(params: SwapParams): Promise<SwapQuote>;
     swap(params: SwapParams): Promise<OperationResult>;
+    earn: {
+        deposit(params: EarnDepositParams): Promise<EarnResult>;
+        bulkDeposit(items: EarnDepositParams[], options?: BulkDepositOptions): Promise<BulkEarnResult>;
+        withdraw(params: EarnWithdrawParams): Promise<EarnResult>;
+        bulkWithdraw(items: EarnWithdrawParams[], options?: BulkWithdrawOptions): Promise<BulkEarnResult>;
+        redeem(params: EarnRedeemParams): Promise<EarnResult>;
+        forceWithdraw(params: ForceWithdrawParams): Promise<EarnResult>;
+        forceRedeem(params: ForceRedeemParams): Promise<EarnResult>;
+    };
+}
+interface StableReader {
+    earn: {
+        /** Current net APY for the configured vault. */
+        getYield(): Promise<VaultYield>;
+        /** Current vault position (shares + asset value) for the configured user address. */
+        position(): Promise<VaultPosition>;
+        /** Projected yield over a given horizon, using Morpho's live net APY. */
+        preview(params: {
+            amount: number;
+            horizonDays: number;
+        }): Promise<YieldPreview>;
+        /** Whether a given withdrawal amount can be fulfilled instantly from idle liquidity. */
+        withdrawability(params: {
+            amount: number;
+            tokenDecimals?: number;
+        }): Promise<WithdrawStatus>;
+    };
 }
-declare function createStable({ network, rpc: rpcOverride, account, transport, walletClient, }: StableConfig): StableClient;
+declare function createStable({ network, rpc: rpcOverride, account, transport, walletClient, earn: earnConfig, }: StableConfig): StableClient;
+declare function createStableReader(config: StableReaderConfig): StableReader;
 
 interface ChainConfig {
     id: number;
@@ -117,6 +326,9 @@ interface ChainConfig {
 }
 declare const CHAIN_CONFIGS: Partial<Record<Chain, ChainConfig>>;
 
+declare const STABLE_USDT_ADDRESS: Address;
+declare const STABLE_VAULT_ADDRESS: Address;
+
 declare class StableError extends BaseError {
 }
 declare class StableValidationError extends StableError {
@@ -162,5 +374,16 @@ declare class StableNetworkError extends StableError {
         cause?: Error;
     });
 }
+declare class StableBulkError extends StableError {
+    results: BulkEarnResultItem[];
+    succeeded: number;
+    failed: number;
+    constructor(args: {
+        shortMessage: string;
+        results: BulkEarnResultItem[];
+        succeeded: number;
+        failed: number;
+    });
+}
 
-export { type BridgeParams, type BridgeQuote, CHAIN_CONFIGS, Chain, type ChainConfig, Network, type OperationResult, type StableClient, type StableConfig, StableError, StableNetworkError, StableQuoteError, StableTransactionError, StableValidationError, type SwapParams, type SwapQuote, type TransferParams, createStable };
+export { type BridgeParams, type BridgeQuote, type BulkDepositOptions, type BulkEarnResult, type BulkEarnResultItem, type BulkWithdrawOptions, CHAIN_CONFIGS, Chain, type ChainConfig, type EarnConfig, type EarnDepositParams, type EarnRedeemParams, type EarnResult, type EarnWithdrawParams, type ForceDeallocation, type ForceRedeemParams, type ForceWithdrawParams, Network, type OperationResult, STABLE_USDT_ADDRESS, STABLE_VAULT_ADDRESS, StableBulkError, type StableClient, type StableConfig, StableError, StableNetworkError, StableQuoteError, type StableReader, type StableReaderConfig, StableTransactionError, StableValidationError, type SwapParams, type SwapQuote, type TransferParams, type VaultPosition, type VaultYield, type VaultYieldReward, type WithdrawStatus, type YieldPreview, createStable, createStableReader };