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

package/dist/core/index.js

@@ -12084,6 +12084,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 TokenType3(tokenTypeBytes);
+      const tokenIdBytes = new Uint8Array(32);
+      crypto.getRandomValues(tokenIdBytes);
+      const tokenId = new TokenId5(tokenIdBytes);
+      const coinIdBytes = fromHex4(coinIdHex);
+      const coinId = new CoinId4(coinIdBytes);
+      const coinData = TokenCoinData3.create([[coinId, amount]]);
+      const addressRef = await UnmaskedPredicateReference4.create(
+        tokenType,
+        signingService.algorithm,
+        signingService.publicKey,
+        HashAlgorithm5.SHA256
+      );
+      const ownerAddress = await addressRef.toAddress();
+      const salt = new Uint8Array(32);
+      crypto.getRandomValues(salt);
+      const mintData = await MintTransactionData3.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 MintCommitment3.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 waitInclusionProof5(trustBase, stClient, commitment);
+      const genesisTransaction = commitment.toTransaction(inclusionProof);
+      const predicate = await UnmaskedPredicate5.create(
+        tokenId,
+        tokenType,
+        signingService,
+        HashAlgorithm5.SHA256,
+        salt
+      );
+      const tokenState = new TokenState5(predicate, null);
+      const sdkToken = await SdkToken2.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")
@@ -18294,6 +18420,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. */
@@ -19284,6 +19428,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);
@@ -19552,6 +19697,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).
    *
@@ -19871,6 +20039,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 {
@@ -20038,6 +20207,7 @@ var AccountingModule = class _AccountingModule {
             this.dirtyLedgerEntries.add(invoiceId);
           }
           this.balanceCache.delete(invoiceId);
+          await this._persistProvisionalAndVerify(invoiceId, "returnInvoicePayment");
         }
         return result;
       } finally {
@@ -21117,9 +21287,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) {
@@ -21320,7 +21511,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;
           }
@@ -21437,6 +21635,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
   // ===========================================================================
@@ -21497,13 +21738,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);
@@ -21939,7 +22263,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) {
@@ -21954,8 +22279,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,
@@ -22105,7 +22447,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) {
@@ -22118,8 +22461,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,
@@ -24650,17 +25009,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(
@@ -24766,7 +25171,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",
@@ -24781,7 +25185,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;
           }
@@ -24825,9 +25235,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);
@@ -24837,8 +25263,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;
@@ -25017,8 +25463,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) {
@@ -25384,16 +25844,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`);
@@ -26886,27 +27373,42 @@ async function parseAndDecryptWalletDat(data, password, onProgress) {
 
 // core/Sphere.ts
 import { SigningService as SigningService2 } from "@unicitylabs/state-transition-sdk/lib/sign/SigningService";
+import { normalizeNametag as normalizeNametag2, isPhoneNumber } from "@unicitylabs/nostr-js-sdk";
+
+// core/address-derivation.ts
 import { TokenType as TokenType5 } from "@unicitylabs/state-transition-sdk/lib/token/TokenType";
 import { HashAlgorithm as HashAlgorithm7 } from "@unicitylabs/state-transition-sdk/lib/hash/HashAlgorithm";
 import { UnmaskedPredicateReference as UnmaskedPredicateReference3 } from "@unicitylabs/state-transition-sdk/lib/predicate/embedded/UnmaskedPredicateReference";
-import { normalizeNametag as normalizeNametag2, isPhoneNumber } from "@unicitylabs/nostr-js-sdk";
+var UNICITY_TOKEN_TYPE_HEX2 = "f8aa13834268d29355ff12183066f0cb902003629bbc5eb9ef0efbe397867509";
+var COMPRESSED_PUBKEY_RE = /^(02|03)[0-9a-fA-F]{64}$/;
+async function computeDirectAddressFromChainPubkey(chainPubkey) {
+  if (typeof chainPubkey !== "string" || !COMPRESSED_PUBKEY_RE.test(chainPubkey)) {
+    throw new Error(
+      `computeDirectAddressFromChainPubkey: chainPubkey must be 66-char hex with 02/03 prefix, got "${String(chainPubkey).slice(0, 12)}..."`
+    );
+  }
+  const tokenTypeBytes = Buffer.from(UNICITY_TOKEN_TYPE_HEX2, "hex");
+  const tokenType = new TokenType5(tokenTypeBytes);
+  const publicKeyBytes = Buffer.from(chainPubkey, "hex");
+  const predicateRef = await UnmaskedPredicateReference3.create(
+    tokenType,
+    "secp256k1",
+    publicKeyBytes,
+    HashAlgorithm7.SHA256
+  );
+  return (await predicateRef.toAddress()).toString();
+}
+
+// core/Sphere.ts
 function isValidNametag2(nametag) {
   if (isPhoneNumber(nametag)) return true;
   return /^[a-z0-9_-]{3,20}$/.test(nametag);
 }
-var UNICITY_TOKEN_TYPE_HEX2 = "f8aa13834268d29355ff12183066f0cb902003629bbc5eb9ef0efbe397867509";
 async function deriveL3PredicateAddress(privateKey) {
   const secret = Buffer.from(privateKey, "hex");
   const signingService = await SigningService2.createFromSecret(secret);
-  const tokenTypeBytes = Buffer.from(UNICITY_TOKEN_TYPE_HEX2, "hex");
-  const tokenType = new TokenType5(tokenTypeBytes);
-  const predicateRef = UnmaskedPredicateReference3.create(
-    tokenType,
-    signingService.algorithm,
-    signingService.publicKey,
-    HashAlgorithm7.SHA256
-  );
-  return (await (await predicateRef).toAddress()).toString();
+  const pubkeyHex = Buffer.from(signingService.publicKey).toString("hex");
+  return computeDirectAddressFromChainPubkey(pubkeyHex);
 }
 var Sphere = class _Sphere {
   // Singleton
@@ -30290,6 +30792,7 @@ export {
   base58Encode,
   bytesToHex3 as bytesToHex,
   checkNetworkHealth,
+  computeDirectAddressFromChainPubkey,
   computeHash160,
   convertBits,
   createAddress,