@unicitylabs/sphere-sdk 0.6.2 → 0.6.3

package/dist/core/index.d.ts

@@ -1,4 +1,5 @@
 import { Token as Token$1 } from '@unicitylabs/state-transition-sdk/lib/token/Token';
+import { NostrClient, NostrKeyManager } from '@unicitylabs/nostr-js-sdk';
 import elliptic from 'elliptic';
 
 /**
@@ -1144,6 +1145,13 @@ interface TokenStorageProvider<TData = unknown> extends BaseProvider {
      * Clear all data
      */
     clear?(): Promise<boolean>;
+    /**
+     * Create a new independent instance of this provider for a different address.
+     * Used by per-address module architecture — each address gets its own
+     * TokenStorageProvider instance to avoid cross-address data contamination.
+     * If not implemented, the provider cannot be used in multi-address mode.
+     */
+    createForAddress?(): TokenStorageProvider<TData>;
     /**
      * Subscribe to storage events
      */
@@ -1400,6 +1408,16 @@ interface TransportProvider extends BaseProvider {
      * @returns Unsubscribe function
      */
     onInstantSplitReceived?(handler: InstantSplitBundleHandler): () => void;
+    /**
+     * Set fallback 'since' timestamp for event subscriptions.
+     * Used when switching to an address that has never subscribed before.
+     * The transport uses this instead of 'now' as the initial since filter,
+     * ensuring events sent while the address was inactive are not missed.
+     * Consumed once by the next subscription setup, then cleared.
+     *
+     * @param sinceSeconds - Unix timestamp in seconds
+     */
+    setFallbackSince?(sinceSeconds: number): void;
     /**
      * Fetch pending events from transport (one-shot query).
      * Creates a temporary subscription, processes events through normal handlers,
@@ -1551,6 +1569,14 @@ interface IncomingBroadcast {
     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;
 /**
  * Resolved peer identity information.
  * Returned by resolve methods — contains all public address formats for a peer.
@@ -1592,6 +1618,280 @@ interface IncomingTypingIndicator {
 type TypingIndicatorHandler = (indicator: IncomingTypingIndicator) => void;
 type ComposingHandler = (indicator: ComposingIndicator) => 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;
+}
+/**
+ * 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;
+
+/**
+ * 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
+ * - NostrClient for reliable connection management (ping, reconnect, NIP-42)
+ *
+ * WebSocket is injected via factory for cross-platform support
+ */
+
+/**
+ * Minimal key-value storage interface for transport persistence.
+ * Used to persist the last processed event timestamp across sessions.
+ */
+interface TransportStorageAdapter {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string): Promise<void>;
+}
+
+/**
+ * Multi-Address Transport Multiplexer
+ *
+ * Wraps a single NostrTransportProvider to support multiple HD addresses
+ * simultaneously. Each address gets a lightweight AddressTransportAdapter
+ * that implements TransportProvider but shares the single WebSocket connection.
+ *
+ * Event routing:
+ * - Wallet events (kind 4, 31113, 31115, 31116): routed by #p tag (recipient pubkey)
+ * - Chat events (kind 1059 gift wrap): try decrypt with each address keyManager
+ *
+ * Sending: each adapter delegates to the inner transport with its own keyManager.
+ */
+
+interface MultiAddressTransportMuxConfig {
+    relays?: string[];
+    timeout?: number;
+    autoReconnect?: boolean;
+    reconnectDelay?: number;
+    maxReconnectAttempts?: number;
+    createWebSocket: WebSocketFactory;
+    generateUUID?: UUIDGenerator;
+    storage?: TransportStorageAdapter;
+}
+declare class MultiAddressTransportMux {
+    private config;
+    private storage;
+    private nostrClient;
+    private primaryKeyManager;
+    private status;
+    private addresses;
+    private pubkeyToIndex;
+    private walletSubscriptionId;
+    private chatSubscriptionId;
+    private chatEoseFired;
+    private chatEoseHandlers;
+    private processedEventIds;
+    private eventCallbacks;
+    constructor(config: MultiAddressTransportMuxConfig);
+    /**
+     * Add an address to the multiplexer.
+     * Creates an AddressTransportAdapter for this address.
+     * If already connected, updates subscriptions to include the new pubkey.
+     */
+    addAddress(index: number, identity: FullIdentity, resolveDelegate?: TransportProvider | null): Promise<AddressTransportAdapter>;
+    /**
+     * Remove an address from the multiplexer.
+     * Stops routing events to this address.
+     */
+    removeAddress(index: number): Promise<void>;
+    /**
+     * Get adapter for a specific address index.
+     */
+    getAdapter(index: number): AddressTransportAdapter | undefined;
+    /**
+     * Set fallback 'since' for an address (consumed once on next subscription setup).
+     */
+    setFallbackSince(index: number, sinceSeconds: number): void;
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    isConnected(): boolean;
+    getStatus(): ProviderStatus;
+    getRelays(): string[];
+    getConnectedRelays(): string[];
+    addRelay(relayUrl: string): Promise<boolean>;
+    removeRelay(relayUrl: string): Promise<boolean>;
+    hasRelay(relayUrl: string): boolean;
+    isRelayConnected(relayUrl: string): boolean;
+    /**
+     * Update Nostr subscriptions to listen for events on ALL registered address pubkeys.
+     * Called whenever addresses are added/removed.
+     */
+    private updateSubscriptions;
+    /**
+     * Determine 'since' timestamp for an address entry.
+     */
+    private getAddressSince;
+    /**
+     * Route an incoming Nostr event to the correct address adapter.
+     */
+    private handleEvent;
+    /**
+     * Extract recipient pubkey from event's #p tag.
+     * Returns the first #p value that matches a known address pubkey,
+     * or the first #p value if none match.
+     */
+    private extractRecipientPubkey;
+    /**
+     * Route a gift wrap event by trying decryption with each address keyManager.
+     */
+    private routeGiftWrap;
+    /**
+     * Dispatch a wallet event (non-gift-wrap) to the correct address adapter.
+     */
+    private dispatchWalletEvent;
+    private handleTokenTransfer;
+    private handlePaymentRequest;
+    private handlePaymentRequestResponse;
+    private decryptContent;
+    private stripContentPrefix;
+    /**
+     * Create an encrypted event using a specific address's keyManager.
+     * Used by AddressTransportAdapter for sending.
+     */
+    createAndPublishEncryptedEvent(addressIndex: number, kind: number, content: string, tags: string[][]): Promise<string>;
+    /**
+     * Create and publish a NIP-17 gift wrap message for a specific address.
+     */
+    sendGiftWrap(addressIndex: number, recipientPubkey: string, content: string): Promise<string>;
+    /**
+     * Publish a raw event (e.g., identity binding, broadcast).
+     */
+    publishRawEvent(addressIndex: number, kind: number, content: string, tags: string[][]): Promise<string>;
+    /**
+     * Get the NostrClient for resolve operations.
+     * Adapters use this for resolve*, publishIdentityBinding, etc.
+     */
+    getNostrClient(): NostrClient | null;
+    /**
+     * Get keyManager for a specific address (used by adapters for resolve/binding).
+     */
+    getKeyManager(addressIndex: number): NostrKeyManager | null;
+    /**
+     * Get identity for a specific address.
+     */
+    getIdentity(addressIndex: number): FullIdentity | null;
+    private updateLastEventTimestamp;
+    onTransportEvent(callback: TransportEventCallback): () => void;
+    onChatReady(handler: () => void): () => void;
+    private emitEvent;
+    /**
+     * Clear processed event IDs (e.g., on address change or periodic cleanup).
+     */
+    clearProcessedEvents(): void;
+    /**
+     * Get the storage adapter (for adapters that need it).
+     */
+    getStorage(): TransportStorageAdapter | null;
+    /**
+     * Get the UUID generator.
+     */
+    getUUIDGenerator(): UUIDGenerator;
+}
+/**
+ * Lightweight TransportProvider implementation for a single address.
+ * Does NOT own a WebSocket — delegates to MultiAddressTransportMux.
+ * Each per-address module (PaymentsModule, CommunicationsModule) uses one of these.
+ */
+declare class AddressTransportAdapter implements TransportProvider {
+    readonly id: string;
+    readonly name: string;
+    readonly type: "p2p";
+    readonly description: string;
+    private mux;
+    private addressIndex;
+    private identity;
+    private resolveDelegate;
+    private messageHandlers;
+    private transferHandlers;
+    private paymentRequestHandlers;
+    private paymentRequestResponseHandlers;
+    private readReceiptHandlers;
+    private typingIndicatorHandlers;
+    private composingHandlers;
+    private instantSplitBundleHandlers;
+    private broadcastHandlers;
+    private eventCallbacks;
+    private pendingMessages;
+    private chatEoseHandlers;
+    constructor(mux: MultiAddressTransportMux, addressIndex: number, identity: FullIdentity, resolveDelegate?: TransportProvider | null);
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    isConnected(): boolean;
+    getStatus(): ProviderStatus;
+    setIdentity(identity: FullIdentity): Promise<void>;
+    sendMessage(recipientPubkey: string, content: string): Promise<string>;
+    sendTokenTransfer(recipientPubkey: string, payload: TokenTransferPayload): Promise<string>;
+    sendPaymentRequest(recipientPubkey: string, payload: PaymentRequestPayload): Promise<string>;
+    sendPaymentRequestResponse(recipientPubkey: string, response: PaymentRequestResponsePayload): Promise<string>;
+    sendReadReceipt(recipientPubkey: string, messageEventId: string): Promise<void>;
+    sendTypingIndicator(recipientPubkey: string): Promise<void>;
+    sendComposingIndicator(recipientPubkey: string, content: string): Promise<void>;
+    sendInstantSplitBundle(recipientPubkey: string, bundle: InstantSplitBundlePayload): Promise<string>;
+    onMessage(handler: MessageHandler): () => void;
+    onTokenTransfer(handler: TokenTransferHandler): () => void;
+    onPaymentRequest(handler: PaymentRequestHandler): () => void;
+    onPaymentRequestResponse(handler: PaymentRequestResponseHandler): () => void;
+    onReadReceipt(handler: ReadReceiptHandler): () => void;
+    onTypingIndicator(handler: TypingIndicatorHandler): () => void;
+    onComposing(handler: ComposingHandler): () => void;
+    onInstantSplitReceived(handler: InstantSplitBundleHandler): () => void;
+    subscribeToBroadcast(tags: string[], handler: BroadcastHandler): () => void;
+    publishBroadcast(content: string, tags?: string[]): Promise<string>;
+    resolve(identifier: string): Promise<PeerInfo | null>;
+    resolveNametag(nametag: string): Promise<string | null>;
+    resolveNametagInfo(nametag: string): Promise<PeerInfo | null>;
+    resolveAddressInfo(address: string): Promise<PeerInfo | null>;
+    resolveTransportPubkeyInfo(transportPubkey: string): Promise<PeerInfo | null>;
+    discoverAddresses(transportPubkeys: string[]): Promise<PeerInfo[]>;
+    recoverNametag(): Promise<string | null>;
+    publishIdentityBinding(chainPubkey: string, l1Address: string, directAddress: string, nametag?: string): Promise<boolean>;
+    getRelays(): string[];
+    getConnectedRelays(): string[];
+    addRelay(relayUrl: string): Promise<boolean>;
+    removeRelay(relayUrl: string): Promise<boolean>;
+    hasRelay(relayUrl: string): boolean;
+    isRelayConnected(relayUrl: string): boolean;
+    setFallbackSince(sinceSeconds: number): void;
+    fetchPendingEvents(): Promise<void>;
+    onChatReady(handler: () => void): () => void;
+    dispatchMessage(message: IncomingMessage): void;
+    dispatchTokenTransfer(transfer: IncomingTokenTransfer): void;
+    dispatchPaymentRequest(request: IncomingPaymentRequest): void;
+    dispatchPaymentRequestResponse(response: IncomingPaymentRequestResponse): void;
+    dispatchReadReceipt(receipt: IncomingReadReceipt): void;
+    dispatchTypingIndicator(indicator: IncomingTypingIndicator): void;
+    dispatchComposingIndicator(indicator: any): void;
+    dispatchInstantSplitBundle(bundle: IncomingInstantSplitBundle): void;
+    emitTransportEvent(event: TransportEvent): void;
+}
+
 /**
  * L1 Payments Sub-Module
  *
@@ -3594,6 +3894,21 @@ interface SphereInitResult {
     /** Generated mnemonic (only if autoGenerate was used) */
     generatedMnemonic?: string;
 }
+/**
+ * Holds all per-address module instances.
+ * Each HD address gets its own set so modules can run independently in background.
+ */
+interface AddressModuleSet {
+    index: number;
+    identity: FullIdentity;
+    payments: PaymentsModule;
+    communications: CommunicationsModule;
+    groupChat: GroupChatModule | null;
+    market: MarketModule | null;
+    transportAdapter: AddressTransportAdapter | null;
+    tokenStorageProviders: Map<string, TokenStorageProvider<TxfStorageDataBase>>;
+    initialized: boolean;
+}
 declare class Sphere {
     private static instance;
     private _initialized;
@@ -3622,6 +3937,11 @@ declare class Sphere {
     private _communications;
     private _groupChat;
     private _market;
+    private _addressModules;
+    private _transportMux;
+    private _l1Config;
+    private _groupChatConfig;
+    private _marketConfig;
     private eventHandlers;
     private _disabledProviders;
     private _providerEventCleanups;
@@ -4017,9 +4337,28 @@ declare class Sphere {
      */
     private postSwitchSync;
     /**
-     * Re-initialize modules after address switch
+     * Create a new set of per-address modules for the given index.
+     * Each address gets its own PaymentsModule, CommunicationsModule, etc.
+     * Modules are fully independent — they have their own token storage,
+     * and can sync/finalize/split in background regardless of active address.
+     *
+     * @param index - HD address index
+     * @param identity - Full identity for this address
+     * @param tokenStorageProviders - Token storage providers for this address
+     */
+    private initializeAddressModules;
+    /**
+     * Ensure the transport multiplexer exists and register an address.
+     * Creates the mux on first call. Returns an AddressTransportAdapter
+     * that routes events for this address independently.
+     * @returns AddressTransportAdapter or null if transport is not Nostr-based
+     */
+    private ensureTransportMux;
+    /**
+     * Get per-address modules for any address index (creates lazily if needed).
+     * This allows accessing any address's modules without switching.
      */
-    private reinitializeModulesForNewAddress;
+    getAddressPayments(index: number): PaymentsModule | undefined;
     /**
      * Derive address at a specific index
      *
@@ -4750,4 +5089,4 @@ interface CheckNetworkHealthOptions {
  */
 declare function checkNetworkHealth(network?: NetworkType, options?: CheckNetworkHealthOptions): Promise<NetworkHealthResult>;
 
-export { type AddressInfo, CHARSET, type CheckNetworkHealthOptions, CurrencyUtils, DEFAULT_DERIVATION_PATH, DEFAULT_TOKEN_DECIMALS, type DerivedKey, type DiscoverAddressProgress, type DiscoverAddressesOptions, type DiscoverAddressesResult, type DiscoveredAddress, type EncryptedData, type EncryptionOptions, type InitProgress, type InitProgressCallback, type InitProgressStep, type KeyPair, type L1Config, type LogHandler, type LogLevel, type LoggerConfig, type MasterKey, SIGN_MESSAGE_PREFIX, type ScanAddressProgress, type ScanAddressesOptions, type ScanAddressesResult, type ScannedAddressResult, Sphere, type SphereCreateOptions, SphereError, type SphereErrorCode, type SphereImportOptions, type SphereInitOptions, type SphereInitResult, type SphereLoadOptions, base58Decode, base58Encode, bytesToHex, checkNetworkHealth, computeHash160, convertBits, createAddress, createBech32, createKeyPair, createSphere, decodeBech32, decrypt, decryptJson, decryptMnemonic, decryptSimple, decryptWithSalt, deriveAddressInfo, deriveChildKey, deriveKeyAtPath, deserializeEncrypted, discoverAddressesImpl, doubleSha256, ec, encodeBech32, encrypt, encryptMnemonic, encryptSimple, entropyToMnemonic, extractFromText, findPattern, formatAmount, generateAddressInfo, generateMasterKey, generateMnemonic, generateRandomKey, getAddressHrp, getPublicKey, getSphere, hash160, hash160ToBytes, hashSignMessage, hexToBytes, identityFromMnemonic, identityFromMnemonicSync, importSphere, initSphere, isEncryptedData, isSphereError, isValidBech32, isValidNametag, isValidPrivateKey, loadSphere, logger, mnemonicToEntropy, mnemonicToSeed, mnemonicToSeedSync, privateKeyToAddressInfo, publicKeyToAddress, randomBytes, randomHex, randomUUID, ripemd160, scanAddressesImpl, serializeEncrypted, sha256, signMessage, sleep, sphereExists, toHumanReadable, toSmallestUnit, validateMnemonic, verifySignedMessage };
+export { type AddressInfo, type AddressModuleSet, CHARSET, type CheckNetworkHealthOptions, CurrencyUtils, DEFAULT_DERIVATION_PATH, DEFAULT_TOKEN_DECIMALS, type DerivedKey, type DiscoverAddressProgress, type DiscoverAddressesOptions, type DiscoverAddressesResult, type DiscoveredAddress, type EncryptedData, type EncryptionOptions, type InitProgress, type InitProgressCallback, type InitProgressStep, type KeyPair, type L1Config, type LogHandler, type LogLevel, type LoggerConfig, type MasterKey, SIGN_MESSAGE_PREFIX, type ScanAddressProgress, type ScanAddressesOptions, type ScanAddressesResult, type ScannedAddressResult, Sphere, type SphereCreateOptions, SphereError, type SphereErrorCode, type SphereImportOptions, type SphereInitOptions, type SphereInitResult, type SphereLoadOptions, base58Decode, base58Encode, bytesToHex, checkNetworkHealth, computeHash160, convertBits, createAddress, createBech32, createKeyPair, createSphere, decodeBech32, decrypt, decryptJson, decryptMnemonic, decryptSimple, decryptWithSalt, deriveAddressInfo, deriveChildKey, deriveKeyAtPath, deserializeEncrypted, discoverAddressesImpl, doubleSha256, ec, encodeBech32, encrypt, encryptMnemonic, encryptSimple, entropyToMnemonic, extractFromText, findPattern, formatAmount, generateAddressInfo, generateMasterKey, generateMnemonic, generateRandomKey, getAddressHrp, getPublicKey, getSphere, hash160, hash160ToBytes, hashSignMessage, hexToBytes, identityFromMnemonic, identityFromMnemonicSync, importSphere, initSphere, isEncryptedData, isSphereError, isValidBech32, isValidNametag, isValidPrivateKey, loadSphere, logger, mnemonicToEntropy, mnemonicToSeed, mnemonicToSeedSync, privateKeyToAddressInfo, publicKeyToAddress, randomBytes, randomHex, randomUUID, ripemd160, scanAddressesImpl, serializeEncrypted, sha256, signMessage, sleep, sphereExists, toHumanReadable, toSmallestUnit, validateMnemonic, verifySignedMessage };