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

package/dist/index.js

@@ -12347,6 +12347,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")
@@ -18557,6 +18683,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. */
@@ -19547,6 +19691,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);
@@ -19815,6 +19960,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).
    *
@@ -20134,6 +20302,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 {
@@ -20301,6 +20470,7 @@ var AccountingModule = class _AccountingModule {
             this.dirtyLedgerEntries.add(invoiceId);
           }
           this.balanceCache.delete(invoiceId);
+          await this._persistProvisionalAndVerify(invoiceId, "returnInvoicePayment");
         }
         return result;
       } finally {
@@ -21380,9 +21550,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) {
@@ -21583,7 +21774,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;
           }
@@ -21700,6 +21898,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
   // ===========================================================================
@@ -21760,13 +22001,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);
@@ -22202,7 +22526,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) {
@@ -22217,7 +22542,24 @@ 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,
@@ -22368,7 +22710,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) {
@@ -22381,8 +22724,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,
@@ -24928,17 +25287,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(
@@ -25044,7 +25449,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",
@@ -25059,7 +25463,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;
           }
@@ -25103,9 +25513,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);
@@ -25115,8 +25541,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;
@@ -25295,8 +25741,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) {
@@ -25662,16 +26122,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`);
@@ -26310,6 +26797,65 @@ init_constants();
 init_errors();
 init_logger();
 import CryptoJS6 from "crypto-js";
+var DEFAULT_ITERATIONS = 1e5;
+var KEY_SIZE = 256;
+var SALT_SIZE = 16;
+var IV_SIZE = 16;
+function deriveKey(password, salt, iterations) {
+  return CryptoJS6.PBKDF2(password, salt, {
+    keySize: KEY_SIZE / 32,
+    // WordArray uses 32-bit words
+    iterations,
+    hasher: CryptoJS6.algo.SHA256
+  });
+}
+function encrypt2(plaintext, password, options = {}) {
+  const iterations = options.iterations ?? DEFAULT_ITERATIONS;
+  const data = typeof plaintext === "string" ? plaintext : JSON.stringify(plaintext);
+  const salt = CryptoJS6.lib.WordArray.random(SALT_SIZE);
+  const iv = CryptoJS6.lib.WordArray.random(IV_SIZE);
+  const key = deriveKey(password, salt, iterations);
+  const encrypted = CryptoJS6.AES.encrypt(data, key, {
+    iv,
+    mode: CryptoJS6.mode.CBC,
+    padding: CryptoJS6.pad.Pkcs7
+  });
+  return {
+    ciphertext: encrypted.ciphertext.toString(CryptoJS6.enc.Base64),
+    iv: iv.toString(CryptoJS6.enc.Hex),
+    salt: salt.toString(CryptoJS6.enc.Hex),
+    algorithm: "aes-256-cbc",
+    kdf: "pbkdf2",
+    iterations
+  };
+}
+function decrypt2(encryptedData, password) {
+  const salt = CryptoJS6.enc.Hex.parse(encryptedData.salt);
+  const iv = CryptoJS6.enc.Hex.parse(encryptedData.iv);
+  const key = deriveKey(password, salt, encryptedData.iterations);
+  const ciphertext = CryptoJS6.enc.Base64.parse(encryptedData.ciphertext);
+  const cipherParams = CryptoJS6.lib.CipherParams.create({
+    ciphertext
+  });
+  const decrypted = CryptoJS6.AES.decrypt(cipherParams, key, {
+    iv,
+    mode: CryptoJS6.mode.CBC,
+    padding: CryptoJS6.pad.Pkcs7
+  });
+  const result = decrypted.toString(CryptoJS6.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 CryptoJS6.AES.encrypt(plaintext, password).toString();
 }
@@ -26336,6 +26882,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();
@@ -27079,27 +27631,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
@@ -31118,7 +31685,37 @@ function createPriceProvider(config) {
       throw new SphereError(`Unsupported price platform: ${String(config.platform)}`, "INVALID_CONFIG");
   }
 }
+
+// core/auth.ts
+var AuthVerificationError = class extends Error {
+  code;
+  constructor(message, code) {
+    super(message);
+    this.name = "AuthVerificationError";
+    this.code = code;
+  }
+};
+async function verifySphereAuth(input) {
+  const { challenge, signature, chainPubkey } = input;
+  let directAddress;
+  try {
+    directAddress = await computeDirectAddressFromChainPubkey(chainPubkey);
+  } catch (err) {
+    throw new AuthVerificationError(
+      `chainPubkey is malformed: ${err.message}`,
+      "PUBKEY_MALFORMED"
+    );
+  }
+  if (!verifySignedMessage(challenge, signature, chainPubkey)) {
+    throw new AuthVerificationError(
+      "Signature does not verify against chainPubkey",
+      "SIGNATURE_INVALID"
+    );
+  }
+  return { chainPubkey, directAddress };
+}
 export {
+  AuthVerificationError,
   COIN_TYPES,
   CoinGeckoPriceProvider,
   CommunicationsModule,
@@ -31168,6 +31765,8 @@ export {
   buildTxfStorageData,
   bytesToHex3 as bytesToHex,
   checkNetworkHealth,
+  coinIdsMatch,
+  computeDirectAddressFromChainPubkey,
   computeSwapId,
   countCommittedTransactions,
   createAddress,
@@ -31186,22 +31785,34 @@ export {
   createSwapModule,
   createTokenValidator,
   decodeBech32,
+  decrypt2 as decrypt,
   decryptCMasterKey,
+  decryptJson,
+  decryptMnemonic,
   decryptNametag2 as decryptNametag,
   decryptPrivateKey,
+  decryptSimple,
   decryptTextFormatKey,
+  decryptWallet,
+  decryptWithSalt,
   deriveAddressInfo,
   deriveChildKey,
   deriveKeyAtPath,
   doubleSha256,
   encodeBech32,
+  encrypt2 as encrypt,
+  encryptMnemonic,
   encryptNametag,
+  encryptSimple,
+  encryptWallet,
   extractFromText,
   findPattern,
   forkedKeyFromTokenIdAndState,
   formatAmount,
+  generateAddressFromMasterKey,
   generateMasterKey,
   generateMnemonic2 as generateMnemonic,
+  generatePrivateKey,
   getAddressHrp,
   getAddressId,
   getAddressStorageKey,
@@ -31224,6 +31835,7 @@ export {
   hashNametag,
   hashSignMessage,
   hexToBytes2 as hexToBytes,
+  hexToWIF,
   identityFromMnemonicSync,
   initSphere,
   isArchivedKey,
@@ -31253,6 +31865,7 @@ export {
   logger,
   mnemonicToSeedSync2 as mnemonicToSeedSync,
   normalizeAddress,
+  normalizeCoinId,
   normalizeNametag3 as normalizeNametag,
   normalizeSdkTokenToStorage,
   objectToTxf,
@@ -31283,6 +31896,7 @@ export {
   verifyManifestIntegrity,
   verifyNametagBinding,
   verifySignedMessage,
+  verifySphereAuth,
   verifySwapSignature
 };
 /*! Bundled license information: