@unicitylabs/sphere-sdk 0.1.0

package/dist/core/index.d.cts

@@ -0,0 +1,2548 @@
+import { Token as Token$1 } from '@unicitylabs/state-transition-sdk/lib/token/Token';
+import elliptic from 'elliptic';
+
+/**
+ * Cryptographic utilities for SDK2
+ *
+ * Provides BIP39 mnemonic and BIP32 key derivation functions.
+ * Platform-independent - no browser-specific APIs.
+ */
+
+declare const ec: elliptic.ec;
+/** Default derivation path for Unicity (BIP44) */
+declare const DEFAULT_DERIVATION_PATH = "m/44'/0'/0'";
+interface MasterKey {
+    privateKey: string;
+    chainCode: string;
+}
+interface DerivedKey {
+    privateKey: string;
+    chainCode: string;
+}
+interface KeyPair {
+    privateKey: string;
+    publicKey: string;
+}
+interface AddressInfo extends KeyPair {
+    address: string;
+    path: string;
+    index: number;
+}
+/**
+ * Generate a new BIP39 mnemonic phrase
+ * @param strength - Entropy bits (128 = 12 words, 256 = 24 words)
+ */
+declare function generateMnemonic(strength?: 128 | 256): string;
+/**
+ * Validate a BIP39 mnemonic phrase
+ */
+declare function validateMnemonic(mnemonic: string): boolean;
+/**
+ * Convert mnemonic to seed (64-byte hex string)
+ * @param mnemonic - BIP39 mnemonic phrase
+ * @param passphrase - Optional passphrase for additional security
+ */
+declare function mnemonicToSeed(mnemonic: string, passphrase?: string): Promise<string>;
+/**
+ * Synchronous version of mnemonicToSeed
+ */
+declare function mnemonicToSeedSync(mnemonic: string, passphrase?: string): string;
+/**
+ * Convert mnemonic to entropy (for recovery purposes)
+ */
+declare function mnemonicToEntropy(mnemonic: string): string;
+/**
+ * Convert entropy to mnemonic
+ */
+declare function entropyToMnemonic(entropy: string): string;
+/**
+ * Generate master key from seed (BIP32 standard)
+ * Uses HMAC-SHA512 with key "Bitcoin seed"
+ */
+declare function generateMasterKey(seedHex: string): MasterKey;
+/**
+ * Derive child key using BIP32 standard
+ * @param parentPrivKey - Parent private key (64 hex chars)
+ * @param parentChainCode - Parent chain code (64 hex chars)
+ * @param index - Child index (>= 0x80000000 for hardened)
+ */
+declare function deriveChildKey(parentPrivKey: string, parentChainCode: string, index: number): DerivedKey;
+/**
+ * Derive key at a full BIP32/BIP44 path
+ * @param masterPrivKey - Master private key
+ * @param masterChainCode - Master chain code
+ * @param path - BIP44 path like "m/44'/0'/0'/0/0"
+ */
+declare function deriveKeyAtPath(masterPrivKey: string, masterChainCode: string, path: string): DerivedKey;
+/**
+ * Get public key from private key
+ * @param privateKey - Private key as hex string
+ * @param compressed - Return compressed public key (default: true)
+ */
+declare function getPublicKey(privateKey: string, compressed?: boolean): string;
+/**
+ * Create key pair from private key
+ */
+declare function createKeyPair(privateKey: string): KeyPair;
+/**
+ * Compute SHA256 hash
+ */
+declare function sha256(data: string, inputEncoding?: 'hex' | 'utf8'): string;
+/**
+ * Compute RIPEMD160 hash
+ */
+declare function ripemd160(data: string, inputEncoding?: 'hex' | 'utf8'): string;
+/**
+ * Compute HASH160 (SHA256 -> RIPEMD160)
+ */
+declare function hash160(data: string): string;
+/**
+ * Compute double SHA256
+ */
+declare function doubleSha256(data: string, inputEncoding?: 'hex' | 'utf8'): string;
+/**
+ * Alias for hash160 (L1 SDK compatibility)
+ */
+declare const computeHash160: typeof hash160;
+/**
+ * Convert hex string to Uint8Array for witness program
+ */
+declare function hash160ToBytes(hash160Hex: string): Uint8Array;
+/**
+ * Generate bech32 address from public key
+ * @param publicKey - Compressed public key as hex string
+ * @param prefix - Address prefix (default: "alpha")
+ * @param witnessVersion - Witness version (default: 0 for P2WPKH)
+ * @returns Bech32 encoded address
+ */
+declare function publicKeyToAddress(publicKey: string, prefix?: string, witnessVersion?: number): string;
+/**
+ * Get address info from private key
+ */
+declare function privateKeyToAddressInfo(privateKey: string, prefix?: string): {
+    address: string;
+    publicKey: string;
+};
+/**
+ * Convert hex string to Uint8Array
+ */
+declare function hexToBytes(hex: string): Uint8Array;
+/**
+ * Convert Uint8Array to hex string
+ */
+declare function bytesToHex(bytes: Uint8Array): string;
+/**
+ * Generate random bytes as hex string
+ */
+declare function randomBytes(length: number): string;
+/**
+ * Generate identity from mnemonic
+ * Returns master key derived from mnemonic seed
+ */
+declare function identityFromMnemonic(mnemonic: string, passphrase?: string): Promise<MasterKey>;
+/**
+ * Synchronous version of identityFromMnemonic
+ */
+declare function identityFromMnemonicSync(mnemonic: string, passphrase?: string): MasterKey;
+/**
+ * Derive address info at a specific path
+ * @param masterKey - Master key with privateKey and chainCode
+ * @param basePath - Base derivation path (e.g., "m/44'/0'/0'")
+ * @param index - Address index
+ * @param isChange - Whether this is a change address (chain 1 vs 0)
+ * @param prefix - Address prefix (default: "alpha")
+ */
+declare function deriveAddressInfo(masterKey: MasterKey, basePath: string, index: number, isChange?: boolean, prefix?: string): AddressInfo;
+/**
+ * Generate full address info from private key with index and path
+ * (L1 SDK compatibility)
+ */
+declare function generateAddressInfo(privateKey: string, index: number, path: string, prefix?: string): AddressInfo;
+
+/**
+ * TXF (Token eXchange Format) Type Definitions
+ * Based on TXF Format Specification v2.0
+ *
+ * These types define the serialization format for tokens,
+ * independent of any UI or storage implementation.
+ */
+/**
+ * Complete token object in TXF format
+ */
+interface TxfToken {
+    version: '2.0';
+    genesis: TxfGenesis;
+    state: TxfState;
+    transactions: TxfTransaction[];
+    nametags?: string[];
+    _integrity?: TxfIntegrity;
+}
+/**
+ * Genesis transaction (initial minting)
+ */
+interface TxfGenesis {
+    data: TxfGenesisData;
+    inclusionProof: TxfInclusionProof;
+}
+/**
+ * Genesis data payload
+ */
+interface TxfGenesisData {
+    tokenId: string;
+    tokenType: string;
+    coinData: [string, string][];
+    tokenData: string;
+    salt: string;
+    recipient: string;
+    recipientDataHash: string | null;
+    reason: string | null;
+}
+/**
+ * Current token state
+ */
+interface TxfState {
+    data: string;
+    predicate: string;
+}
+/**
+ * State transition transaction
+ */
+interface TxfTransaction {
+    previousStateHash: string;
+    newStateHash?: string;
+    predicate: string;
+    inclusionProof: TxfInclusionProof | null;
+    data?: Record<string, unknown>;
+}
+/**
+ * Sparse Merkle Tree inclusion proof
+ */
+interface TxfInclusionProof {
+    authenticator: TxfAuthenticator;
+    merkleTreePath: TxfMerkleTreePath;
+    transactionHash: string;
+    unicityCertificate: string;
+}
+/**
+ * Proof authenticator
+ */
+interface TxfAuthenticator {
+    algorithm: string;
+    publicKey: string;
+    signature: string;
+    stateHash: string;
+}
+/**
+ * Merkle tree path for proof verification
+ */
+interface TxfMerkleTreePath {
+    root: string;
+    steps: TxfMerkleStep[];
+}
+/**
+ * Single step in merkle path
+ */
+interface TxfMerkleStep {
+    data: string;
+    path: string;
+}
+/**
+ * Token integrity metadata
+ */
+interface TxfIntegrity {
+    genesisDataJSONHash: string;
+    currentStateHash?: string;
+}
+/**
+ * Nametag data (one per identity)
+ */
+interface NametagData {
+    name: string;
+    token: object;
+    timestamp: number;
+    format: string;
+    version: string;
+}
+/**
+ * Tombstone entry for tracking spent token states
+ */
+interface TombstoneEntry {
+    tokenId: string;
+    stateHash: string;
+    timestamp: number;
+}
+
+/**
+ * SDK2 Core Types
+ * Platform-independent type definitions
+ */
+type ProviderStatus = 'disconnected' | 'connecting' | 'connected' | 'error';
+interface ProviderMetadata {
+    readonly id: string;
+    readonly name: string;
+    readonly type: 'local' | 'cloud' | 'p2p' | 'network';
+    readonly description?: string;
+}
+interface BaseProvider extends ProviderMetadata {
+    connect(config?: unknown): Promise<void>;
+    disconnect(): Promise<void>;
+    isConnected(): boolean;
+    getStatus(): ProviderStatus;
+}
+interface Identity {
+    readonly publicKey: string;
+    /** L1 address (alpha1...) */
+    readonly address: string;
+    /** L3 predicate address (DIRECT://...) */
+    readonly predicateAddress?: string;
+    readonly ipnsName?: string;
+    readonly nametag?: string;
+}
+interface FullIdentity extends Identity {
+    readonly privateKey: string;
+}
+type TokenStatus = 'pending' | 'confirmed' | 'transferring' | 'spent' | 'invalid';
+interface Token {
+    readonly id: string;
+    readonly coinId: string;
+    readonly symbol: string;
+    readonly name: string;
+    readonly amount: string;
+    status: TokenStatus;
+    readonly createdAt: number;
+    updatedAt: number;
+    readonly sdkData?: string;
+}
+interface TokenBalance {
+    readonly coinId: string;
+    readonly symbol: string;
+    readonly name: string;
+    readonly totalAmount: string;
+    readonly tokenCount: number;
+    readonly decimals: number;
+}
+type TransferStatus = 'pending' | 'submitted' | 'confirmed' | 'delivered' | 'completed' | 'failed';
+interface TransferRequest {
+    readonly coinId: string;
+    readonly amount: string;
+    readonly recipient: string;
+    readonly memo?: string;
+}
+interface TransferResult {
+    readonly id: string;
+    status: TransferStatus;
+    readonly tokens: Token[];
+    txHash?: string;
+    error?: string;
+}
+interface IncomingTransfer {
+    readonly id: string;
+    readonly senderPubkey: string;
+    readonly senderNametag?: string;
+    readonly tokens: Token[];
+    readonly memo?: string;
+    readonly receivedAt: number;
+}
+type PaymentRequestStatus = 'pending' | 'accepted' | 'rejected' | 'paid' | 'expired';
+/**
+ * Outgoing payment request (requesting payment from someone)
+ */
+interface PaymentRequest {
+    /** Unique request ID */
+    readonly id: string;
+    /** Amount requested (in smallest units) */
+    readonly amount: string;
+    /** Coin/token type */
+    readonly coinId: string;
+    /** Optional message/memo */
+    readonly message?: string;
+    /** Recipient nametag (who should pay) */
+    readonly recipientNametag?: string;
+    /** Custom metadata */
+    readonly metadata?: Record<string, unknown>;
+    /** Expiration timestamp (ms) */
+    readonly expiresAt?: number;
+    /** Created timestamp */
+    readonly createdAt: number;
+}
+/**
+ * Incoming payment request (someone requesting payment from us)
+ */
+interface IncomingPaymentRequest$1 {
+    /** Event ID from Nostr */
+    readonly id: string;
+    /** Sender's public key */
+    readonly senderPubkey: string;
+    /** Sender's nametag (if known) */
+    readonly senderNametag?: string;
+    /** Amount requested */
+    readonly amount: string;
+    /** Coin/token type */
+    readonly coinId: string;
+    /** Symbol for display */
+    readonly symbol: string;
+    /** Message from sender */
+    readonly message?: string;
+    /** Who this request is for (our nametag) */
+    readonly recipientNametag?: string;
+    /** Original request ID from sender */
+    readonly requestId: string;
+    /** Timestamp */
+    readonly timestamp: number;
+    /** Current status */
+    status: PaymentRequestStatus;
+    /** Custom metadata */
+    readonly metadata?: Record<string, unknown>;
+}
+/**
+ * Result of sending a payment request
+ */
+interface PaymentRequestResult {
+    readonly success: boolean;
+    readonly requestId?: string;
+    readonly eventId?: string;
+    readonly error?: string;
+}
+/**
+ * Handler for incoming payment requests
+ */
+type PaymentRequestHandler$1 = (request: IncomingPaymentRequest$1) => void;
+/**
+ * Response type for payment requests
+ */
+type PaymentRequestResponseType$1 = 'accepted' | 'rejected' | 'paid';
+/**
+ * Outgoing payment request (we sent to someone)
+ */
+interface OutgoingPaymentRequest {
+    /** Unique request ID */
+    readonly id: string;
+    /** Nostr event ID */
+    readonly eventId: string;
+    /** Recipient's public key */
+    readonly recipientPubkey: string;
+    /** Recipient's nametag (if known) */
+    readonly recipientNametag?: string;
+    /** Amount requested */
+    readonly amount: string;
+    /** Coin/token type */
+    readonly coinId: string;
+    /** Message sent with request */
+    readonly message?: string;
+    /** Created timestamp */
+    readonly createdAt: number;
+    /** Current status */
+    status: PaymentRequestStatus;
+    /** Response data (if received) */
+    response?: PaymentRequestResponse;
+}
+/**
+ * Response to a payment request
+ */
+interface PaymentRequestResponse {
+    /** Response event ID */
+    readonly id: string;
+    /** Responder's public key */
+    readonly responderPubkey: string;
+    /** Responder's nametag (if known) */
+    readonly responderNametag?: string;
+    /** Original request ID */
+    readonly requestId: string;
+    /** Response type */
+    readonly responseType: PaymentRequestResponseType$1;
+    /** Optional message */
+    readonly message?: string;
+    /** Transfer ID (if paid) */
+    readonly transferId?: string;
+    /** Timestamp */
+    readonly timestamp: number;
+}
+/**
+ * Handler for payment request responses
+ */
+type PaymentRequestResponseHandler$1 = (response: PaymentRequestResponse) => void;
+interface DirectMessage {
+    readonly id: string;
+    readonly senderPubkey: string;
+    readonly senderNametag?: string;
+    readonly recipientPubkey: string;
+    readonly recipientNametag?: string;
+    readonly content: string;
+    readonly timestamp: number;
+    isRead: boolean;
+}
+interface BroadcastMessage {
+    readonly id: string;
+    readonly authorPubkey: string;
+    readonly authorNametag?: string;
+    readonly content: string;
+    readonly timestamp: number;
+    readonly tags?: string[];
+}
+type SphereEventType = 'transfer:incoming' | 'transfer:confirmed' | 'transfer:failed' | 'payment_request:incoming' | 'payment_request:accepted' | 'payment_request:rejected' | 'payment_request:paid' | 'payment_request:response' | 'message:dm' | 'message:broadcast' | 'sync:started' | 'sync:completed' | 'sync:provider' | 'sync:error' | 'connection:changed' | 'nametag:registered' | 'identity:changed';
+interface SphereEventMap {
+    'transfer:incoming': IncomingTransfer;
+    'transfer:confirmed': TransferResult;
+    'transfer:failed': TransferResult;
+    'payment_request:incoming': IncomingPaymentRequest$1;
+    'payment_request:accepted': IncomingPaymentRequest$1;
+    'payment_request:rejected': IncomingPaymentRequest$1;
+    'payment_request:paid': IncomingPaymentRequest$1;
+    'payment_request:response': PaymentRequestResponse;
+    'message:dm': DirectMessage;
+    'message:broadcast': BroadcastMessage;
+    'sync:started': {
+        source: string;
+    };
+    'sync:completed': {
+        source: string;
+        count: number;
+    };
+    'sync:provider': {
+        providerId: string;
+        success: boolean;
+        added?: number;
+        removed?: number;
+        error?: string;
+    };
+    'sync:error': {
+        source: string;
+        error: string;
+    };
+    'connection:changed': {
+        provider: string;
+        connected: boolean;
+    };
+    'nametag:registered': {
+        nametag: string;
+        addressIndex: number;
+    };
+    'identity:changed': {
+        address: string;
+        predicateAddress?: string;
+        publicKey: string;
+        nametag?: string;
+        addressIndex: number;
+    };
+}
+type SphereEventHandler<T extends SphereEventType> = (data: SphereEventMap[T]) => void;
+/**
+ * Derivation mode determines how child keys are derived:
+ * - "bip32": Standard BIP32 with chain code (IL + parentKey) mod n
+ * - "legacy_hmac": Legacy Sphere HMAC derivation with chain code
+ * - "wif_hmac": Simple HMAC derivation without chain code (webwallet compatibility)
+ */
+type DerivationMode = 'bip32' | 'legacy_hmac' | 'wif_hmac';
+/**
+ * Source of wallet creation
+ */
+type WalletSource = 'mnemonic' | 'file' | 'unknown';
+/**
+ * Wallet information for backup/export purposes
+ */
+interface WalletInfo {
+    readonly source: WalletSource;
+    readonly hasMnemonic: boolean;
+    readonly hasChainCode: boolean;
+    readonly derivationMode: DerivationMode;
+    readonly basePath: string;
+    readonly address0: string | null;
+}
+/**
+ * JSON export format for wallet backup (v1.0)
+ */
+interface WalletJSON {
+    readonly version: '1.0';
+    readonly type: 'sphere-wallet';
+    readonly createdAt: string;
+    readonly wallet: {
+        readonly masterPrivateKey?: string;
+        readonly chainCode?: string;
+        readonly addresses: ReadonlyArray<{
+            readonly address: string;
+            readonly publicKey: string;
+            readonly path: string;
+            readonly index: number;
+        }>;
+        readonly isBIP32: boolean;
+        readonly descriptorPath?: string;
+    };
+    readonly mnemonic?: string;
+    readonly encrypted?: boolean;
+    readonly source?: WalletSource;
+    readonly derivationMode?: DerivationMode;
+}
+/**
+ * Options for exporting wallet to JSON
+ */
+interface WalletJSONExportOptions {
+    /** Include mnemonic in export (default: true if available) */
+    includeMnemonic?: boolean;
+    /** Encrypt sensitive data with password */
+    password?: string;
+    /** Number of addresses to include (default: 1) */
+    addressCount?: number;
+}
+
+/**
+ * L1 Payments Sub-Module
+ *
+ * Handles Layer 1 (ALPHA blockchain) transactions including:
+ * - Balance queries
+ * - UTXO management
+ * - Transaction sending
+ * - Vesting classification
+ * - Transaction history
+ */
+
+interface L1SendRequest {
+    /** Recipient address */
+    to: string;
+    /** Amount in satoshis */
+    amount: string;
+    /** Fee rate in sat/byte */
+    feeRate?: number;
+    /** Use vested coins only */
+    useVested?: boolean;
+    /** Memo/OP_RETURN data */
+    memo?: string;
+}
+interface L1SendResult {
+    success: boolean;
+    txHash?: string;
+    fee?: string;
+    error?: string;
+}
+interface L1Balance {
+    confirmed: string;
+    unconfirmed: string;
+    vested: string;
+    unvested: string;
+    total: string;
+}
+interface L1Utxo {
+    txid: string;
+    vout: number;
+    amount: string;
+    address: string;
+    isVested: boolean;
+    confirmations: number;
+    coinbaseHeight?: number;
+}
+interface L1Transaction {
+    txid: string;
+    type: 'send' | 'receive';
+    amount: string;
+    fee?: string;
+    address: string;
+    confirmations: number;
+    timestamp: number;
+    blockHeight?: number;
+}
+interface L1PaymentsModuleConfig {
+    /** Fulcrum server URL */
+    electrumUrl?: string;
+    /** Network: mainnet or testnet */
+    network?: 'mainnet' | 'testnet';
+    /** Default fee rate */
+    defaultFeeRate?: number;
+    /** Enable vesting classification */
+    enableVesting?: boolean;
+}
+interface L1PaymentsModuleDependencies {
+    identity: FullIdentity;
+    chainCode?: string;
+    addresses?: string[];
+}
+/**
+ * L1 Payments Module - Full Implementation
+ *
+ * Handles all L1 (ALPHA blockchain) operations including balance queries,
+ * transaction sending, UTXO management, and vesting classification.
+ */
+declare class L1PaymentsModule {
+    private _initialized;
+    private _config;
+    private _identity?;
+    private _chainCode?;
+    private _addresses;
+    private _wallet?;
+    constructor(config?: L1PaymentsModuleConfig);
+    initialize(deps: L1PaymentsModuleDependencies): Promise<void>;
+    destroy(): void;
+    send(request: L1SendRequest): Promise<L1SendResult>;
+    getBalance(): Promise<L1Balance>;
+    getUtxos(): Promise<L1Utxo[]>;
+    getHistory(limit?: number): Promise<L1Transaction[]>;
+    getTransaction(txid: string): Promise<L1Transaction | null>;
+    estimateFee(to: string, amount: string): Promise<{
+        fee: string;
+        feeRate: number;
+    }>;
+    getAddresses(): string[];
+    addAddress(address: string): void;
+    getVestingThreshold(): number;
+    isConnected(): boolean;
+    private ensureInitialized;
+    private _getWatchedAddresses;
+    private _getAllUtxos;
+}
+
+/**
+ * Nametag Minter
+ * Mints nametag tokens on-chain for PROXY address support
+ *
+ * Flow (same as Sphere wallet and lottery):
+ * 1. Generate salt
+ * 2. Create MintTransactionData from nametag
+ * 3. Create MintCommitment
+ * 4. Submit to aggregator
+ * 5. Wait for inclusion proof
+ * 6. Create Token with proof
+ * 7. Return token for storage
+ */
+
+interface MintNametagResult {
+    success: boolean;
+    token?: Token$1<any>;
+    nametagData?: NametagData;
+    error?: string;
+}
+
+/**
+ * Storage Provider Interface
+ * Platform-independent storage abstraction
+ */
+
+/**
+ * Basic key-value storage provider
+ * All operations are async for platform flexibility
+ */
+interface StorageProvider extends BaseProvider {
+    /**
+     * Set identity for scoped storage
+     */
+    setIdentity(identity: FullIdentity): void;
+    /**
+     * Get value by key
+     */
+    get(key: string): Promise<string | null>;
+    /**
+     * Set value by key
+     */
+    set(key: string, value: string): Promise<void>;
+    /**
+     * Remove key
+     */
+    remove(key: string): Promise<void>;
+    /**
+     * Check if key exists
+     */
+    has(key: string): Promise<boolean>;
+    /**
+     * Get all keys with optional prefix filter
+     */
+    keys(prefix?: string): Promise<string[]>;
+    /**
+     * Clear all keys with optional prefix filter
+     */
+    clear(prefix?: string): Promise<void>;
+}
+/**
+ * Storage result types
+ */
+interface SaveResult {
+    success: boolean;
+    cid?: string;
+    error?: string;
+    timestamp: number;
+}
+interface LoadResult<T = unknown> {
+    success: boolean;
+    data?: T;
+    error?: string;
+    source: 'local' | 'remote' | 'cache';
+    timestamp: number;
+}
+interface SyncResult<T = unknown> {
+    success: boolean;
+    merged?: T;
+    added: number;
+    removed: number;
+    conflicts: number;
+    error?: string;
+}
+/**
+ * Token-specific storage provider
+ * Handles token persistence with sync capabilities
+ */
+interface TokenStorageProvider<TData = unknown> extends BaseProvider {
+    /**
+     * Set identity for storage scope
+     */
+    setIdentity(identity: FullIdentity): void;
+    /**
+     * Initialize provider (called once after identity is set)
+     */
+    initialize(): Promise<boolean>;
+    /**
+     * Shutdown provider
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Save token data
+     */
+    save(data: TData): Promise<SaveResult>;
+    /**
+     * Load token data
+     */
+    load(identifier?: string): Promise<LoadResult<TData>>;
+    /**
+     * Sync local data with remote
+     */
+    sync(localData: TData): Promise<SyncResult<TData>>;
+    /**
+     * Check if data exists
+     */
+    exists?(identifier?: string): Promise<boolean>;
+    /**
+     * Clear all data
+     */
+    clear?(): Promise<boolean>;
+    /**
+     * Subscribe to storage events
+     */
+    onEvent?(callback: StorageEventCallback): () => void;
+    /**
+     * Save individual token (for file-based storage like lottery pattern)
+     */
+    saveToken?(tokenId: string, tokenData: unknown): Promise<void>;
+    /**
+     * Get individual token
+     */
+    getToken?(tokenId: string): Promise<unknown | null>;
+    /**
+     * List all token IDs
+     */
+    listTokenIds?(): Promise<string[]>;
+    /**
+     * Delete individual token
+     */
+    deleteToken?(tokenId: string): Promise<void>;
+}
+type StorageEventType = 'storage:saving' | 'storage:saved' | 'storage:loading' | 'storage:loaded' | 'storage:error' | 'sync:started' | 'sync:completed' | 'sync:conflict' | 'sync:error';
+interface StorageEvent {
+    type: StorageEventType;
+    timestamp: number;
+    data?: unknown;
+    error?: string;
+}
+type StorageEventCallback = (event: StorageEvent) => void;
+interface TxfStorageDataBase {
+    _meta: TxfMeta;
+    _tombstones?: TxfTombstone[];
+    _outbox?: TxfOutboxEntry[];
+    _sent?: TxfSentEntry[];
+    _invalid?: TxfInvalidEntry[];
+    [key: `_${string}`]: unknown;
+}
+interface TxfMeta {
+    version: number;
+    address: string;
+    ipnsName?: string;
+    formatVersion: string;
+    updatedAt: number;
+}
+interface TxfTombstone {
+    tokenId: string;
+    stateHash: string;
+    timestamp: number;
+}
+interface TxfOutboxEntry {
+    id: string;
+    status: string;
+    tokenId: string;
+    recipient: string;
+    createdAt: number;
+    data: unknown;
+}
+interface TxfSentEntry {
+    tokenId: string;
+    recipient: string;
+    txHash: string;
+    sentAt: number;
+}
+interface TxfInvalidEntry {
+    tokenId: string;
+    reason: string;
+    detectedAt: number;
+}
+
+/**
+ * Transport Provider Interface
+ * Platform-independent P2P messaging abstraction
+ */
+
+/**
+ * P2P messaging transport provider
+ */
+interface TransportProvider extends BaseProvider {
+    /**
+     * Set identity for signing/encryption
+     */
+    setIdentity(identity: FullIdentity): void;
+    /**
+     * Send encrypted direct message
+     * @returns Event ID
+     */
+    sendMessage(recipientPubkey: string, content: string): Promise<string>;
+    /**
+     * Subscribe to incoming direct messages
+     * @returns Unsubscribe function
+     */
+    onMessage(handler: MessageHandler): () => void;
+    /**
+     * Send token transfer payload
+     * @returns Event ID
+     */
+    sendTokenTransfer(recipientPubkey: string, payload: TokenTransferPayload): Promise<string>;
+    /**
+     * Subscribe to incoming token transfers
+     * @returns Unsubscribe function
+     */
+    onTokenTransfer(handler: TokenTransferHandler): () => void;
+    /**
+     * Resolve nametag to public key
+     */
+    resolveNametag?(nametag: string): Promise<string | null>;
+    /**
+     * Register a nametag for this identity
+     * @returns true if successful, false if already taken
+     */
+    registerNametag?(nametag: string, publicKey: string): Promise<boolean>;
+    /**
+     * Publish nametag binding
+     */
+    publishNametag?(nametag: string, address: string): Promise<void>;
+    /**
+     * Subscribe to broadcast messages (global/channel)
+     */
+    subscribeToBroadcast?(tags: string[], handler: BroadcastHandler): () => void;
+    /**
+     * Publish broadcast message
+     */
+    publishBroadcast?(content: string, tags?: string[]): Promise<string>;
+    /**
+     * Send payment request to a recipient
+     * @returns Event ID
+     */
+    sendPaymentRequest?(recipientPubkey: string, request: PaymentRequestPayload): Promise<string>;
+    /**
+     * Subscribe to incoming payment requests
+     * @returns Unsubscribe function
+     */
+    onPaymentRequest?(handler: PaymentRequestHandler): () => void;
+    /**
+     * Send response to a payment request
+     * @returns Event ID
+     */
+    sendPaymentRequestResponse?(recipientPubkey: string, response: PaymentRequestResponsePayload): Promise<string>;
+    /**
+     * Subscribe to incoming payment request responses
+     * @returns Unsubscribe function
+     */
+    onPaymentRequestResponse?(handler: PaymentRequestResponseHandler): () => void;
+    /**
+     * Get list of configured relay URLs
+     */
+    getRelays?(): string[];
+    /**
+     * Get list of currently connected relay URLs
+     */
+    getConnectedRelays?(): string[];
+    /**
+     * Add a relay dynamically
+     * @returns true if added successfully
+     */
+    addRelay?(relayUrl: string): Promise<boolean>;
+    /**
+     * Remove a relay dynamically
+     * @returns true if removed successfully
+     */
+    removeRelay?(relayUrl: string): Promise<boolean>;
+    /**
+     * Check if a relay is configured
+     */
+    hasRelay?(relayUrl: string): boolean;
+    /**
+     * Check if a relay is currently connected
+     */
+    isRelayConnected?(relayUrl: string): boolean;
+}
+interface IncomingMessage {
+    id: string;
+    senderPubkey: string;
+    content: string;
+    timestamp: number;
+    encrypted: boolean;
+}
+type MessageHandler = (message: IncomingMessage) => void;
+interface TokenTransferPayload {
+    /** Serialized token data */
+    token: string;
+    /** Inclusion proof */
+    proof: unknown;
+    /** Optional memo */
+    memo?: string;
+    /** Sender info */
+    sender?: {
+        pubkey: string;
+        nametag?: string;
+    };
+}
+interface IncomingTokenTransfer {
+    id: string;
+    senderPubkey: string;
+    payload: TokenTransferPayload;
+    timestamp: number;
+}
+type TokenTransferHandler = (transfer: IncomingTokenTransfer) => void;
+interface PaymentRequestPayload {
+    /** Amount requested (in smallest units) */
+    amount: string | bigint;
+    /** Coin/token type ID */
+    coinId: string;
+    /** Message/memo for recipient */
+    message?: string;
+    /** Recipient's nametag (who should pay) */
+    recipientNametag?: string;
+    /** Custom metadata */
+    metadata?: Record<string, unknown>;
+}
+interface IncomingPaymentRequest {
+    /** Event ID */
+    id: string;
+    /** Sender's public key */
+    senderPubkey: string;
+    /** Parsed request data */
+    request: {
+        requestId: string;
+        amount: string;
+        coinId: string;
+        message?: string;
+        recipientNametag?: string;
+        metadata?: Record<string, unknown>;
+    };
+    /** Timestamp */
+    timestamp: number;
+}
+type PaymentRequestHandler = (request: IncomingPaymentRequest) => void;
+type PaymentRequestResponseType = 'accepted' | 'rejected' | 'paid';
+interface PaymentRequestResponsePayload {
+    /** Original request ID */
+    requestId: string;
+    /** Response type */
+    responseType: PaymentRequestResponseType;
+    /** Optional message */
+    message?: string;
+    /** Transfer ID (if paid) */
+    transferId?: string;
+}
+interface IncomingPaymentRequestResponse {
+    /** Event ID */
+    id: string;
+    /** Responder's public key */
+    responderPubkey: string;
+    /** Parsed response data */
+    response: {
+        requestId: string;
+        responseType: PaymentRequestResponseType;
+        message?: string;
+        transferId?: string;
+    };
+    /** Timestamp */
+    timestamp: number;
+}
+type PaymentRequestResponseHandler = (response: IncomingPaymentRequestResponse) => void;
+interface IncomingBroadcast {
+    id: string;
+    authorPubkey: string;
+    content: string;
+    tags: string[];
+    timestamp: number;
+}
+type BroadcastHandler = (broadcast: IncomingBroadcast) => void;
+
+/**
+ * Oracle Provider Interface
+ * Platform-independent Unicity oracle abstraction
+ *
+ * The oracle is a trusted third-party service that provides verifiable truth
+ * about the state of tokens in the Unicity network. It aggregates state
+ * transitions into rounds and provides inclusion proofs that cryptographically
+ * verify token ownership and transfers.
+ */
+
+/**
+ * Unicity state transition oracle provider
+ *
+ * The oracle serves as the source of truth for:
+ * - Token state validation (spent/unspent)
+ * - State transition inclusion proofs
+ * - Round-based commitment aggregation
+ */
+interface OracleProvider extends BaseProvider {
+    /**
+     * Initialize with trust base
+     */
+    initialize(trustBase?: unknown): Promise<void>;
+    /**
+     * Submit transfer commitment
+     */
+    submitCommitment(commitment: TransferCommitment): Promise<SubmitResult>;
+    /**
+     * Get inclusion proof for a request
+     */
+    getProof(requestId: string): Promise<InclusionProof | null>;
+    /**
+     * Wait for inclusion proof with polling
+     */
+    waitForProof(requestId: string, options?: WaitOptions): Promise<InclusionProof>;
+    /**
+     * Validate token against aggregator
+     */
+    validateToken(tokenData: unknown): Promise<ValidationResult>;
+    /**
+     * Check if token state is spent
+     */
+    isSpent(stateHash: string): Promise<boolean>;
+    /**
+     * Get token state
+     */
+    getTokenState(tokenId: string): Promise<TokenState | null>;
+    /**
+     * Get current round number
+     */
+    getCurrentRound(): Promise<number>;
+    /**
+     * Mint new tokens (for faucet/testing)
+     */
+    mint?(params: MintParams): Promise<MintResult>;
+    /**
+     * Get underlying StateTransitionClient (if available)
+     * Used for advanced SDK operations like commitment creation
+     */
+    getStateTransitionClient?(): unknown;
+    /**
+     * Get underlying AggregatorClient (if available)
+     * Used for direct aggregator API access
+     */
+    getAggregatorClient?(): unknown;
+    /**
+     * Wait for inclusion proof using SDK commitment (if available)
+     * Used for transfer flows with SDK TransferCommitment
+     */
+    waitForProofSdk?(commitment: unknown, signal?: AbortSignal): Promise<unknown>;
+}
+interface TransferCommitment {
+    /** Source token (SDK format) */
+    sourceToken: unknown;
+    /** Recipient address/predicate */
+    recipient: string;
+    /** Random salt (non-reproducible) */
+    salt: Uint8Array;
+    /** Optional additional data */
+    data?: unknown;
+}
+interface SubmitResult {
+    success: boolean;
+    requestId?: string;
+    error?: string;
+    timestamp: number;
+}
+interface InclusionProof {
+    requestId: string;
+    roundNumber: number;
+    proof: unknown;
+    timestamp: number;
+}
+interface WaitOptions {
+    /** Timeout in ms (default: 30000) */
+    timeout?: number;
+    /** Poll interval in ms (default: 1000) */
+    pollInterval?: number;
+    /** Callback on each poll attempt */
+    onPoll?: (attempt: number) => void;
+}
+interface ValidationResult {
+    valid: boolean;
+    spent: boolean;
+    error?: string;
+    stateHash?: string;
+}
+interface TokenState {
+    tokenId: string;
+    stateHash: string;
+    spent: boolean;
+    roundNumber?: number;
+    lastUpdated: number;
+}
+interface MintParams {
+    coinId: string;
+    amount: string;
+    recipientAddress: string;
+    recipientPubkey?: string;
+}
+interface MintResult {
+    success: boolean;
+    requestId?: string;
+    tokenId?: string;
+    error?: string;
+}
+
+/**
+ * Payments Module
+ * Platform-independent token operations with full wallet repository functionality
+ *
+ * Includes:
+ * - Token CRUD operations
+ * - Tombstones for sync
+ * - Archived tokens (spent history)
+ * - Forked tokens (alternative histories)
+ * - Transaction history
+ * - Nametag storage
+ */
+
+interface TransactionHistoryEntry {
+    id: string;
+    type: 'SENT' | 'RECEIVED' | 'SPLIT' | 'MINT';
+    amount: string;
+    coinId: string;
+    symbol: string;
+    timestamp: number;
+    recipientNametag?: string;
+    senderPubkey?: string;
+    txHash?: string;
+}
+interface PaymentsModuleConfig {
+    /** Auto-sync after operations */
+    autoSync?: boolean;
+    /** Auto-validate with aggregator */
+    autoValidate?: boolean;
+    /** Retry failed transfers */
+    retryFailed?: boolean;
+    /** Max retry attempts */
+    maxRetries?: number;
+    /** Enable debug logging */
+    debug?: boolean;
+    /** L1 (ALPHA blockchain) configuration */
+    l1?: L1PaymentsModuleConfig;
+}
+interface PaymentsModuleDependencies {
+    identity: FullIdentity;
+    storage: StorageProvider;
+    /** @deprecated Use tokenStorageProviders instead */
+    tokenStorage?: TokenStorageProvider<TxfStorageDataBase>;
+    /** Multiple token storage providers (e.g., IPFS, MongoDB, file) */
+    tokenStorageProviders?: Map<string, TokenStorageProvider<TxfStorageDataBase>>;
+    transport: TransportProvider;
+    oracle: OracleProvider;
+    emitEvent: <T extends SphereEventType>(type: T, data: SphereEventMap[T]) => void;
+    /** Chain code for BIP32 HD derivation (for L1 multi-address support) */
+    chainCode?: string;
+    /** Additional L1 addresses to watch */
+    l1Addresses?: string[];
+}
+declare class PaymentsModule {
+    private readonly moduleConfig;
+    private deps;
+    /** L1 (ALPHA blockchain) payments sub-module (null if disabled) */
+    readonly l1: L1PaymentsModule | null;
+    private tokens;
+    private pendingTransfers;
+    private tombstones;
+    private archivedTokens;
+    private forkedTokens;
+    private transactionHistory;
+    private nametag;
+    private paymentRequests;
+    private paymentRequestHandlers;
+    private outgoingPaymentRequests;
+    private paymentRequestResponseHandlers;
+    private pendingResponseResolvers;
+    private unsubscribeTransfers;
+    private unsubscribePaymentRequests;
+    private unsubscribePaymentRequestResponses;
+    constructor(config?: PaymentsModuleConfig);
+    /** Get module configuration */
+    getConfig(): Omit<Required<PaymentsModuleConfig>, 'l1'>;
+    private log;
+    /**
+     * Initialize module with dependencies
+     */
+    initialize(deps: PaymentsModuleDependencies): void;
+    /**
+     * Load tokens from storage
+     */
+    load(): Promise<void>;
+    /**
+     * Cleanup resources
+     */
+    destroy(): void;
+    /**
+     * Send tokens to recipient
+     * Supports automatic token splitting when exact amount is needed
+     */
+    send(request: TransferRequest): Promise<TransferResult>;
+    /**
+     * Get coin symbol from coinId
+     */
+    private getCoinSymbol;
+    /**
+     * Get coin name from coinId
+     */
+    private getCoinName;
+    /**
+     * Send a payment request to someone
+     * @param recipientPubkeyOrNametag - Recipient's pubkey or @nametag
+     * @param request - Payment request details
+     * @returns Result with event ID
+     */
+    sendPaymentRequest(recipientPubkeyOrNametag: string, request: Omit<PaymentRequest, 'id' | 'createdAt'>): Promise<PaymentRequestResult>;
+    /**
+     * Subscribe to incoming payment requests
+     * @param handler - Handler function for incoming requests
+     * @returns Unsubscribe function
+     */
+    onPaymentRequest(handler: PaymentRequestHandler$1): () => void;
+    /**
+     * Get all payment requests
+     * @param filter - Optional status filter
+     */
+    getPaymentRequests(filter?: {
+        status?: PaymentRequestStatus;
+    }): IncomingPaymentRequest$1[];
+    /**
+     * Get pending payment requests count
+     */
+    getPendingPaymentRequestsCount(): number;
+    /**
+     * Accept a payment request (marks it as accepted, user should then call send())
+     */
+    acceptPaymentRequest(requestId: string): Promise<void>;
+    /**
+     * Reject a payment request
+     */
+    rejectPaymentRequest(requestId: string): Promise<void>;
+    /**
+     * Mark a payment request as paid (after successful transfer)
+     */
+    markPaymentRequestPaid(requestId: string): void;
+    /**
+     * Clear processed (non-pending) payment requests
+     */
+    clearProcessedPaymentRequests(): void;
+    /**
+     * Remove a specific payment request
+     */
+    removePaymentRequest(requestId: string): void;
+    /**
+     * Pay a payment request directly
+     * Convenience method that accepts, sends, and marks as paid
+     */
+    payPaymentRequest(requestId: string, memo?: string): Promise<TransferResult>;
+    private updatePaymentRequestStatus;
+    private handleIncomingPaymentRequest;
+    /**
+     * Get outgoing payment requests
+     * @param filter - Optional status filter
+     */
+    getOutgoingPaymentRequests(filter?: {
+        status?: PaymentRequestStatus;
+    }): OutgoingPaymentRequest[];
+    /**
+     * Subscribe to payment request responses (for outgoing requests)
+     * @param handler - Handler function for incoming responses
+     * @returns Unsubscribe function
+     */
+    onPaymentRequestResponse(handler: PaymentRequestResponseHandler$1): () => void;
+    /**
+     * Wait for a response to a payment request
+     * @param requestId - The outgoing request ID to wait for
+     * @param timeoutMs - Timeout in milliseconds (default: 60000)
+     * @returns Promise that resolves with the response or rejects on timeout
+     */
+    waitForPaymentResponse(requestId: string, timeoutMs?: number): Promise<PaymentRequestResponse>;
+    /**
+     * Cancel waiting for a payment response
+     */
+    cancelWaitForPaymentResponse(requestId: string): void;
+    /**
+     * Remove an outgoing payment request
+     */
+    removeOutgoingPaymentRequest(requestId: string): void;
+    /**
+     * Clear completed/expired outgoing payment requests
+     */
+    clearCompletedOutgoingPaymentRequests(): void;
+    private handlePaymentRequestResponse;
+    /**
+     * Send a response to a payment request (used internally by accept/reject/pay methods)
+     */
+    private sendPaymentRequestResponse;
+    /**
+     * Get balance for coin type
+     */
+    getBalance(coinId?: string): TokenBalance[];
+    /**
+     * Get all tokens
+     */
+    getTokens(filter?: {
+        coinId?: string;
+        status?: TokenStatus;
+    }): Token[];
+    /**
+     * Get single token
+     */
+    getToken(id: string): Token | undefined;
+    /**
+     * Add a token
+     * @returns false if duplicate
+     */
+    addToken(token: Token, skipHistory?: boolean): Promise<boolean>;
+    /**
+     * Save token as individual file to token storage providers
+     * Similar to lottery's saveReceivedToken() pattern
+     */
+    private saveTokenToFileStorage;
+    /**
+     * Load tokens from file storage providers (lottery compatibility)
+     * This loads tokens from file-based storage that may have been saved
+     * by other applications using the same storage directory.
+     */
+    private loadTokensFromFileStorage;
+    /**
+     * Update an existing token
+     */
+    updateToken(token: Token): Promise<void>;
+    /**
+     * Remove a token by ID
+     */
+    removeToken(tokenId: string, recipientNametag?: string, skipHistory?: boolean): Promise<void>;
+    /**
+     * Get all tombstones
+     */
+    getTombstones(): TombstoneEntry[];
+    /**
+     * Check if token state is tombstoned
+     */
+    isStateTombstoned(tokenId: string, stateHash: string): boolean;
+    /**
+     * Merge remote tombstones
+     * @returns number of local tokens removed
+     */
+    mergeTombstones(remoteTombstones: TombstoneEntry[]): Promise<number>;
+    /**
+     * Prune old tombstones
+     */
+    pruneTombstones(maxAge?: number): Promise<void>;
+    /**
+     * Get archived tokens
+     */
+    getArchivedTokens(): Map<string, TxfToken>;
+    /**
+     * Get best archived version of a token
+     */
+    getBestArchivedVersion(tokenId: string): TxfToken | null;
+    /**
+     * Merge remote archived tokens
+     * @returns number of tokens updated/added
+     */
+    mergeArchivedTokens(remoteArchived: Map<string, TxfToken>): Promise<number>;
+    /**
+     * Prune archived tokens
+     */
+    pruneArchivedTokens(maxCount?: number): Promise<void>;
+    /**
+     * Get forked tokens
+     */
+    getForkedTokens(): Map<string, TxfToken>;
+    /**
+     * Store a forked token
+     */
+    storeForkedToken(tokenId: string, stateHash: string, txfToken: TxfToken): Promise<void>;
+    /**
+     * Merge remote forked tokens
+     * @returns number of tokens added
+     */
+    mergeForkedTokens(remoteForked: Map<string, TxfToken>): Promise<number>;
+    /**
+     * Prune forked tokens
+     */
+    pruneForkedTokens(maxCount?: number): Promise<void>;
+    /**
+     * Get transaction history
+     */
+    getHistory(): TransactionHistoryEntry[];
+    /**
+     * Add to transaction history
+     */
+    addToHistory(entry: Omit<TransactionHistoryEntry, 'id'>): Promise<void>;
+    /**
+     * Set nametag for current identity
+     */
+    setNametag(nametag: NametagData): Promise<void>;
+    /**
+     * Get nametag
+     */
+    getNametag(): NametagData | null;
+    /**
+     * Check if has nametag
+     */
+    hasNametag(): boolean;
+    /**
+     * Clear nametag
+     */
+    clearNametag(): Promise<void>;
+    /**
+     * Save nametag to file storage for lottery compatibility
+     * Creates file: nametag-{name}.json
+     */
+    private saveNametagToFileStorage;
+    /**
+     * Load nametag from file storage (lottery compatibility)
+     * Looks for file: nametag-{name}.json
+     */
+    private loadNametagFromFileStorage;
+    /**
+     * Mint a nametag token on-chain (like Sphere wallet and lottery)
+     * This creates the nametag token required for receiving tokens via PROXY addresses
+     *
+     * @param nametag - The nametag to mint (e.g., "alice" or "@alice")
+     * @returns MintNametagResult with success status and token if successful
+     */
+    mintNametag(nametag: string): Promise<MintNametagResult>;
+    /**
+     * Check if a nametag is available for minting
+     * @param nametag - The nametag to check (e.g., "alice" or "@alice")
+     */
+    isNametagAvailable(nametag: string): Promise<boolean>;
+    /**
+     * Sync with all token storage providers (IPFS, MongoDB, etc.)
+     * Syncs with each provider and merges results
+     */
+    sync(): Promise<{
+        added: number;
+        removed: number;
+    }>;
+    /**
+     * Get all active token storage providers
+     */
+    private getTokenStorageProviders;
+    /**
+     * Update token storage providers (called when providers are added/removed dynamically)
+     */
+    updateTokenStorageProviders(providers: Map<string, TokenStorageProvider<TxfStorageDataBase>>): void;
+    /**
+     * Validate tokens with aggregator
+     */
+    validate(): Promise<{
+        valid: Token[];
+        invalid: Token[];
+    }>;
+    /**
+     * Get pending transfers
+     */
+    getPendingTransfers(): TransferResult[];
+    private resolveRecipient;
+    /**
+     * Create SDK TransferCommitment for a token transfer
+     */
+    private createSdkCommitment;
+    /**
+     * Create SigningService from identity private key
+     */
+    private createSigningService;
+    /**
+     * Resolve recipient to IAddress
+     */
+    private resolveRecipientAddress;
+    private handleIncomingTransfer;
+    private archiveToken;
+    private save;
+    private saveToOutbox;
+    private removeFromOutbox;
+    private loadOutbox;
+    private createStorageData;
+    private loadFromStorageData;
+    private ensureInitialized;
+}
+
+/**
+ * Communications Module
+ * Platform-independent messaging operations
+ */
+
+interface CommunicationsModuleConfig {
+    /** Auto-save messages */
+    autoSave?: boolean;
+    /** Max messages in memory */
+    maxMessages?: number;
+    /** Enable read receipts */
+    readReceipts?: boolean;
+}
+interface CommunicationsModuleDependencies {
+    identity: FullIdentity;
+    storage: StorageProvider;
+    transport: TransportProvider;
+    emitEvent: <T extends SphereEventType>(type: T, data: SphereEventMap[T]) => void;
+}
+declare class CommunicationsModule {
+    private config;
+    private deps;
+    private messages;
+    private broadcasts;
+    private unsubscribeMessages;
+    private broadcastSubscriptions;
+    private dmHandlers;
+    private broadcastHandlers;
+    constructor(config?: CommunicationsModuleConfig);
+    /**
+     * Initialize module with dependencies
+     */
+    initialize(deps: CommunicationsModuleDependencies): void;
+    /**
+     * Load messages from storage
+     */
+    load(): Promise<void>;
+    /**
+     * Cleanup resources
+     */
+    destroy(): void;
+    /**
+     * Send direct message
+     */
+    sendDM(recipient: string, content: string): Promise<DirectMessage>;
+    /**
+     * Get conversation with peer
+     */
+    getConversation(peerPubkey: string): DirectMessage[];
+    /**
+     * Get all conversations grouped by peer
+     */
+    getConversations(): Map<string, DirectMessage[]>;
+    /**
+     * Mark messages as read
+     */
+    markAsRead(messageIds: string[]): Promise<void>;
+    /**
+     * Get unread count
+     */
+    getUnreadCount(peerPubkey?: string): number;
+    /**
+     * Subscribe to incoming DMs
+     */
+    onDirectMessage(handler: (message: DirectMessage) => void): () => void;
+    /**
+     * Publish broadcast message
+     */
+    broadcast(content: string, tags?: string[]): Promise<BroadcastMessage>;
+    /**
+     * Subscribe to broadcasts with tags
+     */
+    subscribeToBroadcasts(tags: string[]): () => void;
+    /**
+     * Get broadcasts
+     */
+    getBroadcasts(limit?: number): BroadcastMessage[];
+    /**
+     * Subscribe to incoming broadcasts
+     */
+    onBroadcast(handler: (message: BroadcastMessage) => void): () => void;
+    private handleIncomingMessage;
+    private handleIncomingBroadcast;
+    private save;
+    private pruneIfNeeded;
+    private resolveRecipient;
+    private ensureInitialized;
+}
+
+/** Network configurations */
+declare const NETWORKS: {
+    readonly mainnet: {
+        readonly name: "Mainnet";
+        readonly aggregatorUrl: "https://aggregator.unicity.network/rpc";
+        readonly nostrRelays: readonly ["wss://relay.unicity.network", "wss://relay.damus.io", "wss://nos.lol", "wss://relay.nostr.band"];
+        readonly ipfsGateways: readonly ["https://ipfs.unicity.network", "https://dweb.link", "https://ipfs.io"];
+        readonly electrumUrl: "wss://fulcrum.alpha.unicity.network:50004";
+    };
+    readonly testnet: {
+        readonly name: "Testnet";
+        readonly aggregatorUrl: "https://goggregator-test.unicity.network";
+        readonly nostrRelays: readonly ["wss://nostr-relay.testnet.unicity.network"];
+        readonly ipfsGateways: readonly ["https://ipfs.unicity.network", "https://dweb.link", "https://ipfs.io"];
+        readonly electrumUrl: "wss://fulcrum.alpha.testnet.unicity.network:50004";
+    };
+    readonly dev: {
+        readonly name: "Development";
+        readonly aggregatorUrl: "https://dev-aggregator.dyndns.org/rpc";
+        readonly nostrRelays: readonly ["wss://nostr-relay.testnet.unicity.network"];
+        readonly ipfsGateways: readonly ["https://ipfs.unicity.network", "https://dweb.link", "https://ipfs.io"];
+        readonly electrumUrl: "wss://fulcrum.alpha.testnet.unicity.network:50004";
+    };
+};
+type NetworkType = keyof typeof NETWORKS;
+
+/**
+ * Legacy File Serialization Types
+ */
+
+type LegacyFileType = 'dat' | 'txt' | 'json' | 'mnemonic' | 'unknown';
+/**
+ * Progress callback for decryption operations
+ */
+type DecryptionProgressCallback = (iteration: number, total: number) => Promise<void> | void;
+
+/** Options for creating a new wallet */
+interface SphereCreateOptions {
+    /** BIP39 mnemonic (12 or 24 words) */
+    mnemonic: string;
+    /** Custom derivation path (default: m/44'/0'/0') */
+    derivationPath?: string;
+    /** Optional nametag to register for this wallet (e.g., 'alice' for @alice). Token is auto-minted. */
+    nametag?: string;
+    /** Storage provider instance */
+    storage: StorageProvider;
+    /** Optional token storage provider (for IPFS sync) */
+    tokenStorage?: TokenStorageProvider<TxfStorageDataBase>;
+    /** Transport provider instance */
+    transport: TransportProvider;
+    /** Oracle provider instance */
+    oracle: OracleProvider;
+    /** L1 (ALPHA blockchain) configuration */
+    l1?: L1Config;
+    /**
+     * Network type (mainnet, testnet, dev) - informational only.
+     * Actual network configuration comes from provider URLs.
+     * Use createBrowserProviders({ network: 'testnet' }) to set up testnet providers.
+     */
+    network?: NetworkType;
+}
+/** Options for loading existing wallet */
+interface SphereLoadOptions {
+    /** Storage provider instance */
+    storage: StorageProvider;
+    /** Optional token storage provider (for IPFS sync) */
+    tokenStorage?: TokenStorageProvider<TxfStorageDataBase>;
+    /** Transport provider instance */
+    transport: TransportProvider;
+    /** Oracle provider instance */
+    oracle: OracleProvider;
+    /** L1 (ALPHA blockchain) configuration */
+    l1?: L1Config;
+    /**
+     * Network type (mainnet, testnet, dev) - informational only.
+     * Actual network configuration comes from provider URLs.
+     * Use createBrowserProviders({ network: 'testnet' }) to set up testnet providers.
+     */
+    network?: NetworkType;
+}
+/** Options for importing a wallet */
+interface SphereImportOptions {
+    /** BIP39 mnemonic to import */
+    mnemonic?: string;
+    /** Or master private key (hex) */
+    masterKey?: string;
+    /** Chain code for BIP32 (optional) */
+    chainCode?: string;
+    /** Custom derivation path */
+    derivationPath?: string;
+    /** Base path for BIP32 derivation (e.g., "m/84'/1'/0'" from wallet.dat) */
+    basePath?: string;
+    /** Derivation mode: bip32, wif_hmac, legacy_hmac */
+    derivationMode?: DerivationMode;
+    /** Optional nametag to register for this wallet (e.g., 'alice' for @alice). Token is auto-minted. */
+    nametag?: string;
+    /** Storage provider instance */
+    storage: StorageProvider;
+    /** Optional token storage provider */
+    tokenStorage?: TokenStorageProvider<TxfStorageDataBase>;
+    /** Transport provider instance */
+    transport: TransportProvider;
+    /** Oracle provider instance */
+    oracle: OracleProvider;
+    /** L1 (ALPHA blockchain) configuration */
+    l1?: L1Config;
+}
+/** L1 (ALPHA blockchain) configuration */
+interface L1Config {
+    /** Fulcrum WebSocket URL (default: wss://fulcrum.alpha.unicity.network:50004) */
+    electrumUrl?: string;
+    /** Default fee rate in sat/byte (default: 10) */
+    defaultFeeRate?: number;
+    /** Enable vesting classification (default: true) */
+    enableVesting?: boolean;
+}
+/** Options for unified init (auto-create or load) */
+interface SphereInitOptions {
+    /** Storage provider instance */
+    storage: StorageProvider;
+    /** Transport provider instance */
+    transport: TransportProvider;
+    /** Oracle provider instance */
+    oracle: OracleProvider;
+    /** Optional token storage provider (for IPFS sync) */
+    tokenStorage?: TokenStorageProvider<TxfStorageDataBase>;
+    /** BIP39 mnemonic - if wallet doesn't exist, use this to create */
+    mnemonic?: string;
+    /** Auto-generate mnemonic if wallet doesn't exist and no mnemonic provided */
+    autoGenerate?: boolean;
+    /** Custom derivation path (default: m/44'/0'/0') */
+    derivationPath?: string;
+    /** Optional nametag to register (only on create). Token is auto-minted. */
+    nametag?: string;
+    /** L1 (ALPHA blockchain) configuration */
+    l1?: L1Config;
+    /**
+     * Network type (mainnet, testnet, dev) - informational only.
+     * Actual network configuration comes from provider URLs.
+     * Use createBrowserProviders({ network: 'testnet' }) to set up testnet providers.
+     */
+    network?: NetworkType;
+}
+/** Result of init operation */
+interface SphereInitResult {
+    /** The initialized Sphere instance */
+    sphere: Sphere;
+    /** Whether wallet was newly created */
+    created: boolean;
+    /** Generated mnemonic (only if autoGenerate was used) */
+    generatedMnemonic?: string;
+}
+declare class Sphere {
+    private static instance;
+    private _initialized;
+    private _identity;
+    private _masterKey;
+    private _mnemonic;
+    private _source;
+    private _derivationMode;
+    private _basePath;
+    private _currentAddressIndex;
+    private _addressNametags;
+    private _storage;
+    private _tokenStorageProviders;
+    private _transport;
+    private _oracle;
+    private _payments;
+    private _communications;
+    private eventHandlers;
+    private constructor();
+    /**
+     * Check if wallet exists in storage
+     */
+    static exists(storage: StorageProvider): Promise<boolean>;
+    /**
+     * Initialize wallet - auto-loads existing or creates new
+     *
+     * @example
+     * ```ts
+     * // Load existing or create with provided mnemonic
+     * const { sphere, created } = await Sphere.init({
+     *   storage,
+     *   transport,
+     *   oracle,
+     *   mnemonic: 'your twelve words...',
+     * });
+     *
+     * // Load existing or auto-generate new mnemonic
+     * const { sphere, created, generatedMnemonic } = await Sphere.init({
+     *   storage,
+     *   transport,
+     *   oracle,
+     *   autoGenerate: true,
+     * });
+     * if (generatedMnemonic) {
+     *   console.log('Save this mnemonic:', generatedMnemonic);
+     * }
+     * ```
+     */
+    static init(options: SphereInitOptions): Promise<SphereInitResult>;
+    /**
+     * Create new wallet with mnemonic
+     */
+    static create(options: SphereCreateOptions): Promise<Sphere>;
+    /**
+     * Load existing wallet from storage
+     */
+    static load(options: SphereLoadOptions): Promise<Sphere>;
+    /**
+     * Import wallet from mnemonic or master key
+     */
+    static import(options: SphereImportOptions): Promise<Sphere>;
+    /**
+     * Clear wallet data from storage
+     */
+    static clear(storage: StorageProvider): Promise<void>;
+    /**
+     * Get current instance
+     */
+    static getInstance(): Sphere | null;
+    /**
+     * Check if initialized
+     */
+    static isInitialized(): boolean;
+    /**
+     * Validate mnemonic using BIP39
+     */
+    static validateMnemonic(mnemonic: string): boolean;
+    /**
+     * Generate new BIP39 mnemonic
+     * @param strength - 128 for 12 words, 256 for 24 words
+     */
+    static generateMnemonic(strength?: 128 | 256): string;
+    /** Payments module (L3 + L1) */
+    get payments(): PaymentsModule;
+    /** Communications module */
+    get communications(): CommunicationsModule;
+    /** Current identity (public info only) */
+    get identity(): Identity | null;
+    /** Is ready */
+    get isReady(): boolean;
+    getStorage(): StorageProvider;
+    /**
+     * Get first token storage provider (for backward compatibility)
+     * @deprecated Use getTokenStorageProviders() for multiple providers
+     */
+    getTokenStorage(): TokenStorageProvider<TxfStorageDataBase> | undefined;
+    /**
+     * Get all token storage providers
+     */
+    getTokenStorageProviders(): Map<string, TokenStorageProvider<TxfStorageDataBase>>;
+    /**
+     * Add a token storage provider dynamically (e.g., from UI)
+     * Provider will be initialized and connected automatically
+     */
+    addTokenStorageProvider(provider: TokenStorageProvider<TxfStorageDataBase>): Promise<void>;
+    /**
+     * Remove a token storage provider dynamically
+     */
+    removeTokenStorageProvider(providerId: string): Promise<boolean>;
+    /**
+     * Check if a token storage provider is registered
+     */
+    hasTokenStorageProvider(providerId: string): boolean;
+    getTransport(): TransportProvider;
+    getAggregator(): OracleProvider;
+    /**
+     * Check if wallet has BIP32 master key for HD derivation
+     */
+    hasMasterKey(): boolean;
+    /**
+     * Get the base derivation path used by this wallet (e.g., "m/44'/0'/0'")
+     */
+    getBasePath(): string;
+    /**
+     * Get the default address path (first external address)
+     * Returns path like "m/44'/0'/0'/0/0"
+     */
+    getDefaultAddressPath(): string;
+    /**
+     * Get current derivation mode
+     */
+    getDerivationMode(): DerivationMode;
+    /**
+     * Get the mnemonic phrase (for backup purposes)
+     * Returns null if wallet was imported from file (masterKey only)
+     */
+    getMnemonic(): string | null;
+    /**
+     * Get wallet info for backup/export purposes
+     */
+    getWalletInfo(): WalletInfo;
+    /**
+     * Export wallet to JSON format for backup
+     *
+     * @example
+     * ```ts
+     * // Export with mnemonic (if available)
+     * const json = sphere.exportToJSON();
+     *
+     * // Export with encryption
+     * const encrypted = sphere.exportToJSON({ password: 'secret' });
+     *
+     * // Export multiple addresses
+     * const multi = sphere.exportToJSON({ addressCount: 5 });
+     * ```
+     */
+    exportToJSON(options?: WalletJSONExportOptions): WalletJSON;
+    /**
+     * Export wallet to text format for backup
+     *
+     * @example
+     * ```ts
+     * // Export unencrypted
+     * const text = sphere.exportToTxt();
+     *
+     * // Export with encryption
+     * const encrypted = sphere.exportToTxt({ password: 'secret' });
+     *
+     * // Export multiple addresses
+     * const multi = sphere.exportToTxt({ addressCount: 5 });
+     * ```
+     */
+    exportToTxt(options?: {
+        password?: string;
+        addressCount?: number;
+    }): string;
+    /**
+     * Import wallet from JSON backup
+     *
+     * @returns Object with success status and optionally recovered mnemonic
+     *
+     * @example
+     * ```ts
+     * const json = '{"version":"1.0",...}';
+     * const { success, mnemonic } = await Sphere.importFromJSON({
+     *   jsonContent: json,
+     *   password: 'secret', // if encrypted
+     *   storage, transport, oracle,
+     * });
+     * ```
+     */
+    static importFromJSON(options: {
+        jsonContent: string;
+        password?: string;
+        storage: StorageProvider;
+        transport: TransportProvider;
+        oracle: OracleProvider;
+        tokenStorage?: TokenStorageProvider<TxfStorageDataBase>;
+    }): Promise<{
+        success: boolean;
+        mnemonic?: string;
+        error?: string;
+    }>;
+    /**
+     * Import wallet from legacy file (.dat, .txt, or mnemonic text)
+     *
+     * Supports:
+     * - Bitcoin Core wallet.dat files (SQLite format, encrypted or unencrypted)
+     * - Text backup files (UNICITY WALLET DETAILS format)
+     * - Plain mnemonic text (12 or 24 words)
+     *
+     * @returns Object with success status, created Sphere instance, and optionally recovered mnemonic
+     *
+     * @example
+     * ```ts
+     * // Import from .dat file
+     * const fileBuffer = await file.arrayBuffer();
+     * const result = await Sphere.importFromLegacyFile({
+     *   fileContent: new Uint8Array(fileBuffer),
+     *   fileName: 'wallet.dat',
+     *   password: 'wallet-password', // if encrypted
+     *   storage, transport, oracle,
+     * });
+     *
+     * // Import from .txt file
+     * const textContent = await file.text();
+     * const result = await Sphere.importFromLegacyFile({
+     *   fileContent: textContent,
+     *   fileName: 'backup.txt',
+     *   storage, transport, oracle,
+     * });
+     * ```
+     */
+    static importFromLegacyFile(options: {
+        /** File content - Uint8Array for .dat, string for .txt */
+        fileContent: string | Uint8Array;
+        /** File name (used for type detection) */
+        fileName: string;
+        /** Password for encrypted files */
+        password?: string;
+        /** Progress callback for long decryption operations */
+        onDecryptProgress?: DecryptionProgressCallback;
+        /** Storage provider instance */
+        storage: StorageProvider;
+        /** Transport provider instance */
+        transport: TransportProvider;
+        /** Oracle provider instance */
+        oracle: OracleProvider;
+        /** Optional token storage provider */
+        tokenStorage?: TokenStorageProvider<TxfStorageDataBase>;
+        /** Optional nametag to register */
+        nametag?: string;
+    }): Promise<{
+        success: boolean;
+        sphere?: Sphere;
+        mnemonic?: string;
+        needsPassword?: boolean;
+        error?: string;
+    }>;
+    /**
+     * Detect legacy file type from filename and content
+     */
+    static detectLegacyFileType(fileName: string, content: string | Uint8Array): LegacyFileType;
+    /**
+     * Check if a legacy file is encrypted
+     */
+    static isLegacyFileEncrypted(fileName: string, content: string | Uint8Array): boolean;
+    /**
+     * Get the current active address index
+     *
+     * @example
+     * ```ts
+     * const currentIndex = sphere.getCurrentAddressIndex();
+     * console.log(currentIndex); // 0
+     *
+     * await sphere.switchToAddress(2);
+     * console.log(sphere.getCurrentAddressIndex()); // 2
+     * ```
+     */
+    getCurrentAddressIndex(): number;
+    /**
+     * Get nametag for a specific address index
+     *
+     * @param index - Address index (default: current address)
+     * @returns Nametag or undefined if not registered
+     */
+    getNametagForAddress(index?: number): string | undefined;
+    /**
+     * Get all registered address nametags
+     *
+     * @returns Map of address index to nametag
+     */
+    getAllAddressNametags(): Map<number, string>;
+    /**
+     * Switch to a different address by index
+     * This changes the active identity to the derived address at the specified index.
+     *
+     * @param index - Address index to switch to (0, 1, 2, ...)
+     *
+     * @example
+     * ```ts
+     * // Switch to second address
+     * await sphere.switchToAddress(1);
+     * console.log(sphere.identity?.address); // alpha1... (address at index 1)
+     *
+     * // Register nametag for this address
+     * await sphere.registerNametag('bob');
+     *
+     * // Switch back to first address
+     * await sphere.switchToAddress(0);
+     * ```
+     */
+    switchToAddress(index: number): Promise<void>;
+    /**
+     * Re-initialize modules after address switch
+     */
+    private reinitializeModulesForNewAddress;
+    /**
+     * Derive address at a specific index
+     *
+     * @param index - Address index (0, 1, 2, ...)
+     * @param isChange - Whether this is a change address (default: false)
+     * @returns Address info with privateKey, publicKey, address, path, index
+     *
+     * @example
+     * ```ts
+     * // Derive first receiving address
+     * const addr0 = sphere.deriveAddress(0);
+     * console.log(addr0.address); // alpha1...
+     *
+     * // Derive second receiving address
+     * const addr1 = sphere.deriveAddress(1);
+     *
+     * // Derive change address
+     * const change = sphere.deriveAddress(0, true);
+     * ```
+     */
+    deriveAddress(index: number, isChange?: boolean): AddressInfo;
+    /**
+     * Derive address at a full BIP32 path
+     *
+     * @param path - Full BIP32 path like "m/44'/0'/0'/0/5"
+     * @returns Address info
+     *
+     * @example
+     * ```ts
+     * const addr = sphere.deriveAddressAtPath("m/44'/0'/0'/0/5");
+     * ```
+     */
+    deriveAddressAtPath(path: string): AddressInfo;
+    /**
+     * Derive multiple addresses starting from index 0
+     *
+     * @param count - Number of addresses to derive
+     * @param includeChange - Include change addresses (default: false)
+     * @returns Array of address info
+     *
+     * @example
+     * ```ts
+     * // Get first 5 receiving addresses
+     * const addresses = sphere.deriveAddresses(5);
+     *
+     * // Get 5 receiving + 5 change addresses
+     * const allAddresses = sphere.deriveAddresses(5, true);
+     * ```
+     */
+    deriveAddresses(count: number, includeChange?: boolean): AddressInfo[];
+    getStatus(): {
+        storage: {
+            connected: boolean;
+        };
+        transport: {
+            connected: boolean;
+        };
+        oracle: {
+            connected: boolean;
+        };
+    };
+    reconnect(): Promise<void>;
+    on<T extends SphereEventType>(type: T, handler: SphereEventHandler<T>): () => void;
+    off<T extends SphereEventType>(type: T, handler: SphereEventHandler<T>): void;
+    sync(): Promise<void>;
+    /**
+     * Get current nametag (if registered)
+     */
+    getNametag(): string | undefined;
+    /**
+     * Check if nametag is registered
+     */
+    hasNametag(): boolean;
+    /**
+     * Register a nametag for the current active address
+     * Each address can have its own independent nametag
+     *
+     * @example
+     * ```ts
+     * // Register nametag for first address (index 0)
+     * await sphere.registerNametag('alice');
+     *
+     * // Switch to second address and register different nametag
+     * await sphere.switchToAddress(1);
+     * await sphere.registerNametag('bob');
+     *
+     * // Now:
+     * // - Address 0 has nametag @alice
+     * // - Address 1 has nametag @bob
+     * ```
+     */
+    registerNametag(nametag: string): Promise<void>;
+    /**
+     * Persist address nametags to storage
+     */
+    private persistAddressNametags;
+    /**
+     * Mint a nametag token on-chain (like Sphere wallet and lottery)
+     * This creates the nametag token required for receiving tokens via PROXY addresses (@nametag)
+     *
+     * @param nametag - The nametag to mint (e.g., "alice" or "@alice")
+     * @returns MintNametagResult with success status and token if successful
+     *
+     * @example
+     * ```typescript
+     * // Mint nametag token for receiving via @alice
+     * const result = await sphere.mintNametag('alice');
+     * if (result.success) {
+     *   console.log('Nametag minted:', result.nametagData?.name);
+     * } else {
+     *   console.error('Mint failed:', result.error);
+     * }
+     * ```
+     */
+    mintNametag(nametag: string): Promise<MintNametagResult>;
+    /**
+     * Check if a nametag is available for minting
+     * @param nametag - The nametag to check (e.g., "alice" or "@alice")
+     * @returns true if available, false if taken or error
+     */
+    isNametagAvailable(nametag: string): Promise<boolean>;
+    /**
+     * Load address nametags from storage
+     */
+    private loadAddressNametags;
+    /**
+     * Sync nametag with Nostr on wallet load
+     * If local nametag exists but not registered on Nostr, re-register it
+     */
+    private syncNametagWithNostr;
+    /**
+     * Validate nametag format
+     */
+    private validateNametag;
+    destroy(): Promise<void>;
+    private storeMnemonic;
+    private storeMasterKey;
+    /**
+     * Mark wallet as fully created (after successful initialization)
+     * This is called at the end of create()/import() to ensure wallet is only
+     * marked as existing after all initialization steps succeed.
+     */
+    private finalizeWalletCreation;
+    private loadIdentityFromStorage;
+    private initializeIdentityFromMnemonic;
+    private initializeIdentityFromMasterKey;
+    private initializeProviders;
+    private initializeModules;
+    private ensureReady;
+    private emitEvent;
+    private encrypt;
+    private decrypt;
+}
+declare const createSphere: typeof Sphere.create;
+declare const loadSphere: typeof Sphere.load;
+declare const importSphere: typeof Sphere.import;
+declare const initSphere: typeof Sphere.init;
+declare const getSphere: typeof Sphere.getInstance;
+declare const sphereExists: typeof Sphere.exists;
+
+/**
+ * Encryption utilities for SDK2
+ *
+ * Provides AES-256 encryption for sensitive wallet data.
+ * Uses crypto-js for cross-platform compatibility.
+ */
+interface EncryptedData {
+    /** Encrypted ciphertext (base64) */
+    ciphertext: string;
+    /** Initialization vector (hex) */
+    iv: string;
+    /** Salt used for key derivation (hex) */
+    salt: string;
+    /** Algorithm identifier */
+    algorithm: 'aes-256-cbc';
+    /** Key derivation function */
+    kdf: 'pbkdf2';
+    /** Number of PBKDF2 iterations */
+    iterations: number;
+}
+interface EncryptionOptions {
+    /** Number of PBKDF2 iterations (default: 100000) */
+    iterations?: number;
+}
+/**
+ * Encrypt data with AES-256-CBC
+ * @param plaintext - Data to encrypt (string or object)
+ * @param password - Encryption password
+ * @param options - Encryption options
+ */
+declare function encrypt(plaintext: string | object, password: string, options?: EncryptionOptions): EncryptedData;
+/**
+ * Decrypt AES-256-CBC encrypted data
+ * @param encryptedData - Encrypted data object
+ * @param password - Decryption password
+ */
+declare function decrypt(encryptedData: EncryptedData, password: string): string;
+/**
+ * Decrypt and parse JSON data
+ * @param encryptedData - Encrypted data object
+ * @param password - Decryption password
+ */
+declare function decryptJson<T = unknown>(encryptedData: EncryptedData, password: string): T;
+/**
+ * Simple encryption using CryptoJS built-in password-based encryption
+ * Suitable for localStorage where we don't need full EncryptedData metadata
+ * @param plaintext - Data to encrypt
+ * @param password - Encryption password
+ */
+declare function encryptSimple(plaintext: string, password: string): string;
+/**
+ * Simple decryption
+ * @param ciphertext - Encrypted string
+ * @param password - Decryption password
+ */
+declare function decryptSimple(ciphertext: string, password: string): string;
+/**
+ * Encrypt mnemonic phrase for storage
+ * Uses simple AES encryption compatible with existing wallet format
+ * @param mnemonic - BIP39 mnemonic phrase
+ * @param password - Encryption password
+ */
+declare function encryptMnemonic(mnemonic: string, password: string): string;
+/**
+ * Decrypt mnemonic phrase from storage
+ * @param encryptedMnemonic - Encrypted mnemonic string
+ * @param password - Decryption password
+ */
+declare function decryptMnemonic(encryptedMnemonic: string, password: string): string;
+/**
+ * Check if data looks like an EncryptedData object
+ */
+declare function isEncryptedData(data: unknown): data is EncryptedData;
+/**
+ * Serialize EncryptedData to string for storage
+ */
+declare function serializeEncrypted(data: EncryptedData): string;
+/**
+ * Deserialize EncryptedData from string
+ */
+declare function deserializeEncrypted(serialized: string): EncryptedData;
+/**
+ * Generate a random password/key as hex string
+ * @param bytes - Number of random bytes (default: 32)
+ */
+declare function generateRandomKey(bytes?: number): string;
+
+/**
+ * Currency Utilities
+ * Conversion between human-readable amounts and smallest units (bigint)
+ */
+/** Default token decimals (18 for most tokens) */
+declare const DEFAULT_TOKEN_DECIMALS = 18;
+/**
+ * Convert human-readable amount to smallest unit (bigint)
+ *
+ * @example
+ * ```ts
+ * toSmallestUnit('1.5', 18) // 1500000000000000000n
+ * toSmallestUnit('100', 6)  // 100000000n
+ * ```
+ */
+declare function toSmallestUnit(amount: number | string, decimals?: number): bigint;
+/**
+ * Convert smallest unit (bigint) to human-readable string
+ *
+ * @example
+ * ```ts
+ * toHumanReadable(1500000000000000000n, 18) // '1.5'
+ * toHumanReadable(100000000n, 6)            // '100'
+ * ```
+ */
+declare function toHumanReadable(amount: bigint | string, decimals?: number): string;
+/**
+ * Format amount for display with optional symbol
+ *
+ * @example
+ * ```ts
+ * formatAmount(1500000000000000000n, { decimals: 18, symbol: 'ALPHA' })
+ * // '1.5 ALPHA'
+ * ```
+ */
+declare function formatAmount(amount: bigint | string, options?: {
+    decimals?: number;
+    symbol?: string;
+    maxFractionDigits?: number;
+}): string;
+declare const CurrencyUtils: {
+    toSmallestUnit: typeof toSmallestUnit;
+    toHumanReadable: typeof toHumanReadable;
+    format: typeof formatAmount;
+};
+
+/**
+ * Bech32 Encoding/Decoding
+ * BIP-173 implementation for address encoding
+ */
+/** Bech32 character set from BIP-173 */
+declare const CHARSET = "qpzry9x8gf2tvdw0s3jn54khce6mua7l";
+/**
+ * Convert between bit arrays (8→5 or 5→8)
+ */
+declare function convertBits(data: number[], fromBits: number, toBits: number, pad: boolean): number[] | null;
+/**
+ * Encode data to bech32 address
+ *
+ * @example
+ * ```ts
+ * const address = encodeBech32('alpha', 1, pubkeyHash);
+ * // 'alpha1qw...'
+ * ```
+ */
+declare function encodeBech32(hrp: string, version: number, program: Uint8Array): string;
+/**
+ * Decode bech32 address
+ *
+ * @example
+ * ```ts
+ * const result = decodeBech32('alpha1qw...');
+ * // { hrp: 'alpha', witnessVersion: 1, data: Uint8Array }
+ * ```
+ */
+declare function decodeBech32(addr: string): {
+    hrp: string;
+    witnessVersion: number;
+    data: Uint8Array;
+} | null;
+/**
+ * Create address from public key hash
+ *
+ * @example
+ * ```ts
+ * const address = createAddress('alpha', pubkeyHash);
+ * // 'alpha1...'
+ * ```
+ */
+declare function createAddress(hrp: string, pubkeyHash: Uint8Array | string): string;
+/**
+ * Validate bech32 address
+ */
+declare function isValidBech32(addr: string): boolean;
+/**
+ * Get HRP from address
+ */
+declare function getAddressHrp(addr: string): string | null;
+/**
+ * Alias for encodeBech32 (L1 SDK compatibility)
+ */
+declare const createBech32: typeof encodeBech32;
+
+/**
+ * SDK Utility Functions
+ * Pure utility functions for the wallet SDK
+ */
+/**
+ * Validate if a hex string is a valid secp256k1 private key
+ * Must be 0 < key < n (curve order)
+ */
+declare function isValidPrivateKey(hex: string): boolean;
+/**
+ * Base58 encode hex string
+ *
+ * @example
+ * ```ts
+ * base58Encode('00f54a5851e9372b87810a8e60cdd2e7cfd80b6e31')
+ * // '1PMycacnJaSqwwJqjawXBErnLsZ7RkXUAs'
+ * ```
+ */
+declare function base58Encode(hex: string): string;
+/**
+ * Base58 decode string to Uint8Array
+ *
+ * @example
+ * ```ts
+ * base58Decode('1PMycacnJaSqwwJqjawXBErnLsZ7RkXUAs')
+ * // Uint8Array [0, 245, 74, ...]
+ * ```
+ */
+declare function base58Decode(str: string): Uint8Array;
+/**
+ * Find pattern in Uint8Array
+ *
+ * @param data - Data to search in
+ * @param pattern - Pattern to find
+ * @param startIndex - Start index for search
+ * @returns Index of pattern or -1 if not found
+ */
+declare function findPattern(data: Uint8Array, pattern: Uint8Array, startIndex?: number): number;
+/**
+ * Extract value from text using regex pattern
+ *
+ * @param text - Text to search
+ * @param pattern - Regex pattern with capture group
+ * @returns Captured value or null
+ */
+declare function extractFromText(text: string, pattern: RegExp): string | null;
+/**
+ * Sleep for specified milliseconds
+ */
+declare function sleep(ms: number): Promise<void>;
+/**
+ * Generate random hex string of specified byte length
+ */
+declare function randomHex(byteLength: number): string;
+/**
+ * Generate random UUID v4
+ */
+declare function randomUUID(): string;
+
+export { type AddressInfo, CHARSET, CurrencyUtils, DEFAULT_DERIVATION_PATH, DEFAULT_TOKEN_DECIMALS, type DerivedKey, type EncryptedData, type EncryptionOptions, type KeyPair, type L1Config, type MasterKey, Sphere, type SphereCreateOptions, type SphereImportOptions, type SphereInitOptions, type SphereInitResult, type SphereLoadOptions, base58Decode, base58Encode, bytesToHex, computeHash160, convertBits, createAddress, createBech32, createKeyPair, createSphere, decodeBech32, decrypt, decryptJson, decryptMnemonic, decryptSimple, deriveAddressInfo, deriveChildKey, deriveKeyAtPath, deserializeEncrypted, doubleSha256, ec, encodeBech32, encrypt, encryptMnemonic, encryptSimple, entropyToMnemonic, extractFromText, findPattern, formatAmount, generateAddressInfo, generateMasterKey, generateMnemonic, generateRandomKey, getAddressHrp, getPublicKey, getSphere, hash160, hash160ToBytes, hexToBytes, identityFromMnemonic, identityFromMnemonicSync, importSphere, initSphere, isEncryptedData, isValidBech32, isValidPrivateKey, loadSphere, mnemonicToEntropy, mnemonicToSeed, mnemonicToSeedSync, privateKeyToAddressInfo, publicKeyToAddress, randomBytes, randomHex, randomUUID, ripemd160, serializeEncrypted, sha256, sleep, sphereExists, toHumanReadable, toSmallestUnit, validateMnemonic };