@unicitylabs/sphere-sdk 0.2.2 → 0.2.5

package/dist/core/index.d.ts

@@ -272,147 +272,6 @@ 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
  */
@@ -429,19 +288,8 @@ interface InstantSplitResult {
     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;
+    /** Promise that resolves when background processing completes (change token saved) */
+    backgroundPromise?: Promise<void>;
 }
 /**
  * Options for instant split send operation
@@ -476,6 +324,17 @@ interface BackgroundProgressStatus {
     message: string;
     error?: string;
 }
+/** Result of resolveUnconfirmed() */
+interface UnconfirmedResolutionResult {
+    resolved: number;
+    stillPending: number;
+    failed: number;
+    details: Array<{
+        tokenId: string;
+        stage: string;
+        status: 'resolved' | 'pending' | 'failed';
+    }>;
+}
 
 /**
  * SDK2 Core Types
@@ -529,6 +388,14 @@ interface Asset {
     readonly iconUrl?: string;
     readonly totalAmount: string;
     readonly tokenCount: number;
+    /** Sum of confirmed token amounts (smallest units) */
+    readonly confirmedAmount: string;
+    /** Sum of unconfirmed (submitted/pending) token amounts (smallest units) */
+    readonly unconfirmedAmount: string;
+    /** Number of confirmed tokens aggregated */
+    readonly confirmedTokenCount: number;
+    /** Number of unconfirmed tokens aggregated */
+    readonly unconfirmedTokenCount: 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) */
@@ -542,6 +409,7 @@ interface Asset {
 }
 type TransferStatus = 'pending' | 'submitted' | 'confirmed' | 'delivered' | 'completed' | 'failed';
 type AddressMode = 'auto' | 'direct' | 'proxy';
+type TransferMode = 'instant' | 'conservative';
 interface TransferRequest {
     readonly coinId: string;
     readonly amount: string;
@@ -549,12 +417,31 @@ interface TransferRequest {
     readonly memo?: string;
     /** Address mode: 'auto' (default) uses directAddress if available, 'direct' forces DIRECT, 'proxy' forces PROXY */
     readonly addressMode?: AddressMode;
+    /** Transfer mode: 'instant' (default) sends via Nostr immediately, 'conservative' collects all proofs first */
+    readonly transferMode?: TransferMode;
+}
+/**
+ * Per-token transfer detail tracking the on-chain commitment or split operation
+ * for each source token involved in a transfer.
+ */
+interface TokenTransferDetail {
+    /** Source token ID that was consumed in this transfer */
+    readonly sourceTokenId: string;
+    /** Transfer method used for this token */
+    readonly method: 'direct' | 'split';
+    /** Aggregator commitment request ID hex (for direct transfers) */
+    readonly requestIdHex?: string;
+    /** Split group ID (for split transfers — correlates sender/recipient/change tokens) */
+    readonly splitGroupId?: string;
+    /** Nostr event ID (for split transfers delivered via Nostr) */
+    readonly nostrEventId?: string;
 }
 interface TransferResult {
     readonly id: string;
     status: TransferStatus;
     readonly tokens: Token[];
-    txHash?: string;
+    /** Per-token transfer details — one entry per source token consumed */
+    readonly tokenTransfers: TokenTransferDetail[];
     error?: string;
 }
 interface IncomingTransfer {
@@ -578,7 +465,7 @@ interface PaymentRequest {
     readonly coinId: string;
     /** Optional message/memo */
     readonly message?: string;
-    /** Recipient nametag (who should pay) */
+    /** Where tokens should be sent */
     readonly recipientNametag?: string;
     /** Custom metadata */
     readonly metadata?: Record<string, unknown>;
@@ -605,7 +492,7 @@ interface IncomingPaymentRequest$1 {
     readonly symbol: string;
     /** Message from sender */
     readonly message?: string;
-    /** Who this request is for (our nametag) */
+    /** Requester's nametag (where tokens should be sent) */
     readonly recipientNametag?: string;
     /** Original request ID from sender */
     readonly requestId: string;
@@ -731,7 +618,7 @@ interface TrackedAddress extends TrackedAddressEntry {
     /** 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';
+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' | 'sync:remote-update';
 interface SphereEventMap {
     'transfer:incoming': IncomingTransfer;
     'transfer:confirmed': TransferResult;
@@ -790,6 +677,14 @@ interface SphereEventMap {
         index: number;
         addressId: string;
     };
+    'sync:remote-update': {
+        providerId: string;
+        name: string;
+        sequence: number;
+        cid: string;
+        added: number;
+        removed: number;
+    };
 }
 type SphereEventHandler<T extends SphereEventType> = (data: SphereEventMap[T]) => void;
 /**
@@ -1012,6 +907,12 @@ interface TransportProvider extends BaseProvider {
      * @returns Unsubscribe function
      */
     onInstantSplitReceived?(handler: InstantSplitBundleHandler): () => void;
+    /**
+     * Fetch pending events from transport (one-shot query).
+     * Creates a temporary subscription, processes events through normal handlers,
+     * and resolves after EOSE (End Of Stored Events).
+     */
+    fetchPendingEvents?(): Promise<void>;
 }
 /**
  * Payload for sending instant split bundles
@@ -1076,7 +977,7 @@ interface IncomingTokenTransfer {
     payload: TokenTransferPayload;
     timestamp: number;
 }
-type TokenTransferHandler = (transfer: IncomingTokenTransfer) => void;
+type TokenTransferHandler = (transfer: IncomingTokenTransfer) => void | Promise<void>;
 interface PaymentRequestPayload {
     /** Amount requested (in smallest units) */
     amount: string | bigint;
@@ -1094,6 +995,8 @@ interface IncomingPaymentRequest {
     id: string;
     /** Transport-specific pubkey of sender */
     senderTransportPubkey: string;
+    /** Sender's nametag (if included in encrypted content) */
+    senderNametag?: string;
     /** Parsed request data */
     request: {
         requestId: string;
@@ -1252,6 +1155,12 @@ declare class L1PaymentsModule {
     private _transport?;
     constructor(config?: L1PaymentsModuleConfig);
     initialize(deps: L1PaymentsModuleDependencies): Promise<void>;
+    /**
+     * Ensure the Fulcrum WebSocket is connected. Called lazily before any
+     * operation that needs the network. If the singleton is already connected
+     * (e.g. by the address scanner), this is a no-op.
+     */
+    private ensureConnected;
     destroy(): void;
     /**
      * Check if a string looks like an L1 address (alpha1... or alphat1...)
@@ -1261,7 +1170,7 @@ declare class L1PaymentsModule {
      * Resolve recipient to L1 address
      * Supports: L1 address (alpha1...), nametag (with or without @)
      */
-    private resolveL1Address;
+    resolveL1Address(recipient: string): Promise<string>;
     /**
      * Resolve nametag to L1 address using transport provider
      */
@@ -1434,7 +1343,7 @@ interface TokenStorageProvider<TData = unknown> extends BaseProvider {
      */
     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';
+type StorageEventType = 'storage:saving' | 'storage:saved' | 'storage:loading' | 'storage:loaded' | 'storage:error' | 'storage:remote-updated' | 'sync:started' | 'sync:completed' | 'sync:conflict' | 'sync:error';
 interface StorageEvent {
     type: StorageEventType;
     timestamp: number;
@@ -1690,7 +1599,30 @@ interface TransactionHistoryEntry {
     timestamp: number;
     recipientNametag?: string;
     senderPubkey?: string;
-    txHash?: string;
+    /** TransferResult.id that created this entry (links history to transfer operation) */
+    transferId?: string;
+}
+interface ReceiveOptions {
+    /** Wait for all unconfirmed tokens to be finalized (default: false).
+     *  When false, calls resolveUnconfirmed() once to submit pending commitments.
+     *  When true, polls resolveUnconfirmed() + load() until all confirmed or timeout. */
+    finalize?: boolean;
+    /** Finalization timeout in ms (default: 60000). Only used when finalize=true. */
+    timeout?: number;
+    /** Poll interval in ms (default: 2000). Only used when finalize=true. */
+    pollInterval?: number;
+    /** Progress callback after each resolveUnconfirmed() poll. Only used when finalize=true. */
+    onProgress?: (result: UnconfirmedResolutionResult) => void;
+}
+interface ReceiveResult {
+    /** Newly received incoming transfers. */
+    transfers: IncomingTransfer[];
+    /** Finalization result (from resolveUnconfirmed). */
+    finalization?: UnconfirmedResolutionResult;
+    /** Whether finalization timed out (only when finalize=true). */
+    timedOut?: boolean;
+    /** Duration of finalization in ms (only when finalize=true). */
+    finalizationDurationMs?: number;
 }
 interface PaymentsModuleConfig {
     /** Auto-sync after operations */
@@ -1703,8 +1635,8 @@ interface PaymentsModuleConfig {
     maxRetries?: number;
     /** Enable debug logging */
     debug?: boolean;
-    /** L1 (ALPHA blockchain) configuration */
-    l1?: L1PaymentsModuleConfig;
+    /** L1 (ALPHA blockchain) configuration. Set to null to explicitly disable L1. */
+    l1?: L1PaymentsModuleConfig | null;
 }
 interface PaymentsModuleDependencies {
     identity: FullIdentity;
@@ -1730,6 +1662,7 @@ declare class PaymentsModule {
     readonly l1: L1PaymentsModule | null;
     private tokens;
     private pendingTransfers;
+    private pendingBackgroundTasks;
     private tombstones;
     private archivedTokens;
     private forkedTokens;
@@ -1747,8 +1680,17 @@ declare class PaymentsModule {
     private proofPollingInterval;
     private static readonly PROOF_POLLING_INTERVAL_MS;
     private static readonly PROOF_POLLING_MAX_ATTEMPTS;
+    private storageEventUnsubscribers;
+    private syncDebounceTimer;
+    private static readonly SYNC_DEBOUNCE_MS;
+    /** Sync coalescing: concurrent sync() calls share the same operation */
+    private _syncInProgress;
     constructor(config?: PaymentsModuleConfig);
-    /** Get module configuration */
+    /**
+     * Get the current module configuration (excluding L1 config).
+     *
+     * @returns Resolved configuration with all defaults applied.
+     */
     getConfig(): Omit<Required<PaymentsModuleConfig>, 'l1'>;
     /** Price provider (optional) */
     private priceProvider;
@@ -1758,11 +1700,18 @@ declare class PaymentsModule {
      */
     initialize(deps: PaymentsModuleDependencies): void;
     /**
-     * Load tokens from storage
+     * Load all token data from storage providers and restore wallet state.
+     *
+     * Loads tokens, nametag data, transaction history, and pending transfers
+     * from configured storage providers. Restores pending V5 tokens and
+     * triggers a fire-and-forget {@link resolveUnconfirmed} call.
      */
     load(): Promise<void>;
     /**
-     * Cleanup resources
+     * Cleanup all subscriptions, polling jobs, and pending resolvers.
+     *
+     * Should be called when the wallet is being shut down or the module is
+     * no longer needed. Also destroys the L1 sub-module if present.
      */
     destroy(): void;
     /**
@@ -1814,11 +1763,19 @@ declare class PaymentsModule {
      * @param senderPubkey - Sender's public key for verification
      * @returns Processing result with finalized token
      */
-    processInstantSplitBundle(bundle: InstantSplitBundle, senderPubkey: string): Promise<InstantSplitProcessResult>;
+    private processInstantSplitBundle;
     /**
-     * Check if a payload is an instant split bundle
+     * Synchronous V4 bundle processing (dev mode only).
+     * Kept for backward compatibility with V4 bundles.
      */
-    isInstantSplitBundle(payload: unknown): payload is InstantSplitBundle;
+    private processInstantSplitBundleSync;
+    /**
+     * Type-guard: check whether a payload is a valid {@link InstantSplitBundle} (V4 or V5).
+     *
+     * @param payload - The object to test.
+     * @returns `true` if the payload matches the InstantSplitBundle shape.
+     */
+    private isInstantSplitBundle;
     /**
      * Send a payment request to someone
      * @param recipientPubkeyOrNametag - Recipient's pubkey or @nametag
@@ -1840,27 +1797,45 @@ declare class PaymentsModule {
         status?: PaymentRequestStatus;
     }): IncomingPaymentRequest$1[];
     /**
-     * Get pending payment requests count
+     * Get the count of payment requests with status `'pending'`.
+     *
+     * @returns Number of pending incoming payment requests.
      */
     getPendingPaymentRequestsCount(): number;
     /**
-     * Accept a payment request (marks it as accepted, user should then call send())
+     * Accept a payment request and notify the requester.
+     *
+     * Marks the request as `'accepted'` and sends a response via transport.
+     * The caller should subsequently call {@link send} to fulfill the payment.
+     *
+     * @param requestId - ID of the incoming payment request to accept.
      */
     acceptPaymentRequest(requestId: string): Promise<void>;
     /**
-     * Reject a payment request
+     * Reject a payment request and notify the requester.
+     *
+     * @param requestId - ID of the incoming payment request to reject.
      */
     rejectPaymentRequest(requestId: string): Promise<void>;
     /**
-     * Mark a payment request as paid (after successful transfer)
+     * Mark a payment request as paid (local status update only).
+     *
+     * Typically called after a successful {@link send} to record that the
+     * request has been fulfilled.
+     *
+     * @param requestId - ID of the incoming payment request to mark as paid.
      */
     markPaymentRequestPaid(requestId: string): void;
     /**
-     * Clear processed (non-pending) payment requests
+     * Remove all non-pending incoming payment requests from memory.
+     *
+     * Keeps only requests with status `'pending'`.
      */
     clearProcessedPaymentRequests(): void;
     /**
-     * Remove a specific payment request
+     * Remove a specific incoming payment request by ID.
+     *
+     * @param requestId - ID of the payment request to remove.
      */
     removePaymentRequest(requestId: string): void;
     /**
@@ -1891,15 +1866,21 @@ declare class PaymentsModule {
      */
     waitForPaymentResponse(requestId: string, timeoutMs?: number): Promise<PaymentRequestResponse>;
     /**
-     * Cancel waiting for a payment response
+     * Cancel an active {@link waitForPaymentResponse} call.
+     *
+     * The pending promise is rejected with a `'Cancelled'` error.
+     *
+     * @param requestId - The outgoing request ID whose wait should be cancelled.
      */
     cancelWaitForPaymentResponse(requestId: string): void;
     /**
-     * Remove an outgoing payment request
+     * Remove an outgoing payment request and cancel any pending wait.
+     *
+     * @param requestId - ID of the outgoing request to remove.
      */
     removeOutgoingPaymentRequest(requestId: string): void;
     /**
-     * Clear completed/expired outgoing payment requests
+     * Remove all outgoing payment requests that are `'paid'`, `'rejected'`, or `'expired'`.
      */
     clearCompletedOutgoingPaymentRequests(): void;
     private handlePaymentRequestResponse;
@@ -1907,36 +1888,141 @@ declare class PaymentsModule {
      * Send a response to a payment request (used internally by accept/reject/pay methods)
      */
     private sendPaymentRequestResponse;
+    /**
+     * Fetch and process pending incoming transfers from the transport layer.
+     *
+     * Performs a one-shot query to fetch all pending events, processes them
+     * through the existing pipeline, and resolves after all stored events
+     * are handled. Useful for batch/CLI apps that need explicit receive.
+     *
+     * When `finalize` is true, polls resolveUnconfirmed() + load() until all
+     * tokens are confirmed or the timeout expires. Otherwise calls
+     * resolveUnconfirmed() once to submit pending commitments.
+     *
+     * @param options - Optional receive options including finalization control
+     * @param callback - Optional callback invoked for each newly received transfer
+     * @returns ReceiveResult with transfers and finalization metadata
+     */
+    receive(options?: ReceiveOptions, callback?: (transfer: IncomingTransfer) => void): Promise<ReceiveResult>;
     /**
      * Set or update price provider
      */
     setPriceProvider(provider: PriceProvider): void;
     /**
-     * Get total portfolio value in USD
-     * Returns null if PriceProvider is not configured
+     * Wait for all pending background operations (e.g., instant split change token creation).
+     * Call this before process exit to ensure all tokens are saved.
+     */
+    waitForPendingOperations(): Promise<void>;
+    /**
+     * Get total portfolio value in USD.
+     * Returns null if PriceProvider is not configured.
+     */
+    getFiatBalance(): Promise<number | null>;
+    /**
+     * Get token balances grouped by coin type.
+     *
+     * Returns an array of {@link Asset} objects, one per coin type held.
+     * Each entry includes confirmed and unconfirmed breakdowns. Tokens with
+     * status `'spent'`, `'invalid'`, or `'transferring'` are excluded.
+     *
+     * This is synchronous — no price data is included. Use {@link getAssets}
+     * for the async version with fiat pricing.
+     *
+     * @param coinId - Optional coin ID to filter by (e.g. hex string). When omitted, all coin types are returned.
+     * @returns Array of balance summaries (synchronous — no await needed).
      */
-    getBalance(): Promise<number | null>;
+    getBalance(coinId?: string): Asset[];
     /**
-     * Get aggregated assets (tokens grouped by coinId) with price data
-     * Only includes confirmed tokens
+     * Get aggregated assets (tokens grouped by coinId) with price data.
+     * Includes both confirmed and unconfirmed tokens with breakdown.
      */
     getAssets(coinId?: string): Promise<Asset[]>;
     /**
-     * Get all tokens
+     * Aggregate tokens by coinId with confirmed/unconfirmed breakdown.
+     * Excludes tokens with status 'spent', 'invalid', or 'transferring'.
+     */
+    private aggregateTokens;
+    /**
+     * Get all tokens, optionally filtered by coin type and/or status.
+     *
+     * @param filter - Optional filter criteria.
+     * @param filter.coinId - Return only tokens of this coin type.
+     * @param filter.status - Return only tokens with this status (e.g. `'submitted'` for unconfirmed).
+     * @returns Array of matching {@link Token} objects (synchronous).
      */
     getTokens(filter?: {
         coinId?: string;
         status?: TokenStatus;
     }): Token[];
     /**
-     * Get single token
+     * Get a single token by its local ID.
+     *
+     * @param id - The local UUID assigned when the token was added.
+     * @returns The token, or `undefined` if not found.
      */
     getToken(id: string): Token | undefined;
     /**
-     * Add a token
-     * 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)
+     * Attempt to resolve unconfirmed (status `'submitted'`) tokens by acquiring
+     * their missing aggregator proofs.
+     *
+     * Each unconfirmed V5 token progresses through stages:
+     * `RECEIVED` → `MINT_SUBMITTED` → `MINT_PROVEN` → `TRANSFER_SUBMITTED` → `FINALIZED`
+     *
+     * Uses 500 ms quick-timeouts per proof check so the call returns quickly even
+     * when proofs are not yet available. Tokens that exceed 50 failed attempts are
+     * marked `'invalid'`.
+     *
+     * Automatically called (fire-and-forget) by {@link load}.
+     *
+     * @returns Summary with counts of resolved, still-pending, and failed tokens plus per-token details.
+     */
+    resolveUnconfirmed(): Promise<UnconfirmedResolutionResult>;
+    /**
+     * Process a single V5 token through its finalization stages with quick-timeout proof checks.
+     */
+    private resolveV5Token;
+    /**
+     * Non-blocking proof check with 500ms timeout.
+     */
+    private quickProofCheck;
+    /**
+     * Perform V5 bundle finalization from stored bundle data and proofs.
+     * Extracted from InstantSplitProcessor.processV5Bundle() steps 4-10.
+     */
+    private finalizeFromV5Bundle;
+    /**
+     * Parse pending finalization metadata from token's sdkData.
+     */
+    private parsePendingFinalization;
+    /**
+     * Update pending finalization metadata in token's sdkData.
+     * Creates a new token object since sdkData is readonly.
+     */
+    private updatePendingFinalization;
+    /**
+     * Save pending V5 tokens to key-value storage.
+     * These tokens can't be serialized to TXF format (no genesis/state),
+     * so we persist them separately and restore on load().
+     */
+    private savePendingV5Tokens;
+    /**
+     * Load pending V5 tokens from key-value storage and merge into tokens map.
+     * Called during load() to restore tokens that TXF format can't represent.
+     */
+    private loadPendingV5Tokens;
+    /**
+     * Add a token to the wallet.
+     *
+     * Tokens are uniquely identified by a `(tokenId, stateHash)` composite key.
+     * Duplicate detection:
+     * - **Tombstoned** — rejected if the exact `(tokenId, stateHash)` pair has a tombstone.
+     * - **Exact duplicate** — rejected if a token with the same composite key already exists.
+     * - **State replacement** — if the same `tokenId` exists with a *different* `stateHash`,
+     *   the old state is archived and replaced with the incoming one.
+     *
+     * @param token - The token to add.
+     * @param skipHistory - When `true`, do not create a `RECEIVED` transaction history entry (default `false`).
+     * @returns `true` if the token was added, `false` if rejected as duplicate or tombstoned.
      */
     addToken(token: Token, skipHistory?: boolean): Promise<boolean>;
     /**
@@ -1951,11 +2037,24 @@ declare class PaymentsModule {
      */
     private loadTokensFromFileStorage;
     /**
-     * Update an existing token
+     * Update an existing token or add it if not found.
+     *
+     * Looks up the token by genesis `tokenId` (from `sdkData`) first, then by
+     * `token.id`. If no match is found, falls back to {@link addToken}.
+     *
+     * @param token - The token with updated data. Must include a valid `id`.
      */
     updateToken(token: Token): Promise<void>;
     /**
-     * Remove a token by ID
+     * Remove a token from the wallet.
+     *
+     * The token is archived first, then a tombstone `(tokenId, stateHash)` is
+     * created to prevent re-addition via Nostr re-delivery. A `SENT` history
+     * entry is created unless `skipHistory` is `true`.
+     *
+     * @param tokenId - Local UUID of the token to remove.
+     * @param recipientNametag - Optional nametag of the transfer recipient (for history).
+     * @param skipHistory - When `true`, skip creating a transaction history entry (default `false`).
      */
     removeToken(tokenId: string, recipientNametag?: string, skipHistory?: boolean): Promise<void>;
     /**
@@ -1964,78 +2063,145 @@ declare class PaymentsModule {
      */
     private deleteTokenFiles;
     /**
-     * Get all tombstones
+     * Get all tombstone entries.
+     *
+     * Each tombstone is keyed by `(tokenId, stateHash)` and prevents a spent
+     * token state from being re-added (e.g. via Nostr re-delivery).
+     *
+     * @returns A shallow copy of the tombstone array.
      */
     getTombstones(): TombstoneEntry[];
     /**
-     * Check if token state is tombstoned
+     * Check whether a specific `(tokenId, stateHash)` combination is tombstoned.
+     *
+     * @param tokenId - The genesis token ID.
+     * @param stateHash - The state hash of the token version to check.
+     * @returns `true` if the exact combination has been tombstoned.
      */
     isStateTombstoned(tokenId: string, stateHash: string): boolean;
     /**
-     * Merge remote tombstones
-     * @returns number of local tokens removed
+     * Merge tombstones received from a remote sync source.
+     *
+     * Any local token whose `(tokenId, stateHash)` matches a remote tombstone is
+     * removed. The remote tombstones are then added to the local set (union merge).
+     *
+     * @param remoteTombstones - Tombstone entries from the remote source.
+     * @returns Number of local tokens that were removed.
      */
     mergeTombstones(remoteTombstones: TombstoneEntry[]): Promise<number>;
     /**
-     * Prune old tombstones
+     * Remove tombstones older than `maxAge` and cap the list at 100 entries.
+     *
+     * @param maxAge - Maximum age in milliseconds (default: 30 days).
      */
     pruneTombstones(maxAge?: number): Promise<void>;
     /**
-     * Get archived tokens
+     * Get all archived (spent/superseded) tokens in TXF format.
+     *
+     * Archived tokens are kept for recovery and sync purposes. The map key is
+     * the genesis token ID.
+     *
+     * @returns A shallow copy of the archived token map.
      */
     getArchivedTokens(): Map<string, TxfToken>;
     /**
-     * Get best archived version of a token
+     * Get the best (most committed transactions) archived version of a token.
+     *
+     * Searches both archived and forked token maps and returns the version with
+     * the highest number of committed transactions.
+     *
+     * @param tokenId - The genesis token ID to look up.
+     * @returns The best TXF token version, or `null` if not found.
      */
     getBestArchivedVersion(tokenId: string): TxfToken | null;
     /**
-     * Merge remote archived tokens
-     * @returns number of tokens updated/added
+     * Merge archived tokens from a remote sync source.
+     *
+     * For each remote token:
+     * - If missing locally, it is added.
+     * - If the remote version is an incremental update of the local, it replaces it.
+     * - If the histories diverge (fork), the remote version is stored via {@link storeForkedToken}.
+     *
+     * @param remoteArchived - Map of genesis token ID → TXF token from remote.
+     * @returns Number of tokens that were updated or added locally.
      */
     mergeArchivedTokens(remoteArchived: Map<string, TxfToken>): Promise<number>;
     /**
-     * Prune archived tokens
+     * Prune archived tokens to keep at most `maxCount` entries.
+     *
+     * Oldest entries (by insertion order) are removed first.
+     *
+     * @param maxCount - Maximum number of archived tokens to retain (default: 100).
      */
     pruneArchivedTokens(maxCount?: number): Promise<void>;
     /**
-     * Get forked tokens
+     * Get all forked token versions.
+     *
+     * Forked tokens represent alternative histories detected during sync.
+     * The map key is `{tokenId}_{stateHash}`.
+     *
+     * @returns A shallow copy of the forked tokens map.
      */
     getForkedTokens(): Map<string, TxfToken>;
     /**
-     * Store a forked token
+     * Store a forked token version (alternative history).
+     *
+     * No-op if the exact `(tokenId, stateHash)` key already exists.
+     *
+     * @param tokenId - Genesis token ID.
+     * @param stateHash - State hash of this forked version.
+     * @param txfToken - The TXF token data to store.
      */
     storeForkedToken(tokenId: string, stateHash: string, txfToken: TxfToken): Promise<void>;
     /**
-     * Merge remote forked tokens
-     * @returns number of tokens added
+     * Merge forked tokens from a remote sync source. Only new keys are added.
+     *
+     * @param remoteForked - Map of `{tokenId}_{stateHash}` → TXF token from remote.
+     * @returns Number of new forked tokens added.
      */
     mergeForkedTokens(remoteForked: Map<string, TxfToken>): Promise<number>;
     /**
-     * Prune forked tokens
+     * Prune forked tokens to keep at most `maxCount` entries.
+     *
+     * @param maxCount - Maximum number of forked tokens to retain (default: 50).
      */
     pruneForkedTokens(maxCount?: number): Promise<void>;
     /**
-     * Get transaction history
+     * Get the transaction history sorted newest-first.
+     *
+     * @returns Array of {@link TransactionHistoryEntry} objects in descending timestamp order.
      */
     getHistory(): TransactionHistoryEntry[];
     /**
-     * Add to transaction history
+     * Append an entry to the transaction history.
+     *
+     * A unique `id` is auto-generated. The entry is immediately persisted to storage.
+     *
+     * @param entry - History entry fields (without `id`).
      */
     addToHistory(entry: Omit<TransactionHistoryEntry, 'id'>): Promise<void>;
     /**
-     * Set nametag for current identity
+     * Set the nametag data for the current identity.
+     *
+     * Persists to both key-value storage and file storage (lottery compatibility).
+     *
+     * @param nametag - The nametag data including minted token JSON.
      */
     setNametag(nametag: NametagData): Promise<void>;
     /**
-     * Get nametag
+     * Get the current nametag data.
+     *
+     * @returns The nametag data, or `null` if no nametag is set.
      */
     getNametag(): NametagData | null;
     /**
-     * Check if has nametag
+     * Check whether a nametag is currently set.
+     *
+     * @returns `true` if nametag data is present.
      */
     hasNametag(): boolean;
     /**
-     * Clear nametag
+     * Remove the current nametag data from memory and storage.
      */
     clearNametag(): Promise<void>;
     /**
@@ -2062,30 +2228,60 @@ declare class PaymentsModule {
      */
     isNametagAvailable(nametag: string): Promise<boolean>;
     /**
-     * Sync with all token storage providers (IPFS, MongoDB, etc.)
-     * Syncs with each provider and merges results
+     * Sync local token state with all configured token storage providers (IPFS, file, etc.).
+     *
+     * For each provider, the local data is packaged into TXF storage format, sent
+     * to the provider's `sync()` method, and the merged result is applied locally.
+     * Emits `sync:started`, `sync:completed`, and `sync:error` events.
+     *
+     * @returns Summary with counts of tokens added and removed during sync.
      */
     sync(): Promise<{
         added: number;
         removed: number;
     }>;
+    private _doSync;
+    /**
+     * Subscribe to 'storage:remote-updated' events from all token storage providers.
+     * When a provider emits this event, a debounced sync is triggered.
+     */
+    private subscribeToStorageEvents;
+    /**
+     * Unsubscribe from all storage provider events and clear debounce timer.
+     */
+    private unsubscribeStorageEvents;
+    /**
+     * Debounced sync triggered by a storage:remote-updated event.
+     * Waits 500ms to batch rapid updates, then performs sync.
+     */
+    private debouncedSyncFromRemoteUpdate;
     /**
      * Get all active token storage providers
      */
     private getTokenStorageProviders;
     /**
-     * Update token storage providers (called when providers are added/removed dynamically)
+     * Replace the set of token storage providers at runtime.
+     *
+     * Use when providers are added or removed dynamically (e.g. IPFS node started).
+     *
+     * @param providers - New map of provider ID → TokenStorageProvider.
      */
     updateTokenStorageProviders(providers: Map<string, TokenStorageProvider<TxfStorageDataBase>>): void;
     /**
-     * Validate tokens with aggregator
+     * Validate all tokens against the aggregator (oracle provider).
+     *
+     * Tokens that fail validation or are detected as spent are marked `'invalid'`.
+     *
+     * @returns Object with arrays of valid and invalid tokens.
      */
     validate(): Promise<{
         valid: Token[];
         invalid: Token[];
     }>;
     /**
-     * Get pending transfers
+     * Get all in-progress (pending) outgoing transfers.
+     *
+     * @returns Array of {@link TransferResult} objects for transfers that have not yet completed.
      */
     getPendingTransfers(): TransferResult[];
     /**
@@ -2357,6 +2553,8 @@ type LegacyFileType = 'dat' | 'txt' | 'json' | 'mnemonic' | 'unknown';
  */
 type DecryptionProgressCallback = (iteration: number, total: number) => Promise<void> | void;
 
+declare function isValidNametag(nametag: string): boolean;
+
 /** Options for creating a new wallet */
 interface SphereCreateOptions {
     /** BIP39 mnemonic (12 or 24 words) */
@@ -2710,6 +2908,7 @@ declare class Sphere {
         transport: TransportProvider;
         oracle: OracleProvider;
         tokenStorage?: TokenStorageProvider<TxfStorageDataBase>;
+        l1?: L1Config;
     }): Promise<{
         success: boolean;
         mnemonic?: string;
@@ -2764,6 +2963,8 @@ declare class Sphere {
         tokenStorage?: TokenStorageProvider<TxfStorageDataBase>;
         /** Optional nametag to register */
         nametag?: string;
+        /** L1 (ALPHA blockchain) configuration */
+        l1?: L1Config;
     }): Promise<{
         success: boolean;
         sphere?: Sphere;
@@ -3084,9 +3285,9 @@ declare class Sphere {
      */
     private recoverNametagFromTransport;
     /**
-     * Validate nametag format
+     * Strip @ prefix and normalize a nametag (lowercase, phone E.164, strip @unicity suffix).
      */
-    private validateNametag;
+    private cleanNametag;
     destroy(): Promise<void>;
     private storeMnemonic;
     private storeMasterKey;
@@ -3367,4 +3568,4 @@ declare function randomHex(byteLength: number): string;
  */
 declare function randomUUID(): string;
 
-export { type AddressInfo, CHARSET, CurrencyUtils, DEFAULT_DERIVATION_PATH, DEFAULT_TOKEN_DECIMALS, type DerivedKey, type EncryptedData, type EncryptionOptions, type KeyPair, type L1Config, type MasterKey, type ScanAddressProgress, type ScanAddressesOptions, type ScanAddressesResult, type ScannedAddressResult, Sphere, type SphereCreateOptions, type SphereImportOptions, type SphereInitOptions, type SphereInitResult, type SphereLoadOptions, base58Decode, base58Encode, bytesToHex, computeHash160, convertBits, createAddress, createBech32, createKeyPair, createSphere, decodeBech32, decrypt, decryptJson, decryptMnemonic, decryptSimple, decryptWithSalt, deriveAddressInfo, deriveChildKey, deriveKeyAtPath, deserializeEncrypted, doubleSha256, ec, encodeBech32, encrypt, encryptMnemonic, encryptSimple, entropyToMnemonic, extractFromText, findPattern, formatAmount, generateAddressInfo, generateMasterKey, generateMnemonic, generateRandomKey, getAddressHrp, getPublicKey, getSphere, hash160, hash160ToBytes, hexToBytes, identityFromMnemonic, identityFromMnemonicSync, importSphere, initSphere, isEncryptedData, isValidBech32, isValidPrivateKey, loadSphere, mnemonicToEntropy, mnemonicToSeed, mnemonicToSeedSync, privateKeyToAddressInfo, publicKeyToAddress, randomBytes, randomHex, randomUUID, ripemd160, scanAddressesImpl, serializeEncrypted, sha256, sleep, sphereExists, toHumanReadable, toSmallestUnit, validateMnemonic };
+export { type AddressInfo, CHARSET, CurrencyUtils, DEFAULT_DERIVATION_PATH, DEFAULT_TOKEN_DECIMALS, type DerivedKey, type EncryptedData, type EncryptionOptions, type KeyPair, type L1Config, type MasterKey, type ScanAddressProgress, type ScanAddressesOptions, type ScanAddressesResult, type ScannedAddressResult, Sphere, type SphereCreateOptions, type SphereImportOptions, type SphereInitOptions, type SphereInitResult, type SphereLoadOptions, base58Decode, base58Encode, bytesToHex, computeHash160, convertBits, createAddress, createBech32, createKeyPair, createSphere, decodeBech32, decrypt, decryptJson, decryptMnemonic, decryptSimple, decryptWithSalt, deriveAddressInfo, deriveChildKey, deriveKeyAtPath, deserializeEncrypted, doubleSha256, ec, encodeBech32, encrypt, encryptMnemonic, encryptSimple, entropyToMnemonic, extractFromText, findPattern, formatAmount, generateAddressInfo, generateMasterKey, generateMnemonic, generateRandomKey, getAddressHrp, getPublicKey, getSphere, hash160, hash160ToBytes, hexToBytes, identityFromMnemonic, identityFromMnemonicSync, importSphere, initSphere, isEncryptedData, isValidBech32, isValidNametag, isValidPrivateKey, loadSphere, mnemonicToEntropy, mnemonicToSeed, mnemonicToSeedSync, privateKeyToAddressInfo, publicKeyToAddress, randomBytes, randomHex, randomUUID, ripemd160, scanAddressesImpl, serializeEncrypted, sha256, sleep, sphereExists, toHumanReadable, toSmallestUnit, validateMnemonic };