@unicitylabs/sphere-sdk 0.2.3 → 0.3.0

package/dist/core/index.d.ts

@@ -1,6 +1,73 @@
 import { Token as Token$1 } from '@unicitylabs/state-transition-sdk/lib/token/Token';
 import elliptic from 'elliptic';
 
+/**
+ * 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
  *
@@ -272,147 +339,6 @@ interface TombstoneEntry {
     timestamp: number;
 }
 
-/**
- * INSTANT_SPLIT V5 Types
- *
- * Optimized token split transfer types that achieve ~2.3s critical path latency
- * instead of the standard ~42s sequential flow.
- *
- * Key Insight: TransferCommitment.create() only needs token.state, NOT the mint proof.
- * This allows creating transfer commitments immediately after mint data creation,
- * without waiting for mint proofs.
- *
- * V5 Flow (Production Mode):
- * 1. Create burn commitment, submit to aggregator
- * 2. Wait for burn inclusion proof (~2s - unavoidable)
- * 3. Create mint commitments with proper SplitMintReason (requires burn proof)
- * 4. Create transfer commitment from mint data (no mint proof needed)
- * 5. Package bundle -> send via Nostr -> SUCCESS (~2.3s total!)
- * 6. Background: submit mints, wait for proofs, save change token, sync storage
- */
-type SdkToken = any;
-/**
- * Bundle payload for INSTANT_SPLIT V5 (Production Mode)
- *
- * V5 achieves ~2.3s sender latency while working with production aggregators:
- * - Burn proof is required for creating SplitMintReason
- * - Transfer commitment is created from mint data WITHOUT waiting for mint proof
- * - Mints are submitted in background after Nostr delivery
- *
- * Security: Burn is proven on-chain before mints can be created, preventing double-spend.
- */
-interface InstantSplitBundleV5 {
-    /** Bundle version - V5 is production mode (proper SplitMintReason) */
-    version: '5.0';
-    /** Bundle type identifier */
-    type: 'INSTANT_SPLIT';
-    /**
-     * Burn TRANSACTION JSON (WITH inclusion proof!)
-     * V5 sends the proven burn transaction so recipient can verify burn completed.
-     */
-    burnTransaction: string;
-    /**
-     * Recipient's MintTransactionData JSON (contains proper SplitMintReason in V5)
-     * The SplitMintReason references the burn transaction.
-     */
-    recipientMintData: string;
-    /**
-     * Pre-created TransferCommitment JSON (recipient submits and waits for proof)
-     * Created from mint data WITHOUT any proofs.
-     */
-    transferCommitment: string;
-    /** Payment amount (display metadata) */
-    amount: string;
-    /** Coin ID hex */
-    coinId: string;
-    /** Token type hex */
-    tokenTypeHex: string;
-    /** Split group ID for recovery correlation */
-    splitGroupId: string;
-    /** Sender's pubkey for acknowledgment */
-    senderPubkey: string;
-    /** Salt for recipient predicate creation (hex) */
-    recipientSaltHex: string;
-    /** Salt for transfer commitment creation (hex) */
-    transferSaltHex: string;
-    /**
-     * Serialized TokenState JSON for the intermediate minted token.
-     *
-     * In V5, the mint is to sender's address first, then transferred to recipient.
-     * The recipient needs this state to reconstruct the minted token before applying transfer.
-     * Without this, the recipient can't create a matching predicate (they don't have sender's signing key).
-     */
-    mintedTokenStateJson: string;
-    /**
-     * Serialized TokenState JSON for the final recipient state (after transfer).
-     *
-     * The sender creates the transfer commitment targeting the recipient's PROXY address.
-     * The recipient can't recreate this state correctly because their signingService
-     * creates predicates for their DIRECT address, not the PROXY address.
-     * This is optional - recipient can create their own if they have the correct address.
-     */
-    finalRecipientStateJson: string;
-    /**
-     * Serialized recipient address JSON (PROXY or DIRECT).
-     *
-     * Used by the recipient to identify which nametag token is being targeted.
-     * For PROXY address transfers, the recipient needs to find the matching
-     * nametag token and pass it to finalizeTransaction() for verification.
-     */
-    recipientAddressJson: string;
-    /**
-     * Serialized nametag token JSON (for PROXY address transfers).
-     *
-     * For PROXY address transfers, the sender includes the nametag token
-     * so the recipient can verify they're authorized to receive at this address.
-     * This is REQUIRED for PROXY addresses - transfers without this will fail.
-     */
-    nametagTokenJson?: string;
-}
-/**
- * Bundle payload for INSTANT_SPLIT V4 (Dev Mode Only - True Nostr-First Split)
- *
- * V4 achieves near-zero sender latency (~0.3s) by:
- * 1. Creating ALL commitments locally BEFORE any aggregator submission
- * 2. Persisting via Nostr FIRST
- * 3. Then submitting ALL to aggregator in background
- *
- * NOTE: V4 only works in dev mode. Production requires V5 with proper SplitMintReason.
- */
-interface InstantSplitBundleV4 {
-    /** Bundle version - V4 is true Nostr-first (dev mode only) */
-    version: '4.0';
-    /** Bundle type identifier */
-    type: 'INSTANT_SPLIT';
-    /**
-     * Burn commitment JSON (NOT transaction - no proof yet!)
-     * Both sender and recipient submit this to aggregator.
-     */
-    burnCommitment: string;
-    /** Recipient's MintTransactionData JSON (they recreate commitment and submit) */
-    recipientMintData: string;
-    /**
-     * Pre-created TransferCommitment JSON (recipient submits and waits for proof)
-     * Created from mint data WITHOUT any proofs.
-     */
-    transferCommitment: string;
-    /** Payment amount (display metadata) */
-    amount: string;
-    /** Coin ID hex */
-    coinId: string;
-    /** Token type hex */
-    tokenTypeHex: string;
-    /** Split group ID for recovery correlation */
-    splitGroupId: string;
-    /** Sender's pubkey for acknowledgment */
-    senderPubkey: string;
-    /** Salt for recipient predicate creation (hex) */
-    recipientSaltHex: string;
-    /** Salt for transfer commitment creation (hex) */
-    transferSaltHex: string;
-}
-/** Union type for all InstantSplit bundle versions */
-type InstantSplitBundle = InstantSplitBundleV4 | InstantSplitBundleV5;
 /**
  * Result of an instant split send operation
  */
@@ -429,19 +355,8 @@ interface InstantSplitResult {
     error?: string;
     /** Whether background processing was started */
     backgroundStarted?: boolean;
-}
-/**
- * Result from processing an INSTANT_SPLIT bundle (recipient side)
- */
-interface InstantSplitProcessResult {
-    /** Whether processing succeeded */
-    success: boolean;
-    /** The finalized SDK token (if successful) */
-    token?: SdkToken;
-    /** Error message (if failed) */
-    error?: string;
-    /** Processing duration in ms */
-    durationMs: number;
+    /** Promise that resolves when background processing completes (change token saved) */
+    backgroundPromise?: Promise<void>;
 }
 /**
  * Options for instant split send operation
@@ -476,6 +391,17 @@ interface BackgroundProgressStatus {
     message: string;
     error?: string;
 }
+/** Result of resolveUnconfirmed() */
+interface UnconfirmedResolutionResult {
+    resolved: number;
+    stillPending: number;
+    failed: number;
+    details: Array<{
+        tokenId: string;
+        stage: string;
+        status: 'resolved' | 'pending' | 'failed';
+    }>;
+}
 
 /**
  * SDK2 Core Types
@@ -529,6 +455,14 @@ interface Asset {
     readonly iconUrl?: string;
     readonly totalAmount: string;
     readonly tokenCount: number;
+    /** Sum of confirmed token amounts (smallest units) */
+    readonly confirmedAmount: string;
+    /** Sum of unconfirmed (submitted/pending) token amounts (smallest units) */
+    readonly unconfirmedAmount: string;
+    /** Number of confirmed tokens aggregated */
+    readonly confirmedTokenCount: number;
+    /** Number of unconfirmed tokens aggregated */
+    readonly unconfirmedTokenCount: number;
     /** Price per whole unit in USD (null if PriceProvider not configured) */
     readonly priceUsd: number | null;
     /** Price per whole unit in EUR (null if PriceProvider not configured) */
@@ -542,6 +476,7 @@ interface Asset {
 }
 type TransferStatus = 'pending' | 'submitted' | 'confirmed' | 'delivered' | 'completed' | 'failed';
 type AddressMode = 'auto' | 'direct' | 'proxy';
+type TransferMode = 'instant' | 'conservative';
 interface TransferRequest {
     readonly coinId: string;
     readonly amount: string;
@@ -549,12 +484,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 {
@@ -731,7 +685,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;
@@ -790,6 +744,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;
 /**
@@ -1012,6 +994,12 @@ interface TransportProvider extends BaseProvider {
      * @returns Unsubscribe function
      */
     onInstantSplitReceived?(handler: InstantSplitBundleHandler): () => void;
+    /**
+     * Fetch pending events from transport (one-shot query).
+     * Creates a temporary subscription, processes events through normal handlers,
+     * and resolves after EOSE (End Of Stored Events).
+     */
+    fetchPendingEvents?(): Promise<void>;
 }
 /**
  * Payload for sending instant split bundles
@@ -1076,7 +1064,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;
@@ -1425,24 +1413,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;
@@ -1698,7 +1670,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 */
@@ -1738,11 +1733,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;
@@ -1755,8 +1751,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;
@@ -1766,11 +1771,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;
     /**
@@ -1822,11 +1834,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
@@ -1848,27 +1868,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;
     /**
@@ -1899,15 +1937,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;
@@ -1915,147 +1959,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.
+     */
+    resolveUnconfirmed(): Promise<UnconfirmedResolutionResult>;
+    /**
+     * Process a single V5 token through its finalization stages with quick-timeout proof checks.
      */
-    addToken(token: Token, skipHistory?: boolean): Promise<boolean>;
+    private resolveV5Token;
     /**
-     * Save token as individual file to token storage providers
-     * Similar to lottery's saveReceivedToken() pattern
+     * Non-blocking proof check with 500ms timeout.
      */
-    private saveTokenToFileStorage;
+    private quickProofCheck;
     /**
-     * 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.
+     * Perform V5 bundle finalization from stored bundle data and proofs.
+     * Extracted from InstantSplitProcessor.processV5Bundle() steps 4-10.
      */
-    private loadTokensFromFileStorage;
+    private finalizeFromV5Bundle;
     /**
-     * Update an existing token
+     * Parse pending finalization metadata from token's sdkData.
      */
-    updateToken(token: Token): Promise<void>;
+    private parsePendingFinalization;
     /**
-     * Remove a token by ID
+     * Update pending finalization metadata in token's sdkData.
+     * Creates a new token object since sdkData is readonly.
      */
-    removeToken(tokenId: string, recipientNametag?: string, skipHistory?: boolean): Promise<void>;
+    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;
     /**
-     * Delete physical token file(s) from all storage providers.
-     * Finds files by matching the SDK token ID prefix in the filename.
+     * 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 deleteTokenFiles;
+    private loadPendingV5Tokens;
     /**
-     * Get all tombstones
+     * 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>;
+    /**
+     * 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`).
+     */
+    removeToken(tokenId: string, recipientNametag?: string, skipHistory?: boolean): Promise<void>;
+    /**
+     * 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
@@ -2070,30 +2279,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[];
     /**
@@ -2258,6 +2497,126 @@ declare class CommunicationsModule {
     private ensureInitialized;
 }
 
+/**
+ * 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;
+}
+
 /** Network configurations */
 declare const NETWORKS: {
     readonly mainnet: {
@@ -2266,6 +2625,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";
@@ -2273,6 +2633,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";
@@ -2280,6 +2641,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;
@@ -2365,6 +2727,8 @@ type LegacyFileType = 'dat' | 'txt' | 'json' | 'mnemonic' | 'unknown';
  */
 type DecryptionProgressCallback = (iteration: number, total: number) => Promise<void> | void;
 
+declare function isValidNametag(nametag: string): boolean;
+
 /** Options for creating a new wallet */
 interface SphereCreateOptions {
     /** BIP39 mnemonic (12 or 24 words) */
@@ -2391,6 +2755,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 {
@@ -2412,6 +2778,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 {
@@ -2441,6 +2809,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 {
@@ -2479,6 +2849,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 {
@@ -2514,6 +2891,7 @@ declare class Sphere {
     private _priceProvider;
     private _payments;
     private _communications;
+    private _groupChat;
     private eventHandlers;
     private constructor();
     /**
@@ -2546,6 +2924,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
      */
@@ -2602,6 +2992,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 */
@@ -3095,9 +3487,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;
@@ -3378,4 +3770,4 @@ declare function randomHex(byteLength: number): string;
  */
 declare function randomUUID(): string;
 
-export { type AddressInfo, CHARSET, CurrencyUtils, DEFAULT_DERIVATION_PATH, DEFAULT_TOKEN_DECIMALS, type DerivedKey, type EncryptedData, type EncryptionOptions, type KeyPair, type L1Config, type MasterKey, type ScanAddressProgress, type ScanAddressesOptions, type ScanAddressesResult, type ScannedAddressResult, Sphere, type SphereCreateOptions, type SphereImportOptions, type SphereInitOptions, type SphereInitResult, type SphereLoadOptions, base58Decode, base58Encode, bytesToHex, computeHash160, convertBits, createAddress, createBech32, createKeyPair, createSphere, decodeBech32, decrypt, decryptJson, decryptMnemonic, decryptSimple, decryptWithSalt, deriveAddressInfo, deriveChildKey, deriveKeyAtPath, deserializeEncrypted, doubleSha256, ec, encodeBech32, encrypt, encryptMnemonic, encryptSimple, entropyToMnemonic, extractFromText, findPattern, formatAmount, generateAddressInfo, generateMasterKey, generateMnemonic, generateRandomKey, getAddressHrp, getPublicKey, getSphere, hash160, hash160ToBytes, hexToBytes, identityFromMnemonic, identityFromMnemonicSync, importSphere, initSphere, isEncryptedData, isValidBech32, isValidPrivateKey, loadSphere, mnemonicToEntropy, mnemonicToSeed, mnemonicToSeedSync, privateKeyToAddressInfo, publicKeyToAddress, randomBytes, randomHex, randomUUID, ripemd160, scanAddressesImpl, serializeEncrypted, sha256, sleep, sphereExists, toHumanReadable, toSmallestUnit, validateMnemonic };
+export { type AddressInfo, CHARSET, CurrencyUtils, DEFAULT_DERIVATION_PATH, DEFAULT_TOKEN_DECIMALS, type DerivedKey, type EncryptedData, type EncryptionOptions, type KeyPair, type L1Config, type MasterKey, type ScanAddressProgress, type ScanAddressesOptions, type ScanAddressesResult, type ScannedAddressResult, Sphere, type SphereCreateOptions, type SphereImportOptions, type SphereInitOptions, type SphereInitResult, type SphereLoadOptions, base58Decode, base58Encode, bytesToHex, computeHash160, convertBits, createAddress, createBech32, createKeyPair, createSphere, decodeBech32, decrypt, decryptJson, decryptMnemonic, decryptSimple, decryptWithSalt, deriveAddressInfo, deriveChildKey, deriveKeyAtPath, deserializeEncrypted, doubleSha256, ec, encodeBech32, encrypt, encryptMnemonic, encryptSimple, entropyToMnemonic, extractFromText, findPattern, formatAmount, generateAddressInfo, generateMasterKey, generateMnemonic, generateRandomKey, getAddressHrp, getPublicKey, getSphere, hash160, hash160ToBytes, hexToBytes, identityFromMnemonic, identityFromMnemonicSync, importSphere, initSphere, isEncryptedData, isValidBech32, isValidNametag, isValidPrivateKey, loadSphere, mnemonicToEntropy, mnemonicToSeed, mnemonicToSeedSync, privateKeyToAddressInfo, publicKeyToAddress, randomBytes, randomHex, randomUUID, ripemd160, scanAddressesImpl, serializeEncrypted, sha256, sleep, sphereExists, toHumanReadable, toSmallestUnit, validateMnemonic };