@unicitylabs/sphere-sdk 0.2.3 → 0.2.5

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import { Token as Token$1 } from '@unicitylabs/state-transition-sdk/lib/token/Token';
 import elliptic from 'elliptic';
+export { areSameNametag, hashNametag, isPhoneNumber, normalizeNametag } from '@unicitylabs/nostr-js-sdk';
 
 /**
  * Cryptographic utilities for SDK2
@@ -539,6 +540,8 @@ interface InstantSplitResult {
     error?: string;
     /** Whether background processing was started */
     backgroundStarted?: boolean;
+    /** Promise that resolves when background processing completes (change token saved) */
+    backgroundPromise?: Promise<void>;
 }
 /**
  * Result from processing an INSTANT_SPLIT bundle (recipient side)
@@ -614,6 +617,30 @@ interface SplitRecoveryResult {
     /** Total duration of recovery in ms */
     durationMs: number;
 }
+/** Finalization stage for V5 bundles saved as unconfirmed */
+type V5FinalizationStage = 'RECEIVED' | 'MINT_SUBMITTED' | 'MINT_PROVEN' | 'TRANSFER_SUBMITTED' | 'FINALIZED';
+/** Pending finalization metadata stored in token.sdkData */
+interface PendingV5Finalization {
+    type: 'v5_bundle';
+    stage: V5FinalizationStage;
+    bundleJson: string;
+    senderPubkey: string;
+    savedAt: number;
+    lastAttemptAt?: number;
+    attemptCount: number;
+    mintProofJson?: string;
+}
+/** Result of resolveUnconfirmed() */
+interface UnconfirmedResolutionResult {
+    resolved: number;
+    stillPending: number;
+    failed: number;
+    details: Array<{
+        tokenId: string;
+        stage: string;
+        status: 'resolved' | 'pending' | 'failed';
+    }>;
+}
 
 /**
  * Payment Session Types
@@ -837,6 +864,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) */
@@ -850,6 +885,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;
@@ -857,12 +893,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 {
@@ -1039,7 +1094,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;
@@ -1098,6 +1153,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;
 interface SphereConfig {
@@ -1362,6 +1425,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
@@ -1426,7 +1495,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;
@@ -1801,7 +1870,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;
@@ -2142,7 +2211,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 */
@@ -2182,6 +2274,7 @@ declare class PaymentsModule {
     readonly l1: L1PaymentsModule | null;
     private tokens;
     private pendingTransfers;
+    private pendingBackgroundTasks;
     private tombstones;
     private archivedTokens;
     private forkedTokens;
@@ -2199,8 +2292,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;
@@ -2210,11 +2312,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;
     /**
@@ -2266,11 +2375,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;
+    /**
+     * Synchronous V4 bundle processing (dev mode only).
+     * Kept for backward compatibility with V4 bundles.
+     */
+    private processInstantSplitBundleSync;
     /**
-     * Check if a payload is an instant split bundle
+     * 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.
      */
-    isInstantSplitBundle(payload: unknown): payload is InstantSplitBundle;
+    private isInstantSplitBundle;
     /**
      * Send a payment request to someone
      * @param recipientPubkeyOrNametag - Recipient's pubkey or @nametag
@@ -2292,27 +2409,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;
     /**
@@ -2343,15 +2478,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;
@@ -2359,36 +2500,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.
      */
-    getBalance(): Promise<number | null>;
+    getFiatBalance(): Promise<number | null>;
     /**
-     * Get aggregated assets (tokens grouped by coinId) with price data
-     * Only includes confirmed tokens
+     * 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(coinId?: string): Asset[];
+    /**
+     * 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>;
     /**
@@ -2403,11 +2649,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>;
     /**
@@ -2416,78 +2675,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>;
     /**
@@ -2514,30 +2840,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[];
     /**
@@ -2722,6 +3078,8 @@ declare const STORAGE_KEYS: {
     readonly MESSAGES: "messages";
     /** Transaction history for this address */
     readonly TRANSACTION_HISTORY: "transaction_history";
+    /** Pending V5 finalization tokens (unconfirmed instant split tokens) */
+    readonly PENDING_V5_TOKENS: "pending_v5_tokens";
     /** Encrypted BIP39 mnemonic */
     readonly MNEMONIC: "mnemonic";
     /** Encrypted master private key */
@@ -2966,6 +3324,8 @@ interface LegacyFileImportOptions {
     onDecryptProgress?: DecryptionProgressCallback;
 }
 
+declare function isValidNametag(nametag: string): boolean;
+
 /** Options for creating a new wallet */
 interface SphereCreateOptions {
     /** BIP39 mnemonic (12 or 24 words) */
@@ -3696,9 +4056,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;
@@ -5047,4 +5407,4 @@ declare function getCoinIdBySymbol(symbol: string): string | undefined;
  */
 declare function getCoinIdByName(name: string): string | undefined;
 
-export { type AddressInfo, type AddressMode, type AggregatorClient, type AggregatorEvent, type AggregatorEventCallback, type AggregatorEventType, type AggregatorProvider, type AggregatorProviderConfig, type Asset, type BackgroundProgressStatus, type BaseProvider, type BroadcastHandler, type BroadcastMessage, type CMasterKeyData, COIN_TYPES, CoinGeckoPriceProvider, CommunicationsModule, type CommunicationsModuleConfig, type CommunicationsModuleDependencies, DEFAULT_AGGREGATOR_TIMEOUT, DEFAULT_AGGREGATOR_URL, DEFAULT_DERIVATION_PATH, DEFAULT_ELECTRUM_URL, DEFAULT_IPFS_BOOTSTRAP_PEERS, DEFAULT_IPFS_GATEWAYS, DEFAULT_NOSTR_RELAYS, DEV_AGGREGATOR_URL, type DecryptionProgressCallback, type DerivationMode, type DirectMessage, type ExtendedValidationResult, type FullIdentity, type Identity, type IdentityConfig, type InclusionProof, type IncomingBroadcast, type IncomingMessage, type IncomingPaymentRequest$1 as IncomingPaymentRequest, type IncomingTokenTransfer, type IncomingTransfer, type InstantSplitBundle, type InstantSplitBundleV4, type InstantSplitBundleV5, type InstantSplitOptions, type InstantSplitProcessResult, type InstantSplitResult, type InstantSplitV5RecoveryMetadata, type InvalidatedNametagEntry, index as L1, type L1Balance, L1PaymentsModule, type L1PaymentsModuleConfig, type L1PaymentsModuleDependencies, type L1SendRequest, type L1SendResult, type L1Transaction, type L1Utxo, LIMITS, type LegacyFileImportOptions, type LegacyFileInfo, type LegacyFileParseResult, type LegacyFileParsedData, type LegacyFileType, type LoadResult, type LoggingConfig, type MessageHandler, type MintOutboxEntry, type MintParams, type MintResult, NETWORKS, NOSTR_EVENT_KINDS, type NametagData, type NetworkType, type OracleEvent, type OracleEventCallback, type OracleEventType, type OracleProvider, type OutboxEntry, type OutgoingPaymentRequest, type ParsedStorageData, type PaymentRequest, type PaymentRequestHandler$1 as PaymentRequestHandler, type PaymentRequestResponse, type PaymentRequestResponseHandler$1 as PaymentRequestResponseHandler, type PaymentRequestResponseType$1 as PaymentRequestResponseType, type PaymentRequestResult, type PaymentRequestStatus, type PaymentSession, type PaymentSessionDirection, type PaymentSessionError, type PaymentSessionErrorCode, type PaymentSessionStatus, PaymentsModule, type PaymentsModuleConfig, type PaymentsModuleDependencies, type PeerInfo, type PricePlatform, type PriceProvider, type PriceProviderConfig, type ProviderMetadata, type ProviderStatus, type RegistryNetwork, STORAGE_KEYS, STORAGE_PREFIX, type SaveResult, type ScanAddressProgress, type ScanAddressesOptions, type ScanAddressesResult, type ScannedAddressResult, type SpentTokenInfo, type SpentTokenResult, Sphere, type SphereConfig, type SphereCreateOptions, SphereError, type SphereErrorCode, type SphereEventHandler, type SphereEventMap, type SphereEventType, type SphereInitOptions, type SphereInitResult, type SphereLoadOptions, type SplitPaymentSession, type SplitRecoveryResult, type StorageEvent, type StorageEventCallback, type StorageEventType, type StorageProvider, type StorageProviderConfig, type SubmitResult, type SyncResult, TEST_AGGREGATOR_URL, TEST_ELECTRUM_URL, TEST_NOSTR_RELAYS, TIMEOUTS, type Token, type TokenDefinition, type TokenIcon, type TokenPrice, TokenRegistry, type TokenState, type TokenStatus, type TokenStorageProvider, type TokenTransferHandler, type TokenTransferPayload, type ValidationResult as TokenValidationResult, TokenValidator, type TombstoneEntry, type TrackedAddress, type TrackedAddressEntry, type TransactionHistoryEntry, type TransferCommitment, type TransferRequest, type TransferResult, type TransferStatus, type TransportEvent, type TransportEventCallback, type TransportEventType, type TransportProvider, type TransportProviderConfig, type TrustBaseLoader, type TxfAuthenticator, type TxfGenesis, type TxfGenesisData, type TxfInclusionProof, type TxfIntegrity, type TxfInvalidEntry, type TxfMerkleStep, type TxfMerkleTreePath, type TxfMeta, type TxfOutboxEntry, type TxfSentEntry, type TxfState, type TxfStorageData, type TxfStorageDataBase, type TxfToken, type TxfTombstone, type TxfTransaction, type ValidationAction, type ValidationIssue, type ValidationResult$1 as ValidationResult, type WaitOptions, type WalletDatInfo, type WalletInfo, type WalletJSON$1 as WalletJSON, type WalletJSONExportOptions$1 as WalletJSONExportOptions, type WalletSource, archivedKeyFromTokenId, base58Decode, base58Encode, buildTxfStorageData, bytesToHex, countCommittedTransactions, createAddress, createCommunicationsModule, createKeyPair, createL1PaymentsModule, createPaymentSession, createPaymentSessionError, createPaymentsModule, createPriceProvider, createSphere, createSplitPaymentSession, createTokenValidator, decodeBech32, decryptCMasterKey, decryptPrivateKey, decryptTextFormatKey, deriveAddressInfo, deriveChildKey$1 as deriveChildKey, deriveKeyAtPath$1 as deriveKeyAtPath, doubleSha256, encodeBech32, extractFromText, findPattern, forkedKeyFromTokenIdAndState, formatAmount, generateMasterKey, generateMnemonic, getAddressHrp, getCoinIdByName, getCoinIdBySymbol, getCurrentStateHash, getPublicKey, getSphere, getTokenDecimals, getTokenDefinition, getTokenIconUrl, getTokenId, getTokenName, getTokenSymbol, hasMissingNewStateHash, hasUncommittedTransactions, hasValidTxfData, hash160, hexToBytes, identityFromMnemonicSync, initSphere, isArchivedKey, isForkedKey, isInstantSplitBundle, isInstantSplitBundleV4, isInstantSplitBundleV5, isKnownToken, isPaymentSessionTerminal, isPaymentSessionTimedOut, isSQLiteDatabase, isTextWalletEncrypted, isTokenKey, isValidBech32, isValidPrivateKey, isValidTokenId, isWalletDatEncrypted, isWalletTextFormat, keyFromTokenId, loadSphere, mnemonicToSeedSync, normalizeSdkTokenToStorage, objectToTxf, parseAndDecryptWalletDat, parseAndDecryptWalletText, parseForkedKey, parseTxfStorageData, parseWalletDat, parseWalletText, randomBytes, randomHex, randomUUID, ripemd160, sha256, sleep, sphereExists, toHumanReadable, toSmallestUnit, tokenIdFromArchivedKey, tokenIdFromKey, tokenToTxf, txfToToken, validateMnemonic };
+export { type AddressInfo, type AddressMode, type AggregatorClient, type AggregatorEvent, type AggregatorEventCallback, type AggregatorEventType, type AggregatorProvider, type AggregatorProviderConfig, type Asset, type BackgroundProgressStatus, type BaseProvider, type BroadcastHandler, type BroadcastMessage, type CMasterKeyData, COIN_TYPES, CoinGeckoPriceProvider, CommunicationsModule, type CommunicationsModuleConfig, type CommunicationsModuleDependencies, DEFAULT_AGGREGATOR_TIMEOUT, DEFAULT_AGGREGATOR_URL, DEFAULT_DERIVATION_PATH, DEFAULT_ELECTRUM_URL, DEFAULT_IPFS_BOOTSTRAP_PEERS, DEFAULT_IPFS_GATEWAYS, DEFAULT_NOSTR_RELAYS, DEV_AGGREGATOR_URL, type DecryptionProgressCallback, type DerivationMode, type DirectMessage, type ExtendedValidationResult, type FullIdentity, type Identity, type IdentityConfig, type InclusionProof, type IncomingBroadcast, type IncomingMessage, type IncomingPaymentRequest$1 as IncomingPaymentRequest, type IncomingTokenTransfer, type IncomingTransfer, type InstantSplitBundle, type InstantSplitBundleV4, type InstantSplitBundleV5, type InstantSplitOptions, type InstantSplitProcessResult, type InstantSplitResult, type InstantSplitV5RecoveryMetadata, type InvalidatedNametagEntry, index as L1, type L1Balance, L1PaymentsModule, type L1PaymentsModuleConfig, type L1PaymentsModuleDependencies, type L1SendRequest, type L1SendResult, type L1Transaction, type L1Utxo, LIMITS, type LegacyFileImportOptions, type LegacyFileInfo, type LegacyFileParseResult, type LegacyFileParsedData, type LegacyFileType, type LoadResult, type LoggingConfig, type MessageHandler, type MintOutboxEntry, type MintParams, type MintResult, NETWORKS, NOSTR_EVENT_KINDS, type NametagData, type NetworkType, type OracleEvent, type OracleEventCallback, type OracleEventType, type OracleProvider, type OutboxEntry, type OutgoingPaymentRequest, type ParsedStorageData, type PaymentRequest, type PaymentRequestHandler$1 as PaymentRequestHandler, type PaymentRequestResponse, type PaymentRequestResponseHandler$1 as PaymentRequestResponseHandler, type PaymentRequestResponseType$1 as PaymentRequestResponseType, type PaymentRequestResult, type PaymentRequestStatus, type PaymentSession, type PaymentSessionDirection, type PaymentSessionError, type PaymentSessionErrorCode, type PaymentSessionStatus, PaymentsModule, type PaymentsModuleConfig, type PaymentsModuleDependencies, type PeerInfo, type PendingV5Finalization, type PricePlatform, type PriceProvider, type PriceProviderConfig, type ProviderMetadata, type ProviderStatus, type ReceiveOptions, type ReceiveResult, type RegistryNetwork, STORAGE_KEYS, STORAGE_PREFIX, type SaveResult, type ScanAddressProgress, type ScanAddressesOptions, type ScanAddressesResult, type ScannedAddressResult, type SpentTokenInfo, type SpentTokenResult, Sphere, type SphereConfig, type SphereCreateOptions, SphereError, type SphereErrorCode, type SphereEventHandler, type SphereEventMap, type SphereEventType, type SphereInitOptions, type SphereInitResult, type SphereLoadOptions, type SplitPaymentSession, type SplitRecoveryResult, type StorageEvent, type StorageEventCallback, type StorageEventType, type StorageProvider, type StorageProviderConfig, type SubmitResult, type SyncResult, TEST_AGGREGATOR_URL, TEST_ELECTRUM_URL, TEST_NOSTR_RELAYS, TIMEOUTS, type Token, type TokenDefinition, type TokenIcon, type TokenPrice, TokenRegistry, type TokenState, type TokenStatus, type TokenStorageProvider, type TokenTransferDetail, type TokenTransferHandler, type TokenTransferPayload, type ValidationResult as TokenValidationResult, TokenValidator, type TombstoneEntry, type TrackedAddress, type TrackedAddressEntry, type TransactionHistoryEntry, type TransferCommitment, type TransferMode, type TransferRequest, type TransferResult, type TransferStatus, type TransportEvent, type TransportEventCallback, type TransportEventType, type TransportProvider, type TransportProviderConfig, type TrustBaseLoader, type TxfAuthenticator, type TxfGenesis, type TxfGenesisData, type TxfInclusionProof, type TxfIntegrity, type TxfInvalidEntry, type TxfMerkleStep, type TxfMerkleTreePath, type TxfMeta, type TxfOutboxEntry, type TxfSentEntry, type TxfState, type TxfStorageData, type TxfStorageDataBase, type TxfToken, type TxfTombstone, type TxfTransaction, type UnconfirmedResolutionResult, type V5FinalizationStage, type ValidationAction, type ValidationIssue, type ValidationResult$1 as ValidationResult, type WaitOptions, type WalletDatInfo, type WalletInfo, type WalletJSON$1 as WalletJSON, type WalletJSONExportOptions$1 as WalletJSONExportOptions, type WalletSource, archivedKeyFromTokenId, base58Decode, base58Encode, buildTxfStorageData, bytesToHex, countCommittedTransactions, createAddress, createCommunicationsModule, createKeyPair, createL1PaymentsModule, createPaymentSession, createPaymentSessionError, createPaymentsModule, createPriceProvider, createSphere, createSplitPaymentSession, createTokenValidator, decodeBech32, decryptCMasterKey, decryptPrivateKey, decryptTextFormatKey, deriveAddressInfo, deriveChildKey$1 as deriveChildKey, deriveKeyAtPath$1 as deriveKeyAtPath, doubleSha256, encodeBech32, extractFromText, findPattern, forkedKeyFromTokenIdAndState, formatAmount, generateMasterKey, generateMnemonic, getAddressHrp, getCoinIdByName, getCoinIdBySymbol, getCurrentStateHash, getPublicKey, getSphere, getTokenDecimals, getTokenDefinition, getTokenIconUrl, getTokenId, getTokenName, getTokenSymbol, hasMissingNewStateHash, hasUncommittedTransactions, hasValidTxfData, hash160, hexToBytes, identityFromMnemonicSync, initSphere, isArchivedKey, isForkedKey, isInstantSplitBundle, isInstantSplitBundleV4, isInstantSplitBundleV5, isKnownToken, isPaymentSessionTerminal, isPaymentSessionTimedOut, isSQLiteDatabase, isTextWalletEncrypted, isTokenKey, isValidBech32, isValidNametag, isValidPrivateKey, isValidTokenId, isWalletDatEncrypted, isWalletTextFormat, keyFromTokenId, loadSphere, mnemonicToSeedSync, normalizeSdkTokenToStorage, objectToTxf, parseAndDecryptWalletDat, parseAndDecryptWalletText, parseForkedKey, parseTxfStorageData, parseWalletDat, parseWalletText, randomBytes, randomHex, randomUUID, ripemd160, sha256, sleep, sphereExists, toHumanReadable, toSmallestUnit, tokenIdFromArchivedKey, tokenIdFromKey, tokenToTxf, txfToToken, validateMnemonic };