@unicitylabs/sphere-sdk 0.1.3 → 0.1.5

package/dist/core/index.d.ts

@@ -290,11 +290,12 @@ interface BaseProvider extends ProviderMetadata {
     getStatus(): ProviderStatus;
 }
 interface Identity {
-    readonly publicKey: string;
+    /** 33-byte compressed secp256k1 public key (for L3 chain) */
+    readonly chainPubkey: string;
     /** L1 address (alpha1...) */
-    readonly address: string;
-    /** L3 predicate address (DIRECT://...) */
-    readonly predicateAddress?: string;
+    readonly l1Address: string;
+    /** L3 DIRECT address (DIRECT://...) */
+    readonly directAddress?: string;
     readonly ipnsName?: string;
     readonly nametag?: string;
 }
@@ -307,6 +308,8 @@ interface Token {
     readonly coinId: string;
     readonly symbol: string;
     readonly name: string;
+    readonly decimals: number;
+    readonly iconUrl?: string;
     readonly amount: string;
     status: TokenStatus;
     readonly createdAt: number;
@@ -479,7 +482,7 @@ interface BroadcastMessage {
     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';
+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' | 'nametag:recovered' | 'identity:changed';
 interface SphereEventMap {
     'transfer:incoming': IncomingTransfer;
     'transfer:confirmed': TransferResult;
@@ -517,10 +520,13 @@ interface SphereEventMap {
         nametag: string;
         addressIndex: number;
     };
+    'nametag:recovered': {
+        nametag: string;
+    };
     'identity:changed': {
-        address: string;
-        predicateAddress?: string;
-        publicKey: string;
+        l1Address: string;
+        directAddress?: string;
+        chainPubkey: string;
         nametag?: string;
         addressIndex: number;
     };
@@ -584,6 +590,245 @@ interface WalletJSONExportOptions {
     addressCount?: number;
 }
 
+/**
+ * Transport Provider Interface
+ * Platform-independent P2P messaging abstraction
+ */
+
+/**
+ * P2P messaging transport provider
+ */
+interface TransportProvider extends BaseProvider {
+    /**
+     * Set identity for signing/encryption
+     */
+    setIdentity(identity: FullIdentity): void;
+    /**
+     * Send encrypted direct message
+     * @param recipientTransportPubkey - Transport-specific pubkey for messaging
+     * @returns Event ID
+     */
+    sendMessage(recipientTransportPubkey: string, content: string): Promise<string>;
+    /**
+     * Subscribe to incoming direct messages
+     * @returns Unsubscribe function
+     */
+    onMessage(handler: MessageHandler): () => void;
+    /**
+     * Send token transfer payload
+     * @param recipientTransportPubkey - Transport-specific pubkey for messaging
+     * @returns Event ID
+     */
+    sendTokenTransfer(recipientTransportPubkey: 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>;
+    /**
+     * Resolve nametag to full address information
+     * Returns transportPubkey, chainPubkey, l1Address, directAddress, proxyAddress
+     */
+    resolveNametagInfo?(nametag: string): Promise<NametagInfo | null>;
+    /**
+     * Recover nametag for current identity by decrypting stored encrypted nametag
+     * Used after wallet import to recover associated nametag
+     * @returns Decrypted nametag or null if none found
+     */
+    recoverNametag?(): Promise<string | null>;
+    /**
+     * Register a nametag for this identity
+     * @param nametag - Nametag to register
+     * @param chainPubkey - 33-byte compressed secp256k1 public key (for L1/L3)
+     * @param directAddress - L3 DIRECT address (DIRECT://...)
+     * @returns true if successful, false if already taken
+     */
+    registerNametag?(nametag: string, chainPubkey: string, directAddress: 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
+     * @param recipientTransportPubkey - Transport-specific pubkey for messaging
+     * @returns Event ID
+     */
+    sendPaymentRequest?(recipientTransportPubkey: string, request: PaymentRequestPayload): Promise<string>;
+    /**
+     * Subscribe to incoming payment requests
+     * @returns Unsubscribe function
+     */
+    onPaymentRequest?(handler: PaymentRequestHandler): () => void;
+    /**
+     * Send response to a payment request
+     * @param recipientTransportPubkey - Transport-specific pubkey for messaging
+     * @returns Event ID
+     */
+    sendPaymentRequestResponse?(recipientTransportPubkey: 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;
+    /** Transport-specific pubkey of sender */
+    senderTransportPubkey: string;
+    /** Sender's nametag (if known from NIP-17 unwrap) */
+    senderNametag?: 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?: {
+        /** Transport-specific pubkey */
+        transportPubkey: string;
+        nametag?: string;
+    };
+}
+interface IncomingTokenTransfer {
+    id: string;
+    /** Transport-specific pubkey of sender */
+    senderTransportPubkey: 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;
+    /** Transport-specific pubkey of sender */
+    senderTransportPubkey: 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;
+    /** Transport-specific pubkey of responder */
+    responderTransportPubkey: 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;
+    /** Transport-specific pubkey of author */
+    authorTransportPubkey: string;
+    content: string;
+    tags: string[];
+    timestamp: number;
+}
+type BroadcastHandler = (broadcast: IncomingBroadcast) => void;
+/**
+ * Full nametag address information
+ * Used for resolving nametag to all address formats
+ */
+interface NametagInfo {
+    /** Nametag name (without @) */
+    nametag: string;
+    /** Transport-specific pubkey (for messaging/encryption) */
+    transportPubkey: string;
+    /** 33-byte compressed secp256k1 public key (for L3 chain) */
+    chainPubkey: string;
+    /** L1 address (alpha1...) */
+    l1Address: string;
+    /** L3 DIRECT address (DIRECT://...) */
+    directAddress: string;
+    /** L3 PROXY address derived from nametag hash (PROXY:...) */
+    proxyAddress: string;
+    /** Event timestamp */
+    timestamp: number;
+}
+
 /**
  * L1 Payments Sub-Module
  *
@@ -653,6 +898,8 @@ interface L1PaymentsModuleDependencies {
     identity: FullIdentity;
     chainCode?: string;
     addresses?: string[];
+    /** Transport provider for nametag resolution (optional) */
+    transport?: TransportProvider;
 }
 /**
  * L1 Payments Module - Full Implementation
@@ -667,9 +914,23 @@ declare class L1PaymentsModule {
     private _chainCode?;
     private _addresses;
     private _wallet?;
+    private _transport?;
     constructor(config?: L1PaymentsModuleConfig);
     initialize(deps: L1PaymentsModuleDependencies): Promise<void>;
     destroy(): void;
+    /**
+     * Check if a string looks like an L1 address (alpha1... or alphat1...)
+     */
+    private isL1Address;
+    /**
+     * Resolve recipient to L1 address
+     * Supports: L1 address (alpha1...), nametag (with or without @)
+     */
+    private resolveL1Address;
+    /**
+     * Resolve nametag to L1 address using transport provider
+     */
+    private resolveNametagToL1Address;
     send(request: L1SendRequest): Promise<L1SendResult>;
     getBalance(): Promise<L1Balance>;
     getUtxos(): Promise<L1Utxo[]>;
@@ -878,201 +1139,6 @@ interface TxfInvalidEntry {
     detectedAt: number;
 }
 
-/**
- * Transport Provider Interface
- * Platform-independent P2P messaging abstraction
- */
-
-/**
- * P2P messaging transport provider
- */
-interface TransportProvider extends BaseProvider {
-    /**
-     * Set identity for signing/encryption
-     */
-    setIdentity(identity: FullIdentity): void;
-    /**
-     * Send encrypted direct message
-     * @returns Event ID
-     */
-    sendMessage(recipientPubkey: string, content: string): Promise<string>;
-    /**
-     * Subscribe to incoming direct messages
-     * @returns Unsubscribe function
-     */
-    onMessage(handler: MessageHandler): () => void;
-    /**
-     * Send token transfer payload
-     * @returns Event ID
-     */
-    sendTokenTransfer(recipientPubkey: string, payload: TokenTransferPayload): Promise<string>;
-    /**
-     * Subscribe to incoming token transfers
-     * @returns Unsubscribe function
-     */
-    onTokenTransfer(handler: TokenTransferHandler): () => void;
-    /**
-     * Resolve nametag to public key
-     */
-    resolveNametag?(nametag: string): Promise<string | null>;
-    /**
-     * Register a nametag for this identity
-     * @returns true if successful, false if already taken
-     */
-    registerNametag?(nametag: string, publicKey: string): Promise<boolean>;
-    /**
-     * Publish nametag binding
-     */
-    publishNametag?(nametag: string, address: string): Promise<void>;
-    /**
-     * Subscribe to broadcast messages (global/channel)
-     */
-    subscribeToBroadcast?(tags: string[], handler: BroadcastHandler): () => void;
-    /**
-     * Publish broadcast message
-     */
-    publishBroadcast?(content: string, tags?: string[]): Promise<string>;
-    /**
-     * Send payment request to a recipient
-     * @returns Event ID
-     */
-    sendPaymentRequest?(recipientPubkey: string, request: PaymentRequestPayload): Promise<string>;
-    /**
-     * Subscribe to incoming payment requests
-     * @returns Unsubscribe function
-     */
-    onPaymentRequest?(handler: PaymentRequestHandler): () => void;
-    /**
-     * Send response to a payment request
-     * @returns Event ID
-     */
-    sendPaymentRequestResponse?(recipientPubkey: string, response: PaymentRequestResponsePayload): Promise<string>;
-    /**
-     * Subscribe to incoming payment request responses
-     * @returns Unsubscribe function
-     */
-    onPaymentRequestResponse?(handler: PaymentRequestResponseHandler): () => void;
-    /**
-     * Get list of configured relay URLs
-     */
-    getRelays?(): string[];
-    /**
-     * Get list of currently connected relay URLs
-     */
-    getConnectedRelays?(): string[];
-    /**
-     * Add a relay dynamically
-     * @returns true if added successfully
-     */
-    addRelay?(relayUrl: string): Promise<boolean>;
-    /**
-     * Remove a relay dynamically
-     * @returns true if removed successfully
-     */
-    removeRelay?(relayUrl: string): Promise<boolean>;
-    /**
-     * Check if a relay is configured
-     */
-    hasRelay?(relayUrl: string): boolean;
-    /**
-     * Check if a relay is currently connected
-     */
-    isRelayConnected?(relayUrl: string): boolean;
-}
-interface IncomingMessage {
-    id: string;
-    senderPubkey: string;
-    content: string;
-    timestamp: number;
-    encrypted: boolean;
-}
-type MessageHandler = (message: IncomingMessage) => void;
-interface TokenTransferPayload {
-    /** Serialized token data */
-    token: string;
-    /** Inclusion proof */
-    proof: unknown;
-    /** Optional memo */
-    memo?: string;
-    /** Sender info */
-    sender?: {
-        pubkey: string;
-        nametag?: string;
-    };
-}
-interface IncomingTokenTransfer {
-    id: string;
-    senderPubkey: string;
-    payload: TokenTransferPayload;
-    timestamp: number;
-}
-type TokenTransferHandler = (transfer: IncomingTokenTransfer) => void;
-interface PaymentRequestPayload {
-    /** Amount requested (in smallest units) */
-    amount: string | bigint;
-    /** Coin/token type ID */
-    coinId: string;
-    /** Message/memo for recipient */
-    message?: string;
-    /** Recipient's nametag (who should pay) */
-    recipientNametag?: string;
-    /** Custom metadata */
-    metadata?: Record<string, unknown>;
-}
-interface IncomingPaymentRequest {
-    /** Event ID */
-    id: string;
-    /** Sender's public key */
-    senderPubkey: string;
-    /** Parsed request data */
-    request: {
-        requestId: string;
-        amount: string;
-        coinId: string;
-        message?: string;
-        recipientNametag?: string;
-        metadata?: Record<string, unknown>;
-    };
-    /** Timestamp */
-    timestamp: number;
-}
-type PaymentRequestHandler = (request: IncomingPaymentRequest) => void;
-type PaymentRequestResponseType = 'accepted' | 'rejected' | 'paid';
-interface PaymentRequestResponsePayload {
-    /** Original request ID */
-    requestId: string;
-    /** Response type */
-    responseType: PaymentRequestResponseType;
-    /** Optional message */
-    message?: string;
-    /** Transfer ID (if paid) */
-    transferId?: string;
-}
-interface IncomingPaymentRequestResponse {
-    /** Event ID */
-    id: string;
-    /** Responder's public key */
-    responderPubkey: string;
-    /** Parsed response data */
-    response: {
-        requestId: string;
-        responseType: PaymentRequestResponseType;
-        message?: string;
-        transferId?: string;
-    };
-    /** Timestamp */
-    timestamp: number;
-}
-type PaymentRequestResponseHandler = (response: IncomingPaymentRequestResponse) => void;
-interface IncomingBroadcast {
-    id: string;
-    authorPubkey: string;
-    content: string;
-    tags: string[];
-    timestamp: number;
-}
-type BroadcastHandler = (broadcast: IncomingBroadcast) => void;
-
 /**
  * Oracle Provider Interface
  * Platform-independent Unicity oracle abstraction
@@ -1302,6 +1368,14 @@ declare class PaymentsModule {
      * Get coin name from coinId
      */
     private getCoinName;
+    /**
+     * Get coin decimals from coinId
+     */
+    private getCoinDecimals;
+    /**
+     * Get coin icon URL from coinId
+     */
+    private getCoinIconUrl;
     /**
      * Send a payment request to someone
      * @param recipientPubkeyOrNametag - Recipient's pubkey or @nametag
@@ -1554,6 +1628,15 @@ declare class PaymentsModule {
      * Get pending transfers
      */
     getPendingTransfers(): TransferResult[];
+    /**
+     * Detect if a string is an L3 address (not a nametag)
+     * Returns true for: hex pubkeys (64+ chars), PROXY:, DIRECT: prefixed addresses
+     */
+    private isL3Address;
+    /**
+     * Resolve recipient to Nostr pubkey for messaging
+     * Supports: nametag (with or without @), hex pubkey
+     */
     private resolveRecipient;
     /**
      * Create SDK TransferCommitment for a token transfer
@@ -1564,7 +1647,17 @@ declare class PaymentsModule {
      */
     private createSigningService;
     /**
-     * Resolve recipient to IAddress
+     * Create DirectAddress from a public key using UnmaskedPredicateReference
+     */
+    private createDirectAddressFromPubkey;
+    /**
+     * Resolve nametag to 33-byte compressed public key using resolveNametagInfo
+     * Returns null if nametag not found or publicKey not available
+     */
+    private resolveNametagToPublicKey;
+    /**
+     * Resolve recipient to IAddress for L3 transfers
+     * Supports: nametag (with or without @), PROXY:, DIRECT:, hex pubkey
      */
     private resolveRecipientAddress;
     private handleIncomingTransfer;
@@ -1829,6 +1922,7 @@ declare class Sphere {
     private _derivationMode;
     private _basePath;
     private _currentAddressIndex;
+    /** Map of addressId -> (nametagIndex -> nametag). Supports multiple nametags per address (e.g., from Nostr recovery) */
     private _addressNametags;
     private _storage;
     private _tokenStorageProviders;
@@ -1882,6 +1976,7 @@ declare class Sphere {
     static import(options: SphereImportOptions): Promise<Sphere>;
     /**
      * Clear wallet data from storage
+     * Note: Token data is cleared via TokenStorageProvider, not here
      */
     static clear(storage: StorageProvider): Promise<void>;
     /**
@@ -2100,18 +2195,29 @@ declare class Sphere {
      */
     getCurrentAddressIndex(): number;
     /**
-     * Get nametag for a specific address index
+     * Get primary nametag for a specific address
+     *
+     * @param addressId - Address identifier (DIRECT://xxx), defaults to current address
+     * @returns Primary nametag (index 0) or undefined if not registered
+     */
+    getNametagForAddress(addressId?: string): string | undefined;
+    /**
+     * Get all nametags for a specific address
      *
-     * @param index - Address index (default: current address)
-     * @returns Nametag or undefined if not registered
+     * @param addressId - Address identifier (DIRECT://xxx), defaults to current address
+     * @returns Map of nametagIndex to nametag, or undefined if no nametags
      */
-    getNametagForAddress(index?: number): string | undefined;
+    getNametagsForAddress(addressId?: string): Map<number, string> | undefined;
     /**
      * Get all registered address nametags
      *
-     * @returns Map of address index to nametag
+     * @returns Map of addressId to (nametagIndex -> nametag)
      */
-    getAllAddressNametags(): Map<number, string>;
+    getAllAddressNametags(): Map<string, Map<number, string>>;
+    /**
+     * Get current address identifier (DIRECT://xxx format)
+     */
+    private getCurrentAddressId;
     /**
      * Switch to a different address by index
      * This changes the active identity to the derived address at the specified index.
@@ -2209,6 +2315,13 @@ declare class Sphere {
      * Check if nametag is registered
      */
     hasNametag(): boolean;
+    /**
+     * Get the PROXY address for the current nametag
+     * PROXY addresses are derived from the nametag hash and require
+     * the nametag token to claim funds sent to them
+     * @returns PROXY address string or undefined if no nametag
+     */
+    getProxyAddress(): string | undefined;
     /**
      * Register a nametag for the current active address
      * Each address can have its own independent nametag
@@ -2230,6 +2343,7 @@ declare class Sphere {
     registerNametag(nametag: string): Promise<void>;
     /**
      * Persist address nametags to storage
+     * Format: { "DIRECT://abc...xyz": { "0": "alice", "1": "alice2" }, ... }
      */
     private persistAddressNametags;
     /**
@@ -2259,6 +2373,8 @@ declare class Sphere {
     isNametagAvailable(nametag: string): Promise<boolean>;
     /**
      * Load address nametags from storage
+     * Supports new format: { "DIRECT://abc...xyz": { "0": "alice" } }
+     * And legacy format: { "0": "alice" } (migrates to new format on save)
      */
     private loadAddressNametags;
     /**
@@ -2266,6 +2382,12 @@ declare class Sphere {
      * If local nametag exists but not registered on Nostr, re-register it
      */
     private syncNametagWithNostr;
+    /**
+     * Recover nametag from Nostr after wallet import
+     * Searches for encrypted nametag events authored by this wallet's pubkey
+     * and decrypts them to restore the nametag association
+     */
+    private recoverNametagFromNostr;
     /**
      * Validate nametag format
      */