@unicitylabs/sphere-sdk 0.2.3 → 0.3.0

package/dist/index.d.ts

@@ -1,5 +1,73 @@
 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';
+
+/**
+ * Group Chat Types (NIP-29)
+ * Plain interfaces for SDK consumers — no classes, no UI helpers.
+ */
+declare const GroupRole: {
+    readonly ADMIN: "ADMIN";
+    readonly MODERATOR: "MODERATOR";
+    readonly MEMBER: "MEMBER";
+};
+type GroupRole = (typeof GroupRole)[keyof typeof GroupRole];
+declare const GroupVisibility: {
+    readonly PUBLIC: "PUBLIC";
+    readonly PRIVATE: "PRIVATE";
+};
+type GroupVisibility = (typeof GroupVisibility)[keyof typeof GroupVisibility];
+interface GroupData {
+    id: string;
+    relayUrl: string;
+    name: string;
+    description?: string;
+    picture?: string;
+    visibility: GroupVisibility;
+    createdAt: number;
+    updatedAt?: number;
+    memberCount?: number;
+    unreadCount?: number;
+    lastMessageTime?: number;
+    lastMessageText?: string;
+    /** When the current user joined this group locally (used to filter old events) */
+    localJoinedAt?: number;
+}
+interface GroupMessageData {
+    id?: string;
+    groupId: string;
+    content: string;
+    timestamp: number;
+    senderPubkey: string;
+    senderNametag?: string;
+    replyToId?: string;
+    previousIds?: string[];
+}
+interface GroupMemberData {
+    pubkey: string;
+    groupId: string;
+    role: GroupRole;
+    nametag?: string;
+    joinedAt: number;
+}
+interface GroupChatModuleConfig {
+    /** Override relay URLs (default: from network config) */
+    relays?: string[];
+    /** Default message fetch limit (default: 50) */
+    defaultMessageLimit?: number;
+    /** Max previous message IDs in ordering tags (default: 3) */
+    maxPreviousTags?: number;
+    /** Reconnect delay in ms (default: 3000) */
+    reconnectDelayMs?: number;
+    /** Max reconnect attempts (default: 5) */
+    maxReconnectAttempts?: number;
+}
+interface CreateGroupOptions {
+    name: string;
+    description?: string;
+    picture?: string;
+    visibility?: GroupVisibility;
+}
 
 /**
  * Cryptographic utilities for SDK2
@@ -310,11 +378,12 @@ interface TxfMeta$1 {
 interface TxfStorageData {
     _meta: TxfMeta$1;
     _nametag?: NametagData;
+    _nametags?: NametagData[];
     _tombstones?: TombstoneEntry[];
     _invalidatedNametags?: InvalidatedNametagEntry[];
     _outbox?: OutboxEntry[];
     _mintOutbox?: MintOutboxEntry[];
-    [key: string]: TxfToken | TxfMeta$1 | NametagData | TombstoneEntry[] | InvalidatedNametagEntry[] | OutboxEntry[] | MintOutboxEntry[] | undefined;
+    [key: string]: TxfToken | TxfMeta$1 | NametagData | NametagData[] | TombstoneEntry[] | InvalidatedNametagEntry[] | OutboxEntry[] | MintOutboxEntry[] | undefined;
 }
 interface ValidationIssue {
     tokenId: string;
@@ -539,6 +608,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 +685,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 +932,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 +953,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 +961,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 +1162,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' | 'groupchat:message' | 'groupchat:joined' | 'groupchat:left' | 'groupchat:kicked' | 'groupchat:group_deleted' | 'groupchat:updated' | 'groupchat:connection';
 interface SphereEventMap {
     'transfer:incoming': IncomingTransfer;
     'transfer:confirmed': TransferResult;
@@ -1098,6 +1221,34 @@ interface SphereEventMap {
         index: number;
         addressId: string;
     };
+    'sync:remote-update': {
+        providerId: string;
+        name: string;
+        sequence: number;
+        cid: string;
+        added: number;
+        removed: number;
+    };
+    'groupchat:message': GroupMessageData;
+    'groupchat:joined': {
+        groupId: string;
+        groupName: string;
+    };
+    'groupchat:left': {
+        groupId: string;
+    };
+    'groupchat:kicked': {
+        groupId: string;
+        groupName: string;
+    };
+    'groupchat:group_deleted': {
+        groupId: string;
+        groupName: string;
+    };
+    'groupchat:updated': Record<string, never>;
+    'groupchat:connection': {
+        connected: boolean;
+    };
 }
 type SphereEventHandler<T extends SphereEventType> = (data: SphereEventMap[T]) => void;
 interface SphereConfig {
@@ -1362,6 +1513,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 +1583,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;
@@ -1784,24 +1941,8 @@ interface TokenStorageProvider<TData = unknown> extends BaseProvider {
      * Subscribe to storage events
      */
     onEvent?(callback: StorageEventCallback): () => void;
-    /**
-     * Save individual token (for file-based storage like lottery pattern)
-     */
-    saveToken?(tokenId: string, tokenData: unknown): Promise<void>;
-    /**
-     * Get individual token
-     */
-    getToken?(tokenId: string): Promise<unknown | null>;
-    /**
-     * List all token IDs
-     */
-    listTokenIds?(): Promise<string[]>;
-    /**
-     * Delete individual token
-     */
-    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 +2283,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,11 +2346,12 @@ declare class PaymentsModule {
     readonly l1: L1PaymentsModule | null;
     private tokens;
     private pendingTransfers;
+    private pendingBackgroundTasks;
     private tombstones;
     private archivedTokens;
     private forkedTokens;
     private transactionHistory;
-    private nametag;
+    private nametags;
     private paymentRequests;
     private paymentRequestHandlers;
     private outgoingPaymentRequests;
@@ -2199,8 +2364,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 +2384,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 +2447,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
@@ -2292,27 +2481,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 +2550,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,147 +2572,312 @@ 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.
      */
-    getBalance(): Promise<number | null>;
+    waitForPendingOperations(): Promise<void>;
     /**
-     * Get aggregated assets (tokens grouped by coinId) with price data
-     * Only includes confirmed tokens
+     * 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(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.
      */
-    addToken(token: Token, skipHistory?: boolean): Promise<boolean>;
+    resolveUnconfirmed(): Promise<UnconfirmedResolutionResult>;
     /**
-     * Save token as individual file to token storage providers
-     * Similar to lottery's saveReceivedToken() pattern
+     * Process a single V5 token through its finalization stages with quick-timeout proof checks.
      */
-    private saveTokenToFileStorage;
+    private resolveV5Token;
     /**
-     * Load tokens from file storage providers (lottery compatibility)
-     * This loads tokens from file-based storage that may have been saved
-     * by other applications using the same storage directory.
+     * Non-blocking proof check with 500ms timeout.
      */
-    private loadTokensFromFileStorage;
+    private quickProofCheck;
     /**
-     * Update an existing token
+     * Perform V5 bundle finalization from stored bundle data and proofs.
+     * Extracted from InstantSplitProcessor.processV5Bundle() steps 4-10.
      */
-    updateToken(token: Token): Promise<void>;
+    private finalizeFromV5Bundle;
     /**
-     * Remove a token by ID
+     * Parse pending finalization metadata from token's sdkData.
      */
-    removeToken(tokenId: string, recipientNametag?: string, skipHistory?: boolean): Promise<void>;
+    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>;
     /**
-     * Delete physical token file(s) from all storage providers.
-     * Finds files by matching the SDK token ID prefix in the filename.
+     * 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 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`).
      */
-    private deleteTokenFiles;
+    removeToken(tokenId: string, recipientNametag?: string, skipHistory?: boolean): Promise<void>;
     /**
-     * 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 (first) nametag data.
+     *
+     * @returns The nametag data, or `null` if no nametag is set.
      */
     getNametag(): NametagData | null;
     /**
-     * Check if has nametag
-     */
-    hasNametag(): boolean;
-    /**
-     * Clear nametag
+     * Get all nametag data entries.
+     *
+     * @returns A copy of the nametags array.
      */
-    clearNametag(): Promise<void>;
+    getNametags(): NametagData[];
     /**
-     * Save nametag to file storage for lottery compatibility
-     * Creates file: nametag-{name}.json
+     * Check whether a nametag is currently set.
+     *
+     * @returns `true` if nametag data is present.
      */
-    private saveNametagToFileStorage;
+    hasNametag(): boolean;
     /**
-     * Load nametag from file storage (lottery compatibility)
-     * Looks for file: nametag-{name}.json
+     * Remove all nametag data from memory and storage.
      */
-    private loadNametagFromFileStorage;
+    clearNametag(): Promise<void>;
     /**
      * Mint a nametag token on-chain (like Sphere wallet and lottery)
      * This creates the nametag token required for receiving tokens via PROXY addresses
@@ -2514,30 +2892,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[];
     /**
@@ -2704,6 +3112,127 @@ declare class CommunicationsModule {
 }
 declare function createCommunicationsModule(config?: CommunicationsModuleConfig): CommunicationsModule;
 
+/**
+ * Group Chat Module (NIP-29)
+ *
+ * Relay-based group chat using NIP-29 protocol on a dedicated Nostr relay.
+ * Embeds its own NostrClient — does NOT share the wallet's TransportProvider.
+ */
+
+interface GroupChatModuleDependencies {
+    identity: FullIdentity;
+    storage: StorageProvider;
+    emitEvent: <T extends SphereEventType>(type: T, data: SphereEventMap[T]) => void;
+}
+declare class GroupChatModule {
+    private config;
+    private deps;
+    private client;
+    private keyManager;
+    private connected;
+    private connecting;
+    private connectPromise;
+    private reconnectAttempts;
+    private reconnectTimer;
+    private subscriptionIds;
+    private groups;
+    private messages;
+    private members;
+    private processedEventIds;
+    private pendingLeaves;
+    private persistTimer;
+    private persistPromise;
+    private relayAdminPubkeys;
+    private relayAdminFetchPromise;
+    private messageHandlers;
+    constructor(config?: GroupChatModuleConfig);
+    initialize(deps: GroupChatModuleDependencies): void;
+    load(): Promise<void>;
+    destroy(): void;
+    private destroyConnection;
+    connect(): Promise<void>;
+    getConnectionStatus(): boolean;
+    private doConnect;
+    private scheduleReconnect;
+    private subscribeToJoinedGroups;
+    private subscribeToGroup;
+    private handleGroupEvent;
+    private handleMetadataEvent;
+    private handleModerationEvent;
+    private updateMembersFromEvent;
+    private updateAdminsFromEvent;
+    private restoreJoinedGroups;
+    fetchAvailableGroups(): Promise<GroupData[]>;
+    joinGroup(groupId: string, inviteCode?: string): Promise<boolean>;
+    leaveGroup(groupId: string): Promise<boolean>;
+    createGroup(options: CreateGroupOptions): Promise<GroupData | null>;
+    deleteGroup(groupId: string): Promise<boolean>;
+    createInvite(groupId: string): Promise<string | null>;
+    sendMessage(groupId: string, content: string, replyToId?: string): Promise<GroupMessageData | null>;
+    fetchMessages(groupId: string, since?: number, limit?: number): Promise<GroupMessageData[]>;
+    getGroups(): GroupData[];
+    getGroup(groupId: string): GroupData | null;
+    getMessages(groupId: string): GroupMessageData[];
+    getMembers(groupId: string): GroupMemberData[];
+    getMember(groupId: string, pubkey: string): GroupMemberData | null;
+    getTotalUnreadCount(): number;
+    markGroupAsRead(groupId: string): void;
+    kickUser(groupId: string, userPubkey: string, reason?: string): Promise<boolean>;
+    deleteMessage(groupId: string, messageId: string): Promise<boolean>;
+    isCurrentUserAdmin(groupId: string): boolean;
+    isCurrentUserModerator(groupId: string): boolean;
+    /**
+     * Check if current user can moderate a group:
+     * - Group admin/moderator can always moderate their group
+     * - Relay admins can moderate public groups
+     */
+    canModerateGroup(groupId: string): Promise<boolean>;
+    isCurrentUserRelayAdmin(): Promise<boolean>;
+    getCurrentUserRole(groupId: string): GroupRole | null;
+    onMessage(handler: (message: GroupMessageData) => void): () => void;
+    getRelayUrls(): string[];
+    getMyPublicKey(): string | null;
+    private fetchRelayAdmins;
+    private doFetchRelayAdmins;
+    private fetchGroupMetadataInternal;
+    private fetchAndSaveMembers;
+    private fetchGroupMembersInternal;
+    private fetchGroupAdminsInternal;
+    private saveMessageToMemory;
+    private deleteMessageFromMemory;
+    private saveMemberToMemory;
+    private removeMemberFromMemory;
+    private removeGroupFromMemory;
+    private updateGroupLastMessage;
+    private updateMemberNametag;
+    private addProcessedEventId;
+    /** Schedule a debounced persist (coalesces rapid event bursts). */
+    private schedulePersist;
+    /** Persist immediately (for explicit flush points). */
+    private persistAll;
+    private doPersistAll;
+    private persistGroups;
+    private persistMessages;
+    private persistMembers;
+    private persistProcessedEvents;
+    private checkAndClearOnRelayChange;
+    private wrapMessageContent;
+    private unwrapMessageContent;
+    private getGroupIdFromEvent;
+    private getGroupIdFromMetadataEvent;
+    private extractReplyTo;
+    private extractPreviousIds;
+    private parseGroupMetadata;
+    /** Subscribe and track the subscription ID for cleanup. */
+    private trackSubscription;
+    /** Subscribe for a one-shot fetch, auto-unsubscribe on EOSE or timeout. */
+    private oneshotSubscription;
+    private ensureInitialized;
+    private ensureConnected;
+    private randomId;
+}
+declare function createGroupChatModule(config?: GroupChatModuleConfig): GroupChatModule;
+
 /**
  * SDK2 Constants
  * Default configuration values and storage keys
@@ -2722,6 +3251,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 */
@@ -2746,6 +3277,16 @@ declare const STORAGE_KEYS: {
     readonly TRACKED_ADDRESSES: "tracked_addresses";
     /** Last processed Nostr wallet event timestamp (unix seconds), keyed per pubkey */
     readonly LAST_WALLET_EVENT_TS: "last_wallet_event_ts";
+    /** Group chat: joined groups */
+    readonly GROUP_CHAT_GROUPS: "group_chat_groups";
+    /** Group chat: messages */
+    readonly GROUP_CHAT_MESSAGES: "group_chat_messages";
+    /** Group chat: members */
+    readonly GROUP_CHAT_MEMBERS: "group_chat_members";
+    /** Group chat: processed event IDs for deduplication */
+    readonly GROUP_CHAT_PROCESSED_EVENTS: "group_chat_processed_events";
+    /** Group chat: last used relay URL (stale data detection) */
+    readonly GROUP_CHAT_RELAY_URL: "group_chat_relay_url";
 };
 /** Default Nostr relays */
 declare const DEFAULT_NOSTR_RELAYS: readonly ["wss://relay.unicity.network", "wss://relay.damus.io", "wss://nos.lol", "wss://relay.nostr.band"];
@@ -2764,6 +3305,44 @@ declare const NOSTR_EVENT_KINDS: {
     /** Public broadcast */
     readonly BROADCAST: 1;
 };
+/**
+ * NIP-29 Event Kinds for relay-based group chat
+ * https://github.com/nostr-protocol/nips/blob/master/29.md
+ */
+declare const NIP29_KINDS: {
+    /** Chat message sent to group */
+    readonly CHAT_MESSAGE: 9;
+    /** Thread root message */
+    readonly THREAD_ROOT: 11;
+    /** Thread reply message */
+    readonly THREAD_REPLY: 12;
+    /** User join request */
+    readonly JOIN_REQUEST: 9021;
+    /** User leave request */
+    readonly LEAVE_REQUEST: 9022;
+    /** Admin: add/update user */
+    readonly PUT_USER: 9000;
+    /** Admin: remove user */
+    readonly REMOVE_USER: 9001;
+    /** Admin: edit group metadata */
+    readonly EDIT_METADATA: 9002;
+    /** Admin: delete event */
+    readonly DELETE_EVENT: 9005;
+    /** Admin: create group */
+    readonly CREATE_GROUP: 9007;
+    /** Admin: delete group */
+    readonly DELETE_GROUP: 9008;
+    /** Admin: create invite code */
+    readonly CREATE_INVITE: 9009;
+    /** Relay-signed group metadata */
+    readonly GROUP_METADATA: 39000;
+    /** Relay-signed group admins */
+    readonly GROUP_ADMINS: 39001;
+    /** Relay-signed group members */
+    readonly GROUP_MEMBERS: 39002;
+    /** Relay-signed group roles */
+    readonly GROUP_ROLES: 39003;
+};
 /**
  * Default aggregator URL
  * Note: The aggregator is conceptually an oracle - a trusted service that provides
@@ -2795,6 +3374,8 @@ declare const DEFAULT_ELECTRUM_URL: "wss://fulcrum.alpha.unicity.network:50004";
 declare const TEST_ELECTRUM_URL: "wss://fulcrum.alpha.testnet.unicity.network:50004";
 /** Testnet Nostr relays */
 declare const TEST_NOSTR_RELAYS: readonly ["wss://nostr-relay.testnet.unicity.network"];
+/** Default group chat relays (NIP-29 Zooid relay) */
+declare const DEFAULT_GROUP_RELAYS: readonly ["wss://sphere-relay.unicity.network"];
 /** Network configurations */
 declare const NETWORKS: {
     readonly mainnet: {
@@ -2803,6 +3384,7 @@ declare const NETWORKS: {
         readonly nostrRelays: readonly ["wss://relay.unicity.network", "wss://relay.damus.io", "wss://nos.lol", "wss://relay.nostr.band"];
         readonly ipfsGateways: readonly ["https://ipfs.unicity.network", "https://dweb.link", "https://ipfs.io"];
         readonly electrumUrl: "wss://fulcrum.alpha.unicity.network:50004";
+        readonly groupRelays: readonly ["wss://sphere-relay.unicity.network"];
     };
     readonly testnet: {
         readonly name: "Testnet";
@@ -2810,6 +3392,7 @@ declare const NETWORKS: {
         readonly nostrRelays: readonly ["wss://nostr-relay.testnet.unicity.network"];
         readonly ipfsGateways: readonly ["https://ipfs.unicity.network", "https://dweb.link", "https://ipfs.io"];
         readonly electrumUrl: "wss://fulcrum.alpha.testnet.unicity.network:50004";
+        readonly groupRelays: readonly ["wss://sphere-relay.unicity.network"];
     };
     readonly dev: {
         readonly name: "Development";
@@ -2817,6 +3400,7 @@ declare const NETWORKS: {
         readonly nostrRelays: readonly ["wss://nostr-relay.testnet.unicity.network"];
         readonly ipfsGateways: readonly ["https://ipfs.unicity.network", "https://dweb.link", "https://ipfs.io"];
         readonly electrumUrl: "wss://fulcrum.alpha.testnet.unicity.network:50004";
+        readonly groupRelays: readonly ["wss://sphere-relay.unicity.network"];
     };
 };
 type NetworkType = keyof typeof NETWORKS;
@@ -2966,6 +3550,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) */
@@ -2992,6 +3578,8 @@ interface SphereCreateOptions {
      * Use createBrowserProviders({ network: 'testnet' }) to set up testnet providers.
      */
     network?: NetworkType;
+    /** Group chat configuration (NIP-29). Omit to disable groupchat. */
+    groupChat?: GroupChatModuleConfig | boolean;
 }
 /** Options for loading existing wallet */
 interface SphereLoadOptions {
@@ -3013,6 +3601,8 @@ interface SphereLoadOptions {
      * Use createBrowserProviders({ network: 'testnet' }) to set up testnet providers.
      */
     network?: NetworkType;
+    /** Group chat configuration (NIP-29). Omit to disable groupchat. */
+    groupChat?: GroupChatModuleConfig | boolean;
 }
 /** Options for importing a wallet */
 interface SphereImportOptions {
@@ -3042,6 +3632,8 @@ interface SphereImportOptions {
     l1?: L1Config;
     /** Optional price provider for fiat conversion */
     price?: PriceProvider;
+    /** Group chat configuration (NIP-29). Omit to disable groupchat. */
+    groupChat?: GroupChatModuleConfig | boolean;
 }
 /** L1 (ALPHA blockchain) configuration */
 interface L1Config {
@@ -3080,6 +3672,13 @@ interface SphereInitOptions {
      * Use createBrowserProviders({ network: 'testnet' }) to set up testnet providers.
      */
     network?: NetworkType;
+    /**
+     * Group chat configuration (NIP-29).
+     * - `true`: Enable with network-default relays
+     * - `GroupChatModuleConfig`: Enable with custom config
+     * - Omit/undefined: No groupchat module
+     */
+    groupChat?: GroupChatModuleConfig | boolean;
 }
 /** Result of init operation */
 interface SphereInitResult {
@@ -3115,6 +3714,7 @@ declare class Sphere {
     private _priceProvider;
     private _payments;
     private _communications;
+    private _groupChat;
     private eventHandlers;
     private constructor();
     /**
@@ -3147,6 +3747,18 @@ declare class Sphere {
      * ```
      */
     static init(options: SphereInitOptions): Promise<SphereInitResult>;
+    /**
+     * Resolve groupChat config from init/create/load options.
+     * - `true` → use network-default relays
+     * - `GroupChatModuleConfig` → pass through
+     * - `undefined` → no groupchat
+     */
+    /**
+     * Resolve GroupChat config from Sphere.init() options.
+     * Note: impl/shared/resolvers.ts has a similar resolver for provider-level config
+     * (different input shape: { enabled?, relays? }). Both fill relay URLs from network defaults.
+     */
+    private static resolveGroupChatConfig;
     /**
      * Create new wallet with mnemonic
      */
@@ -3203,6 +3815,8 @@ declare class Sphere {
     get payments(): PaymentsModule;
     /** Communications module */
     get communications(): CommunicationsModule;
+    /** Group chat module (NIP-29). Null if not configured. */
+    get groupChat(): GroupChatModule | null;
     /** Current identity (public info only) */
     get identity(): Identity | null;
     /** Is ready */
@@ -3696,9 +4310,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;
@@ -3990,7 +4604,7 @@ declare function txfToToken(tokenId: string, txf: TxfToken): Token;
  * Build TXF storage data from tokens and metadata
  */
 declare function buildTxfStorageData(tokens: Token[], meta: Omit<TxfMeta$1, 'formatVersion'>, options?: {
-    nametag?: NametagData;
+    nametags?: NametagData[];
     tombstones?: TombstoneEntry[];
     archivedTokens?: Map<string, TxfToken>;
     forkedTokens?: Map<string, TxfToken>;
@@ -4001,7 +4615,7 @@ declare function buildTxfStorageData(tokens: Token[], meta: Omit<TxfMeta$1, 'for
 interface ParsedStorageData {
     tokens: Token[];
     meta: TxfMeta$1 | null;
-    nametag: NametagData | null;
+    nametags: NametagData[];
     tombstones: TombstoneEntry[];
     archivedTokens: Map<string, TxfToken>;
     forkedTokens: Map<string, TxfToken>;
@@ -5047,4 +5661,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, type CreateGroupOptions, DEFAULT_AGGREGATOR_TIMEOUT, DEFAULT_AGGREGATOR_URL, DEFAULT_DERIVATION_PATH, DEFAULT_ELECTRUM_URL, DEFAULT_GROUP_RELAYS, DEFAULT_IPFS_BOOTSTRAP_PEERS, DEFAULT_IPFS_GATEWAYS, DEFAULT_NOSTR_RELAYS, DEV_AGGREGATOR_URL, type DecryptionProgressCallback, type DerivationMode, type DirectMessage, type ExtendedValidationResult, type FullIdentity, GroupChatModule, type GroupChatModuleConfig, type GroupChatModuleDependencies, type GroupData, type GroupMemberData, type GroupMessageData, GroupRole, GroupVisibility, 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, NIP29_KINDS, 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, createGroupChatModule, 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 };