@mycelium-sdk/core 1.0.0-alpha.0 → 1.0.0-alpha.1

package/dist/index.d.ts

@@ -4,23 +4,6 @@ import { SmartAccount, BundlerClient, WebAuthnAccount, toCoinbaseSmartAccount }
 declare const SUPPORTED_CHAIN_IDS: number[];
 type SupportedChainId = (typeof SUPPORTED_CHAIN_IDS)[number];
 
-/**
- * @internal
- * @category Types
- *  Detailed token balance information
- *
- */
-interface TokenBalance {
-    symbol: string;
-    totalBalance: bigint;
-    totalFormattedBalance: string;
-    chainBalances: Array<{
-        chainId: SupportedChainId;
-        balance: bigint;
-        formattedBalance: string;
-    }>;
-}
-
 /**
  * Chain configuration
  *  Configuration for each supported chain
@@ -135,6 +118,23 @@ declare class ChainManager {
     private createPublicClient;
 }
 
+/**
+ * @internal
+ * @category Types
+ *  Detailed token balance information
+ *
+ */
+interface TokenBalance {
+    symbol: string;
+    totalBalance: bigint;
+    totalFormattedBalance: string;
+    chainBalances: Array<{
+        chainId: SupportedChainId;
+        balance: bigint;
+        formattedBalance: string;
+    }>;
+}
+
 /**
  * Asset identifier - can be a symbol (like 'usdc') or address
  */
@@ -294,7 +294,7 @@ declare abstract class SmartWallet {
      * @param amount Amount to deposit in human-readable format
      * @returns Promise resolving to a {@link VaultTxnResult}
      */
-    abstract earn(amount: string): Promise<VaultTxnResult>;
+    abstract earn(vaultInfo: VaultInfo, amount: string): Promise<VaultTxnResult>;
     /**
      * Retrieves the balance of deposited funds in the selected protocol vault
      *
@@ -302,7 +302,7 @@ declare abstract class SmartWallet {
      * @category Yield
      * @returns Promise resolving to a {@link VaultBalance} or null if none
      */
-    abstract getEarnBalance(): Promise<VaultBalance | null>;
+    abstract getEarnBalances(): Promise<VaultBalance[] | null>;
     /**
      * Withdraws a specific amount of shares from the protocol vault
      *
@@ -311,7 +311,7 @@ declare abstract class SmartWallet {
      * @param amount Human-readable amount of shares to withdraw
      * @returns Promise resolving to a {@link VaultTxnResult}
      */
-    abstract withdraw(amount: string): Promise<VaultTxnResult>;
+    abstract withdraw(vaultInfo: VaultInfo, amount: string): Promise<VaultTxnResult>;
     /**
      * Funds the smart wallet with the specified amount of the specified token via Coinbase CDP on-ramp service
      *
@@ -350,6 +350,63 @@ declare abstract class SmartWallet {
     abstract cashOut(country: string, paymentMethod: string, redirectUrl: string, sellAmount: string, cashoutCurrency?: string, sellCurrency?: string): Promise<OffRampUrlResponse>;
 }
 
+type ApiResponse<T = unknown> = {
+    success: true;
+    data: T;
+} | {
+    success: false;
+    error: string;
+};
+type OperationType = 'config' | 'deposit' | 'withdraw' | 'log' | 'vaults' | 'balances' | 'apiKeyValidation';
+
+declare class ApiClient {
+    private readonly client;
+    /** URL settings for the endpoint: get the best vaults to deposit funds */
+    private readonly bestVaultUrlSettings;
+    /** URL settings for the endpoint: deposit funds to a provided vault */
+    private readonly depositUrlSettings;
+    /** URL settings for the endpoint: log a vault-related operation after deposit or withdraw funds */
+    private readonly logOperationSettings;
+    /** URL settings for the endpoint: withdraw funds from a provided vault */
+    private readonly withdrawUrlSettings;
+    /** URL settings for the endpoint: get the balances of a user by a provided address */
+    private readonly balancesUrlSettings;
+    /** URL settings for the endpoint: validate the API key */
+    private readonly apiKeyValidUrlSettings;
+    /** URL settings for the endpoint: get the config for services */
+    private readonly configUrlSettings;
+    /** URL settings mapping with operation types */
+    private readonly operationTypeToUrlSettings;
+    /** API key for the backend API */
+    private apiKey;
+    constructor(apiKey: string);
+    /**
+     * Send a request to the backend API
+     * @param path Path of the endpoint to send the request to
+     * @param method Method of the request
+     * @param body Body of the request
+     * @returns Response from the backend API
+     */
+    sendRequest(operationType: OperationType, params?: Record<string, string>, protocolId?: string, body?: Record<string, string | VaultInfo>): Promise<ApiResponse<unknown>>;
+    /**
+     * Validates whether the provided API key is valid
+     *
+     * @internal
+     * @param apiKey API key from {@link ProtocolsRouterConfig}
+     * @returns True if the API key is considered valid
+     */
+    validate(): Promise<boolean>;
+    /**
+     *
+     * Validates the format of the API key. Must start with 'sk_' and contain only hexadecimal characters
+     *
+     * @internal
+     * @param apiKey API key from {@link ProtocolsRouterConfig}
+     * @returns
+     */
+    private validateApiKeyFormat;
+}
+
 /**
  * Base Protocol
  *
@@ -363,56 +420,51 @@ declare abstract class SmartWallet {
  *
  * Generic parameters allow protocol-specific typing for vault info, balances, and transaction results
  */
-declare abstract class BaseProtocol<TVaultInfo extends VaultInfo = VaultInfo, TVaultBalance extends VaultBalance = VaultBalance, TVaultTxnResult extends VaultTxnResult = VaultTxnResult> {
-    /** Chain manager instance injected during initialization */
+declare abstract class BaseProtocol {
+    /** Selected chain ID for the protocol */
+    protected selectedChainId: SupportedChainId | undefined;
+    /** Public client to make requests to RPC */
+    protected publicClient: PublicClient | undefined;
+    /** Chain manager instance for network access */
     chainManager: ChainManager | undefined;
     /**
      * Initialize the protocol
      * @param chainManager Chain manager for accessing RPC and bundler clients
      */
-    abstract init(chainManager: ChainManager): Promise<void>;
+    abstract init(chainManager: ChainManager, protocolsSecurityConfig: ProtocolsSecurityConfig, apiClient?: ApiClient): Promise<void>;
     /**
      * Ensure the protocol has been initialized
      * @throws Error if `init()` has not been called
      */
     protected ensureInitialized(): void;
-    /**
-     * Get all available vaults
-     * @returns List of vaults that support deposits
-     */
-    abstract getVaults(): Promise<TVaultInfo[]> | TVaultInfo[];
     /**
      * Get the best vault for deposits
      * @returns Single vault considered optimal for deposit
      */
-    abstract getBestVault(): Promise<TVaultInfo> | TVaultInfo;
-    /**
-     * Get a vault where funds may already be deposited
-     * @param smartWallet Wallet to check for existing deposits
-     * @returns Vault info if deposits exist, otherwise null
-     */
-    abstract fetchDepositedVaults(smartWallet: SmartWallet): Promise<TVaultInfo | null>;
+    abstract getBestVaults(stableVaultsLimit?: number, nonStableVaultsLimit?: number): Promise<Vaults> | Vaults;
     /**
      * Deposit funds into a vault
+     * @param vaultInfo Vault information
      * @param amount Amount in human-readable format
      * @param smartWallet Wallet executing the deposit
      * @returns Result of the deposit transaction
      */
-    abstract deposit(amount: string, smartWallet: SmartWallet): Promise<TVaultTxnResult>;
+    abstract deposit(vaultInfo: VaultInfo, amount: string, smartWallet: SmartWallet): Promise<VaultTxnResult>;
     /**
      * Withdraw funds from a vault
-     * @param amountInShares Amount of shares to withdraw
+     * @param vaultInfo Vault information
+     * @param amount Amount in human-readable format (or undefined to withdraw all)
      * @param smartWallet Wallet executing the withdrawal
      * @returns Result of the withdrawal transaction
      */
-    abstract withdraw(amountInShares: string, smartWallet: SmartWallet): Promise<TVaultTxnResult>;
+    abstract withdraw(vaultInfo: VaultInfo, amountInShares: string, smartWallet: SmartWallet): Promise<VaultTxnResult>;
     /**
      * Get deposited balance in a vault
-     * @param vaultInfo Vault info for a selected protocol
      * @param walletAddress Wallet address to check the balance of
+     * @param protocolId Protocol ID to get balances for
      * @returns Balance of deposited funds
      */
-    abstract getBalance(vaultInfo: TVaultInfo, walletAddress: Address): Promise<TVaultBalance>;
+    abstract getBalances(walletAddress: Address, protocolId?: string): Promise<VaultBalance[]>;
     /**
      * Approve a token for protocol use
      * @param tokenAddress Token address
@@ -434,35 +486,14 @@ declare abstract class BaseProtocol<TVaultInfo extends VaultInfo = VaultInfo, TV
     protected checkAllowance(tokenAddress: Address, spenderAddress: Address, walletAddress: Address, chainId: SupportedChainId): Promise<bigint>;
 }
 
-/**
- * Base information that can be used to identify a protocol
- */
-interface ProtocolInfo {
-    id: string;
-    name: string;
-    website: string;
-    logo: string;
-    supportedChains: number[];
-    riskLevel: 'low' | 'medium' | 'high';
-    isPremium: boolean;
-}
-/**
- * Interface with protocol information and instance object
- */
-interface Protocol {
-    instance: BaseProtocol;
-    info: ProtocolInfo;
-}
 /**
  * The protocols router config that defines which protocols should be used for an integrator
  */
-interface ProtocolsRouterConfig {
+interface ProtocolsSecurityConfig {
     riskLevel: 'low' | 'medium' | 'high';
-    minApy?: number;
-    apiKey?: string;
 }
 /**
- * @internal
+ * @public
  * The info about a protocol vault
  * @category Types
  * @remarks
@@ -470,17 +501,26 @@ interface ProtocolsRouterConfig {
  */
 interface VaultInfo {
     id: string;
-    chain: string;
-    chainId?: number;
-    depositTokenAddress: Address;
-    depositTokenDecimals: number;
-    depositTokenSymbol?: string;
+    protocolId: string;
     vaultAddress: Address;
-    earnTokenAddress?: Address;
-    earnTokenDecimals?: number;
-    earnTokenSymbol?: string;
+    tokenAddress: Address;
+    tokenDecimals: number;
+    tokenSymbol?: string;
+    name: string;
+    type: 'stable' | 'non-stable';
+    chain: string;
     metadata?: Record<string, number | string>;
 }
+/**
+ * @public
+ * The array of stable and non-stable vaults for a protocol
+ * @remarks Stable and non-stable vaults are @see VaultInfo type
+ * @category Types
+ */
+interface Vaults {
+    stable: VaultInfo[];
+    nonStable: VaultInfo[];
+}
 /**
  * @public
  * The info about current user's balance in a protocol vault
@@ -489,10 +529,8 @@ interface VaultInfo {
  * The generic type that shows fields that should be present in a protocol vault balance
  */
 interface VaultBalance {
-    /** amount of shares in a protocol vault based on a deposited amount */
-    shares: string;
     /** amount of deposited tokens in a protocol vault (e.g. sUSDC)*/
-    depositedAmount: string;
+    balance: string | ProxyBalance | null;
     /** info about a protocol vault where a user deposited funds */
     vaultInfo: VaultInfo;
 }
@@ -512,44 +550,24 @@ interface VaultTxnResult {
     error?: string;
 }
 
-interface SparkVaultInfo extends VaultInfo {
-    id: string;
-    chain: string;
-    earnTokenAddress: Address;
-    earnTokenDecimals: number;
-    depositTokenSymbol: string;
-    earnTokenSymbol: string;
-    metadata?: {
-        apy?: number;
-    };
-}
-/**
- * @public
- * The result of a Spark vault deposit or withdrawal transaction
- * @category Types
- */
-interface SparkVaultTxnResult {
-    /** the boolean value that indicates if the transaction was successful */
-    success: boolean;
-    /** hash of the operation */
-    hash: string;
-}
-/**
- * @public
- * The info about current user's balance in a Spark vault
- * @category Types
- */
-interface SparkVaultBalance {
-    /** amount of shares in sUSDC token that user has in the Spark vault */
-    shares: string;
-    /**
-     *  amount of deposited tokens + earned tokens
-     * @remarks
-     * To get the amount of earned tokens, you need to store all user's deposits and withdrawals
-     * on your side and then subtract the amount of deposited tokens from the `depositedAmount` */
-    depositedAmount: string;
-    /** detailed info about a Spark vault where a user deposited funds */
-    vaultInfo: SparkVaultInfo;
+interface ProxyBalance {
+    userAddress: Address;
+    integratorId: string;
+    protocolId: string;
+    vaultAddress: Address;
+    chainId: number;
+    currentBalance: string;
+    actualCurrentBalance: string;
+    pnl: number;
+    balanceInShares: string;
+    earnedOverall: string;
+    earned7d: string;
+    earned30d: string;
+    earned90d: string;
+    earnedOverallUpdatedAt: string | null;
+    earned7dUpdatedAt: string | null;
+    earned30dUpdatedAt: string | null;
+    earned90dUpdatedAt: string | null;
 }
 
 /**
@@ -1008,6 +1026,22 @@ declare class WalletNamespace {
     getSmartWallet(params: GetSmartWalletOptions): Promise<SmartWallet>;
 }
 
+/**
+ * Protocol namespace to manage protocol related operations, e.g. get best vaults
+ * @public
+ * @category Protocols
+ */
+declare class ProtocolsNamespace {
+    private protocol;
+    constructor(protocol: BaseProtocol);
+    /**
+     * Find the best vaults for protocols that were selected based on integrator's settings
+     *
+     * @returns Best vaults for protocols that were selected based on integrator's settings
+     */
+    getBestVaults(stableVaultsLimit?: number, nonStableVaultsLimit?: number): Promise<Vaults>;
+}
+
 /**
  * Mycelium SDK configuration
  * Configuration object for initializing the Mycelium SDK
@@ -1070,7 +1104,7 @@ interface MyceliumSDKConfig {
      * @remarks
      * If an integrator is not provided any requirements, `low` risk level protocols will be used by default
      */
-    protocolsRouterConfig?: ProtocolsRouterConfig;
+    protocolsSecurityConfig?: ProtocolsSecurityConfig;
     /**
      * Coinbase CDP configuration
      * @remarks
@@ -1081,6 +1115,15 @@ interface MyceliumSDKConfig {
      */
     coinbaseCDPConfig?: CoinbaseCDPConfig;
 }
+/**
+ * Basic Mycelium SDK configuration for a case when a user provided only API key without advanced configurations
+ */
+interface BasicMyceliumSDKConfig {
+    apiKey: string;
+    chainId?: number;
+    protocolsSecurityConfig: ProtocolsSecurityConfig;
+    overrides?: Partial<MyceliumSDKConfig>;
+}
 /**
  * Coinbase CDP configuration
  * Configuration for Coinbase CDP API
@@ -1270,7 +1313,8 @@ declare class DefaultSmartWallet extends SmartWallet {
      * @param signerOwnerIndex Optional index of `signer` in owners (default 0)
      * @param nonce Optional salt for deterministic address calc (default 0)
      */
-    constructor(owners: Array<Address | WebAuthnAccount>, signer: LocalAccount, chainManager: ChainManager, protocolProvider: Protocol['instance'], coinbaseCDP: CoinbaseCDP | null, deploymentAddress?: Address, signerOwnerIndex?: number, nonce?: bigint);
+    constructor(owners: Array<Address | WebAuthnAccount>, signer: LocalAccount, chainManager: ChainManager, protocolProvider: BaseProtocol, // Protocol['instance'],
+    coinbaseCDP: CoinbaseCDP | null, deploymentAddress?: Address, signerOwnerIndex?: number, nonce?: bigint);
     /**
      * Returns the signer account for this smart wallet
      *
@@ -1320,7 +1364,7 @@ declare class DefaultSmartWallet extends SmartWallet {
      * @param amount Human-readable amount string
      * @returns Transaction result for the deposit
      */
-    earn(amount: string): Promise<VaultTxnResult>;
+    earn(vaultInfo: VaultInfo, amount: string): Promise<VaultTxnResult>;
     /**
      * Reads current deposit balance from the selected protocol’s vault
      * Method to read the current deposit balance from the selected protocol’s vault for a smart account
@@ -1329,7 +1373,7 @@ declare class DefaultSmartWallet extends SmartWallet {
      * @category Earn
      * @returns Vault balance or `null` if nothing deposited
      */
-    getEarnBalance(): Promise<VaultBalance | null>;
+    getEarnBalances(): Promise<VaultBalance[]>;
     /**
      * Withdraws from the selected protocol’s vault
      * @public
@@ -1339,7 +1383,7 @@ declare class DefaultSmartWallet extends SmartWallet {
      * @throws Error if the withdrawal fails
      * @throws Error a user didn't deposit anything
      */
-    withdraw(amount: string): Promise<VaultTxnResult>;
+    withdraw(vaultInfo: VaultInfo, amount: string): Promise<VaultTxnResult>;
     /**
      * Builds a UserOperation and submits via the bundler, then waits for inclusion
   
@@ -1476,31 +1520,39 @@ declare class FundingNamespace {
  * @category 1. Getting started
  * @remarks
  * This class encapsulates:
- * - protocol selection and initialization (`Smart Router`),
+ * - protocol selection and initialization
  * - chain/network management (`ChainManager`),
  * - public wallet namespace (accessible through {@link MyceliumSDK.wallet | wallet}).
  *
  * By default, if no chain config is provided, it uses the public RPC
  * and Bundler for the Base chain
  *
+ * The SDK can be initialized in two ways:
+ * 1. With an API key - fetches configuration from backend automatically
+ * 2. With full configuration - uses provided configuration directly
+ *
  * @example
- * ```ts
- * import { MyceliumSDK, type MyceliumSDKConfig } from '@mycelium-sdk/core';
  *
+ * import { MyceliumSDK, type MyceliumSDKConfig, type BasicMyceliumSDKConfig } from '@mycelium-sdk/core';
+ *
+ * // Option 1: Initialize with API key (fetches config from backend)
+ * const sdk = await MyceliumSDK.init({
+ *   apiKey: 'sk_...'
+ * });
+ *
+ * // Option 2: Initialize with full configuration
  * const config: MyceliumSDKConfig = {
  *   walletsConfig: { /* ... *\/ },
- *   protocolsRouterConfig: { /* ... *\/ },
+ *   protocolsSecurityConfig: { riskLevel: 'low' },
  *   chain: { /* ... *\/ },
  *   coinbaseCDPConfig: { /* ... *\/ },
  *   integratorId: 'MyceliumApp',
  * };
- *
- * const sdk = new MyceliumSDK(config);
+ * const sdk = await MyceliumSDK.init(config);
  *
  * const {embeddedWalletId, smartWallet} = await sdk.wallet.createAccount();
  * const balance = await smartWallet.getBalance();
- * ```
- */
+ *  */
 declare class MyceliumSDK {
     /**
      * Returns a unified wallet namespace to manage embedded/smart wallets and related operations
@@ -1508,6 +1560,12 @@ declare class MyceliumSDK {
      * @category Wallets
      */
     readonly wallet: WalletNamespace;
+    /**
+     * Protocol namespace to manage protocol related operations
+     * @public
+     * @category Protocols
+     */
+    readonly protocols: ProtocolsNamespace;
     /**
      * Ramp namespace to manage ramp operations. Methods are available on {@link RampNamespace}
      * @internal
@@ -1531,6 +1589,8 @@ declare class MyceliumSDK {
      * @internal
      */
     private protocol;
+    /** API client for the backend API */
+    apiClient: ApiClient | undefined;
     /**
      * Coinbase CDP instance to Coinbase related and onchain operations using Coinbase CDP API
      * @remarks
@@ -1539,6 +1599,12 @@ declare class MyceliumSDK {
      * @internal
      */
     private coinbaseCDP;
+    /**
+     * Initializes the SDK
+     * @param config SDK configuration (networks, wallets, protocol router settings)
+     * @returns SDK instance
+     */
+    static init(config: BasicMyceliumSDKConfig | MyceliumSDKConfig): Promise<MyceliumSDK>;
     /**
      * Creates a new SDK instance
      *
@@ -1546,7 +1612,7 @@ declare class MyceliumSDK {
      * @throws Throws if an unsupported wallet provider is given
      * @see MyceliumSDKConfig
      */
-    constructor(config: MyceliumSDKConfig);
+    constructor(config: MyceliumSDKConfig, isPremiumAvailable: boolean, apiClient?: ApiClient);
     /**
      * Returns the chain manager instance for multi-chain operations
      * @public
@@ -1574,7 +1640,7 @@ declare class MyceliumSDK {
      * @param config Protocol router configuration (e.g. risk level)
      * @returns Selected protocol object of the type {@link Protocol}
      */
-    private findProtocol;
+    private selectProtocol;
     /**
      * Creates a wallet provider (embedded + smart) and combines them
      *
@@ -1594,4 +1660,4 @@ declare class MyceliumSDK {
     private createWalletNamespace;
 }
 
-export { type OffRampUrlResponse as CashOutUrlResponse, DefaultSmartWallet, EmbeddedWallet, FundingNamespace, type RampConfigResponse as FundingOptionsResponse, MyceliumSDK, type MyceliumSDKConfig, SmartWallet, type SparkVaultBalance, type SparkVaultTxnResult, type TokenBalance, type OnRampUrlResponse as TopUpUrlResponse, type VaultBalance, type VaultTxnResult, WalletNamespace };
+export { type OffRampUrlResponse as CashOutUrlResponse, DefaultSmartWallet, EmbeddedWallet, FundingNamespace, type RampConfigResponse as FundingOptionsResponse, MyceliumSDK, type MyceliumSDKConfig, ProtocolsNamespace, type ProxyBalance, SmartWallet, type TokenBalance, type OnRampUrlResponse as TopUpUrlResponse, type VaultBalance, type VaultInfo, type VaultTxnResult, type Vaults, WalletNamespace };