@utexo/rgb-sdk 1.0.4 → 1.0.6

package/dist/index.d.mts

@@ -143,6 +143,27 @@ declare function deriveKeysFromMnemonic(bitcoinNetwork: string | number | undefi
  * Derive wallet keys directly from a BIP39 seed (hex string or Uint8Array)
  */
 declare function deriveKeysFromSeed(bitcoinNetwork: string | number | undefined, seed: string | Uint8Array): Promise<GeneratedKeys>;
+/**
+ * Derive wallet keys from either a mnemonic phrase or seed
+ * Automatically detects the input type and uses the appropriate derivation method
+ *
+ * @param bitcoinNetwork - Network string or number (default: 'regtest')
+ * @param mnemonicOrSeed - Either a BIP39 mnemonic phrase (string) or seed (Uint8Array | string)
+ * @returns Promise resolving to derived keys including mnemonic, xpubs, and master fingerprint
+ * @throws {ValidationError} If mnemonic is invalid
+ * @throws {CryptoError} If key derivation fails
+ *
+ * @example
+ * ```typescript
+ * // With mnemonic
+ * const keys1 = await deriveKeysFromMnemonicOrSeed('testnet', 'abandon abandon abandon...');
+ *
+ * // With seed (Uint8Array)
+ * const seed = new Uint8Array([...]);
+ * const keys2 = await deriveKeysFromMnemonicOrSeed('testnet', seed);
+ * ```
+ */
+declare function deriveKeysFromMnemonicOrSeed(bitcoinNetwork: string | number | undefined, mnemonicOrSeed: string | Uint8Array): Promise<GeneratedKeys>;
 /**
  * Restore wallet keys from existing mnemonic (backward compatibility alias)
  * @deprecated Use `deriveKeysFromMnemonic()` instead. This alias will be removed in a future version.
@@ -215,12 +236,28 @@ declare function getXpubFromXpriv(xpriv: string, bitcoinNetwork?: string | numbe
 declare function deriveKeysFromXpriv(bitcoinNetwork: string | number | undefined, xpriv: string): Promise<GeneratedKeys>;
 declare function accountXpubsFromMnemonic(bitcoinNetwork: string | number | undefined, mnemonic: string): Promise<AccountXpubs>;
 
-type RGBHTTPClientParams = {
-    xpubVan: string;
-    xpubCol: string;
-    masterFingerprint: string;
-    rgbEndpoint: string;
-};
+/**
+ * VSS (Versioned Storage Service) backup key derivation.
+ *
+ * Derives a 32-byte signing key from a BIP39 mnemonic for use with rgb-lib's
+ * VssBackupClient (server_url, store_id, signing_key). rgb-lib does not define
+ * mnemonic → signing_key; this SDK uses HMAC-SHA256 with the same domain string
+ * as rgb-lib's HKDF so backup/restore stay deterministic per wallet.
+ *
+ * Derivation: HMAC-SHA256(key = "rgb-lib-vss-backup-encryption-v1", message = mnemonic),
+ * output as 64-char hex (32 bytes).
+ */
+/**
+ * Derive the VSS backup signing key from a BIP39 mnemonic.
+ * The result is a 64-character hex string (32 bytes) suitable for
+ * VssBackupConfig.signingKey. Must match rgb-lib's Rust derivation.
+ *
+ * @param mnemonic - BIP39 mnemonic phrase (12 or 24 words)
+ * @returns 32-byte signing key as hex string (same mnemonic always yields same key for backup/restore)
+ */
+declare function deriveVssSigningKeyFromMnemonic(mnemonic: string): string;
+
+type BitcoinNetwork = 'mainnet' | 'testnet' | 'testnet4' | 'regtest' | 'signet';
 interface FailTransfersRequest {
     batchTransferIdx?: number;
     noAssetOnly?: boolean;
@@ -243,16 +280,54 @@ interface WitnessData {
     blinding?: number;
 }
 interface InvoiceRequest {
-    amount: number;
-    assetId: string;
+    amount?: number;
+    assetId?: string;
     minConfirmations?: number;
     durationSeconds?: number;
 }
-interface Recipient {
+type BatchRecipient = {
     recipientId: string;
-    witnessData?: WitnessData;
-    amount: number;
+    witnessData?: {
+        amountSat: string;
+        blinding?: number | null;
+    } | null;
+    assignment: {
+        Fungible: number;
+    };
     transportEndpoints: string[];
+};
+type RecipientMap = Record<string, BatchRecipient[]>;
+/**
+ * VSS backup mode: Async (fire-and-forget) or Blocking (wait for upload).
+ */
+type VssBackupMode = 'Async' | 'Blocking';
+/**
+ * VSS backup configuration for cloud backup.
+ *
+ * serverUrl, storeId and signingKey are required; other fields are optional
+ * and default to the underlying rgb-lib defaults when omitted:
+ * - encryptionEnabled: true
+ * - autoBackup: false
+ * - backupMode: 'Async'
+ */
+interface VssBackupConfig {
+    serverUrl: string;
+    storeId: string;
+    /**
+     * Signing key as a hex-encoded 32-byte secret key string.
+     */
+    signingKey: string;
+    encryptionEnabled?: boolean;
+    autoBackup?: boolean;
+    backupMode?: VssBackupMode;
+}
+/**
+ * Information about the current VSS backup status for a wallet.
+ */
+interface VssBackupInfo {
+    backupExists: boolean;
+    serverVersion?: number | null;
+    backupRequired: boolean;
 }
 interface IssueAssetNiaRequestModel {
     ticker: string;
@@ -267,13 +342,14 @@ interface IssueAssetIfaRequestModel {
     amounts: number[];
     inflationAmounts: number[];
     replaceRightsNum: number;
-    rejectListUrl?: string;
+    rejectListUrl: string | null;
 }
 interface SendAssetBeginRequestModel {
     invoice: string;
     witnessData?: WitnessData;
     assetId?: string;
     amount?: number;
+    donation?: boolean;
     feeRate?: number;
     minConfirmations?: number;
 }
@@ -318,16 +394,8 @@ interface SendBtcEndRequestModel {
     signedPsbt: string;
     skipSync?: boolean;
 }
-interface GetFeeEstimationRequestModel {
-    blocks: number;
-}
 type GetFeeEstimationResponse = Record<string, number> | number;
-declare enum TransactionType {
-    RGB_SEND = 0,
-    DRAIN = 1,
-    CREATE_UTXOS = 2,
-    USER = 3
-}
+type TransactionType = 'RgbSend' | 'Drain' | 'CreateUtxos' | 'User';
 interface BlockTime {
     height: number;
     timestamp: number;
@@ -340,59 +408,55 @@ interface Transaction {
     fee: number;
     confirmationTime?: BlockTime;
 }
-declare enum TransferKind {
-    ISSUANCE = 0,
-    RECEIVE_BLIND = 1,
-    RECEIVE_WITNESS = 2,
-    SEND = 3,
-    INFLATION = 4
-}
-interface RgbTransfer {
+type TransferKind = 'Issuance' | 'ReceiveBlind' | 'ReceiveWitness' | 'Send' | 'Inflation';
+type Outpoint = {
+    txid: string;
+    vout: number;
+};
+interface Transfer {
     idx: number;
     batchTransferIdx: number;
     createdAt: number;
     updatedAt: number;
     status: TransferStatus;
-    amount: number;
+    requestedAssignment?: Assignment;
+    assignments: Assignment[];
     kind: TransferKind;
-    txid: string | null;
-    recipientId: string;
-    receiveUtxo: {
-        txid: string;
-        vout: number;
-    };
-    changeUtxo: {
-        txid: string;
-        vout: number;
-    } | null;
-    expiration: number;
+    txid?: string;
+    recipientId?: string;
+    receiveUtxo?: Outpoint;
+    changeUtxo?: Outpoint;
+    expiration?: number;
     transportEndpoints: {
         endpoint: string;
-        transportType: number;
+        transportType: string;
         used: boolean;
     }[];
-}
-declare enum TransferStatus {
-    WAITING_COUNTERPARTY = 0,
-    WAITING_CONFIRMATIONS = 1,
-    SETTLED = 2,
-    FAILED = 3
-}
-interface Unspent {
-    utxo: Utxo;
-    rgbAllocations: RgbAllocation[];
-}
-interface Utxo {
+    invoiceString?: string;
+    consignmentPath?: string;
+}
+type TransferStatus = 'WaitingCounterparty' | 'WaitingConfirmations' | 'Settled' | 'Failed';
+/** Bridge transfer statuses (from UTEXO bridge API) */
+type BridgeTransferStatus = 'Unspecified' | 'Confirming' | 'Canceled' | 'Finished' | 'Waiting' | 'Cancelling' | 'Failed' | 'Fetching';
+/** Unified status for on-chain operations (from RGB wallet or bridge) */
+type OnchainSendStatus = TransferStatus | BridgeTransferStatus;
+interface Unspent$1 {
+    utxo: Utxo$1;
+    rgbAllocations: RgbAllocation$1[];
+    pendingBlinded: number;
+}
+interface Utxo$1 {
     outpoint: {
         txid: string;
         vout: number;
     };
     btcAmount: number;
     colorable: boolean;
+    exists: boolean;
 }
-interface RgbAllocation {
-    assetId: string;
-    amount: number;
+interface RgbAllocation$1 {
+    assetId?: string;
+    assignment: Assignment;
     settled: boolean;
 }
 interface Balance {
@@ -407,7 +471,7 @@ interface BtcBalance {
 interface InvoiceReceiveData {
     invoice: string;
     recipientId: string;
-    expirationTimestamp: number;
+    expirationTimestamp: number | null;
     batchTransferIdx: number;
 }
 interface AssetNIA {
@@ -416,7 +480,7 @@ interface AssetNIA {
      * @memberof AssetNIA
      * @example rgb:2dkSTbr-jFhznbPmo-TQafzswCN-av4gTsJjX-ttx6CNou5-M98k8Zd
      */
-    assetId?: string;
+    assetId: string;
     /**
      * @type {AssetIface}
      * @memberof AssetNIA
@@ -427,53 +491,54 @@ interface AssetNIA {
      * @memberof AssetNIA
      * @example USDT
      */
-    ticker?: string;
+    ticker: string;
     /**
      * @type {string}
      * @memberof AssetNIA
      * @example Tether
      */
-    name?: string;
+    name: string;
     /**
-     * @type {string}
+     * @type {string | null}
      * @memberof AssetNIA
-     * @example asset details
+     * @example asset details (API may return null)
      */
-    details?: string;
+    details?: string | null;
     /**
      * @type {number}
      * @memberof AssetNIA
      * @example 0
      */
-    precision?: number;
+    precision: number;
     /**
      * @type {number}
      * @memberof AssetNIA
      * @example 777
      */
-    issuedSupply?: number;
+    issuedSupply: number;
     /**
      * @type {number}
      * @memberof AssetNIA
      * @example 1691160565
      */
-    timestamp?: number;
+    timestamp: number;
     /**
      * @type {number}
      * @memberof AssetNIA
      * @example 1691161979
      */
-    addedAt?: number;
+    addedAt: number;
     /**
-     * @type {BtcBalance}
+     * @type {Balance}
      * @memberof AssetNIA
      */
-    balance?: BtcBalance;
+    balance: Balance;
     /**
-     * @type {Media}
+     * @type {Media | null}
      * @memberof AssetNIA
+     * @example API may return null
      */
-    media?: Media;
+    media?: Media | null;
 }
 interface AssetIfa {
     assetId: string;
@@ -514,86 +579,432 @@ declare enum AssetSchema {
     Uda = "Uda",
     Cfa = "Cfa"
 }
+type ListAssets = {
+    nia: AssetNIA[];
+    uda: AssetUDA[];
+    cfa: AssetCFA[];
+    ifa: AssetIfa[];
+};
+type AssetUDA = {
+    assetId: string;
+    ticker: string;
+    name: string;
+    details?: string;
+    precision: number;
+    timestamp: number;
+    addedAt: number;
+    balance: Balance;
+    token?: {
+        index: number;
+        ticker?: string;
+        name?: string;
+        details?: string;
+        embeddedMedia: boolean;
+        media?: Media;
+        attachments: Array<{
+            key: number;
+            filePath: string;
+            mime: string;
+            digest: string;
+        }>;
+        reserves: boolean;
+    };
+};
+type AssetCFA = {
+    assetId: string;
+    name: string;
+    details?: string;
+    precision: number;
+    issuedSupply: number;
+    timestamp: number;
+    addedAt: number;
+    balance: Balance;
+    media?: Media;
+};
 /**
  *
  *
  * @export
- * @interface ListAssetsResponse
- */
-interface ListAssetsResponse {
-    /**
-     * @type {Array<AssetNIA>}
-     * @memberof ListAssetsResponse
-     */
-    nia?: Array<AssetNIA>;
-    /**
-     * @type {Array<AssetNIA>}
-     * @memberof ListAssetsResponse
-     */
-    uda?: Array<AssetNIA>;
-    /**
-     * @type {Array<AssetNIA>}
-     * @memberof ListAssetsResponse
-     */
-    cfa?: Array<AssetNIA>;
-}
-interface IssueAssetNIAResponse {
-    /**
-     * @type {AssetNIA}
-     * @memberof IssueAssetNIAResponse
-     */
-    asset?: AssetNIA;
-}
-/**
- *
- *
- * @export
- * @interface AssetBalanceResponse
+ * @interface AssetBalance
  */
-interface AssetBalanceResponse {
+interface AssetBalance {
     /**
      * @type {number}
-     * @memberof AssetBalanceResponse
+     * @memberof AssetBalance
      * @example 777
      */
     settled?: number;
     /**
      * @type {number}
-     * @memberof AssetBalanceResponse
+     * @memberof AssetBalance
      * @example 777
      */
     future?: number;
     /**
      * @type {number}
-     * @memberof AssetBalanceResponse
+     * @memberof AssetBalance
      * @example 777
      */
     spendable?: number;
     /**
      * @type {number}
-     * @memberof AssetBalanceResponse
+     * @memberof AssetBalance
      * @example 444
      */
     offchainOutbound?: number;
     /**
      * @type {number}
-     * @memberof AssetBalanceResponse
+     * @memberof AssetBalance
      * @example 0
      */
     offchainInbound?: number;
 }
-interface DecodeRgbInvoiceResponse {
+interface InvoiceData {
+    invoice: string;
     recipientId: string;
-    assetSchema?: string;
+    assetSchema?: AssetSchema;
     assetId?: string;
-    network: string;
+    network: BitcoinNetwork;
     assignment: Assignment;
     assignmentName?: string;
-    expirationTimestamp?: number;
+    expirationTimestamp: number | null;
     transportEndpoints: string[];
 }
-interface Assignment {
-    [key: string]: any;
+type AssignmentType = 'Fungible' | 'NonFungible' | 'InflationRight' | 'ReplaceRight' | 'Any';
+type Assignment = {
+    type: AssignmentType;
+    amount?: number;
+};
+
+/**
+ * IWalletManager - Unified interface for WalletManager implementations
+ *
+ * This interface defines the contract that all WalletManager implementations must follow
+ * for cross-platform compatibility.
+ *
+ * All methods are async to support native module requirements.
+ * Synchronous implementations should wrap operations in Promise.resolve().
+ *
+ * Type Standards:
+ * - All enum-like types use PascalCase: 'RgbSend', 'WaitingCounterparty', 'Nia', etc.
+ * - Network identifiers use lowercase: 'mainnet', 'testnet', 'regtest', 'signet', 'testnet4'
+ * - Transaction types: 'RgbSend' | 'Drain' | 'CreateUtxos' | 'User'
+ * - Transfer status: 'WaitingCounterparty' | 'WaitingConfirmations' | 'Settled' | 'Failed'
+ * - Transfer kind: 'Issuance' | 'ReceiveBlind' | 'ReceiveWitness' | 'Send' | 'Inflation'
+ * - Asset schemas: 'Nia' | 'Uda' | 'Cfa' | 'Ifa'
+ * - Assignment types: 'Fungible' | 'NonFungible' | 'InflationRight' | 'ReplaceRight' | 'Any'
+ */
+
+/**
+ * Unified WalletManager interface for cross-platform compatibility
+ *
+ * This interface ensures all implementations provide the same API surface,
+ * allowing clients to switch between implementations based on environment.
+ */
+interface IWalletManager {
+    /**
+     * Initialize the wallet and establish online connection
+     * Must be called before performing operations that require network access.
+     *
+     * @returns Promise that resolves when initialization is complete
+     * @throws {WalletError} if initialization fails
+     *
+     * NOTE: Some implementations require this method to be called explicitly,
+     *       while others may initialize automatically in the constructor.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Connect the wallet to an online indexer service for syncing and transaction operations.
+     * Must be called before performing operations that require network connectivity.
+     *
+     * @param indexerUrl - The URL of the RGB indexer service to connect to
+     * @param skipConsistencyCheck - If true, skips the consistency check with the indexer (default: false)
+     * @returns Promise that resolves when the wallet is successfully connected online
+     * @throws {WalletError} if connection fails
+     */
+    goOnline(indexerUrl: string, skipConsistencyCheck?: boolean): Promise<void>;
+    /**
+     * Get wallet's extended public keys
+     * @returns Object containing vanilla and colored extended public keys
+     */
+    getXpub(): {
+        xpubVan: string;
+        xpubCol: string;
+    };
+    /**
+     * Get wallet's network
+     * @returns Network identifier
+     */
+    getNetwork(): Network;
+    /**
+     * Dispose of sensitive wallet data
+     * Clears mnemonic and seed from memory, closes connections
+     * Idempotent - safe to call multiple times
+     *
+     * @returns Promise that resolves when disposal is complete
+     */
+    dispose(): Promise<void>;
+    /**
+     * Check if wallet has been disposed
+     * @returns true if wallet has been disposed, false otherwise
+     */
+    isDisposed(): boolean;
+    /**
+     * Register wallet and get initial address and balance
+     * This is typically called once after wallet creation
+     *
+     * @returns Promise resolving to address and BTC balance
+     */
+    /**
+     * Get current BTC balance
+     * @returns Promise resolving to BTC balance information
+     */
+    getBtcBalance(): Promise<BtcBalance>;
+    /**
+     * Get wallet's receiving address
+     * @returns Promise resolving to Bitcoin address string
+     */
+    getAddress(): Promise<string>;
+    /**
+     * List all unspent transaction outputs (UTXOs)
+     * @returns Promise resolving to array of unspent outputs
+     */
+    listUnspents(): Promise<Unspent$1[]>;
+    /**
+     * Begin creating UTXOs (first step of two-step process)
+     * @param params - UTXO creation parameters
+     * @returns Promise resolving to base64-encoded PSBT that needs to be signed
+     */
+    createUtxosBegin(params: CreateUtxosBeginRequestModel): Promise<string>;
+    /**
+     * Complete UTXO creation (second step after signing)
+     * @param params - Signed PSBT from createUtxosBegin
+     * @returns Promise resolving to number of UTXOs created
+     */
+    createUtxosEnd(params: CreateUtxosEndRequestModel): Promise<number>;
+    /**
+     * Complete UTXO creation flow: begin → sign → end
+     * Convenience method that combines createUtxosBegin, signing, and createUtxosEnd
+     *
+     * @param params - UTXO creation parameters
+     * @returns Promise resolving to number of UTXOs created
+     */
+    createUtxos(params: {
+        upTo?: boolean;
+        num?: number;
+        size?: number;
+        feeRate?: number;
+    }): Promise<number>;
+    /**
+     * List all assets in the wallet
+     * Returns assets grouped by schema (NIA, UDA, CFA, IFA)
+     * @returns Promise resolving to assets information grouped by schema
+     */
+    listAssets(): Promise<ListAssets>;
+    /**
+     * Get balance for a specific asset
+     * @param asset_id - Asset identifier
+     * @returns Promise resolving to asset balance information
+     */
+    getAssetBalance(asset_id: string): Promise<AssetBalance>;
+    /**
+     * Issue a new NIA (Non-Inflatable Asset)
+     * @param params - Asset issuance parameters
+     * @returns Promise resolving to issued asset information
+     */
+    issueAssetNia(params: IssueAssetNiaRequestModel): Promise<AssetNIA>;
+    /**
+     * Issue a new IFA (Inflatable Fungible Asset)
+     * @param params - Asset issuance parameters
+     * @returns Promise resolving to issued asset information
+     */
+    issueAssetIfa(params: IssueAssetIfaRequestModel): Promise<any>;
+    /**
+     * Begin asset inflation (first step of two-step process)
+     * @param params - Inflation parameters
+     * @returns Promise resolving to base64-encoded PSBT that needs to be signed
+     */
+    inflateBegin(params: InflateAssetIfaRequestModel): Promise<string>;
+    /**
+     * Complete asset inflation (second step after signing)
+     * @param params - Signed PSBT from inflateBegin
+     * @returns Promise resolving to operation result
+     */
+    inflateEnd(params: InflateEndRequestModel): Promise<OperationResult>;
+    /**
+     * Complete inflation flow: begin → sign → end
+     * Convenience method that combines inflateBegin, signing, and inflateEnd
+     *
+     * @param params - Inflation parameters
+     * @param mnemonic - Optional mnemonic for signing (uses wallet's mnemonic if not provided)
+     * @returns Promise resolving to operation result
+     */
+    inflate(params: InflateAssetIfaRequestModel, mnemonic?: string): Promise<OperationResult>;
+    /**
+     * Begin sending assets (first step of two-step process)
+     * @param params - Send parameters including invoice
+     * @returns Promise resolving to base64-encoded PSBT that needs to be signed
+     */
+    sendBegin(params: SendAssetBeginRequestModel): Promise<string>;
+    /**
+     * Complete sending assets (second step after signing)
+     * @param params - Signed PSBT from sendBegin
+     * @returns Promise resolving to send result with txid
+     */
+    sendEnd(params: SendAssetEndRequestModel): Promise<SendResult>;
+    /**
+     * Complete send flow: begin → sign → end
+     * Convenience method that combines sendBegin, signing, and sendEnd
+     *
+     * @param invoiceTransfer - Send parameters including invoice
+     * @param mnemonic - Optional mnemonic for signing (uses wallet's mnemonic if not provided)
+     * @returns Promise resolving to send result with txid
+     */
+    send(invoiceTransfer: SendAssetBeginRequestModel, mnemonic?: string): Promise<SendResult>;
+    /**
+     * Begin sending BTC (first step of two-step process)
+     * @param params - Send BTC parameters
+     * @returns Promise resolving to base64-encoded PSBT that needs to be signed
+     */
+    sendBtcBegin(params: SendBtcBeginRequestModel): Promise<string>;
+    /**
+     * Complete sending BTC (second step after signing)
+     * @param params - Signed PSBT from sendBtcBegin
+     * @returns Promise resolving to transaction ID
+     */
+    sendBtcEnd(params: SendBtcEndRequestModel): Promise<string>;
+    /**
+     * Complete BTC send flow: begin → sign → end
+     * Convenience method that combines sendBtcBegin, signing, and sendBtcEnd
+     *
+     * @param params - Send BTC parameters
+     * @returns Promise resolving to transaction ID
+     */
+    sendBtc(params: SendBtcBeginRequestModel): Promise<string>;
+    /**
+     * Generate blind receive invoice
+     * Creates an invoice for receiving assets without revealing the amount
+     *
+     * @param params - Invoice generation parameters including assignment type
+     *                 Assignment types: 'Fungible' | 'NonFungible' | 'InflationRight' | 'ReplaceRight' | 'Any'
+     * @returns Promise resolving to invoice data including invoice string
+     */
+    blindReceive(params: InvoiceRequest): Promise<InvoiceReceiveData>;
+    /**
+     * Generate witness receive invoice
+     * Creates an invoice for receiving assets with amount visible
+     *
+     * @param params - Invoice generation parameters including assignment type
+     *                 Assignment types: 'Fungible' | 'NonFungible' | 'InflationRight' | 'ReplaceRight' | 'Any'
+     * @returns Promise resolving to invoice data including invoice string
+     */
+    witnessReceive(params: InvoiceRequest): Promise<InvoiceReceiveData>;
+    /**
+     * Decode RGB invoice
+     * Extracts information from an RGB invoice string
+     *
+     * @param params - Invoice string to decode
+     * @returns Promise resolving to decoded invoice data including recipientId, assetSchema, assignment, etc.
+     */
+    decodeRGBInvoice(params: {
+        invoice: string;
+    }): Promise<InvoiceData>;
+    /**
+     * List all transactions
+     * @returns Promise resolving to array of transactions
+     * Each transaction includes transactionType ('RgbSend' | 'Drain' | 'CreateUtxos' | 'User'),
+     * txid, received/sent amounts, fee, and optional confirmationTime
+     */
+    listTransactions(): Promise<Transaction[]>;
+    /**
+     * List transfers for a specific asset or all assets
+     * @param asset_id - Optional asset identifier (lists all if not provided)
+     * @returns Promise resolving to array of transfers
+     * Each transfer includes status ('WaitingCounterparty' | 'WaitingConfirmations' | 'Settled' | 'Failed'),
+     * kind ('Issuance' | 'ReceiveBlind' | 'ReceiveWitness' | 'Send' | 'Inflation'),
+     * assignments, and transport endpoints
+     */
+    listTransfers(asset_id?: string): Promise<Transfer[]>;
+    /**
+     * Mark transfers as failed
+     * @param params - Transfer failure parameters
+     * @returns Promise resolving to boolean indicating success
+     */
+    failTransfers(params: FailTransfersRequest): Promise<boolean>;
+    /**
+     * Refresh wallet state
+     * Syncs wallet with the network and updates internal state
+     *
+     * @returns Promise that resolves when refresh is complete
+     */
+    refreshWallet(): Promise<void>;
+    /**
+     * Sync wallet with network
+     * Performs a full synchronization with the indexer
+     *
+     * @returns Promise that resolves when sync is complete
+     */
+    syncWallet(): Promise<void>;
+    /**
+     * Configure VSS (Versioned Storage Service) cloud backup for this wallet.
+     * When configured with autoBackup enabled, the wallet will perform automatic
+     * backups after state-changing operations according to the underlying rgb-lib behavior.
+     */
+    configureVssBackup(config: VssBackupConfig): Promise<void>;
+    /**
+     * Disable automatic VSS backup for this wallet.
+     */
+    disableVssAutoBackup(): Promise<void>;
+    /**
+     * Trigger a VSS backup immediately and return the server version of the stored backup.
+     */
+    vssBackup(config: VssBackupConfig): Promise<number>;
+    /**
+     * Get VSS backup status information for this wallet.
+     */
+    vssBackupInfo(config: VssBackupConfig): Promise<VssBackupInfo>;
+    /**
+     * Estimate fee rate for a given number of blocks
+     * @param blocks - Number of blocks for fee estimation
+     * @returns Promise resolving to fee estimation response
+     */
+    estimateFeeRate(blocks: number): Promise<GetFeeEstimationResponse>;
+    /**
+     * Estimate fee for a specific PSBT
+     * @param psbtBase64 - Base64-encoded PSBT
+     * @returns Promise resolving to fee estimation result
+     */
+    estimateFee(psbtBase64: string): Promise<EstimateFeeResult>;
+    /**
+     * Create wallet backup
+     * @param params - Backup parameters including path and password
+     * @returns Promise resolving to backup response
+     */
+    createBackup(params: {
+        backupPath: string;
+        password: string;
+    }): Promise<WalletBackupResponse>;
+    /**
+     * Sign a PSBT using the wallet's mnemonic or a provided mnemonic
+     * @param psbt - Base64 encoded PSBT
+     * @param mnemonic - Optional mnemonic (uses wallet's mnemonic if not provided)
+     * @returns Promise resolving to signed PSBT (base64-encoded)
+     */
+    signPsbt(psbt: string, mnemonic?: string): Promise<string>;
+    /**
+     * Sign a message using Schnorr signature
+     * @param message - Message to sign
+     * @returns Promise resolving to signature string
+     */
+    signMessage(message: string): Promise<string>;
+    /**
+     * Verify a Schnorr message signature
+     * @param message - Original message
+     * @param signature - Signature to verify
+     * @param accountXpub - Optional account xpub (uses wallet's xpubVan if not provided)
+     * @returns Promise resolving to boolean indicating if signature is valid
+     */
+    verifyMessage(message: string, signature: string, accountXpub?: string): Promise<boolean>;
 }
 
 /**
@@ -645,7 +1056,7 @@ type WalletInitParams = {
  * const balance = await wallet.getBtcBalance();
  * ```
  */
-declare class WalletManager {
+declare class WalletManager implements IWalletManager {
     private readonly client;
     private readonly xpub;
     private readonly xpubVan;
@@ -657,6 +1068,8 @@ declare class WalletManager {
     private disposed;
     private readonly dataDir;
     constructor(params: WalletInitParams);
+    initialize(): Promise<void>;
+    goOnline(): Promise<void>;
     /**
      * Get wallet's extended public keys
      */
@@ -673,7 +1086,7 @@ declare class WalletManager {
      * Clears mnemonic and seed from memory
      * Idempotent - safe to call multiple times
      */
-    dispose(): void;
+    dispose(): Promise<void>;
     /**
      * Check if wallet has been disposed
      */
@@ -687,43 +1100,78 @@ declare class WalletManager {
         address: string;
         btcBalance: BtcBalance;
     };
-    getBtcBalance(): BtcBalance;
-    getAddress(): string;
-    listUnspents(): Unspent[];
-    listAssets(): ListAssetsResponse;
-    getAssetBalance(asset_id: string): AssetBalanceResponse;
-    createUtxosBegin(params: CreateUtxosBeginRequestModel): string;
-    createUtxosEnd(params: CreateUtxosEndRequestModel): number;
-    sendBegin(params: SendAssetBeginRequestModel): string;
-    sendEnd(params: SendAssetEndRequestModel): SendResult;
-    sendBtcBegin(params: SendBtcBeginRequestModel): string;
-    sendBtcEnd(params: SendBtcEndRequestModel): string;
-    estimateFeeRate(blocks: number): GetFeeEstimationResponse;
-    estimateFee(psbtBase64: string): Promise<EstimateFeeResult>;
-    sendBtc(params: SendBtcBeginRequestModel): Promise<string>;
-    blindReceive(params: InvoiceRequest): InvoiceReceiveData;
-    witnessReceive(params: InvoiceRequest): InvoiceReceiveData;
-    issueAssetNia(params: IssueAssetNiaRequestModel): AssetNIA;
-    issueAssetIfa(params: IssueAssetIfaRequestModel): AssetIfa;
-    inflateBegin(params: InflateAssetIfaRequestModel): string;
-    inflateEnd(params: InflateEndRequestModel): OperationResult;
+    getBtcBalance(): Promise<BtcBalance>;
+    getAddress(): Promise<string>;
+    listUnspents(): Promise<Unspent$1[]>;
+    listAssets(): Promise<ListAssets>;
+    getAssetBalance(asset_id: string): Promise<AssetBalance>;
+    createUtxosBegin(params: CreateUtxosBeginRequestModel): Promise<string>;
+    createUtxosEnd(params: CreateUtxosEndRequestModel): Promise<number>;
+    sendBegin(params: SendAssetBeginRequestModel): Promise<string>;
     /**
-     * Complete inflate operation: begin → sign → end
-     * @param params - Inflate parameters
-     * @param mnemonic - Optional mnemonic for signing
+     * Batch send begin: accepts already-built recipientMap.
+     * Returns unsigned PSBT (use signPsbt then sendEnd to complete).
      */
-    inflate(params: InflateAssetIfaRequestModel, mnemonic?: string): Promise<OperationResult>;
-    refreshWallet(): void;
-    listTransactions(): Transaction[];
-    listTransfers(asset_id?: string): RgbTransfer[];
-    failTransfers(params: FailTransfersRequest): boolean;
+    sendBeginBatch(params: {
+        recipientMap: RecipientMap;
+        feeRate?: number;
+        minConfirmations?: number;
+        donation?: boolean;
+    }): Promise<string>;
+    /**
+     * Complete batch send: sendBeginBatch → sign PSBT → sendEnd.
+     */
+    sendBatch(params: {
+        recipientMap: RecipientMap;
+        feeRate?: number;
+        minConfirmations?: number;
+        donation?: boolean;
+    }, mnemonic?: string): Promise<SendResult>;
+    sendEnd(params: SendAssetEndRequestModel): Promise<SendResult>;
+    sendBtcBegin(params: SendBtcBeginRequestModel): Promise<string>;
+    sendBtcEnd(params: SendBtcEndRequestModel): Promise<string>;
+    estimateFeeRate(blocks: number): Promise<GetFeeEstimationResponse>;
+    estimateFee(psbtBase64: string): Promise<EstimateFeeResult>;
+    sendBtc(params: SendBtcBeginRequestModel): Promise<string>;
+    blindReceive(params: InvoiceRequest): Promise<InvoiceReceiveData>;
+    witnessReceive(params: InvoiceRequest): Promise<InvoiceReceiveData>;
     decodeRGBInvoice(params: {
         invoice: string;
-    }): DecodeRgbInvoiceResponse;
+    }): Promise<InvoiceData>;
+    issueAssetNia(params: IssueAssetNiaRequestModel): Promise<AssetNIA>;
+    issueAssetIfa(params: IssueAssetIfaRequestModel): Promise<AssetIfa>;
+    inflateBegin(params: InflateAssetIfaRequestModel): Promise<string>;
+    inflateEnd(params: InflateEndRequestModel): Promise<OperationResult>;
+    /**
+     * Complete inflate operation: begin → sign → end
+     * @param params - Inflate parameters
+     * @param mnemonic - Optional mnemonic for signing
+     */
+    inflate(params: InflateAssetIfaRequestModel, mnemonic?: string): Promise<OperationResult>;
+    refreshWallet(): Promise<void>;
+    listTransactions(): Promise<Transaction[]>;
+    listTransfers(asset_id?: string): Promise<Transfer[]>;
+    failTransfers(params: FailTransfersRequest): Promise<boolean>;
     createBackup(params: {
         backupPath: string;
         password: string;
-    }): WalletBackupResponse;
+    }): Promise<WalletBackupResponse>;
+    /**
+     * Configure VSS cloud backup for this wallet.
+     */
+    configureVssBackup(config: VssBackupConfig): Promise<void>;
+    /**
+     * Disable automatic VSS backup.
+     */
+    disableVssAutoBackup(): Promise<void>;
+    /**
+     * Trigger a VSS backup immediately and return the server version.
+     */
+    vssBackup(config: VssBackupConfig): Promise<number>;
+    /**
+     * Get VSS backup info for this wallet.
+     */
+    vssBackupInfo(config: VssBackupConfig): Promise<VssBackupInfo>;
     /**
      * Sign a PSBT using the wallet's mnemonic or a provided mnemonic
      * @param psbt - Base64 encoded PSBT
@@ -736,13 +1184,13 @@ declare class WalletManager {
      * @param mnemonic - Optional mnemonic for signing
      */
     send(invoiceTransfer: SendAssetBeginRequestModel, mnemonic?: string): Promise<SendResult>;
-    createUtxos({ upTo, num, size, feeRate }: {
+    createUtxos({ upTo, num, size, feeRate, }: {
         upTo?: boolean;
         num?: number;
         size?: number;
         feeRate?: number;
     }): Promise<number>;
-    syncWallet(): void;
+    syncWallet(): Promise<void>;
     signMessage(message: string): Promise<string>;
     verifyMessage(message: string, signature: string, accountXpub?: string): Promise<boolean>;
 }
@@ -767,6 +1215,649 @@ declare class WalletManager {
 declare function createWalletManager(params: WalletInitParams): WalletManager;
 declare const wallet: WalletManager;
 
+/**
+ * UTEXO Protocol Types
+ */
+type PublicKeys = {
+    xpub: string;
+    accountXpubVanilla: string;
+    accountXpubColored: string;
+    masterFingerprint: string;
+};
+/**
+ * Lightning API Types
+ */
+interface LightningAsset {
+    /**
+     * @type {string}
+     * @memberof LightningAsset
+     */
+    assetId: string;
+    /**
+     * @type {number}
+     * @memberof LightningAsset
+     */
+    amount: number;
+}
+/**
+ * Request model for creating Lightning invoice.
+ *
+ * @export
+ * @interface CreateLightningInvoiceRequestModel
+ */
+interface CreateLightningInvoiceRequestModel {
+    /**
+     * @type {number}
+     * @memberof CreateLightningInvoiceRequestModel
+     */
+    amountSats?: number;
+    /**
+     * @type {LightningAsset}
+     * @memberof CreateLightningInvoiceRequestModel
+     */
+    asset: LightningAsset;
+    /**
+     * @type {number}
+     * @memberof CreateLightningInvoiceRequestModel
+     */
+    expirySeconds?: number;
+}
+interface LightningReceiveRequest {
+    lnInvoice: string;
+    expiresAt?: number;
+}
+interface LightningSendRequest extends SendResult {
+}
+interface GetLightningSendFeeEstimateRequestModel {
+    invoice: string;
+    assetId?: string;
+}
+interface PayLightningInvoiceRequestModel {
+    lnInvoice: string;
+    amount?: number;
+    assetId?: string;
+    maxFee?: number;
+}
+interface PayLightningInvoiceEndRequestModel {
+    signedPsbt: string;
+    lnInvoice: string;
+}
+/**
+ * Onchain API Types
+ */
+interface OnchainReceiveRequestModel extends InvoiceRequest {
+    amount: number;
+    assetId: string;
+}
+interface OnchainReceiveResponse {
+    /** Mainnet invoice */
+    invoice: string;
+}
+interface OnchainSendRequestModel {
+    /** Mainnet invoice */
+    invoice: string;
+    assetId?: string;
+    amount?: number;
+}
+interface OnchainSendEndRequestModel {
+    /** Mainnet invoice */
+    invoice: string;
+    signedPsbt: string;
+}
+interface OnchainSendResponse extends SendResult {
+}
+interface ListLightningPaymentsResponse {
+    payments: LightningSendRequest[];
+}
+
+/**
+ * UTEXO Protocol Interfaces
+ *
+ * These interfaces define the contract for UTEXO-specific operations.
+ * They are separated by concern (Lightning vs Onchain) and combined into IUTEXOProtocol.
+ */
+
+/**
+ * Lightning Protocol Interface
+ *
+ * Defines methods for Lightning Network operations including
+ * invoice creation, payments, and fee estimation.
+ */
+interface ILightningProtocol {
+    /**
+     * Creates a Lightning invoice for receiving BTC or asset payments.
+     *
+     * @param params - Request parameters for creating the Lightning invoice
+     * @returns Promise resolving to Lightning invoice response
+     */
+    createLightningInvoice(params: CreateLightningInvoiceRequestModel): Promise<LightningReceiveRequest>;
+    /**
+     * Returns the status of a Lightning invoice created with createLightningInvoice.
+     * Supports both BTC and asset invoices.
+     *
+     * @param id - The request ID of the Lightning invoice
+     * @returns Promise resolving to Lightning invoice response or null if not found
+     */
+    getLightningReceiveRequest(id: string): Promise<TransferStatus | null>;
+    /**
+     * Returns the current status of a Lightning payment initiated with payLightningInvoice.
+     * Works for both BTC and asset payments.
+     *
+     * @param id - The request ID of the Lightning send request
+     * @returns Promise resolving to Lightning send request response or null if not found
+     */
+    getLightningSendRequest(id: string): Promise<TransferStatus | null>;
+    /**
+     * Estimates the routing fee required to pay a Lightning invoice.
+     * For asset payments, the returned fee is always denominated in satoshis.
+     *
+     * @param params - Request parameters containing the invoice and optional asset
+     * @returns Promise resolving to estimated fee in satoshis
+     */
+    getLightningSendFeeEstimate(params: GetLightningSendFeeEstimateRequestModel): Promise<number>;
+    /**
+     * Begins a Lightning invoice payment process.
+     * Returns the invoice string as a mock PSBT (later will be constructed base64 PSBT).
+     *
+     * @param params - Request parameters containing the invoice and max fee
+     * @returns Promise resolving to PSBT string (currently returns invoice, later will be base64 PSBT)
+     */
+    payLightningInvoiceBegin(params: PayLightningInvoiceRequestModel): Promise<string>;
+    /**
+     * Completes a Lightning invoice payment using signed PSBT.
+     * Works the same as pay-invoice but uses signed_psbt instead of invoice.
+     *
+     * @param params - Request parameters containing the signed PSBT
+     * @returns Promise resolving to Lightning send request response
+     */
+    payLightningInvoiceEnd(params: SendAssetEndRequestModel): Promise<LightningSendRequest>;
+    /**
+     * Pays a Lightning invoice using the UTEXOWallet.
+     * This method supports BTC Lightning payments and asset-based Lightning payments.
+     *
+     * This is a convenience method that combines:
+     * 1. payLightningInvoiceBegin - to get the PSBT
+     * 2. signPsbt - to sign the PSBT (mock for now)
+     * 3. payLightningInvoiceEnd - to complete the payment
+     *
+     * @param params - Request parameters containing the invoice and max fee
+     * @param mnemonic - Optional mnemonic for signing (uses wallet's mnemonic if not provided)
+     * @returns Promise resolving to Lightning send request response
+     */
+    payLightningInvoice(params: PayLightningInvoiceRequestModel, mnemonic?: string): Promise<LightningSendRequest>;
+    /**
+     * Lists Lightning payments.
+     *
+     * @returns Promise resolving to response containing array of Lightning payments
+     */
+    listLightningPayments(): Promise<ListLightningPaymentsResponse>;
+}
+/**
+ * Onchain Protocol Interface
+ *
+ * Defines methods for on-chain withdrawal operations from UTEXO layer.
+ */
+interface IOnchainProtocol {
+    /**
+     * Begins an on-chain send process from UTEXO.
+     * Returns the request encoded as base64 (mock PSBT).
+     * Later this should construct and return a real base64 PSBT.
+     *
+     * @param params - Request parameters for on-chain send
+     * @returns Promise resolving to PSBT string (currently returns encoded request, later will be base64 PSBT)
+     */
+    onchainSendBegin(params: OnchainSendRequestModel): Promise<string>;
+    /**
+     * Completes an on-chain send from UTEXO using signed PSBT.
+     *
+     * @param params - Request parameters containing the signed PSBT
+     * @returns Promise resolving to on-chain send response
+     */
+    onchainSendEnd(params: SendAssetEndRequestModel): Promise<OnchainSendResponse>;
+    /**
+     * Sends BTC or assets on-chain from the UTEXO layer.
+     * This operation creates a Bitcoin transaction that releases funds from UTEXO to a specified on-chain address.
+     *
+     * This is a convenience method that combines:
+     * 1. onchainSendBegin - to get the PSBT
+     * 2. signPsbt - to sign the PSBT (mock for now)
+     * 3. onchainSendEnd - to complete the on-chain send
+     *
+     * @param params - Request parameters for on-chain send
+     * @param mnemonic - Optional mnemonic for signing (uses wallet's mnemonic if not provided)
+     * @returns Promise resolving to on-chain send response
+     */
+    onchainSend(params: OnchainSendRequestModel, mnemonic?: string): Promise<OnchainSendResponse>;
+    /**
+     * Gets the status of an on-chain send by send ID.
+     *
+     * @param send_id - The on-chain send ID
+     * @returns Promise resolving to on-chain send status response
+     */
+    getOnchainSendStatus(send_id: string): Promise<OnchainSendStatus | null>;
+    /**
+     * Lists on-chain transfers for a specific asset.
+     *
+     * @param asset_id - The asset ID to list transfers for
+     * @returns Promise resolving to array of on-chain transfers
+     */
+    listOnchainTransfers(asset_id?: string): Promise<Transfer[]>;
+}
+/**
+ * UTEXO Protocol Interface
+ *
+ * Combines Lightning and Onchain protocol interfaces.
+ * This is the main interface that UTEXOWallet implements.
+ */
+interface IUTEXOProtocol extends ILightningProtocol, IOnchainProtocol {
+}
+
+/**
+ * UTEXO Protocol Base Implementations
+ *
+ * These classes provide empty implementations for UTEXO-specific operations.
+ * They should be extended or used as mixins for concrete implementations.
+ */
+
+/**
+ * Lightning Protocol Base Class
+ *
+ * Provides empty implementations for all Lightning protocol methods.
+ * Concrete implementations should override these methods.
+ */
+declare class LightningProtocol implements ILightningProtocol {
+    createLightningInvoice(_params: CreateLightningInvoiceRequestModel): Promise<LightningReceiveRequest>;
+    getLightningReceiveRequest(_id: string): Promise<TransferStatus | null>;
+    getLightningSendRequest(_id: string): Promise<TransferStatus | null>;
+    getLightningSendFeeEstimate(_params: GetLightningSendFeeEstimateRequestModel): Promise<number>;
+    payLightningInvoiceBegin(_params: PayLightningInvoiceRequestModel): Promise<string>;
+    payLightningInvoiceEnd(_params: SendAssetEndRequestModel): Promise<LightningSendRequest>;
+    payLightningInvoice(_params: PayLightningInvoiceRequestModel, _mnemonic?: string): Promise<LightningSendRequest>;
+    listLightningPayments(): Promise<ListLightningPaymentsResponse>;
+}
+/**
+ * Onchain Protocol Base Class
+ *
+ * Provides empty implementations for all onchain protocol methods.
+ * Concrete implementations should override these methods.
+ */
+declare class OnchainProtocol implements IOnchainProtocol {
+    onchainReceive(_params: OnchainReceiveRequestModel): Promise<OnchainReceiveResponse>;
+    onchainSendBegin(_params: OnchainSendRequestModel): Promise<string>;
+    onchainSendEnd(_params: SendAssetEndRequestModel): Promise<OnchainSendResponse>;
+    onchainSend(_params: OnchainSendRequestModel, _mnemonic?: string): Promise<OnchainSendResponse>;
+    getOnchainSendStatus(_send_id: string): Promise<OnchainSendStatus | null>;
+    listOnchainTransfers(_asset_id?: string): Promise<Transfer[]>;
+}
+/**
+ * UTEXO Protocol Base Class
+ *
+ * Combines Lightning and Onchain protocol implementations.
+ * Provides empty implementations for all UTEXO protocol methods.
+ * Concrete implementations should override these methods.
+ */
+declare class UTEXOProtocol extends LightningProtocol implements IUTEXOProtocol {
+    private onchainProtocol;
+    onchainReceive(params: OnchainReceiveRequestModel): Promise<OnchainReceiveResponse>;
+    onchainSendBegin(params: OnchainSendRequestModel): Promise<string>;
+    onchainSendEnd(params: SendAssetEndRequestModel): Promise<OnchainSendResponse>;
+    onchainSend(params: OnchainSendRequestModel, mnemonic?: string): Promise<OnchainSendResponse>;
+    getOnchainSendStatus(send_id: string): Promise<OnchainSendStatus | null>;
+    listOnchainTransfers(asset_id?: string): Promise<Transfer[]>;
+}
+
+/**
+ * UTEXO network and asset mapping
+ */
+
+/**
+ * Network preset type - determines which configuration bundle to use
+ */
+type UtxoNetworkPreset = 'mainnet' | 'testnet';
+/**
+ * Network map configuration - maps logical network names to Bitcoin network types
+ */
+type UtxoNetworkMap = {
+    mainnet: Network;
+    utexo: Network;
+};
+/**
+ * Network configuration for a single network (RGB, RGB Lightning, or UTEXO)
+ */
+type NetworkConfig = {
+    networkName: string;
+    networkId: number;
+    assets: {
+        assetId: string;
+        tokenName: string;
+        longName: string;
+        precision: number;
+        tokenId: number;
+    }[];
+};
+/**
+ * Network ID map configuration - contains all network configs with asset lookup
+ */
+type UtxoNetworkIdMap = {
+    mainnet: NetworkConfig & {
+        getAssetById(tokenId: number): NetworkConfig['assets'][number] | undefined;
+    };
+    mainnetLightning: NetworkConfig & {
+        getAssetById(tokenId: number): NetworkConfig['assets'][number] | undefined;
+    };
+    utexo: NetworkConfig & {
+        getAssetById(tokenId: number): NetworkConfig['assets'][number] | undefined;
+    };
+};
+/**
+ * Complete network preset configuration bundle
+ */
+type UtxoNetworkPresetConfig = {
+    networkMap: UtxoNetworkMap;
+    networkIdMap: UtxoNetworkIdMap;
+};
+/**
+ * Gets the network configuration for a given preset
+ * @param preset - Network preset ('mainnet' or 'testnet')
+ * @returns Network preset configuration bundle
+ */
+declare function getUtxoNetworkConfig(preset: UtxoNetworkPreset): UtxoNetworkPresetConfig;
+/**
+ * Backward compatibility: Export testnet preset as default (current behavior)
+ * @deprecated Use getUtxoNetworkConfig('testnet') or getUtxoNetworkConfig('mainnet') instead
+ */
+declare const utexoNetworkMap: UtxoNetworkMap;
+/**
+ * Backward compatibility: Export testnet preset as default (current behavior)
+ * @deprecated Use getUtxoNetworkConfig('testnet') or getUtxoNetworkConfig('mainnet') instead
+ */
+declare const utexoNetworkIdMap: UtxoNetworkIdMap;
+type NetworkAsset = (typeof utexoNetworkIdMap)[keyof typeof utexoNetworkIdMap]['assets'][number];
+type UtxoNetworkId = keyof typeof utexoNetworkIdMap;
+/**
+ * Resolves the destination network's asset object from sender network, destination network, and sender asset ID.
+ * Uses tokenId as the cross-network identifier (same tokenId = same logical asset).
+ *
+ * @param networkIdMap - Optional. When provided (e.g. from wallet's preset), uses this config. Otherwise uses deprecated testnet preset.
+ */
+declare function getDestinationAsset(senderNetwork: UtxoNetworkId, destinationNetwork: UtxoNetworkId, assetIdSender: string | null, networkIdMap?: UtxoNetworkIdMap): NetworkAsset | undefined;
+
+/**
+ * UTEXOWallet constructor and runtime options.
+ */
+
+/**
+ * Options for UTEXOWallet. When omitted, defaults apply (e.g. DEFAULT_VSS_SERVER_URL for VSS).
+ */
+interface ConfigOptions {
+    /**
+     * Network preset: 'mainnet' (production) or 'testnet' (development).
+     * Default: 'mainnet'.
+     */
+    network?: UtxoNetworkPreset;
+    /**
+     * Optional base directory for wallet data. When set, each wallet uses a subdir by network + fingerprint:
+     * utexoRGBWallet → dataDir/{networkMap.utexo}/{masterFingerprint} (e.g. ./utexo/signet/3780bc30)
+     * layer1RGBWallet → dataDir/{networkMap.mainnet}/{masterFingerprint} (e.g. ./utexo/testnet/3780bc30)
+     * Same structure is used by restoreUtxoWalletFromVss so restored data can be loaded with this dataDir.
+     */
+    dataDir?: string;
+    /**
+     * Optional VSS server URL. When omitted, DEFAULT_VSS_SERVER_URL is used.
+     * vssBackup() / vssBackupInfo() build config from mnemonic + this URL when config is not passed.
+     */
+    vssServerUrl?: string;
+}
+
+/**
+ * UTEXOWallet - Wallet class for UTEXO operations
+ *
+ * This class provides a wallet interface that accepts either a mnemonic or seed
+ * for initialization. It implements both IWalletManager (standard RGB operations)
+ * and IUTEXOProtocol (UTEXO-specific Lightning and on-chain operations).
+ */
+
+/**
+ * UTEXOWallet - Combines standard RGB wallet operations with UTEXO protocol features
+ *
+ * Architecture:
+ * - Implements IWalletManager for standard RGB operations (via WalletManager delegation)
+ * - Implements IUTEXOProtocol for UTEXO-specific operations (Lightning, on-chain sends)
+ * - Manages two WalletManager instances: layer1 (Bitcoin) and utexo (UTEXO network)
+ */
+declare class UTEXOWallet extends UTEXOProtocol implements IWalletManager, IUTEXOProtocol {
+    private readonly mnemonicOrSeed;
+    private readonly options;
+    private readonly networkMap;
+    private readonly networkIdMap;
+    private readonly bridge;
+    private layer1Keys;
+    private utexoKeys;
+    private layer1RGBWallet;
+    private utexoRGBWallet;
+    /**
+     * Creates a new UTEXOWallet instance
+     * @param mnemonicOrSeed - Either a mnemonic phrase (string) or seed (Uint8Array)
+     * @param options - Optional configuration options (defaults to { network: 'mainnet' })
+     */
+    constructor(mnemonicOrSeed: string | Uint8Array, options?: ConfigOptions);
+    initialize(): Promise<void>;
+    /**
+     * Derive public keys from mnemonic or seed
+     * @param network - BitcoinNetwork identifier
+     * @returns Promise resolving to PublicKeys containing xpub, accountXpubVanilla, accountXpubColored, and masterFingerprint
+     * @throws {ValidationError} If mnemonic is invalid
+     */
+    derivePublicKeys(network: BitcoinNetwork): Promise<PublicKeys>;
+    getPubKeys(): Promise<PublicKeys>;
+    /**
+     * Guard method to ensure wallet is initialized
+     * @throws {WalletError} if wallet is not initialized
+     */
+    private ensureInitialized;
+    goOnline(): Promise<void>;
+    getXpub(): {
+        xpubVan: string;
+        xpubCol: string;
+    };
+    getNetwork(): Network;
+    dispose(): Promise<void>;
+    isDisposed(): boolean;
+    getBtcBalance(): Promise<BtcBalance>;
+    getAddress(): Promise<string>;
+    listUnspents(): Promise<Unspent$1[]>;
+    createUtxosBegin(params: CreateUtxosBeginRequestModel): Promise<string>;
+    createUtxosEnd(params: CreateUtxosEndRequestModel): Promise<number>;
+    createUtxos(params: {
+        upTo?: boolean;
+        num?: number;
+        size?: number;
+        feeRate?: number;
+    }): Promise<number>;
+    listAssets(): Promise<ListAssets>;
+    getAssetBalance(asset_id: string): Promise<AssetBalance>;
+    issueAssetNia(params: IssueAssetNiaRequestModel): Promise<AssetNIA>;
+    issueAssetIfa(params: IssueAssetIfaRequestModel): Promise<any>;
+    inflateBegin(params: InflateAssetIfaRequestModel): Promise<string>;
+    inflateEnd(params: InflateEndRequestModel): Promise<OperationResult>;
+    inflate(params: InflateAssetIfaRequestModel, mnemonic?: string): Promise<OperationResult>;
+    sendBegin(params: SendAssetBeginRequestModel): Promise<string>;
+    sendEnd(params: SendAssetEndRequestModel): Promise<SendResult>;
+    send(invoiceTransfer: SendAssetBeginRequestModel, mnemonic?: string): Promise<SendResult>;
+    sendBtcBegin(params: SendBtcBeginRequestModel): Promise<string>;
+    sendBtcEnd(params: SendBtcEndRequestModel): Promise<string>;
+    sendBtc(params: SendBtcBeginRequestModel): Promise<string>;
+    blindReceive(params: InvoiceRequest): Promise<InvoiceReceiveData>;
+    witnessReceive(params: InvoiceRequest): Promise<InvoiceReceiveData>;
+    decodeRGBInvoice(params: {
+        invoice: string;
+    }): Promise<InvoiceData>;
+    listTransactions(): Promise<Transaction[]>;
+    listTransfers(asset_id?: string): Promise<Transfer[]>;
+    failTransfers(params: FailTransfersRequest): Promise<boolean>;
+    refreshWallet(): Promise<void>;
+    syncWallet(): Promise<void>;
+    estimateFeeRate(blocks: number): Promise<GetFeeEstimationResponse>;
+    estimateFee(psbtBase64: string): Promise<EstimateFeeResult>;
+    /**
+     * Create backup for both layer1 and utexo stores in one folder.
+     * Writes backupPath/wallet_{masterFingerprint}_layer1.backup and backupPath/wallet_{masterFingerprint}_utexo.backup
+     * (same naming convention as VSS: storeId_layer1, storeId_utexo with storeId = wallet_<fp>).
+     * Use restoreUtxoWalletFromBackup with the same backupPath to restore both.
+     */
+    createBackup(params: {
+        backupPath: string;
+        password: string;
+    }): Promise<WalletBackupResponse & {
+        layer1BackupPath: string;
+        utexoBackupPath: string;
+    }>;
+    configureVssBackup(config: VssBackupConfig): Promise<void>;
+    disableVssAutoBackup(): Promise<void>;
+    /**
+     * Run VSS backup for both layer1 and utexo stores.
+     * Config is optional: when omitted, builds config from mnemonic (option param or wallet mnemonic)
+     * and options.vssServerUrl (or DEFAULT_VSS_SERVER_URL if not set).
+     *
+     * @param config - Optional; when omitted, built from mnemonic and vssServerUrl
+     * @param mnemonic - Optional; when omitted, uses wallet mnemonic (only if wallet was created with mnemonic string)
+     */
+    vssBackup(config?: VssBackupConfig, mnemonic?: string): Promise<number>;
+    /**
+     * Get VSS backup info. Config is optional; when omitted, built from mnemonic (param or wallet)
+     * and options.vssServerUrl (or DEFAULT_VSS_SERVER_URL if not set).
+     */
+    vssBackupInfo(config?: VssBackupConfig, mnemonic?: string): Promise<VssBackupInfo>;
+    signPsbt(psbt: string, mnemonic?: string): Promise<string>;
+    signMessage(message: string): Promise<string>;
+    verifyMessage(message: string, signature: string, accountXpub?: string): Promise<boolean>;
+    /**
+     * Validates that the wallet has sufficient spendable balance for the given asset and amount.
+     * @param assetId - Asset ID to check balance for
+     * @param amount - Required amount (in asset units)
+     * @throws {ValidationError} If balance is not found or insufficient
+     */
+    validateBalance(assetId: string, amount: number): Promise<void>;
+    /**
+     * Extracts invoice data and destination asset from a bridge transfer.
+     *
+     * @param bridgeTransfer - Bridge transfer response containing recipient invoice and token info
+     * @returns Object containing invoice string, decoded invoice data, and destination asset
+     * @throws {ValidationError} If destination asset is not supported
+     */
+    private extractInvoiceAndAsset;
+    /**
+     * IUTEXOProtocol Implementation
+     */
+    onchainReceive(params: OnchainReceiveRequestModel): Promise<OnchainReceiveResponse>;
+    onchainSendBegin(params: OnchainSendRequestModel): Promise<string>;
+    onchainSendEnd(params: OnchainSendEndRequestModel): Promise<OnchainSendResponse>;
+    onchainSend(params: OnchainSendRequestModel, mnemonic?: string): Promise<OnchainSendResponse>;
+    getOnchainSendStatus(invoice: string): Promise<OnchainSendStatus | null>;
+    listOnchainTransfers(asset_id?: string): Promise<Transfer[]>;
+    createLightningInvoice(params: CreateLightningInvoiceRequestModel): Promise<LightningReceiveRequest>;
+    payLightningInvoiceBegin(params: PayLightningInvoiceRequestModel): Promise<string>;
+    payLightningInvoiceEnd(params: PayLightningInvoiceEndRequestModel): Promise<SendResult>;
+    payLightningInvoice(params: PayLightningInvoiceRequestModel, mnemonic?: string): Promise<LightningSendRequest>;
+    getLightningSendRequest(lnInvoice: string): Promise<TransferStatus | null>;
+    getLightningReceiveRequest(lnInvoice: string): Promise<TransferStatus | null>;
+    private UTEXOToMainnetRGB;
+    private UtexoToMainnetLightning;
+}
+
+/**
+ * VSS (Versioned Storage Service) configuration defaults and helpers for UTEXO wallet backup/restore.
+ */
+
+/** Default VSS server URL used when vssServerUrl is not set in config or restore params. */
+declare const DEFAULT_VSS_SERVER_URL = "https://vss-server.utexo.com/vss";
+
+/**
+ * UTEXO wallet restore: VSS and file backup restore helpers.
+ */
+
+/**
+ * Restore a UTEXOWallet from VSS by restoring both layer1 and utexo stores.
+ * Mnemonic is required; config is optional (built from mnemonic when omitted; vssServerUrl uses DEFAULT_VSS_SERVER_URL if omitted).
+ * Uses the same storeId suffix convention as UTEXOWallet VSS backup (storeId_layer1, storeId_utexo).
+ * Restored data is written to targetDir/{layer1Network}/{masterFingerprint} and
+ * targetDir/{utexoNetwork}/{masterFingerprint} (same layout as when using dataDir on UTEXOWallet).
+ */
+declare function restoreUtxoWalletFromVss(params: {
+    mnemonic: string;
+    targetDir: string;
+    /** Optional; when omitted, config is built from mnemonic (vssServerUrl defaults to DEFAULT_VSS_SERVER_URL). */
+    config?: VssBackupConfig;
+    /** Preset to derive layer1/utexo network names; defaults to 'testnet'. */
+    networkPreset?: UtxoNetworkPreset;
+    /** Optional; when omitted and config not passed, DEFAULT_VSS_SERVER_URL is used. */
+    vssServerUrl?: string;
+}): Promise<{
+    layer1Path: string;
+    utexoPath: string;
+    targetDir: string;
+}>;
+/**
+ * Restore a UTEXOWallet from a regular (file) backup created by UTEXOWallet.createBackup.
+ * Expects one folder with wallet_<masterFingerprint>_layer1.backup and wallet_<masterFingerprint>_utexo.backup
+ * (same naming convention as VSS: storeId_layer1, storeId_utexo with storeId = wallet_<fp>).
+ * Restores into targetDir (same layout as VSS restore).
+ */
+declare function restoreUtxoWalletFromBackup(params: {
+    backupPath: string;
+    password: string;
+    targetDir: string;
+    networkPreset?: UtxoNetworkPreset;
+}): {
+    layer1Path: string;
+    utexoPath: string;
+    targetDir: string;
+};
+
+interface Unspent {
+    utxo: Utxo;
+    rgbAllocations: RgbAllocation[];
+}
+interface Utxo {
+    outpoint: {
+        txid: string;
+        vout: number;
+    };
+    btcAmount: number;
+    colorable: boolean;
+    exists: boolean;
+    pendingBlinded: number;
+}
+interface RgbAllocation {
+    assetId: string;
+    assignment: BindingAssignment;
+    settled: boolean;
+}
+interface DecodeRgbInvoiceResponse {
+    recipientId: string;
+    assetSchema?: string;
+    assetId?: string;
+    network: string;
+    assignment: BindingAssignment;
+    assignmentName?: string;
+    expirationTimestamp?: number;
+    transportEndpoints: string[];
+}
+interface BindingAssignment {
+    [key: string]: number;
+}
+
+/**
+ * Restore a wallet from a VSS backup into a target directory.
+ * Returns a message indicating the restored wallet path.
+ */
+declare const restoreFromVss: (params: {
+    config: VssBackupConfig;
+    targetDir: string;
+}) => WalletRestoreResponse & {
+    walletPath: string;
+};
+
 /**
  * Custom error classes for the RGB SDK
  */
@@ -819,7 +1910,7 @@ declare class CryptoError extends SDKError {
  * Configuration errors (missing or invalid configuration)
  */
 declare class ConfigurationError extends SDKError {
-    constructor(message: string, field?: string);
+    constructor(message: string, _field?: string);
 }
 /**
  * Bad request errors (400) - Invalid request parameters or data
@@ -927,6 +2018,7 @@ declare const KEYCHAIN_BTC = 0;
 /**
  * Network-related constants
  */
+
 /**
  * Coin type constants
  */
@@ -995,4 +2087,4 @@ declare const DEFAULT_MAX_RETRIES = 3;
  */
 declare const DEFAULT_LOG_LEVEL = 3;
 
-export { type AccountXpubs, type AssetBalanceResponse, type AssetIfa, AssetIface, type AssetNIA, AssetSchema, type Assignment, BIP32_VERSIONS, BadRequestError, type Balance, type BlockTime, type BtcBalance, COIN_BITCOIN_MAINNET, COIN_BITCOIN_TESTNET, COIN_RGB_MAINNET, COIN_RGB_TESTNET, ConfigurationError, ConflictError, type CreateUtxosBeginRequestModel, type CreateUtxosEndRequestModel, CryptoError, DEFAULT_API_TIMEOUT, DEFAULT_LOG_LEVEL, DEFAULT_MAX_RETRIES, DEFAULT_NETWORK, DERIVATION_ACCOUNT, DERIVATION_PURPOSE, type DecodeRgbInvoiceResponse, type Descriptors, type Environment, type FailTransfersRequest, type GeneratedKeys, type GetFeeEstimationRequestModel, type GetFeeEstimationResponse, type InflateAssetIfaRequestModel, type InflateEndRequestModel, type InvoiceReceiveData, type InvoiceRequest, type IssueAssetIfaRequestModel, type IssueAssetNIAResponse, type IssueAssetNiaRequestModel, KEYCHAIN_BTC, KEYCHAIN_RGB, type ListAssetsResponse, LogLevel, type Media, NETWORK_MAP, type Network, NetworkError, type NetworkVersions, NotFoundError, type OperationResult, type PsbtType, type RGBHTTPClientParams, type Recipient, type RestoreWalletRequestModel, type RgbAllocation, RgbNodeError, type RgbTransfer, SDKError, type SendAssetBeginRequestModel, type SendAssetEndRequestModel, type SendBtcBeginRequestModel, type SendBtcEndRequestModel, type SendResult, type SignPsbtOptions, type Transaction, TransactionType, TransferStatus, type Unspent, type Utxo, ValidationError, type WalletBackupResponse, WalletError, type WalletInitParams, WalletManager, type WalletRestoreResponse, type WitnessData, accountXpubsFromMnemonic, configureLogging, createWallet, createWalletManager, deriveKeysFromMnemonic, deriveKeysFromSeed, deriveKeysFromXpriv, generateKeys, getEnvironment, getXprivFromMnemonic, getXpubFromXpriv, isBrowser, isNode, logger, normalizeNetwork, restoreFromBackup, restoreKeys, signMessage, signPsbt, signPsbtFromSeed, signPsbtSync, validateBase64, validateHex, validateMnemonic, validateNetwork, validatePsbt, validateRequired, validateString, verifyMessage, wallet };
+export { type AccountXpubs, BIP32_VERSIONS, BadRequestError, type BindingAssignment, type BridgeTransferStatus, COIN_BITCOIN_MAINNET, COIN_BITCOIN_TESTNET, COIN_RGB_MAINNET, COIN_RGB_TESTNET, type ConfigOptions, ConfigurationError, ConflictError, CryptoError, DEFAULT_API_TIMEOUT, DEFAULT_LOG_LEVEL, DEFAULT_MAX_RETRIES, DEFAULT_NETWORK, DEFAULT_VSS_SERVER_URL, DERIVATION_ACCOUNT, DERIVATION_PURPOSE, type DecodeRgbInvoiceResponse, type Descriptors, type Environment, type GeneratedKeys, type ILightningProtocol, type IOnchainProtocol, type IUTEXOProtocol, KEYCHAIN_BTC, KEYCHAIN_RGB, LightningProtocol, LogLevel, NETWORK_MAP, type Network, type NetworkAsset, NetworkError, type NetworkVersions, NotFoundError, OnchainProtocol, type OnchainSendStatus, type PsbtType, type RgbAllocation, RgbNodeError, SDKError, type SignPsbtOptions, type TransferStatus, UTEXOProtocol, UTEXOWallet, type Unspent, type Utxo, type UtxoNetworkId, type UtxoNetworkIdMap, type UtxoNetworkMap, type UtxoNetworkPreset, type UtxoNetworkPresetConfig, ValidationError, WalletError, type WalletInitParams, WalletManager, accountXpubsFromMnemonic, configureLogging, createWallet, createWalletManager, deriveKeysFromMnemonic, deriveKeysFromMnemonicOrSeed, deriveKeysFromSeed, deriveKeysFromXpriv, deriveVssSigningKeyFromMnemonic, generateKeys, getDestinationAsset, getEnvironment, getUtxoNetworkConfig, getXprivFromMnemonic, getXpubFromXpriv, isBrowser, isNode, logger, normalizeNetwork, restoreFromBackup, restoreFromVss, restoreKeys, restoreUtxoWalletFromBackup, restoreUtxoWalletFromVss, signMessage, signPsbt, signPsbtFromSeed, signPsbtSync, utexoNetworkIdMap, utexoNetworkMap, validateBase64, validateHex, validateMnemonic, validateNetwork, validatePsbt, validateRequired, validateString, verifyMessage, wallet };