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

package/dist/core/index.d.ts

@@ -464,9 +464,6 @@ interface TokenStorageProvider<TData = unknown> extends BaseProvider {
 interface TxfStorageDataBase {
     _meta: TxfMeta;
     _tombstones?: TxfTombstone[];
-    _outbox?: TxfOutboxEntry[];
-    _sent?: TxfSentEntry[];
-    _invalid?: TxfInvalidEntry[];
     _history?: HistoryRecord[];
     [key: `_${string}`]: unknown;
 }
@@ -482,25 +479,6 @@ interface TxfTombstone {
     stateHash: string;
     timestamp: number;
 }
-interface TxfOutboxEntry {
-    id: string;
-    status: string;
-    tokenId: string;
-    recipient: string;
-    createdAt: number;
-    data: unknown;
-}
-interface TxfSentEntry {
-    tokenId: string;
-    recipient: string;
-    txHash: string;
-    sentAt: number;
-}
-interface TxfInvalidEntry {
-    tokenId: string;
-    reason: string;
-    detectedAt: number;
-}
 
 /**
  * Oracle Provider Interface
@@ -949,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
@@ -1247,274 +1456,66 @@ interface IncomingPaymentRequestResponse {
     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 {
-    /**
-     * 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;
+        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;
 
 /**
  * WebSocket Abstraction
@@ -1962,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;
@@ -2211,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). */
@@ -2236,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;
     /**
@@ -2281,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). */
@@ -2305,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.
      *
@@ -2664,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.
      *
@@ -2812,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>;
     /**
@@ -2821,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>;
     /**
@@ -2838,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[];
     /**
@@ -2846,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.
      *
@@ -2869,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;
@@ -2879,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;
     /**
@@ -2936,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[];
     /**
@@ -2945,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.
      *
@@ -2983,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).
      */
@@ -3155,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[];
@@ -3169,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
@@ -3243,143 +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;
     /**
      * Persist the token state to every (non-disabled) token storage provider.
      *
@@ -3395,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;
     /**
@@ -4879,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)
  */
@@ -4938,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)
  */
@@ -5040,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;
@@ -5063,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;
@@ -7470,13 +7047,15 @@ interface DerivedAddressInfo {
 declare function discoverAddressesImpl(deriveTransportPubkey: (index: number) => DerivedAddressInfo, batchResolve: (transportPubkeys: string[]) => Promise<PeerInfo[]>, options?: DiscoverAddressesOptions): Promise<DiscoverAddressesResult>;
 
 /**
- * Legacy File Serialization Types
+ * Text Wallet Backup Serialization Types
  */
 
-type LegacyFileType = 'dat' | 'txt' | 'json' | 'mnemonic' | 'unknown';
 /**
- * Progress callback for decryption operations
+ * Result of parsing a text wallet backup file
  */
+/** Backup file shapes `Sphere.importFromLegacyFile` accepts. Bitcoin Core `.dat` was removed (#604 — L3-only). */
+type LegacyFileType = 'txt' | 'json' | 'mnemonic' | 'unknown';
+/** Reports PBKDF2 progress while decrypting a password-protected backup. */
 type DecryptionProgressCallback = (iteration: number, total: number) => Promise<void> | void;
 
 /**
@@ -7520,7 +7099,6 @@ type DecryptionProgressCallback = (iteration: number, total: number) => Promise<
  */
 
 declare function isValidNametag(nametag: string): boolean;
-
 /** Steps reported by the onProgress callback during wallet init/create/load/import */
 type InitProgressStep = 'clearing' | 'storing_keys' | 'initializing' | 'recovering_nametag' | 'registering_nametag' | 'syncing_identity' | 'syncing_tokens' | 'discovering_addresses' | 'finalizing' | 'complete';
 /** Progress info passed to onProgress callback */
@@ -8159,6 +7737,43 @@ declare class Sphere {
      * modules fall back to their legacy path, same as init).
      */
     setOracleApiKey(apiKey: string): Promise<void>;
+    /**
+     * Import a wallet from a backup file: a `UNICITY WALLET DETAILS` text backup
+     * (the format `exportToTxt` writes, optionally password-encrypted), a legacy
+     * flat-JSON webwallet export, or a bare mnemonic in a text file.
+     *
+     * @example
+     * const result = await Sphere.importFromLegacyFile({
+     *   fileContent: await file.text(),
+     *   fileName: file.name,
+     *   password,          // when the backup is encrypted
+     *   ...providers,
+     * });
+     */
+    static importFromLegacyFile(options: Omit<SphereImportOptions, 'mnemonic' | 'masterKey' | 'chainCode' | 'derivationPath' | 'basePath' | 'derivationMode'> & {
+        /** The backup file's text. */
+        fileContent: string;
+        /** File name (used for type detection) */
+        fileName: string;
+        /** Password for encrypted files */
+        password?: string;
+        /** Progress callback for long decryption operations */
+        onDecryptProgress?: DecryptionProgressCallback;
+    }): Promise<{
+        success: boolean;
+        sphere?: Sphere;
+        mnemonic?: string;
+        needsPassword?: boolean;
+        error?: string;
+    }>;
+    /**
+     * Detect legacy file type from filename and content
+     */
+    static detectLegacyFileType(fileName: string, content: string): LegacyFileType;
+    /**
+     * Check if a legacy file is encrypted
+     */
+    static isLegacyFileEncrypted(fileName: string, content: string): boolean;
     /**
      * Check if wallet has BIP32 master key for HD derivation
      */
@@ -8243,60 +7858,6 @@ declare class Sphere {
         mnemonic?: string;
         error?: string;
     }>;
-    /**
-     * Import wallet from legacy file (.dat, .txt, or mnemonic text)
-     *
-     * Supports:
-     * - Bitcoin Core wallet.dat files (SQLite format, encrypted or unencrypted)
-     * - Text backup files (UNICITY WALLET DETAILS format)
-     * - Plain mnemonic text (12 or 24 words)
-     *
-     * @returns Object with success status, created Sphere instance, and optionally recovered mnemonic
-     *
-     * @example
-     * ```ts
-     * // Import from .dat file
-     * const fileBuffer = await file.arrayBuffer();
-     * const result = await Sphere.importFromLegacyFile({
-     *   fileContent: new Uint8Array(fileBuffer),
-     *   fileName: 'wallet.dat',
-     *   password: 'wallet-password', // if encrypted
-     *   storage, transport, oracle,
-     * });
-     *
-     * // Import from .txt file
-     * const textContent = await file.text();
-     * const result = await Sphere.importFromLegacyFile({
-     *   fileContent: textContent,
-     *   fileName: 'backup.txt',
-     *   storage, transport, oracle,
-     * });
-     * ```
-     */
-    static importFromLegacyFile(options: Omit<SphereImportOptions, 'mnemonic' | 'masterKey' | 'chainCode' | 'derivationPath' | 'basePath' | 'derivationMode'> & {
-        /** File content - Uint8Array for .dat, string for .txt */
-        fileContent: string | Uint8Array;
-        /** File name (used for type detection) */
-        fileName: string;
-        /** Password for encrypted files */
-        password?: string;
-        /** Progress callback for long decryption operations */
-        onDecryptProgress?: DecryptionProgressCallback;
-    }): Promise<{
-        success: boolean;
-        sphere?: Sphere;
-        mnemonic?: string;
-        needsPassword?: boolean;
-        error?: string;
-    }>;
-    /**
-     * Detect legacy file type from filename and content
-     */
-    static detectLegacyFileType(fileName: string, content: string | Uint8Array): LegacyFileType;
-    /**
-     * Check if a legacy file is encrypted
-     */
-    static isLegacyFileEncrypted(fileName: string, content: string | Uint8Array): boolean;
     /**
      * Get the current active address index
      *
@@ -9036,59 +8597,6 @@ declare const CurrencyUtils: {
     format: typeof formatAmount;
 };
 
-/**
- * Bech32 Encoding/Decoding
- * BIP-173 implementation for address encoding
- */
-/** Bech32 character set from BIP-173 */
-declare const CHARSET = "qpzry9x8gf2tvdw0s3jn54khce6mua7l";
-/**
- * Convert between bit arrays (8→5 or 5→8)
- */
-declare function convertBits(data: number[], fromBits: number, toBits: number, pad: boolean): number[] | null;
-/**
- * Encode data to bech32 address
- *
- * @example
- * ```ts
- * const address = encodeBech32('bc', 1, pubkeyHash);
- * // 'bc1qw...'
- * ```
- */
-declare function encodeBech32(hrp: string, version: number, program: Uint8Array): string;
-/**
- * Decode bech32 address
- *
- * @example
- * ```ts
- * const result = decodeBech32('bc1qw...');
- * // { hrp: 'bc', witnessVersion: 1, data: Uint8Array }
- * ```
- */
-declare function decodeBech32(addr: string): {
-    hrp: string;
-    witnessVersion: number;
-    data: Uint8Array;
-} | null;
-/**
- * Create address from public key hash
- *
- * @example
- * ```ts
- * const address = createAddress('bc', pubkeyHash);
- * // 'bc1...'
- * ```
- */
-declare function createAddress(hrp: string, pubkeyHash: Uint8Array | string): string;
-/**
- * Validate bech32 address
- */
-declare function isValidBech32(addr: string): boolean;
-/**
- * Get HRP from address
- */
-declare function getAddressHrp(addr: string): string | null;
-
 /**
  * Browser-safe UUID v4 generation.
  *
@@ -9335,4 +8843,4 @@ interface CheckNetworkHealthOptions {
  */
 declare function checkNetworkHealth(network?: NetworkType, options?: CheckNetworkHealthOptions): Promise<NetworkHealthResult>;
 
-export { type AddressInfo, type AddressModuleSet, CHARSET, type CheckNetworkHealthOptions, CurrencyUtils, DEFAULT_DERIVATION_PATH, DEFAULT_TOKEN_DECIMALS, DELIVERY_ENCRYPTION_HKDF_INFO, type DeliveryBundle, type DerivedKey, type DiscoverAddressProgress, type DiscoverAddressesOptions, type DiscoverAddressesResult, type DiscoveredAddress, type EncryptedData, type EncryptionOptions, FIELD_ENCRYPTION_HKDF_INFO, FIELD_ENVELOPE_MAX_BYTES, FIELD_ENVELOPE_NONCE_BYTES, FIELD_ENVELOPE_PREFIX, type InitProgress, type InitProgressCallback, type InitProgressStep, type KeyPair, type LogHandler, type LogLevel, type LoggerConfig, type MasterKey, PartialSendConflictError, SIGN_MESSAGE_PREFIX, Sphere, type SphereCreateOptions, SphereError, type SphereErrorCode, type SphereImportOptions, type SphereInitOptions, type SphereInitResult, type SphereLoadOptions, type SphereWalletApiSession, assertFieldEnvelopeShape, base58Decode, base58Encode, bytesToHex, checkNetworkHealth, convertBits, createAddress, createKeyPair, createSphere, decodeBech32, decrypt, decryptDeliveryBundle, decryptField, decryptFieldBytes, decryptJson, decryptMnemonic, decryptSimple, decryptWithSalt, deriveAddressInfo, deriveChildKey, deriveDeliveryEncryptionKey, deriveFieldEncryptionKey, deriveKeyAtPath, deserializeEncrypted, discoverAddressesImpl, doubleSha256, encodeBech32, encrypt, encryptDeliveryBundle, encryptField, encryptFieldBytes, encryptMnemonic, encryptSimple, entropyToMnemonic, extractFromText, findPattern, formatAmount, generateAddressFromMasterKey, generateAddressInfo, generateMasterKey, generateMnemonic, generateRandomKey, getAddressHrp, getPublicKey, getSphere, hash160, hashSignMessage, hexToBytes, identityFromMnemonic, identityFromMnemonicSync, importSphere, initSphere, isEncryptedData, isPossiblyCommittedSendOutcome, isSphereError, isValidBech32, isValidNametag, isValidPrivateKey, loadSphere, logger, mnemonicToEntropy, mnemonicToSeed, mnemonicToSeedSync, parseTokenAmount, randomBytes, randomHex, randomUUID, recoverPubkeyFromSignature, ripemd160, safeParseTokenAmount, serializeEncrypted, sha256, signMessage, sleep, sphereExists, toHumanReadable, validateMnemonic, verifySignedMessage };
+export { type AddressInfo, type AddressModuleSet, type CheckNetworkHealthOptions, CurrencyUtils, DEFAULT_DERIVATION_PATH, DEFAULT_TOKEN_DECIMALS, DELIVERY_ENCRYPTION_HKDF_INFO, type DeliveryBundle, type DerivedKey, type DiscoverAddressProgress, type DiscoverAddressesOptions, type DiscoverAddressesResult, type DiscoveredAddress, type EncryptedData, type EncryptionOptions, FIELD_ENCRYPTION_HKDF_INFO, FIELD_ENVELOPE_MAX_BYTES, FIELD_ENVELOPE_NONCE_BYTES, FIELD_ENVELOPE_PREFIX, type InitProgress, type InitProgressCallback, type InitProgressStep, type KeyPair, type LogHandler, type LogLevel, type LoggerConfig, type MasterKey, PartialSendConflictError, SIGN_MESSAGE_PREFIX, Sphere, type SphereCreateOptions, SphereError, type SphereErrorCode, type SphereImportOptions, type SphereInitOptions, type SphereInitResult, type SphereLoadOptions, type SphereWalletApiSession, assertFieldEnvelopeShape, base58Decode, base58Encode, bytesToHex, checkNetworkHealth, createKeyPair, createSphere, decrypt, decryptDeliveryBundle, decryptField, decryptFieldBytes, decryptJson, decryptMnemonic, decryptSimple, decryptWithSalt, deriveAddressInfo, deriveChildKey, deriveDeliveryEncryptionKey, deriveFieldEncryptionKey, deriveKeyAtPath, deserializeEncrypted, discoverAddressesImpl, doubleSha256, encrypt, encryptDeliveryBundle, encryptField, encryptFieldBytes, encryptMnemonic, encryptSimple, entropyToMnemonic, extractFromText, findPattern, formatAmount, generateAddressFromMasterKey, generateAddressInfo, generateMasterKey, generateMnemonic, generateRandomKey, getPublicKey, getSphere, hash160, hashSignMessage, hexToBytes, identityFromMnemonic, identityFromMnemonicSync, importSphere, initSphere, isEncryptedData, isPossiblyCommittedSendOutcome, isSphereError, isValidNametag, isValidPrivateKey, loadSphere, logger, mnemonicToEntropy, mnemonicToSeed, mnemonicToSeedSync, parseTokenAmount, randomBytes, randomHex, randomUUID, recoverPubkeyFromSignature, ripemd160, safeParseTokenAmount, serializeEncrypted, sha256, signMessage, sleep, sphereExists, toHumanReadable, validateMnemonic, verifySignedMessage };