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

package/dist/index.d.ts

@@ -553,71 +553,54 @@ interface SparkVaultBalance {
 }
 
 /**
- * Abstract base class for smart wallet providers
- *
- * @internal
- * @category Wallet Providers
- * @remarks
- * Defines the interface for factories that create and manage {@link SmartWallet} instances
- * Extended by implementations such as {@link DefaultSmartWalletProvider}
+ * Options for creating a smart wallet
+ * Parameters for creating a new smart wallet with specified owners and signer
  */
-declare abstract class SmartWalletProvider$1 {
-    /**
-     * Creates a new smart wallet instance that will be deployed on first transaction
-     *
-     * @internal
-     * @category Creation
-     * @remarks
-     * Address is calculated deterministically using owners and nonce
-     *
-     * @param params Wallet creation parameters
-     * @param params.owners Array of wallet owners (addresses or WebAuthn accounts)
-     * @param params.signer Local account used for signing
-     * @param params.nonce Optional nonce for address derivation, default 0
-     * @returns Promise resolving to a {@link SmartWallet} instance
-     */
-    abstract createWallet(params: {
-        owners: Array<Address | WebAuthnAccount>;
-        signer: LocalAccount;
-        nonce?: bigint;
-    }): Promise<SmartWallet>;
-    /**
-     * Returns a smart wallet instance for an already deployed contract
-     *
-     * @internal
-     * @category Retrieval
-     * @remarks
-     * Use when the wallet address is already known
-     *
-     * @param params Wallet retrieval parameters
-     * @param params.walletAddress Deployed smart wallet address
-     * @param params.signer Local account to operate the wallet
-     * @param params.ownerIndex Optional index of signer in the owners list, default 0
-     * @returns A {@link SmartWallet} instance
-     */
-    abstract getWallet(params: {
-        walletAddress: Address;
-        signer: LocalAccount;
-        ownerIndex?: number;
-    }): SmartWallet;
-    /**
-     * Predicts the deterministic address of a smart wallet
-     *
-     * @internal
-     * @category Addressing
-     * @remarks
-     * Uses CREATE2 with owners and nonce to calculate the wallet address
-     *
-     * @param params Prediction parameters
-     * @param params.owners Array of wallet owners (addresses or WebAuthn accounts)
-     * @param params.nonce Optional nonce, default 0
-     * @returns Promise resolving to the predicted {@link Address}
-     */
-    abstract getWalletAddress(params: {
-        owners: Array<Address | WebAuthnAccount>;
-        nonce?: bigint;
-    }): Promise<Address>;
-}
+type CreateSmartWalletOptions = {
+    owners: Array<Address | WebAuthnAccount>;
+    signer: LocalAccount;
+    nonce?: bigint;
+};
+/**
+ * Options for creating a wallet with embedded signer
+ * Parameters for creating both embedded and smart wallets, with embedded wallet automatically added as signer
+ */
+type CreateAccountOptions = {
+    owners?: Array<Address | WebAuthnAccount>;
+    embeddedWalletIndex?: number;
+    nonce?: bigint;
+};
+/**
+ * Options for retrieving a smart wallet with provided signer
+ * Parameters for getting an existing smart wallet using a provided LocalAccount signer
+ */
+type GetSmartWalletOptions = {
+    signer: LocalAccount;
+    deploymentOwners?: Array<Address | WebAuthnAccount>;
+    signerOwnerIndex?: number;
+    walletAddress?: Address;
+    nonce?: bigint;
+};
+/**
+ * Options for retrieving an embedded wallet
+ * Parameters for getting an existing embedded wallet
+ */
+type GetEmbeddedWalletOptions = {
+    walletId: string;
+};
+/**
+ * Options for retrieving a smart wallet with embedded wallet signer
+ * Parameters for getting an existing smart wallet using an embedded wallet as signer.
+ * If neither walletAddress nor deploymentOwners is provided, defaults to using the embedded wallet as single owner.
+ */
+type GetAccountOptions = Omit<GetSmartWalletOptions, 'signer'> & GetEmbeddedWalletOptions;
+/**
+ * Result of creating a unified web3 account in {@link WalletProvider.createAccount} and {@link WalletNamespace.createAccount}
+ */
+type CreateAccountResult = {
+    embeddedWalletId: string;
+    smartWallet: SmartWallet;
+};
 
 /**
  * Abstract base class for embedded wallet implementations
@@ -703,47 +686,71 @@ declare abstract class EmbeddedWalletProvider {
 }
 
 /**
- * Options for creating a smart wallet
- *  Parameters for creating a new smart wallet with specified owners and signer
- */
-type CreateSmartWalletOptions = {
-    owners: Array<Address | WebAuthnAccount>;
-    signer: LocalAccount;
-    nonce?: bigint;
-};
-/**
- * Options for creating a wallet with embedded signer
- *  Parameters for creating both embedded and smart wallets, with embedded wallet automatically added as signer
- */
-type CreateWalletWithEmbeddedSignerOptions = {
-    owners?: Array<Address | WebAuthnAccount>;
-    embeddedWalletIndex?: number;
-    nonce?: bigint;
-};
-/**
- * Options for retrieving a smart wallet with provided signer
- *  Parameters for getting an existing smart wallet using a provided LocalAccount signer
- */
-type GetSmartWalletOptions = {
-    signer: LocalAccount;
-    deploymentOwners?: Array<Address | WebAuthnAccount>;
-    signerOwnerIndex?: number;
-    walletAddress?: Address;
-    nonce?: bigint;
-};
-/**
- * Options for retrieving an embedded wallet
- *  Parameters for getting an existing embedded wallet
- */
-type GetEmbeddedWalletOptions = {
-    walletId: string;
-};
-/**
- * Options for retrieving a smart wallet with embedded wallet signer
- *  Parameters for getting an existing smart wallet using an embedded wallet as signer.
- * If neither walletAddress nor deploymentOwners is provided, defaults to using the embedded wallet as single owner.
+ * Abstract base class for smart wallet providers
+ *
+ * @internal
+ * @category Wallet Providers
+ * @remarks
+ * Defines the interface for factories that create and manage {@link SmartWallet} instances
+ * Extended by implementations such as {@link DefaultSmartWalletProvider}
  */
-type GetSmartWalletWithEmbeddedSignerOptions = Omit<GetSmartWalletOptions, 'signer'> & GetEmbeddedWalletOptions;
+declare abstract class SmartWalletProvider$1 {
+    /**
+     * Creates a new smart wallet instance that will be deployed on first transaction
+     *
+     * @internal
+     * @category Creation
+     * @remarks
+     * Address is calculated deterministically using owners and nonce
+     *
+     * @param params Wallet creation parameters
+     * @param params.owners Array of wallet owners (addresses or WebAuthn accounts)
+     * @param params.signer Local account used for signing
+     * @param params.nonce Optional nonce for address derivation, default 0
+     * @returns Promise resolving to a {@link SmartWallet} instance
+     */
+    abstract createWallet(params: {
+        owners: Array<Address | WebAuthnAccount>;
+        signer: LocalAccount;
+        nonce?: bigint;
+    }): Promise<SmartWallet>;
+    /**
+     * Returns a smart wallet instance for an already deployed contract
+     *
+     * @internal
+     * @category Retrieval
+     * @remarks
+     * Use when the wallet address is already known
+     *
+     * @param params Wallet retrieval parameters
+     * @param params.walletAddress Deployed smart wallet address
+     * @param params.signer Local account to operate the wallet
+     * @param params.ownerIndex Optional index of signer in the owners list, default 0
+     * @returns A {@link SmartWallet} instance
+     */
+    abstract getWallet(params: {
+        walletAddress: Address;
+        signer: LocalAccount;
+        ownerIndex?: number;
+    }): SmartWallet;
+    /**
+     * Predicts the deterministic address of a smart wallet
+     *
+     * @internal
+     * @category Addressing
+     * @remarks
+     * Uses CREATE2 with owners and nonce to calculate the wallet address
+     *
+     * @param params Prediction parameters
+     * @param params.owners Array of wallet owners (addresses or WebAuthn accounts)
+     * @param params.nonce Optional nonce, default 0
+     * @returns Promise resolving to the predicted {@link Address}
+     */
+    abstract getWalletAddress(params: {
+        owners: Array<Address | WebAuthnAccount>;
+        nonce?: bigint;
+    }): Promise<Address>;
+}
 
 /**
  * Unified Wallet Provider class
@@ -821,9 +828,9 @@ declare class WalletProvider {
      * @param params.nonce Optional salt/nonce for deterministic address calculation (defaults to 0)
      * @returns Promise that resolves to the created {@link SmartWallet}
      */
-    createWalletWithEmbeddedSigner(params?: CreateWalletWithEmbeddedSignerOptions): Promise<SmartWallet>;
+    createAccount(params?: CreateAccountOptions): Promise<CreateAccountResult>;
     /**
-     * Gets a smart wallet using an embedded wallet as the signer
+     * Gets a unified web3 account: a smart wallet using an embedded wallet as the signer
      *
      * @internal
      * @remarks
@@ -840,7 +847,7 @@ declare class WalletProvider {
      * @returns Promise that resolves to the {@link SmartWallet}
      * @throws Error if the embedded wallet cannot be found
      */
-    getSmartWalletWithEmbeddedSigner(params: GetSmartWalletWithEmbeddedSignerOptions): Promise<SmartWallet>;
+    getAccount(params: GetAccountOptions): Promise<SmartWallet>;
     /**
      * Gets an existing embedded wallet by ID
      *
@@ -873,22 +880,27 @@ declare class WalletProvider {
 }
 
 /**
- * Public wallet namespace that exposes unified wallet operations
+ * Wallet namespace to create and retrieve different wallet formats and overall web3 account
  *
  * @public
- * @category Wallets creation and retrieval
+ * @category 2. Accounts creation and retrieval
  * @remarks
- * This class is returned by {@link MyceliumSDK} and provides a simplified
- * interface for wallet creation and retrieval. Advanced functionality can be accessed through
- * the underlying providers via the getters {@link embeddedWalletProvider} and
- * {@link smartWalletProvider}
+ * This class is returned by {@link MyceliumSDK} and provides a methods to create and retrieve different wallet formats
+ * The common methods are:
+ * - {@link createAccount} which creates a unified account: a smart wallet with an embedded wallet as signer
+ * - {@link getAccount} which retrieves a unified account: a smart wallet using an embedded walletId
+ * More advanced option are also available
  *
- * Typical flows:
- * - Create embedded wallet only: {@link createEmbeddedWallet}
- * - Create smart wallet only (you provide signer/owners): {@link createSmartWallet}
- * - Create smart wallet with embedded as signer: {@link createWalletWithEmbeddedSigner}
- * - Get smart wallet using embedded as signer: {@link getSmartWalletWithEmbeddedSigner}
- * - Get smart wallet using a provided signer: {@link getSmartWallet}
+ * @example
+ * ```ts
+ * // Create a smart wallet and related embedded wallet
+ * const { embeddedWalletId, smartWallet } = await myceliumSDK.wallet.createAccount();
+ *
+ * // Get the smart wallet using the embedded walletId
+ * const smartWallet = await myceliumSDK.wallet.getAccount({
+ *   embeddedWalletId,
+ * });
+ * ```
  */
 declare class WalletNamespace {
     /**
@@ -901,28 +913,6 @@ declare class WalletNamespace {
      * @param provider Unified provider that composes embedded & smart providers
      */
     constructor(provider: WalletProvider);
-    /**
-     * Direct access to the underlying embedded wallet provider
-     *
-     * @public
-     * @category Providers
-     * @remarks
-     * Useful when you need advanced functionality beyond the unified namespace. By default, you should use the unified namespace
-     *
-     * @returns The configured embedded wallet provider instance
-     */
-    get embeddedWalletProvider(): EmbeddedWalletProvider;
-    /**
-     * Direct access to the underlying smart wallet provider
-     *
-     * @public
-     * @category Providers
-     * @remarks
-     * Useful when you need advanced functionality beyond the unified namespace. By default, you should use the unified namespace
-     *
-     * @returns The configured smart wallet provider instance
-     */
-    get smartWalletProvider(): SmartWalletProvider$1;
     /**
      * Creates an embedded wallet
      *
@@ -951,7 +941,7 @@ declare class WalletNamespace {
      */
     createSmartWallet(params: CreateSmartWalletOptions): Promise<SmartWallet>;
     /**
-     * Creates a smart wallet with an embedded wallet as signer
+     * A unified a web3 account: creates a smart wallet with an embedded wallet as signer
      *
      * @public
      * @category Creation
@@ -965,9 +955,9 @@ declare class WalletNamespace {
      * @param params.nonce Optional nonce/salt for deterministic address generation (defaults to 0)
      * @returns Promise that resolves to the created {@link SmartWallet}
      */
-    createWalletWithEmbeddedSigner(params?: CreateWalletWithEmbeddedSignerOptions): Promise<SmartWallet>;
+    createAccount(params?: CreateAccountOptions): Promise<CreateAccountResult>;
     /**
-     * Gets a smart wallet using an embedded wallet as the signer
+     * Gets a unified web3 account: a smart wallet using an embedded wallet as the signer
      *
      * @public
      * @category Retrieval
@@ -985,7 +975,7 @@ declare class WalletNamespace {
      * @returns Promise that resolves to the {@link SmartWallet}
      * @throws Error if the embedded wallet cannot be found
      */
-    getSmartWalletWithEmbeddedSigner(params: GetSmartWalletWithEmbeddedSignerOptions): Promise<SmartWallet>;
+    getAccount(params: GetAccountOptions): Promise<SmartWallet>;
     /**
      * Gets an existing embedded wallet by ID
      *
@@ -1245,7 +1235,7 @@ declare class CoinbaseCDP {
  * Default ERC-4337 smart wallet implementation. Implements main methods that a user can use to interact with DeFi protocols and use all related functionalities
  *
  * @public
- * @category Wallets operations
+ * @category 3. Account operations
  * @remarks
  * Backed by Coinbase Smart Account and compatible with ERC-4337 UserOperations
  * Supports multi-owner wallets (EVM addresses or WebAuthn owners), gas-sponsored flows,
@@ -1379,7 +1369,7 @@ declare class DefaultSmartWallet extends SmartWallet {
      * Funds the smart wallet with the specified amount of the specified token via Coinbase CDP on-ramp service
      *
      * @public
-     * @category Ramp
+     * @category Funding
      *
      * @remarks
      * If Coinbase CDP is not initialized, the method will throw an error. For more details, visit @see {@link https://docs.cdp.coinbase.com/api-reference/v2/rest-api/onramp/create-an-onramp-session}
@@ -1400,7 +1390,7 @@ declare class DefaultSmartWallet extends SmartWallet {
      * Cashout token from smart wallet to fiat currency via Coinbase CDP off-ramp service
      *
      * @public
-     * @category Ramp
+     * @category Funding
      *
      * @remarks
      * If Coinbase CDP is not initialized, the method will throw an error. For more details, visit @see {@link https://docs.cdp.coinbase.com/api-reference/rest-api/onramp-offramp/create-sell-quote}
@@ -1431,11 +1421,59 @@ declare class DefaultSmartWallet extends SmartWallet {
     sendTokens(amount: number, asset: AssetIdentifier, recipientAddress: Address): Promise<TransactionData>;
 }
 
+/**
+ * Namespace to manage funding & payouts of an account
+ * @public
+ * @remarks
+ * Contains 2 methods to get available options to top up an account and cash out funds
+ * - {@link getTopUpConfig} to get available options to top up an account
+ * - {@link getCashOutConfig} to get available options to cash out funds
+ *
+ * @example
+ * ```ts
+ * const topUpConfig = await myceliumSDK.funding.getTopUpConfig();
+ * const cashOutConfig = await myceliumSDK.funding.getCashOutConfig();
+ * ```
+ * @category 4. Funding & payouts
+ */
+declare class FundingNamespace {
+    private readonly coinbaseCDP;
+    constructor(coinbaseCDP: CoinbaseCDP);
+    /**
+     * Return all supported countries and payment methods for on-ramp by Coinbase CDP
+     * @public
+     * @category Funding
+     *
+     * @returns @see {@link RampConfigResponse} with supported countries and payment methods for top-up
+     * @throws If API returned an error
+     */
+    getTopUpConfig(): Promise<RampConfigResponse>;
+    /**
+     * Return all supported countries and payment methods for off-ramp by Coinbase CDP
+     * @public
+     * @category Funding
+     *
+     *
+     * @returns @see {@link RampConfigResponse} with supported countries and payment methods for cash out
+     * @throws If API returned an error
+     */
+    getCashOutConfig(): Promise<RampConfigResponse>;
+}
+
+/**
+ * @packageDocumentation
+ * Entry point for the Mycelium SDK
+ *
+ * Exports stable types and the main SDK facade (`MyceliumSDK`)
+ * Internal base classes and implementations are not part of the public API
+ * and are hidden from public documentation
+ */
+
 /**
  * Main SDK facade for integrating wallets and protocols.
  *
  * @public
- * @category Get started
+ * @category 1. Getting started
  * @remarks
  * This class encapsulates:
  * - protocol selection and initialization (`Smart Router`),
@@ -1459,21 +1497,26 @@ declare class DefaultSmartWallet extends SmartWallet {
  *
  * const sdk = new MyceliumSDK(config);
  *
- * const embeddedWallet = await sdk.wallet.createEmbeddedWallet();
- * const wallet = await sdk.wallet.createSmartWallet({
- *     owners: [embeddedWallet.address],
- *     signer: await embeddedWallet.account(),
- * })
- * const balance = await wallet.getBalance();
+ * const {embeddedWalletId, smartWallet} = await sdk.wallet.createAccount();
+ * const balance = await smartWallet.getBalance();
  * ```
  */
 declare class MyceliumSDK {
     /**
-     * Unified wallet namespace to manage embedded/smart wallets and related operations
+     * Returns a unified wallet namespace to manage embedded/smart wallets and related operations
      * @public
      * @category Wallets
      */
     readonly wallet: WalletNamespace;
+    /**
+     * Ramp namespace to manage ramp operations. Methods are available on {@link RampNamespace}
+     * @internal
+     * @remarks
+     * If the Coinbase CDP configuration is not provided, the ramp functionality will be disabled.
+     * Calling the respective method will throw an error
+     * @category Tools
+     */
+    readonly fundingNamespace: FundingNamespace | null;
     /**
      * Chain manager instance to manage chain related entities
      * @internal
@@ -1507,37 +1550,23 @@ declare class MyceliumSDK {
     /**
      * Returns the chain manager instance for multi-chain operations
      * @public
+     * @remarks
+     * More about methods in {@link ChainManager}
      * @category Tools
      *
      * @returns ChainManager instance of the type {@link ChainManager}
      */
     get chainManager(): ChainManager;
     /**
-     * Coinbase CDP configuration methods for ramp operations
+     * Returns a funding namespace to manage top ups & cash outs configurations
      * @public
+     * @remarks
+     * More about methods in {@link FundingNamespace}
      * @category Tools
+     *
+     * @returns Funding namespace of the type {@link FundingNamespace}
      */
-    readonly rampConfig: {
-        /**
-         * Return all supported countries and payment methods for on-ramp by Coinbase CDP
-         * @public
-         * @category Ramp
-         *
-         * @returns @see {@link RampConfigResponse} with supported countries and payment methods for top-up
-         * @throws If API returned an error
-         */
-        getTopUpConfig: () => Promise<RampConfigResponse>;
-        /**
-         * Return all supported countries and payment methods for off-ramp by Coinbase CDP
-         * @public
-         * @category Ramp
-         *
-         *
-         * @returns @see {@link RampConfigResponse} with supported countries and payment methods for cash out
-         * @throws If API returned an error
-         */
-        getCashOutConfig: () => Promise<RampConfigResponse>;
-    };
+    get funding(): FundingNamespace;
     /**
      * Recommends and initializes a protocol based on router settings
      *
@@ -1565,4 +1594,4 @@ declare class MyceliumSDK {
     private createWalletNamespace;
 }
 
-export { type OffRampUrlResponse as CashOutUrlResponse, DefaultSmartWallet, EmbeddedWallet, MyceliumSDK, type MyceliumSDKConfig, type RampConfigResponse, 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, SmartWallet, type SparkVaultBalance, type SparkVaultTxnResult, type TokenBalance, type OnRampUrlResponse as TopUpUrlResponse, type VaultBalance, type VaultTxnResult, WalletNamespace };