@unicitylabs/sphere-sdk 0.13.3-dev.1 → 0.13.3-dev.2

package/dist/index.d.ts

@@ -1048,605 +1048,628 @@ declare function keyFromTokenId(tokenId: string): string;
 declare function isValidTokenId(tokenId: string): boolean;
 
 /**
- * Transport Provider Interface
- * Platform-independent P2P messaging abstraction
- */
-
-/**
- * P2P messaging transport provider
+ * transport/delivery-provider.ts — the `DeliveryProvider` port (sdk-changes S7,
+ * covenant §3.1-6).
+ *
+ * The seam that keeps the delivery rail swappable. In Unicity, a transfer —
+ * after certification — is just a file handoff, so the port is deliberately
+ * tiny: hand a finished token blob to a recipient, pull incoming deliveries,
+ * acknowledge them. `WalletApiMailboxProvider`
+ * (impl/shared/wallet-api/WalletApiMailboxProvider.ts) is the reference
+ * implementation; anything that can move a file can implement it (the port
+ * shape must not preclude the old Nostr transport or a future federated
+ * transport — neither is a deliverable here).
+ *
+ * Normative shapes (sdk-changes S7):
+ * - `DeliveryReceipt = { deliveryId }`
+ * - `IncomingDelivery = { deliveryId, transferId?, senderPubkey?, memo?,
+ *   fetchBlob(), cursor }`
+ * - `deliveryId` is the **content-derived** entry id —
+ *   `hex(SHA-256(tokenId bytes ‖ stateHash bytes))` — NEVER a server-assigned
+ *   row id or seq (covenant §3.1-4; the contract suite asserts it). It is
+ *   computed client-side ({@link computeDeliveryId}) and must equal the
+ *   backend's `entry_id` (ARCHITECTURE §6).
+ * - **Custody is a composition-time property, not a per-call flag**:
+ *   implementations take `custody: 'inventory' | 'external'` at construction
+ *   and every ack sends the corresponding `intoInventory` — delivery-only
+ *   safety must never depend on remembering an option at a call site.
+ * - Implementations MUST keep a **persistent `(tokenId, stateHash)` seen-set**
+ *   for incoming deliveries: the recipient-side replay guard is part of the
+ *   port contract, not a server promise (the recipient never trusts the
+ *   backend — ARCHITECTURE §8.2). `deliveryId` is the canonical hash encoding
+ *   of exactly that pair, so a persistent deliveryId set satisfies this.
  */
-interface TransportProvider extends BaseProvider {
-    /**
-     * Set identity for signing/encryption.
-     * If the transport is already connected, reconnects with the new identity.
-     */
-    setIdentity(identity: FullIdentity): void | Promise<void>;
-    /**
-     * Send encrypted direct message
-     * @param recipientTransportPubkey - Transport-specific pubkey for messaging
-     * @returns Event ID
-     */
-    sendMessage(recipientTransportPubkey: string, content: string): Promise<string>;
-    /**
-     * Subscribe to incoming direct messages
-     * @returns Unsubscribe function
-     */
-    onMessage(handler: MessageHandler): () => void;
-    /**
-     * Send token transfer payload
-     * @param recipientTransportPubkey - Transport-specific pubkey for messaging
-     * @returns Event ID
-     */
-    sendTokenTransfer(recipientTransportPubkey: string, payload: TokenTransferPayload): Promise<string>;
-    /**
-     * Subscribe to incoming token transfers
-     * @returns Unsubscribe function
-     */
-    onTokenTransfer(handler: TokenTransferHandler): () => void;
+/** Receipt for a delivered blob. `deliveryId` is content-derived — see module doc. */
+interface DeliveryReceipt {
+    deliveryId: string;
+}
+/** Options for {@link DeliveryProvider.deliver}. */
+interface DeliverOptions {
     /**
-     * Resolve any identifier to full peer information.
-     * Accepts @nametag, bare nametag, DIRECT://, chain pubkey, or transport pubkey.
-     * @param identifier - Any supported identifier format
-     * @returns PeerInfo or null if not found
+     * The send's transferId (the E.3 intent id / realization seed). Recorded
+     * with the delivery so the recipient can group multi-token payments and the
+     * backend can evidence-check the sender's removals (ARCHITECTURE §5.3/§6).
      */
-    resolve?(identifier: string): Promise<PeerInfo | null>;
+    transferId: string;
+    /** Optional human memo. Implementations encrypt it client-side (S6). */
+    memo?: string;
     /**
-     * Resolve nametag to public key
+     * The SENDER's own nametag (without a leading `@`), so the recipient can
+     * render the human identity instead of a raw pubkey ("Someone"). Bundled
+     * with the memo into ONE recipient-addressed (ECDH) `enc1.` envelope (S6) —
+     * the operator never sees it. Attached whenever the sender has a nametag OR
+     * a memo (so the nametag travels even on a memo-less transfer).
      */
-    resolveNametag?(nametag: string): Promise<string | null>;
+    senderNametag?: string;
+}
+/** One incoming delivery pulled from the feed. */
+interface IncomingDelivery {
+    /** Content-derived id — `hex(SHA-256(tokenId bytes ‖ stateHash bytes))`. */
+    deliveryId: string;
+    /** The sender's transferId, when the transport carries it. */
+    transferId?: string;
+    /** The sender's pubkey, when the transport carries it. */
+    senderPubkey?: string;
+    /** Decrypted memo (S6), when present and decryptable. */
+    memo?: string;
     /**
-     * Resolve nametag to full peer information
-     * Returns transportPubkey, chainPubkey, directAddress
+     * The sender's nametag (without a leading `@`), decrypted from the same
+     * recipient-addressed delivery envelope as {@link memo} (S6). Lets the
+     * receiver render the human identity instead of a raw pubkey, with no
+     * Nostr/transport lookup. Absent when the envelope carried none or could
+     * not be decrypted.
      */
-    resolveNametagInfo?(nametag: string): Promise<PeerInfo | null>;
+    senderNametag?: string;
+    /** Fetch the finished token blob bytes (the encoded TokenBlob). */
+    fetchBlob(): Promise<Uint8Array>;
+    /** Transport-local resume cursor (opaque to callers). */
+    cursor: string;
+}
+type DeliveryDisposition = 'claimed' | 'rejected';
+/**
+ * The §9 wake streams a backend may nudge: `mailbox` (incoming deliveries),
+ * `inventory` (owned-token set changed — e.g. a top-up or a claim on another
+ * device), and `payment_requests` (a request created/answered). A wake on any
+ * of these is a NUDGE — the consumer pulls that stream's cursor; correctness
+ * never depends on the wake arriving (the poll backstop is the source of
+ * truth).
+ */
+type WakeStream = 'inventory' | 'mailbox' | 'payment_requests';
+/**
+ * True liveness of the realtime wake channel (§9), decoupled from sign-in
+ * session state: `connecting`/`connected` — a socket is (being) established;
+ * `reconnecting` — it dropped and is backing off to re-establish (the poll
+ * backstop carries correctness meanwhile); `closed` — torn down intentionally.
+ * The wake is a nudge, so this is informational for the frontend (a "live"
+ * indicator) — never a correctness gate.
+ */
+type WakeChannelStatus = 'connecting' | 'connected' | 'reconnecting' | 'closed';
+/**
+ * Custody mode (composition-time): `'inventory'` — acknowledged deliveries
+ * enter the wallet-api inventory (the full wallet-api preset); `'external'` —
+ * the app's own storage keeps custody and acks perform ZERO inventory writes
+ * (the delivery-only preset, ARCHITECTURE §6 "delivery-only claim").
+ */
+type DeliveryCustody = 'inventory' | 'external';
+interface DeliveryProvider {
+    /** Composition-time custody property — never a per-call flag (S7). */
+    readonly custody: DeliveryCustody;
     /**
-     * Resolve a DIRECT:// or PROXY:// address to full peer info.
-     * Performs reverse lookup: address → binding event → PeerInfo.
-     * @param address - L3 address (DIRECT://... or PROXY://...)
-     * @returns PeerInfo or null if no binding found for this address
+     * Bind the wallet identity (optional — implementations that authenticate or
+     * encrypt per-wallet need it; mirrors `TokenStorageProvider.setIdentity`).
      */
-    resolveAddressInfo?(address: string): Promise<PeerInfo | null>;
+    setIdentity?(identity: {
+        privateKey: string;
+        chainPubkey: string;
+    }): void;
     /**
-     * Resolve transport pubkey to full peer info.
-     * Queries binding events authored by the given transport pubkey.
-     * @param transportPubkey - Transport-specific pubkey (e.g. 64-char hex string)
-     * @returns PeerInfo or null if no binding found
+     * #583 per-address client isolation: mint an INDEPENDENT delivery provider for
+     * a different HD address, backed by its OWN authenticated client + wake socket
+     * (mirrors `TokenStorageProvider.createForAddress`). Implementations that hold
+     * a single mutable identity+session per instance (e.g. the wallet-api mailbox
+     * over one `WalletApiClient`) provide this so `Sphere.switchToAddress` can give
+     * each address its OWN delivery instance — an orphaned previous-address pump
+     * then re-auths as ITS OWN owner (harmless) instead of driving a client that
+     * was re-bound to the new owner. Stateless transports may omit it (the same
+     * instance serves every address).
      */
-    resolveTransportPubkeyInfo?(transportPubkey: string): Promise<PeerInfo | null>;
+    createForAddress?(): DeliveryProvider;
     /**
-     * Batch-resolve multiple transport pubkeys to peer info.
-     * Used for HD address discovery: derives transport pubkeys for indices 0..N
-     * and queries binding events in a single batch.
-     * @param transportPubkeys - Array of transport-specific pubkeys to look up
-     * @returns Array of PeerInfo for pubkeys that have binding events (may be shorter than input)
+     * Hand a finished token blob to a recipient. `recipientPubkey` is the
+     * recipient's CHAIN pubkey (33-byte compressed secp256k1, hex) — the
+     * canonical Unicity identity (ARCHITECTURE §4); transports that address
+     * recipients differently resolve it themselves.
+     *
+     * MUST be idempotent per (token, state): re-delivering the same finished
+     * blob — including after the recipient claimed — succeeds and returns the
+     * same content-derived `deliveryId` (ARCHITECTURE §6 deposit idempotency).
      */
-    discoverAddresses?(transportPubkeys: string[]): Promise<PeerInfo[]>;
+    deliver(recipientPubkey: string, blob: Uint8Array, options: DeliverOptions): Promise<DeliveryReceipt>;
     /**
-     * Recover nametag for current identity by decrypting stored encrypted nametag
-     * Used after wallet import to recover associated nametag
-     * @returns Decrypted nametag or null if none found
+     * Pull-based feed of incoming deliveries since the given transport-local
+     * cursor (or the provider's persisted cursor when omitted). Yields only
+     * deliveries not yet in the persistent seen-set; completes when the feed is
+     * drained — callers re-invoke on poll/wake. Feeds the existing
+     * transport-agnostic `handleV2Transfer` (sdk-changes S3).
      */
-    recoverNametag?(): Promise<string | null>;
+    incoming(sinceCursor?: string): AsyncIterable<IncomingDelivery>;
     /**
-     * Publish identity binding event.
-     * Without nametag: publishes base binding (chainPubkey, directAddress).
-     * With nametag: adds nametag hash, proxy address, encrypted nametag for recovery.
-     * Uses parameterized replaceable event (kind 30078, d=hash(nostrPubkey)).
-     * @returns true if successful, false if nametag is taken by another pubkey
+     * Acknowledge a delivery: `'claimed'` accepts it (with the provider's
+     * composition-time custody), `'rejected'` marks it locally-unverifiable —
+     * terminal for discovery only (the entry stays claimable server-side and
+     * its blob is retained — ARCHITECTURE §6). Both record the delivery in the
+     * persistent seen-set.
      */
-    publishIdentityBinding?(chainPubkey: string, directAddress: string, nametag?: string): Promise<boolean>;
+    ack(deliveryId: string, disposition: DeliveryDisposition): Promise<void>;
     /**
-     * Subscribe to broadcast messages (global/channel)
+     * Optional batch acknowledge (#623): claim and reject whole pages of incoming deliveries in a
+     * single request each, instead of one per entry — so draining a large inbox (a long-offline or
+     * service wallet) doesn't fire thousands of writes and trip the per-owner rate limit. Same
+     * semantics as {@link ack}: the seen-set records only entries that were acked successfully, so a
+     * partial/failed batch is re-listed and re-processed (idempotent claim, §6). A provider that does
+     * not implement it (e.g. the relay no-op) is driven via per-entry {@link ack}.
      */
-    subscribeToBroadcast?(tags: string[], handler: BroadcastHandler): () => void;
+    ackBatch?(claimed: string[], rejected: string[]): Promise<void>;
     /**
-     * Publish broadcast message
+     * Optional batch deliver (#699): hand N finished blobs to ONE recipient with a single deposit
+     * request (and one upload-urls request) instead of N — a multi-source send then costs O(1)
+     * against the backend's deposit rate limit regardless of fragmentation. Optional like
+     * {@link ackBatch}: the port must not preclude the relay transport or a future federated one,
+     * and neither has a batch primitive — callers probe and fall back to per-blob {@link deliver}.
+     *
+     * Semantically equivalent to awaiting {@link deliver} once per blob, in order:
+     * - receipts return in REQUEST order; each `deliveryId` is the content-derived entry id
+     *   (covenant §3.1-4 — NEVER the batch endpoint's server-assigned seq);
+     * - idempotent per (token, state) exactly like {@link deliver};
+     * - `options` apply to every blob (one send = one transferId/memo/senderNametag);
+     * - throws when ANY blob could not be deposited — blobs that DID land are absorbed
+     *   idempotently when the caller retries, batched or per-blob.
      */
-    publishBroadcast?(content: string, tags?: string[]): Promise<string>;
+    deliverBatch?(recipientPubkey: string, blobs: Uint8Array[], options: DeliverOptions): Promise<DeliveryReceipt[]>;
     /**
-     * Send payment request to a recipient
-     * @param recipientTransportPubkey - Transport-specific pubkey for messaging
-     * @returns Event ID
+     * Optional wake hook: `callback` fires with the {@link WakeStream} that was
+     * nudged when new data may be available on it (e.g. a WS nudge — never a
+     * correctness dependency, ARCHITECTURE §9). The wallet-api wake socket
+     * multiplexes all three owner streams (`mailbox` | `inventory` |
+     * `payment_requests`); the consumer routes each to that stream's pull.
+     *
+     * The underlying socket SELF-HEALS (§9): it reconnects with backoff on any
+     * drop and a liveness watchdog force-reconnects a half-open socket. On every
+     * (re)connect the consumer MUST run a full catch-up pull of every stream —
+     * wakes missed while the socket was dead are not replayed — so `callback`
+     * fires once for EACH stream on (re)connect (a synthetic catch-up nudge).
+     * `onStatus` (optional) surfaces true socket liveness for the frontend,
+     * decoupled from sign-in state. Returns an unsubscribe function.
      */
-    sendPaymentRequest?(recipientTransportPubkey: string, request: PaymentRequestPayload): Promise<string>;
+    onWake?(callback: (stream: WakeStream) => void, onStatus?: (status: WakeChannelStatus) => void): () => void;
     /**
-     * Subscribe to incoming payment requests
-     * @returns Unsubscribe function
+     * Late-bind the backend-true (tokenId, stateHash) derivation —
+     * `ITokenEngine.deliveryKeys`. Compositions are engine-less (the engine is
+     * built later); the module that owns both (PaymentsModule) binds this at
+     * init. Implementations that derive ids (S7) MUST use it and fail loudly if
+     * unbound; transports that don't derive may omit the method.
      */
-    onPaymentRequest?(handler: PaymentRequestHandler$1): () => void;
-    /**
-     * Send response to a payment request
-     * @param recipientTransportPubkey - Transport-specific pubkey for messaging
-     * @returns Event ID
-     */
-    sendPaymentRequestResponse?(recipientTransportPubkey: string, response: PaymentRequestResponsePayload): Promise<string>;
-    /**
-     * Subscribe to incoming payment request responses
-     * @returns Unsubscribe function
-     */
-    onPaymentRequestResponse?(handler: PaymentRequestResponseHandler$1): () => void;
-    /**
-     * Send a read receipt for a message
-     * @param recipientTransportPubkey - Transport pubkey of the message sender
-     * @param messageEventId - Event ID of the message being acknowledged
-     */
-    sendReadReceipt?(recipientTransportPubkey: string, messageEventId: string): Promise<void>;
+    bindDeliveryKeys?(derive: (blobBytes: Uint8Array) => Promise<{
+        tokenId: string;
+        stateHash: string;
+    }>): void;
+}
+/**
+ * The content-derived delivery id:
+ * `hex(SHA-256(tokenId bytes ‖ stateHash bytes))` — identical to the
+ * backend's `entry_id` (ARCHITECTURE §6), computed client-side so no
+ * implementation can substitute a server row id (covenant §3.1-4).
+ *
+ * @param tokenIdHex - genesis-stable 64-hex token id
+ * @param stateHashHex - the SDK's per-state hash (DataHash imprint, hex) — the
+ *   backend's `state_hash` (wallet-api validation/chain.ts); NEVER a plain
+ *   sha256 over the token bytes (that variant 422s on deposit).
+ */
+declare function computeDeliveryId(tokenIdHex: string, stateHashHex: string): string;
+/** Full delivery keys: the engine-derived pair + the composed deliveryId. */
+interface DeliveryBlobKeys {
+    /** Genesis-stable 64-hex token id (from the TokenBlob envelope). */
+    tokenId: string;
+    /** Per-state hash: `hex(SHA-256(inner token bytes))` — changes every transfer. */
+    stateHash: string;
+    /** {@link computeDeliveryId} of the two above. */
+    deliveryId: string;
+}
+/**
+ * Derive (tokenId, stateHash, deliveryId) from encoded TokenBlob bytes.
+ * Throws when the bytes are not a decodable TokenBlob.
+ */
+/**
+ * Compose full delivery keys from an engine-derived (tokenId, stateHash) pair.
+ * The pair MUST come from `ITokenEngine.deliveryKeys` (the backend-true SDK
+ * derivation) — the port module deliberately cannot decode tokens itself.
+ */
+declare function composeDeliveryKeys(keys: {
+    tokenId: string;
+    stateHash: string;
+}): DeliveryBlobKeys;
+
+/**
+ * Receive + delivery: `receive()`, the `handleV2Transfer` receiver, the
+ * PENDING_V2_DELIVERIES journal, the hoisted send delivery pass and the bounded
+ * replay + poison budget. The token map and `save()` stay in PaymentsModule.
+ */
+
+/**
+ * @deprecated v2 transfers arrive as finished tokens — there is no finalization
+ * phase. The options are accepted for backwards compatibility and ignored.
+ */
+interface ReceiveOptions {
+    /** @deprecated Ignored — v2 tokens are stored confirmed on receipt. */
+    finalize?: boolean;
+    /** @deprecated Ignored. */
+    timeout?: number;
+    /** @deprecated Ignored. */
+    pollInterval?: number;
+}
+interface ReceiveResult {
+    /** Newly received incoming transfers. */
+    transfers: IncomingTransfer[];
+}
+
+/**
+ * Transport Provider Interface
+ * Platform-independent P2P messaging abstraction
+ */
+
+/**
+ * P2P messaging transport provider
+ */
+interface TransportProvider extends BaseProvider {
     /**
-     * Subscribe to incoming read receipts
-     * @returns Unsubscribe function
+     * Set identity for signing/encryption.
+     * If the transport is already connected, reconnects with the new identity.
      */
-    onReadReceipt?(handler: ReadReceiptHandler): () => void;
+    setIdentity(identity: FullIdentity): void | Promise<void>;
     /**
-     * Send typing indicator to a recipient
-     * @param recipientTransportPubkey - Transport pubkey of the conversation partner
+     * Send encrypted direct message
+     * @param recipientTransportPubkey - Transport-specific pubkey for messaging
+     * @returns Event ID
      */
-    sendTypingIndicator?(recipientTransportPubkey: string): Promise<void>;
+    sendMessage(recipientTransportPubkey: string, content: string): Promise<string>;
     /**
-     * Subscribe to incoming typing indicators
+     * Subscribe to incoming direct messages
      * @returns Unsubscribe function
      */
-    onTypingIndicator?(handler: TypingIndicatorHandler): () => void;
+    onMessage(handler: MessageHandler): () => void;
     /**
-     * Send composing indicator to a recipient using NIP-44 encrypted gift wrap
-     * @param recipientTransportPubkey - Transport pubkey of the conversation partner
-     * @param content - JSON payload with senderNametag and expiresIn
+     * Send token transfer payload
+     * @param recipientTransportPubkey - Transport-specific pubkey for messaging
+     * @returns Event ID
      */
-    sendComposingIndicator?(recipientTransportPubkey: string, content: string): Promise<void>;
+    sendTokenTransfer(recipientTransportPubkey: string, payload: TokenTransferPayload): Promise<string>;
     /**
-     * Subscribe to incoming composing indicators
+     * Subscribe to incoming token transfers
      * @returns Unsubscribe function
      */
-    onComposing?(handler: ComposingHandler): () => void;
+    onTokenTransfer(handler: TokenTransferHandler): () => void;
     /**
-     * Get list of configured relay URLs
+     * Resolve any identifier to full peer information.
+     * Accepts @nametag, bare nametag, DIRECT://, chain pubkey, or transport pubkey.
+     * @param identifier - Any supported identifier format
+     * @returns PeerInfo or null if not found
      */
-    getRelays?(): string[];
+    resolve?(identifier: string): Promise<PeerInfo | null>;
     /**
-     * Get list of currently connected relay URLs
+     * Resolve nametag to public key
      */
-    getConnectedRelays?(): string[];
+    resolveNametag?(nametag: string): Promise<string | null>;
     /**
-     * Add a relay dynamically
-     * @returns true if added successfully
+     * Resolve nametag to full peer information
+     * Returns transportPubkey, chainPubkey, directAddress
      */
-    addRelay?(relayUrl: string): Promise<boolean>;
+    resolveNametagInfo?(nametag: string): Promise<PeerInfo | null>;
     /**
-     * Remove a relay dynamically
-     * @returns true if removed successfully
+     * Resolve a DIRECT:// or PROXY:// address to full peer info.
+     * Performs reverse lookup: address → binding event → PeerInfo.
+     * @param address - L3 address (DIRECT://... or PROXY://...)
+     * @returns PeerInfo or null if no binding found for this address
      */
-    removeRelay?(relayUrl: string): Promise<boolean>;
+    resolveAddressInfo?(address: string): Promise<PeerInfo | null>;
     /**
-     * Check if a relay is configured
+     * Resolve transport pubkey to full peer info.
+     * Queries binding events authored by the given transport pubkey.
+     * @param transportPubkey - Transport-specific pubkey (e.g. 64-char hex string)
+     * @returns PeerInfo or null if no binding found
      */
-    hasRelay?(relayUrl: string): boolean;
+    resolveTransportPubkeyInfo?(transportPubkey: string): Promise<PeerInfo | null>;
     /**
-     * Check if a relay is currently connected
+     * Batch-resolve multiple transport pubkeys to peer info.
+     * Used for HD address discovery: derives transport pubkeys for indices 0..N
+     * and queries binding events in a single batch.
+     * @param transportPubkeys - Array of transport-specific pubkeys to look up
+     * @returns Array of PeerInfo for pubkeys that have binding events (may be shorter than input)
      */
-    isRelayConnected?(relayUrl: string): boolean;
+    discoverAddresses?(transportPubkeys: string[]): Promise<PeerInfo[]>;
     /**
-     * Set fallback 'since' timestamp for event subscriptions.
-     * Used when switching to an address that has never subscribed before.
-     * The transport uses this instead of 'now' as the initial since filter,
-     * ensuring events sent while the address was inactive are not missed.
-     * Consumed once by the next subscription setup, then cleared.
-     *
-     * @param sinceSeconds - Unix timestamp in seconds
+     * Recover nametag for current identity by decrypting stored encrypted nametag
+     * Used after wallet import to recover associated nametag
+     * @returns Decrypted nametag or null if none found
      */
-    setFallbackSince?(sinceSeconds: number): void;
+    recoverNametag?(): Promise<string | null>;
     /**
-     * Set fallback 'since' timestamp for DM (gift-wrap) subscriptions.
-     * Used when no persisted DM timestamp exists in storage (e.g. first connect).
-     * Consumed once by the next subscription setup, then cleared.
-     *
-     * @param sinceSeconds - Unix timestamp in seconds
+     * Publish identity binding event.
+     * Without nametag: publishes base binding (chainPubkey, directAddress).
+     * With nametag: adds nametag hash, proxy address, encrypted nametag for recovery.
+     * Uses parameterized replaceable event (kind 30078, d=hash(nostrPubkey)).
+     * @returns true if successful, false if nametag is taken by another pubkey
      */
-    setFallbackDmSince?(sinceSeconds: number): void;
+    publishIdentityBinding?(chainPubkey: string, directAddress: string, nametag?: string): Promise<boolean>;
     /**
-     * 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).
+     * Subscribe to broadcast messages (global/channel)
      */
-    fetchPendingEvents?(): Promise<void>;
+    subscribeToBroadcast?(tags: string[], handler: BroadcastHandler): () => void;
     /**
-     * Register a handler to be called when the chat subscription receives EOSE
-     * (End Of Stored Events), indicating that historical DMs have been delivered.
-     * The handler fires at most once per subscription lifecycle.
-     *
-     * @returns Unsubscribe function
+     * Publish broadcast message
      */
-    onChatReady?(handler: () => void): () => void;
-}
-interface IncomingMessage {
-    id: string;
-    /** Transport-specific pubkey of sender */
-    senderTransportPubkey: string;
-    /** Sender's nametag (if known from NIP-17 unwrap) */
-    senderNametag?: string;
-    content: string;
-    timestamp: number;
-    encrypted: boolean;
-    /** Set when this is a self-wrap replay (sent message recovered from relay) */
-    isSelfWrap?: boolean;
-    /** Recipient pubkey — only present on self-wrap replays */
-    recipientTransportPubkey?: string;
-}
-type MessageHandler = (message: IncomingMessage) => void;
-interface TokenTransferPayload {
-    /** Serialized token data */
-    token: string;
-    /** Inclusion proof */
-    proof: unknown;
-    /** Optional memo */
-    memo?: string;
-    /** Sender info */
-    sender?: {
-        /** Transport-specific pubkey */
-        transportPubkey: string;
-        nametag?: string;
-    };
-}
-interface IncomingTokenTransfer {
-    id: string;
-    /** Transport-specific pubkey of sender */
-    senderTransportPubkey: string;
-    payload: TokenTransferPayload;
-    timestamp: number;
-}
-type TokenTransferHandler = (transfer: IncomingTokenTransfer) => void | Promise<void>;
-interface PaymentRequestPayload {
-    /** Amount requested (in smallest units) */
-    amount: string | bigint;
-    /** Coin/token type ID */
-    coinId: string;
-    /** Message/memo for recipient */
-    message?: string;
-    /** Recipient's nametag (who should pay) */
-    recipientNametag?: string;
-    /** Custom metadata */
-    metadata?: Record<string, unknown>;
-}
-interface IncomingPaymentRequest$1 {
-    /** Event ID */
-    id: string;
-    /** Transport-specific pubkey of sender */
-    senderTransportPubkey: string;
-    /** Sender's nametag (if included in encrypted content) */
-    senderNametag?: string;
-    /** Parsed request data */
-    request: {
-        requestId: string;
-        amount: string;
-        coinId: string;
-        message?: string;
-        recipientNametag?: string;
-        metadata?: Record<string, unknown>;
-    };
-    /** Timestamp */
-    timestamp: number;
-}
-type PaymentRequestHandler$1 = (request: IncomingPaymentRequest$1) => void;
-type PaymentRequestResponseType$1 = 'accepted' | 'rejected' | 'paid';
-interface PaymentRequestResponsePayload {
-    /** Original request ID */
-    requestId: string;
-    /** Response type */
-    responseType: PaymentRequestResponseType$1;
-    /** Optional message */
-    message?: string;
-    /** Transfer ID (if paid) */
-    transferId?: string;
-}
-interface IncomingPaymentRequestResponse {
-    /** Event ID */
-    id: string;
-    /** Transport-specific pubkey of responder */
-    responderTransportPubkey: string;
-    /** Parsed response data */
-    response: {
-        requestId: string;
-        responseType: PaymentRequestResponseType$1;
-        message?: string;
-        transferId?: string;
-    };
-    /** Timestamp */
-    timestamp: number;
-}
-type PaymentRequestResponseHandler$1 = (response: IncomingPaymentRequestResponse) => void;
-interface IncomingBroadcast {
-    id: string;
-    /** Transport-specific pubkey of author */
-    authorTransportPubkey: string;
-    content: string;
-    tags: string[];
-    timestamp: number;
-}
-type BroadcastHandler = (broadcast: IncomingBroadcast) => void;
-type TransportEventType = 'transport:connected' | 'transport:disconnected' | 'transport:reconnecting' | 'transport:error' | 'transport:relay_added' | 'transport:relay_removed' | 'message:received' | 'message:sent' | 'transfer:received' | 'transfer:sent';
-interface TransportEvent {
-    type: TransportEventType;
-    timestamp: number;
-    data?: unknown;
-    error?: string;
-}
-type TransportEventCallback = (event: TransportEvent) => void;
-/**
- * Resolved peer identity information.
- * Returned by resolve methods — contains all public address formats for a peer.
- * The nametag field is optional (only present if a nametag is registered).
- */
-interface PeerInfo {
-    /** Nametag name (without @), if registered */
-    nametag?: string;
-    /** Transport-specific pubkey (for messaging/encryption) */
-    transportPubkey: string;
-    /** 33-byte compressed secp256k1 public key (for L3 chain) */
-    chainPubkey: string;
-    /** L3 DIRECT address (DIRECT://...) */
-    directAddress: string;
-    /** Event timestamp */
-    timestamp: number;
-}
-interface IncomingReadReceipt {
-    /** Transport-specific pubkey of the sender who read the message */
-    senderTransportPubkey: string;
-    /** Event ID of the message that was read */
-    messageEventId: string;
-    /** Timestamp */
-    timestamp: number;
-}
-type ReadReceiptHandler = (receipt: IncomingReadReceipt) => void;
-interface IncomingTypingIndicator {
-    /** Transport-specific pubkey of the sender who is typing */
-    senderTransportPubkey: string;
-    /** Sender's nametag (if known) */
-    senderNametag?: string;
-    /** Timestamp */
-    timestamp: number;
-}
-type TypingIndicatorHandler = (indicator: IncomingTypingIndicator) => void;
-type ComposingHandler = (indicator: ComposingIndicator) => void;
-
-/**
- * transport/delivery-provider.ts — the `DeliveryProvider` port (sdk-changes S7,
- * covenant §3.1-6).
- *
- * The seam that keeps the delivery rail swappable. In Unicity, a transfer —
- * after certification — is just a file handoff, so the port is deliberately
- * tiny: hand a finished token blob to a recipient, pull incoming deliveries,
- * acknowledge them. `WalletApiMailboxProvider`
- * (impl/shared/wallet-api/WalletApiMailboxProvider.ts) is the reference
- * implementation; anything that can move a file can implement it (the port
- * shape must not preclude the old Nostr transport or a future federated
- * transport — neither is a deliverable here).
- *
- * Normative shapes (sdk-changes S7):
- * - `DeliveryReceipt = { deliveryId }`
- * - `IncomingDelivery = { deliveryId, transferId?, senderPubkey?, memo?,
- *   fetchBlob(), cursor }`
- * - `deliveryId` is the **content-derived** entry id —
- *   `hex(SHA-256(tokenId bytes ‖ stateHash bytes))` — NEVER a server-assigned
- *   row id or seq (covenant §3.1-4; the contract suite asserts it). It is
- *   computed client-side ({@link computeDeliveryId}) and must equal the
- *   backend's `entry_id` (ARCHITECTURE §6).
- * - **Custody is a composition-time property, not a per-call flag**:
- *   implementations take `custody: 'inventory' | 'external'` at construction
- *   and every ack sends the corresponding `intoInventory` — delivery-only
- *   safety must never depend on remembering an option at a call site.
- * - Implementations MUST keep a **persistent `(tokenId, stateHash)` seen-set**
- *   for incoming deliveries: the recipient-side replay guard is part of the
- *   port contract, not a server promise (the recipient never trusts the
- *   backend — ARCHITECTURE §8.2). `deliveryId` is the canonical hash encoding
- *   of exactly that pair, so a persistent deliveryId set satisfies this.
- */
-/** Receipt for a delivered blob. `deliveryId` is content-derived — see module doc. */
-interface DeliveryReceipt {
-    deliveryId: string;
-}
-/** Options for {@link DeliveryProvider.deliver}. */
-interface DeliverOptions {
+    publishBroadcast?(content: string, tags?: string[]): Promise<string>;
     /**
-     * The send's transferId (the E.3 intent id / realization seed). Recorded
-     * with the delivery so the recipient can group multi-token payments and the
-     * backend can evidence-check the sender's removals (ARCHITECTURE §5.3/§6).
+     * Send payment request to a recipient
+     * @param recipientTransportPubkey - Transport-specific pubkey for messaging
+     * @returns Event ID
      */
-    transferId: string;
-    /** Optional human memo. Implementations encrypt it client-side (S6). */
-    memo?: string;
+    sendPaymentRequest?(recipientTransportPubkey: string, request: PaymentRequestPayload): Promise<string>;
     /**
-     * The SENDER's own nametag (without a leading `@`), so the recipient can
-     * render the human identity instead of a raw pubkey ("Someone"). Bundled
-     * with the memo into ONE recipient-addressed (ECDH) `enc1.` envelope (S6) —
-     * the operator never sees it. Attached whenever the sender has a nametag OR
-     * a memo (so the nametag travels even on a memo-less transfer).
+     * Subscribe to incoming payment requests
+     * @returns Unsubscribe function
      */
-    senderNametag?: string;
-}
-/** One incoming delivery pulled from the feed. */
-interface IncomingDelivery {
-    /** Content-derived id — `hex(SHA-256(tokenId bytes ‖ stateHash bytes))`. */
-    deliveryId: string;
-    /** The sender's transferId, when the transport carries it. */
-    transferId?: string;
-    /** The sender's pubkey, when the transport carries it. */
-    senderPubkey?: string;
-    /** Decrypted memo (S6), when present and decryptable. */
-    memo?: string;
+    onPaymentRequest?(handler: PaymentRequestHandler$1): () => void;
     /**
-     * The sender's nametag (without a leading `@`), decrypted from the same
-     * recipient-addressed delivery envelope as {@link memo} (S6). Lets the
-     * receiver render the human identity instead of a raw pubkey, with no
-     * Nostr/transport lookup. Absent when the envelope carried none or could
-     * not be decrypted.
+     * Send response to a payment request
+     * @param recipientTransportPubkey - Transport-specific pubkey for messaging
+     * @returns Event ID
      */
-    senderNametag?: string;
-    /** Fetch the finished token blob bytes (the encoded TokenBlob). */
-    fetchBlob(): Promise<Uint8Array>;
-    /** Transport-local resume cursor (opaque to callers). */
-    cursor: string;
-}
-type DeliveryDisposition = 'claimed' | 'rejected';
-/**
- * The §9 wake streams a backend may nudge: `mailbox` (incoming deliveries),
- * `inventory` (owned-token set changed — e.g. a top-up or a claim on another
- * device), and `payment_requests` (a request created/answered). A wake on any
- * of these is a NUDGE — the consumer pulls that stream's cursor; correctness
- * never depends on the wake arriving (the poll backstop is the source of
- * truth).
- */
-type WakeStream = 'inventory' | 'mailbox' | 'payment_requests';
-/**
- * True liveness of the realtime wake channel (§9), decoupled from sign-in
- * session state: `connecting`/`connected` — a socket is (being) established;
- * `reconnecting` — it dropped and is backing off to re-establish (the poll
- * backstop carries correctness meanwhile); `closed` — torn down intentionally.
- * The wake is a nudge, so this is informational for the frontend (a "live"
- * indicator) — never a correctness gate.
- */
-type WakeChannelStatus = 'connecting' | 'connected' | 'reconnecting' | 'closed';
-/**
- * Custody mode (composition-time): `'inventory'` — acknowledged deliveries
- * enter the wallet-api inventory (the full wallet-api preset); `'external'` —
- * the app's own storage keeps custody and acks perform ZERO inventory writes
- * (the delivery-only preset, ARCHITECTURE §6 "delivery-only claim").
- */
-type DeliveryCustody = 'inventory' | 'external';
-interface DeliveryProvider {
-    /** Composition-time custody property — never a per-call flag (S7). */
-    readonly custody: DeliveryCustody;
+    sendPaymentRequestResponse?(recipientTransportPubkey: string, response: PaymentRequestResponsePayload): Promise<string>;
     /**
-     * Bind the wallet identity (optional — implementations that authenticate or
-     * encrypt per-wallet need it; mirrors `TokenStorageProvider.setIdentity`).
+     * Subscribe to incoming payment request responses
+     * @returns Unsubscribe function
      */
-    setIdentity?(identity: {
-        privateKey: string;
-        chainPubkey: string;
-    }): void;
+    onPaymentRequestResponse?(handler: PaymentRequestResponseHandler$1): () => void;
     /**
-     * #583 per-address client isolation: mint an INDEPENDENT delivery provider for
-     * a different HD address, backed by its OWN authenticated client + wake socket
-     * (mirrors `TokenStorageProvider.createForAddress`). Implementations that hold
-     * a single mutable identity+session per instance (e.g. the wallet-api mailbox
-     * over one `WalletApiClient`) provide this so `Sphere.switchToAddress` can give
-     * each address its OWN delivery instance — an orphaned previous-address pump
-     * then re-auths as ITS OWN owner (harmless) instead of driving a client that
-     * was re-bound to the new owner. Stateless transports may omit it (the same
-     * instance serves every address).
+     * Send a read receipt for a message
+     * @param recipientTransportPubkey - Transport pubkey of the message sender
+     * @param messageEventId - Event ID of the message being acknowledged
      */
-    createForAddress?(): DeliveryProvider;
+    sendReadReceipt?(recipientTransportPubkey: string, messageEventId: string): Promise<void>;
     /**
-     * Hand a finished token blob to a recipient. `recipientPubkey` is the
-     * recipient's CHAIN pubkey (33-byte compressed secp256k1, hex) — the
-     * canonical Unicity identity (ARCHITECTURE §4); transports that address
-     * recipients differently resolve it themselves.
-     *
-     * MUST be idempotent per (token, state): re-delivering the same finished
-     * blob — including after the recipient claimed — succeeds and returns the
-     * same content-derived `deliveryId` (ARCHITECTURE §6 deposit idempotency).
+     * Subscribe to incoming read receipts
+     * @returns Unsubscribe function
      */
-    deliver(recipientPubkey: string, blob: Uint8Array, options: DeliverOptions): Promise<DeliveryReceipt>;
+    onReadReceipt?(handler: ReadReceiptHandler): () => void;
     /**
-     * Pull-based feed of incoming deliveries since the given transport-local
-     * cursor (or the provider's persisted cursor when omitted). Yields only
-     * deliveries not yet in the persistent seen-set; completes when the feed is
-     * drained — callers re-invoke on poll/wake. Feeds the existing
-     * transport-agnostic `handleV2Transfer` (sdk-changes S3).
+     * Send typing indicator to a recipient
+     * @param recipientTransportPubkey - Transport pubkey of the conversation partner
      */
-    incoming(sinceCursor?: string): AsyncIterable<IncomingDelivery>;
+    sendTypingIndicator?(recipientTransportPubkey: string): Promise<void>;
     /**
-     * Acknowledge a delivery: `'claimed'` accepts it (with the provider's
-     * composition-time custody), `'rejected'` marks it locally-unverifiable —
-     * terminal for discovery only (the entry stays claimable server-side and
-     * its blob is retained — ARCHITECTURE §6). Both record the delivery in the
-     * persistent seen-set.
+     * Subscribe to incoming typing indicators
+     * @returns Unsubscribe function
      */
-    ack(deliveryId: string, disposition: DeliveryDisposition): Promise<void>;
+    onTypingIndicator?(handler: TypingIndicatorHandler): () => void;
     /**
-     * Optional batch acknowledge (#623): claim and reject whole pages of incoming deliveries in a
-     * single request each, instead of one per entry — so draining a large inbox (a long-offline or
-     * service wallet) doesn't fire thousands of writes and trip the per-owner rate limit. Same
-     * semantics as {@link ack}: the seen-set records only entries that were acked successfully, so a
-     * partial/failed batch is re-listed and re-processed (idempotent claim, §6). A provider that does
-     * not implement it (e.g. the relay no-op) is driven via per-entry {@link ack}.
+     * Send composing indicator to a recipient using NIP-44 encrypted gift wrap
+     * @param recipientTransportPubkey - Transport pubkey of the conversation partner
+     * @param content - JSON payload with senderNametag and expiresIn
      */
-    ackBatch?(claimed: string[], rejected: string[]): Promise<void>;
+    sendComposingIndicator?(recipientTransportPubkey: string, content: string): Promise<void>;
     /**
-     * Optional batch deliver (#699): hand N finished blobs to ONE recipient with a single deposit
-     * request (and one upload-urls request) instead of N — a multi-source send then costs O(1)
-     * against the backend's deposit rate limit regardless of fragmentation. Optional like
-     * {@link ackBatch}: the port must not preclude the relay transport or a future federated one,
-     * and neither has a batch primitive — callers probe and fall back to per-blob {@link deliver}.
+     * Subscribe to incoming composing indicators
+     * @returns Unsubscribe function
+     */
+    onComposing?(handler: ComposingHandler): () => void;
+    /**
+     * Get list of configured relay URLs
+     */
+    getRelays?(): string[];
+    /**
+     * Get list of currently connected relay URLs
+     */
+    getConnectedRelays?(): string[];
+    /**
+     * Add a relay dynamically
+     * @returns true if added successfully
+     */
+    addRelay?(relayUrl: string): Promise<boolean>;
+    /**
+     * Remove a relay dynamically
+     * @returns true if removed successfully
+     */
+    removeRelay?(relayUrl: string): Promise<boolean>;
+    /**
+     * Check if a relay is configured
+     */
+    hasRelay?(relayUrl: string): boolean;
+    /**
+     * Check if a relay is currently connected
+     */
+    isRelayConnected?(relayUrl: string): boolean;
+    /**
+     * Set fallback 'since' timestamp for event subscriptions.
+     * Used when switching to an address that has never subscribed before.
+     * The transport uses this instead of 'now' as the initial since filter,
+     * ensuring events sent while the address was inactive are not missed.
+     * Consumed once by the next subscription setup, then cleared.
      *
-     * Semantically equivalent to awaiting {@link deliver} once per blob, in order:
-     * - receipts return in REQUEST order; each `deliveryId` is the content-derived entry id
-     *   (covenant §3.1-4 — NEVER the batch endpoint's server-assigned seq);
-     * - idempotent per (token, state) exactly like {@link deliver};
-     * - `options` apply to every blob (one send = one transferId/memo/senderNametag);
-     * - throws when ANY blob could not be deposited — blobs that DID land are absorbed
-     *   idempotently when the caller retries, batched or per-blob.
+     * @param sinceSeconds - Unix timestamp in seconds
      */
-    deliverBatch?(recipientPubkey: string, blobs: Uint8Array[], options: DeliverOptions): Promise<DeliveryReceipt[]>;
+    setFallbackSince?(sinceSeconds: number): void;
     /**
-     * Optional wake hook: `callback` fires with the {@link WakeStream} that was
-     * nudged when new data may be available on it (e.g. a WS nudge — never a
-     * correctness dependency, ARCHITECTURE §9). The wallet-api wake socket
-     * multiplexes all three owner streams (`mailbox` | `inventory` |
-     * `payment_requests`); the consumer routes each to that stream's pull.
+     * Set fallback 'since' timestamp for DM (gift-wrap) subscriptions.
+     * Used when no persisted DM timestamp exists in storage (e.g. first connect).
+     * Consumed once by the next subscription setup, then cleared.
      *
-     * The underlying socket SELF-HEALS (§9): it reconnects with backoff on any
-     * drop and a liveness watchdog force-reconnects a half-open socket. On every
-     * (re)connect the consumer MUST run a full catch-up pull of every stream —
-     * wakes missed while the socket was dead are not replayed — so `callback`
-     * fires once for EACH stream on (re)connect (a synthetic catch-up nudge).
-     * `onStatus` (optional) surfaces true socket liveness for the frontend,
-     * decoupled from sign-in state. Returns an unsubscribe function.
+     * @param sinceSeconds - Unix timestamp in seconds
      */
-    onWake?(callback: (stream: WakeStream) => void, onStatus?: (status: WakeChannelStatus) => void): () => void;
+    setFallbackDmSince?(sinceSeconds: number): void;
     /**
-     * Late-bind the backend-true (tokenId, stateHash) derivation —
-     * `ITokenEngine.deliveryKeys`. Compositions are engine-less (the engine is
-     * built later); the module that owns both (PaymentsModule) binds this at
-     * init. Implementations that derive ids (S7) MUST use it and fail loudly if
-     * unbound; transports that don't derive may omit the method.
+     * 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).
      */
-    bindDeliveryKeys?(derive: (blobBytes: Uint8Array) => Promise<{
-        tokenId: string;
-        stateHash: string;
-    }>): void;
+    fetchPendingEvents?(): Promise<void>;
+    /**
+     * Register a handler to be called when the chat subscription receives EOSE
+     * (End Of Stored Events), indicating that historical DMs have been delivered.
+     * The handler fires at most once per subscription lifecycle.
+     *
+     * @returns Unsubscribe function
+     */
+    onChatReady?(handler: () => void): () => void;
+}
+interface IncomingMessage {
+    id: string;
+    /** Transport-specific pubkey of sender */
+    senderTransportPubkey: string;
+    /** Sender's nametag (if known from NIP-17 unwrap) */
+    senderNametag?: string;
+    content: string;
+    timestamp: number;
+    encrypted: boolean;
+    /** Set when this is a self-wrap replay (sent message recovered from relay) */
+    isSelfWrap?: boolean;
+    /** Recipient pubkey — only present on self-wrap replays */
+    recipientTransportPubkey?: string;
+}
+type MessageHandler = (message: IncomingMessage) => void;
+interface TokenTransferPayload {
+    /** Serialized token data */
+    token: string;
+    /** Inclusion proof */
+    proof: unknown;
+    /** Optional memo */
+    memo?: string;
+    /** Sender info */
+    sender?: {
+        /** Transport-specific pubkey */
+        transportPubkey: string;
+        nametag?: string;
+    };
 }
-/**
- * The content-derived delivery id:
- * `hex(SHA-256(tokenId bytes ‖ stateHash bytes))` — identical to the
- * backend's `entry_id` (ARCHITECTURE §6), computed client-side so no
- * implementation can substitute a server row id (covenant §3.1-4).
- *
- * @param tokenIdHex - genesis-stable 64-hex token id
- * @param stateHashHex - the SDK's per-state hash (DataHash imprint, hex) — the
- *   backend's `state_hash` (wallet-api validation/chain.ts); NEVER a plain
- *   sha256 over the token bytes (that variant 422s on deposit).
- */
-declare function computeDeliveryId(tokenIdHex: string, stateHashHex: string): string;
-/** Full delivery keys: the engine-derived pair + the composed deliveryId. */
-interface DeliveryBlobKeys {
-    /** Genesis-stable 64-hex token id (from the TokenBlob envelope). */
-    tokenId: string;
-    /** Per-state hash: `hex(SHA-256(inner token bytes))` — changes every transfer. */
-    stateHash: string;
-    /** {@link computeDeliveryId} of the two above. */
-    deliveryId: string;
+interface IncomingTokenTransfer {
+    id: string;
+    /** Transport-specific pubkey of sender */
+    senderTransportPubkey: string;
+    payload: TokenTransferPayload;
+    timestamp: number;
 }
+type TokenTransferHandler = (transfer: IncomingTokenTransfer) => void | Promise<void>;
+interface PaymentRequestPayload {
+    /** Amount requested (in smallest units) */
+    amount: string | bigint;
+    /** Coin/token type ID */
+    coinId: string;
+    /** Message/memo for recipient */
+    message?: string;
+    /** Recipient's nametag (who should pay) */
+    recipientNametag?: string;
+    /** Custom metadata */
+    metadata?: Record<string, unknown>;
+}
+interface IncomingPaymentRequest$1 {
+    /** Event ID */
+    id: string;
+    /** Transport-specific pubkey of sender */
+    senderTransportPubkey: string;
+    /** Sender's nametag (if included in encrypted content) */
+    senderNametag?: string;
+    /** Parsed request data */
+    request: {
+        requestId: string;
+        amount: string;
+        coinId: string;
+        message?: string;
+        recipientNametag?: string;
+        metadata?: Record<string, unknown>;
+    };
+    /** Timestamp */
+    timestamp: number;
+}
+type PaymentRequestHandler$1 = (request: IncomingPaymentRequest$1) => void;
+type PaymentRequestResponseType$1 = 'accepted' | 'rejected' | 'paid';
+interface PaymentRequestResponsePayload {
+    /** Original request ID */
+    requestId: string;
+    /** Response type */
+    responseType: PaymentRequestResponseType$1;
+    /** Optional message */
+    message?: string;
+    /** Transfer ID (if paid) */
+    transferId?: string;
+}
+interface IncomingPaymentRequestResponse {
+    /** Event ID */
+    id: string;
+    /** Transport-specific pubkey of responder */
+    responderTransportPubkey: string;
+    /** Parsed response data */
+    response: {
+        requestId: string;
+        responseType: PaymentRequestResponseType$1;
+        message?: string;
+        transferId?: string;
+    };
+    /** Timestamp */
+    timestamp: number;
+}
+type PaymentRequestResponseHandler$1 = (response: IncomingPaymentRequestResponse) => void;
+interface IncomingBroadcast {
+    id: string;
+    /** Transport-specific pubkey of author */
+    authorTransportPubkey: string;
+    content: string;
+    tags: string[];
+    timestamp: number;
+}
+type BroadcastHandler = (broadcast: IncomingBroadcast) => void;
+type TransportEventType = 'transport:connected' | 'transport:disconnected' | 'transport:reconnecting' | 'transport:error' | 'transport:relay_added' | 'transport:relay_removed' | 'message:received' | 'message:sent' | 'transfer:received' | 'transfer:sent';
+interface TransportEvent {
+    type: TransportEventType;
+    timestamp: number;
+    data?: unknown;
+    error?: string;
+}
+type TransportEventCallback = (event: TransportEvent) => void;
 /**
- * Derive (tokenId, stateHash, deliveryId) from encoded TokenBlob bytes.
- * Throws when the bytes are not a decodable TokenBlob.
- */
-/**
- * Compose full delivery keys from an engine-derived (tokenId, stateHash) pair.
- * The pair MUST come from `ITokenEngine.deliveryKeys` (the backend-true SDK
- * derivation) — the port module deliberately cannot decode tokens itself.
+ * Resolved peer identity information.
+ * Returned by resolve methods — contains all public address formats for a peer.
+ * The nametag field is optional (only present if a nametag is registered).
  */
-declare function composeDeliveryKeys(keys: {
-    tokenId: string;
-    stateHash: string;
-}): DeliveryBlobKeys;
+interface PeerInfo {
+    /** Nametag name (without @), if registered */
+    nametag?: string;
+    /** Transport-specific pubkey (for messaging/encryption) */
+    transportPubkey: string;
+    /** 33-byte compressed secp256k1 public key (for L3 chain) */
+    chainPubkey: string;
+    /** L3 DIRECT address (DIRECT://...) */
+    directAddress: string;
+    /** Event timestamp */
+    timestamp: number;
+}
+interface IncomingReadReceipt {
+    /** Transport-specific pubkey of the sender who read the message */
+    senderTransportPubkey: string;
+    /** Event ID of the message that was read */
+    messageEventId: string;
+    /** Timestamp */
+    timestamp: number;
+}
+type ReadReceiptHandler = (receipt: IncomingReadReceipt) => void;
+interface IncomingTypingIndicator {
+    /** Transport-specific pubkey of the sender who is typing */
+    senderTransportPubkey: string;
+    /** Sender's nametag (if known) */
+    senderNametag?: string;
+    /** Timestamp */
+    timestamp: number;
+}
+type TypingIndicatorHandler = (indicator: IncomingTypingIndicator) => void;
+type ComposingHandler = (indicator: ComposingIndicator) => void;
 
 /**
  * Price Provider Interface
@@ -1813,22 +1836,6 @@ declare function createPriceProvider(config: PriceProviderConfig): PriceProvider
  * Single source of truth: {@link HistoryRecord} in `storage/storage-provider.ts`.
  */
 type TransactionHistoryEntry = HistoryRecord;
-/**
- * @deprecated v2 transfers arrive as finished tokens — there is no finalization
- * phase. The options are accepted for backwards compatibility and ignored.
- */
-interface ReceiveOptions {
-    /** @deprecated Ignored — v2 tokens are stored confirmed on receipt. */
-    finalize?: boolean;
-    /** @deprecated Ignored. */
-    timeout?: number;
-    /** @deprecated Ignored. */
-    pollInterval?: number;
-}
-interface ReceiveResult {
-    /** Newly received incoming transfers. */
-    transfers: IncomingTransfer[];
-}
 interface PaymentsModuleConfig {
     /** Auto-sync after operations */
     autoSync?: boolean;
@@ -2062,15 +2069,17 @@ declare class PaymentsModule {
     private readonly moduleConfig;
     private deps;
     private tokens;
-    private tombstones;
-    private tombstoneKeySet;
-    private _historyCache;
     private nametags;
-    private paymentRequests;
-    private paymentRequestHandlers;
-    private outgoingPaymentRequests;
-    private paymentRequestResponseHandlers;
-    private pendingResponseResolvers;
+    /** Inventory reads: balances/assets, the token accessors, tombstones, validate(). */
+    private readonly inventory;
+    /** Payment requests (incoming + outgoing, the S4 pump, the #441 journal). */
+    private readonly requests;
+    /** Transaction history (the cache, the dedupKey rules, the §10 server log). */
+    private readonly history;
+    /** E.3/E.4 intent resume (the sign-in replay of OPEN send intents). */
+    private readonly intents;
+    /** Receive + delivery (receive(), the v2 receiver, the journal, the replay budget). */
+    private readonly deliveries;
     /** The single delivery seam — an injected provider or the transport adapter. */
     private delivery;
     /** Set only when a provider was INJECTED — gates the incoming pump (S3). */
@@ -2087,35 +2096,6 @@ declare class PaymentsModule {
     /** S6 field-encryption key (intent payloads, history memos) — per identity. */
     private fieldEncryptionKey;
     private checkpointStore;
-    private prPollTimer;
-    /** Coalesces concurrent payment-request pump runs. */
-    private prPumpInFlight;
-    /**
-     * Set after the once-per-session full incoming hydration (#556): the surfaced
-     * incoming list is in-memory only, so on a fresh engine the CURRENT state of
-     * ALL incoming requests — open AND resolved (paid/declined/expired) — must be
-     * rebuilt from a `role=incoming&since=0` pull, not just the still-open ones.
-     * A status-filtered bootstrap (the pre-#556 `status=open` scan) dropped
-     * requests resolved in a PRIOR session, so the payer reopened and the
-     * 'Paid Successfully' request was gone (twin of #521/#549).
-     */
-    private prBootstrapped;
-    /**
-     * #441 deferred-paid journal (durable, per network+identity): links a payment
-     * request to the in-flight transfer of a possibly-committed pay so the request
-     * is held NON-payable ('settling') until that transfer completes (→ 'paid',
-     * server told) or aborts (→ payable, journal cleared). Keyed by request wire id
-     * (== requestId for wallet-api-surfaced requests). The in-memory Map is the
-     * synchronous source of truth used by the reload re-apply seam; it is
-     * single-flight loaded and every read-modify-write is serialized through a tail
-     * promise (the #679/#680 lesson: an unserialized RMW drops entries under
-     * concurrency = a re-payable request = the double-pay this fix prevents).
-     */
-    private settlingJournal;
-    private settlingJournalLoad;
-    private settlingJournalWrite;
-    /** #441: guard overlapping resume reconciles (resumeOpenIntents has 2 fire-and-forget call sites). */
-    private reconcileInFlight;
     private loadedPromise;
     private loaded;
     /**
@@ -2132,20 +2112,6 @@ declare class PaymentsModule {
     private loadInFlightOwner;
     private loadRerunRequested;
     private loadRerunTimer;
-    /**
-     * Owner (chainPubkey) whose server history hydration last completed —
-     * enables the #642 incremental fast path in {@link hydrateHistoryFromServer}.
-     * Reset on re-init (address switch). `serverSeenHistoryKeys` holds only
-     * dedupKeys actually PULLED from the server (never locally-POSTed ones), so
-     * the incremental stop condition can't be masked by our own fresh POSTs;
-     * `incrementalHistoryPulls` forces a periodic full re-pull to bound the
-     * staleness window if server keyset order ever diverges from arrival order.
-     * `hydrationEpoch` guards a pull racing a same-owner re-init.
-     */
-    private historyHydratedFor;
-    private serverSeenHistoryKeys;
-    private incrementalHistoryPulls;
-    private hydrationEpoch;
     private inventoryDebounceTimer;
     private static readonly SYNC_DEBOUNCE_MS;
     /** Quiet-then-escalate logging for the background wallet-api pumps (#630). */
@@ -2156,43 +2122,45 @@ declare class PaymentsModule {
     private tokenChangeCallbacks;
     private readonly reservationLedger;
     private readonly spendPlanner;
-    /**
-     * Per-request single-flight for {@link payPaymentRequest}. The pay flow flips the request to
-     * 'accepted' before it awaits send(), and the status guard re-admits 'accepted' (intended for a
-     * sequential retry-after-failure) — so a concurrent double-tap / second session would otherwise
-     * enter send() a second time and DOUBLE-PAY (each send picks a different token; the reservation
-     * ledger is coin-scoped, not request-scoped). Concurrent calls for the same requestId coalesce
-     * onto the first in-flight pay; the entry is cleared when it settles, so a later retry is unaffected.
-     */
-    private readonly payInFlight;
     private spendQueue;
     /** Cache of parsed SdkToken data for synchronous queue re-evaluation */
     private readonly parsedTokenCache;
+    constructor(config?: PaymentsModuleConfig);
     /**
-     * Base delay (ms) for the journaled-delivery replay backoff (#517 item 1).
-     * A field, not a const, so tests can drive the bounded retry loop without
-     * waiting real time — never mutated in production.
+     * The narrow seam {@link TokenView} reaches back through. Live getters for
+     * `deps` and `priceProvider` (both swapped on {@link initialize}); the token
+     * map is handed over as a READ-ONLY view, so the inventory view never becomes
+     * a second writer of it.
      */
-    private replayBackoffBaseMs;
-    /** Deferral window for recipient-quota (429) deliveries (#621). Overridable in tests. */
-    private deliveryDeferralMs;
+    private tokenViewHost;
     /**
-     * #517: serializes {@link replayPendingV2Deliveries}. `load()` kicks replay
-     * off fire-and-forget and `receive()` calls `load()`, so two passes can
-     * overlap — duplicating delivery attempts and clobbering each other's
-     * `attempts` increments (both read the same stale value, both write N+1,
-     * delaying poison surfacing). Only one pass runs per module instance at a time.
+     * The narrow seam {@link Delivery} reaches back through. Live getters for
+     * `deps` and `delivery` (both swapped on every {@link initialize}); the token
+     * map is handed over as a READ-ONLY view and written only by the module's own
+     * `storeEngineToken`, so delivery never becomes a second writer.
      */
-    private replayInFlight;
+    private deliveryHost;
     /**
-     * #517: serializes every read-modify-write of the PENDING_V2_DELIVERIES journal.
-     * save/remove/update each load → mutate → store the WHOLE blob, so a replay
-     * (fire-and-forget from load()) overlapping a send()'s journal write could
-     * clobber a newly-saved undelivered entry and lose it — defeating the crash-
-     * safety guarantee. A promise-chain mutex makes each whole RMW atomic.
+     * The narrow seam {@link PaymentRequests} reaches back through. Live getters,
+     * not a snapshot: `deps` is swapped on every {@link initialize} (address
+     * switch) and the feature must always observe the CURRENT one.
      */
-    private journalMutation;
-    constructor(config?: PaymentsModuleConfig);
+    private paymentRequestsHost;
+    /**
+     * The narrow seam {@link TransferHistory} reaches back through. Live getter
+     * for `deps` (swapped on every {@link initialize}); the rest are thunks onto
+     * the module's own private helpers — history never touches the token map or
+     * `save()`.
+     */
+    private transferHistoryHost;
+    /**
+     * The narrow seam {@link IntentResume} reaches back through. Live getters for
+     * `deps` and `delivery` (both swapped on every {@link initialize}); the rest
+     * are thunks onto the module's own helpers. The token map is READ through
+     * `getHeldToken` and written only by the module's `removeToken` /
+     * `storeEngineToken` — resume never becomes a second writer.
+     */
+    private intentResumeHost;
     /**
      * Get the current module configuration.
      *
@@ -2515,141 +2483,40 @@ declare class PaymentsModule {
      * fetched only when a token is selected to be spent.
      */
     private mergeLazyInventory;
-    /**
-     * Send a payment request to someone
-     * @param recipientPubkeyOrNametag - Recipient's pubkey or @nametag
-     * @param request - Payment request details
-     * @returns Result with event ID
-     */
+    /** Send a payment request to someone. @see PaymentRequests.sendPaymentRequest */
     sendPaymentRequest(recipientPubkeyOrNametag: string, request: Omit<PaymentRequest, 'id' | 'createdAt'>): Promise<PaymentRequestResult>;
-    /**
-     * S4: create the request via wallet-api (§16). The payer is addressed by
-     * CHAIN pubkey (the canonical identity); the memo is S6-encrypted client-
-     * side BEFORE it leaves the device (§8.3) — the operator stores ciphertext.
-     * Mirrors the transport path's no-throw contract: failures (including the
-     * §5.5 per-payer cap → 429) come back as `{ success: false, error }`.
-     */
-    private sendWalletApiPaymentRequest;
-    /**
-     * Subscribe to incoming payment requests
-     * @param handler - Handler function for incoming requests
-     * @returns Unsubscribe function
-     */
+    /** Subscribe to incoming payment requests. @see PaymentRequests.onPaymentRequest */
     onPaymentRequest(handler: PaymentRequestHandler): () => void;
-    /**
-     * Get all payment requests
-     * @param filter - Optional status filter
-     */
+    /** Get all payment requests. @see PaymentRequests.getPaymentRequests */
     getPaymentRequests(filter?: {
         status?: PaymentRequestStatus;
     }): IncomingPaymentRequest[];
-    /**
-     * Get the count of payment requests with status `'pending'`.
-     *
-     * @returns Number of pending incoming payment requests.
-     */
+    /** Count of incoming payment requests with status `'pending'`. @see PaymentRequests.getPendingPaymentRequestsCount */
     getPendingPaymentRequestsCount(): number;
-    /**
-     * 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 and notify the requester.
-     *
-     * On the wallet-api path (S4) the respond IS the state change — it is
-     * confirmed server-side (`action: 'declined'`, §16) before the local status
-     * flips, and a server rejection (403/409) propagates to the caller. The
-     * transport path is best-effort and never throws.
-     *
-     * @param requestId - ID of the incoming payment request to reject.
-     */
+    /** Reject a payment request and notify the requester. @see PaymentRequests.rejectPaymentRequest */
     rejectPaymentRequest(requestId: string): Promise<void>;
-    /**
-     * 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;
-    /**
-     * Remove resolved incoming payment requests from memory.
-     *
-     * Keeps requests with status `'pending'` OR `'settling'` (#441). A `'settling'`
-     * request is UNRESOLVED — its linked transfer is still in-flight — so evicting
-     * it would drop the in-memory hold that keeps it non-payable until the journal
-     * re-surfaces it. Only terminal statuses (`'paid'`/`'rejected'`/`'expired'`)
-     * are removed.
-     */
+    /** Remove resolved incoming payment requests from memory. @see PaymentRequests.clearProcessedPaymentRequests */
     clearProcessedPaymentRequests(): void;
-    /**
-     * Remove a specific incoming payment request by ID.
-     *
-     * @param requestId - ID of the payment request to remove.
-     */
+    /** Remove a specific incoming payment request by ID. @see PaymentRequests.removePaymentRequest */
     removePaymentRequest(requestId: string): void;
-    /**
-     * Pay a payment request directly
-     * Convenience method that accepts, sends, and marks as paid
-     */
+    /** Pay a payment request directly. @see PaymentRequests.payPaymentRequest */
     payPaymentRequest(requestId: string, memo?: string): Promise<TransferResult>;
-    private payPaymentRequestInner;
-    private updatePaymentRequestStatus;
-    /**
-     * Get outgoing payment requests
-     * @param filter - Optional status filter
-     */
+    /** Get outgoing payment requests. @see PaymentRequests.getOutgoingPaymentRequests */
     getOutgoingPaymentRequests(filter?: {
         status?: PaymentRequestStatus;
     }): OutgoingPaymentRequest[];
-    /**
-     * Subscribe to payment request responses (for outgoing requests)
-     * @param handler - Handler function for incoming responses
-     * @returns Unsubscribe function
-     */
+    /** Subscribe to payment request responses. @see PaymentRequests.onPaymentRequestResponse */
     onPaymentRequestResponse(handler: PaymentRequestResponseHandler): () => void;
-    /**
-     * Wait for a response to a payment request
-     * @param requestId - The outgoing request ID to wait for
-     * @param timeoutMs - Timeout in milliseconds (default: 60000)
-     * @returns Promise that resolves with the response or rejects on timeout
-     */
+    /** Wait for a response to a payment request. @see PaymentRequests.waitForPaymentResponse */
     waitForPaymentResponse(requestId: string, timeoutMs?: number): Promise<PaymentRequestResponse>;
-    /**
-     * 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.
-     */
+    /** Cancel an active {@link waitForPaymentResponse} call. @see PaymentRequests.cancelWaitForPaymentResponse */
     cancelWaitForPaymentResponse(requestId: string): void;
-    /**
-     * Remove an outgoing payment request and cancel any pending wait.
-     *
-     * @param requestId - ID of the outgoing request to remove.
-     */
+    /** Remove an outgoing payment request and cancel any pending wait. @see PaymentRequests.removeOutgoingPaymentRequest */
     removeOutgoingPaymentRequest(requestId: string): void;
-    /**
-     * Remove all outgoing payment requests that are `'paid'`, `'rejected'`, or `'expired'`.
-     */
+    /** Remove all `'paid'`/`'rejected'`/`'expired'` outgoing requests. @see PaymentRequests.clearCompletedOutgoingPaymentRequests */
     clearCompletedOutgoingPaymentRequests(): void;
-    /**
-     * Fold a payment-request response into the outgoing surface and notify —
-     * shared by the transport subscription and the wallet-api outgoing refresh
-     * (S4): update the matched outgoing request, resolve any
-     * {@link waitForPaymentResponse} waiter, emit the event, run the handlers.
-     */
-    private dispatchPaymentRequestResponse;
-    /**
-     * Send a response to a payment request (used internally by accept/reject/pay methods)
-     */
-    private sendPaymentRequestResponse;
+    /** Pull the wallet-api payment-request streams now (S4). @see PaymentRequests.syncPaymentRequests */
+    syncPaymentRequests(): Promise<void>;
     /**
      * Fetch and process pending incoming transfers from the transport layer.
      *
@@ -2663,6 +2530,7 @@ declare class PaymentsModule {
      * @param _options - Deprecated; the v1 finalization options are ignored.
      * @param callback - Optional callback invoked for each newly received transfer
      * @returns ReceiveResult with the newly received transfers
+     * @see Delivery.receive
      */
     receive(_options?: ReceiveOptions, callback?: (transfer: IncomingTransfer) => void): Promise<ReceiveResult>;
     /**
@@ -2672,6 +2540,8 @@ declare class PaymentsModule {
     /**
      * Get total portfolio value in USD.
      * Returns null if PriceProvider is not configured.
+     *
+     * @see TokenView.getFiatBalance
      */
     getFiatBalance(): Promise<number | null>;
     /**
@@ -2689,6 +2559,7 @@ declare class PaymentsModule {
      *
      * @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).
+     * @see TokenView.getBalance
      */
     getBalance(coinId?: string): Asset[];
     /**
@@ -2697,22 +2568,10 @@ declare class PaymentsModule {
      * (`'transferring'`) tokens are reported only in the `transferring*` fields
      * and excluded from `totalAmount` (#517 item 3). Fiat value derives from
      * `totalAmount`, so it likewise excludes in-flight value.
-     */
-    getAssets(coinId?: string): Promise<Asset[]>;
-    /**
-     * Aggregate tokens by coinId with confirmed/unconfirmed/transferring breakdown.
-     * Excludes tokens with status 'spent' or 'invalid'.
      *
-     * In-flight (`'transferring'`) tokens are LEAVING the wallet during an active
-     * send, so they are NOT counted as spendable: they are tracked in their own
-     * `transferring*` fields and excluded from `totalAmount`/`unconfirmedAmount`.
-     * Counting them as balance would show the user value they cannot spend (the
-     * #517 incident follow-up).
+     * @see TokenView.getAssets
      */
-    private aggregateTokens;
-    /** Fold one token into its coin's running totals (see {@link aggregateTokens}). */
-    private accumulateToken;
-    private newAssetAccumulator;
+    getAssets(coinId?: string): Promise<Asset[]>;
     /**
      * Get all tokens, optionally filtered by coin type and/or status.
      *
@@ -2720,6 +2579,7 @@ declare class PaymentsModule {
      * @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).
+     * @see TokenView.getTokens
      */
     getTokens(filter?: {
         coinId?: string;
@@ -2730,6 +2590,7 @@ declare class PaymentsModule {
      *
      * @param id - The local UUID assigned when the token was added.
      * @returns The token, or `undefined` if not found.
+     * @see TokenView.getToken
      */
     getToken(id: string): Token | undefined;
     /**
@@ -2787,6 +2648,7 @@ declare class PaymentsModule {
      * token state from being re-added (e.g. via Nostr re-delivery).
      *
      * @returns A shallow copy of the tombstone array.
+     * @see TokenView.getTombstones
      */
     getTombstones(): TombstoneEntry[];
     /**
@@ -2796,36 +2658,23 @@ declare class PaymentsModule {
      * @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.
+     * @see TokenView.isStateTombstoned
      */
     isStateTombstoned(tokenId: string, stateHash: string): boolean;
-    private rebuildTombstoneKeySet;
-    /**
-     * 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>;
     /**
      * Remove tombstones older than `maxAge` and cap the list at 100 entries.
      *
      * @param maxAge - Maximum age in milliseconds (default: 30 days).
+     * @see TokenView.pruneTombstones
      */
     pruneTombstones(maxAge?: number): Promise<void>;
     /**
      * Get the transaction history sorted newest-first.
      *
      * @returns Array of {@link TransactionHistoryEntry} objects in descending timestamp order.
+     * @see TransferHistory.getHistory
      */
     getHistory(): TransactionHistoryEntry[];
-    /**
-     * Best-effort resolve sender's DIRECT address and nametag from their transport pubkey.
-     * Returns empty object if transport doesn't support resolution or lookup fails.
-     */
-    private resolveSenderInfo;
     /**
      * Append an entry to the transaction history.
      *
@@ -2834,56 +2683,15 @@ declare class PaymentsModule {
      * Duplicate entries with the same `dedupKey` are silently ignored (upsert).
      *
      * @param entry - History entry fields (without `id` and `dedupKey`).
+     * @see TransferHistory.addToHistory
      */
     addToHistory(entry: Omit<TransactionHistoryEntry, 'id' | 'dedupKey'>): Promise<void>;
     /**
      * Load history into the in-memory cache.
      *
-     * In the wallet-api composition (the `walletApi` client is present) the
-     * durable §10 history log lives on the SERVER — the thin storage provider
-     * keeps none — so the cache is rebuilt from `walletApi.listHistory()`. The
-     * twin of the #521 inventory reload bug: `_historyCache` is process-lifetime,
-     * so a reload (tab refresh) must re-pull it or render an empty history.
-     * Compositions WITHOUT `walletApi` keep the legacy local path below.
+     * @see TransferHistory.loadHistory
      */
     loadHistory(): Promise<void>;
-    /**
-     * Rebuild `_historyCache` from the server's §10 history log (the wallet-api
-     * composition). Pages newest-first via the keyset cursor until `more:false`
-     * or the page cap; dedups by `dedupKey` (a hydrate-then-receive in the same
-     * session must not double-list). The S6 `memo` / `counterpartyNametag`
-     * envelopes are decrypted with the owner's own field key on the way in.
-     *
-     * #642 incremental fast path: after one completed hydration for this owner,
-     * later pulls stop at the first non-empty page holding nothing new — the
-     * §10 log is append-only (newest-first keyset), so everything past a fully
-     * known page is already cached. The steady-state 30s inventory resync then
-     * costs ONE history page instead of a full re-pagination (which on a wallet
-     * whose history overflows the page cap was 100 pages, every tick, forever).
-     *
-     * Best-effort, like the §10 history POST: history is untrusted DISPLAY data,
-     * so a backend outage during hydration must NEVER fail `load()` (the money
-     * path) — the in-session cache is left intact and the pull retries next load.
-     */
-    private hydrateHistoryFromServer;
-    /**
-     * Map one §16 history wire record onto the display
-     * {@link TransactionHistoryEntry}. `counterpartyNametag` lands on the role-
-     * appropriate field (sender for RECEIVED, recipient otherwise); the S6 memo +
-     * nametag envelopes decrypt under THIS wallet's field key (self-scoped at
-     * rest — §8.3), surfaced as absent if they don't decrypt rather than as
-     * ciphertext (same rule as mailbox/payment-request memos).
-     */
-    private historyEntryFromWire;
-    /** S6 field decrypt that surfaces an undecryptable envelope as absent (§8.3). */
-    private tryDecryptField;
-    /**
-     * Import history entries from remote TXF data into local store.
-     * Delegates to the local TokenStorageProvider's importHistoryEntries() for
-     * persistent storage, with in-memory fallback.
-     * Reused by both load() (initial IPFS fetch) and _doSync() (merge result).
-     */
-    private importRemoteHistoryEntries;
     /**
      * Get the first local token storage provider (for history operations).
      */
@@ -3006,6 +2814,7 @@ declare class PaymentsModule {
      * Tokens that fail validation or are detected as spent are marked `'invalid'`.
      *
      * @returns Object with arrays of valid and invalid tokens.
+     * @see TokenView.validate
      */
     validate(): Promise<{
         valid: Token[];
@@ -3020,17 +2829,6 @@ declare class PaymentsModule {
      * Uses pre-resolved PeerInfo if available, otherwise resolves via transport.
      */
     private resolveTransportPubkey;
-    /**
-     * v2 engine transfer (sender-driven): the sender handed us a FINISHED token.
-     * Decode the blob, dedup by the genesis-stable token id, store it as a
-     * confirmed token, and emit/record the receipt. No commitment / inclusion-proof
-     * / finalization round-trip (contrast the v1 sourceToken+transferTx path).
-     *
-     * Transport-agnostic (sdk-changes S3): fed by the relay push subscription
-     * AND by the delivery port's incoming pump — the returned verdict lets the
-     * pump map outcomes onto `ack('claimed' | 'rejected')`.
-     */
-    private handleV2Transfer;
     private teardownDeliveryPump;
     /**
      * Route a §9 wake nudge to the matching stream's pull. The wake is
@@ -3094,158 +2892,16 @@ declare class PaymentsModule {
      * ack for a provider without it (e.g. the relay no-op).
      */
     private flushIncomingAcks;
-    /** The S4 capability slice — null unless the composed wallet-api port carries it. */
-    private paymentRequestsApi;
-    private teardownPaymentRequestPump;
-    private prCursorKey;
-    private readPrCursorState;
-    private persistPrCursorState;
-    private prSettlingKey;
-    /**
-     * Single-flight load: concurrent callers (the pump's reload re-apply, resume's
-     * reconcile, a live pay catch) share ONE storage.get + ONE Map instance so a
-     * lazy read never overwrites another context's in-memory mutation.
-     */
-    private ensureSettlingJournalLoaded;
-    /**
-     * Serialize every read-modify-write through a tail-promise chain so two
-     * concurrent mutations can't lose an entry (the #679/#680 mutex lesson — a
-     * dropped entry is a re-payable request is a double-pay). `fn` returns true
-     * when the Map changed and must be persisted.
-     */
-    private mutateSettlingJournal;
-    /**
-     * #441: link a request to its in-flight transfer. `committed` marks a
-     * DEFINITE spend whose anchor intent is soft-aborted and will NOT resume-
-     * complete — a `PartialSendConflictError` (≥1 leg already delivered). The
-     * reconcile must resolve such a link 'paid' and NEVER revert it to payable
-     * (re-paying the full amount would double-pay the delivered leg). A
-     * non-`committed` link is a keep-open outcome that resume may still complete
-     * OR abort (e.g. CERTIFICATION_UNCONFIRMED losing to a foreign tx delivers
-     * nothing) — those DO revert to payable on abort.
-     */
-    private journalSettling;
-    private clearSettling;
-    /**
-     * Pull the wallet-api payment-request streams now (S4): drains the payer's
-     * incoming `?since=<seq>` stream (gap-free — §9/§16) into the existing
-     * handler/event surface and refreshes outgoing requests still awaiting a
-     * response. The poll interval and `load()` call this automatically; it is
-     * public for explicit fetch-now flows (mirrors {@link receive}). A no-op in
-     * compositions without the wallet-api payment-request capability — there
-     * the Nostr subscription is push-based.
-     */
-    syncPaymentRequests(): Promise<void>;
-    /** Coalesces concurrent pump runs (poll + wake + load can overlap). */
-    private pumpPaymentRequests;
-    private doPumpPaymentRequests;
-    /**
-     * Drain the payer's gap-free `?since=<seq>` stream (§9/§16), mirroring the
-     * mailbox-cursor pattern: the persisted `{cursor, syncEpoch}` is the resume
-     * point; a `syncEpoch` change (server restore — §5.4) voids cursor
-     * continuity, so the tail re-pulls from 0 and the id-dedup in
-     * {@link surfaceIncomingPaymentRequest} absorbs the replays.
-     *
-     * Because the surfaced list is in-memory only, each session FIRST runs one
-     * full incoming hydration from `since=0` with NO status filter (#556 —
-     * mirrors {@link hydrateHistoryFromServer}): a fresh engine rebuilds the
-     * CURRENT state of ALL incoming requests — open AND resolved — so a request
-     * paid/declined/expired in a PRIOR session is still present (with its
-     * resolved status) instead of vanishing once the cursor advanced past it.
-     * Hydration NEVER fires the new-incoming handlers/events for resolved
-     * requests — only `open` ones notify (the status-aware
-     * {@link surfaceIncomingPaymentRequest}) — so reopening can't spam stale
-     * 'new request' notifications. After hydration the `since`-cursor delta poll
-     * picks up live updates from the resume point.
-     */
-    private pumpIncomingPaymentRequests;
-    /**
-     * Decrypt a payment-request's recipient-addressed memo envelope into
-     * `{ memo, senderNametag }` (the requester's message + nametag). The key is
-     * the ECDH shared secret between THIS wallet (the payer) and the requester's
-     * chain pubkey (`wire.fromPubkey`) — symmetric with the requester's
-     * create-time derivation. Returns an empty bundle (and logs at debug) on any
-     * absence/failure so the incoming view never wedges on an unreadable memo
-     * (PR twin of #546/#547).
-     */
-    private decryptPaymentRequestMemo;
-    /** §16 wire status → the public {@link PaymentRequestStatus} display status. */
-    private static readonly PR_WIRE_STATUS;
-    /** Terminal local statuses: a re-surfaced wire may advance a request INTO one, never out of it. */
-    private static readonly PR_TERMINAL;
-    /**
-     * Map a §16 wire request onto the public {@link IncomingPaymentRequest}
-     * surface, deduped by id (the in-memory id-dedup doubles as the replay guard
-     * for cursor resets). Requests of EVERY status are surfaced so a reloaded
-     * thin wallet rebuilds the CURRENT state of its incoming view (#556) — open
-     * ones land as actionable `pending`, resolved ones carry their paid/declined
-     * (→ `rejected`)/expired status. Only `open` requests fire the new-incoming
-     * event + handlers; resolved requests are folded into the list silently, so a
-     * reload (or a `syncEpoch` re-pull) never re-notifies for already-resolved
-     * requests. Multi-asset requests surface their first asset (the module's
-     * request surface is single-asset; module-created requests always are).
-     */
-    private surfaceIncomingPaymentRequest;
-    /**
-     * Outgoing requests are a `?before=` backfill view (§16 — newest-first, no
-     * gap-free tail): refresh only while something local still awaits a
-     * response, paging until every pending id is resolved or the view drains.
-     */
-    private refreshOutgoingPaymentRequests;
-    /** Fold a server-side status change into the outgoing surface (responses + expiry). */
-    private applyOutgoingPaymentRequestState;
-    /**
-     * E.3 resume: list this wallet's OPEN intents (server-side — any device),
-     * decrypt each payload, and re-run the engine with the SAME transferId and
-     * inputs — deterministic realization yields byte-identical transactions, so
-     * an interrupted transfer completes instead of failing (proof fetch →
-     * match-verify → apply, Part E). Called at sign-in (S4).
+    /**
+     * E.3 resume of this wallet's OPEN send intents.
+     *
+     * @see IntentResume.resumeOpenIntents
      */
     resumeOpenIntents(): Promise<{
         resumed: string[];
         conflicted: string[];
         failed: string[];
     }>;
-    /**
-     * #441: resolve every journaled settling payment request against a resume
-     * outcome. Completed → send the deferred 'paid' response (server now told) and
-     * resolve 'paid'. Aborted (nothing delivered) → clear journal, return to
-     * payable. Still open → leave it. For an id accounted for by NONE of those
-     * (a crash between resume-complete and the local write), consult the server
-     * `listIntents('aborted')` authority: aborted → payable; else → paid (a
-     * completed row the server GC'd). Direction-of-error is deliberate: the only
-     * residual false-paid is a transfer that aborted server-side AND whose local
-     * 'aborted' write was lost AND whose server aborted-row was later GC'd — it is
-     * treated as paid, erring toward PAID-NEVER-RE-PAYABLE (no double-pay), the
-     * invariant this fix exists to protect.
-     */
-    private reconcileSettlingPaymentRequests;
-    /** #441: the linked transfer completed — tell the server 'paid' and resolve 'paid'. */
-    private resolveSettledPaid;
-    /** #441: the linked transfer aborted — nothing was paid; clear the link and return to payable. */
-    private revertSettlingToPayable;
-    /**
-     * Re-run one intent end-to-end: getToken (works for tombstoned rows — §5.3
-     * recovery surface), engine re-run under the original transferId, journaled
-     * delivery, the single §7 apply (inventory custody only), uniform close,
-     * and the SENT history record (dedupKey'd by transferId — idempotent).
-     */
-    private resumeIntent;
-    /**
-     * A resumed split that produced no output: a lost source means the leg delivered
-     * nothing (returns false), and every checkpoint failure keeps the intent open by
-     * throwing. There is no path here that records the spend.
-     */
-    private classifyResumeSplitFailure;
-    /**
-     * Drop the local records of the sources a resume consumed (present when
-     * resuming on the originating device). M7: each removal carries the LOCAL state
-     * we spent, so a source a concurrent claim reactivated to a NEW state (a
-     * self-send round-trip) is KEPT, not destroyed.
-     */
-    private dropResumedSources;
-    /** §10: the SENT record — same dedupKey as the original attempt, so a resume after the history POST is a server-side no-op. */
-    private recordResumedSentHistory;
     /**
      * Persist the token state to every (non-disabled) token storage provider.
      *
@@ -3261,77 +2917,6 @@ declare class PaymentsModule {
      * behavior.
      */
     private save;
-    private loadPendingV2Deliveries;
-    /**
-     * #621: journaled finished blobs for an intent, keyed by op position. opIndex when present,
-     * else positional among the intent's entries (legacy entries journaled in op order). Resume
-     * uses this to re-deliver an already-certified op instead of re-running the engine on its spent source.
-     */
-    private journaledByOp;
-    /** #517: run a journal read-modify-write atomically against all other journal mutations. */
-    private withJournalLock;
-    private savePendingV2Delivery;
-    private removePendingV2Delivery;
-    /**
-     * The hoisted send delivery pass (#699): hand a send's journaled committed
-     * blobs to ONE recipient — a single deliverBatch call when the port offers
-     * it and there is more than one blob, else per-blob deliver at the
-     * certification fan-out width. Returns true iff every blob was delivered
-     * (deferred blobs stay journaled). Never throws (§3.1).
-     */
-    private deliverCommittedBlobs;
-    /**
-     * Batch sibling of {@link tryDeliver}: success clears every journal entry;
-     * ANY failure keeps them ALL journaled (the deposit is idempotent by
-     * content-derived entry_id, so a replay absorbs entries that already
-     * landed). Never throws.
-     */
-    private tryDeliverBatch;
-    /**
-     * Per-blob fallback (a batch-less port, or a single blob), chunked at
-     * MAX_SEND_OPERATION_CONCURRENCY so the pass keeps the certification
-     * fan-out era's delivery width. Never throws.
-     */
-    private deliverPerBlob;
-    /**
-     * Covenant §3.1 (#621): once the source is certified on-chain, a delivery failure must NEVER
-     * fail the sender. Recipient-side conditions (a full mailbox / 429 from a never-claiming recipient)
-     * and transient delivery-infra failures (5xx/network) both leave the finished blob JOURNALED for
-     * (re-)delivery — the send resolves as delivery-pending and the sender moves on. The blob is already
-     * journaled (savePendingV2Delivery ran before this); on success we clear the journal, on any failure
-     * we keep it. Returns true if delivered, false if deferred. Never throws.
-     */
-    private tryDeliver;
-    /**
-     * Replay journaled finished-but-undelivered v2 blobs (kicked from load())
-     * through the delivery port (sdk-changes S3). Idempotent end to end: the
-     * mailbox deposit is idempotent by the content-derived entry_id — it succeeds
-     * even after the recipient claimed (§6) — and the relay path's recipient
-     * dedups by the genesis-stable token id.
-     *
-     * #517 item 1: instead of a silent unbounded fire-and-forget, each entry is
-     * retried with bounded exponential backoff, its cumulative failed-attempt
-     * count is journaled across loads, and an entry that exhausts
-     * {@link MAX_DELIVERY_REPLAY_ATTEMPTS} is SURFACED as poison
-     * (`delivery:undeliverable`) and left journaled but no longer auto-retried —
-     * so a journaled blob never sits undelivered invisibly.
-     */
-    private replayPendingV2Deliveries;
-    /** Replay a single journaled entry: backoff retries → success/removal, or → bounded poison. */
-    private replayOneDelivery;
-    /**
-     * §3.1 (#621): defer a recipient-quota (429) delivery — keep it journaled, never poison it (it
-     * self-heals when the recipient claims), and retry no sooner than the deferral window. Surfaced
-     * distinctly (delivery:deferred) so a UI can show "recipient's mailbox is full — will retry".
-     */
-    private deferDelivery;
-    /** One delivery with in-pass exponential backoff; throws the last error if all attempts fail. */
-    private attemptDeliveryWithBackoff;
-    /** Mark a journal entry poison (keep it, stop retrying) and surface it (#517 item 1). */
-    private markDeliveryPoison;
-    private bumpDeliveryAttempts;
-    /** Mutate one journaled entry in place (keyed by tokenBlob) and persist. No-op if gone. */
-    private updatePendingV2Delivery;
     private createStorageData;
     private loadFromStorageData;
     /**
@@ -4721,7 +4306,7 @@ interface IncomingTransfer {
     readonly memo?: string;
     readonly receivedAt: number;
 }
-type PaymentRequestStatus = 'pending' | 'accepted' | 'rejected' | 'paid' | 'expired' | 'settling';
+type PaymentRequestStatus = 'pending' | 'rejected' | 'paid' | 'expired' | 'settling';
 /**
  * Outgoing payment request (requesting payment from someone)
  */
@@ -4780,7 +4365,7 @@ type PaymentRequestHandler = (request: IncomingPaymentRequest) => void;
 /**
  * Response type for payment requests
  */
-type PaymentRequestResponseType = 'accepted' | 'rejected' | 'paid';
+type PaymentRequestResponseType = 'rejected' | 'paid';
 /**
  * Outgoing payment request (we sent to someone)
  */
@@ -4882,7 +4467,7 @@ interface TrackedAddress extends TrackedAddressEntry {
     /** Primary nametag (from nametag cache, without @ prefix) */
     readonly nametag?: string;
 }
-type SphereEventType = 'transfer:incoming' | 'transfer:confirmed' | 'transfer:failed' | 'transfer:delivery_pending' | 'transfer:invalid' | 'payment_request:incoming' | 'payment_request:accepted' | 'payment_request:rejected' | 'payment_request:paid' | 'payment_request:expired' | 'payment_request:settling' | 'payment_request:response' | 'message:dm' | 'message:read' | 'message:typing' | 'composing:started' | 'message:broadcast' | 'sync:started' | 'sync:completed' | 'sync:error' | 'storage:degraded' | 'inventory:conflict' | 'split:checkpoint-stuck' | 'send:partial-remainder' | 'delivery:undeliverable' | 'delivery:deferred' | 'walletapi:session' | 'realtime:status' | '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' | 'groupchat:ready' | 'communications:ready' | 'history:updated' | 'invoice:created' | 'invoice:payment' | 'invoice:asset_covered' | 'invoice:target_covered' | 'invoice:covered' | 'invoice:closed' | 'invoice:cancelled' | 'invoice:expired' | 'invoice:unknown_reference' | 'invoice:overpayment' | 'invoice:irrelevant' | 'invoice:auto_returned' | 'invoice:auto_return_failed' | 'invoice:return_received' | 'invoice:over_refund_warning' | 'invoice:receipt_sent' | 'invoice:receipt_received' | 'invoice:cancellation_sent' | 'invoice:cancellation_received' | 'swap:proposal_received' | 'swap:proposed' | 'swap:accepted' | 'swap:rejected' | 'swap:announced' | 'swap:deposit_sent' | 'swap:deposit_confirmed' | 'swap:deposits_covered' | 'swap:concluding' | 'swap:payout_received' | 'swap:completed' | 'swap:cancelled' | 'swap:failed' | 'swap:deposit_returned' | 'swap:bounce_received';
+type SphereEventType = 'transfer:incoming' | 'transfer:confirmed' | 'transfer:failed' | 'transfer:delivery_pending' | 'transfer:invalid' | 'payment_request:incoming' | 'payment_request:rejected' | 'payment_request:paid' | 'payment_request:expired' | 'payment_request:settling' | 'payment_request:response' | 'message:dm' | 'message:read' | 'message:typing' | 'composing:started' | 'message:broadcast' | 'sync:started' | 'sync:completed' | 'sync:error' | 'storage:degraded' | 'inventory:conflict' | 'split:checkpoint-stuck' | 'send:partial-remainder' | 'delivery:undeliverable' | 'delivery:deferred' | 'walletapi:session' | 'realtime:status' | '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' | 'groupchat:ready' | 'communications:ready' | 'history:updated' | 'invoice:created' | 'invoice:payment' | 'invoice:asset_covered' | 'invoice:target_covered' | 'invoice:covered' | 'invoice:closed' | 'invoice:cancelled' | 'invoice:expired' | 'invoice:unknown_reference' | 'invoice:overpayment' | 'invoice:irrelevant' | 'invoice:auto_returned' | 'invoice:auto_return_failed' | 'invoice:return_received' | 'invoice:over_refund_warning' | 'invoice:receipt_sent' | 'invoice:receipt_received' | 'invoice:cancellation_sent' | 'invoice:cancellation_received' | 'swap:proposal_received' | 'swap:proposed' | 'swap:accepted' | 'swap:rejected' | 'swap:announced' | 'swap:deposit_sent' | 'swap:deposit_confirmed' | 'swap:deposits_covered' | 'swap:concluding' | 'swap:payout_received' | 'swap:completed' | 'swap:cancelled' | 'swap:failed' | 'swap:deposit_returned' | 'swap:bounce_received';
 interface SphereEventMap {
     'transfer:incoming': IncomingTransfer;
     'transfer:confirmed': TransferResult;
@@ -4905,7 +4490,6 @@ interface SphereEventMap {
         reason: string;
     };
     'payment_request:incoming': IncomingPaymentRequest;
-    'payment_request:accepted': IncomingPaymentRequest;
     'payment_request:rejected': IncomingPaymentRequest;
     'payment_request:paid': IncomingPaymentRequest;
     'payment_request:expired': IncomingPaymentRequest;