@stablechain/sdk 0.1.1 → 1.0.0

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,146 @@ 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;
+}
+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;
+}
+/**
+ * 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 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 +251,33 @@ 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>;
+        redeem(params: EarnRedeemParams): Promise<EarnResult>;
+        forceWithdraw(params: ForceWithdrawParams): Promise<EarnResult>;
+        forceRedeem(params: ForceRedeemParams): Promise<EarnResult>;
+    };
 }
-declare function createStable({ network, rpc: rpcOverride, account, transport, walletClient, }: StableConfig): StableClient;
+interface StableReader {
+    earn: {
+        /** 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, earn: earnConfig, }: StableConfig): StableClient;
+declare function createStableReader(config: StableReaderConfig): StableReader;
 
 interface ChainConfig {
     id: number;
@@ -117,6 +288,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 +336,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, 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 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,146 @@ 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;
+}
+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;
+}
+/**
+ * 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 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 +251,33 @@ 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>;
+        redeem(params: EarnRedeemParams): Promise<EarnResult>;
+        forceWithdraw(params: ForceWithdrawParams): Promise<EarnResult>;
+        forceRedeem(params: ForceRedeemParams): Promise<EarnResult>;
+    };
 }
-declare function createStable({ network, rpc: rpcOverride, account, transport, walletClient, }: StableConfig): StableClient;
+interface StableReader {
+    earn: {
+        /** 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, earn: earnConfig, }: StableConfig): StableClient;
+declare function createStableReader(config: StableReaderConfig): StableReader;
 
 interface ChainConfig {
     id: number;
@@ -117,6 +288,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 +336,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, 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 WithdrawStatus, type YieldPreview, createStable, createStableReader };