@unicitylabs/sphere-sdk 0.3.8 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (49) hide show
  1. package/dist/connect/index.cjs +770 -0
  2. package/dist/connect/index.cjs.map +1 -0
  3. package/dist/connect/index.d.cts +312 -0
  4. package/dist/connect/index.d.ts +312 -0
  5. package/dist/connect/index.js +747 -0
  6. package/dist/connect/index.js.map +1 -0
  7. package/dist/core/index.cjs +2744 -56
  8. package/dist/core/index.cjs.map +1 -1
  9. package/dist/core/index.d.cts +277 -3
  10. package/dist/core/index.d.ts +277 -3
  11. package/dist/core/index.js +2740 -52
  12. package/dist/core/index.js.map +1 -1
  13. package/dist/impl/browser/connect/index.cjs +271 -0
  14. package/dist/impl/browser/connect/index.cjs.map +1 -0
  15. package/dist/impl/browser/connect/index.d.cts +137 -0
  16. package/dist/impl/browser/connect/index.d.ts +137 -0
  17. package/dist/impl/browser/connect/index.js +248 -0
  18. package/dist/impl/browser/connect/index.js.map +1 -0
  19. package/dist/impl/browser/index.cjs +583 -45
  20. package/dist/impl/browser/index.cjs.map +1 -1
  21. package/dist/impl/browser/index.js +587 -46
  22. package/dist/impl/browser/index.js.map +1 -1
  23. package/dist/impl/browser/ipfs.cjs.map +1 -1
  24. package/dist/impl/browser/ipfs.js.map +1 -1
  25. package/dist/impl/nodejs/connect/index.cjs +372 -0
  26. package/dist/impl/nodejs/connect/index.cjs.map +1 -0
  27. package/dist/impl/nodejs/connect/index.d.cts +178 -0
  28. package/dist/impl/nodejs/connect/index.d.ts +178 -0
  29. package/dist/impl/nodejs/connect/index.js +333 -0
  30. package/dist/impl/nodejs/connect/index.js.map +1 -0
  31. package/dist/impl/nodejs/index.cjs +266 -12
  32. package/dist/impl/nodejs/index.cjs.map +1 -1
  33. package/dist/impl/nodejs/index.d.cts +96 -0
  34. package/dist/impl/nodejs/index.d.ts +96 -0
  35. package/dist/impl/nodejs/index.js +270 -13
  36. package/dist/impl/nodejs/index.js.map +1 -1
  37. package/dist/index.cjs +2761 -56
  38. package/dist/index.cjs.map +1 -1
  39. package/dist/index.d.cts +375 -5
  40. package/dist/index.d.ts +375 -5
  41. package/dist/index.js +2750 -52
  42. package/dist/index.js.map +1 -1
  43. package/dist/l1/index.cjs +5 -1
  44. package/dist/l1/index.cjs.map +1 -1
  45. package/dist/l1/index.d.cts +2 -1
  46. package/dist/l1/index.d.ts +2 -1
  47. package/dist/l1/index.js +5 -1
  48. package/dist/l1/index.js.map +1 -1
  49. package/package.json +31 -1
package/dist/index.d.cts CHANGED
@@ -1132,6 +1132,11 @@ interface BroadcastMessage {
1132
1132
  readonly timestamp: number;
1133
1133
  readonly tags?: string[];
1134
1134
  }
1135
+ interface ComposingIndicator {
1136
+ readonly senderPubkey: string;
1137
+ readonly senderNametag?: string;
1138
+ readonly expiresIn: number;
1139
+ }
1135
1140
  /**
1136
1141
  * Minimal data stored in persistent storage for a tracked address.
1137
1142
  * Only contains user state — derived fields are computed on load.
@@ -1162,7 +1167,7 @@ interface TrackedAddress extends TrackedAddressEntry {
1162
1167
  /** Primary nametag (from nametag cache, without @ prefix) */
1163
1168
  readonly nametag?: string;
1164
1169
  }
1165
- 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';
1170
+ 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:read' | 'message:typing' | 'composing:started' | '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';
1166
1171
  interface SphereEventMap {
1167
1172
  'transfer:incoming': IncomingTransfer;
1168
1173
  'transfer:confirmed': TransferResult;
@@ -1173,6 +1178,16 @@ interface SphereEventMap {
1173
1178
  'payment_request:paid': IncomingPaymentRequest$1;
1174
1179
  'payment_request:response': PaymentRequestResponse;
1175
1180
  'message:dm': DirectMessage;
1181
+ 'message:read': {
1182
+ messageIds: string[];
1183
+ peerPubkey: string;
1184
+ };
1185
+ 'message:typing': {
1186
+ senderPubkey: string;
1187
+ senderNametag?: string;
1188
+ timestamp: number;
1189
+ };
1190
+ 'composing:started': ComposingIndicator;
1176
1191
  'message:broadcast': BroadcastMessage;
1177
1192
  'sync:started': {
1178
1193
  source: string;
@@ -1542,6 +1557,38 @@ interface TransportProvider extends BaseProvider {
1542
1557
  * @returns Unsubscribe function
1543
1558
  */
1544
1559
  onPaymentRequestResponse?(handler: PaymentRequestResponseHandler): () => void;
1560
+ /**
1561
+ * Send a read receipt for a message
1562
+ * @param recipientTransportPubkey - Transport pubkey of the message sender
1563
+ * @param messageEventId - Event ID of the message being acknowledged
1564
+ */
1565
+ sendReadReceipt?(recipientTransportPubkey: string, messageEventId: string): Promise<void>;
1566
+ /**
1567
+ * Subscribe to incoming read receipts
1568
+ * @returns Unsubscribe function
1569
+ */
1570
+ onReadReceipt?(handler: ReadReceiptHandler): () => void;
1571
+ /**
1572
+ * Send typing indicator to a recipient
1573
+ * @param recipientTransportPubkey - Transport pubkey of the conversation partner
1574
+ */
1575
+ sendTypingIndicator?(recipientTransportPubkey: string): Promise<void>;
1576
+ /**
1577
+ * Subscribe to incoming typing indicators
1578
+ * @returns Unsubscribe function
1579
+ */
1580
+ onTypingIndicator?(handler: TypingIndicatorHandler): () => void;
1581
+ /**
1582
+ * Send composing indicator to a recipient using NIP-44 encrypted gift wrap
1583
+ * @param recipientTransportPubkey - Transport pubkey of the conversation partner
1584
+ * @param content - JSON payload with senderNametag and expiresIn
1585
+ */
1586
+ sendComposingIndicator?(recipientTransportPubkey: string, content: string): Promise<void>;
1587
+ /**
1588
+ * Subscribe to incoming composing indicators
1589
+ * @returns Unsubscribe function
1590
+ */
1591
+ onComposing?(handler: ComposingHandler): () => void;
1545
1592
  /**
1546
1593
  * Get list of configured relay URLs
1547
1594
  */
@@ -1631,6 +1678,10 @@ interface IncomingMessage {
1631
1678
  content: string;
1632
1679
  timestamp: number;
1633
1680
  encrypted: boolean;
1681
+ /** Set when this is a self-wrap replay (sent message recovered from relay) */
1682
+ isSelfWrap?: boolean;
1683
+ /** Recipient pubkey — only present on self-wrap replays */
1684
+ recipientTransportPubkey?: string;
1634
1685
  }
1635
1686
  type MessageHandler = (message: IncomingMessage) => void;
1636
1687
  interface TokenTransferPayload {
@@ -1752,6 +1803,25 @@ interface PeerInfo {
1752
1803
  /** Event timestamp */
1753
1804
  timestamp: number;
1754
1805
  }
1806
+ interface IncomingReadReceipt {
1807
+ /** Transport-specific pubkey of the sender who read the message */
1808
+ senderTransportPubkey: string;
1809
+ /** Event ID of the message that was read */
1810
+ messageEventId: string;
1811
+ /** Timestamp */
1812
+ timestamp: number;
1813
+ }
1814
+ type ReadReceiptHandler = (receipt: IncomingReadReceipt) => void;
1815
+ interface IncomingTypingIndicator {
1816
+ /** Transport-specific pubkey of the sender who is typing */
1817
+ senderTransportPubkey: string;
1818
+ /** Sender's nametag (if known) */
1819
+ senderNametag?: string;
1820
+ /** Timestamp */
1821
+ timestamp: number;
1822
+ }
1823
+ type TypingIndicatorHandler = (indicator: IncomingTypingIndicator) => void;
1824
+ type ComposingHandler = (indicator: ComposingIndicator) => void;
1755
1825
 
1756
1826
  /**
1757
1827
  * L1 Payments Sub-Module
@@ -3084,6 +3154,11 @@ declare class PaymentsModule {
3084
3154
  * Create SigningService from identity private key
3085
3155
  */
3086
3156
  private createSigningService;
3157
+ /**
3158
+ * Get the wallet's signing public key (used for token ownership predicates).
3159
+ * This is the key that token state predicates are checked against.
3160
+ */
3161
+ getSigningPublicKey(): Promise<Uint8Array>;
3087
3162
  /**
3088
3163
  * Create DirectAddress from a public key using UnmaskedPredicateReference
3089
3164
  */
@@ -3149,11 +3224,24 @@ declare function createPaymentsModule(config?: PaymentsModuleConfig): PaymentsMo
3149
3224
  interface CommunicationsModuleConfig {
3150
3225
  /** Auto-save messages */
3151
3226
  autoSave?: boolean;
3152
- /** Max messages in memory */
3227
+ /** Max messages in memory (global cap) */
3153
3228
  maxMessages?: number;
3229
+ /** Max messages per conversation (default: 200) */
3230
+ maxPerConversation?: number;
3154
3231
  /** Enable read receipts */
3155
3232
  readReceipts?: boolean;
3156
3233
  }
3234
+ interface ConversationPage {
3235
+ messages: DirectMessage[];
3236
+ hasMore: boolean;
3237
+ oldestTimestamp: number | null;
3238
+ }
3239
+ interface GetConversationPageOptions {
3240
+ /** Max messages to return (default: 20) */
3241
+ limit?: number;
3242
+ /** Return messages older than this timestamp */
3243
+ before?: number;
3244
+ }
3157
3245
  interface CommunicationsModuleDependencies {
3158
3246
  identity: FullIdentity;
3159
3247
  storage: StorageProvider;
@@ -3166,8 +3254,10 @@ declare class CommunicationsModule {
3166
3254
  private messages;
3167
3255
  private broadcasts;
3168
3256
  private unsubscribeMessages;
3257
+ private unsubscribeComposing;
3169
3258
  private broadcastSubscriptions;
3170
3259
  private dmHandlers;
3260
+ private composingHandlers;
3171
3261
  private broadcastHandlers;
3172
3262
  constructor(config?: CommunicationsModuleConfig);
3173
3263
  /**
@@ -3175,7 +3265,10 @@ declare class CommunicationsModule {
3175
3265
  */
3176
3266
  initialize(deps: CommunicationsModuleDependencies): void;
3177
3267
  /**
3178
- * Load messages from storage
3268
+ * Load messages from storage.
3269
+ * Uses per-address key (STORAGE_KEYS_ADDRESS.MESSAGES) which is automatically
3270
+ * scoped by LocalStorageProvider to sphere_DIRECT_xxx_yyy_messages.
3271
+ * Falls back to legacy global 'direct_messages' key for migration.
3179
3272
  */
3180
3273
  load(): Promise<void>;
3181
3274
  /**
@@ -3202,6 +3295,28 @@ declare class CommunicationsModule {
3202
3295
  * Get unread count
3203
3296
  */
3204
3297
  getUnreadCount(peerPubkey?: string): number;
3298
+ /**
3299
+ * Get a page of messages from a conversation (for lazy loading).
3300
+ * Returns messages in chronological order with a cursor for loading older messages.
3301
+ */
3302
+ getConversationPage(peerPubkey: string, options?: GetConversationPageOptions): ConversationPage;
3303
+ /**
3304
+ * Delete all messages in a conversation with a peer
3305
+ */
3306
+ deleteConversation(peerPubkey: string): Promise<void>;
3307
+ /**
3308
+ * Send typing indicator to a peer
3309
+ */
3310
+ sendTypingIndicator(peerPubkey: string): Promise<void>;
3311
+ /**
3312
+ * Send a composing indicator to a peer.
3313
+ * Fire-and-forget — does not save to message history.
3314
+ */
3315
+ sendComposingIndicator(recipientPubkeyOrNametag: string): Promise<void>;
3316
+ /**
3317
+ * Subscribe to incoming composing indicators
3318
+ */
3319
+ onComposingIndicator(handler: (indicator: ComposingIndicator) => void): () => void;
3205
3320
  /**
3206
3321
  * Subscribe to incoming DMs
3207
3322
  */
@@ -3223,6 +3338,7 @@ declare class CommunicationsModule {
3223
3338
  */
3224
3339
  onBroadcast(handler: (message: BroadcastMessage) => void): () => void;
3225
3340
  private handleIncomingMessage;
3341
+ private handleComposingIndicator;
3226
3342
  private handleIncomingBroadcast;
3227
3343
  private save;
3228
3344
  private pruneIfNeeded;
@@ -3352,12 +3468,233 @@ declare class GroupChatModule {
3352
3468
  }
3353
3469
  declare function createGroupChatModule(config?: GroupChatModuleConfig): GroupChatModule;
3354
3470
 
3471
+ /**
3472
+ * Market Module Types
3473
+ * Intent bulletin board for posting and discovering intents,
3474
+ * plus real-time feed subscription.
3475
+ */
3476
+ type IntentType = 'buy' | 'sell' | 'service' | 'announcement' | 'other' | (string & {});
3477
+ type IntentStatus = 'active' | 'closed' | 'expired';
3478
+ interface MarketModuleConfig {
3479
+ /** Market API base URL (default: https://market-api.unicity.network) */
3480
+ apiUrl?: string;
3481
+ /** Request timeout in ms (default: 30000) */
3482
+ timeout?: number;
3483
+ }
3484
+ interface MarketModuleDependencies {
3485
+ identity: FullIdentity;
3486
+ emitEvent: <T extends SphereEventType>(type: T, data: SphereEventMap[T]) => void;
3487
+ }
3488
+ interface PostIntentRequest {
3489
+ description: string;
3490
+ intentType: IntentType;
3491
+ category?: string;
3492
+ price?: number;
3493
+ currency?: string;
3494
+ location?: string;
3495
+ contactHandle?: string;
3496
+ expiresInDays?: number;
3497
+ }
3498
+ interface PostIntentResult {
3499
+ intentId: string;
3500
+ message: string;
3501
+ expiresAt: string;
3502
+ }
3503
+ interface MarketIntent {
3504
+ id: string;
3505
+ intentType: IntentType;
3506
+ category?: string;
3507
+ price?: string;
3508
+ currency: string;
3509
+ location?: string;
3510
+ status: IntentStatus;
3511
+ createdAt: string;
3512
+ expiresAt: string;
3513
+ }
3514
+ interface SearchIntentResult {
3515
+ id: string;
3516
+ score: number;
3517
+ agentNametag?: string;
3518
+ agentPublicKey: string;
3519
+ description: string;
3520
+ intentType: IntentType;
3521
+ category?: string;
3522
+ price?: number;
3523
+ currency: string;
3524
+ location?: string;
3525
+ contactMethod: string;
3526
+ contactHandle?: string;
3527
+ createdAt: string;
3528
+ expiresAt: string;
3529
+ }
3530
+ interface SearchFilters {
3531
+ intentType?: IntentType;
3532
+ category?: string;
3533
+ minPrice?: number;
3534
+ maxPrice?: number;
3535
+ location?: string;
3536
+ /** Minimum similarity score (0–1). Results below this threshold are excluded (client-side). */
3537
+ minScore?: number;
3538
+ }
3539
+ interface SearchOptions {
3540
+ filters?: SearchFilters;
3541
+ limit?: number;
3542
+ }
3543
+ interface SearchResult {
3544
+ intents: SearchIntentResult[];
3545
+ count: number;
3546
+ }
3547
+ /** A listing broadcast on the live feed */
3548
+ interface FeedListing {
3549
+ id: string;
3550
+ title: string;
3551
+ descriptionPreview: string;
3552
+ agentName: string;
3553
+ agentId: number;
3554
+ type: IntentType;
3555
+ createdAt: string;
3556
+ }
3557
+ /** WebSocket message: initial batch of recent listings */
3558
+ interface FeedInitialMessage {
3559
+ type: 'initial';
3560
+ listings: FeedListing[];
3561
+ }
3562
+ /** WebSocket message: single new listing */
3563
+ interface FeedNewMessage {
3564
+ type: 'new';
3565
+ listing: FeedListing;
3566
+ }
3567
+ type FeedMessage = FeedInitialMessage | FeedNewMessage;
3568
+ /** Callback for live feed events */
3569
+ type FeedListener = (message: FeedMessage) => void;
3570
+
3571
+ /**
3572
+ * Market Module
3573
+ *
3574
+ * Intent bulletin board — post and discover intents (buy, sell,
3575
+ * service, announcement, other) with secp256k1-signed requests
3576
+ * tied to the wallet identity. Includes real-time feed via WebSocket.
3577
+ */
3578
+ /** Default Market API URL (intent bulletin board) */
3579
+ declare const DEFAULT_MARKET_API_URL = "https://market-api.unicity.network";
3580
+
3581
+ declare class MarketModule {
3582
+ private readonly apiUrl;
3583
+ private readonly timeout;
3584
+ private identity;
3585
+ private registered;
3586
+ constructor(config?: MarketModuleConfig);
3587
+ /** Called by Sphere after construction */
3588
+ initialize(deps: MarketModuleDependencies): void;
3589
+ /** No-op — stateless module */
3590
+ load(): Promise<void>;
3591
+ /** No-op — stateless module */
3592
+ destroy(): void;
3593
+ /** Post a new intent (agent is auto-registered on first post) */
3594
+ postIntent(intent: PostIntentRequest): Promise<PostIntentResult>;
3595
+ /** Semantic search for intents (public — no auth required) */
3596
+ search(query: string, opts?: SearchOptions): Promise<SearchResult>;
3597
+ /** List own intents (authenticated) */
3598
+ getMyIntents(): Promise<MarketIntent[]>;
3599
+ /** Close (delete) an intent */
3600
+ closeIntent(intentId: string): Promise<void>;
3601
+ /** Fetch the most recent listings via REST (public — no auth required) */
3602
+ getRecentListings(): Promise<FeedListing[]>;
3603
+ /**
3604
+ * Subscribe to the live listing feed via WebSocket.
3605
+ * Returns an unsubscribe function that closes the connection.
3606
+ *
3607
+ * Requires a WebSocket implementation — works natively in browsers
3608
+ * and in Node.js 21+ (or with the `ws` package).
3609
+ */
3610
+ subscribeFeed(listener: FeedListener): () => void;
3611
+ private ensureIdentity;
3612
+ /** Register the agent's public key with the server (idempotent) */
3613
+ private ensureRegistered;
3614
+ private parseResponse;
3615
+ private apiPost;
3616
+ private apiGet;
3617
+ private apiDelete;
3618
+ private apiPublicPost;
3619
+ }
3620
+ declare function createMarketModule(config?: MarketModuleConfig): MarketModule;
3621
+
3355
3622
  /**
3356
3623
  * SDK2 Constants
3357
3624
  * Default configuration values and storage keys
3358
3625
  */
3359
3626
  /** Default prefix for all storage keys */
3360
3627
  declare const STORAGE_PREFIX: "sphere_";
3628
+ /**
3629
+ * Global storage keys (one per wallet, no address index)
3630
+ * Final key format: sphere_{key}
3631
+ */
3632
+ declare const STORAGE_KEYS_GLOBAL: {
3633
+ /** Encrypted BIP39 mnemonic */
3634
+ readonly MNEMONIC: "mnemonic";
3635
+ /** Encrypted master private key */
3636
+ readonly MASTER_KEY: "master_key";
3637
+ /** BIP32 chain code */
3638
+ readonly CHAIN_CODE: "chain_code";
3639
+ /** HD derivation path (full path like m/44'/0'/0'/0/0) */
3640
+ readonly DERIVATION_PATH: "derivation_path";
3641
+ /** Base derivation path (like m/44'/0'/0' without chain/index) */
3642
+ readonly BASE_PATH: "base_path";
3643
+ /** Derivation mode: bip32, wif_hmac, legacy_hmac */
3644
+ readonly DERIVATION_MODE: "derivation_mode";
3645
+ /** Wallet source: mnemonic, file, unknown */
3646
+ readonly WALLET_SOURCE: "wallet_source";
3647
+ /** Wallet existence flag */
3648
+ readonly WALLET_EXISTS: "wallet_exists";
3649
+ /** Current active address index */
3650
+ readonly CURRENT_ADDRESS_INDEX: "current_address_index";
3651
+ /** Nametag cache per address (separate from tracked addresses registry) */
3652
+ readonly ADDRESS_NAMETAGS: "address_nametags";
3653
+ /** Active addresses registry (JSON: TrackedAddressesStorage) */
3654
+ readonly TRACKED_ADDRESSES: "tracked_addresses";
3655
+ /** Last processed Nostr wallet event timestamp (unix seconds), keyed per pubkey */
3656
+ readonly LAST_WALLET_EVENT_TS: "last_wallet_event_ts";
3657
+ /** Group chat: joined groups */
3658
+ readonly GROUP_CHAT_GROUPS: "group_chat_groups";
3659
+ /** Group chat: messages */
3660
+ readonly GROUP_CHAT_MESSAGES: "group_chat_messages";
3661
+ /** Group chat: members */
3662
+ readonly GROUP_CHAT_MEMBERS: "group_chat_members";
3663
+ /** Group chat: processed event IDs for deduplication */
3664
+ readonly GROUP_CHAT_PROCESSED_EVENTS: "group_chat_processed_events";
3665
+ /** Group chat: last used relay URL (stale data detection) */
3666
+ readonly GROUP_CHAT_RELAY_URL: "group_chat_relay_url";
3667
+ /** Cached token registry JSON (fetched from remote) */
3668
+ readonly TOKEN_REGISTRY_CACHE: "token_registry_cache";
3669
+ /** Timestamp of last token registry cache update (ms since epoch) */
3670
+ readonly TOKEN_REGISTRY_CACHE_TS: "token_registry_cache_ts";
3671
+ /** Cached price data JSON (from CoinGecko or other provider) */
3672
+ readonly PRICE_CACHE: "price_cache";
3673
+ /** Timestamp of last price cache update (ms since epoch) */
3674
+ readonly PRICE_CACHE_TS: "price_cache_ts";
3675
+ };
3676
+ /**
3677
+ * Per-address storage keys (one per derived address)
3678
+ * Final key format: sphere_{DIRECT_xxx_yyy}_{key}
3679
+ * Example: sphere_DIRECT_abc123_xyz789_pending_transfers
3680
+ *
3681
+ * Note: Token data (tokens, tombstones, archived, forked) is stored via
3682
+ * TokenStorageProvider, not here. This avoids duplication.
3683
+ */
3684
+ declare const STORAGE_KEYS_ADDRESS: {
3685
+ /** Pending transfers for this address */
3686
+ readonly PENDING_TRANSFERS: "pending_transfers";
3687
+ /** Transfer outbox for this address */
3688
+ readonly OUTBOX: "outbox";
3689
+ /** Conversations for this address */
3690
+ readonly CONVERSATIONS: "conversations";
3691
+ /** Messages for this address */
3692
+ readonly MESSAGES: "messages";
3693
+ /** Transaction history for this address */
3694
+ readonly TRANSACTION_HISTORY: "transaction_history";
3695
+ /** Pending V5 finalization tokens (unconfirmed instant split tokens) */
3696
+ readonly PENDING_V5_TOKENS: "pending_v5_tokens";
3697
+ };
3361
3698
  /** @deprecated Use STORAGE_KEYS_GLOBAL and STORAGE_KEYS_ADDRESS instead */
3362
3699
  declare const STORAGE_KEYS: {
3363
3700
  /** Pending transfers for this address */
@@ -3415,6 +3752,20 @@ declare const STORAGE_KEYS: {
3415
3752
  /** Timestamp of last price cache update (ms since epoch) */
3416
3753
  readonly PRICE_CACHE_TS: "price_cache_ts";
3417
3754
  };
3755
+ /**
3756
+ * Build a per-address storage key using address identifier
3757
+ * @param addressId - Short identifier for the address (e.g., first 8 chars of pubkey hash, or direct address hash)
3758
+ * @param key - The key from STORAGE_KEYS_ADDRESS
3759
+ * @returns Key in format: "{addressId}_{key}" e.g., "a1b2c3d4_tokens"
3760
+ */
3761
+ declare function getAddressStorageKey(addressId: string, key: string): string;
3762
+ /**
3763
+ * Create a readable address identifier from directAddress or chainPubkey
3764
+ * Format: DIRECT_first6_last6 (sanitized for filesystem/storage)
3765
+ * @param directAddress - The L3 direct address (DIRECT:xxx) or chainPubkey
3766
+ * @returns Sanitized identifier like "DIRECT_abc123_xyz789"
3767
+ */
3768
+ declare function getAddressId(directAddress: string): string;
3418
3769
  /** Default Nostr relays */
3419
3770
  declare const DEFAULT_NOSTR_RELAYS: readonly ["wss://relay.unicity.network", "wss://relay.damus.io", "wss://nos.lol", "wss://relay.nostr.band"];
3420
3771
  /** Nostr event kinds used by SDK - must match @unicitylabs/nostr-js-sdk */
@@ -3710,6 +4061,8 @@ interface SphereCreateOptions {
3710
4061
  network?: NetworkType;
3711
4062
  /** Group chat configuration (NIP-29). Omit to disable groupchat. */
3712
4063
  groupChat?: GroupChatModuleConfig | boolean;
4064
+ /** Market module configuration. true = enable with defaults, object = custom config. */
4065
+ market?: MarketModuleConfig | boolean;
3713
4066
  /** Optional password to encrypt the wallet. If omitted, mnemonic is stored as plaintext. */
3714
4067
  password?: string;
3715
4068
  }
@@ -3735,6 +4088,8 @@ interface SphereLoadOptions {
3735
4088
  network?: NetworkType;
3736
4089
  /** Group chat configuration (NIP-29). Omit to disable groupchat. */
3737
4090
  groupChat?: GroupChatModuleConfig | boolean;
4091
+ /** Market module configuration. true = enable with defaults, object = custom config. */
4092
+ market?: MarketModuleConfig | boolean;
3738
4093
  /** Optional password to decrypt the wallet. Must match the password used during creation. */
3739
4094
  password?: string;
3740
4095
  }
@@ -3768,6 +4123,8 @@ interface SphereImportOptions {
3768
4123
  price?: PriceProvider;
3769
4124
  /** Group chat configuration (NIP-29). Omit to disable groupchat. */
3770
4125
  groupChat?: GroupChatModuleConfig | boolean;
4126
+ /** Market module configuration. true = enable with defaults, object = custom config. */
4127
+ market?: MarketModuleConfig | boolean;
3771
4128
  /** Optional password to encrypt the wallet. If omitted, mnemonic/key is stored as plaintext. */
3772
4129
  password?: string;
3773
4130
  }
@@ -3815,6 +4172,8 @@ interface SphereInitOptions {
3815
4172
  * - Omit/undefined: No groupchat module
3816
4173
  */
3817
4174
  groupChat?: GroupChatModuleConfig | boolean;
4175
+ /** Market module configuration. true = enable with defaults, object = custom config. */
4176
+ market?: MarketModuleConfig | boolean;
3818
4177
  /** Optional password to encrypt/decrypt the wallet. If omitted, mnemonic is stored as plaintext. */
3819
4178
  password?: string;
3820
4179
  }
@@ -3854,6 +4213,7 @@ declare class Sphere {
3854
4213
  private _payments;
3855
4214
  private _communications;
3856
4215
  private _groupChat;
4216
+ private _market;
3857
4217
  private eventHandlers;
3858
4218
  private _disabledProviders;
3859
4219
  private _providerEventCleanups;
@@ -3901,6 +4261,13 @@ declare class Sphere {
3901
4261
  * (different input shape: { enabled?, relays? }). Both fill relay URLs from network defaults.
3902
4262
  */
3903
4263
  private static resolveGroupChatConfig;
4264
+ /**
4265
+ * Resolve market module config from Sphere.init() options.
4266
+ * - `true` → enable with default API URL
4267
+ * - `MarketModuleConfig` → pass through
4268
+ * - `undefined` → no market module
4269
+ */
4270
+ private static resolveMarketConfig;
3904
4271
  /**
3905
4272
  * Configure TokenRegistry in the main bundle context.
3906
4273
  *
@@ -3969,6 +4336,8 @@ declare class Sphere {
3969
4336
  get communications(): CommunicationsModule;
3970
4337
  /** Group chat module (NIP-29). Null if not configured. */
3971
4338
  get groupChat(): GroupChatModule | null;
4339
+ /** Market module (intent bulletin board). Null if not configured. */
4340
+ get market(): MarketModule | null;
3972
4341
  /** Current identity (public info only) */
3973
4342
  get identity(): Identity | null;
3974
4343
  /** Is ready */
@@ -5481,7 +5850,8 @@ declare class VestingClassifier {
5481
5850
  private storeName;
5482
5851
  private db;
5483
5852
  /**
5484
- * Initialize IndexedDB for persistent caching
5853
+ * Initialize IndexedDB for persistent caching.
5854
+ * In Node.js (no IndexedDB), silently falls back to memory-only caching.
5485
5855
  */
5486
5856
  initDB(): Promise<void>;
5487
5857
  /**
@@ -6051,4 +6421,4 @@ declare function getCoinIdBySymbol(symbol: string): string | undefined;
6051
6421
  */
6052
6422
  declare function getCoinIdByName(name: string): string | undefined;
6053
6423
 
6054
- 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, type CheckNetworkHealthOptions, 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 HealthCheckFn, 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 NetworkHealthResult, 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 ProviderRole, type ProviderStatus, type ProviderStatusInfo, type ReceiveOptions, type ReceiveResult, type RegistryNetwork, STORAGE_KEYS, STORAGE_PREFIX, type SaveResult, type ScanAddressProgress, type ScanAddressesOptions, type ScanAddressesResult, type ScannedAddressResult, type ServiceHealthResult, 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 SphereStatus, 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, checkNetworkHealth, 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 };
6424
+ 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, type CheckNetworkHealthOptions, CoinGeckoPriceProvider, CommunicationsModule, type CommunicationsModuleConfig, type CommunicationsModuleDependencies, type ComposingIndicator, type ConversationPage, 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_MARKET_API_URL, DEFAULT_NOSTR_RELAYS, DEV_AGGREGATOR_URL, type DecryptionProgressCallback, type DerivationMode, type DirectMessage, type ExtendedValidationResult, type FullIdentity, type GetConversationPageOptions, GroupChatModule, type GroupChatModuleConfig, type GroupChatModuleDependencies, type GroupData, type GroupMemberData, type GroupMessageData, GroupRole, GroupVisibility, type HealthCheckFn, 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 IntentStatus, type IntentType, 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 MarketIntent, MarketModule, type MarketModuleConfig, type MarketModuleDependencies, type MessageHandler, type MintOutboxEntry, type MintParams, type MintResult, NETWORKS, NIP29_KINDS, NOSTR_EVENT_KINDS, type NametagData, type NetworkHealthResult, 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 PostIntentRequest, type PostIntentResult, type PricePlatform, type PriceProvider, type PriceProviderConfig, type ProviderMetadata, type ProviderRole, type ProviderStatus, type ProviderStatusInfo, type ReceiveOptions, type ReceiveResult, type RegistryNetwork, STORAGE_KEYS, STORAGE_KEYS_ADDRESS, STORAGE_KEYS_GLOBAL, STORAGE_PREFIX, type SaveResult, type ScanAddressProgress, type ScanAddressesOptions, type ScanAddressesResult, type ScannedAddressResult, type SearchFilters, type SearchIntentResult, type SearchOptions, type SearchResult, type ServiceHealthResult, 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 SphereStatus, 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, checkNetworkHealth, countCommittedTransactions, createAddress, createCommunicationsModule, createGroupChatModule, createKeyPair, createL1PaymentsModule, createMarketModule, 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, getAddressId, getAddressStorageKey, 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 };