@unicitylabs/sphere-sdk 0.7.1-dev.3 → 0.7.2

package/dist/index.cjs

@@ -943,6 +943,7 @@ __export(index_exports, {
   buildTxfStorageData: () => buildTxfStorageData,
   bytesToHex: () => bytesToHex3,
   checkNetworkHealth: () => checkNetworkHealth,
+  coinIdsMatch: () => coinIdsMatch,
   computeSwapId: () => computeSwapId,
   countCommittedTransactions: () => countCommittedTransactions,
   createAddress: () => createAddress,
@@ -961,22 +962,34 @@ __export(index_exports, {
   createSwapModule: () => createSwapModule,
   createTokenValidator: () => createTokenValidator,
   decodeBech32: () => decodeBech32,
+  decrypt: () => decrypt2,
   decryptCMasterKey: () => decryptCMasterKey,
+  decryptJson: () => decryptJson,
+  decryptMnemonic: () => decryptMnemonic,
   decryptNametag: () => import_nostr_js_sdk6.decryptNametag,
   decryptPrivateKey: () => decryptPrivateKey,
+  decryptSimple: () => decryptSimple,
   decryptTextFormatKey: () => decryptTextFormatKey,
+  decryptWallet: () => decryptWallet,
+  decryptWithSalt: () => decryptWithSalt,
   deriveAddressInfo: () => deriveAddressInfo,
   deriveChildKey: () => deriveChildKey,
   deriveKeyAtPath: () => deriveKeyAtPath,
   doubleSha256: () => doubleSha256,
   encodeBech32: () => encodeBech32,
+  encrypt: () => encrypt2,
+  encryptMnemonic: () => encryptMnemonic,
   encryptNametag: () => import_nostr_js_sdk6.encryptNametag,
+  encryptSimple: () => encryptSimple,
+  encryptWallet: () => encryptWallet,
   extractFromText: () => extractFromText,
   findPattern: () => findPattern,
   forkedKeyFromTokenIdAndState: () => forkedKeyFromTokenIdAndState,
   formatAmount: () => formatAmount,
+  generateAddressFromMasterKey: () => generateAddressFromMasterKey,
   generateMasterKey: () => generateMasterKey,
   generateMnemonic: () => generateMnemonic2,
+  generatePrivateKey: () => generatePrivateKey,
   getAddressHrp: () => getAddressHrp,
   getAddressId: () => getAddressId,
   getAddressStorageKey: () => getAddressStorageKey,
@@ -999,6 +1012,7 @@ __export(index_exports, {
   hashNametag: () => import_nostr_js_sdk6.hashNametag,
   hashSignMessage: () => hashSignMessage,
   hexToBytes: () => hexToBytes2,
+  hexToWIF: () => hexToWIF,
   identityFromMnemonicSync: () => identityFromMnemonicSync,
   initSphere: () => initSphere,
   isArchivedKey: () => isArchivedKey,
@@ -1028,6 +1042,7 @@ __export(index_exports, {
   logger: () => logger,
   mnemonicToSeedSync: () => mnemonicToSeedSync2,
   normalizeAddress: () => normalizeAddress,
+  normalizeCoinId: () => normalizeCoinId,
   normalizeNametag: () => import_nostr_js_sdk6.normalizeNametag,
   normalizeSdkTokenToStorage: () => normalizeSdkTokenToStorage,
   objectToTxf: () => objectToTxf,
@@ -1041,6 +1056,7 @@ __export(index_exports, {
   randomBytes: () => randomBytes2,
   randomHex: () => randomHex,
   randomUUID: () => randomUUID,
+  recoverPubkeyFromSignature: () => recoverPubkeyFromSignature,
   ripemd160: () => ripemd160,
   sha256: () => sha2562,
   signMessage: () => signMessage,
@@ -5093,6 +5109,27 @@ function verifySignedMessage(message, signature, expectedPubkey) {
     return false;
   }
 }
+function recoverPubkeyFromSignature(message, signature) {
+  if (signature.length !== 130) {
+    throw new SphereError(
+      `Invalid signature length: expected 130 hex chars, got ${signature.length}`,
+      "SIGNING_ERROR"
+    );
+  }
+  const v = parseInt(signature.slice(0, 2), 16) - 31;
+  const r = signature.slice(2, 66);
+  const s = signature.slice(66, 130);
+  if (v < 0 || v > 3) {
+    throw new SphereError(
+      `Invalid recovery byte: v=${v} out of range [0..3]`,
+      "SIGNING_ERROR"
+    );
+  }
+  const hashHex = hashSignMessage(message);
+  const hashBytes = Buffer.from(hashHex, "hex");
+  const recovered = ec.recoverPubKey(hashBytes, { r, s }, v);
+  return recovered.encode("hex", true);
+}
 
 // l1/crypto.ts
 var import_crypto_js3 = __toESM(require("crypto-js"), 1);
@@ -12513,6 +12550,132 @@ var PaymentsModule = class _PaymentsModule {
       };
     }
   }
+  /**
+   * 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.
+   */
+  async mintFungibleToken(coinIdHex, amount) {
+    this.ensureInitialized();
+    const stClient = this.deps.oracle.getStateTransitionClient?.();
+    if (!stClient) {
+      return { success: false, error: "State transition client not available" };
+    }
+    const trustBase = this.deps.oracle.getTrustBase?.();
+    if (!trustBase) {
+      return { success: false, error: "Trust base not available" };
+    }
+    try {
+      const signingService = await this.createSigningService();
+      const { TokenId: TokenId5 } = await import("@unicitylabs/state-transition-sdk/lib/token/TokenId");
+      const { TokenCoinData: TokenCoinData3 } = await import("@unicitylabs/state-transition-sdk/lib/token/fungible/TokenCoinData");
+      const { UnmaskedPredicateReference: UnmaskedPredicateReference4 } = await import("@unicitylabs/state-transition-sdk/lib/predicate/embedded/UnmaskedPredicateReference");
+      const tokenTypeBytes = fromHex4("f8aa13834268d29355ff12183066f0cb902003629bbc5eb9ef0efbe397867509");
+      const tokenType = new import_TokenType3.TokenType(tokenTypeBytes);
+      const tokenIdBytes = new Uint8Array(32);
+      crypto.getRandomValues(tokenIdBytes);
+      const tokenId = new TokenId5(tokenIdBytes);
+      const coinIdBytes = fromHex4(coinIdHex);
+      const coinId = new import_CoinId4.CoinId(coinIdBytes);
+      const coinData = TokenCoinData3.create([[coinId, amount]]);
+      const addressRef = await UnmaskedPredicateReference4.create(
+        tokenType,
+        signingService.algorithm,
+        signingService.publicKey,
+        import_HashAlgorithm5.HashAlgorithm.SHA256
+      );
+      const ownerAddress = await addressRef.toAddress();
+      const salt = new Uint8Array(32);
+      crypto.getRandomValues(salt);
+      const mintData = await import_MintTransactionData3.MintTransactionData.create(
+        tokenId,
+        tokenType,
+        null,
+        // tokenData: no metadata
+        coinData,
+        // fungible coin data
+        ownerAddress,
+        // recipient = self
+        salt,
+        null,
+        // recipientDataHash
+        null
+        // reason: null (genesis, no burn predecessor)
+      );
+      const commitment = await import_MintCommitment3.MintCommitment.create(mintData);
+      const MAX_RETRIES = 3;
+      let lastStatus;
+      for (let attempt = 1; attempt <= MAX_RETRIES; attempt++) {
+        const response = await stClient.submitMintCommitment(commitment);
+        lastStatus = response.status;
+        if (response.status === "SUCCESS" || response.status === "REQUEST_ID_EXISTS") break;
+        if (attempt === MAX_RETRIES) {
+          return { success: false, error: `Mint submit failed after ${MAX_RETRIES} attempts: ${response.status}` };
+        }
+        await new Promise((r) => setTimeout(r, 1e3 * attempt));
+      }
+      if (lastStatus !== "SUCCESS" && lastStatus !== "REQUEST_ID_EXISTS") {
+        return { success: false, error: `Mint submit failed: ${lastStatus}` };
+      }
+      const inclusionProof = await (0, import_InclusionProofUtils5.waitInclusionProof)(trustBase, stClient, commitment);
+      const genesisTransaction = commitment.toTransaction(inclusionProof);
+      const predicate = await import_UnmaskedPredicate5.UnmaskedPredicate.create(
+        tokenId,
+        tokenType,
+        signingService,
+        import_HashAlgorithm5.HashAlgorithm.SHA256,
+        salt
+      );
+      const tokenState = new import_TokenState5.TokenState(predicate, null);
+      const sdkToken = await import_Token6.Token.mint(trustBase, tokenState, genesisTransaction);
+      const tokenIdHex = tokenId.toJSON();
+      const symbol = this.getCoinSymbol(coinIdHex);
+      const name = this.getCoinName(coinIdHex);
+      const decimals = this.getCoinDecimals(coinIdHex);
+      const iconUrl = this.getCoinIconUrl(coinIdHex);
+      const uiToken = {
+        id: tokenIdHex,
+        coinId: coinIdHex,
+        symbol,
+        name,
+        decimals,
+        ...iconUrl !== void 0 ? { iconUrl } : {},
+        amount: amount.toString(),
+        status: "confirmed",
+        createdAt: Date.now(),
+        updatedAt: Date.now(),
+        sdkData: JSON.stringify(sdkToken.toJSON())
+      };
+      await this.addToken(uiToken);
+      return { success: true, token: uiToken, tokenId: tokenIdHex };
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      return { success: false, error: `Local mint failed: ${msg}` };
+    }
+  }
   /**
    * Check if a nametag is available for minting
    * @param nametag - The nametag to check (e.g., "alice" or "@alice")
@@ -18719,6 +18882,24 @@ var AccountingModule = class _AccountingModule {
   dirtyLedgerEntries = /* @__PURE__ */ new Set();
   /** Count of unknown (not in invoiceTermsCache) invoice IDs in the ledger. */
   unknownLedgerCount = 0;
+  /**
+   * 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).
+   */
+  unknownLedgerFirstSeen = /* @__PURE__ */ new Map();
+  unknownLedgerNextSweepMs = 0;
   /** W17: Tracks whether tokenScanState has been mutated since last flush. */
   tokenScanDirty = false;
   /** W2 fix: Serialization guard for _flushDirtyLedgerEntries. */
@@ -19709,6 +19890,7 @@ var AccountingModule = class _AccountingModule {
     }
     if (this.invoiceLedger.has(tokenId) && !this.invoiceTermsCache.has(tokenId)) {
       this.unknownLedgerCount = Math.max(0, this.unknownLedgerCount - 1);
+      this.unknownLedgerFirstSeen.delete(tokenId);
     }
     this.invoiceTermsCache.set(tokenId, terms);
     this._addToHashIndex(tokenId);
@@ -19977,6 +20159,29 @@ var AccountingModule = class _AccountingModule {
       closed: this.closedInvoices.has(invoiceId)
     };
   }
+  /**
+   * 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) {
+    const result = /* @__PURE__ */ new Set();
+    for (const [tokenId, invoiceIds] of this.tokenInvoiceMap) {
+      if (invoiceIds.has(invoiceId)) {
+        result.add(tokenId);
+      }
+    }
+    return result;
+  }
   /**
    * Explicitly close an invoice. Only target parties may close (§8.3).
    *
@@ -20296,6 +20501,7 @@ var AccountingModule = class _AccountingModule {
           ledger.set(entryKey, forwardRef);
           this.dirtyLedgerEntries.add(invoiceId);
           this.balanceCache.delete(invoiceId);
+          await this._persistProvisionalAndVerify(invoiceId, "payInvoice");
         }
         return result;
       } finally {
@@ -20463,6 +20669,7 @@ var AccountingModule = class _AccountingModule {
             this.dirtyLedgerEntries.add(invoiceId);
           }
           this.balanceCache.delete(invoiceId);
+          await this._persistProvisionalAndVerify(invoiceId, "returnInvoicePayment");
         }
         return result;
       } finally {
@@ -21542,9 +21749,30 @@ var AccountingModule = class _AccountingModule {
             continue;
           }
           innerMap.set(entryKey, ref);
-          if (!ref.transferId.startsWith("provisional:") && ref.transferId.includes(":")) {
+          const HEX_64 = /^[a-f0-9]{64}$/i;
+          if (entryKey.startsWith("mt:")) {
+            const firstColon = entryKey.indexOf(":");
+            const secondColon = entryKey.indexOf(":", firstColon + 1);
+            if (secondColon > firstColon + 1) {
+              const tokenIdFromKey2 = entryKey.slice(firstColon + 1, secondColon);
+              if (HEX_64.test(tokenIdFromKey2)) {
+                this._addToTokenInvoiceMap(tokenIdFromKey2, invoiceId);
+              }
+            }
+          } else if (entryKey.startsWith("synthetic:")) {
+            const afterPrefix = entryKey.slice("synthetic:".length);
+            const tokenIdEnd = afterPrefix.indexOf(":");
+            if (tokenIdEnd > 0) {
+              const tokenId = afterPrefix.slice(0, tokenIdEnd);
+              if (HEX_64.test(tokenId) && ref.transferId !== tokenId) {
+                this._addToTokenInvoiceMap(tokenId, invoiceId);
+              }
+            }
+          } else if (!ref.transferId.startsWith("provisional:") && ref.transferId.includes(":")) {
             const tokenIdFromRef = ref.transferId.slice(0, ref.transferId.indexOf(":"));
-            this._addToTokenInvoiceMap(tokenIdFromRef, invoiceId);
+            if (HEX_64.test(tokenIdFromRef)) {
+              this._addToTokenInvoiceMap(tokenIdFromRef, invoiceId);
+            }
           }
         }
       } catch (err) {
@@ -21745,7 +21973,14 @@ var AccountingModule = class _AccountingModule {
           }
         }
         for (const [existingKey, existingRef] of ledger) {
-          if (existingKey.startsWith("synthetic:") && existingRef.coinId === coinId && existingRef.paymentDirection === paymentDirection) {
+          if ((existingKey.startsWith("synthetic:") || existingKey.startsWith("synthetic-tx:")) && existingRef.coinId === coinId && existingRef.paymentDirection === paymentDirection) {
+            keysToDelete.push(existingKey);
+            break;
+          }
+        }
+        const mtPrefix = `mt:${tokenId}:`;
+        for (const [existingKey, existingRef] of ledger) {
+          if (existingKey.startsWith(mtPrefix) && existingRef.coinId === coinId && existingRef.paymentDirection === paymentDirection) {
             keysToDelete.push(existingKey);
             break;
           }
@@ -21862,6 +22097,49 @@ var AccountingModule = class _AccountingModule {
       });
     }
   }
+  /**
+   * 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.
+   */
+  async _persistProvisionalAndVerify(invoiceId, callContext) {
+    const flushTrigger = (this._flushPromise ?? Promise.resolve()).then(() => this._flushDirtyLedgerEntries());
+    const tracked = flushTrigger.catch(() => {
+    }).finally(() => {
+      if (this._flushPromise === tracked) this._flushPromise = null;
+    });
+    this._flushPromise = tracked;
+    await flushTrigger;
+    if (this.dirtyLedgerEntries.has(invoiceId)) {
+      throw new SphereError(
+        `${callContext}: provisional ledger entry for invoice ${invoiceId} failed to persist \u2014 caller should retry`,
+        "STORAGE_ERROR"
+      );
+    }
+  }
   // ===========================================================================
   // Internal: Event handlers
   // ===========================================================================
@@ -21922,13 +22200,96 @@ var AccountingModule = class _AccountingModule {
       }
     }
     if (!this.invoiceTermsCache.has(invoiceId)) {
-      const syntheticRef = this._buildSyntheticTransferRef(
-        transfer,
-        invoiceId,
-        paymentDirection,
-        confirmed
-      );
-      deps.emitEvent("invoice:unknown_reference", { invoiceId, transfer: syntheticRef });
+      let gracefullyGraduated = false;
+      await this.withInvoiceGate(invoiceId, async () => {
+        if (this.invoiceTermsCache.has(invoiceId)) {
+          gracefullyGraduated = true;
+          return;
+        }
+        const syntheticRef = this._buildSyntheticTransferRef(
+          transfer,
+          invoiceId,
+          paymentDirection,
+          confirmed
+        );
+        deps.emitEvent("invoice:unknown_reference", { invoiceId, transfer: syntheticRef });
+        const MAX_UNKNOWN_INVOICE_IDS = 500;
+        const UNKNOWN_LEDGER_TTL_MS = 30 * 60 * 1e3;
+        const MAX_ORPHAN_ENTRIES_PER_INVOICE = 50;
+        const UNKNOWN_LEDGER_SWEEP_INTERVAL_MS = 6e4;
+        const nowMs = Date.now();
+        const capFull = this.unknownLedgerCount >= MAX_UNKNOWN_INVOICE_IDS;
+        const sweepDue = nowMs >= this.unknownLedgerNextSweepMs;
+        if (this.unknownLedgerFirstSeen.size > 0 && (capFull || sweepDue)) {
+          this.unknownLedgerNextSweepMs = nowMs + UNKNOWN_LEDGER_SWEEP_INTERVAL_MS;
+          const expiredIds = [];
+          for (const [unkId, firstSeen] of this.unknownLedgerFirstSeen) {
+            if (nowMs - firstSeen > UNKNOWN_LEDGER_TTL_MS) {
+              expiredIds.push(unkId);
+            }
+          }
+          for (const expiredId of expiredIds) {
+            if (!this.invoiceTermsCache.has(expiredId) && this.invoiceLedger.has(expiredId)) {
+              this.invoiceLedger.delete(expiredId);
+              this.unknownLedgerCount = Math.max(0, this.unknownLedgerCount - 1);
+              for (const [tokenId, invoiceSet] of this.tokenInvoiceMap) {
+                if (invoiceSet.has(expiredId)) {
+                  invoiceSet.delete(expiredId);
+                  if (invoiceSet.size === 0) this.tokenInvoiceMap.delete(tokenId);
+                }
+              }
+            }
+            this.unknownLedgerFirstSeen.delete(expiredId);
+          }
+        }
+        if (!this.invoiceLedger.has(invoiceId)) {
+          if (this.unknownLedgerCount >= MAX_UNKNOWN_INVOICE_IDS) {
+            return;
+          }
+          this.invoiceLedger.set(invoiceId, /* @__PURE__ */ new Map());
+          this.unknownLedgerCount++;
+          this.unknownLedgerFirstSeen.set(invoiceId, nowMs);
+        }
+        const orphanLedger = this.invoiceLedger.get(invoiceId);
+        let mtEntryCount = 0;
+        for (const k of orphanLedger.keys()) {
+          if (k.startsWith("mt:")) mtEntryCount++;
+        }
+        if (mtEntryCount >= MAX_ORPHAN_ENTRIES_PER_INVOICE) {
+          return;
+        }
+        for (const token of transfer.tokens) {
+          if (!token.id) continue;
+          let onChainAttributed = false;
+          const tokenKeyPrefix = `${token.id}:`;
+          for (const existingKey of orphanLedger.keys()) {
+            if (existingKey.startsWith(tokenKeyPrefix) && !existingKey.startsWith("mt:")) {
+              onChainAttributed = true;
+              break;
+            }
+          }
+          if (!onChainAttributed) {
+            if (mtEntryCount >= MAX_ORPHAN_ENTRIES_PER_INVOICE) {
+              break;
+            }
+            const orphanKey = `mt:${token.id}:${transfer.id}`;
+            if (!orphanLedger.has(orphanKey)) {
+              orphanLedger.set(orphanKey, syntheticRef);
+              mtEntryCount++;
+            }
+          }
+          if (!this.tokenInvoiceMap.has(token.id)) {
+            this.tokenInvoiceMap.set(token.id, /* @__PURE__ */ new Set());
+          }
+          this.tokenInvoiceMap.get(token.id).add(invoiceId);
+        }
+        this.dirtyLedgerEntries.add(invoiceId);
+        this.balanceCache.delete(invoiceId);
+        await this._flushDirtyLedgerEntries();
+      });
+      if (gracefullyGraduated) {
+        await this._processInvoiceTransferEvent(transfer, invoiceId, paymentDirection, confirmed);
+      }
       return;
     }
     await this._processInvoiceTransferEvent(transfer, invoiceId, paymentDirection, confirmed);
@@ -22364,7 +22725,8 @@ var AccountingModule = class _AccountingModule {
       }
       const existingLedger = this.invoiceLedger.get(invoiceId);
       const firstTokenId = transfer.tokens.find((t) => t.id)?.id;
-      const syntheticKey = firstTokenId ? `synthetic:${firstTokenId}::${syntheticRef.coinId}` : `synthetic:${syntheticRef.transferId}::${syntheticRef.coinId}`;
+      const syntheticKey = firstTokenId ? `synthetic:${firstTokenId}::${syntheticRef.coinId}` : `synthetic-tx:${syntheticRef.transferId}::${syntheticRef.coinId}`;
+      let mutated = false;
       if (!existingLedger.has(syntheticKey)) {
         let hasRealEntry = false;
         for (const tok of transfer.tokens) {
@@ -22379,8 +22741,25 @@ var AccountingModule = class _AccountingModule {
         }
         if (!hasRealEntry) {
           existingLedger.set(syntheticKey, { ...syntheticRef });
+          mutated = true;
+        }
+      }
+      for (const tok of transfer.tokens) {
+        if (!tok.id) continue;
+        if (!this.tokenInvoiceMap.has(tok.id)) {
+          this.tokenInvoiceMap.set(tok.id, /* @__PURE__ */ new Set());
+          mutated = true;
+        }
+        const beforeSize = this.tokenInvoiceMap.get(tok.id).size;
+        this.tokenInvoiceMap.get(tok.id).add(invoiceId);
+        if (this.tokenInvoiceMap.get(tok.id).size !== beforeSize) {
+          mutated = true;
         }
       }
+      if (mutated) {
+        this.dirtyLedgerEntries.add(invoiceId);
+        this.balanceCache.delete(invoiceId);
+      }
       deps.emitEvent("invoice:payment", {
         invoiceId,
         transfer: syntheticRef,
@@ -22530,7 +22909,8 @@ var AccountingModule = class _AccountingModule {
         this.invoiceLedger.set(invoiceId, /* @__PURE__ */ new Map());
       }
       const hLedger = this.invoiceLedger.get(invoiceId);
-      const hKey = entry.tokenId ? `synthetic:${entry.tokenId}::${syntheticRef.coinId}` : `synthetic:${syntheticRef.transferId}::${syntheticRef.coinId}`;
+      const hKey = entry.tokenId ? `synthetic:${entry.tokenId}::${syntheticRef.coinId}` : `synthetic-tx:${syntheticRef.transferId}::${syntheticRef.coinId}`;
+      let hMutated = false;
       if (!hLedger.has(hKey)) {
         let hasRealEntry = false;
         if (entry.tokenId) {
@@ -22543,8 +22923,24 @@ var AccountingModule = class _AccountingModule {
         }
         if (!hasRealEntry) {
           hLedger.set(hKey, { ...syntheticRef });
+          hMutated = true;
         }
       }
+      if (entry.tokenId) {
+        if (!this.tokenInvoiceMap.has(entry.tokenId)) {
+          this.tokenInvoiceMap.set(entry.tokenId, /* @__PURE__ */ new Set());
+          hMutated = true;
+        }
+        const beforeSize = this.tokenInvoiceMap.get(entry.tokenId).size;
+        this.tokenInvoiceMap.get(entry.tokenId).add(invoiceId);
+        if (this.tokenInvoiceMap.get(entry.tokenId).size !== beforeSize) {
+          hMutated = true;
+        }
+      }
+      if (hMutated) {
+        this.dirtyLedgerEntries.add(invoiceId);
+        this.balanceCache.delete(invoiceId);
+      }
       deps.emitEvent("invoice:payment", {
         invoiceId,
         transfer: syntheticRef,
@@ -25090,17 +25486,63 @@ var SwapModule = class {
     for (const addr of allAddresses) {
       myDirectAddresses.add(addr.directAddress);
     }
-    let assetIndex;
-    if (myDirectAddresses.has(swap.manifest.party_a_address)) {
-      assetIndex = 0;
-    } else if (myDirectAddresses.has(swap.manifest.party_b_address)) {
-      assetIndex = 1;
+    const matchesPartyA = myDirectAddresses.has(swap.manifest.party_a_address);
+    const matchesPartyB = myDirectAddresses.has(swap.manifest.party_b_address);
+    if (matchesPartyA && matchesPartyB) {
+      throw new SphereError(
+        "Ambiguous party identity: local wallet matches both party_a_address and party_b_address",
+        "SWAP_DEPOSIT_FAILED"
+      );
+    }
+    let myExpectedCurrency;
+    if (matchesPartyA) {
+      myExpectedCurrency = swap.manifest.party_a_currency_to_change;
+    } else if (matchesPartyB) {
+      myExpectedCurrency = swap.manifest.party_b_currency_to_change;
     } else {
       throw new SphereError(
         "Local wallet address does not match either party in the swap manifest",
         "SWAP_DEPOSIT_FAILED"
       );
     }
+    if (!myExpectedCurrency || myExpectedCurrency === "") {
+      throw new SphereError(
+        "Manifest currency_to_change is empty for this party",
+        "SWAP_DEPOSIT_FAILED"
+      );
+    }
+    const invoiceRefForAssetLookup = deps.accounting.getInvoice(swap.depositInvoiceId);
+    if (!invoiceRefForAssetLookup) {
+      throw new SphereError(
+        "Deposit invoice not yet imported into accounting module",
+        "SWAP_WRONG_STATE"
+      );
+    }
+    const depositTarget = invoiceRefForAssetLookup.terms.targets[0];
+    if (!depositTarget) {
+      throw new SphereError(
+        "Deposit invoice has no targets",
+        "SWAP_DEPOSIT_FAILED"
+      );
+    }
+    const assetIndex = depositTarget.assets.findIndex(
+      (a) => a.coin !== void 0 && coinIdsMatch(a.coin[0], myExpectedCurrency)
+    );
+    if (assetIndex < 0) {
+      throw new SphereError(
+        `No asset matching expected currency ${myExpectedCurrency} found in deposit invoice`,
+        "SWAP_DEPOSIT_FAILED"
+      );
+    }
+    for (let i = assetIndex + 1; i < depositTarget.assets.length; i += 1) {
+      const a = depositTarget.assets[i];
+      if (a?.coin !== void 0 && coinIdsMatch(a.coin[0], myExpectedCurrency)) {
+        throw new SphereError(
+          `Ambiguous asset match in deposit invoice: slots ${assetIndex} and ${i} both match currency ${myExpectedCurrency}`,
+          "SWAP_DEPOSIT_FAILED"
+        );
+      }
+    }
     return this.withSwapGate(swapId, async () => {
       if (swap.progress !== "announced") {
         throw new SphereError(
@@ -25206,7 +25648,6 @@ var SwapModule = class {
           swap.updatedAt = Date.now();
           this.clearLocalTimer(swap.swapId);
           this.terminalSwapIds.add(swap.swapId);
-          const entryIdx = this._storedTerminalEntries.length;
           this._storedTerminalEntries.push({
             swapId: swap.swapId,
             progress: "failed",
@@ -25221,7 +25662,13 @@ var SwapModule = class {
             swap.error = prevError;
             swap.updatedAt = prevUpdatedAt;
             this.terminalSwapIds.delete(swap.swapId);
-            this._storedTerminalEntries.splice(entryIdx, 1);
+            for (let i = this._storedTerminalEntries.length - 1; i >= 0; i--) {
+              const entry = this._storedTerminalEntries[i];
+              if (entry.swapId === swap.swapId && entry.progress === "failed") {
+                this._storedTerminalEntries.splice(i, 1);
+                break;
+              }
+            }
             logger.warn(LOG_TAG3, `failPayout: persistSwap failed for ${swapId}; fraud detection will retry on next load:`, persistErr);
             throw persistErr;
           }
@@ -25265,9 +25712,25 @@ var SwapModule = class {
       if (!targetStatus.coinAssets[0].isCovered) {
         return returnFalse();
       }
-      if (BigInt(targetStatus.coinAssets[0].netCoveredAmount) < BigInt(expectedAmount)) {
+      let netCoveredAmount;
+      let expectedAmountBigInt;
+      try {
+        netCoveredAmount = BigInt(targetStatus.coinAssets[0].netCoveredAmount);
+        expectedAmountBigInt = BigInt(expectedAmount);
+      } catch (parseErr) {
+        return failPayout(
+          `MALFORMED_AMOUNT: failed to parse coverage amounts (netCoveredAmount=${targetStatus.coinAssets[0].netCoveredAmount}, expectedAmount=${expectedAmount}): ${parseErr instanceof Error ? parseErr.message : String(parseErr)}`
+        );
+      }
+      if (netCoveredAmount < expectedAmountBigInt) {
         return returnFalse();
       }
+      if (netCoveredAmount > expectedAmountBigInt) {
+        const surplus = netCoveredAmount - expectedAmountBigInt;
+        return failPayout(
+          `OVER_COVERAGE: net=${netCoveredAmount.toString()}, expected=${expectedAmount}, surplus=${surplus.toString()} \u2014 surplus refund expected via auto-return; settlement halted`
+        );
+      }
       const escrowAddr = swap.deal.escrowAddress ?? this.config.defaultEscrowAddress;
       if (escrowAddr) {
         const escrowPeer = await deps.resolve(escrowAddr);
@@ -25277,8 +25740,28 @@ var SwapModule = class {
       }
       const validationResult = await deps.payments.validate();
       if (validationResult.invalid.length > 0) {
-        logger.warn(LOG_TAG3, `verifyPayout for ${swapId.slice(0, 12)}: L3 validation found ${validationResult.invalid.length} invalid token(s) \u2014 retry after wallet sync`);
-        return returnFalse();
+        const payoutTokenIds = deps.accounting.getTokenIdsForInvoice?.(swap.payoutInvoiceId) ?? /* @__PURE__ */ new Set();
+        if (payoutTokenIds.size === 0) {
+          logger.warn(
+            LOG_TAG3,
+            `verifyPayout for ${swapId.slice(0, 12)}: ${validationResult.invalid.length} invalid token(s) but tokenInvoiceMap is empty for this payout invoice \u2014 failing closed until reverse index rebuilds`
+          );
+          return returnFalse();
+        }
+        const relevantInvalid = validationResult.invalid.filter(
+          (t) => payoutTokenIds.has(t.id)
+        );
+        if (relevantInvalid.length > 0) {
+          logger.warn(
+            LOG_TAG3,
+            `verifyPayout for ${swapId.slice(0, 12)}: L3 validation found ${relevantInvalid.length} invalid token(s) covering this payout invoice \u2014 retry after wallet sync`
+          );
+          return returnFalse();
+        }
+        logger.debug(
+          LOG_TAG3,
+          `verifyPayout for ${swapId.slice(0, 12)}: ${validationResult.invalid.length} unrelated invalid token(s) ignored (not linked to this payout invoice)`
+        );
       }
       if (swap.progress === "completed") {
         swap.payoutVerified = true;
@@ -25457,8 +25940,22 @@ var SwapModule = class {
    * @param dm - The incoming direct message.
    */
   handleIncomingDM(dm) {
+    if (dm.content.startsWith("{") && dm.content.includes('"invoice_delivery"')) {
+      logger.warn(
+        LOG_TAG3,
+        `diag_swap_dm_arrived sender=${dm.senderPubkey.slice(0, 16)} length=${dm.content.length}`
+      );
+    }
     const parsed = parseSwapDM(dm.content);
-    if (!parsed) return;
+    if (!parsed) {
+      if (dm.content.startsWith("{") && dm.content.includes('"invoice_delivery"')) {
+        logger.warn(
+          LOG_TAG3,
+          `diag_swap_dm_parse_rejected sender=${dm.senderPubkey.slice(0, 16)} prefix=${dm.content.slice(0, 80)}`
+        );
+      }
+      return;
+    }
     void (async () => {
       try {
         switch (parsed.kind) {
@@ -25824,16 +26321,43 @@ var SwapModule = class {
               // invoice_delivery (§12.4.2 + §12.4.3)
               // ---------------------------------------------------------------
               case "invoice_delivery": {
-                if (!swapId) return;
+                logger.warn(
+                  LOG_TAG3,
+                  `diag_invoice_delivery_received swap_id=${swapId?.slice(0, 16)} sender=${dm.senderPubkey.slice(0, 16)} invoice_type=${msg.invoice_type} invoice_id=${msg.invoice_id?.slice(0, 16)}`
+                );
+                if (!swapId) {
+                  logger.warn(LOG_TAG3, "diag_invoice_delivery_dropped reason=no_swap_id");
+                  return;
+                }
                 const swap = this.swaps.get(swapId);
-                if (!swap) return;
-                if (!this.isFromExpectedEscrow(dm.senderPubkey, swap)) return;
+                if (!swap) {
+                  logger.warn(
+                    LOG_TAG3,
+                    `diag_invoice_delivery_dropped reason=swap_not_in_map swap_id=${swapId.slice(0, 16)} known_swap_ids_count=${this.swaps.size}`
+                  );
+                  return;
+                }
+                if (!this.isFromExpectedEscrow(dm.senderPubkey, swap)) {
+                  logger.warn(
+                    LOG_TAG3,
+                    `diag_invoice_delivery_dropped reason=not_expected_escrow swap_id=${swapId.slice(0, 16)} sender=${dm.senderPubkey.slice(0, 16)} expected_escrow_pubkey=${swap.escrowPubkey?.slice(0, 16)} expected_escrow_addr=${swap.escrowDirectAddress?.slice(0, 24)}`
+                  );
+                  return;
+                }
                 const deps = this.deps;
                 if (msg.invoice_type === "deposit") {
+                  logger.warn(
+                    LOG_TAG3,
+                    `diag_invoice_delivery_proceeding_to_import swap_id=${swapId.slice(0, 16)} progress=${swap.progress} invoice_id=${(msg.invoice_id ?? "").slice(0, 16)}`
+                  );
                   await this.withSwapGate(swapId, async () => {
                     if (isTerminalProgress(swap.progress)) return;
                     try {
                       await deps.accounting.importInvoice(msg.invoice_token);
+                      logger.warn(
+                        LOG_TAG3,
+                        `diag_invoice_imported swap_id=${swapId.slice(0, 16)} invoice_id=${(msg.invoice_id ?? "").slice(0, 16)} type=deposit`
+                      );
                     } catch (err) {
                       if (err instanceof SphereError && err.code === "INVOICE_ALREADY_EXISTS") {
                         logger.debug(LOG_TAG3, `Deposit invoice for swap ${swapId} already imported \u2014 relay re-delivery, continuing`);
@@ -26472,6 +26996,65 @@ init_constants();
 var import_crypto_js6 = __toESM(require("crypto-js"), 1);
 init_errors();
 init_logger();
+var DEFAULT_ITERATIONS = 1e5;
+var KEY_SIZE = 256;
+var SALT_SIZE = 16;
+var IV_SIZE = 16;
+function deriveKey(password, salt, iterations) {
+  return import_crypto_js6.default.PBKDF2(password, salt, {
+    keySize: KEY_SIZE / 32,
+    // WordArray uses 32-bit words
+    iterations,
+    hasher: import_crypto_js6.default.algo.SHA256
+  });
+}
+function encrypt2(plaintext, password, options = {}) {
+  const iterations = options.iterations ?? DEFAULT_ITERATIONS;
+  const data = typeof plaintext === "string" ? plaintext : JSON.stringify(plaintext);
+  const salt = import_crypto_js6.default.lib.WordArray.random(SALT_SIZE);
+  const iv = import_crypto_js6.default.lib.WordArray.random(IV_SIZE);
+  const key = deriveKey(password, salt, iterations);
+  const encrypted = import_crypto_js6.default.AES.encrypt(data, key, {
+    iv,
+    mode: import_crypto_js6.default.mode.CBC,
+    padding: import_crypto_js6.default.pad.Pkcs7
+  });
+  return {
+    ciphertext: encrypted.ciphertext.toString(import_crypto_js6.default.enc.Base64),
+    iv: iv.toString(import_crypto_js6.default.enc.Hex),
+    salt: salt.toString(import_crypto_js6.default.enc.Hex),
+    algorithm: "aes-256-cbc",
+    kdf: "pbkdf2",
+    iterations
+  };
+}
+function decrypt2(encryptedData, password) {
+  const salt = import_crypto_js6.default.enc.Hex.parse(encryptedData.salt);
+  const iv = import_crypto_js6.default.enc.Hex.parse(encryptedData.iv);
+  const key = deriveKey(password, salt, encryptedData.iterations);
+  const ciphertext = import_crypto_js6.default.enc.Base64.parse(encryptedData.ciphertext);
+  const cipherParams = import_crypto_js6.default.lib.CipherParams.create({
+    ciphertext
+  });
+  const decrypted = import_crypto_js6.default.AES.decrypt(cipherParams, key, {
+    iv,
+    mode: import_crypto_js6.default.mode.CBC,
+    padding: import_crypto_js6.default.pad.Pkcs7
+  });
+  const result = decrypted.toString(import_crypto_js6.default.enc.Utf8);
+  if (!result) {
+    throw new SphereError("Decryption failed: invalid password or corrupted data", "DECRYPTION_ERROR");
+  }
+  return result;
+}
+function decryptJson(encryptedData, password) {
+  const decrypted = decrypt2(encryptedData, password);
+  try {
+    return JSON.parse(decrypted);
+  } catch {
+    throw new SphereError("Decryption failed: invalid JSON data", "DECRYPTION_ERROR");
+  }
+}
 function encryptSimple(plaintext, password) {
   return import_crypto_js6.default.AES.encrypt(plaintext, password).toString();
 }
@@ -26498,6 +27081,12 @@ function decryptWithSalt(ciphertext, password, salt) {
     return null;
   }
 }
+function encryptMnemonic(mnemonic, password) {
+  return encryptSimple(mnemonic, password);
+}
+function decryptMnemonic(encryptedMnemonic, password) {
+  return decryptSimple(encryptedMnemonic, password);
+}
 
 // core/scan.ts
 init_logger();
@@ -31323,6 +31912,7 @@ function createPriceProvider(config) {
   buildTxfStorageData,
   bytesToHex,
   checkNetworkHealth,
+  coinIdsMatch,
   computeSwapId,
   countCommittedTransactions,
   createAddress,
@@ -31341,22 +31931,34 @@ function createPriceProvider(config) {
   createSwapModule,
   createTokenValidator,
   decodeBech32,
+  decrypt,
   decryptCMasterKey,
+  decryptJson,
+  decryptMnemonic,
   decryptNametag,
   decryptPrivateKey,
+  decryptSimple,
   decryptTextFormatKey,
+  decryptWallet,
+  decryptWithSalt,
   deriveAddressInfo,
   deriveChildKey,
   deriveKeyAtPath,
   doubleSha256,
   encodeBech32,
+  encrypt,
+  encryptMnemonic,
   encryptNametag,
+  encryptSimple,
+  encryptWallet,
   extractFromText,
   findPattern,
   forkedKeyFromTokenIdAndState,
   formatAmount,
+  generateAddressFromMasterKey,
   generateMasterKey,
   generateMnemonic,
+  generatePrivateKey,
   getAddressHrp,
   getAddressId,
   getAddressStorageKey,
@@ -31379,6 +31981,7 @@ function createPriceProvider(config) {
   hashNametag,
   hashSignMessage,
   hexToBytes,
+  hexToWIF,
   identityFromMnemonicSync,
   initSphere,
   isArchivedKey,
@@ -31408,6 +32011,7 @@ function createPriceProvider(config) {
   logger,
   mnemonicToSeedSync,
   normalizeAddress,
+  normalizeCoinId,
   normalizeNametag,
   normalizeSdkTokenToStorage,
   objectToTxf,
@@ -31421,6 +32025,7 @@ function createPriceProvider(config) {
   randomBytes,
   randomHex,
   randomUUID,
+  recoverPubkeyFromSignature,
   ripemd160,
   sha256,
   signMessage,