@unicitylabs/sphere-sdk 0.1.0

package/dist/impl/browser/index.d.ts

@@ -0,0 +1,3016 @@
+import { StateTransitionClient } from '@unicitylabs/state-transition-sdk/lib/StateTransitionClient';
+import { AggregatorClient } from '@unicitylabs/state-transition-sdk/lib/api/AggregatorClient';
+import { RootTrustBase } from '@unicitylabs/state-transition-sdk/lib/bft/RootTrustBase';
+import { TransferCommitment as TransferCommitment$1 } from '@unicitylabs/state-transition-sdk/lib/transaction/TransferCommitment';
+import { Token as Token$1 } from '@unicitylabs/state-transition-sdk/lib/token/Token';
+
+/**
+ * Cryptographic utilities for SDK2
+ *
+ * Provides BIP39 mnemonic and BIP32 key derivation functions.
+ * Platform-independent - no browser-specific APIs.
+ */
+
+interface KeyPair {
+    privateKey: string;
+    publicKey: string;
+}
+interface AddressInfo extends KeyPair {
+    address: string;
+    path: string;
+    index: number;
+}
+
+/**
+ * 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;
+}
+
+/**
+ * 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;
+}
+
+/**
+ * Browser LocalStorage Provider
+ * Implements StorageProvider using browser localStorage
+ */
+
+interface LocalStorageProviderConfig {
+    /** Key prefix (default: 'sphere_sdk2_') */
+    prefix?: string;
+    /** Custom storage instance (for testing/SSR) */
+    storage?: Storage;
+    /** Enable debug logging */
+    debug?: boolean;
+}
+declare class LocalStorageProvider implements StorageProvider {
+    readonly id = "localStorage";
+    readonly name = "Local Storage";
+    readonly type: "local";
+    readonly description = "Browser localStorage for single-device persistence";
+    private config;
+    private identity;
+    private status;
+    constructor(config?: LocalStorageProviderConfig);
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    isConnected(): boolean;
+    getStatus(): ProviderStatus;
+    setIdentity(identity: FullIdentity): void;
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string): Promise<void>;
+    remove(key: string): Promise<void>;
+    has(key: string): Promise<boolean>;
+    keys(prefix?: string): Promise<string[]>;
+    clear(prefix?: string): Promise<void>;
+    /**
+     * Get JSON data
+     */
+    getJSON<T>(key: string): Promise<T | null>;
+    /**
+     * Set JSON data
+     */
+    setJSON<T>(key: string, value: T): Promise<void>;
+    private getFullKey;
+    private ensureConnected;
+    private getStorageSafe;
+    private log;
+}
+declare function createLocalStorageProvider(config?: LocalStorageProviderConfig): LocalStorageProvider;
+
+/**
+ * Browser IPFS Storage Provider
+ * Implements TokenStorageProvider using IPFS/IPNS for decentralized storage
+ *
+ * Uses a hybrid approach:
+ * - HTTP API to backend gateways for fast publishing/resolution
+ * - Helia for browser-based DHT operations as backup
+ */
+
+interface IpfsStorageProviderConfig {
+    /** IPFS gateway URLs for HTTP API */
+    gateways?: string[];
+    /** Bootstrap peers for DHT */
+    bootstrapPeers?: string[];
+    /** Enable IPNS for mutable addressing */
+    enableIpns?: boolean;
+    /** IPNS publish timeout (ms) */
+    ipnsTimeout?: number;
+    /** Content fetch timeout (ms) */
+    fetchTimeout?: number;
+    /** Enable debug logging */
+    debug?: boolean;
+}
+declare class IpfsStorageProvider<TData extends TxfStorageDataBase = TxfStorageDataBase> implements TokenStorageProvider<TData> {
+    readonly id = "ipfs";
+    readonly name = "IPFS Storage";
+    readonly type: "p2p";
+    readonly description = "Decentralized storage via IPFS/IPNS";
+    private config;
+    private identity;
+    private status;
+    private ipnsName;
+    private lastCid;
+    private eventCallbacks;
+    private helia;
+    private heliaJson;
+    private ipnsKeyPair;
+    /** Get the last published CID */
+    getLastCid(): string | null;
+    private localCache;
+    private cacheTimestamp;
+    constructor(config?: IpfsStorageProviderConfig);
+    connect(): Promise<void>;
+    /**
+     * Initialize Helia browser IPFS node
+     */
+    private initializeHelia;
+    disconnect(): Promise<void>;
+    isConnected(): boolean;
+    getStatus(): ProviderStatus;
+    setIdentity(identity: FullIdentity): Promise<void>;
+    initialize(): Promise<boolean>;
+    shutdown(): Promise<void>;
+    save(data: TData): Promise<SaveResult>;
+    load(identifier?: string): Promise<LoadResult<TData>>;
+    sync(localData: TData): Promise<SyncResult<TData>>;
+    exists(): Promise<boolean>;
+    clear(): Promise<boolean>;
+    onEvent(callback: StorageEventCallback): () => void;
+    private testGatewayConnectivity;
+    private publishToGateways;
+    /**
+     * Publish data via Helia (browser DHT)
+     */
+    private publishToHelia;
+    private publishToGateway;
+    private publishIpns;
+    private publishIpnsToGateway;
+    private resolveIpns;
+    private resolveIpnsFromGateway;
+    private fetchFromGateways;
+    /**
+     * Fetch content via Helia (browser DHT)
+     */
+    private fetchFromHelia;
+    private fetchFromGateway;
+    private mergeData;
+    private ensureReady;
+    /**
+     * Simple IPNS name derivation (fallback when libp2p is unavailable)
+     */
+    private deriveIpnsNameSimple;
+    /**
+     * Convert hex string to Uint8Array
+     */
+    private hexToBytes;
+    private emitEvent;
+    private log;
+}
+declare function createIpfsStorageProvider<TData extends TxfStorageDataBase = TxfStorageDataBase>(config?: IpfsStorageProviderConfig): IpfsStorageProvider<TData>;
+
+/**
+ * IndexedDB Token Storage Provider for Browser
+ * Stores tokens in IndexedDB for persistent browser storage
+ */
+
+interface IndexedDBTokenStorageConfig {
+    /** Database name prefix (default: 'sphere-token-storage') */
+    dbNamePrefix?: string;
+}
+declare class IndexedDBTokenStorageProvider implements TokenStorageProvider<TxfStorageDataBase> {
+    readonly id = "indexeddb-token-storage";
+    readonly name = "IndexedDB Token Storage";
+    readonly type: "local";
+    private dbName;
+    private db;
+    private status;
+    private identity;
+    constructor(config?: IndexedDBTokenStorageConfig);
+    setIdentity(identity: FullIdentity): void;
+    initialize(): Promise<boolean>;
+    shutdown(): Promise<void>;
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    isConnected(): boolean;
+    getStatus(): ProviderStatus;
+    load(): Promise<LoadResult<TxfStorageDataBase>>;
+    save(data: TxfStorageDataBase): Promise<SaveResult>;
+    sync(localData: TxfStorageDataBase): Promise<SyncResult<TxfStorageDataBase>>;
+    exists(): Promise<boolean>;
+    clear(): Promise<boolean>;
+    deleteToken(tokenId: string): Promise<void>;
+    saveToken(tokenId: string, tokenData: unknown): Promise<void>;
+    getToken(tokenId: string): Promise<unknown | null>;
+    listTokenIds(): Promise<string[]>;
+    private openDatabase;
+    private getFromStore;
+    private getAllFromStore;
+    private putToStore;
+    private deleteFromStore;
+    private clearStore;
+}
+declare function createIndexedDBTokenStorageProvider(config?: IndexedDBTokenStorageConfig): IndexedDBTokenStorageProvider;
+
+/**
+ * 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;
+type TransportEventType = 'transport:connected' | 'transport:disconnected' | 'transport:reconnecting' | 'transport:error' | 'transport:relay_added' | 'transport:relay_removed' | 'message:received' | 'message:sent' | 'transfer:received' | 'transfer:sent';
+interface TransportEvent {
+    type: TransportEventType;
+    timestamp: number;
+    data?: unknown;
+    error?: string;
+}
+type TransportEventCallback = (event: TransportEvent) => void;
+
+/**
+ * WebSocket Abstraction
+ * Platform-independent WebSocket interface for cross-platform support
+ */
+/**
+ * Minimal WebSocket interface compatible with browser and Node.js
+ */
+interface IWebSocket {
+    readonly readyState: number;
+    send(data: string): void;
+    close(code?: number, reason?: string): void;
+    onopen: ((event: unknown) => void) | null;
+    onclose: ((event: unknown) => void) | null;
+    onerror: ((event: unknown) => void) | null;
+    onmessage: ((event: IMessageEvent) => void) | null;
+}
+interface IMessageEvent {
+    data: string;
+}
+/**
+ * WebSocket ready states (same as native WebSocket)
+ */
+declare const WebSocketReadyState: {
+    readonly CONNECTING: 0;
+    readonly OPEN: 1;
+    readonly CLOSING: 2;
+    readonly CLOSED: 3;
+};
+/**
+ * Factory function to create WebSocket instances
+ * Different implementations for browser (native) vs Node.js (ws package)
+ */
+type WebSocketFactory = (url: string) => IWebSocket;
+/**
+ * Generate a unique ID (platform-independent)
+ * Browser: crypto.randomUUID()
+ * Node: crypto.randomUUID() or uuid package
+ */
+type UUIDGenerator = () => string;
+/**
+ * Default UUID generator using crypto.randomUUID
+ * Works in modern browsers and Node 19+
+ */
+declare function defaultUUIDGenerator(): string;
+
+/**
+ * Nostr Transport Provider
+ * Platform-independent implementation using Nostr protocol for P2P messaging
+ *
+ * Uses @unicitylabs/nostr-js-sdk for:
+ * - Real secp256k1 event signing
+ * - NIP-04 encryption/decryption
+ * - Event ID calculation
+ *
+ * WebSocket is injected via factory for cross-platform support
+ */
+
+interface NostrTransportProviderConfig {
+    /** Nostr relay URLs */
+    relays?: string[];
+    /** Connection timeout (ms) */
+    timeout?: number;
+    /** Auto-reconnect on disconnect */
+    autoReconnect?: boolean;
+    /** Reconnect delay (ms) */
+    reconnectDelay?: number;
+    /** Max reconnect attempts */
+    maxReconnectAttempts?: number;
+    /** Enable debug logging */
+    debug?: boolean;
+    /** WebSocket factory (required for platform support) */
+    createWebSocket: WebSocketFactory;
+    /** UUID generator (optional, defaults to crypto.randomUUID) */
+    generateUUID?: UUIDGenerator;
+}
+declare class NostrTransportProvider implements TransportProvider {
+    readonly id = "nostr";
+    readonly name = "Nostr Transport";
+    readonly type: "p2p";
+    readonly description = "P2P messaging via Nostr protocol";
+    private config;
+    private identity;
+    private keyManager;
+    private status;
+    private connections;
+    private reconnectAttempts;
+    private messageHandlers;
+    private transferHandlers;
+    private paymentRequestHandlers;
+    private paymentRequestResponseHandlers;
+    private broadcastHandlers;
+    private eventCallbacks;
+    private subscriptions;
+    constructor(config: NostrTransportProviderConfig);
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    isConnected(): boolean;
+    getStatus(): ProviderStatus;
+    /**
+     * Get list of configured relay URLs
+     */
+    getRelays(): string[];
+    /**
+     * Get list of currently connected relay URLs
+     */
+    getConnectedRelays(): string[];
+    /**
+     * Add a new relay dynamically
+     * Will connect immediately if provider is already connected
+     */
+    addRelay(relayUrl: string): Promise<boolean>;
+    /**
+     * Remove a relay dynamically
+     * Will disconnect from the relay if connected
+     */
+    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;
+    setIdentity(identity: FullIdentity): void;
+    /**
+     * Get the Nostr-format public key (32 bytes / 64 hex chars)
+     * This is the x-coordinate only, without the 02/03 prefix.
+     */
+    getNostrPubkey(): string;
+    sendMessage(recipientPubkey: string, content: string): Promise<string>;
+    onMessage(handler: MessageHandler): () => void;
+    sendTokenTransfer(recipientPubkey: string, payload: TokenTransferPayload): Promise<string>;
+    onTokenTransfer(handler: TokenTransferHandler): () => void;
+    sendPaymentRequest(recipientPubkey: string, payload: PaymentRequestPayload): Promise<string>;
+    onPaymentRequest(handler: PaymentRequestHandler): () => void;
+    sendPaymentRequestResponse(recipientPubkey: string, payload: PaymentRequestResponsePayload): Promise<string>;
+    onPaymentRequestResponse(handler: PaymentRequestResponseHandler): () => void;
+    resolveNametag(nametag: string): Promise<string | null>;
+    publishNametag(nametag: string, address: string): Promise<void>;
+    registerNametag(nametag: string, _publicKey: string): Promise<boolean>;
+    subscribeToBroadcast(tags: string[], handler: BroadcastHandler): () => void;
+    publishBroadcast(content: string, tags?: string[]): Promise<string>;
+    onEvent(callback: TransportEventCallback): () => void;
+    private connectToRelay;
+    private scheduleReconnect;
+    private handleRelayMessage;
+    private handleEvent;
+    private handleDirectMessage;
+    private handleTokenTransfer;
+    private handlePaymentRequest;
+    private handlePaymentRequestResponse;
+    private handleBroadcast;
+    private createEvent;
+    private createEncryptedEvent;
+    private publishEvent;
+    private queryEvents;
+    private queryEventsFromRelay;
+    private unsubscribeFromRelay;
+    private subscribeToEvents;
+    private subscribeToTags;
+    private decryptContent;
+    /**
+     * Strip known content prefixes (nostr-js-sdk compatibility)
+     * Handles: payment_request:, token_transfer:, etc.
+     */
+    private stripContentPrefix;
+    private ensureReady;
+    private emitEvent;
+    private log;
+}
+
+/**
+ * Browser Transport Exports
+ * Re-exports shared transport with browser-specific WebSocket factory
+ */
+
+/**
+ * Browser WebSocket factory using native WebSocket
+ * Cast to IWebSocket since native WebSocket is a superset
+ */
+declare function createBrowserWebSocket(url: string): IWebSocket;
+/**
+ * Create NostrTransportProvider with browser WebSocket
+ * Convenience factory that injects browser-native WebSocket
+ */
+declare function createNostrTransportProvider(config?: Omit<NostrTransportProviderConfig, 'createWebSocket'>): NostrTransportProvider;
+
+/**
+ * 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;
+}
+type OracleEventType = 'oracle:connected' | 'oracle:disconnected' | 'oracle:error' | 'commitment:submitted' | 'proof:received' | 'validation:completed';
+interface OracleEvent {
+    type: OracleEventType;
+    timestamp: number;
+    data?: unknown;
+    error?: string;
+}
+type OracleEventCallback = (event: OracleEvent) => void;
+/**
+ * Trust base loader interface for platform-specific loading
+ * Browser: fetch from URL
+ * Node.js: read from file
+ */
+interface TrustBaseLoader {
+    /**
+     * Load trust base JSON data
+     * @returns Trust base data or null if not available
+     */
+    load(): Promise<unknown | null>;
+}
+
+/**
+ * Unicity Aggregator Provider
+ * Platform-independent implementation using @unicitylabs/state-transition-sdk
+ *
+ * The oracle is a trusted service that provides verifiable truth
+ * about token state through cryptographic inclusion proofs.
+ *
+ * TrustBaseLoader is injected for platform-specific loading:
+ * - Browser: fetch from URL
+ * - Node.js: read from file
+ */
+
+interface SdkMintCommitment {
+    requestId?: {
+        toString(): string;
+    };
+    [key: string]: unknown;
+}
+interface UnicityAggregatorProviderConfig {
+    /** Aggregator URL */
+    url: string;
+    /** API key for authentication */
+    apiKey?: string;
+    /** Request timeout (ms) */
+    timeout?: number;
+    /** Skip trust base verification (dev only) */
+    skipVerification?: boolean;
+    /** Enable debug logging */
+    debug?: boolean;
+    /** Trust base loader (platform-specific) */
+    trustBaseLoader?: TrustBaseLoader;
+}
+/**
+ * Unicity Aggregator Provider
+ * Concrete implementation of OracleProvider using Unicity's aggregator service
+ */
+declare class UnicityAggregatorProvider implements OracleProvider {
+    readonly id = "unicity-aggregator";
+    readonly name = "Unicity Aggregator";
+    readonly type: "network";
+    readonly description = "Unicity state transition aggregator (oracle implementation)";
+    private config;
+    private status;
+    private eventCallbacks;
+    private aggregatorClient;
+    private stateTransitionClient;
+    private trustBase;
+    /** Get the current trust base */
+    getTrustBase(): RootTrustBase | null;
+    /** Get the state transition client */
+    getStateTransitionClient(): StateTransitionClient | null;
+    /** Get the aggregator client */
+    getAggregatorClient(): AggregatorClient | null;
+    private spentCache;
+    constructor(config: UnicityAggregatorProviderConfig);
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    isConnected(): boolean;
+    getStatus(): ProviderStatus;
+    initialize(trustBase?: RootTrustBase): Promise<void>;
+    /**
+     * Submit a transfer commitment to the aggregator.
+     * Accepts either an SDK TransferCommitment or a simple commitment object.
+     */
+    submitCommitment(commitment: TransferCommitment | TransferCommitment$1): Promise<SubmitResult>;
+    /**
+     * Submit a mint commitment to the aggregator (SDK only)
+     * @param commitment - SDK MintCommitment instance
+     */
+    submitMintCommitment(commitment: SdkMintCommitment): Promise<SubmitResult>;
+    private isSdkTransferCommitment;
+    getProof(requestId: string): Promise<InclusionProof | null>;
+    waitForProof(requestId: string, options?: WaitOptions): Promise<InclusionProof>;
+    validateToken(tokenData: unknown): Promise<ValidationResult>;
+    /**
+     * Wait for inclusion proof using SDK (for SDK commitments)
+     */
+    waitForProofSdk(commitment: TransferCommitment$1 | SdkMintCommitment, signal?: AbortSignal): Promise<unknown>;
+    isSpent(stateHash: string): Promise<boolean>;
+    getTokenState(tokenId: string): Promise<TokenState | null>;
+    getCurrentRound(): Promise<number>;
+    mint(params: MintParams): Promise<MintResult>;
+    onEvent(callback: OracleEventCallback): () => void;
+    private rpcCall;
+    private ensureConnected;
+    private emitEvent;
+    private log;
+}
+/** @deprecated Use UnicityAggregatorProvider instead */
+declare const UnicityOracleProvider: typeof UnicityAggregatorProvider;
+/** @deprecated Use UnicityAggregatorProviderConfig instead */
+type UnicityOracleProviderConfig = UnicityAggregatorProviderConfig;
+
+/**
+ * Browser Oracle Exports
+ * Re-exports shared oracle with browser-specific TrustBaseLoader
+ */
+
+/**
+ * Browser TrustBase loader using fetch
+ */
+declare class BrowserTrustBaseLoader implements TrustBaseLoader {
+    private url;
+    constructor(url?: string);
+    load(): Promise<unknown | null>;
+}
+/**
+ * Create browser TrustBase loader
+ */
+declare function createBrowserTrustBaseLoader(url?: string): TrustBaseLoader;
+/**
+ * Create UnicityAggregatorProvider with browser TrustBase loader
+ * Convenience factory that injects browser-specific loader
+ */
+declare function createUnicityAggregatorProvider(config: Omit<UnicityAggregatorProviderConfig, 'trustBaseLoader'> & {
+    trustBaseUrl?: string;
+}): UnicityAggregatorProvider;
+/** @deprecated Use createUnicityAggregatorProvider instead */
+declare const createUnicityOracleProvider: typeof createUnicityAggregatorProvider;
+
+/**
+ * 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;
+}
+
+/**
+ * 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$1;
+    /**
+     * 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$1;
+    /**
+     * 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$1;
+}
+/** L1 (ALPHA blockchain) configuration */
+interface L1Config$1 {
+    /** 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$1;
+    /**
+     * 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;
+}
+
+/**
+ * Browser Download Utilities
+ * Functions for downloading wallet backups as files
+ */
+
+interface DownloadTextOptions {
+    /** Password for encryption */
+    password?: string;
+    /** Number of addresses to include */
+    addressCount?: number;
+    /** Custom filename (without extension) */
+    filename?: string;
+}
+interface DownloadJSONOptions extends WalletJSONExportOptions {
+    /** Custom filename (without extension) */
+    filename?: string;
+    /** Pretty print JSON (default: true) */
+    pretty?: boolean;
+}
+/**
+ * Download content as a file in the browser
+ */
+declare function downloadFile(content: string | Blob, filename: string, mimeType?: string): void;
+/**
+ * Download text content as a .txt file
+ */
+declare function downloadTextFile(content: string, filename: string): void;
+/**
+ * Download JSON content as a .json file
+ */
+declare function downloadJSONFile(content: object | string, filename: string): void;
+/**
+ * Download wallet backup as text file
+ *
+ * @example
+ * ```ts
+ * // Download unencrypted backup
+ * downloadWalletText(sphere);
+ *
+ * // Download encrypted backup
+ * downloadWalletText(sphere, { password: 'secret' });
+ *
+ * // Custom filename
+ * downloadWalletText(sphere, { filename: 'my-backup' });
+ * ```
+ */
+declare function downloadWalletText(sphere: Sphere, options?: DownloadTextOptions): void;
+/**
+ * Download wallet backup as JSON file
+ *
+ * @example
+ * ```ts
+ * // Download unencrypted backup
+ * downloadWalletJSON(sphere);
+ *
+ * // Download encrypted backup
+ * downloadWalletJSON(sphere, { password: 'secret' });
+ *
+ * // Include multiple addresses
+ * downloadWalletJSON(sphere, { addressCount: 5 });
+ * ```
+ */
+declare function downloadWalletJSON(sphere: Sphere, options?: DownloadJSONOptions): void;
+/**
+ * Download pre-built WalletJSON as file
+ */
+declare function downloadWalletJSONData(json: WalletJSON, filename?: string): void;
+/**
+ * Read a file as text
+ */
+declare function readFileAsText(file: File): Promise<string>;
+/**
+ * Read a file as ArrayBuffer (for binary files like .dat)
+ */
+declare function readFileAsArrayBuffer(file: File): Promise<ArrayBuffer>;
+/**
+ * Read a file as Uint8Array (for binary files like .dat)
+ */
+declare function readFileAsUint8Array(file: File): Promise<Uint8Array>;
+
+/**
+ * Shared Configuration Interfaces
+ * Base types extended by platform-specific implementations
+ */
+
+/**
+ * Base transport (Nostr) configuration
+ * Supports extend/override pattern for relays
+ */
+interface BaseTransportConfig {
+    /** Replace default relays entirely */
+    relays?: string[];
+    /** Add relays to network defaults (use with network preset) */
+    additionalRelays?: string[];
+    /** Connection timeout (ms) */
+    timeout?: number;
+    /** Auto-reconnect on disconnect */
+    autoReconnect?: boolean;
+    /** Enable debug logging */
+    debug?: boolean;
+}
+/**
+ * Browser-specific transport extensions
+ */
+interface BrowserTransportExtensions {
+    /** Reconnect delay (ms) */
+    reconnectDelay?: number;
+    /** Max reconnect attempts */
+    maxReconnectAttempts?: number;
+}
+/**
+ * Base oracle (Aggregator) configuration
+ */
+interface BaseOracleConfig {
+    /** Replace default aggregator URL (if not set, uses network default) */
+    url?: string;
+    /** API key for authentication */
+    apiKey?: string;
+    /** Request timeout (ms) */
+    timeout?: number;
+    /** Skip trust base verification (dev only) */
+    skipVerification?: boolean;
+    /** Enable debug logging */
+    debug?: boolean;
+}
+/**
+ * L1 (ALPHA blockchain) configuration
+ * Same for all platforms
+ */
+interface L1Config {
+    /** Fulcrum WebSocket URL (if not set, uses network default) */
+    electrumUrl?: string;
+    /** Default fee rate in sat/byte */
+    defaultFeeRate?: number;
+    /** Enable vesting classification */
+    enableVesting?: boolean;
+}
+/**
+ * Base providers result
+ * Common structure for all platforms
+ */
+interface BaseProviders {
+    storage: StorageProvider;
+    tokenStorage: TokenStorageProvider<TxfStorageDataBase>;
+    transport: TransportProvider;
+    oracle: OracleProvider;
+    /** L1 configuration (for passing to Sphere.init) */
+    l1?: L1Config;
+}
+
+/**
+ * Browser-specific implementations
+ * All platform-dependent code lives here
+ */
+
+/**
+ * Browser transport configuration
+ * Extends base with browser-specific options
+ */
+type TransportConfig = BaseTransportConfig & BrowserTransportExtensions;
+/**
+ * Browser oracle configuration
+ * Same as base (no browser-specific extensions)
+ */
+type OracleConfig = BaseOracleConfig;
+/**
+ * IPFS sync backend configuration
+ */
+interface IpfsSyncConfig {
+    /** Enable IPFS sync (default: false) */
+    enabled?: boolean;
+    /** Replace default gateways entirely */
+    gateways?: string[];
+    /** Add gateways to network defaults */
+    additionalGateways?: string[];
+    /** Replace default bootstrap peers */
+    bootstrapPeers?: string[];
+    /** Add bootstrap peers to defaults */
+    additionalBootstrapPeers?: string[];
+    /** Use browser DHT (Helia) vs HTTP-only mode */
+    useDht?: boolean;
+}
+/**
+ * File sync backend configuration (future)
+ */
+interface FileSyncConfig {
+    /** Enable file sync (default: false) */
+    enabled?: boolean;
+    /** Directory path for token files */
+    directory?: string;
+    /** File format: 'json' | 'txf' */
+    format?: 'json' | 'txf';
+}
+/**
+ * Cloud sync backend configuration (future)
+ */
+interface CloudSyncConfig {
+    /** Enable cloud sync (default: false) */
+    enabled?: boolean;
+    /** Cloud provider */
+    provider?: 'aws' | 'gcp' | 'azure' | 'custom';
+    /** Bucket/container name */
+    bucket?: string;
+    /** API endpoint (for custom provider) */
+    endpoint?: string;
+    /** API key or credentials */
+    apiKey?: string;
+}
+/**
+ * MongoDB sync backend configuration
+ */
+interface MongoDbSyncConfig {
+    /** Enable MongoDB sync (default: false) */
+    enabled?: boolean;
+    /** MongoDB connection URI */
+    uri?: string;
+    /** Database name */
+    database?: string;
+    /** Collection name (default: 'tokens') */
+    collection?: string;
+    /** Enable authentication */
+    authEnabled?: boolean;
+    /** Username (if authEnabled) */
+    username?: string;
+    /** Password (if authEnabled) */
+    password?: string;
+}
+/**
+ * Token sync configuration - supports multiple backends
+ */
+interface TokenSyncConfig {
+    /** IPFS sync backend */
+    ipfs?: IpfsSyncConfig;
+    /** File sync backend (future) */
+    file?: FileSyncConfig;
+    /** Cloud sync backend (future) */
+    cloud?: CloudSyncConfig;
+    /** MongoDB sync backend */
+    mongodb?: MongoDbSyncConfig;
+}
+interface BrowserProvidersConfig {
+    /** Network preset: mainnet, testnet, or dev. Sets default URLs for all services */
+    network?: NetworkType;
+    /** Storage configuration (localStorage) */
+    storage?: LocalStorageProviderConfig;
+    /** Transport (Nostr) configuration - supports extend/override pattern */
+    transport?: TransportConfig;
+    /** Oracle (Aggregator) configuration - supports extend/override pattern */
+    oracle?: OracleConfig;
+    /** L1 (ALPHA blockchain) configuration */
+    l1?: L1Config;
+    /**
+     * Token sync backends configuration
+     * Supports multiple backends: IPFS, file, cloud (future)
+     * Each backend can be enabled/disabled independently
+     */
+    tokenSync?: TokenSyncConfig;
+}
+interface BrowserProviders {
+    storage: StorageProvider;
+    transport: TransportProvider;
+    oracle: OracleProvider;
+    /** Token storage provider for local persistence (IndexedDB) */
+    tokenStorage: TokenStorageProvider<TxfStorageDataBase>;
+    /** L1 configuration (for passing to Sphere.init) */
+    l1?: L1Config;
+    /**
+     * Token sync configuration (resolved from tokenSync options)
+     * For advanced use cases when additional sync backends are needed
+     * @deprecated Use tokenStorage provider instead. For custom sync backends,
+     * use Sphere.addTokenStorageProvider() after initialization.
+     */
+    tokenSyncConfig?: {
+        ipfs?: {
+            enabled: boolean;
+            gateways: string[];
+            bootstrapPeers?: string[];
+            useDht?: boolean;
+        };
+        file?: {
+            enabled: boolean;
+            directory?: string;
+            format?: 'json' | 'txf';
+        };
+        cloud?: {
+            enabled: boolean;
+            provider?: string;
+            bucket?: string;
+            endpoint?: string;
+            apiKey?: string;
+        };
+        mongodb?: {
+            enabled: boolean;
+            uri?: string;
+            database?: string;
+            collection?: string;
+        };
+    };
+}
+/**
+ * Create all browser providers with default configuration
+ *
+ * Supports extend/override pattern for flexible configuration:
+ * - Use `network` preset for quick setup (mainnet/testnet/dev)
+ * - Override specific values (e.g., `oracle.url` replaces default)
+ * - Extend arrays with `additional*` (e.g., `additionalRelays` adds to defaults)
+ *
+ * @example
+ * ```ts
+ * // Simple - uses mainnet defaults
+ * const providers = createBrowserProviders();
+ *
+ * // Testnet - all services use testnet URLs
+ * const providers = createBrowserProviders({ network: 'testnet' });
+ *
+ * // Add extra relays to testnet defaults
+ * const providers = createBrowserProviders({
+ *   network: 'testnet',
+ *   transport: {
+ *     additionalRelays: ['wss://my-relay.com', 'wss://backup-relay.com'],
+ *   },
+ * });
+ *
+ * // Replace relays entirely (ignores network defaults)
+ * const providers = createBrowserProviders({
+ *   network: 'testnet',
+ *   transport: {
+ *     relays: ['wss://only-this-relay.com'],
+ *   },
+ * });
+ *
+ * // Use with Sphere.init (tokenStorage is automatically included)
+ * const { sphere } = await Sphere.init({
+ *   ...providers,
+ *   autoGenerate: true,
+ * });
+ *
+ * // Add additional sync backends dynamically after init
+ * // await sphere.addTokenStorageProvider(myMongoDbProvider);
+ * ```
+ */
+declare function createBrowserProviders(config?: BrowserProvidersConfig): BrowserProviders;
+
+export { type BaseOracleConfig, type BaseProviders, type BaseTransportConfig, type BrowserProviders, type BrowserProvidersConfig, BrowserTrustBaseLoader, type CloudSyncConfig, type DownloadJSONOptions, type DownloadTextOptions, type FileSyncConfig, type IMessageEvent, type IWebSocket, type IndexedDBTokenStorageConfig, IndexedDBTokenStorageProvider, IpfsStorageProvider, type IpfsStorageProviderConfig, type IpfsSyncConfig, type L1Config, LocalStorageProvider, type LocalStorageProviderConfig, type MongoDbSyncConfig, NostrTransportProvider, type NostrTransportProviderConfig, type OracleConfig, type TokenSyncConfig, type TransportConfig, type TrustBaseLoader, type UUIDGenerator, UnicityAggregatorProvider, type UnicityAggregatorProviderConfig, UnicityOracleProvider, type UnicityOracleProviderConfig, type WebSocketFactory, WebSocketReadyState, createBrowserProviders, createBrowserTrustBaseLoader, createBrowserWebSocket, createIndexedDBTokenStorageProvider, createIpfsStorageProvider, createLocalStorageProvider, createNostrTransportProvider, createUnicityAggregatorProvider, createUnicityOracleProvider, defaultUUIDGenerator, downloadFile, downloadJSONFile, downloadTextFile, downloadWalletJSON, downloadWalletJSONData, downloadWalletText, readFileAsArrayBuffer, readFileAsText, readFileAsUint8Array };