@dusk-network/app-core 0.4.0 → 0.5.0

package/src/bridge.js

@@ -10,11 +10,46 @@
  * @module
  */
 
-import { networkFor, routeForAccount, routes } from "@dusk-network/networks";
+import { routeForAccount, routes } from "@dusk-network/networks";
 import { isAccount } from "@dusk-network/networks/account";
-import { BRIDGE_FUNCTIONS, duskEvmContracts, evmAddressOf } from "@dusk-network/networks/duskevm";
+import { BRIDGE_FUNCTIONS, decodeBridgeCall, duskEvmContracts, evmAddressOf, isBridgeContract } from "@dusk-network/networks/duskevm";
+import {
+  CREDIT_WINDOW_MS,
+  EVM_ADDRESS,
+  EVM_HASH,
+  TIMEOUT_MS,
+  WAIT_MS,
+  WEI_PER_LUX,
+  addressOf,
+  allOpen,
+  byTime,
+  depositsIn,
+  duskHashOf,
+  evmHashOf,
+  groupBy,
+  heightOf,
+  inOrder,
+  luxOf,
+  messageOf,
+  msOf,
+  networkOf,
+  pays,
+  quantityOf,
+  queued,
+  reader,
+  settle,
+  triage,
+  uniqueByHash,
+  urlOf,
+  usedOf,
+  withPast,
+} from "./bridge-common.js";
+import { depositArrivalsFromExplorer } from "./bridge-explorer.js";
 import { DETAILS_BATCH, TRANSFER_CONTRACT, fetchTxDetails, historyRange } from "./history.js";
 
+export { CREDIT_WINDOW_MS, EXPLORER_PAGES, WAIT_MS } from "./bridge-common.js";
+export { depositArrivalsFromExplorer } from "./bridge-explorer.js";
+
 /** @typedef {import("./bridge.js").Arrival} Arrival */
 /** @typedef {import("./bridge.js").BlockTimes} BlockTimes */
 /** @typedef {import("./bridge.js").Deposit} Deposit */
@@ -35,34 +70,15 @@ import { DETAILS_BATCH, TRANSFER_CONTRACT, fetchTxDetails, historyRange } from "
 /** @typedef {import("@dusk-network/networks").Network} Network */
 /** @typedef {import("@dusk-network/networks").NetworkRef} NetworkRef */
 /** @typedef {import("@dusk-network/networks").Route} Route */
-
-/**
- * A transfer as the matching sees it: when it was sent, the block on the
- * other chain its credit can't be before, and whether it is one of the
- * app's own (`given`) or one read from the chain.
- *
- * @typedef {{ hash: string, at: number, notBefore: bigint | null, given: boolean, scan: Scan | null }} Queued
- */
-
-/**
- * A credit on the other chain: its transaction, its block and time, its
- * amount in wei, whether it went through, and the address it came from as
- * its log names it (lower case; null where it isn't named). Found by an RPC
- * search, the passes over its blocks again done before it was (`pass`).
- *
- * @typedef {{ hash: string, block: bigint | null, at: number, wei: bigint, success: boolean, from: string | null, pass?: number }} Credit
- */
-
-/**
- * What a group's matching gave each transfer.
- *
- * @typedef {"arrived" | "waiting" | "unsure" | "late"} Verdict
- */
+/** @typedef {import("./bridge.js").BridgeNetwork} BridgeNetwork */
+/** @typedef {import("./bridge.js").FactCache} FactCache */
+/** @typedef {import("./bridge-common.js").Credit} Credit */
+/** @typedef {import("./bridge-common.js").DepositItem} DepositItem */
+/** @typedef {import("./bridge-common.js").Queued} Queued */
+/** @typedef {import("./bridge-common.js").Reader} Reader */
+/** @typedef {import("./bridge-common.js").Rules} Rules */
 
 export const CLOCK_SLACK_MS = 120_000;
-export const CREDIT_WINDOW_MS = 120_000;
-export const WAIT_MS = 7 * 24 * 60 * 60_000;
-export const EXPLORER_PAGES = 5;
 export const LOG_WINDOW = 5_000;
 export const LOG_WINDOWS = 8;
 export const DEPOSIT_HORIZON_MS = 2 * 60 * 60_000;
@@ -71,9 +87,6 @@ export const HISTORY_PAGES = 4;
 export const TRANSFER_TOPIC = "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef";
 export const ETH_BRIDGE_FINALIZED_TOPIC = "0x31b2166ff604fc5672ea5df08a78081d2bc6d746cadce880747f3643d819e83d";
 
-const WEI_PER_LUX = 1_000_000_000n;
-const MAX_U64 = (1n << 64n) - 1n;
-const TIMEOUT_MS = 8_000;
 // About one Dusk block every 10 seconds: how far back a sender's history is read.
 const DUSK_BLOCK_MS = 10_000;
 // The blocks the chain's pace is read over, from a block rounded down to a
@@ -99,84 +112,12 @@ const RECHECK_MS = 60_000;
 const CONFIRM_PASSES = 8;
 // What an RPC says when it won't search that many blocks at once.
 const RANGE_REFUSED = /limit|range|too many|exceed/i;
-const DUSK_HASH = /^[0-9a-f]{64}$/;
-const EVM_HASH = /^0x[0-9a-f]{64}$/;
-const EVM_ADDRESS = /^0x[0-9a-fA-F]{40}$/;
 const WORDS = /^0x(?:[0-9a-fA-F]{64})+$/;
 
 // ---------------------------------------------------------------------------
 // Values
 // ---------------------------------------------------------------------------
 
-/**
- * Lux from a bigint, a safe integer or its decimal text: null for anything
- * else, and past a u64.
- *
- * @param {unknown} value
- * @returns {bigint | null}
- */
-function luxOf(value) {
-  /** @type {bigint} */
-  let n;
-
-  if (typeof value === "bigint") n = value;
-  else if (typeof value === "number" && Number.isSafeInteger(value)) n = BigInt(value);
-  else if (typeof value === "string" && /^\d+$/.test(value.trim())) n = BigInt(value.trim());
-  else return null;
-
-  return n >= 0n && n <= MAX_U64 ? n : null;
-}
-
-/**
- * A block number or a time as JSON-RPC writes it (hex), or as decimal: null
- * for anything else.
- *
- * @param {unknown} value
- * @returns {bigint | null}
- */
-function quantityOf(value) {
-  if (typeof value === "bigint") return value >= 0n ? value : null;
-  if (typeof value === "number") return Number.isSafeInteger(value) && value >= 0 ? BigInt(value) : null;
-
-  const text = String(value ?? "").trim();
-
-  return /^0x[0-9a-fA-F]+$/.test(text) || /^\d+$/.test(text) ? BigInt(text) : null;
-}
-
-/**
- * A Dusk transaction's hash, lower case, without 0x; "" for anything else.
- *
- * @param {unknown} value
- */
-const duskHashOf = (value) => {
-  const hash = String(value ?? "")
-    .trim()
-    .toLowerCase()
-    .replace(/^0x/, "");
-
-  return DUSK_HASH.test(hash) ? hash : "";
-};
-
-/**
- * An EVM transaction's hash, lower case; "" for anything else.
- *
- * @param {unknown} value
- */
-const evmHashOf = (value) => {
-  const hash = String(value ?? "")
-    .trim()
-    .toLowerCase();
-
-  return EVM_HASH.test(hash) ? hash : "";
-};
-
-/**
- * An EVM address, lower case; "" for anything else.
- *
- * @param {unknown} value
- */
-const addressOf = (value) => (typeof value === "string" && EVM_ADDRESS.test(value) ? value.toLowerCase() : "");
-
 /**
  * An address as an indexed log topic: 32 bytes, lower case.
  *
@@ -187,33 +128,6 @@ const topicOf = (address) => `0x${address.slice(2).toLowerCase().padStart(64, "0
 /** @param {bigint} n */
 const hex = (n) => `0x${n.toString(16)}`;
 
-/**
- * @param {unknown} error
- * @returns {string}
- */
-const messageOf = (error) => String(/** @type {any} */ (error)?.message ?? error ?? "");
-
-/**
- * A Blockscout time ("2026-10-27T05:52:13.000000Z") in milliseconds.
- *
- * @param {unknown} text
- */
-const timeOf = (text) => Date.parse(String(text ?? "").replace(/(\.\d{3})\d+/, "$1"));
-
-/**
- * A time in milliseconds, or null.
- *
- * @param {unknown} value
- */
-const msOf = (value) => (typeof value === "number" && Number.isFinite(value) && value > 0 ? value : null);
-
-/**
- * A height, or null.
- *
- * @param {unknown} value
- */
-const heightOf = (value) => (typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : null);
-
 /**
  * How far a transfer's history is read, as a result gave it; null for
  * anything else.
@@ -293,286 +207,16 @@ function scanOf(value) {
   return out;
 }
 
-/**
- * The network a reference names; a TypeError for none there's a file for.
- *
- * @param {NetworkRef} network
- * @returns {Network}
- */
-function networkOf(network) {
-  const net = network && typeof network === "object" ? network : networkFor(/** @type {number | bigint | string} */ (network));
-
-  if (!net || typeof net.chainId !== "number" || !net.routes) throw new TypeError("Not one of the networks");
-
-  return net;
-}
-
-/**
- * @template T
- * @param {Iterable<T>} items
- * @param {(item: T) => string} keyOf
- * @returns {Map<string, T[]>}
- */
-function groupBy(items, keyOf) {
-  /** @type {Map<string, T[]>} */
-  const out = new Map();
-
-  for (const item of items) {
-    const key = keyOf(item);
-
-    out.set(key, [...(out.get(key) ?? []), item]);
-  }
-
-  return out;
-}
-
-/**
- * Oldest first, then by hash, so the order is the same everywhere.
- *
- * @param {{ at: number, hash: string, block?: bigint | null }} a
- * @param {{ at: number, hash: string, block?: bigint | null }} b
- */
-const byTime = (a, b) =>
-  a.at - b.at || (a.block !== undefined && b.block !== undefined && a.block !== null && b.block !== null && a.block !== b.block ? (a.block < b.block ? -1 : 1) : 0) || (a.hash < b.hash ? -1 : a.hash > b.hash ? 1 : 0);
-
 /**
  * @param {ReadonlyArray<bigint>} list
  * @returns {bigint}
  */
 const minOf = (list) => list.reduce((a, b) => (b < a ? b : a));
 
-// ---------------------------------------------------------------------------
-// Requests
-// ---------------------------------------------------------------------------
-
-/**
- * @param {string} url
- * @returns {string}
- */
-function hostOf(url) {
-  try {
-    return new URL(url).host;
-  } catch {
-    return url;
-  }
-}
-
-/**
- * The app's fetch, each request within `timeoutMs`, counted.
- *
- * @param {FetchLike | undefined} fetchFn
- * @param {number} timeoutMs
- */
-function reader(fetchFn, timeoutMs) {
-  const counter = { requests: 0 };
-
-  /**
-   * @param {string} url
-   * @param {{ method: "GET" | "POST", headers: Record<string, string>, body?: string }} init
-   * @returns {Promise<{ ok: boolean, status: number, body: any, host: string }>}
-   */
-  async function exchange(url, init) {
-    const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), timeoutMs);
-    const host = hostOf(url);
-
-    counter.requests += 1;
-
-    try {
-      const send = fetchFn ?? globalThis.fetch;
-      const response = await send(url, { ...init, signal: controller.signal });
-      const text = await response.text();
-      /** @type {any} */
-      let body;
-
-      try {
-        body = JSON.parse(text);
-      } catch {
-        throw new Error(response.ok ? `${host} didn't answer with JSON` : `${host} answers with HTTP ${response.status}`);
-      }
-
-      return { body, host, ok: response.ok, status: response.status };
-    } catch (error) {
-      if (controller.signal.aborted) throw new Error(`${host} didn't answer within ${Math.round(timeoutMs / 100) / 10} s`);
-
-      throw error;
-    } finally {
-      clearTimeout(timer);
-    }
-  }
-
-  return {
-    counter,
-    // What a call reads once for all its searches, by what and where: a
-    // chain's head and pace.
-    /** @type {Map<string, Promise<any>>} */
-    once: new Map(),
-
-    /**
-     * @param {string} url
-     * @returns {Promise<any>}
-     */
-    async getJson(url) {
-      const answer = await exchange(url, { headers: { accept: "application/json" }, method: "GET" });
-
-      if (!answer.ok) throw new Error(`${answer.host} answers with HTTP ${answer.status}`);
-
-      return answer.body;
-    },
-
-    /**
-     * One JSON-RPC call; its error's message, with its code, when it refuses.
-     *
-     * @param {string} url
-     * @param {string} method
-     * @param {unknown[]} params
-     * @returns {Promise<any>}
-     */
-    async rpc(url, method, params) {
-      const answer = await exchange(url, {
-        body: JSON.stringify({ id: 1, jsonrpc: "2.0", method, params }),
-        headers: { "content-type": "application/json" },
-        method: "POST",
-      });
-      const error = answer.body?.error;
-
-      if (error) throw Object.assign(new Error(String(error.message ?? `${method} was refused`)), { code: error.code });
-      if (!answer.ok) throw new Error(`${answer.host} answers ${method} with HTTP ${answer.status}`);
-
-      return answer.body?.result;
-    },
-  };
-}
-
-/** @typedef {ReturnType<typeof reader>} Reader */
-
 // ---------------------------------------------------------------------------
 // Matching: each credit pays one transfer, in the order they were sent
 // ---------------------------------------------------------------------------
 
-/**
- * Transfers whose windows touch, each window from `windowMs` before its
- * time to `windowMs` after: a credit in one could be another's.
- *
- * @param {ReadonlyArray<Queued>} queue oldest first
- * @param {number} windowMs
- * @returns {Queued[][]}
- */
-function clustersOf(queue, windowMs) {
-  /** @type {Queued[][]} */
-  const out = [];
-
-  for (const item of queue) {
-    const last = out[out.length - 1];
-
-    if (last && item.at - windowMs <= last[last.length - 1].at + windowMs) last.push(item);
-    else out.push([item]);
-  }
-
-  return out;
-}
-
-/**
- * Whether every window of the queue is still open: nothing in it can be
- * told apart yet.
- *
- * @param {ReadonlyArray<Queued>} queue
- * @param {number} windowMs
- * @param {number} now
- */
-const allOpen = (queue, windowMs, now) => clustersOf(queue, windowMs).every((cluster) => now < cluster[cluster.length - 1].at + windowMs);
-
-/**
- * How a group's credits are matched: see `settle`.
- *
- * @typedef {{ guarded: boolean, now: number, slackMs: number, used: ReadonlySet<string>, windowMs: number, rivals?: ReadonlySet<string> }} Rules
- */
-
-/**
- * Whether a credit could pay a transfer, whether or not another one took it:
- * it went through, isn't one the app gave another of its transfers when
- * this one is the app's, comes from none of `rivals`, and is in the
- * transfer's time and at or after the block it can't be before.
- *
- * @param {Queued} item
- * @param {Credit} credit
- * @param {Rules} rules
- */
-function pays(item, credit, { guarded, rivals = new Set(), slackMs, used, windowMs }) {
-  const lo = item.at - (guarded ? windowMs : slackMs);
-  const hi = guarded ? item.at + windowMs : Infinity;
-
-  return (
-    credit.success &&
-    (!item.given || !used.has(credit.hash)) &&
-    (credit.from === null || !rivals.has(credit.from)) &&
-    credit.at >= lo &&
-    credit.at <= hi &&
-    (item.notBefore === null || credit.block === null || credit.block >= item.notBefore)
-  );
-}
-
-/**
- * Each transfer of a queue of equal ones, oldest first, takes the first
- * credit that went through after it that no earlier one took: from
- * `slackMs` before it on, and at or after the block it can't be before.
- * None comes from an address of `rivals`: the senders of other transfers
- * the app gave, whose credits these could be. A credit the app gave another
- * of its transfers (`used`) is none of the app's own waiting ones; a
- * transfer read from the chain may have it, as the one it paid comes back
- * among them.
- *
- * Where the queue may not hold every transfer that could have made the
- * credits (`guarded`), a credit is a transfer's only within `windowMs`
- * either side of it, and once the windows that touch its own are over,
- * only when every payment of its amount in them (those that failed too) is
- * one of those transfers' credits, or one the app gave another. Otherwise
- * it could be another transfer's: unsure. A transfer whose windows closed
- * without a credit is late: one coming later can't be told apart.
- *
- * @param {ReadonlyArray<Queued>} queue oldest first
- * @param {ReadonlyArray<Credit>} credits
- * @param {Rules} rules
- * @returns {{ assigned: Map<string, Credit>, verdicts: Map<string, Verdict> }}
- */
-function settle(queue, credits, rules) {
-  const { guarded, now, used, windowMs } = rules;
-  const sorted = [...credits].sort(byTime);
-  /** @type {Map<string, Credit>} */
-  const assigned = new Map();
-  const taken = new Set();
-  /** @type {Map<string, Verdict>} */
-  const verdicts = new Map();
-
-  for (const item of queue) {
-    const credit = sorted.find((c) => !taken.has(c.hash) && pays(item, c, rules));
-
-    if (credit) {
-      assigned.set(item.hash, credit);
-      taken.add(credit.hash);
-    }
-  }
-
-  if (!guarded) {
-    for (const item of queue) verdicts.set(item.hash, assigned.has(item.hash) ? "arrived" : "waiting");
-
-    return { assigned, verdicts };
-  }
-
-  for (const cluster of clustersOf(queue, windowMs)) {
-    const lo = cluster[0].at - windowMs;
-    const hi = cluster[cluster.length - 1].at + windowMs;
-    const own = new Set(cluster.flatMap((item) => (assigned.has(item.hash) ? [/** @type {Credit} */ (assigned.get(item.hash)).hash] : [])));
-    const stray = sorted.some((c) => c.at >= lo && c.at <= hi && !used.has(c.hash) && !own.has(c.hash));
-
-    for (const item of cluster) {
-      verdicts.set(item.hash, now < hi ? "waiting" : stray ? "unsure" : assigned.has(item.hash) ? "arrived" : "late");
-    }
-  }
-
-  return { assigned, verdicts };
-}
-
 /**
  * The queue of equal transfers: the app's, and those read from the chain
  * that were sent shortly before one of them, each within `horizonMs` of the
@@ -595,25 +239,6 @@ function queueOf(given, read, horizonMs) {
   return all.filter((_, i) => kept[i]);
 }
 
-/**
- * A queue of equal transfers where the credits can't be told apart, with
- * the ones the app gave but no longer looks for (waited for too long) whose
- * windows touch theirs: those were sent first, and take their credits
- * first.
- *
- * @param {ReadonlyArray<Queued>} given
- * @param {ReadonlyArray<Queued>} past
- * @param {number} windowMs
- * @returns {Queued[]}
- */
-function withPast(given, past, windowMs) {
-  const polled = new Set(given.map((item) => item.hash));
-
-  return clustersOf([...given, ...past].sort(byTime), windowMs)
-    .filter((cluster) => cluster.some((item) => polled.has(item.hash)))
-    .flat();
-}
-
 /**
  * The first transfer of the run of equal ones before `item`, each within
  * `horizonMs` of the next.
@@ -1278,19 +903,24 @@ function exactJson(text) {
   return JSON.parse(text.replace(TOKEN, (match, string) => string ?? (/^-?\d+$/.test(match) && !Number.isSafeInteger(Number(match)) ? `"${match}"` : match)));
 }
 
-const utf8 = new TextDecoder();
+const utf8 = new TextDecoder("utf-8", { fatal: true });
 
 /**
- * A memo's bytes, given as hex, as text, read as the route's bridge reads
- * them: as UTF-8, bytes that aren't UTF-8 becoming the replacement
- * character; "" for none.
+ * A memo's bytes, given as hex, as UTF-8 text; "" for none, and for bytes
+ * that aren't UTF-8: an address or a hash is read from text only.
  *
  * @param {unknown} hex
  */
 function memoOf(hex) {
   const text = String(hex ?? "").replace(/^0x/i, "");
 
-  return /^(?:[0-9a-fA-F]{2})+$/.test(text) ? utf8.decode(Uint8Array.from(text.match(/../g) ?? [], (byte) => parseInt(byte, 16))) : "";
+  if (!/^(?:[0-9a-fA-F]{2})+$/.test(text)) return "";
+
+  try {
+    return utf8.decode(Uint8Array.from(text.match(/../g) ?? [], (byte) => parseInt(byte, 16)));
+  } catch {
+    return "";
+  }
 }
 
 /**
@@ -1366,10 +996,9 @@ async function transfersOf(archive, hashes, counter) {
  *
  * @param {Archive} archive
  * @param {ReadonlyArray<string>} hashes
- * @param {{ network?: Network, args?: boolean }} options
  * @param {{ requests: number }} counter
  */
-async function detailsOf(archive, hashes, { args = false, network }, counter) {
+async function detailsOf(archive, hashes, counter) {
   /** @type {Map<string, any>} */
   const out = new Map();
   const list = [...new Set(hashes)];
@@ -1379,12 +1008,161 @@ async function detailsOf(archive, hashes, { args = false, network }, counter) {
 
     counter.requests += 1;
 
-    for (const [hash, found] of await fetchTxDetails(archive, batch, { args: args ? new Set(batch) : undefined, network })) out.set(hash, found);
+    for (const [hash, found] of await fetchTxDetails(archive, batch)) out.set(hash, found);
+  }
+
+  return out;
+}
+
+/**
+ * A deposit's call, as `tx(hash) { blockHeight blockTimestamp err tx {
+ * callData { contractId fnName data } } }` gives it: whether it went
+ * through, its block's time, its function, and for a call of DuskEVM's
+ * bridge or Portal on Dusk, what it did (`bridge`, as `/history` reads it:
+ * null for one that isn't a deposit, a proof or a claim). Null for none.
+ *
+ * @param {Network} net
+ * @param {any} raw
+ * @returns {{ bridge?: { kind: string, amount?: string, to?: string } | null, fnName: string | undefined, success: boolean, timestamp: number | null } | null}
+ */
+function callOf(net, raw) {
+  if (!raw || typeof raw !== "object") return null;
+
+  const call = raw.tx?.callData;
+  const contractId = call?.contractId ? String(call.contractId) : undefined;
+  const fnName = call?.fnName ? String(call.fnName) : undefined;
+  const seconds = Number(raw.blockTimestamp);
+  /** @type {NonNullable<ReturnType<typeof callOf>>} */
+  const out = { fnName, success: !failedTx(raw), timestamp: Number.isFinite(seconds) && seconds > 0 ? seconds * 1000 : null };
+
+  if (isBridgeContract(net, contractId)) {
+    const done = decodeBridgeCall(net, { args: typeof call?.data === "string" ? call.data : null, contractId, fnName });
+
+    out.bridge = done === null ? null : done.kind === "deposit" ? { amount: String(done.amountLux), kind: "deposit", to: done.recipient } : { kind: done.kind };
   }
 
   return out;
 }
 
+/**
+ * Whether a transaction, as the archive gives it, failed.
+ *
+ * @param {any} raw
+ */
+const failedTx = (raw) => raw?.err !== null && raw?.err !== undefined && raw?.err !== "";
+
+/**
+ * A transaction's block height, as the archive gives it; null for none.
+ *
+ * @param {any} raw
+ */
+const heightIn = (raw) => (/^\d+$/.test(String(raw?.blockHeight)) ? heightOf(Number(raw.blockHeight)) : null);
+
+/**
+ * Whether a deposit's call, as `callOf` reads it, says all a match reads of
+ * it: its time, and that it failed, that it's another call of DuskEVM's
+ * bridge or Portal than a deposit, or a deposit's amount and DuskEVM
+ * address. One that doesn't, as one whose arguments the archive gave cut
+ * short, is asked for again: the archive may give it whole later.
+ *
+ * @param {ReturnType<typeof callOf>} call
+ */
+function decided(call) {
+  if (!call || call.timestamp === null) return false;
+  if (!call.success) return true;
+  // Not a call of the bridge's contracts, as the network names them.
+  if (call.bridge === undefined) return false;
+  if (call.bridge === null) return call.fnName !== undefined && call.fnName !== BRIDGE_FUNCTIONS.deposit;
+
+  return call.bridge.kind !== "deposit" || (luxOf(call.bridge.amount) !== null && addressOf(call.bridge.to) !== "");
+}
+
+/**
+ * The calls of deposits a sender's history lists, by hash, as `callOf` reads
+ * them: a batch a request, with the last finalized block. One that can't
+ * change any more, in a block at or under that one, and that says all a
+ * match reads of it (`decided`), is kept in the app's `cache`, by the
+ * network, its bridge and the transaction's hash, and isn't asked for
+ * again; others are asked for each time.
+ *
+ * @param {Archive} archive
+ * @param {Network} net
+ * @param {ReadonlyArray<string>} hashes
+ * @param {FactCache | undefined} cache
+ * @param {{ requests: number }} counter
+ * @returns {Promise<Map<string, NonNullable<ReturnType<typeof callOf>>>>}
+ */
+async function depositCalls(archive, net, hashes, cache, counter) {
+  /** @type {Map<string, NonNullable<ReturnType<typeof callOf>>>} */
+  const out = new Map();
+  /** @param {string} hash */
+  const keyOf = (hash) => `deposit:${net.chainId}:${duskEvmContracts(net)?.bridge ?? ""}:${hash}`;
+  /** @type {string[]} */
+  const missing = [];
+
+  for (const hash of new Set(hashes)) {
+    const kept = cache ? keptCall(net, cache, keyOf(hash), hash) : null;
+
+    if (kept) out.set(hash, kept);
+    else missing.push(hash);
+  }
+
+  for (let i = 0; i < missing.length; i += DETAILS_BATCH) {
+    const batch = missing.slice(i, i + DETAILS_BATCH);
+
+    counter.requests += 1;
+
+    const data = await archive.query(`query { pair: lastBlockPair { json } ${batch.map((hash, j) => `t${j}: tx(hash: "${hash}") { blockHeight blockTimestamp err tx { callData { contractId fnName data } } }`).join(" ")} }`);
+    const finalized = Number(data?.pair?.json?.last_finalized_block?.[0]);
+
+    batch.forEach((hash, j) => {
+      const raw = data?.[`t${j}`];
+      const call = callOf(net, raw);
+
+      if (!call) return;
+
+      out.set(hash, call);
+
+      const height = heightIn(raw);
+
+      if (cache && height !== null && Number.isSafeInteger(finalized) && height <= finalized && decided(call)) {
+        try {
+          cache.set(keyOf(hash), JSON.stringify({ hash, tx: raw }));
+        } catch {
+          // Not kept: asked for again next time.
+        }
+      }
+    });
+  }
+
+  return out;
+}
+
+/**
+ * A deposit's call kept in the app's cache, as `callOf` reads it; null where
+ * none is kept, or what is kept isn't this transaction's call, in a block,
+ * saying all a match reads of it.
+ *
+ * @param {Network} net
+ * @param {FactCache} cache
+ * @param {string} key
+ * @param {string} hash
+ */
+function keptCall(net, cache, key, hash) {
+  try {
+    const text = cache.get(key);
+
+    if (typeof text !== "string" || !text) return null;
+
+    const kept = JSON.parse(text);
+    const call = kept?.hash === hash && heightIn(kept.tx) !== null ? callOf(net, kept.tx) : null;
+
+    return decided(call) ? call : null;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * A transfer whose history is read: its hash, its Dusk block's time and
  * height, the block on the other chain its credit can't be before, and its
@@ -1512,17 +1290,18 @@ async function readHistories(archive, items, { account, direction, horizonMs, ke
  * (`to`, `amount`), from their calls: each with the block the app gave it
  * its credit can't be before; and those whose call or time the archive
  * doesn't give, which could be any deposit of up to what they paid, but
- * for one the app gave: its own facts tell. `calls` keeps each call read.
+ * for one the app gave: its own facts tell. `calls` keeps each call read,
+ * and the app's `cache` those that can't change any more.
  *
  * @param {Archive} archive
  * @param {Network} net
  * @param {ReadonlyArray<{ hash: string, height: number }>} found
- * @param {{ amount: bigint, to: string, bounds: ReadonlyMap<string, bigint | null>, calls: Map<string, any>, supplied: ReadonlyMap<string, DepositItem> }} group
+ * @param {{ amount: bigint, to: string, bounds: ReadonlyMap<string, bigint | null>, cache: FactCache | undefined, calls: Map<string, any>, supplied: ReadonlyMap<string, DepositItem> }} group
  * @param {{ requests: number }} counter
  */
-async function depositPeers(archive, net, found, { amount, bounds, calls, supplied, to }, counter) {
+async function depositPeers(archive, net, found, { amount, bounds, cache, calls, supplied, to }, counter) {
   const missing = found.flatMap((entry) => (calls.has(entry.hash) ? [] : [entry.hash]));
-  const read = await detailsOf(archive, missing, { args: true, network: net }, counter);
+  const read = await depositCalls(archive, net, missing, cache, counter);
 
   for (const hash of missing) calls.set(hash, read.get(hash) ?? null);
 
@@ -1613,39 +1392,6 @@ function withHistory(hash, arrival, given, states) {
 // Inputs
 // ---------------------------------------------------------------------------
 
-/**
- * A deposit as given, checked.
- *
- * @typedef {{ amount: bigint, at: number | null, hash: string, height: number | null, notBefore: bigint | null, scan: Scan | null, sender: string | null, to: string }} DepositItem
- */
-
-/**
- * @param {Deposit} deposit
- * @returns {DepositItem}
- */
-function depositIn(deposit) {
-  const hash = duskHashOf(deposit?.hash);
-  const amount = luxOf(deposit?.amount);
-  const to = addressOf(deposit?.to);
-  const sender = deposit?.sender ?? null;
-
-  if (!hash) throw new TypeError("A deposit's hash is its Dusk transaction's: 64 hex digits");
-  if (amount === null || amount === 0n) throw new TypeError("A deposit's amount is lux: more than 0, at most a u64");
-  if (!to) throw new TypeError("A deposit pays a DuskEVM address: 0x and 40 hex digits");
-  if (sender !== null && !isAccount(sender)) throw new TypeError("A deposit's sender is a Dusk account");
-
-  return {
-    amount,
-    at: msOf(deposit.at),
-    hash,
-    height: heightOf(deposit.height),
-    notBefore: quantityOf(deposit.notBefore),
-    scan: scanOf(deposit.scan),
-    sender: /** @type {string | null} */ (sender),
-    to,
-  };
-}
-
 /**
  * A transfer out as given, checked: its route, the fee the app gives where
  * it gives one, and where an earlier search stopped.
@@ -1685,63 +1431,6 @@ function transferIn(transfer, services) {
  */
 const horizonOf = (route) => Math.max(SERVICE_HORIZON_MS, 4 * (route.typicalSeconds ?? 0) * 1000);
 
-/**
- * @param {{ hash: string, at: number | null, notBefore: bigint | null, scan: Scan | null }} item
- * @returns {Queued}
- */
-const queued = (item) => ({ at: /** @type {number} */ (item.at), given: true, hash: item.hash, notBefore: item.notBefore, scan: item.scan });
-
-/**
- * Sorts out the transfers that aren't looked for: without their block's
- * time yet, waiting; sent longer ago than they're waited for, unknown.
- *
- * @template {{ hash: string, at: number | null }} T
- * @param {ReadonlyArray<T>} list
- * @param {Map<string, Arrival>} results
- * @param {{ now: number, waitMs: number }} options
- * @returns {T[]}
- */
-function triage(list, results, { now, waitMs }) {
-  /** @type {T[]} */
-  const live = [];
-
-  for (const item of list) {
-    if (item.at === null) results.set(item.hash, { state: "waiting" });
-    else if (now - item.at > waitMs) results.set(item.hash, { reason: "expired", state: "unknown" });
-    else live.push(item);
-  }
-
-  return live;
-}
-
-/**
- * Each item once, by hash: the first.
- *
- * @template {{ hash: string }} T
- * @param {ReadonlyArray<T>} list
- * @returns {T[]}
- */
-function uniqueByHash(list) {
-  const seen = new Set();
-
-  return list.filter((item) => !seen.has(item.hash) && Boolean(seen.add(item.hash)));
-}
-
-/**
- * The results in the order the transfers came.
- *
- * @param {ReadonlyArray<{ hash: string }>} list
- * @param {Map<string, Arrival>} results
- * @returns {Map<string, Arrival>}
- */
-const inOrder = (list, results) => new Map(list.map((item) => [item.hash, /** @type {Arrival} */ (results.get(item.hash))]));
-
-/**
- * @param {Iterable<string> | undefined} taken
- * @param {(value: unknown) => string} hashOf
- */
-const usedOf = (taken, hashOf) => new Set([...(taken ?? [])].map(hashOf).filter(Boolean));
-
 // ---------------------------------------------------------------------------
 // Deposits to DuskEVM
 // ---------------------------------------------------------------------------
@@ -1750,183 +1439,52 @@ const usedOf = (taken, hashOf) => new Set([...(taken ?? [])].map(hashOf).filter(
  * @param {DepositArrivalOptions} options
  * @returns {Promise<{ arrivals: Map<string, Arrival>, requests: number }>}
  */
-export async function depositArrivals({
-  network,
-  deposits,
-  via = "explorer",
-  fetch: fetchFn,
-  explorerUrl,
-  rpcUrl,
-  archive,
-  taken,
-  blockTimes,
-  now = Date.now(),
-  waitMs = WAIT_MS,
-  windowMs = CREDIT_WINDOW_MS,
-  maxPages = EXPLORER_PAGES,
-  maxWindows = LOG_WINDOWS,
-  timeoutMs = TIMEOUT_MS,
-}) {
+export async function depositArrivals(options) {
+  const {
+    network,
+    deposits,
+    via = "explorer",
+    fetch: fetchFn,
+    rpcUrl,
+    archive,
+    taken,
+    blockTimes,
+    cache,
+    now = Date.now(),
+    waitMs = WAIT_MS,
+    windowMs = CREDIT_WINDOW_MS,
+    maxWindows = LOG_WINDOWS,
+    timeoutMs = TIMEOUT_MS,
+  } = options;
+
   if (via !== "explorer" && via !== "rpc") throw new RangeError('A deposit is followed on the "explorer" or the "rpc"');
+  if (via === "explorer") return depositArrivalsFromExplorer(options);
 
-  const net = networkOf(network);
-  const list = uniqueByHash(Array.from(deposits ?? [], depositIn));
+  const { evm, list, live, net, past, results, used } = depositsIn({ deposits, network, now, taken, waitMs }, scanOf);
   const read = reader(fetchFn, timeoutMs);
-  /** @type {Map<string, Arrival>} */
-  const results = new Map();
-  const evm = net.duskEvm;
 
-  if (!evm) {
-    for (const item of list) results.set(item.hash, { reason: "no-route", state: "unknown" });
+  if (evm) {
+    const url = urlOf(rpcUrl, evm.rpcUrl, "DuskEVM RPC");
 
-    return { arrivals: inOrder(list, results), requests: 0 };
-  }
-
-  const used = usedOf(taken, evmHashOf);
-  const live = triage(list, results, { now, waitMs });
-  // Waited for too long: not looked for, though still before the newer ones.
-  const past = list.filter((item) => item.at !== null && now - item.at > waitMs);
-  const bridge = evm.predeploys.l2StandardBridge.toLowerCase();
-  const rules = { now, past, results, used, windowMs };
-
-  if (via === "explorer") {
-    await onExplorer(read, live, { ...rules, api: String(explorerUrl ?? evm.blockscoutApiUrl), bridge, maxPages });
-  } else {
-    await onRpc(read, live, { ...rules, archive, blockTimes, bridge, list, maxWindows, net, url: String(rpcUrl ?? evm.rpcUrl) });
+    await onRpc(read, live, { archive, blockTimes, bridge: evm.predeploys.l2StandardBridge.toLowerCase(), cache, list, maxWindows, net, now, past, results, url, used, windowMs });
   }
 
   return { arrivals: inOrder(list, results), requests: read.counter.requests };
 }
 
-/**
- * The L2 bridge's payments to an address, as DuskEVM's explorer lists its
- * incoming calls: newest first, a page at a time (the explorer's
- * `next_page_params`), back past `since`, at most `maxPages`. `complete`
- * once they reach it, or there are no more.
- *
- * @param {Reader} read
- * @param {{ api: string, bridge: string, maxPages: number, since: number, to: string }} ask
- * @returns {Promise<{ complete: boolean, payments: Credit[] }>}
- */
-async function explorerPayments(read, { api, bridge, maxPages, since, to }) {
-  const base = `${api.replace(/\/+$/, "")}/addresses/${to}/internal-transactions`;
-  /** @type {any[]} */
-  const items = [];
-  /** @type {Record<string, unknown> | null} */
-  let next = null;
-  let complete = false;
-
-  for (let page = 0; page < Math.max(1, Math.floor(maxPages)) && !complete; page += 1) {
-    const query = new URLSearchParams({ filter: "to" });
-
-    for (const [key, value] of Object.entries(next ?? {})) query.set(key, String(value));
-
-    const body = await read.getJson(`${base}?${query}`);
-    const calls = Array.isArray(body?.items) ? body.items : [];
-    const oldest = Math.min(...calls.map((/** @type {any} */ call) => timeOf(call?.timestamp)).filter(Number.isFinite));
-
-    items.push(...calls);
-    next = body?.next_page_params && typeof body.next_page_params === "object" ? body.next_page_params : null;
-    complete = !next || !calls.length || oldest < since;
-  }
-
-  /** @type {Map<string, Credit>} */
-  const payments = new Map();
-
-  for (const call of items) {
-    const hash = evmHashOf(call?.transaction_hash);
-    const at = timeOf(call?.timestamp);
-    const value = String(call?.value ?? "");
-    const payee = call?.to?.hash;
-
-    if (!hash || payments.has(hash) || !Number.isFinite(at) || !/^\d+$/.test(value)) continue;
-    if (String(call?.from?.hash ?? "").toLowerCase() !== bridge) continue;
-    if (payee !== undefined && payee !== null && String(payee).toLowerCase() !== to) continue;
-
-    payments.set(hash, { at, block: quantityOf(call?.block_number), from: null, hash, success: call?.success !== false, wei: BigInt(value) });
-  }
-
-  return { complete, payments: [...payments.values()] };
-}
-
-/**
- * Deposits followed on DuskEVM's explorer: each recipient's incoming calls
- * read once for all its deposits, and matched as where the credits can't be
- * told apart, as they don't say who deposited. Equal deposits past their
- * wait just before them take their payments first, their results kept.
- *
- * @param {Reader} read
- * @param {DepositItem[]} live
- * @param {{ api: string, bridge: string, maxPages: number, now: number, past: DepositItem[], results: Map<string, Arrival>, used: Set<string>, windowMs: number }} options
- */
-async function onExplorer(read, live, { api, bridge, maxPages, now, past, results, used, windowMs }) {
-  for (const [to, items] of groupBy(live, (item) => item.to)) {
-    const polled = new Set(items.map((item) => item.hash));
-    const groups = [...groupBy(items, (item) => item.amount.toString()).values()].map((group) => ({
-      queue: withPast(
-        group.map(queued),
-        past.filter((item) => item.to === to && item.amount === group[0].amount).map(queued),
-        windowMs
-      ),
-      wei: group[0].amount * WEI_PER_LUX,
-    }));
-
-    // Nothing can be told apart before a window is over: nothing is asked.
-    if (groups.every(({ queue }) => allOpen(queue, windowMs, now))) {
-      for (const item of items) results.set(item.hash, { state: "waiting" });
-      continue;
-    }
-
-    /** @type {{ complete: boolean, payments: Credit[] }} */
-    let page;
-
-    try {
-      page = await explorerPayments(read, { api, bridge, maxPages, since: Math.min(...groups.flatMap(({ queue }) => queue.map((item) => item.at))) - windowMs, to });
-    } catch (error) {
-      for (const item of items) results.set(item.hash, { error: messageOf(error), reason: "error", state: "unknown" });
-      continue;
-    }
-
-    // Not back to the oldest: a payment of an older one may be a newer one's.
-    if (!page.complete) {
-      for (const item of items) results.set(item.hash, { reason: "beyond", state: "unknown" });
-      continue;
-    }
-
-    for (const { queue, wei } of groups) {
-      const { assigned, verdicts } = settle(
-        queue,
-        page.payments.filter((payment) => payment.wei === wei),
-        { guarded: true, now, slackMs: windowMs, used, windowMs }
-      );
-
-      for (const item of queue.filter((each) => polled.has(each.hash))) {
-        const credit = assigned.get(item.hash);
-        const verdict = verdicts.get(item.hash);
-
-        if (credit && verdict === "arrived") {
-          used.add(credit.hash);
-          results.set(item.hash, { amount: credit.wei / WEI_PER_LUX, at: credit.at, block: credit.block === null ? null : Number(credit.block), hash: credit.hash, state: "arrived" });
-        } else {
-          results.set(item.hash, verdict === "waiting" ? { state: "waiting" } : { reason: verdict === "unsure" ? "unsure" : "late", state: "unknown" });
-        }
-      }
-    }
-  }
-}
-
 /**
  * Deposits followed on DuskEVM's RPC, by the bridge's events from each
  * sender's DuskEVM address: a group of equal deposits from one sender at a
  * time, with the sender's equal deposits shortly before, from its history,
- * when there's an archive; without it, with the equal ones given that are
- * past their wait just before them.
+ * when there's an archive and the network names DuskEVM's bridge on Dusk;
+ * without them, or while the archive can't be read, with the equal ones
+ * given that are past their wait just before them.
  *
  * @param {Reader} read
  * @param {DepositItem[]} live
- * @param {{ archive: Archive | undefined, blockTimes: BlockTimes | undefined, bridge: string, list: DepositItem[], maxWindows: number, net: Network, now: number, past: DepositItem[], results: Map<string, Arrival>, url: string, used: Set<string>, windowMs: number }} options
+ * @param {{ archive: Archive | undefined, blockTimes: BlockTimes | undefined, bridge: string, cache: FactCache | undefined, list: DepositItem[], maxWindows: number, net: Network, now: number, past: DepositItem[], results: Map<string, Arrival>, url: string, used: Set<string>, windowMs: number }} options
  */
-async function onRpc(read, live, { archive, blockTimes, bridge, list, maxWindows, net, now, past, results, url, used, windowMs }) {
+async function onRpc(read, live, { archive, blockTimes, bridge, cache, list, maxWindows, net, now, past, results, url, used, windowMs }) {
   // Equal deposits (the same DuskEVM address and amount) from a known sender
   // first, a sender at a time, its events telling its credits apart; then
   // those whose sender isn't known, which take none from the senders of the
@@ -1963,58 +1521,66 @@ async function onRpc(read, live, { archive, blockTimes, bridge, list, maxWindows
   const supplied = new Map(list.map((item) => [item.hash, item]));
   /** @type {Map<string, any>} */
   const calls = new Map();
-  const contract = duskEvmContracts(net)?.bridge;
+  // DuskEVM's bridge on Dusk, which a sender's history lists its deposits to.
+  const contract = duskEvmContracts(net)?.bridge ?? null;
 
   for (const { items, rivals } of [...known, ...unknown]) {
     const { amount, sender, to } = items[0];
-    const vouched = Boolean(archive) && sender !== null && items.every((item) => item.height !== null);
     let given = items.map(queued).sort(byTime);
     /** @type {Queued[]} */
-    let queue;
+    let queue = [];
     /** @type {Set<string>} */
     const unsure = new Set();
     /** @type {Map<string, HistoryScan>} */
     let states = new Map();
+    // Whether the sender's history tells its equal deposits' order.
+    let vouched = false;
 
-    if (vouched) {
+    if (archive && contract && sender !== null && items.every((item) => item.height !== null)) {
       // Each deposit's own hours of its sender's history, with its sender's
       // equal deposits there, the app's no longer looked for among them.
-      /** @type {Awaited<ReturnType<typeof readHistories>>} */
-      let history;
+      /** @type {Awaited<ReturnType<typeof readHistories>> | null} */
+      let history = null;
 
       try {
         history = await readHistories(
-          /** @type {Archive} */ (archive),
+          archive,
           /** @type {Reading[]} */ ([...items].sort((a, b) => /** @type {number} */ (a.height) - /** @type {number} */ (b.height))),
           {
-            account: /** @type {string} */ (sender),
+            account: sender,
             direction: "out",
             horizonMs: DEPOSIT_HORIZON_MS,
             keep: (entry) => entry.counterparty === contract && entry.value >= amount,
             of: (item) => `${sender}:${item.height}:${amount}`,
             pages: HISTORY_PAGES,
-            peersOf: (found) => depositPeers(/** @type {Archive} */ (archive), net, found, { amount, bounds, calls, supplied, to }, read.counter),
+            peersOf: (found) => depositPeers(archive, net, found, { amount, bounds, cache, calls, supplied, to }, read.counter),
             reach: Math.ceil((3 * DEPOSIT_HORIZON_MS) / DUSK_BLOCK_MS),
           },
           read.counter
         );
-      } catch (error) {
-        for (const item of items) results.set(item.hash, { error: messageOf(error), reason: "error", state: "unknown" });
-        continue;
+      } catch {
+        // The archive can't be read now: followed as without it, its history
+        // read on by a later call from where it stopped.
+        states = new Map(items.flatMap((item) => (item.scan?.history ? [[item.hash, item.scan.history]] : [])));
       }
 
-      states = history.states;
-      waitForHistory(items, history, results);
+      if (history) {
+        vouched = true;
+        states = history.states;
+        waitForHistory(items, history, results);
 
-      if (!history.covered.length) continue;
+        if (!history.covered.length) continue;
 
-      given = history.given;
-      queue = history.queue;
+        given = history.given;
+        queue = history.queue;
 
-      // One before it whose call can't be read could be equal: the credits'
-      // order can't be told.
-      for (const item of given) if (/** @type {number[]} */ (history.unread.get(item.hash)).length) unsure.add(item.hash);
-    } else {
+        // One before it whose call can't be read could be equal: the credits'
+        // order can't be told.
+        for (const item of given) if (/** @type {number[]} */ (history.unread.get(item.hash)).length) unsure.add(item.hash);
+      }
+    }
+
+    if (!vouched) {
       queue = withPast(
         given,
         past.filter((item) => item.to === to && item.amount === amount && item.sender === sender).map(queued),
@@ -2363,7 +1929,7 @@ export async function migrationPayouts({ network, migrations, entries, archive,
       const listed = await byMemo(archive, asked.map((item) => item.hash), counter);
       const found = [...listed.values()].flat().flatMap((raw) => payoutsIn(raw, /** @type {string} */ (account), net));
       // Their times, and whether they went through.
-      const details = await detailsOf(archive, found.map((payout) => payout.payout), {}, counter);
+      const details = await detailsOf(archive, found.map((payout) => payout.payout), counter);
 
       candidates = found.flatMap((payout) => {
         const known = details.get(payout.payout);
@@ -2451,8 +2017,9 @@ export function serviceTransferOf(entry, network) {
   const spent = luxOf(entry.gasSpent);
   const price = luxOf(entry.gasPrice);
   const amount = limit !== null && spent !== null && price !== null && (limit - spent) * price <= 0n ? value : null;
-  // The address the memo gives, exactly as the bridge reads it.
-  const memo = typeof entry.memo === "string" ? entry.memo : "";
+  // The address the memo gives, exactly as the bridge reads it: from text.
+  // A memo of bytes that aren't text, which /history gives as 0x hex, gives none.
+  const memo = typeof entry.memo === "string" && entry.memoBinary !== true ? entry.memo : "";
   const to = EVM_ADDRESS.test(memo) ? memo : null;
   const problem = entry.success === false ? "failed" : value <= route.feeLux ? "under-fee" : to === null ? "no-address" : null;
 
@@ -2470,9 +2037,8 @@ export function migrationPayoutOf(entry, network) {
   const { at, hash, height, value } = factsOf(entry);
   // What the transfer paid: a gas refund paid to the account with it aside.
   const refund = entry?.refund === undefined || entry.refund === null ? 0n : luxOf(entry.refund);
-  const memo = String(entry?.memo ?? "")
-    .trim()
-    .toLowerCase();
+  // The migration's hash, as text: a memo of bytes that aren't text names none.
+  const memo = entry?.memoBinary === true ? "" : String(entry?.memo ?? "").trim().toLowerCase();
 
   if (!paying.length || entry.success === false || !hash || height === null || value === null || refund === null || refund > value || !EVM_HASH.test(memo)) {
     return null;
@@ -2500,4 +2066,4 @@ export function arrivalsOf(arrivals) {
   for (const [hash, arrival] of arrivals) if (arrival.state === "arrived") out.set(hash, { at: arrival.at, hash: arrival.hash });
 
   return out;
-}
+}