@unicitylabs/sphere-sdk 0.1.8 → 0.2.0

package/dist/core/index.d.cts

@@ -272,6 +272,211 @@ interface TombstoneEntry {
     timestamp: number;
 }
 
+/**
+ * INSTANT_SPLIT V5 Types
+ *
+ * Optimized token split transfer types that achieve ~2.3s critical path latency
+ * instead of the standard ~42s sequential flow.
+ *
+ * Key Insight: TransferCommitment.create() only needs token.state, NOT the mint proof.
+ * This allows creating transfer commitments immediately after mint data creation,
+ * without waiting for mint proofs.
+ *
+ * V5 Flow (Production Mode):
+ * 1. Create burn commitment, submit to aggregator
+ * 2. Wait for burn inclusion proof (~2s - unavoidable)
+ * 3. Create mint commitments with proper SplitMintReason (requires burn proof)
+ * 4. Create transfer commitment from mint data (no mint proof needed)
+ * 5. Package bundle -> send via Nostr -> SUCCESS (~2.3s total!)
+ * 6. Background: submit mints, wait for proofs, save change token, sync storage
+ */
+type SdkToken = any;
+/**
+ * Bundle payload for INSTANT_SPLIT V5 (Production Mode)
+ *
+ * V5 achieves ~2.3s sender latency while working with production aggregators:
+ * - Burn proof is required for creating SplitMintReason
+ * - Transfer commitment is created from mint data WITHOUT waiting for mint proof
+ * - Mints are submitted in background after Nostr delivery
+ *
+ * Security: Burn is proven on-chain before mints can be created, preventing double-spend.
+ */
+interface InstantSplitBundleV5 {
+    /** Bundle version - V5 is production mode (proper SplitMintReason) */
+    version: '5.0';
+    /** Bundle type identifier */
+    type: 'INSTANT_SPLIT';
+    /**
+     * Burn TRANSACTION JSON (WITH inclusion proof!)
+     * V5 sends the proven burn transaction so recipient can verify burn completed.
+     */
+    burnTransaction: string;
+    /**
+     * Recipient's MintTransactionData JSON (contains proper SplitMintReason in V5)
+     * The SplitMintReason references the burn transaction.
+     */
+    recipientMintData: string;
+    /**
+     * Pre-created TransferCommitment JSON (recipient submits and waits for proof)
+     * Created from mint data WITHOUT any proofs.
+     */
+    transferCommitment: string;
+    /** Payment amount (display metadata) */
+    amount: string;
+    /** Coin ID hex */
+    coinId: string;
+    /** Token type hex */
+    tokenTypeHex: string;
+    /** Split group ID for recovery correlation */
+    splitGroupId: string;
+    /** Sender's pubkey for acknowledgment */
+    senderPubkey: string;
+    /** Salt for recipient predicate creation (hex) */
+    recipientSaltHex: string;
+    /** Salt for transfer commitment creation (hex) */
+    transferSaltHex: string;
+    /**
+     * Serialized TokenState JSON for the intermediate minted token.
+     *
+     * In V5, the mint is to sender's address first, then transferred to recipient.
+     * The recipient needs this state to reconstruct the minted token before applying transfer.
+     * Without this, the recipient can't create a matching predicate (they don't have sender's signing key).
+     */
+    mintedTokenStateJson: string;
+    /**
+     * Serialized TokenState JSON for the final recipient state (after transfer).
+     *
+     * The sender creates the transfer commitment targeting the recipient's PROXY address.
+     * The recipient can't recreate this state correctly because their signingService
+     * creates predicates for their DIRECT address, not the PROXY address.
+     * This is optional - recipient can create their own if they have the correct address.
+     */
+    finalRecipientStateJson: string;
+    /**
+     * Serialized recipient address JSON (PROXY or DIRECT).
+     *
+     * Used by the recipient to identify which nametag token is being targeted.
+     * For PROXY address transfers, the recipient needs to find the matching
+     * nametag token and pass it to finalizeTransaction() for verification.
+     */
+    recipientAddressJson: string;
+    /**
+     * Serialized nametag token JSON (for PROXY address transfers).
+     *
+     * For PROXY address transfers, the sender includes the nametag token
+     * so the recipient can verify they're authorized to receive at this address.
+     * This is REQUIRED for PROXY addresses - transfers without this will fail.
+     */
+    nametagTokenJson?: string;
+}
+/**
+ * Bundle payload for INSTANT_SPLIT V4 (Dev Mode Only - True Nostr-First Split)
+ *
+ * V4 achieves near-zero sender latency (~0.3s) by:
+ * 1. Creating ALL commitments locally BEFORE any aggregator submission
+ * 2. Persisting via Nostr FIRST
+ * 3. Then submitting ALL to aggregator in background
+ *
+ * NOTE: V4 only works in dev mode. Production requires V5 with proper SplitMintReason.
+ */
+interface InstantSplitBundleV4 {
+    /** Bundle version - V4 is true Nostr-first (dev mode only) */
+    version: '4.0';
+    /** Bundle type identifier */
+    type: 'INSTANT_SPLIT';
+    /**
+     * Burn commitment JSON (NOT transaction - no proof yet!)
+     * Both sender and recipient submit this to aggregator.
+     */
+    burnCommitment: string;
+    /** Recipient's MintTransactionData JSON (they recreate commitment and submit) */
+    recipientMintData: string;
+    /**
+     * Pre-created TransferCommitment JSON (recipient submits and waits for proof)
+     * Created from mint data WITHOUT any proofs.
+     */
+    transferCommitment: string;
+    /** Payment amount (display metadata) */
+    amount: string;
+    /** Coin ID hex */
+    coinId: string;
+    /** Token type hex */
+    tokenTypeHex: string;
+    /** Split group ID for recovery correlation */
+    splitGroupId: string;
+    /** Sender's pubkey for acknowledgment */
+    senderPubkey: string;
+    /** Salt for recipient predicate creation (hex) */
+    recipientSaltHex: string;
+    /** Salt for transfer commitment creation (hex) */
+    transferSaltHex: string;
+}
+/** Union type for all InstantSplit bundle versions */
+type InstantSplitBundle = InstantSplitBundleV4 | InstantSplitBundleV5;
+/**
+ * Result of an instant split send operation
+ */
+interface InstantSplitResult {
+    /** Whether the operation succeeded (Nostr delivery) */
+    success: boolean;
+    /** Nostr event ID (if delivered) */
+    nostrEventId?: string;
+    /** Split group ID for recovery correlation */
+    splitGroupId?: string;
+    /** Time taken for critical path (Nostr delivery) in ms */
+    criticalPathDurationMs: number;
+    /** Error message (if failed) */
+    error?: string;
+    /** Whether background processing was started */
+    backgroundStarted?: boolean;
+}
+/**
+ * Result from processing an INSTANT_SPLIT bundle (recipient side)
+ */
+interface InstantSplitProcessResult {
+    /** Whether processing succeeded */
+    success: boolean;
+    /** The finalized SDK token (if successful) */
+    token?: SdkToken;
+    /** Error message (if failed) */
+    error?: string;
+    /** Processing duration in ms */
+    durationMs: number;
+}
+/**
+ * Options for instant split send operation
+ */
+interface InstantSplitOptions {
+    /** Timeout for Nostr delivery in ms (default: 30000) */
+    nostrTimeoutMs?: number;
+    /** Timeout for burn proof wait in ms (default: 60000) */
+    burnProofTimeoutMs?: number;
+    /** Timeout for mint proof wait in ms (default: 60000) */
+    mintProofTimeoutMs?: number;
+    /** Skip background processing (for testing) */
+    skipBackground?: boolean;
+    /** Use dev mode (V4 flow without SplitMintReason validation) */
+    devMode?: boolean;
+    /** Callback when burn is completed */
+    onBurnCompleted?: (burnTxJson: string) => void;
+    /** Callback when Nostr delivery is completed */
+    onNostrDelivered?: (eventId: string) => void;
+    /** Callback for background progress updates */
+    onBackgroundProgress?: (status: BackgroundProgressStatus) => void;
+    /** Callback when change token is created (background) */
+    onChangeTokenCreated?: (token: any) => Promise<void>;
+    /** Callback to trigger storage sync (background) */
+    onStorageSync?: () => Promise<boolean>;
+}
+/**
+ * Background processing status
+ */
+interface BackgroundProgressStatus {
+    stage: 'MINTS_SUBMITTED' | 'MINTS_PROVEN' | 'CHANGE_TOKEN_SAVED' | 'STORAGE_SYNCED' | 'COMPLETED' | 'FAILED';
+    message: string;
+    error?: string;
+}
+
 /**
  * SDK2 Core Types
  * Platform-independent type definitions
@@ -302,7 +507,7 @@ interface Identity {
 interface FullIdentity extends Identity {
     readonly privateKey: string;
 }
-type TokenStatus = 'pending' | 'confirmed' | 'transferring' | 'spent' | 'invalid';
+type TokenStatus = 'pending' | 'submitted' | 'confirmed' | 'transferring' | 'spent' | 'invalid';
 interface Token {
     readonly id: string;
     readonly coinId: string;
@@ -316,14 +521,6 @@ interface Token {
     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;
-}
 interface Asset {
     readonly coinId: string;
     readonly symbol: string;
@@ -332,13 +529,26 @@ interface Asset {
     readonly iconUrl?: string;
     readonly totalAmount: string;
     readonly tokenCount: number;
+    /** Price per whole unit in USD (null if PriceProvider not configured) */
+    readonly priceUsd: number | null;
+    /** Price per whole unit in EUR (null if PriceProvider not configured) */
+    readonly priceEur: number | null;
+    /** 24h price change percentage (null if unavailable) */
+    readonly change24h: number | null;
+    /** Total fiat value in USD: (totalAmount / 10^decimals) * priceUsd */
+    readonly fiatValueUsd: number | null;
+    /** Total fiat value in EUR */
+    readonly fiatValueEur: number | null;
 }
 type TransferStatus = 'pending' | 'submitted' | 'confirmed' | 'delivered' | 'completed' | 'failed';
+type AddressMode = 'auto' | 'direct' | 'proxy';
 interface TransferRequest {
     readonly coinId: string;
     readonly amount: string;
     readonly recipient: string;
     readonly memo?: string;
+    /** Address mode: 'auto' (default) uses directAddress if available, 'direct' forces DIRECT, 'proxy' forces PROXY */
+    readonly addressMode?: AddressMode;
 }
 interface TransferResult {
     readonly id: string;
@@ -491,7 +701,37 @@ 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' | 'nametag:recovered' | 'identity:changed';
+/**
+ * Minimal data stored in persistent storage for a tracked address.
+ * Only contains user state — derived fields are computed on load.
+ */
+interface TrackedAddressEntry {
+    /** HD derivation index (0, 1, 2, ...) */
+    readonly index: number;
+    /** Whether this address is hidden from UI display */
+    hidden: boolean;
+    /** Timestamp (ms) when this address was first activated */
+    readonly createdAt: number;
+    /** Timestamp (ms) of last modification */
+    updatedAt: number;
+}
+/**
+ * Full tracked address with derived fields and nametag (available in memory).
+ * Returned by Sphere.getActiveAddresses() / getAllTrackedAddresses().
+ */
+interface TrackedAddress extends TrackedAddressEntry {
+    /** Short address identifier (e.g., "DIRECT_abc123_xyz789") */
+    readonly addressId: string;
+    /** L1 bech32 address (alpha1...) */
+    readonly l1Address: string;
+    /** L3 DIRECT address (DIRECT://...) */
+    readonly directAddress: string;
+    /** 33-byte compressed secp256k1 public key */
+    readonly chainPubkey: string;
+    /** Primary nametag (from nametag cache, without @ prefix) */
+    readonly nametag?: 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' | 'nametag:recovered' | 'identity:changed' | 'address:activated' | 'address:hidden' | 'address:unhidden';
 interface SphereEventMap {
     'transfer:incoming': IncomingTransfer;
     'transfer:confirmed': TransferResult;
@@ -539,6 +779,17 @@ interface SphereEventMap {
         nametag?: string;
         addressIndex: number;
     };
+    'address:activated': {
+        address: TrackedAddress;
+    };
+    'address:hidden': {
+        index: number;
+        addressId: string;
+    };
+    'address:unhidden': {
+        index: number;
+        addressId: string;
+    };
 }
 type SphereEventHandler<T extends SphereEventType> = (data: SphereEventMap[T]) => void;
 /**
@@ -634,15 +885,36 @@ interface TransportProvider extends BaseProvider {
      * @returns Unsubscribe function
      */
     onTokenTransfer(handler: TokenTransferHandler): () => void;
+    /**
+     * Resolve any identifier to full peer information.
+     * Accepts @nametag, bare nametag, DIRECT://, PROXY://, L1 address, chain pubkey, or transport pubkey.
+     * @param identifier - Any supported identifier format
+     * @returns PeerInfo or null if not found
+     */
+    resolve?(identifier: string): Promise<PeerInfo | null>;
     /**
      * Resolve nametag to public key
      */
     resolveNametag?(nametag: string): Promise<string | null>;
     /**
-     * Resolve nametag to full address information
+     * Resolve nametag to full peer information
      * Returns transportPubkey, chainPubkey, l1Address, directAddress, proxyAddress
      */
-    resolveNametagInfo?(nametag: string): Promise<NametagInfo | null>;
+    resolveNametagInfo?(nametag: string): Promise<PeerInfo | null>;
+    /**
+     * Resolve a DIRECT://, PROXY://, or L1 address to full peer info.
+     * Performs reverse lookup: address → binding event → PeerInfo.
+     * @param address - L3 address (DIRECT://... or PROXY://...) or L1 address (alpha1...)
+     * @returns PeerInfo or null if no binding found for this address
+     */
+    resolveAddressInfo?(address: string): Promise<PeerInfo | null>;
+    /**
+     * Resolve transport pubkey to full peer info.
+     * Queries binding events authored by the given transport pubkey.
+     * @param transportPubkey - Transport-specific pubkey (e.g. 64-char hex string)
+     * @returns PeerInfo or null if no binding found
+     */
+    resolveTransportPubkeyInfo?(transportPubkey: string): Promise<PeerInfo | null>;
     /**
      * Recover nametag for current identity by decrypting stored encrypted nametag
      * Used after wallet import to recover associated nametag
@@ -650,14 +922,20 @@ interface TransportProvider extends BaseProvider {
      */
     recoverNametag?(): Promise<string | null>;
     /**
+     * Publish identity binding event.
+     * Without nametag: publishes base binding (chainPubkey, l1Address, directAddress).
+     * With nametag: adds nametag hash, proxy address, encrypted nametag for recovery.
+     * Uses parameterized replaceable event (kind 30078, d=hash(nostrPubkey)).
+     * @returns true if successful, false if nametag is taken by another pubkey
+     */
+    publishIdentityBinding?(chainPubkey: string, l1Address: string, directAddress: string, nametag?: string): Promise<boolean>;
+    /**
+     * @deprecated Use publishIdentityBinding instead
      * 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>;
     /**
+     * @deprecated Use publishIdentityBinding instead
      * Publish nametag binding
      */
     publishNametag?(nametag: string, address: string): Promise<void>;
@@ -717,7 +995,54 @@ interface TransportProvider extends BaseProvider {
      * Check if a relay is currently connected
      */
     isRelayConnected?(relayUrl: string): boolean;
+    /**
+     * Send an instant split bundle to a recipient.
+     * This is a specialized method for INSTANT_SPLIT V5 bundles.
+     *
+     * @param recipientTransportPubkey - Transport-specific pubkey for messaging
+     * @param bundle - The InstantSplitBundleV5 to send
+     * @returns Event ID
+     */
+    sendInstantSplitBundle?(recipientTransportPubkey: string, bundle: InstantSplitBundlePayload): Promise<string>;
+    /**
+     * Subscribe to incoming instant split bundles.
+     *
+     * @param handler - Handler for received bundles
+     * @returns Unsubscribe function
+     */
+    onInstantSplitReceived?(handler: InstantSplitBundleHandler): () => void;
+}
+/**
+ * Payload for sending instant split bundles
+ */
+interface InstantSplitBundlePayload {
+    /** The bundle JSON string (InstantSplitBundleV5 serialized) */
+    bundle: string;
+    /** Optional memo */
+    memo?: string;
+    /** Sender info */
+    sender?: {
+        transportPubkey: string;
+        nametag?: string;
+    };
 }
+/**
+ * Incoming instant split bundle
+ */
+interface IncomingInstantSplitBundle {
+    /** Event ID */
+    id: string;
+    /** Transport-specific pubkey of sender */
+    senderTransportPubkey: string;
+    /** The bundle JSON string */
+    bundle: string;
+    /** Timestamp */
+    timestamp: number;
+}
+/**
+ * Handler for instant split bundles
+ */
+type InstantSplitBundleHandler = (bundle: IncomingInstantSplitBundle) => void;
 interface IncomingMessage {
     id: string;
     /** Transport-specific pubkey of sender */
@@ -818,12 +1143,13 @@ interface IncomingBroadcast {
 }
 type BroadcastHandler = (broadcast: IncomingBroadcast) => void;
 /**
- * Full nametag address information
- * Used for resolving nametag to all address formats
+ * Resolved peer identity information.
+ * Returned by resolve methods — contains all public address formats for a peer.
+ * Fields nametag and proxyAddress are optional (only present if nametag is registered).
  */
-interface NametagInfo {
-    /** Nametag name (without @) */
-    nametag: string;
+interface PeerInfo {
+    /** Nametag name (without @), if registered */
+    nametag?: string;
     /** Transport-specific pubkey (for messaging/encryption) */
     transportPubkey: string;
     /** 33-byte compressed secp256k1 public key (for L3 chain) */
@@ -832,8 +1158,8 @@ interface NametagInfo {
     l1Address: string;
     /** L3 DIRECT address (DIRECT://...) */
     directAddress: string;
-    /** L3 PROXY address derived from nametag hash (PROXY:...) */
-    proxyAddress: string;
+    /** L3 PROXY address derived from nametag hash (PROXY:...), only if nametag registered */
+    proxyAddress?: string;
     /** Event timestamp */
     timestamp: number;
 }
@@ -920,7 +1246,6 @@ declare class L1PaymentsModule {
     private _initialized;
     private _config;
     private _identity?;
-    private _chainCode?;
     private _addresses;
     private _wallet?;
     private _transport?;
@@ -1017,6 +1342,14 @@ interface StorageProvider extends BaseProvider {
      * Clear all keys with optional prefix filter
      */
     clear(prefix?: string): Promise<void>;
+    /**
+     * Save tracked addresses (only user state: index, hidden, timestamps)
+     */
+    saveTrackedAddresses(entries: TrackedAddressEntry[]): Promise<void>;
+    /**
+     * Load tracked addresses
+     */
+    loadTrackedAddresses(): Promise<TrackedAddressEntry[]>;
 }
 /**
  * Storage result types
@@ -1275,6 +1608,65 @@ interface MintResult {
     error?: string;
 }
 
+/**
+ * Price Provider Interface
+ *
+ * Platform-independent abstraction for fetching token market prices.
+ * Does not extend BaseProvider — stateless HTTP client with internal caching.
+ */
+/**
+ * Supported price provider platforms
+ */
+type PricePlatform = 'coingecko';
+/**
+ * Price data for a single token
+ */
+interface TokenPrice {
+    /** Token name used by the price platform (e.g., "bitcoin") */
+    readonly tokenName: string;
+    /** Price in USD */
+    readonly priceUsd: number;
+    /** Price in EUR (if available) */
+    readonly priceEur?: number;
+    /** 24h price change percentage (if available) */
+    readonly change24h?: number;
+    /** Timestamp when this price was fetched */
+    readonly timestamp: number;
+}
+/**
+ * Price data provider
+ *
+ * Fetches current market prices for tokens. Implementations handle
+ * caching internally to avoid excessive API calls.
+ *
+ * @example
+ * ```ts
+ * const provider = new CoinGeckoPriceProvider({ apiKey: 'CG-xxx' });
+ * const prices = await provider.getPrices(['bitcoin', 'ethereum']);
+ * console.log(prices.get('bitcoin')?.priceUsd); // 97500
+ * ```
+ */
+interface PriceProvider {
+    /** Platform identifier (e.g., 'coingecko') */
+    readonly platform: PricePlatform;
+    /**
+     * Get prices for multiple tokens by their platform-compatible names
+     * @param tokenNames - Array of token names (e.g., ['bitcoin', 'ethereum'])
+     * @returns Map of token name to price data
+     */
+    getPrices(tokenNames: string[]): Promise<Map<string, TokenPrice>>;
+    /**
+     * Get price for a single token
+     * @param tokenName - Token name (e.g., 'bitcoin')
+     * @returns Token price or null if not available
+     */
+    getPrice(tokenName: string): Promise<TokenPrice | null>;
+    /**
+     * Clear cached prices
+     */
+    clearCache(): void;
+}
+
 /**
  * Payments Module
  * Platform-independent token operations with full wallet repository functionality
@@ -1327,6 +1719,8 @@ interface PaymentsModuleDependencies {
     chainCode?: string;
     /** Additional L1 addresses to watch */
     l1Addresses?: string[];
+    /** Price provider (optional — enables fiat value display) */
+    price?: PriceProvider;
 }
 declare class PaymentsModule {
     private readonly moduleConfig;
@@ -1348,9 +1742,15 @@ declare class PaymentsModule {
     private unsubscribeTransfers;
     private unsubscribePaymentRequests;
     private unsubscribePaymentRequestResponses;
+    private proofPollingJobs;
+    private proofPollingInterval;
+    private static readonly PROOF_POLLING_INTERVAL_MS;
+    private static readonly PROOF_POLLING_MAX_ATTEMPTS;
     constructor(config?: PaymentsModuleConfig);
     /** Get module configuration */
     getConfig(): Omit<Required<PaymentsModuleConfig>, 'l1'>;
+    /** Price provider (optional) */
+    private priceProvider;
     private log;
     /**
      * Initialize module with dependencies
@@ -1385,6 +1785,39 @@ declare class PaymentsModule {
      * Get coin icon URL from coinId
      */
     private getCoinIconUrl;
+    /**
+     * Send tokens using INSTANT_SPLIT V5 optimized flow.
+     *
+     * This achieves ~2.3s critical path latency instead of ~42s by:
+     * 1. Waiting only for burn proof (required)
+     * 2. Creating transfer commitment from mint data (no mint proof needed)
+     * 3. Sending bundle via Nostr immediately
+     * 4. Processing mints in background
+     *
+     * @param request - Transfer request with recipient, amount, and coinId
+     * @param options - Optional instant split configuration
+     * @returns InstantSplitResult with timing info
+     */
+    sendInstant(request: TransferRequest, options?: InstantSplitOptions): Promise<InstantSplitResult>;
+    /**
+     * Process a received INSTANT_SPLIT bundle.
+     *
+     * This should be called when receiving an instant split bundle via transport.
+     * It handles the recipient-side processing:
+     * 1. Validate burn transaction
+     * 2. Submit and wait for mint proof
+     * 3. Submit and wait for transfer proof
+     * 4. Finalize and save the token
+     *
+     * @param bundle - The received InstantSplitBundle (V4 or V5)
+     * @param senderPubkey - Sender's public key for verification
+     * @returns Processing result with finalized token
+     */
+    processInstantSplitBundle(bundle: InstantSplitBundle, senderPubkey: string): Promise<InstantSplitProcessResult>;
+    /**
+     * Check if a payload is an instant split bundle
+     */
+    isInstantSplitBundle(payload: unknown): payload is InstantSplitBundle;
     /**
      * Send a payment request to someone
      * @param recipientPubkeyOrNametag - Recipient's pubkey or @nametag
@@ -1474,14 +1907,19 @@ declare class PaymentsModule {
      */
     private sendPaymentRequestResponse;
     /**
-     * Get balance for coin type
+     * Set or update price provider
+     */
+    setPriceProvider(provider: PriceProvider): void;
+    /**
+     * Get total portfolio value in USD
+     * Returns null if PriceProvider is not configured
      */
-    getBalance(coinId?: string): TokenBalance[];
+    getBalance(): Promise<number | null>;
     /**
-     * Get aggregated assets (tokens grouped by coinId)
+     * Get aggregated assets (tokens grouped by coinId) with price data
      * Only includes confirmed tokens
      */
-    getAssets(coinId?: string): Asset[];
+    getAssets(coinId?: string): Promise<Asset[]>;
     /**
      * Get all tokens
      */
@@ -1495,7 +1933,9 @@ declare class PaymentsModule {
     getToken(id: string): Token | undefined;
     /**
      * Add a token
-     * @returns false if duplicate
+     * Tokens are uniquely identified by (tokenId, stateHash) composite key.
+     * Multiple historic states of the same token can coexist.
+     * @returns false if exact duplicate (same tokenId AND same stateHash)
      */
     addToken(token: Token, skipHistory?: boolean): Promise<boolean>;
     /**
@@ -1646,12 +2086,11 @@ declare class PaymentsModule {
      * 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
+     * Resolve recipient to transport pubkey for messaging.
+     * Uses pre-resolved PeerInfo if available, otherwise resolves via transport.
      */
-    private resolveRecipient;
+    private resolveTransportPubkey;
     /**
      * Create SDK TransferCommitment for a token transfer
      */
@@ -1665,15 +2104,25 @@ declare class PaymentsModule {
      */
     private createDirectAddressFromPubkey;
     /**
-     * Resolve nametag to 33-byte compressed public key using resolveNametagInfo
-     * Returns null if nametag not found or publicKey not available
+     * Resolve recipient to IAddress for L3 transfers.
+     * Uses pre-resolved PeerInfo when available to avoid redundant network queries.
      */
-    private resolveNametagToPublicKey;
+    private resolveRecipientAddress;
     /**
-     * Resolve recipient to IAddress for L3 transfers
-     * Supports: nametag (with or without @), PROXY:, DIRECT:, hex pubkey
+     * Handle NOSTR-FIRST commitment-only transfer (recipient side)
+     * This is called when receiving a transfer with only commitmentData and no proof yet.
+     * We create the token as 'submitted', submit commitment (idempotent), and poll for proof.
      */
-    private resolveRecipientAddress;
+    private handleCommitmentOnlyTransfer;
+    /**
+     * Shared finalization logic for received transfers.
+     * Handles both PROXY (with nametag token + address validation) and DIRECT schemes.
+     */
+    private finalizeTransferToken;
+    /**
+     * Finalize a received token after proof is available
+     */
+    private finalizeReceivedToken;
     private handleIncomingTransfer;
     private archiveToken;
     private save;
@@ -1682,6 +2131,27 @@ declare class PaymentsModule {
     private loadOutbox;
     private createStorageData;
     private loadFromStorageData;
+    /**
+     * Submit commitment to aggregator and start background proof polling
+     * (NOSTR-FIRST pattern: fire-and-forget submission)
+     */
+    private submitAndPollForProof;
+    /**
+     * Add a proof polling job to the queue
+     */
+    private addProofPollingJob;
+    /**
+     * Start the proof polling interval if not already running
+     */
+    private startProofPolling;
+    /**
+     * Stop the proof polling interval
+     */
+    private stopProofPolling;
+    /**
+     * Process all pending proof polling jobs
+     */
+    private processProofPollingQueue;
     private ensureInitialized;
 }
 
@@ -1828,6 +2298,8 @@ interface SphereCreateOptions {
     oracle: OracleProvider;
     /** L1 (ALPHA blockchain) configuration */
     l1?: L1Config;
+    /** Optional price provider for fiat conversion */
+    price?: PriceProvider;
     /**
      * Network type (mainnet, testnet, dev) - informational only.
      * Actual network configuration comes from provider URLs.
@@ -1847,6 +2319,8 @@ interface SphereLoadOptions {
     oracle: OracleProvider;
     /** L1 (ALPHA blockchain) configuration */
     l1?: L1Config;
+    /** Optional price provider for fiat conversion */
+    price?: PriceProvider;
     /**
      * Network type (mainnet, testnet, dev) - informational only.
      * Actual network configuration comes from provider URLs.
@@ -1880,6 +2354,8 @@ interface SphereImportOptions {
     oracle: OracleProvider;
     /** L1 (ALPHA blockchain) configuration */
     l1?: L1Config;
+    /** Optional price provider for fiat conversion */
+    price?: PriceProvider;
 }
 /** L1 (ALPHA blockchain) configuration */
 interface L1Config {
@@ -1910,6 +2386,8 @@ interface SphereInitOptions {
     nametag?: string;
     /** L1 (ALPHA blockchain) configuration */
     l1?: L1Config;
+    /** Optional price provider for fiat conversion */
+    price?: PriceProvider;
     /**
      * Network type (mainnet, testnet, dev) - informational only.
      * Actual network configuration comes from provider URLs.
@@ -1936,12 +2414,19 @@ declare class Sphere {
     private _derivationMode;
     private _basePath;
     private _currentAddressIndex;
-    /** Map of addressId -> (nametagIndex -> nametag). Supports multiple nametags per address (e.g., from Nostr recovery) */
+    /** Registry of all tracked (activated) addresses, keyed by HD index */
+    private _trackedAddresses;
+    /** Reverse lookup: addressId -> HD index */
+    private _addressIdToIndex;
+    /** Nametag cache: addressId -> (nametagIndex -> nametag). Separate from tracked addresses. */
     private _addressNametags;
+    /** Cached PROXY address (computed once when nametag is set) */
+    private _cachedProxyAddress;
     private _storage;
     private _tokenStorageProviders;
     private _transport;
     private _oracle;
+    private _priceProvider;
     private _payments;
     private _communications;
     private eventHandlers;
@@ -1989,10 +2474,28 @@ declare class Sphere {
      */
     static import(options: SphereImportOptions): Promise<Sphere>;
     /**
-     * Clear wallet data from storage
-     * Note: Token data is cleared via TokenStorageProvider, not here
+     * Clear all SDK-owned wallet data from storage.
+     *
+     * Removes wallet keys, per-address data, and optionally token storage.
+     * Does NOT affect application-level data stored outside the SDK.
+     *
+     * @param storageOrOptions - StorageProvider (backward compatible) or options object
+     *
+     * @example
+     * // New usage (recommended) - clears wallet keys AND token data
+     * await Sphere.clear({
+     *   storage: providers.storage,
+     *   tokenStorage: providers.tokenStorage,
+     * });
+     *
+     * @example
+     * // Legacy usage - clears only wallet keys
+     * await Sphere.clear(storage);
      */
-    static clear(storage: StorageProvider): Promise<void>;
+    static clear(storageOrOptions: StorageProvider | {
+        storage: StorageProvider;
+        tokenStorage?: TokenStorageProvider<TxfStorageDataBase>;
+    }): Promise<void>;
     /**
      * Get current instance
      */
@@ -2041,6 +2544,10 @@ declare class Sphere {
      * Check if a token storage provider is registered
      */
     hasTokenStorageProvider(providerId: string): boolean;
+    /**
+     * Set or update the price provider after initialization
+     */
+    setPriceProvider(provider: PriceProvider): void;
     getTransport(): TransportProvider;
     getAggregator(): OracleProvider;
     /**
@@ -2224,14 +2731,40 @@ declare class Sphere {
     getNametagsForAddress(addressId?: string): Map<number, string> | undefined;
     /**
      * Get all registered address nametags
-     *
+     * @deprecated Use getActiveAddresses() or getAllTrackedAddresses() instead
      * @returns Map of addressId to (nametagIndex -> nametag)
      */
     getAllAddressNametags(): Map<string, Map<number, string>>;
     /**
-     * Get current address identifier (DIRECT://xxx format)
+     * Get all active (non-hidden) tracked addresses.
+     * Returns addresses that have been activated through create, switchToAddress,
+     * registerNametag, or nametag recovery.
+     *
+     * @returns Array of TrackedAddress entries sorted by index, excluding hidden ones
      */
-    private getCurrentAddressId;
+    getActiveAddresses(): TrackedAddress[];
+    /**
+     * Get all tracked addresses, including hidden ones.
+     *
+     * @returns Array of all TrackedAddress entries sorted by index
+     */
+    getAllTrackedAddresses(): TrackedAddress[];
+    /**
+     * Get tracked address info by index.
+     *
+     * @param index - Address index
+     * @returns TrackedAddress or undefined if not tracked
+     */
+    getTrackedAddress(index: number): TrackedAddress | undefined;
+    /**
+     * Set visibility of a tracked address.
+     * Hidden addresses are not returned by getActiveAddresses() but remain tracked.
+     *
+     * @param index - Address index to hide/unhide
+     * @param hidden - true to hide, false to show
+     * @throws Error if address index is not tracked
+     */
+    setAddressHidden(index: number, hidden: boolean): Promise<void>;
     /**
      * Switch to a different address by index
      * This changes the active identity to the derived address at the specified index.
@@ -2277,6 +2810,12 @@ declare class Sphere {
      * ```
      */
     deriveAddress(index: number, isChange?: boolean): AddressInfo;
+    /**
+     * Internal address derivation without ensureReady() check.
+     * Used during initialization (loadTrackedAddresses, ensureAddressTracked)
+     * when _initialized is still false.
+     */
+    private _deriveAddressInternal;
     /**
      * Derive address at a full BIP32 path
      *
@@ -2336,6 +2875,21 @@ declare class Sphere {
      * @returns PROXY address string or undefined if no nametag
      */
     getProxyAddress(): string | undefined;
+    /**
+     * Resolve any identifier to full peer information.
+     * Accepts @nametag, bare nametag, DIRECT://, PROXY://, L1 address, or transport pubkey.
+     *
+     * @example
+     * ```ts
+     * const peer = await sphere.resolve('@alice');
+     * const peer = await sphere.resolve('DIRECT://...');
+     * const peer = await sphere.resolve('alpha1...');
+     * const peer = await sphere.resolve('ab12cd...'); // 64-char hex transport pubkey
+     * ```
+     */
+    resolve(identifier: string): Promise<PeerInfo | null>;
+    /** Compute and cache the PROXY address from the current nametag */
+    private _updateCachedProxyAddress;
     /**
      * Register a nametag for the current active address
      * Each address can have its own independent nametag
@@ -2356,10 +2910,9 @@ declare class Sphere {
      */
     registerNametag(nametag: string): Promise<void>;
     /**
-     * Persist address nametags to storage
-     * Format: { "DIRECT://abc...xyz": { "0": "alice", "1": "alice2" }, ... }
+     * Persist tracked addresses to storage (only minimal fields via StorageProvider)
      */
-    private persistAddressNametags;
+    private persistTrackedAddresses;
     /**
      * Mint a nametag token on-chain (like Sphere wallet and lottery)
      * This creates the nametag token required for receiving tokens via PROXY addresses (@nametag)
@@ -2386,22 +2939,42 @@ 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)
+     * Load tracked addresses from storage.
+     * Falls back to migrating from old ADDRESS_NAMETAGS format.
+     */
+    private loadTrackedAddresses;
+    /**
+     * Migrate from old ADDRESS_NAMETAGS format to tracked addresses.
+     * Scans HD indices 0..19 to match addressIds from the old format.
+     * Populates both _trackedAddresses and _addressNametags.
+     */
+    private migrateFromOldNametagFormat;
+    /**
+     * Ensure an address is tracked in the registry.
+     * If not yet tracked, derives full info and creates the entry.
+     */
+    private ensureAddressTracked;
+    /**
+     * Persist nametag cache to storage.
+     * Format: { addressId: { "0": "alice", "1": "alice2" } }
+     */
+    private persistAddressNametags;
+    /**
+     * Load nametag cache from storage.
      */
     private loadAddressNametags;
     /**
-     * Sync nametag with Nostr on wallet load
-     * If local nametag exists but not registered on Nostr, re-register it
+     * Publish identity binding via transport.
+     * Always publishes base identity (chainPubkey, l1Address, directAddress).
+     * If nametag is set, also publishes nametag hash, proxy address, encrypted nametag.
      */
-    private syncNametagWithNostr;
+    private syncIdentityWithTransport;
     /**
-     * Recover nametag from Nostr after wallet import
+     * Recover nametag from transport after wallet import.
      * Searches for encrypted nametag events authored by this wallet's pubkey
-     * and decrypts them to restore the nametag association
+     * and decrypts them to restore the nametag association.
      */
-    private recoverNametagFromNostr;
+    private recoverNametagFromTransport;
     /**
      * Validate nametag format
      */