@utexo/rgb-sdk 1.0.1

package/dist/index.d.mts

@@ -0,0 +1,998 @@
+/**
+ * RGB Crypto module types
+ *
+ * Type definitions for RGB-specific cryptographic operations including
+ * PSBT signing and key derivation for RGB protocol
+ */
+/**
+ * Bitcoin network type
+ */
+type Network = 'mainnet' | 'testnet' | 'testnet4' | 'signet' | 'regtest';
+/**
+ * PSBT type (create_utxo or send)
+ */
+type PsbtType = 'create_utxo' | 'send';
+/**
+ * Network versions for BIP32
+ */
+interface NetworkVersions {
+    bip32: {
+        public: number;
+        private: number;
+    };
+    wif: number;
+}
+/**
+ * Descriptors for wallet derivation
+ */
+interface Descriptors {
+    external: string;
+    internal: string;
+}
+/**
+ * BDK SignOptions
+ */
+interface BDKSignOptions {
+}
+
+interface SignPsbtOptions {
+    signOptions?: BDKSignOptions;
+    preprocess?: boolean;
+}
+/**
+ * Sign a PSBT using BDK
+ *
+ * Note: This function is async due to dependency loading and crypto operations.
+ *
+ * @param mnemonic - BIP39 mnemonic phrase (12 or 24 words)
+ * @param psbtBase64 - Base64 encoded PSBT string
+ * @param network - Bitcoin network ('mainnet' | 'testnet' | 'signet' | 'regtest')
+ * @param options - Optional signing options
+ * @param options.signOptions - BDK sign options (defaults used if not provided)
+ * @param options.preprocess - Force preprocessing (auto-detected by default)
+ * @returns Base64 encoded signed PSBT
+ * @throws {ValidationError} If mnemonic or PSBT format is invalid
+ * @throws {CryptoError} If signing fails
+ *
+ * @example
+ * ```typescript
+ * const signedPsbt = signPsbt(
+ *   'abandon abandon abandon...',
+ *   'cHNidP8BAIkBAAAAA...',
+ *   'testnet'
+ * );
+ * ```
+ */
+declare function signPsbt(mnemonic: string, psbtBase64: string, network?: Network, options?: SignPsbtOptions): Promise<string>;
+/**
+ * Legacy sync-named wrapper (still async under the hood).
+ */
+declare function signPsbtSync(mnemonic: string, psbtBase64: string, network?: Network, options?: SignPsbtOptions): Promise<string>;
+/**
+ * Sign a PSBT using a raw BIP39 seed (hex string or Uint8Array)
+ */
+declare function signPsbtFromSeed(seed: string | Uint8Array, psbtBase64: string, network?: Network, options?: SignPsbtOptions): Promise<string>;
+interface SignMessageParams {
+    message: string | Uint8Array;
+    seed: string | Uint8Array;
+    network?: Network;
+}
+interface VerifyMessageParams {
+    message: string | Uint8Array;
+    signature: string;
+    accountXpub: string;
+    network?: Network;
+}
+interface EstimateFeeResult {
+    fee: number;
+    vbytes: number;
+    feeRate: number;
+}
+declare function signMessage(params: SignMessageParams): Promise<string>;
+declare function verifyMessage(params: VerifyMessageParams): Promise<boolean>;
+
+interface GeneratedKeys {
+    mnemonic: string;
+    xpub: string;
+    accountXpubVanilla: string;
+    accountXpubColored: string;
+    masterFingerprint: string;
+    xpriv: string;
+}
+interface AccountXpubs {
+    account_xpub_vanilla: string;
+    account_xpub_colored: string;
+}
+/**
+ * Generate new wallet keys with a random mnemonic
+ * Mirrors rgb_lib::generate_keys (creates new 12-word mnemonic)
+ *
+ * @param bitcoinNetwork - Network string or number (default: 'regtest')
+ * @returns Promise resolving to generated keys including mnemonic, xpubs, and master fingerprint
+ * @throws {CryptoError} If key generation fails
+ *
+ * @example
+ * ```typescript
+ * const keys = await generateKeys('testnet');
+ * console.log('Mnemonic:', keys.mnemonic);
+ * console.log('Master Fingerprint:', keys.master_fingerprint);
+ * ```
+ */
+declare function generateKeys(bitcoinNetwork?: string | number): Promise<GeneratedKeys>;
+/**
+ * Derive wallet keys from existing mnemonic
+ * Takes a mnemonic phrase and derives all keys (xpubs, master fingerprint)
+ *
+ * This function is the counterpart to `generateKeys()` - instead of generating
+ * a new mnemonic, it derives keys from an existing one.
+ *
+ * @param bitcoinNetwork - Network string or number (default: 'regtest')
+ * @param mnemonic - BIP39 mnemonic phrase
+ * @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
+ * const keys = await deriveKeysFromMnemonic('testnet', 'abandon abandon abandon...');
+ * console.log('Account XPub:', keys.account_xpub_vanilla);
+ * ```
+ */
+declare function deriveKeysFromMnemonic(bitcoinNetwork: string | number | undefined, mnemonic: string): Promise<GeneratedKeys>;
+/**
+ * Derive wallet keys directly from a BIP39 seed (hex string or Uint8Array)
+ */
+declare function deriveKeysFromSeed(bitcoinNetwork: string | number | undefined, seed: 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.
+ * @see deriveKeysFromMnemonic
+ */
+declare function restoreKeys(bitcoinNetwork: string | number | undefined, mnemonic: string): Promise<GeneratedKeys>;
+/**
+ * Get account xpubs from mnemonic (convenience function)
+ *
+ * @param bitcoinNetwork - Network string or number (default: 'regtest')
+ * @param mnemonic - BIP39 mnemonic phrase
+ * @returns Promise resolving to account xpubs for vanilla and colored keychains
+ * @throws {ValidationError} If mnemonic is invalid
+ * @throws {CryptoError} If key derivation fails
+ *
+ * @example
+ * ```typescript
+ * const xpubs = await accountXpubsFromMnemonic('testnet', 'abandon abandon abandon...');
+ * console.log('Vanilla XPub:', xpubs.account_xpub_vanilla);
+ * console.log('Colored XPub:', xpubs.account_xpub_colored);
+ * ```
+ */
+/**
+ * Get master extended private key (xpriv) from mnemonic
+ *
+ * @param bitcoinNetwork - Network string or number (default: 'regtest')
+ * @param mnemonic - BIP39 mnemonic phrase (12 or 24 words)
+ * @returns Promise resolving to master xpriv (extended private key)
+ * @throws {ValidationError} If mnemonic is invalid
+ * @throws {CryptoError} If key derivation fails
+ *
+ * @example
+ * ```typescript
+ * const xpriv = await getXprivFromMnemonic('testnet', 'your mnemonic phrase here');
+ * console.log('Master xpriv:', xpriv);
+ * ```
+ */
+declare function getXprivFromMnemonic(bitcoinNetwork: string | number | undefined, mnemonic: string): Promise<string>;
+/**
+ * Get extended public key (xpub) from extended private key (xpriv)
+ *
+ * @param xpriv - Extended private key (base58 encoded)
+ * @returns Promise resolving to xpub (extended public key)
+ * @throws {CryptoError} If xpriv is invalid or derivation fails
+ *
+ * @example
+ * ```typescript
+ * const xpub = await getXpubFromXpriv('xprv...');
+ * console.log('xpub:', xpub);
+ * ```
+ */
+declare function getXpubFromXpriv(xpriv: string, bitcoinNetwork?: string | number): Promise<string>;
+/**
+ * Derive wallet keys from extended private key (xpriv)
+ * Similar to deriveKeysFromMnemonic but starts from xpriv instead of mnemonic
+ *
+ * @param bitcoinNetwork - Network string or number (default: 'regtest')
+ * @param xpriv - Extended private key (base58 encoded)
+ * @returns Promise resolving to generated keys (without mnemonic)
+ * @throws {ValidationError} If xpriv is invalid
+ * @throws {CryptoError} If key derivation fails
+ *
+ * @example
+ * ```typescript
+ * const keys = await deriveKeysFromXpriv('testnet', 'xprv...');
+ * console.log('Master Fingerprint:', keys.master_fingerprint);
+ * console.log('Account xpub vanilla:', keys.account_xpub_vanilla);
+ * ```
+ */
+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;
+};
+interface FailTransfersRequest {
+    batchTransferIdx?: number;
+    noAssetOnly?: boolean;
+    skipSync?: boolean;
+}
+interface WalletBackupResponse {
+    message: string;
+    backupPath: string;
+}
+interface WalletRestoreResponse {
+    message: string;
+}
+interface RestoreWalletRequestModel {
+    backupFilePath: string;
+    password: string;
+    dataDir: string;
+}
+interface WitnessData {
+    amountSat: number;
+    blinding?: number;
+}
+interface InvoiceRequest {
+    amount: number;
+    assetId: string;
+    minConfirmations?: number;
+    durationSeconds?: number;
+}
+interface Recipient {
+    recipientId: string;
+    witnessData?: WitnessData;
+    amount: number;
+    transportEndpoints: string[];
+}
+interface IssueAssetNiaRequestModel {
+    ticker: string;
+    name: string;
+    amounts: number[];
+    precision: number;
+}
+interface IssueAssetIfaRequestModel {
+    ticker: string;
+    name: string;
+    precision: number;
+    amounts: number[];
+    inflationAmounts: number[];
+    replaceRightsNum: number;
+    rejectListUrl?: string;
+}
+interface SendAssetBeginRequestModel {
+    invoice: string;
+    witnessData?: WitnessData;
+    assetId?: string;
+    amount?: number;
+    feeRate?: number;
+    minConfirmations?: number;
+}
+interface SendAssetEndRequestModel {
+    signedPsbt: string;
+    skipSync?: boolean;
+}
+interface SendResult {
+    txid: string;
+    batchTransferIdx: number;
+}
+interface OperationResult {
+    txid: string;
+    batchTransferIdx: number;
+}
+interface CreateUtxosBeginRequestModel {
+    upTo?: boolean;
+    num?: number;
+    size?: number;
+    feeRate?: number;
+}
+interface CreateUtxosEndRequestModel {
+    signedPsbt: string;
+    skipSync?: boolean;
+}
+interface InflateAssetIfaRequestModel {
+    assetId: string;
+    inflationAmounts: number[];
+    feeRate?: number;
+    minConfirmations?: number;
+}
+interface InflateEndRequestModel {
+    signedPsbt: string;
+}
+interface SendBtcBeginRequestModel {
+    address: string;
+    amount: number;
+    feeRate: number;
+    skipSync?: boolean;
+}
+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
+}
+interface BlockTime {
+    height: number;
+    timestamp: number;
+}
+interface Transaction {
+    transactionType: TransactionType;
+    txid: string;
+    received: number;
+    sent: number;
+    fee: number;
+    confirmationTime?: BlockTime;
+}
+declare enum TransferKind {
+    ISSUANCE = 0,
+    RECEIVE_BLIND = 1,
+    RECEIVE_WITNESS = 2,
+    SEND = 3,
+    INFLATION = 4
+}
+interface RgbTransfer {
+    idx: number;
+    batchTransferIdx: number;
+    createdAt: number;
+    updatedAt: number;
+    status: TransferStatus;
+    amount: number;
+    kind: TransferKind;
+    txid: string | null;
+    recipientId: string;
+    receiveUtxo: {
+        txid: string;
+        vout: number;
+    };
+    changeUtxo: {
+        txid: string;
+        vout: number;
+    } | null;
+    expiration: number;
+    transportEndpoints: {
+        endpoint: string;
+        transportType: number;
+        used: boolean;
+    }[];
+}
+declare enum TransferStatus {
+    WAITING_COUNTERPARTY = 0,
+    WAITING_CONFIRMATIONS = 1,
+    SETTLED = 2,
+    FAILED = 3
+}
+interface Unspent {
+    utxo: Utxo;
+    rgbAllocations: RgbAllocation[];
+}
+interface Utxo {
+    outpoint: {
+        txid: string;
+        vout: number;
+    };
+    btcAmount: number;
+    colorable: boolean;
+}
+interface RgbAllocation {
+    assetId: string;
+    amount: number;
+    settled: boolean;
+}
+interface Balance {
+    settled: number;
+    future: number;
+    spendable: number;
+}
+interface BtcBalance {
+    vanilla: Balance;
+    colored: Balance;
+}
+interface InvoiceReceiveData {
+    invoice: string;
+    recipientId: string;
+    expirationTimestamp: number;
+    batchTransferIdx: number;
+}
+interface AssetNIA {
+    /**
+     * @type {string}
+     * @memberof AssetNIA
+     * @example rgb:2dkSTbr-jFhznbPmo-TQafzswCN-av4gTsJjX-ttx6CNou5-M98k8Zd
+     */
+    assetId?: string;
+    /**
+     * @type {AssetIface}
+     * @memberof AssetNIA
+     */
+    assetIface?: AssetIface;
+    /**
+     * @type {string}
+     * @memberof AssetNIA
+     * @example USDT
+     */
+    ticker?: string;
+    /**
+     * @type {string}
+     * @memberof AssetNIA
+     * @example Tether
+     */
+    name?: string;
+    /**
+     * @type {string}
+     * @memberof AssetNIA
+     * @example asset details
+     */
+    details?: string;
+    /**
+     * @type {number}
+     * @memberof AssetNIA
+     * @example 0
+     */
+    precision?: number;
+    /**
+     * @type {number}
+     * @memberof AssetNIA
+     * @example 777
+     */
+    issuedSupply?: number;
+    /**
+     * @type {number}
+     * @memberof AssetNIA
+     * @example 1691160565
+     */
+    timestamp?: number;
+    /**
+     * @type {number}
+     * @memberof AssetNIA
+     * @example 1691161979
+     */
+    addedAt?: number;
+    /**
+     * @type {BtcBalance}
+     * @memberof AssetNIA
+     */
+    balance?: BtcBalance;
+    /**
+     * @type {Media}
+     * @memberof AssetNIA
+     */
+    media?: Media;
+}
+interface AssetIfa {
+    assetId: string;
+    ticker: string;
+    name: string;
+    details?: string;
+    precision: number;
+    initialSupply: number;
+    maxSupply: number;
+    knownCirculatingSupply: number;
+    timestamp: number;
+    addedAt: number;
+    balance: Balance;
+    media?: Media;
+    rejectListUrl?: string;
+}
+interface Media {
+    /**
+     * @type {string}
+     * @memberof Media
+     * @example /path/to/media
+     */
+    filePath?: string;
+    /**
+     * @type {string}
+     * @memberof Media
+     * @example text/plain
+     */
+    mime?: string;
+}
+declare enum AssetIface {
+    RGB20 = "RGB20",
+    RGB21 = "RGB21",
+    RGB25 = "RGB25"
+}
+declare enum AssetSchema {
+    Nia = "Nia",
+    Uda = "Uda",
+    Cfa = "Cfa"
+}
+/**
+ *
+ *
+ * @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 AssetBalanceResponse {
+    /**
+     * @type {number}
+     * @memberof AssetBalanceResponse
+     * @example 777
+     */
+    settled?: number;
+    /**
+     * @type {number}
+     * @memberof AssetBalanceResponse
+     * @example 777
+     */
+    future?: number;
+    /**
+     * @type {number}
+     * @memberof AssetBalanceResponse
+     * @example 777
+     */
+    spendable?: number;
+    /**
+     * @type {number}
+     * @memberof AssetBalanceResponse
+     * @example 444
+     */
+    offchainOutbound?: number;
+    /**
+     * @type {number}
+     * @memberof AssetBalanceResponse
+     * @example 0
+     */
+    offchainInbound?: number;
+}
+interface DecodeRgbInvoiceResponse {
+    recipientId: string;
+    assetSchema?: string;
+    assetId?: string;
+    network: string;
+    assignment: Assignment;
+    assignmentName?: string;
+    expirationTimestamp?: number;
+    transportEndpoints: string[];
+}
+interface Assignment {
+    [key: string]: any;
+}
+
+/**
+ * Restore wallet from backup
+ * This should be called before creating a WalletManager instance
+ * @param params - Restore parameters including backup file path, password, and restore directory
+ * @returns Wallet restore response
+ */
+declare const restoreFromBackup: (params: RestoreWalletRequestModel) => WalletRestoreResponse;
+/**
+ * Generate a new wallet with keys
+ * @param network - Network string (default: 'regtest')
+ * @returns Generated keys including mnemonic, xpubs, and master fingerprint
+ */
+declare const createWallet: (network?: string) => Promise<GeneratedKeys>;
+type WalletInitParams = {
+    xpubVan: string;
+    xpubCol: string;
+    mnemonic?: string;
+    seed?: Uint8Array;
+    network?: string | number;
+    xpub?: string;
+    masterFingerprint: string;
+    transportEndpoint?: string;
+    indexerUrl?: string;
+    dataDir?: string;
+};
+/**
+ * Wallet Manager - High-level wallet interface combining RGB API client and cryptographic operations
+ *
+ * This class provides a unified interface for:
+ * - RGB operations (via RGBLibClient - local rgb-lib)
+ * - PSBT signing operations
+ * - Wallet state management
+ *
+ * @example
+ * ```typescript
+ * const keys = generateKeys('testnet');
+ * const wallet = new WalletManager({
+ *   xpubVan: keys.accountXpubVanilla,
+ *   xpubCol: keys.accountXpubColored,
+ *   masterFingerprint: keys.masterFingerprint,
+ *   mnemonic: keys.mnemonic,
+ *   network: 'testnet',
+ *   transportEndpoint: 'rpcs://proxy.iriswallet.com/0.2/json-rpc',
+ *   indexerUrl: 'ssl://electrum.iriswallet.com:50013'
+ * });
+ *
+ * const balance = await wallet.getBtcBalance();
+ * ```
+ */
+declare class WalletManager {
+    private readonly client;
+    private readonly xpub;
+    private readonly xpubVan;
+    private readonly xpubCol;
+    private mnemonic;
+    private seed;
+    private readonly network;
+    private readonly masterFingerprint;
+    private disposed;
+    private readonly dataDir;
+    constructor(params: WalletInitParams);
+    /**
+     * Get wallet's extended public keys
+     */
+    getXpub(): {
+        xpubVan: string;
+        xpubCol: string;
+    };
+    /**
+     * Get wallet's network
+     */
+    getNetwork(): Network;
+    /**
+     * Dispose of sensitive wallet data
+     * Clears mnemonic and seed from memory
+     * Idempotent - safe to call multiple times
+     */
+    dispose(): void;
+    /**
+     * Check if wallet has been disposed
+     */
+    isDisposed(): boolean;
+    /**
+     * Guard method to ensure wallet has not been disposed
+     * @throws {WalletError} if wallet has been disposed
+     */
+    private ensureNotDisposed;
+    registerWallet(): {
+        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;
+    /**
+     * Complete inflate operation: begin → sign → end
+     * @param params - Inflate parameters
+     * @param mnemonic - Optional mnemonic for signing
+     */
+    inflate(params: InflateAssetIfaRequestModel, mnemonic?: string): Promise<OperationResult>;
+    refreshWallet(): void;
+    listTransactions(): Transaction[];
+    listTransfers(asset_id?: string): RgbTransfer[];
+    failTransfers(params: FailTransfersRequest): boolean;
+    decodeRGBInvoice(params: {
+        invoice: string;
+    }): DecodeRgbInvoiceResponse;
+    createBackup(params: {
+        backupPath: string;
+        password: string;
+    }): 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)
+     */
+    signPsbt(psbt: string, mnemonic?: string): Promise<string>;
+    /**
+     * Complete send operation: begin → sign → end
+     * @param invoiceTransfer - Transfer invoice parameters
+     * @param mnemonic - Optional mnemonic for signing
+     */
+    send(invoiceTransfer: SendAssetBeginRequestModel, mnemonic?: string): Promise<SendResult>;
+    createUtxos({ upTo, num, size, feeRate }: {
+        upTo?: boolean;
+        num?: number;
+        size?: number;
+        feeRate?: number;
+    }): Promise<number>;
+    syncWallet(): void;
+    signMessage(message: string): Promise<string>;
+    verifyMessage(message: string, signature: string, accountXpub?: string): Promise<boolean>;
+}
+/**
+ * Factory function to create a WalletManager instance
+ * Provides a cleaner API than direct constructor
+ *
+ * @example
+ * ```typescript
+ * const keys = generateKeys('testnet');
+ * const wallet = createWalletManager({
+ *   xpubVan: keys.accountXpubVanilla,
+ *   xpubCol: keys.accountXpubColored,
+ *   masterFingerprint: keys.masterFingerprint,
+ *   mnemonic: keys.mnemonic,
+ *   network: 'testnet',
+ *   transportEndpoint: 'rpcs://proxy.iriswallet.com/0.2/json-rpc',
+ *   indexerUrl: 'ssl://electrum.iriswallet.com:50013'
+ * });
+ * ```
+ */
+declare function createWalletManager(params: WalletInitParams): WalletManager;
+declare const wallet: WalletManager;
+
+/**
+ * Custom error classes for the RGB SDK
+ */
+/**
+ * Base SDK error class with error codes and context
+ */
+declare class SDKError extends Error {
+    readonly code: string;
+    readonly statusCode?: number;
+    readonly cause?: Error;
+    constructor(message: string, code: string, statusCode?: number, cause?: Error);
+    /**
+     * Convert error to JSON for logging
+     */
+    toJSON(): {
+        name: string;
+        message: string;
+        code: string;
+        statusCode: number | undefined;
+        cause: string | undefined;
+        stack: string | undefined;
+    };
+}
+/**
+ * Network-related errors (API calls, connectivity)
+ */
+declare class NetworkError extends SDKError {
+    constructor(message: string, statusCode?: number, cause?: Error);
+}
+/**
+ * Validation errors (invalid input parameters)
+ */
+declare class ValidationError extends SDKError {
+    readonly field?: string;
+    constructor(message: string, field?: string);
+}
+/**
+ * Wallet-related errors (initialization, operations)
+ */
+declare class WalletError extends SDKError {
+    constructor(message: string, code?: string, cause?: Error);
+}
+/**
+ * Cryptographic errors (signing, key derivation)
+ */
+declare class CryptoError extends SDKError {
+    constructor(message: string, cause?: Error);
+}
+/**
+ * Configuration errors (missing or invalid configuration)
+ */
+declare class ConfigurationError extends SDKError {
+    constructor(message: string, field?: string);
+}
+/**
+ * Bad request errors (400) - Invalid request parameters or data
+ */
+declare class BadRequestError extends SDKError {
+    constructor(message: string, cause?: Error);
+}
+/**
+ * Not found errors (404) - Resource not found
+ */
+declare class NotFoundError extends SDKError {
+    constructor(message: string, cause?: Error);
+}
+/**
+ * Conflict errors (409) - Resource conflict (e.g., wallet state already exists)
+ */
+declare class ConflictError extends SDKError {
+    constructor(message: string, cause?: Error);
+}
+/**
+ * RGB Node errors (500, 502, 503, 504) - RGB Node server errors
+ */
+declare class RgbNodeError extends SDKError {
+    constructor(message: string, statusCode: number, cause?: Error);
+}
+
+/**
+ * Logger utility for the SDK
+ * Provides structured logging with configurable log levels
+ */
+declare enum LogLevel {
+    DEBUG = 0,
+    INFO = 1,
+    WARN = 2,
+    ERROR = 3,
+    NONE = 4
+}
+declare class Logger {
+    private level;
+    /**
+     * Set the log level
+     */
+    setLevel(level: LogLevel): void;
+    /**
+     * Get the current log level
+     */
+    getLevel(): LogLevel;
+    /**
+     * Log debug messages
+     */
+    debug(...args: unknown[]): void;
+    /**
+     * Log info messages
+     */
+    info(...args: unknown[]): void;
+    /**
+     * Log warning messages
+     */
+    warn(...args: unknown[]): void;
+    /**
+     * Log error messages
+     */
+    error(...args: unknown[]): void;
+}
+declare const logger: Logger;
+/**
+ * Configure SDK logging
+ */
+declare function configureLogging(level: LogLevel): void;
+
+declare function isNode(): boolean;
+declare function isBrowser(): boolean;
+type Environment = 'node' | 'browser' | 'unknown';
+declare function getEnvironment(): Environment;
+
+declare function validateNetwork(network: string | number): asserts network is Network;
+declare function normalizeNetwork(network: string | number): Network;
+declare function validateMnemonic(mnemonic: unknown, field?: string): asserts mnemonic is string;
+declare function validateBase64(base64: unknown, field?: string): asserts base64 is string;
+declare function validatePsbt(psbt: unknown, field?: string): asserts psbt is string;
+declare function validateHex(hex: unknown, field?: string): asserts hex is string;
+declare function validateRequired<T>(value: T | null | undefined, field: string): asserts value is T;
+declare function validateString(value: unknown, field: string): asserts value is string;
+
+/**
+ * BIP32 derivation path constants
+ */
+/**
+ * BIP86 (Taproot) purpose value
+ */
+declare const DERIVATION_PURPOSE = 86;
+/**
+ * Account index (account 0')
+ */
+declare const DERIVATION_ACCOUNT = 0;
+/**
+ * RGB keychain index
+ */
+declare const KEYCHAIN_RGB = 0;
+/**
+ * Bitcoin keychain index
+ */
+declare const KEYCHAIN_BTC = 0;
+
+/**
+ * Network-related constants
+ */
+/**
+ * Coin type constants
+ */
+declare const COIN_RGB_MAINNET = 827166;
+declare const COIN_RGB_TESTNET = 827167;
+declare const COIN_BITCOIN_MAINNET = 0;
+declare const COIN_BITCOIN_TESTNET = 1;
+/**
+ * Network string/number to Network type mapping
+ */
+declare const NETWORK_MAP: {
+    readonly '0': "mainnet";
+    readonly '1': "testnet";
+    readonly '2': "testnet";
+    readonly '3': "regtest";
+    readonly signet: "signet";
+    readonly mainnet: "mainnet";
+    readonly testnet: "testnet";
+    readonly testnet4: "testnet4";
+    readonly regtest: "regtest";
+};
+/**
+ * BIP32 network version constants
+ * Note: testnet4 uses the same versions as testnet
+ */
+declare const BIP32_VERSIONS: {
+    readonly mainnet: {
+        readonly public: 76067358;
+        readonly private: 76066276;
+    };
+    readonly testnet: {
+        readonly public: 70617039;
+        readonly private: 70615956;
+    };
+    readonly testnet4: {
+        readonly public: 70617039;
+        readonly private: 70615956;
+    };
+    readonly signet: {
+        readonly public: 70617039;
+        readonly private: 70615956;
+    };
+    readonly regtest: {
+        readonly public: 70617039;
+        readonly private: 70615956;
+    };
+};
+
+/**
+ * Default configuration values
+ */
+/**
+ * Default network to use
+ */
+declare const DEFAULT_NETWORK: "regtest";
+/**
+ * Default API request timeout in milliseconds
+ */
+declare const DEFAULT_API_TIMEOUT = 120000;
+/**
+ * Default maximum number of retries for failed requests
+ */
+declare const DEFAULT_MAX_RETRIES = 3;
+/**
+ * Default log level
+ */
+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 };