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

package/dist/core/index.d.ts

@@ -927,6 +927,237 @@ interface TombstoneEntry {
     timestamp: number;
 }
 
+/**
+ * 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 {
+    /**
+     * 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).
+     */
+    transferId: string;
+    /** Optional human memo. Implementations encrypt it client-side (S6). */
+    memo?: 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).
+     */
+    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;
+    /**
+     * 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.
+     */
+    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;
+    /**
+     * Bind the wallet identity (optional — implementations that authenticate or
+     * encrypt per-wallet need it; mirrors `TokenStorageProvider.setIdentity`).
+     */
+    setIdentity?(identity: {
+        privateKey: string;
+        chainPubkey: string;
+    }): 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).
+     */
+    createForAddress?(): DeliveryProvider;
+    /**
+     * 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).
+     */
+    deliver(recipientPubkey: string, blob: Uint8Array, options: DeliverOptions): Promise<DeliveryReceipt>;
+    /**
+     * 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).
+     */
+    incoming(sinceCursor?: string): AsyncIterable<IncomingDelivery>;
+    /**
+     * 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.
+     */
+    ack(deliveryId: string, disposition: DeliveryDisposition): Promise<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}.
+     */
+    ackBatch?(claimed: string[], rejected: 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}.
+     *
+     * 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.
+     */
+    deliverBatch?(recipientPubkey: string, blobs: Uint8Array[], options: DeliverOptions): Promise<DeliveryReceipt[]>;
+    /**
+     * 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.
+     */
+    onWake?(callback: (stream: WakeStream) => void, onStatus?: (status: WakeChannelStatus) => void): () => 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.
+     */
+    bindDeliveryKeys?(derive: (blobBytes: Uint8Array) => Promise<{
+        tokenId: string;
+        stateHash: string;
+    }>): void;
+}
+
+/**
+ * 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
@@ -1241,258 +1472,50 @@ interface IncomingBroadcast {
     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 {
-    /**
-     * 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).
-     */
-    transferId: string;
-    /** Optional human memo. Implementations encrypt it client-side (S6). */
-    memo?: 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).
-     */
-    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;
-    /**
-     * 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.
-     */
-    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';
+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;
 /**
- * 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").
+ * 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).
  */
-type DeliveryCustody = 'inventory' | 'external';
-interface DeliveryProvider {
-    /** Composition-time custody property — never a per-call flag (S7). */
-    readonly custody: DeliveryCustody;
-    /**
-     * Bind the wallet identity (optional — implementations that authenticate or
-     * encrypt per-wallet need it; mirrors `TokenStorageProvider.setIdentity`).
-     */
-    setIdentity?(identity: {
-        privateKey: string;
-        chainPubkey: string;
-    }): 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).
-     */
-    createForAddress?(): DeliveryProvider;
-    /**
-     * 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).
-     */
-    deliver(recipientPubkey: string, blob: Uint8Array, options: DeliverOptions): Promise<DeliveryReceipt>;
-    /**
-     * 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).
-     */
-    incoming(sinceCursor?: string): AsyncIterable<IncomingDelivery>;
-    /**
-     * 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.
-     */
-    ack(deliveryId: string, disposition: DeliveryDisposition): Promise<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}.
-     */
-    ackBatch?(claimed: string[], rejected: 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}.
-     *
-     * 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.
-     */
-    deliverBatch?(recipientPubkey: string, blobs: Uint8Array[], options: DeliverOptions): Promise<DeliveryReceipt[]>;
-    /**
-     * 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.
-     */
-    onWake?(callback: (stream: WakeStream) => void, onStatus?: (status: WakeChannelStatus) => void): () => 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.
-     */
-    bindDeliveryKeys?(derive: (blobBytes: Uint8Array) => Promise<{
-        tokenId: string;
-        stateHash: string;
-    }>): void;
+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;
 
 /**
  * WebSocket Abstraction
@@ -1940,22 +1963,6 @@ interface 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;
@@ -2189,15 +2196,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). */
@@ -2214,35 +2223,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;
     /**
@@ -2259,20 +2239,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). */
@@ -2283,43 +2249,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.
      *
@@ -2642,141 +2610,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.
      *
@@ -2790,6 +2657,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>;
     /**
@@ -2799,6 +2667,8 @@ declare class PaymentsModule {
     /**
      * Get total portfolio value in USD.
      * Returns null if PriceProvider is not configured.
+     *
+     * @see TokenView.getFiatBalance
      */
     getFiatBalance(): Promise<number | null>;
     /**
@@ -2816,6 +2686,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[];
     /**
@@ -2824,22 +2695,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.
      *
@@ -2847,6 +2706,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;
@@ -2857,6 +2717,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;
     /**
@@ -2914,6 +2775,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[];
     /**
@@ -2923,36 +2785,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.
      *
@@ -2961,56 +2810,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).
      */
@@ -3133,6 +2941,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[];
@@ -3147,17 +2956,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
@@ -3221,158 +3019,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.
      *
@@ -3388,77 +3044,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;
     /**
@@ -4872,7 +4457,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)
  */
@@ -4931,7 +4516,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)
  */
@@ -5033,7 +4618,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;
@@ -5056,7 +4641,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;