@unicitylabs/sphere-sdk 0.7.1-dev.2 → 0.7.1

package/dist/core/index.d.cts

@@ -768,8 +768,22 @@ interface MultiAddressTransportMuxConfig {
     storage?: TransportStorageAdapter;
     /** Private key for the Mux's NostrClient identity. If provided, the Mux
      *  authenticates as this key — required for relays that filter gift-wrap
-     *  event delivery to the recipient's subscription. */
+     *  event delivery to the recipient's subscription.
+     *  Ignored when {@link sharedNostrClient} is set. */
     identityPrivateKey?: Uint8Array;
+    /**
+     * Optional pre-existing {@link NostrClient} to reuse instead of opening a
+     * fresh WebSocket per relay (#123). When set, the Mux skips both the
+     * {@code new NostrClient(...)} construction and {@code connect()} — it
+     * only registers subscription/connection listeners on the shared
+     * client. The Mux does NOT take ownership: its {@code disconnect()}
+     * leaves the client connected, since the caller (e.g. the original
+     * {@link NostrTransportProvider}) still uses it for resolve calls.
+     *
+     * Use a getter when the client may be created lazily (e.g. before the
+     * provider has connected).
+     */
+    sharedNostrClient?: NostrClient | null | (() => NostrClient | null);
 }
 declare class MultiAddressTransportMux {
     private config;
@@ -783,14 +797,14 @@ declare class MultiAddressTransportMux {
     private chatSubscriptionId;
     private chatEoseFired;
     private resubscribeTimer;
-    private lastWalletEventAt;
-    private lastChatEventAt;
-    private healthCheckTimer;
     private chatEoseHandlers;
     private processedEventIds;
     private static readonly MAX_PROCESSED_IDS;
     private eventCallbacks;
     private readonly identityPrivateKey;
+    private readonly sharedNostrClientGetter;
+    private usingSharedClient;
+    private connectionListener;
     constructor(config: MultiAddressTransportMuxConfig);
     /**
      * Add an address to the multiplexer.
@@ -815,6 +829,58 @@ declare class MultiAddressTransportMux {
     connect(): Promise<void>;
     disconnect(): Promise<void>;
     isConnected(): boolean;
+    /**
+     * Build the connection listener used by both {@link connect} and
+     * {@link rebindToSharedClient}.
+     *
+     * Behavioral notes:
+     * - When the Mux is sharing a {@link NostrClient} with the host
+     *   transport (#123), we deliberately do NOT emit
+     *   {@code transport:connected} / {@code transport:reconnecting} here
+     *   — the host transport's own listener already emits those for the
+     *   same socket event. Re-subscribing after a reconnect IS still our
+     *   responsibility, since the host has
+     *   {@code suppressSubscriptions()}'d its own filters.
+     * - {@code onConnect} does not emit {@code transport:connected}.
+     *   The SDK only fires {@code onConnect} on the initial socket
+     *   connection (subsequent reconnects use {@code onReconnected}),
+     *   and {@link connect()}'s bottom already emits
+     *   {@code transport:connected} once that returns. Emitting here too
+     *   would double-fire on every initial connect.
+     * - Each callback bails out early when the Mux is not in an active
+     *   state ({@code disconnected} / {@code error}). Listeners are
+     *   removed on {@code disconnect()} before the callback can fire,
+     *   so this guard is mainly defense-in-depth against any in-flight
+     *   callback that lands during teardown — but having it at the top
+     *   means we never emit a misleading {@code transport:connected}
+     *   from a Mux that has already torn down.
+     */
+    private buildConnectionListener;
+    /**
+     * Re-attach to a freshly-created shared NostrClient.
+     *
+     * Call this after the host (e.g. {@link NostrTransportProvider}) has
+     * recreated its NostrClient — typically because the wallet's active
+     * identity changed and the SDK's NostrClient does not support
+     * changing identity at runtime. The previous client has already
+     * been disconnected by the host, so its server-side subscriptions
+     * are gone — we just adopt the new client and re-issue our own.
+     *
+     * The caller is responsible for ordering: by the time rebind runs,
+     * the host transport's new NostrClient must already be created and
+     * connected. In Sphere this is guaranteed because we await
+     * {@code transport.setIdentity()} before calling rebind.
+     *
+     * Returns silently in two cases that are not caller errors:
+     *   - the Mux owns its own client (not sharing) — nothing to rebind
+     *   - the shared client reference hasn't changed (rebind is a no-op)
+     *
+     * Throws otherwise (rather than silently no-op'ing) so a wiring
+     * mistake — for instance, calling rebind before the host's new
+     * client is ready — surfaces immediately instead of leaving the
+     * Mux pinned to a stale client.
+     */
+    rebindToSharedClient(): Promise<void>;
     /**
      * One-shot fetch of pending events from the relay.
      * Creates a temporary subscription, waits for EOSE (or timeout),
@@ -835,7 +901,6 @@ declare class MultiAddressTransportMux {
      * Called whenever addresses are added/removed.
      */
     private updateSubscriptions;
-    private startHealthCheck;
     /**
      * Schedule a re-subscription after a relay-initiated subscription closure.
      * Debounced: if both wallet and chat subscriptions fire onError in quick
@@ -4248,6 +4313,42 @@ declare class PaymentsModule {
      * @returns MintNametagResult with success status and token if successful
      */
     mintNametag(nametag: string): Promise<MintNametagResult>;
+    /**
+     * Mint a fungible token directly to this wallet (genesis mint).
+     *
+     * Useful for test setups that need to seed a wallet with specific token
+     * balances WITHOUT depending on the testnet faucet HTTP service. The
+     * resulting token has the canonical CoinId bytes (passed in `coinIdHex`)
+     * — when those bytes match a registered symbol in the TokenRegistry,
+     * the token shows up under the symbol's name (e.g. "UCT"). There is no
+     * cryptographic restriction on which key may issue a given CoinId; the
+     * aggregator records the mint regardless of issuer identity.
+     *
+     * The flow:
+     *   1. Generate a random TokenId.
+     *   2. Build TokenCoinData with [(coinId, amount)].
+     *   3. Build MintTransactionData with recipient = self (UnmaskedPredicate
+     *      from this wallet's signing service).
+     *   4. Submit MintCommitment to the aggregator.
+     *   5. Wait for the inclusion proof.
+     *   6. Construct an SDK Token via Token.mint().
+     *   7. Convert to wallet Token format and call addToken().
+     *
+     * @param coinIdHex - 64-char lowercase hex CoinId. Must match the bytes
+     *   used by the registered symbol if you want the wallet to recognize
+     *   the token as that symbol (e.g. UCT's coinId from the public registry).
+     * @param amount - Amount in smallest units (multiply by 10^decimals
+     *   when converting from human values).
+     * @returns Result with the resulting wallet Token and its on-chain id.
+     */
+    mintFungibleToken(coinIdHex: string, amount: bigint): Promise<{
+        success: true;
+        token: Token;
+        tokenId: string;
+    } | {
+        success: false;
+        error: string;
+    }>;
     /**
      * Check if a nametag is available for minting
      * @param nametag - The nametag to check (e.g., "alice" or "@alice")
@@ -4727,6 +4828,24 @@ declare class AccountingModule {
     private dirtyLedgerEntries;
     /** Count of unknown (not in invoiceTermsCache) invoice IDs in the ledger. */
     private unknownLedgerCount;
+    /**
+     * Per-unknown-invoice first-seen timestamp for TTL eviction.
+     *
+     * W1 (steelman round-4): without TTL, an attacker who can deliver 500
+     * inbound transfers with synthesized memo invoiceIds permanently exhausts
+     * the unknown-ledger cap, after which legitimate orphan transfers (out-of-
+     * order delivery for real swaps) are silently dropped at the cap-check.
+     *
+     * Round-5 perf: gated by `unknownLedgerNextSweepMs` to amortize the
+     * sweep cost. The naive every-call sweep is O(N) where N=cap=500;
+     * combined with the per-token cleanup loop inside the sweep it became
+     * O(N×M) on every transfer under flood. Now we sweep at most every
+     * `UNKNOWN_LEDGER_SWEEP_INTERVAL_MS` (60s) UNLESS the cap is currently
+     * full, in which case we sweep on each call (the only path that can
+     * actually drop a legitimate orphan).
+     */
+    private unknownLedgerFirstSeen;
+    private unknownLedgerNextSweepMs;
     /** W17: Tracks whether tokenScanState has been mutated since last flush. */
     private tokenScanDirty;
     /** W2 fix: Serialization guard for _flushDirtyLedgerEntries. */
@@ -4911,6 +5030,21 @@ declare class AccountingModule {
      * @throws {SphereError} `NOT_INITIALIZED` — module not initialized.
      */
     getInvoice(invoiceId: string): InvoiceRef | null;
+    /**
+     * Return the set of token IDs that are currently linked to the given
+     * invoice. Populated by both the on-chain `_processTokenTransactions`
+     * path (tokens with `inv:` references) and the transport-memo orphan
+     * buffering path in `_handleIncomingTransfer`.
+     *
+     * Used by callers that want to scope per-invoice operations (e.g.
+     * SwapModule.verifyPayout's L3 validation) to only the tokens that
+     * cover this invoice — avoiding false negatives when the wallet
+     * contains unrelated tokens of the same currency in unconfirmed or
+     * spent state.
+     *
+     * Returns an empty set if no tokens are currently linked.
+     */
+    getTokenIdsForInvoice(invoiceId: string): Set<string>;
     /**
      * Explicitly close an invoice. Only target parties may close (§8.3).
      *
@@ -5258,6 +5392,35 @@ declare class AccountingModule {
      * await and the null assignment, so we loop until the field is null.
      */
     private _drainFlushPromise;
+    /**
+     * Synchronously persist any pending provisional ledger entry for `invoiceId`
+     * before returning to the caller. Used by `payInvoice` and
+     * `returnInvoicePayment` to make the in-memory provisional entry durable
+     * inside the same per-invoice gate that wrote it, closing the
+     * crash-mid-conclude race that produces over-coverage on receivers.
+     *
+     * Implementation:
+     *   1. Schedule a flush via the existing `_flushPromise` chain (so
+     *      concurrent `_handleTokenChange` callers waiting on the chain
+     *      observe ours as part of the sequence).
+     *   2. Await OUR flush directly — NOT `_drainFlushPromise()`, which would
+     *      spin while concurrent token changes keep extending the chain and
+     *      hold the per-invoice gate for an unbounded number of additional
+     *      flushes. We only need OUR provisional entry durable.
+     *   3. `_flushDirtyLedgerEntries` swallows per-invoice `storage.set`
+     *      rejections internally (sets a local `step1Failed` flag), leaving
+     *      the dirty entry on the set without re-throwing. So we post-check
+     *      `dirtyLedgerEntries.has(invoiceId)` and throw a `STORAGE_ERROR`
+     *      `SphereError` if our entry is still dirty — propagating to the
+     *      caller so they learn about the durability failure rather than
+     *      receiving a silent "success" return that lies on disk.
+     *
+     * @param invoiceId    The invoice whose provisional entry must be durable.
+     * @param callContext  Used in the error message so the caller is named
+     *                     ('payInvoice' / 'returnInvoicePayment') without
+     *                     forcing a stack-trace inspection.
+     */
+    private _persistProvisionalAndVerify;
     /**
      * Handle an incoming transfer event from PaymentsModule (§6.2).
      *
@@ -6328,6 +6491,23 @@ type LegacyFileType = 'dat' | 'txt' | 'json' | 'mnemonic' | 'unknown';
  */
 type DecryptionProgressCallback = (iteration: number, total: number) => Promise<void> | void;
 
+/**
+ * Compute the Unicity L3 DIRECT:// address that corresponds to a given
+ * compressed secp256k1 public key.
+ *
+ * Deterministic — the underlying primitive `UnmaskedPredicateReference.create`
+ * only uses the public key, so the private key is never needed. This lets
+ * a backend trust only one thing from the client (the chain pubkey, whose
+ * ownership the client proves via signature) and derive everything else
+ * locally. Closes the entire class of "client claims an identifier the
+ * server can't verify" bugs at the API level.
+ *
+ * @param chainPubkey 33-byte compressed secp256k1 pubkey, hex-encoded
+ *                    (66 chars, leading 02 or 03).
+ * @throws if chainPubkey doesn't match the compressed-secp256k1 format.
+ */
+declare function computeDirectAddressFromChainPubkey(chainPubkey: string): Promise<string>;
+
 declare function isValidNametag(nametag: string): boolean;
 
 /** Steps reported by the onProgress callback during wallet init/create/load/import */
@@ -6569,6 +6749,7 @@ interface SphereInitResult {
     /** Generated mnemonic (only if autoGenerate was used) */
     generatedMnemonic?: string;
 }
+
 /**
  * Holds all per-address module instances.
  * Each HD address gets its own set so modules can run independently in background.
@@ -7815,4 +7996,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, type DerivedKey, type DiscoverAddressProgress, type DiscoverAddressesOptions, type DiscoverAddressesResult, type DiscoveredAddress, type EncryptedData, type EncryptionOptions, type InitProgress, type InitProgressCallback, type InitProgressStep, type KeyPair, type L1Config, type LogHandler, type LogLevel, type LoggerConfig, type MasterKey, SIGN_MESSAGE_PREFIX, type ScanAddressProgress, type ScanAddressesOptions, type ScanAddressesResult, type ScannedAddressResult, Sphere, type SphereCreateOptions, SphereError, type SphereErrorCode, type SphereImportOptions, type SphereInitOptions, type SphereInitResult, type SphereLoadOptions, base58Decode, base58Encode, bytesToHex, checkNetworkHealth, computeHash160, convertBits, createAddress, createBech32, createKeyPair, createSphere, decodeBech32, decrypt, decryptJson, decryptMnemonic, decryptSimple, decryptWithSalt, deriveAddressInfo, deriveChildKey, deriveKeyAtPath, deserializeEncrypted, discoverAddressesImpl, doubleSha256, ec, encodeBech32, encrypt, encryptMnemonic, encryptSimple, entropyToMnemonic, extractFromText, findPattern, formatAmount, generateAddressInfo, generateMasterKey, generateMnemonic, generateRandomKey, getAddressHrp, getPublicKey, getSphere, hash160, hash160ToBytes, hashSignMessage, hexToBytes, identityFromMnemonic, identityFromMnemonicSync, importSphere, initSphere, isEncryptedData, isSphereError, isValidBech32, isValidNametag, isValidPrivateKey, loadSphere, logger, mnemonicToEntropy, mnemonicToSeed, mnemonicToSeedSync, privateKeyToAddressInfo, publicKeyToAddress, randomBytes, randomHex, randomUUID, ripemd160, scanAddressesImpl, serializeEncrypted, sha256, signMessage, sleep, sphereExists, toHumanReadable, toSmallestUnit, validateMnemonic, verifySignedMessage };
+export { type AddressInfo, type AddressModuleSet, CHARSET, type CheckNetworkHealthOptions, CurrencyUtils, DEFAULT_DERIVATION_PATH, DEFAULT_TOKEN_DECIMALS, type DerivedKey, type DiscoverAddressProgress, type DiscoverAddressesOptions, type DiscoverAddressesResult, type DiscoveredAddress, type EncryptedData, type EncryptionOptions, type InitProgress, type InitProgressCallback, type InitProgressStep, type KeyPair, type L1Config, type LogHandler, type LogLevel, type LoggerConfig, type MasterKey, SIGN_MESSAGE_PREFIX, type ScanAddressProgress, type ScanAddressesOptions, type ScanAddressesResult, type ScannedAddressResult, Sphere, type SphereCreateOptions, SphereError, type SphereErrorCode, type SphereImportOptions, type SphereInitOptions, type SphereInitResult, type SphereLoadOptions, base58Decode, base58Encode, bytesToHex, checkNetworkHealth, computeDirectAddressFromChainPubkey, computeHash160, convertBits, createAddress, createBech32, createKeyPair, createSphere, decodeBech32, decrypt, decryptJson, decryptMnemonic, decryptSimple, decryptWithSalt, deriveAddressInfo, deriveChildKey, deriveKeyAtPath, deserializeEncrypted, discoverAddressesImpl, doubleSha256, ec, encodeBech32, encrypt, encryptMnemonic, encryptSimple, entropyToMnemonic, extractFromText, findPattern, formatAmount, generateAddressInfo, generateMasterKey, generateMnemonic, generateRandomKey, getAddressHrp, getPublicKey, getSphere, hash160, hash160ToBytes, hashSignMessage, hexToBytes, identityFromMnemonic, identityFromMnemonicSync, importSphere, initSphere, isEncryptedData, isSphereError, isValidBech32, isValidNametag, isValidPrivateKey, loadSphere, logger, mnemonicToEntropy, mnemonicToSeed, mnemonicToSeedSync, privateKeyToAddressInfo, publicKeyToAddress, randomBytes, randomHex, randomUUID, ripemd160, scanAddressesImpl, serializeEncrypted, sha256, signMessage, sleep, sphereExists, toHumanReadable, toSmallestUnit, validateMnemonic, verifySignedMessage };

package/dist/core/index.d.ts

@@ -768,8 +768,22 @@ interface MultiAddressTransportMuxConfig {
     storage?: TransportStorageAdapter;
     /** Private key for the Mux's NostrClient identity. If provided, the Mux
      *  authenticates as this key — required for relays that filter gift-wrap
-     *  event delivery to the recipient's subscription. */
+     *  event delivery to the recipient's subscription.
+     *  Ignored when {@link sharedNostrClient} is set. */
     identityPrivateKey?: Uint8Array;
+    /**
+     * Optional pre-existing {@link NostrClient} to reuse instead of opening a
+     * fresh WebSocket per relay (#123). When set, the Mux skips both the
+     * {@code new NostrClient(...)} construction and {@code connect()} — it
+     * only registers subscription/connection listeners on the shared
+     * client. The Mux does NOT take ownership: its {@code disconnect()}
+     * leaves the client connected, since the caller (e.g. the original
+     * {@link NostrTransportProvider}) still uses it for resolve calls.
+     *
+     * Use a getter when the client may be created lazily (e.g. before the
+     * provider has connected).
+     */
+    sharedNostrClient?: NostrClient | null | (() => NostrClient | null);
 }
 declare class MultiAddressTransportMux {
     private config;
@@ -783,14 +797,14 @@ declare class MultiAddressTransportMux {
     private chatSubscriptionId;
     private chatEoseFired;
     private resubscribeTimer;
-    private lastWalletEventAt;
-    private lastChatEventAt;
-    private healthCheckTimer;
     private chatEoseHandlers;
     private processedEventIds;
     private static readonly MAX_PROCESSED_IDS;
     private eventCallbacks;
     private readonly identityPrivateKey;
+    private readonly sharedNostrClientGetter;
+    private usingSharedClient;
+    private connectionListener;
     constructor(config: MultiAddressTransportMuxConfig);
     /**
      * Add an address to the multiplexer.
@@ -815,6 +829,58 @@ declare class MultiAddressTransportMux {
     connect(): Promise<void>;
     disconnect(): Promise<void>;
     isConnected(): boolean;
+    /**
+     * Build the connection listener used by both {@link connect} and
+     * {@link rebindToSharedClient}.
+     *
+     * Behavioral notes:
+     * - When the Mux is sharing a {@link NostrClient} with the host
+     *   transport (#123), we deliberately do NOT emit
+     *   {@code transport:connected} / {@code transport:reconnecting} here
+     *   — the host transport's own listener already emits those for the
+     *   same socket event. Re-subscribing after a reconnect IS still our
+     *   responsibility, since the host has
+     *   {@code suppressSubscriptions()}'d its own filters.
+     * - {@code onConnect} does not emit {@code transport:connected}.
+     *   The SDK only fires {@code onConnect} on the initial socket
+     *   connection (subsequent reconnects use {@code onReconnected}),
+     *   and {@link connect()}'s bottom already emits
+     *   {@code transport:connected} once that returns. Emitting here too
+     *   would double-fire on every initial connect.
+     * - Each callback bails out early when the Mux is not in an active
+     *   state ({@code disconnected} / {@code error}). Listeners are
+     *   removed on {@code disconnect()} before the callback can fire,
+     *   so this guard is mainly defense-in-depth against any in-flight
+     *   callback that lands during teardown — but having it at the top
+     *   means we never emit a misleading {@code transport:connected}
+     *   from a Mux that has already torn down.
+     */
+    private buildConnectionListener;
+    /**
+     * Re-attach to a freshly-created shared NostrClient.
+     *
+     * Call this after the host (e.g. {@link NostrTransportProvider}) has
+     * recreated its NostrClient — typically because the wallet's active
+     * identity changed and the SDK's NostrClient does not support
+     * changing identity at runtime. The previous client has already
+     * been disconnected by the host, so its server-side subscriptions
+     * are gone — we just adopt the new client and re-issue our own.
+     *
+     * The caller is responsible for ordering: by the time rebind runs,
+     * the host transport's new NostrClient must already be created and
+     * connected. In Sphere this is guaranteed because we await
+     * {@code transport.setIdentity()} before calling rebind.
+     *
+     * Returns silently in two cases that are not caller errors:
+     *   - the Mux owns its own client (not sharing) — nothing to rebind
+     *   - the shared client reference hasn't changed (rebind is a no-op)
+     *
+     * Throws otherwise (rather than silently no-op'ing) so a wiring
+     * mistake — for instance, calling rebind before the host's new
+     * client is ready — surfaces immediately instead of leaving the
+     * Mux pinned to a stale client.
+     */
+    rebindToSharedClient(): Promise<void>;
     /**
      * One-shot fetch of pending events from the relay.
      * Creates a temporary subscription, waits for EOSE (or timeout),
@@ -835,7 +901,6 @@ declare class MultiAddressTransportMux {
      * Called whenever addresses are added/removed.
      */
     private updateSubscriptions;
-    private startHealthCheck;
     /**
      * Schedule a re-subscription after a relay-initiated subscription closure.
      * Debounced: if both wallet and chat subscriptions fire onError in quick
@@ -4248,6 +4313,42 @@ declare class PaymentsModule {
      * @returns MintNametagResult with success status and token if successful
      */
     mintNametag(nametag: string): Promise<MintNametagResult>;
+    /**
+     * Mint a fungible token directly to this wallet (genesis mint).
+     *
+     * Useful for test setups that need to seed a wallet with specific token
+     * balances WITHOUT depending on the testnet faucet HTTP service. The
+     * resulting token has the canonical CoinId bytes (passed in `coinIdHex`)
+     * — when those bytes match a registered symbol in the TokenRegistry,
+     * the token shows up under the symbol's name (e.g. "UCT"). There is no
+     * cryptographic restriction on which key may issue a given CoinId; the
+     * aggregator records the mint regardless of issuer identity.
+     *
+     * The flow:
+     *   1. Generate a random TokenId.
+     *   2. Build TokenCoinData with [(coinId, amount)].
+     *   3. Build MintTransactionData with recipient = self (UnmaskedPredicate
+     *      from this wallet's signing service).
+     *   4. Submit MintCommitment to the aggregator.
+     *   5. Wait for the inclusion proof.
+     *   6. Construct an SDK Token via Token.mint().
+     *   7. Convert to wallet Token format and call addToken().
+     *
+     * @param coinIdHex - 64-char lowercase hex CoinId. Must match the bytes
+     *   used by the registered symbol if you want the wallet to recognize
+     *   the token as that symbol (e.g. UCT's coinId from the public registry).
+     * @param amount - Amount in smallest units (multiply by 10^decimals
+     *   when converting from human values).
+     * @returns Result with the resulting wallet Token and its on-chain id.
+     */
+    mintFungibleToken(coinIdHex: string, amount: bigint): Promise<{
+        success: true;
+        token: Token;
+        tokenId: string;
+    } | {
+        success: false;
+        error: string;
+    }>;
     /**
      * Check if a nametag is available for minting
      * @param nametag - The nametag to check (e.g., "alice" or "@alice")
@@ -4727,6 +4828,24 @@ declare class AccountingModule {
     private dirtyLedgerEntries;
     /** Count of unknown (not in invoiceTermsCache) invoice IDs in the ledger. */
     private unknownLedgerCount;
+    /**
+     * Per-unknown-invoice first-seen timestamp for TTL eviction.
+     *
+     * W1 (steelman round-4): without TTL, an attacker who can deliver 500
+     * inbound transfers with synthesized memo invoiceIds permanently exhausts
+     * the unknown-ledger cap, after which legitimate orphan transfers (out-of-
+     * order delivery for real swaps) are silently dropped at the cap-check.
+     *
+     * Round-5 perf: gated by `unknownLedgerNextSweepMs` to amortize the
+     * sweep cost. The naive every-call sweep is O(N) where N=cap=500;
+     * combined with the per-token cleanup loop inside the sweep it became
+     * O(N×M) on every transfer under flood. Now we sweep at most every
+     * `UNKNOWN_LEDGER_SWEEP_INTERVAL_MS` (60s) UNLESS the cap is currently
+     * full, in which case we sweep on each call (the only path that can
+     * actually drop a legitimate orphan).
+     */
+    private unknownLedgerFirstSeen;
+    private unknownLedgerNextSweepMs;
     /** W17: Tracks whether tokenScanState has been mutated since last flush. */
     private tokenScanDirty;
     /** W2 fix: Serialization guard for _flushDirtyLedgerEntries. */
@@ -4911,6 +5030,21 @@ declare class AccountingModule {
      * @throws {SphereError} `NOT_INITIALIZED` — module not initialized.
      */
     getInvoice(invoiceId: string): InvoiceRef | null;
+    /**
+     * Return the set of token IDs that are currently linked to the given
+     * invoice. Populated by both the on-chain `_processTokenTransactions`
+     * path (tokens with `inv:` references) and the transport-memo orphan
+     * buffering path in `_handleIncomingTransfer`.
+     *
+     * Used by callers that want to scope per-invoice operations (e.g.
+     * SwapModule.verifyPayout's L3 validation) to only the tokens that
+     * cover this invoice — avoiding false negatives when the wallet
+     * contains unrelated tokens of the same currency in unconfirmed or
+     * spent state.
+     *
+     * Returns an empty set if no tokens are currently linked.
+     */
+    getTokenIdsForInvoice(invoiceId: string): Set<string>;
     /**
      * Explicitly close an invoice. Only target parties may close (§8.3).
      *
@@ -5258,6 +5392,35 @@ declare class AccountingModule {
      * await and the null assignment, so we loop until the field is null.
      */
     private _drainFlushPromise;
+    /**
+     * Synchronously persist any pending provisional ledger entry for `invoiceId`
+     * before returning to the caller. Used by `payInvoice` and
+     * `returnInvoicePayment` to make the in-memory provisional entry durable
+     * inside the same per-invoice gate that wrote it, closing the
+     * crash-mid-conclude race that produces over-coverage on receivers.
+     *
+     * Implementation:
+     *   1. Schedule a flush via the existing `_flushPromise` chain (so
+     *      concurrent `_handleTokenChange` callers waiting on the chain
+     *      observe ours as part of the sequence).
+     *   2. Await OUR flush directly — NOT `_drainFlushPromise()`, which would
+     *      spin while concurrent token changes keep extending the chain and
+     *      hold the per-invoice gate for an unbounded number of additional
+     *      flushes. We only need OUR provisional entry durable.
+     *   3. `_flushDirtyLedgerEntries` swallows per-invoice `storage.set`
+     *      rejections internally (sets a local `step1Failed` flag), leaving
+     *      the dirty entry on the set without re-throwing. So we post-check
+     *      `dirtyLedgerEntries.has(invoiceId)` and throw a `STORAGE_ERROR`
+     *      `SphereError` if our entry is still dirty — propagating to the
+     *      caller so they learn about the durability failure rather than
+     *      receiving a silent "success" return that lies on disk.
+     *
+     * @param invoiceId    The invoice whose provisional entry must be durable.
+     * @param callContext  Used in the error message so the caller is named
+     *                     ('payInvoice' / 'returnInvoicePayment') without
+     *                     forcing a stack-trace inspection.
+     */
+    private _persistProvisionalAndVerify;
     /**
      * Handle an incoming transfer event from PaymentsModule (§6.2).
      *
@@ -6328,6 +6491,23 @@ type LegacyFileType = 'dat' | 'txt' | 'json' | 'mnemonic' | 'unknown';
  */
 type DecryptionProgressCallback = (iteration: number, total: number) => Promise<void> | void;
 
+/**
+ * Compute the Unicity L3 DIRECT:// address that corresponds to a given
+ * compressed secp256k1 public key.
+ *
+ * Deterministic — the underlying primitive `UnmaskedPredicateReference.create`
+ * only uses the public key, so the private key is never needed. This lets
+ * a backend trust only one thing from the client (the chain pubkey, whose
+ * ownership the client proves via signature) and derive everything else
+ * locally. Closes the entire class of "client claims an identifier the
+ * server can't verify" bugs at the API level.
+ *
+ * @param chainPubkey 33-byte compressed secp256k1 pubkey, hex-encoded
+ *                    (66 chars, leading 02 or 03).
+ * @throws if chainPubkey doesn't match the compressed-secp256k1 format.
+ */
+declare function computeDirectAddressFromChainPubkey(chainPubkey: string): Promise<string>;
+
 declare function isValidNametag(nametag: string): boolean;
 
 /** Steps reported by the onProgress callback during wallet init/create/load/import */
@@ -6569,6 +6749,7 @@ interface SphereInitResult {
     /** Generated mnemonic (only if autoGenerate was used) */
     generatedMnemonic?: string;
 }
+
 /**
  * Holds all per-address module instances.
  * Each HD address gets its own set so modules can run independently in background.
@@ -7815,4 +7996,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, type DerivedKey, type DiscoverAddressProgress, type DiscoverAddressesOptions, type DiscoverAddressesResult, type DiscoveredAddress, type EncryptedData, type EncryptionOptions, type InitProgress, type InitProgressCallback, type InitProgressStep, type KeyPair, type L1Config, type LogHandler, type LogLevel, type LoggerConfig, type MasterKey, SIGN_MESSAGE_PREFIX, type ScanAddressProgress, type ScanAddressesOptions, type ScanAddressesResult, type ScannedAddressResult, Sphere, type SphereCreateOptions, SphereError, type SphereErrorCode, type SphereImportOptions, type SphereInitOptions, type SphereInitResult, type SphereLoadOptions, base58Decode, base58Encode, bytesToHex, checkNetworkHealth, computeHash160, convertBits, createAddress, createBech32, createKeyPair, createSphere, decodeBech32, decrypt, decryptJson, decryptMnemonic, decryptSimple, decryptWithSalt, deriveAddressInfo, deriveChildKey, deriveKeyAtPath, deserializeEncrypted, discoverAddressesImpl, doubleSha256, ec, encodeBech32, encrypt, encryptMnemonic, encryptSimple, entropyToMnemonic, extractFromText, findPattern, formatAmount, generateAddressInfo, generateMasterKey, generateMnemonic, generateRandomKey, getAddressHrp, getPublicKey, getSphere, hash160, hash160ToBytes, hashSignMessage, hexToBytes, identityFromMnemonic, identityFromMnemonicSync, importSphere, initSphere, isEncryptedData, isSphereError, isValidBech32, isValidNametag, isValidPrivateKey, loadSphere, logger, mnemonicToEntropy, mnemonicToSeed, mnemonicToSeedSync, privateKeyToAddressInfo, publicKeyToAddress, randomBytes, randomHex, randomUUID, ripemd160, scanAddressesImpl, serializeEncrypted, sha256, signMessage, sleep, sphereExists, toHumanReadable, toSmallestUnit, validateMnemonic, verifySignedMessage };
+export { type AddressInfo, type AddressModuleSet, CHARSET, type CheckNetworkHealthOptions, CurrencyUtils, DEFAULT_DERIVATION_PATH, DEFAULT_TOKEN_DECIMALS, type DerivedKey, type DiscoverAddressProgress, type DiscoverAddressesOptions, type DiscoverAddressesResult, type DiscoveredAddress, type EncryptedData, type EncryptionOptions, type InitProgress, type InitProgressCallback, type InitProgressStep, type KeyPair, type L1Config, type LogHandler, type LogLevel, type LoggerConfig, type MasterKey, SIGN_MESSAGE_PREFIX, type ScanAddressProgress, type ScanAddressesOptions, type ScanAddressesResult, type ScannedAddressResult, Sphere, type SphereCreateOptions, SphereError, type SphereErrorCode, type SphereImportOptions, type SphereInitOptions, type SphereInitResult, type SphereLoadOptions, base58Decode, base58Encode, bytesToHex, checkNetworkHealth, computeDirectAddressFromChainPubkey, computeHash160, convertBits, createAddress, createBech32, createKeyPair, createSphere, decodeBech32, decrypt, decryptJson, decryptMnemonic, decryptSimple, decryptWithSalt, deriveAddressInfo, deriveChildKey, deriveKeyAtPath, deserializeEncrypted, discoverAddressesImpl, doubleSha256, ec, encodeBech32, encrypt, encryptMnemonic, encryptSimple, entropyToMnemonic, extractFromText, findPattern, formatAmount, generateAddressInfo, generateMasterKey, generateMnemonic, generateRandomKey, getAddressHrp, getPublicKey, getSphere, hash160, hash160ToBytes, hashSignMessage, hexToBytes, identityFromMnemonic, identityFromMnemonicSync, importSphere, initSphere, isEncryptedData, isSphereError, isValidBech32, isValidNametag, isValidPrivateKey, loadSphere, logger, mnemonicToEntropy, mnemonicToSeed, mnemonicToSeedSync, privateKeyToAddressInfo, publicKeyToAddress, randomBytes, randomHex, randomUUID, ripemd160, scanAddressesImpl, serializeEncrypted, sha256, signMessage, sleep, sphereExists, toHumanReadable, toSmallestUnit, validateMnemonic, verifySignedMessage };