@dusk-network/app-core 0.3.0 → 0.3.1

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 All notable changes to this package are listed here. It follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and [Semantic Versioning](https://semver.org/).
 
+## [0.3.1]
+
+### Added
+
+- `/history`: `historyRange` reads on from a `page`
+
+### Fixed
+
+- `/bridge`: each transfer reads only its own hours of its account's history, read on from its `scan` while a call can't read it all: it waits then, rather than staying unsure
+- `/bridge`: a transfer the archive doesn't list in its account's history yet waits, rather than taking an earlier one's credit
+- `/bridge`: a deposit whose call's arguments the archive doesn't give counts as one that could be equal, rather than none
+
 ## [0.3.0]
 
 ### Added

package/README.md

@@ -98,7 +98,7 @@ const history = createHistory({
 
 ### Other reads
 
-- `historyRange(archive, { account, from, to, direction, pages })`: an account's entries between two heights, a page at a time.
+- `historyRange(archive, { account, from, to, direction, pages, page })`: an account's entries between two heights, a page at a time, from `page` on.
 - `fetchTxDetails(archive, hashes, options)` and `fetchTxNonce(archive, hash)`: a transaction's time, outcome, fee and call, and its nonce.
 - `archive.query(text)`: one GraphQL request, its integers past 2^53 kept as text. A request answered 429, 502, 503 or 504 is sent again, twice at most.
 
@@ -201,9 +201,10 @@ arrivalsOf(arrivals); // Map { hash => { hash: "0x029e…", at: 1793080333000 }
 - Each credit pays one transfer. Equal transfers (the same route, recipient and payout) are paid in the order they were sent: the oldest takes the first credit after it, from 2 minutes before its block, as the chains' clocks differ. The app passes the transfers it still waits for, and the credits its others arrived with (`taken`): none of those pays a waiting one, though an earlier transfer read from the chain takes its own back, as one given but not looked for does.
 - A transfer's time is its Dusk block's, never the device's clock. One without it yet isn't looked for. One sent more than a week ago (`waitMs`) is unknown, and isn't asked about.
 - A deposit is followed on DuskEVM's explorer (`via: "explorer"`, the default): the recipient's incoming calls, newest first, read once for all its deposits, back past the oldest, 5 pages at most. Those calls don't say who deposited, so a payment is a deposit's only when it can't be another's: within 2 minutes either side of its block, once those minutes are over, with no other payment of its amount there (a failed one counts) that isn't another given deposit's. Nothing is asked before then.
-- On DuskEVM's RPC (`via: "rpc"`), a deposit is found by DuskEVM's bridge event from its sender's DuskEVM address. With `/history`'s archive, each sender's equal deposits in the hours before its own are read from its history and paid first; a history too long to read, or a deposit there whose call can't be read, leaves the order unclear. Without it, the RPC's credits are taken as the explorer's are. A deposit given without its sender takes no credit from the sender of another equal one given.
+- On DuskEVM's RPC (`via: "rpc"`), a deposit is found by DuskEVM's bridge event from its sender's DuskEVM address. With `/history`'s archive, each sender's equal deposits in the hours before its own are read from its history and paid first; a deposit there whose call can't be read leaves the order unclear. Without it, the RPC's credits are taken as the explorer's are. A deposit given without its sender takes no credit from the sender of another equal one given.
 - A migration is paid by a transfer to the account from its route's payout account, with the migration's transaction hash as the memo, of exactly its amount: from the account's entries, less any `refund` paid to the account with it, or from the archive's memo index, which gives each payout's own amount. One from that account of another amount leaves it unsure, not waiting: the value of an entry an earlier version kept holds any gas refund paid to the account. With `entries`, the payouts there of migrations the app didn't list come too (`unlisted`), each with its `payer`; where one account pays out more than one route, a payout of a migration not listed doesn't say which: its `route` is null.
-- A transfer out is read from the chain: what the route's account received, the address its memo gives as the route's bridge reads it (0x and 40 hex digits, any case, nothing around them), and its block. It arrives with the DUSK token's `Transfer` from its route's payout address to that address, of what the account received less the fee. The account's history lists every transfer that named the same address, in any case: equal ones in the hours before (a given one's by its own fee) are paid first, and one that can't be read, or a history cut short, leaves the order unclear. One that pays nothing out is `no-payout`, with its `problem`. `serviceTransferOf` gives what left the account (`sent`), and what the account received (`amount`) only where no gas was left to refund: an entry's value holds any refund paid to another account.
+- A transfer out is read from the chain: what the route's account received, the address its memo gives as the route's bridge reads it (0x and 40 hex digits, any case, nothing around them), and its block. It arrives with the DUSK token's `Transfer` from its route's payout address to that address, of what the account received less the fee. The account's history lists every transfer that named the same address, in any case: equal ones in the hours before (a given one's by its own fee) are paid first, and one that can't be read leaves the order unclear. One that pays nothing out is `no-payout`, with its `problem`. `serviceTransferOf` gives what left the account (`sent`), and what the account received (`amount`) only where no gas was left to refund: an entry's value holds any refund paid to another account.
+- With the archive, each transfer reads only its own hours of its account's history (its sender's for a deposit, the route's account's for a transfer out), further back while equal ones before it run on, and only once the archive lists the transfer there. A call reads 4 pages of it (`HISTORY_PAGES`) for each: a transfer whose history is longer waits, and the next call reads on from its `scan`.
 - A route without its payout account or address in the network's file pays out nothing that can be told apart: `no-route`.
 - An RPC search starts at a block from before the transfer, estimated from the chain's pace and checked by its time, and reads 8 windows of 5,000 blocks at most, narrower where the RPC asks for it. A result that isn't arrived says where the next search starts, with what it searched for and the credits found so far (`scan`): the app keeps it with the arrivals it was made with, and passes both back. A search for another sender or amount starts afresh.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dusk-network/app-core",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Shared logic for the Dusk apps: public and shielded history, activity rows, bridge arrivals and DuskEVM withdrawals.",
   "license": "MPL-2.0",
   "type": "module",

package/src/bridge.d.ts

@@ -85,7 +85,7 @@ export declare const DEPOSIT_HORIZON_MS: 7200000;
 /** Equal transfers out sent within this of each other are paid in their order, or 4 times the route's usual time: 12 hours, in milliseconds. */
 export declare const SERVICE_HORIZON_MS: 43200000;
 
-/** Pages of a sender's history read for its earlier equal deposits. */
+/** Pages of its account's history one call reads for a transfer's earlier equal ones; a longer history is read on in the next call, from its `scan`. */
 export declare const HISTORY_PAGES: 4;
 
 /** `Transfer(address,address,uint256)`: the DUSK token's transfer that pays a transfer out. */
@@ -94,15 +94,37 @@ export declare const TRANSFER_TOPIC: "0xddf252ad1be2c89b69c2b068fc378daa952ba7f1
 /** `ETHBridgeFinalized(address,address,uint256,bytes)`: DuskEVM's bridge paying a deposit, from the depositor's DuskEVM address. */
 export declare const ETH_BRIDGE_FINALIZED_TOPIC: "0x31b2166ff604fc5672ea5df08a78081d2bc6d746cadce880747f3643d819e83d";
 
+/**
+ * How far a transfer's own history is read: what it was read for (`of`),
+ * all of it from `lo` up to the transfer's block once `lo` is set, the
+ * range read next (`next`: its first block, its last and the page it
+ * carries on from), and the transfers found in it that could be equal to
+ * it, each with what it paid, in lux (`value`).
+ */
+export type HistoryScan = {
+  of: string;
+  lo: number | null;
+  next: { from: number; to: number; page: number } | null;
+  found: ReadonlyArray<{ hash: string; height: number; value: string }>;
+};
+
 /**
  * Where a search stopped: the block the next one starts at, the time of the
  * transfer it began from, the logs it searched for (`search`), and the
  * credits it found before (`seen`), which the next one counts again. A
  * search for other logs, as for another sender or amount, starts afresh.
- * Kept by the app with the credits it was made with, and passed back as it
- * is.
+ * With the archive, how far the transfer's own history is read
+ * (`history`): a history longer than one call reads is read on from there,
+ * before any search. Kept by the app with the credits it was made with,
+ * and passed back as it is.
  */
-export type Scan = { from: string; basis: number; search: string; seen?: ReadonlyArray<{ hash: string; block: string; at: number; sender: string | null }> };
+export type Scan = {
+  from?: string;
+  basis?: number;
+  search?: string;
+  seen?: ReadonlyArray<{ hash: string; block: string; at: number; sender: string | null }>;
+  history?: HistoryScan;
+};
 
 /**
  * Why a transfer's credit is unknown:
@@ -190,7 +212,9 @@ export type DepositArrivalOptions = {
   /**
    * `/history`'s archive, for "rpc": each sender's equal deposits in the
    * hours before its own are read from its history, those given but not
-   * looked for too, and paid first.
+   * looked for too, and paid first. Each deposit reads its own hours, once
+   * the archive lists it there, `HISTORY_PAGES` pages a call: a deposit
+   * whose history is read on in the next call waits, with its `scan`.
    * Without it, or for a deposit without its sender and height, its credit
    * is a deposit's only as where they can't be told apart.
    */
@@ -279,9 +303,12 @@ export type ServiceArrivalOptions = {
  * route's account received in the hours before that named the same address,
  * in any case, and pay out the same are paid first: its history lists them,
  * and their own transactions say what each received (one given but not
- * looked for pays out what its own fee leaves). One that can't be
- * read, or a history cut short, leaves the order unclear: unsure. Throws a
- * TypeError without an archive, and for a network there's no file for.
+ * looked for pays out what its own fee leaves). One that can't be read
+ * leaves the order unclear: unsure. Each transfer reads its own hours of
+ * that history, once the archive lists it there, `HISTORY_PAGES` pages a
+ * call: one whose history is read on in the next call waits, with its
+ * `scan`. Throws a TypeError without an archive, and for a network there's
+ * no file for.
  */
 export declare function serviceArrivals(options: ServiceArrivalOptions): Promise<{ arrivals: Map<string, Arrival>; requests: number }>;
 

package/src/bridge.js

@@ -12,7 +12,7 @@
 
 import { networkFor, routeForAccount, routes } from "@dusk-network/networks";
 import { isAccount } from "@dusk-network/networks/account";
-import { duskEvmContracts, evmAddressOf } from "@dusk-network/networks/duskevm";
+import { BRIDGE_FUNCTIONS, duskEvmContracts, evmAddressOf } from "@dusk-network/networks/duskevm";
 import { DETAILS_BATCH, TRANSFER_CONTRACT, fetchTxDetails, historyRange } from "./history.js";
 
 /** @typedef {import("./bridge.js").Arrival} Arrival */
@@ -21,6 +21,7 @@ import { DETAILS_BATCH, TRANSFER_CONTRACT, fetchTxDetails, historyRange } from "
 /** @typedef {import("./bridge.js").DepositArrivalOptions} DepositArrivalOptions */
 /** @typedef {import("./bridge.js").FetchLike} FetchLike */
 /** @typedef {import("./bridge.js").HistoryLike} HistoryLike */
+/** @typedef {import("./bridge.js").HistoryScan} HistoryScan */
 /** @typedef {import("./bridge.js").Migration} Migration */
 /** @typedef {import("./bridge.js").MigrationPayout} MigrationPayout */
 /** @typedef {import("./bridge.js").MigrationPayoutOptions} MigrationPayoutOptions */
@@ -199,9 +200,42 @@ const msOf = (value) => (typeof value === "number" && Number.isFinite(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.
+ *
+ * @param {unknown} value
+ * @returns {HistoryScan | null}
+ */
+function historyScanOf(value) {
+  const read = /** @type {any} */ (value);
+
+  if (!read || typeof read !== "object" || typeof read.of !== "string" || !Array.isArray(read.found)) return null;
+
+  const lo = read.lo === null ? null : heightOf(read.lo);
+  const next = read.next === null ? null : { from: heightOf(read.next?.from), page: heightOf(read.next?.page), to: heightOf(read.next?.to) };
+
+  if ((read.lo !== null && lo === null) || (lo === null && next === null)) return null;
+  if (next && (next.from === null || next.to === null || next.page === null || next.page < 1 || next.from > next.to)) return null;
+
+  const found = read.found.flatMap((/** @type {any} */ each) => {
+    const hash = duskHashOf(each?.hash);
+    const height = heightOf(each?.height);
+    const value = each?.value;
+
+    return hash && height !== null && typeof value === "string" && /^\d{1,20}$/.test(value) ? [{ hash, height, value }] : [];
+  });
+
+  // One left out could be equal: it's read afresh.
+  if (found.length !== read.found.length) return null;
+
+  return { found, lo, next: /** @type {HistoryScan["next"]} */ (next), of: read.of };
+}
+
 /**
  * Where a search stopped, what it searched for, and the credits it found
- * before, as a result gave them; null for anything else.
+ * before, and how far the transfer's history is read, as a result gave
+ * them; null for anything else.
  *
  * @param {unknown} value
  * @returns {Scan | null}
@@ -209,19 +243,26 @@ const heightOf = (value) => (typeof value === "number" && Number.isSafeInteger(v
 function scanOf(value) {
   const scan = /** @type {any} */ (value);
   const from = quantityOf(scan?.from);
+  const history = historyScanOf(scan?.history);
+  /** @type {Scan} */
+  const out = history ? { history } : {};
 
-  if (from === null || typeof scan?.basis !== "number" || !Number.isFinite(scan.basis) || typeof scan.search !== "string") return null;
+  if (from !== null && typeof scan?.basis === "number" && Number.isFinite(scan.basis) && typeof scan.search === "string") {
+    const seen = (Array.isArray(scan.seen) ? scan.seen : []).flatMap((/** @type {any} */ credit) => {
+      const hash = evmHashOf(credit?.hash);
+      const block = quantityOf(credit?.block);
+      const at = msOf(credit?.at);
+      const sender = credit?.sender === null ? null : addressOf(credit?.sender);
 
-  const seen = (Array.isArray(scan.seen) ? scan.seen : []).flatMap((/** @type {any} */ credit) => {
-    const hash = evmHashOf(credit?.hash);
-    const block = quantityOf(credit?.block);
-    const at = msOf(credit?.at);
-    const sender = credit?.sender === null ? null : addressOf(credit?.sender);
+      return hash && block !== null && at !== null && sender !== "" ? [{ at, block: block.toString(), hash, sender }] : [];
+    });
 
-    return hash && block !== null && at !== null && sender !== "" ? [{ at, block: block.toString(), hash, sender }] : [];
-  });
+    Object.assign(out, { basis: scan.basis, from: from.toString(), search: scan.search, seen });
+  } else if (!history) {
+    return null;
+  }
 
-  return { basis: scan.basis, from: from.toString(), search: scan.search, seen };
+  return out;
 }
 
 /**
@@ -780,7 +821,10 @@ async function followLogs(read, { filter, given, guarded, queue, rivals, unsure
   // The logs searched for: a search for others, as for another sender or
   // amount, isn't carried on.
   const search = [filter.address, ...filter.topics.map((topic) => topic ?? "*"), filter.wei.toString()].join(":");
-  const resumed = live.flatMap((item) => (item.scan && item.scan.search === search && item.scan.basis <= first.at ? [item.scan] : []));
+  /** @type {{ basis: number, from: string, seen?: Scan["seen"] }[]} */
+  const resumed = live.flatMap(({ scan }) =>
+    scan?.from !== undefined && scan.search === search && scan.basis !== undefined && scan.basis <= first.at ? [{ basis: scan.basis, from: scan.from, seen: scan.seen }] : []
+  );
   /** @type {Map<string, Credit>} */
   const carried = new Map();
 
@@ -797,9 +841,18 @@ async function followLogs(read, { filter, given, guarded, queue, rivals, unsure
   /** @type {bigint} */
   let start;
 
-  if (resumed.length) {
+  if (resumed.length && resumed.every((scan) => scan.basis === first.at)) {
     start = minOf(resumed.map((scan) => BigInt(scan.from)));
     head = await headOf(read, url);
+  } else if (resumed.length) {
+    // Begun from a transfer before the first now, as one that since
+    // arrived: none of the queue's credits is before where a search from
+    // the first starts, which it skips to.
+    const from = minOf(resumed.map((scan) => BigInt(scan.from)));
+    const fresh = first.notBefore !== null ? { head: await headOf(read, url), start: first.notBefore } : await startBefore(read, url, reach, blockTimes);
+
+    head = fresh.head;
+    start = from > fresh.start ? from : fresh.start;
   } else if (first.notBefore !== null) {
     start = first.notBefore;
     head = await headOf(read, url);
@@ -1016,50 +1069,214 @@ async function detailsOf(archive, hashes, { args = false, network }, counter) {
 }
 
 /**
- * A sender's deposits to DuskEVM between two heights, from its history and
- * their calls: amount, DuskEVM address and time, but those `skip` names,
- * which are looked for. Only those of at least `least` lux are read: what
- * an account paid the bridge is its deposit and any gas refund it paid
- * another account. Those whose call or time the archive doesn't give are
- * `unresolved`: they could be any deposit of up to what they paid.
+ * 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
+ * scan.
+ *
+ * @typedef {{ hash: string, at: number, height: number, notBefore: bigint | null, scan: Scan | null }} Reading
+ */
+
+/**
+ * The history a group of equal transfers needs, each transfer's read on
+ * from where its scan stopped: its account's history from `reach` blocks
+ * under its block up to it, and `reach` further down at a time while the
+ * run of equal transfers it is in reaches within `horizonMs` of the bottom.
+ * The transfer itself must be listed there: until it is, the archive
+ * hasn't read its block. Each transfer reads `pages` pages at most, so a
+ * later one's history never keeps an earlier one waiting.
+ *
+ * Those whose history is all read are `covered`, and `given` as the queue
+ * holds them, with `queue`: theirs and the equal transfers found
+ * (`peersOf`), and `unread`: by transfer, the heights it read of those that
+ * could be equal but can't be read. Each one's reading, done or not, is in
+ * `states`.
+ *
+ * @param {Archive} archive
+ * @param {ReadonlyArray<Reading>} items
+ * @param {{ account: string, direction: "in" | "out", horizonMs: number, reach: number, pages: number, keep: (entry: HistoryEntry) => boolean, of: (item: Reading) => string, peersOf: (found: HistoryScan["found"]) => Promise<{ peers: Queued[], unread: ReadonlyArray<{ hash: string, height: number }> }> }} read
+ * @param {{ requests: number }} counter
+ */
+async function readHistories(archive, items, { account, direction, horizonMs, keep, of, pages, peersOf, reach }, counter) {
+  const walks = items.map((item) => {
+    const kept = item.scan?.history;
+    /** @type {HistoryScan} */
+    const state =
+      kept && kept.of === of(item)
+        ? structuredClone(/** @type {HistoryScan} */ (kept))
+        : { found: [], lo: null, next: { from: Math.max(0, item.height - reach), page: 1, to: item.height }, of: of(item) };
+
+    return { item, left: pages, state };
+  });
+  /** @type {Reading[]} */
+  let covered = [];
+  /** @type {Queued[]} */
+  let given = [];
+  /** @type {Queued[]} */
+  let queue = [];
+  /** @type {Map<string, number[]>} */
+  const unread = new Map();
+
+  for (;;) {
+    // Each one's next range, as far as its pages go.
+    for (const walk of walks) {
+      const { state } = walk;
+
+      while (state.next && walk.left > 0) {
+        const next = /** @type {NonNullable<HistoryScan["next"]>} */ (state.next);
+        const range = await historyRange(archive, { account, direction, from: next.from, page: next.page, pages: walk.left, to: next.to });
+        const found = /** @type {HistoryScan["found"][number][]} */ (state.found);
+
+        counter.requests += range.requests;
+        walk.left -= range.requests;
+
+        for (const entry of range.entries) {
+          if (keep(entry) && !found.some((each) => each.hash === entry.hash)) found.push({ hash: entry.hash, height: entry.blockHeight, value: String(entry.value) });
+        }
+
+        if (!range.complete) {
+          state.next = { ...next, page: next.page + range.requests };
+        } else if (state.lo === null && !found.some((each) => each.hash === walk.item.hash)) {
+          // Its own block isn't read yet: its last page is read again.
+          state.next = { ...next, page: next.page + range.requests - 1 };
+          walk.left = 0;
+        } else {
+          state.lo = next.from;
+          state.next = null;
+        }
+      }
+    }
+
+    const done = walks.filter((walk) => !walk.state.next);
+
+    if (!done.length) {
+      covered = [];
+      given = [];
+      break;
+    }
+
+    given = done.map((walk) => queued(walk.item)).sort(byTime);
+
+    const mine = new Set(given.map((item) => item.hash));
+    // The others found: those given are in the queue as they are.
+    const { peers, unread: unknown } = await peersOf(uniqueByHash(done.flatMap((walk) => walk.state.found)).filter((entry) => !mine.has(entry.hash)));
+    let deeper = false;
+
+    queue = queueOf(given, peers, horizonMs);
+
+    // A run reaching within a horizon of the bottom may go on under it: the
+    // history is read further down.
+    for (const walk of done) {
+      const lo = /** @type {number} */ (walk.state.lo);
+      const bottomAt = lo === 0 ? -Infinity : walk.item.at - (walk.item.height - lo) * DUSK_BLOCK_MS;
+      const self = /** @type {Queued} */ (given.find((each) => each.hash === walk.item.hash));
+
+      if (runStart(queue, self, horizonMs).at - bottomAt < horizonMs) {
+        walk.state.next = { from: Math.max(0, lo - reach), page: 1, to: lo - 1 };
+        deeper = true;
+      } else {
+        unread.set(
+          walk.item.hash,
+          unknown.flatMap((each) => (each.height >= lo && each.height <= walk.item.height ? [each.height] : []))
+        );
+      }
+    }
+
+    if (!deeper) {
+      covered = done.map((walk) => walk.item);
+      break;
+    }
+  }
+
+  return { covered, given, queue, states: new Map(walks.map((walk) => [walk.item.hash, walk.state])), unread };
+}
+
+/**
+ * Of the deposits a sender's history lists, those equal to the group's
+ * (`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.
  *
  * @param {Archive} archive
  * @param {Network} net
- * @param {{ sender: string, from: number, to: number, least: bigint, skip: ReadonlySet<string> }} range
+ * @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 {{ requests: number }} counter
  */
-async function senderDeposits(archive, net, { from, least, sender, skip, to }, counter) {
-  const bridge = duskEvmContracts(net)?.bridge;
-  const read = await historyRange(archive, { account: sender, direction: "out", from, pages: HISTORY_PAGES, to });
+async function depositPeers(archive, net, found, { amount, bounds, 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);
 
-  counter.requests += read.requests;
+  for (const hash of missing) calls.set(hash, read.get(hash) ?? null);
 
-  // A history cut short leaves its deposits' order unclear: nothing more is read.
-  if (!read.complete) return { complete: false, deposits: [], unresolved: [] };
+  /** @type {Queued[]} */
+  const peers = [];
+  /** @type {{ hash: string, height: number }[]} */
+  const unread = [];
 
-  const candidates = read.entries.filter((entry) => entry.counterparty === bridge && !skip.has(entry.hash) && entry.value >= least);
-  const details = await detailsOf(archive, candidates.map((entry) => entry.hash), { args: true, network: net }, counter);
-  /** @type {{ amount: bigint, at: number, hash: string, height: number, to: string }[]} */
-  const deposits = [];
-  /** @type {{ hash: string, height: number, value: bigint }[]} */
-  const unresolved = [];
+  for (const entry of found) {
+    const call = calls.get(entry.hash);
+    const bridged = call?.bridge;
 
-  for (const entry of candidates) {
-    const found = details.get(entry.hash);
-    const bridged = found?.bridge;
+    // Failed, or a call that isn't a deposit: no DUSK left for DuskEVM. A
+    // deposit whose arguments can't be read could be any.
+    if (call?.success === false || (bridged && bridged.kind !== "deposit") || (bridged === null && call?.fnName !== BRIDGE_FUNCTIONS.deposit)) continue;
 
-    // Failed, or a call that isn't a deposit: no DUSK left for DuskEVM.
-    if (found?.success === false || bridged === null || (bridged && bridged.kind !== "deposit")) continue;
+    const own = supplied.get(entry.hash);
+    let at = msOf(call?.timestamp);
+    let paid = luxOf(bridged?.amount);
+    let recipient = addressOf(bridged?.to);
 
-    const at = msOf(found?.timestamp);
-    const amount = luxOf(bridged?.amount);
-    const recipient = addressOf(bridged?.to);
+    // One the app gave whose call can't be read: its own facts.
+    if (own && (!call || at === null || paid === null || !recipient)) ({ amount: paid, at, to: recipient } = own);
 
-    if (found && at !== null && amount !== null && recipient) deposits.push({ amount, at, hash: entry.hash, height: entry.blockHeight, to: recipient });
-    else unresolved.push({ hash: entry.hash, height: entry.blockHeight, value: entry.value });
+    if (at === null || paid === null || !recipient) unread.push(entry);
+    else if (recipient === to && paid === amount) peers.push({ at, given: false, hash: entry.hash, notBefore: bounds.get(entry.hash) ?? null, scan: null });
   }
 
-  return { complete: true, deposits, unresolved };
+  return { peers, unread };
+}
+
+/**
+ * Where a scan's search stopped, without its history.
+ *
+ * @param {Scan | null | undefined} scan
+ * @returns {Scan}
+ */
+const searchOf = (scan) => (scan?.from !== undefined ? { basis: scan.basis, from: scan.from, search: scan.search, seen: scan.seen } : {});
+
+/**
+ * The transfers whose history isn't all read yet wait, with where their
+ * reading stopped beside where their last search did.
+ *
+ * @param {ReadonlyArray<{ hash: string, scan: Scan | null }>} items
+ * @param {{ covered: ReadonlyArray<{ hash: string }>, states: ReadonlyMap<string, HistoryScan> }} history
+ * @param {Map<string, Arrival>} results
+ */
+function waitForHistory(items, { covered, states }, results) {
+  const read = new Set(covered.map((item) => item.hash));
+
+  for (const item of items) {
+    if (!read.has(item.hash)) results.set(item.hash, { scan: { ...searchOf(item.scan), history: /** @type {HistoryScan} */ (states.get(item.hash)) }, state: "waiting" });
+  }
+}
+
+/**
+ * A result, with how far its transfer's history is read, which every one
+ * but an arrival keeps in its scan for the next call.
+ *
+ * @param {string} hash
+ * @param {Arrival} arrival
+ * @param {ReadonlyArray<Queued>} given
+ * @param {ReadonlyMap<string, HistoryScan>} states
+ * @returns {Arrival}
+ */
+function withHistory(hash, arrival, given, states) {
+  const history = states.get(hash);
+
+  if (!history || arrival.state === "arrived") return arrival;
+
+  return { ...arrival, scan: { ...(arrival.scan ?? searchOf(given.find((each) => each.hash === hash)?.scan)), history } };
 }
 
 // ---------------------------------------------------------------------------
@@ -1380,34 +1597,6 @@ async function onExplorer(read, live, { api, bridge, maxPages, now, past, result
  * @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
  */
 async function onRpc(read, live, { archive, blockTimes, bridge, list, maxWindows, net, now, past, results, url, used, windowMs }) {
-  /** @type {Map<string, Awaited<ReturnType<typeof senderDeposits>> & { bottom: number, top: number, topAt: number }>} */
-  const histories = new Map();
-
-  // The senders' deposits shortly before theirs, one history read a sender:
-  // the app's deposits no longer looked for among them.
-  if (archive) {
-    const reach = Math.ceil((3 * DEPOSIT_HORIZON_MS) / DUSK_BLOCK_MS);
-
-    for (const [sender, items] of groupBy(
-      live.filter((item) => item.sender !== null && item.height !== null),
-      (item) => /** @type {string} */ (item.sender)
-    )) {
-      const heights = items.map((item) => /** @type {number} */ (item.height));
-      const top = Math.max(...heights);
-      const bottom = Math.max(0, Math.min(...heights) - reach);
-      const least = items.reduce((a, item) => (item.amount < a ? item.amount : a), MAX_U64);
-
-      try {
-        const found = await senderDeposits(archive, net, { from: bottom, least, sender, skip: new Set(items.map((item) => item.hash)), to: top }, read.counter);
-        const topAt = /** @type {number} */ (items.find((item) => item.height === top)?.at);
-
-        histories.set(sender, { ...found, bottom, top, topAt });
-      } catch (error) {
-        for (const item of items) results.set(item.hash, { error: messageOf(error), reason: "error", state: "unknown" });
-      }
-    }
-  }
-
   // 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
@@ -1438,46 +1627,69 @@ async function onRpc(read, live, { archive, blockTimes, bridge, list, maxWindows
     if (rest.length) unknown.push({ items: rest, rivals: aliases.get(key) ?? new Set() });
   }
 
-  // The block each deposit given can't be credited before, the app's own.
+  // The block each deposit given can't be credited before, the app's own,
+  // the deposits given, and the deposits' calls, read once.
   const bounds = new Map(list.map((item) => [item.hash, item.notBefore]));
+  const supplied = new Map(list.map((item) => [item.hash, item]));
+  /** @type {Map<string, any>} */
+  const calls = new Map();
+  const contract = duskEvmContracts(net)?.bridge;
 
   for (const { items, rivals } of [...known, ...unknown]) {
     const { amount, sender, to } = items[0];
-    const history = sender === null ? undefined : histories.get(sender);
-    const vouched = Boolean(history) && items.every((item) => item.height !== null);
-    const given = items.map(queued).sort(byTime);
-    const alike = vouched
-      ? /** @type {NonNullable<typeof history>} */ (history).deposits
-          .filter((deposit) => deposit.to === to && deposit.amount === amount)
-          .map((deposit) => ({ at: deposit.at, given: false, hash: deposit.hash, notBefore: bounds.get(deposit.hash) ?? null, scan: null }))
-      : [];
-    const queue = vouched
-      ? queueOf(given, alike, DEPOSIT_HORIZON_MS)
-      : withPast(
-          given,
-          past.filter((item) => item.to === to && item.amount === amount && item.sender === sender).map(queued),
-          windowMs
-        );
+    const vouched = Boolean(archive) && sender !== null && items.every((item) => item.height !== null);
+    let given = items.map(queued).sort(byTime);
+    /** @type {Queued[]} */
+    let queue;
     /** @type {Set<string>} */
     const unsure = new Set();
+    /** @type {Map<string, HistoryScan>} */
+    let states = new Map();
 
-    // An equal deposit just under the history read could come first, and so
-    // could one before it whose call can't be read: the credits' order
-    // can't be told.
-    if (history && vouched) {
-      const bottomAt = history.bottom === 0 ? -Infinity : history.topAt - (history.top - history.bottom) * DUSK_BLOCK_MS;
-
-      for (const item of given) {
-        const height = /** @type {number} */ (items.find((each) => each.hash === item.hash)?.height);
-
-        if (
-          !history.complete ||
-          runStart(queue, item, DEPOSIT_HORIZON_MS).at - bottomAt < DEPOSIT_HORIZON_MS ||
-          history.unresolved.some((peer) => peer.value >= amount && peer.height <= height)
-        ) {
-          unsure.add(item.hash);
-        }
+    if (vouched) {
+      // 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;
+
+      try {
+        history = await readHistories(
+          /** @type {Archive} */ (archive),
+          /** @type {Reading[]} */ ([...items].sort((a, b) => /** @type {number} */ (a.height) - /** @type {number} */ (b.height))),
+          {
+            account: /** @type {string} */ (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),
+            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;
       }
+
+      states = history.states;
+      waitForHistory(items, history, results);
+
+      if (!history.covered.length) continue;
+
+      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 {
+      queue = withPast(
+        given,
+        past.filter((item) => item.to === to && item.amount === amount && item.sender === sender).map(queued),
+        windowMs
+      );
     }
 
     try {
@@ -1499,9 +1711,9 @@ async function onRpc(read, live, { archive, blockTimes, bridge, list, maxWindows
         { blockTimes, maxWindows, now, slackMs: CLOCK_SLACK_MS, url, used, windowMs }
       );
 
-      for (const [hash, arrival] of found) results.set(hash, arrival);
+      for (const [hash, arrival] of found) results.set(hash, withHistory(hash, arrival, given, states));
     } catch (error) {
-      for (const item of items) results.set(item.hash, { error: messageOf(error), reason: "error", state: "unknown" });
+      for (const item of given) results.set(item.hash, withHistory(item.hash, { error: messageOf(error), reason: "error", state: "unknown" }, given, states));
     }
   }
 }
@@ -1602,97 +1814,62 @@ export async function serviceArrivals({
   }
 
   const live = triage(known, results, { now, waitMs });
-  /** @type {Map<string, { complete: boolean, entries: HistoryEntry[], bottom: number, top: number, topAt: number, horizonMs: number }>} */
-  const histories = new Map();
-
-  // Each route's account's history, back from its transfers: every transfer
-  // that named the same address, in any case, and could be paid before.
-  for (const [id, items] of groupBy(live, (item) => item.route.id)) {
-    const { route } = items[0];
-    const horizonMs = horizonOf(route);
-    const heights = items.map((item) => item.height);
-    const top = Math.max(...heights);
-    const bottom = Math.max(0, Math.min(...heights) - Math.ceil((3 * horizonMs) / DUSK_BLOCK_MS));
-
-    try {
-      const range = await historyRange(archive, { account: route.account, direction: "in", from: bottom, pages: HISTORY_PAGES, to: top });
-
-      read.counter.requests += range.requests;
-      histories.set(id, { bottom, complete: range.complete, entries: range.entries, horizonMs, top, topAt: /** @type {SentItem} */ (items.find((item) => item.height === top)).at });
-    } catch (error) {
-      for (const item of items) results.set(item.hash, failed(error));
-    }
-  }
-
-  const groups = [...groupBy(live.filter((item) => histories.has(item.route.id)), (item) => `${item.route.id}:${item.to}:${item.net}`).values()];
-  const polled = new Set(groups.flat().map((item) => item.hash));
   // The fee of each transfer the app gave, those no longer looked for too,
   // and the block its payout can't be before.
   const feeOf = new Map(routed.map((item) => [item.hash, item.fee ?? /** @type {Route & { kind: "service" }} */ (item.route).feeLux]));
   const bounds = new Map(routed.map((item) => [item.hash, item.notBefore]));
-  // Each group's others: what the account received, at least as much as the
-  // group's transfers, naming the same address, and the app's transfers no
-  // longer looked for. What each paid whom, its memo and its time come from
-  // its own transaction.
-  const others = groups.map((items) => {
-    const { route, to } = items[0];
-    const least = items.reduce((a, item) => (item.net + item.fee < a ? item.net + item.fee : a), MAX_U64);
-
-    return (/** @type {NonNullable<ReturnType<typeof histories.get>>} */ (histories.get(route.id)).entries).filter(
-      (entry) => !polled.has(entry.hash) && entry.kind === "transfer" && entry.direction === "in" && entry.memo.toLowerCase() === to && (entry.value >= least || feeOf.has(entry.hash))
-    );
-  });
-  /** @type {Map<string, TransferFacts>} */
-  let peers;
+  // What each transfer to a route's account paid whom, its memo and its
+  // time, from its own transaction, read once.
+  /** @type {Map<string, TransferFacts | null>} */
+  const facts = new Map(sent);
 
-  try {
-    peers = new Map([...sent, ...(await transfersOf(archive, others.flat().flatMap((entry) => (sent.has(entry.hash) ? [] : [entry.hash])), read.counter))]);
-  } catch (error) {
-    for (const items of groups) for (const item of items) results.set(item.hash, failed(error));
-
-    return done();
-  }
-
-  for (const [i, items] of groups.entries()) {
+  for (const items of groupBy(live, (item) => `${item.route.id}:${item.to}:${item.net}`).values()) {
     const { net: payout, route, to } = items[0];
-    const history = /** @type {NonNullable<ReturnType<typeof histories.get>>} */ (histories.get(route.id));
+    const horizonMs = horizonOf(route);
     const fees = new Set(items.map((item) => item.fee));
-    /** @type {Queued[]} */
-    const alike = [];
-    // The heights of transfers to the same address that can't be read.
-    /** @type {number[]} */
-    const unread = [];
-
-    for (const entry of others[i]) {
-      const facts = peers.get(entry.hash);
-
-      if (!facts || facts.kind === null || facts.at === null || (facts.kind === "moonlight" && (facts.value === null || facts.receiver === null))) {
-        unread.push(entry.blockHeight);
-      } else if (!facts.failed && facts.kind === "moonlight" && facts.receiver === route.account && facts.memo.toLowerCase() === to) {
-        const value = /** @type {bigint} */ (facts.value);
-        // One the app gave pays out what its own fee leaves; one it didn't,
-        // what the group's do.
-        const own = feeOf.get(entry.hash);
-
-        if (own === undefined ? [...fees].some((fee) => value - fee === payout) : value - own === payout) {
-          alike.push({ at: facts.at, given: false, hash: entry.hash, notBefore: bounds.get(entry.hash) ?? null, scan: null });
-        }
-      }
+    const least = payout + [...fees].reduce((a, fee) => (fee < a ? fee : a));
+    // Each transfer's own hours of the route's account's history: every
+    // transfer that named the same address, in any case, and could be paid
+    // before, the app's no longer looked for among them. Of those, the ones
+    // that could pay out as much under the group's fees, or under their own.
+    /** @type {Awaited<ReturnType<typeof readHistories>>} */
+    let history;
+
+    try {
+      history = await readHistories(
+        archive,
+        [...items].sort((a, b) => a.height - b.height),
+        {
+          account: route.account,
+          direction: "in",
+          horizonMs,
+          keep: (entry) => entry.kind === "transfer" && entry.direction === "in" && entry.memo.toLowerCase() === to && entry.value >= payout,
+          of: (item) => `${route.account}:${item.height}:${to}:${payout}`,
+          pages: HISTORY_PAGES,
+          peersOf: (found) =>
+            servicePeers(
+              archive,
+              found.filter((entry) => BigInt(entry.value) >= least || feeOf.has(entry.hash)),
+              { bounds, facts, feeOf, fees, payout, route, to },
+              read.counter
+            ),
+          reach: Math.ceil((3 * horizonMs) / DUSK_BLOCK_MS),
+        },
+        read.counter
+      );
+    } catch (error) {
+      for (const item of items) results.set(item.hash, failed(error));
+      continue;
     }
 
-    const given = items.map(queued).sort(byTime);
-    const queue = queueOf(given, alike, history.horizonMs);
-    const bottomAt = history.bottom === 0 ? -Infinity : history.topAt - (history.top - history.bottom) * DUSK_BLOCK_MS;
-    /** @type {Set<string>} */
-    const unsure = new Set();
+    waitForHistory(items, history, results);
 
-    // A history cut short, an equal transfer just under it, or one before
-    // that can't be read: the payouts' order can't be told.
-    for (const item of given) {
-      const height = /** @type {SentItem} */ (items.find((each) => each.hash === item.hash)).height;
+    if (!history.covered.length) continue;
 
-      if (!history.complete || runStart(queue, item, history.horizonMs).at - bottomAt < history.horizonMs || unread.some((each) => each <= height)) unsure.add(item.hash);
-    }
+    const { given } = history;
+    // One before it that can't be read could be equal: the payouts' order
+    // can't be told.
+    const unsure = new Set(given.flatMap((item) => (/** @type {number[]} */ (history.unread.get(item.hash)).length ? [item.hash] : [])));
 
     try {
       const found = await followLogs(
@@ -1706,21 +1883,63 @@ export async function serviceArrivals({
           },
           given,
           guarded: false,
-          queue,
+          queue: history.queue,
           unsure,
         },
         { blockTimes, maxWindows, now, slackMs: CLOCK_SLACK_MS, url: String(rpcUrl ?? route.chain.rpcUrl), used, windowMs: CREDIT_WINDOW_MS }
       );
 
-      for (const [hash, arrival] of found) results.set(hash, arrival);
+      for (const [hash, arrival] of found) results.set(hash, withHistory(hash, arrival, given, history.states));
     } catch (error) {
-      for (const item of items) results.set(item.hash, failed(error));
+      for (const item of given) results.set(item.hash, withHistory(item.hash, failed(error), given, history.states));
     }
   }
 
   return done();
 }
 
+/**
+ * Of the transfers a route's account received naming a group's address,
+ * those equal to the group's, from their own transactions: one the app
+ * gave pays out what its own fee leaves, one it didn't what the group's
+ * fees do; each with the block the app gave it its payout can't be before.
+ * And those whose transaction can't be read. `facts` keeps each
+ * transaction read.
+ *
+ * @param {Archive} archive
+ * @param {ReadonlyArray<{ hash: string, height: number }>} found
+ * @param {{ bounds: ReadonlyMap<string, bigint | null>, facts: Map<string, TransferFacts | null>, feeOf: ReadonlyMap<string, bigint>, fees: ReadonlySet<bigint>, payout: bigint, route: Route & { kind: "service" }, to: string }} group
+ * @param {{ requests: number }} counter
+ */
+async function servicePeers(archive, found, { bounds, facts, feeOf, fees, payout, route, to }, counter) {
+  const missing = found.flatMap((entry) => (facts.has(entry.hash) ? [] : [entry.hash]));
+  const read = await transfersOf(archive, missing, counter);
+
+  for (const hash of missing) facts.set(hash, read.get(hash) ?? null);
+
+  /** @type {Queued[]} */
+  const peers = [];
+  /** @type {{ hash: string, height: number }[]} */
+  const unread = [];
+
+  for (const entry of found) {
+    const fact = facts.get(entry.hash);
+
+    if (!fact || fact.kind === null || fact.at === null || (fact.kind === "moonlight" && (fact.value === null || fact.receiver === null))) {
+      unread.push(entry);
+    } else if (!fact.failed && fact.kind === "moonlight" && fact.receiver === route.account && fact.memo.toLowerCase() === to) {
+      const value = /** @type {bigint} */ (fact.value);
+      const own = feeOf.get(entry.hash);
+
+      if (own === undefined ? [...fees].some((fee) => value - fee === payout) : value - own === payout) {
+        peers.push({ at: fact.at, given: false, hash: entry.hash, notBefore: bounds.get(entry.hash) ?? null, scan: null });
+      }
+    }
+  }
+
+  return { peers, unread };
+}
+
 // ---------------------------------------------------------------------------
 // Migrations into Dusk
 // ---------------------------------------------------------------------------

package/src/history.d.ts

@@ -373,6 +373,8 @@ export type RangeOptions = {
   direction?: "in" | "out" | "both";
   /** The most pages to read, 1 by default. */
   pages?: number;
+  /** The first page to read, 1 by default: a read of the same range carries on where an earlier one stopped. */
+  page?: number;
 };
 
 /**

package/src/history.js

@@ -816,7 +816,7 @@ function nextWindow(window, count) {
  * @param {RangeOptions} options
  * @returns {Promise<{ entries: HistoryEntry[], complete: boolean, requests: number }>}
  */
-export async function historyRange(archive, { account, from = 0, to, direction = "both", pages = 1 }) {
+export async function historyRange(archive, { account, from = 0, to, direction = "both", pages = 1, page: first = 1 }) {
   /** @type {Record<string, ReadonlyArray<"in" | "out">>} */
   const ASKED = { both: ["out", "in"], in: ["in"], out: ["out"] };
   const aliases = Object.hasOwn(ASKED, direction) ? ASKED[direction] : null;
@@ -827,8 +827,9 @@ export async function historyRange(archive, { account, from = 0, to, direction =
   const entries = [];
   let complete = false;
   let requests = 0;
+  const start = Math.max(1, Math.floor(Number(first)) || 1);
 
-  for (let page = 1; page <= Math.max(1, Math.floor(pages)) && !complete; page += 1) {
+  for (let page = start; page < start + Math.max(1, Math.floor(pages)) && !complete; page += 1) {
     requests += 1;
 
     const data = await archive.query(rangeQuery(account, { aliases, from, page, to }));