@dusk-network/app-core 0.4.0 → 0.5.0

package/src/duskevm-withdrawals.d.ts

@@ -90,7 +90,11 @@ export declare const L2_WINDOW: 100000;
 /** Log searches one run of `syncWithdrawals` makes, the head's included, by default. */
 export declare const L2_RUN_REQUESTS: 8;
 
-/** DuskEVM blocks under the head counted as final where the RPC has no "finalized" block: about an hour. */
+/**
+ * DuskEVM blocks under the head counted as final where the RPC has no
+ * "finalized" block: about an hour. The blocks a run reads within that
+ * margin under it are read again once they're under a later run's.
+ */
 export declare const UNFINALIZED_MARGIN: 1800;
 
 /** Pages of an address's transactions `explorerWithdrawals` reads at most, by default. */
@@ -359,7 +363,11 @@ export type WithdrawalsOptions = {
   maxBatch?: number;
   /** How many of the newest games a proof is looked for among: 64 by default, and for anything but a positive whole number. */
   gameSearchDepth?: number | bigint;
-  /** Where the deployment's fixed facts are kept: each game's hub, each game type's hub, each hub's clock limit. */
+  /**
+   * Where the deployment's fixed facts are kept: each game's hub and each
+   * game type's hub, once the factory names one, each hub's clock limit, and
+   * each withdrawal's receipt once its DuskEVM block is final.
+   */
   cache?: FactCache;
   /** The clock, in milliseconds. */
   now?: () => number;
@@ -368,7 +376,14 @@ export type WithdrawalsOptions = {
 /** A network's withdrawals, read on its Dusk node and DuskEVM. */
 export type Withdrawals = {
   readonly network: Network;
-  /** A DuskEVM transaction's withdrawal, from its receipt; refuses as `parseWithdrawalReceipt` does. */
+  /**
+   * A DuskEVM transaction's withdrawal, from its receipt; refuses as
+   * `parseWithdrawalReceipt` does. The receipt is read after DuskEVM's
+   * finalized block, which the receipts read at the same time share, and
+   * kept in `cache` once its block is at or under that one: a final
+   * receipt is read once. One that isn't final yet, or isn't a
+   * withdrawal's, is read again each time.
+   */
   receipt(txHash: string): Promise<ReceiptWithdrawal>;
   /**
    * Where a withdrawal is, for `submitter` (a Dusk account, or its
@@ -452,6 +467,13 @@ export type FoundWithdrawal = {
 export type WithdrawalScan = {
   /** The final blocks covered, as ranges, highest first. */
   covered: number[][];
+  /**
+   * Where the RPC has no finalized block: the blocks covered within
+   * `UNFINALIZED_MARGIN` under the head a run read them under, as ranges,
+   * highest first, the newest 16, read again once they're under a later
+   * run's margin. Older ones are left to the passes over all the blocks.
+   */
+  open?: number[][];
   /** What was found, by hash. */
   entries: Record<string, FoundWithdrawal>;
   /** The final head the last run read under. */
@@ -478,7 +500,14 @@ export type WithdrawalScan = {
  * take though in half its requests at most (while older blocks are still to
  * be read, only once the final head has moved), and carries on below; under
  * a final head lower than the last run's, what was covered and found above
- * it is dropped, and read again. Once all the final blocks are
+ * it is dropped, and read again. Where the RPC has no finalized block, the
+ * final head is the latest less `UNFINALIZED_MARGIN`, and the blocks a run
+ * reads within that margin under it are read again once they're under a
+ * later run's (`open`): among the newest blocks a run reads again, or, once
+ * all the final blocks are covered, before the passes over them, with the
+ * requests a run has left. A deeper reorg there is found, and older blocks
+ * are read as they would be without it.
+ * Once all the final blocks are
  * covered, they're read again from the newest down, a pass at a time with
  * the requests a run has left: the first an hour later, each after as long
  * again as it has been since. A withdrawal is found once: one read again

package/src/duskevm-withdrawals.js

@@ -133,6 +133,10 @@ const NONCE_COUNT = (1n << 240n) - 1n;
 // since.
 const L2_OVERLAP = 50_000;
 const L2_RECHECK_MS = 60 * 60_000;
+// The ranges of blocks read only under a head the RPC didn't call final that
+// a sync keeps to read again, the newest: older ones are left to its passes
+// over all the blocks.
+const L2_OPEN_RANGES = 16;
 // Answers a read is sent again for, a quarter second, then half a second later.
 const RETRY_STATUSES = new Set([429, 502, 503, 504]);
 const ATTEMPTS = 3;
@@ -773,6 +777,20 @@ function evmRpc(client, net) {
   };
 }
 
+/**
+ * A block number as DuskEVM's RPC gives it, a hex quantity, or as a whole
+ * number; null for anything else.
+ *
+ * @param {unknown} value
+ * @returns {bigint | null}
+ */
+function blockNumberOf(value) {
+  if (typeof value === "bigint") return value >= 0n ? value : null;
+  if (typeof value === "number") return Number.isSafeInteger(value) && value >= 0 ? BigInt(value) : null;
+
+  return typeof value === "string" && /^0x[0-9a-fA-F]+$/.test(value) ? BigInt(value) : null;
+}
+
 // ---------------------------------------------------------------------------
 // The bridge's contracts on Dusk
 // ---------------------------------------------------------------------------
@@ -1010,14 +1028,21 @@ function createReads({ cache, contracts, drivers, fetch, nodeUrl }) {
   };
 
   /**
-   * The hub that holds a game type's games.
+   * The hub that holds a game type's games. None, and nothing kept, for a
+   * type the factory names no hub for yet.
    *
    * @param {number} gameType
    * @returns {Promise<string>}
    */
   const hubOfType = (gameType) =>
     known(cache, inflight, `type:${contracts.disputeGameFactory}:${gameType}`, () =>
-      factory("virtualGameHubId", gameType).then(contractIdHex)
+      factory("virtualGameHubId", gameType).then((value) => {
+        const hubId = contractIdHex(value);
+
+        if (/^0+$/.test(hubId)) throw new Error("The factory names no hub for the game type");
+
+        return hubId;
+      })
     );
 
   /**
@@ -1223,13 +1248,137 @@ export function createWithdrawals(options) {
     ]).then(([status, blacklisted, proper, respected]) => ({ blacklisted, proper, respected, status }));
 
   /**
+   * Where a final receipt is kept: by the network, its Portal and the
+   * transaction's hash, so another network's or deployment's stays apart.
+   *
+   * @param {string} hash - 0x and 64 lower-case hex digits
+   */
+  const receiptKey = (hash) => `receipt:${net.chainId}:${contracts.portal}:${hash}`;
+
+  /** @type {Promise<bigint | null> | null} */
+  let finalizing = null;
+
+  /**
+   * DuskEVM's finalized block's height, or null where it can't be read;
+   * the receipts read at the same time share one read.
+   *
+   * @returns {Promise<bigint | null>}
+   */
+  function finalizedHeight() {
+    if (!finalizing) {
+      const reading = Promise.resolve()
+        .then(() => rpc("eth_getBlockByNumber", ["finalized", false]))
+        .then(
+          (block) => blockNumberOf(block?.number),
+          () => null
+        );
+
+      finalizing = reading;
+      reading.then(() => {
+        if (finalizing === reading) finalizing = null;
+      });
+    }
+
+    return finalizing;
+  }
+
+  /** @type {Map<string, Promise<any>>} */
+  const receiptReads = new Map();
+
+  /**
+   * The withdrawal a kept receipt records, as when it was kept; null when
+   * none is kept, or what is kept isn't this transaction's withdrawal.
+   *
+   * @param {string} hash
+   * @returns {ReceiptWithdrawal | null}
+   */
+  function keptReceipt(hash) {
+    try {
+      const text = cache.get(receiptKey(hash));
+
+      if (typeof text !== "string" || !text) return null;
+
+      const withdrawal = parseWithdrawalReceipt(net, JSON.parse(text));
+
+      return withdrawal.transactionHash === hash ? withdrawal : null;
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Keeps a receipt that can't change any more: a withdrawal's, of this
+   * transaction, in a block at or under `final`, the finalized height read
+   * before the receipt was. A failed or missing receipt, or one that isn't
+   * a withdrawal's, isn't kept. Kept as the RPC gave it, once its text
+   * reads back as the same withdrawal.
+   *
+   * @param {string} hash
+   * @param {any} raw
+   * @param {bigint} final
+   */
+  function keepIfFinal(hash, raw, final) {
+    try {
+      const withdrawal = parseWithdrawalReceipt(net, raw);
+      const block = blockNumberOf(raw?.blockNumber);
+
+      if (block === null || block !== withdrawal.blockNumber || block > final || withdrawal.transactionHash !== hash) return;
+
+      const text = JSON.stringify(raw);
+      const again = parseWithdrawalReceipt(net, JSON.parse(text));
+
+      if (again.withdrawalHash !== withdrawal.withdrawalHash || again.blockNumber !== block || again.transactionHash !== hash) return;
+
+      cache.set(receiptKey(hash), text);
+    } catch {
+      // Not kept: it's read again next time.
+    }
+  }
+
+  /**
+   * A transaction's receipt as DuskEVM gives it, read after DuskEVM's
+   * finalized block: a receipt read once its block is final is the final
+   * chain's, and is kept. The callers asking for one receipt at the same
+   * time share one read.
+   *
+   * @param {string} hash
+   * @returns {Promise<any>}
+   */
+  function readReceipt(hash) {
+    let reading = receiptReads.get(hash);
+
+    if (!reading) {
+      reading = (async () => {
+        const final = await finalizedHeight();
+        const raw = await rpc("eth_getTransactionReceipt", [hash]);
+
+        if (final !== null) keepIfFinal(hash, raw, final);
+
+        return raw;
+      })();
+      receiptReads.set(hash, reading);
+      reading.then(
+        () => receiptReads.delete(hash),
+        () => receiptReads.delete(hash)
+      );
+    }
+
+    return reading;
+  }
+
+  /**
+   * A transaction's withdrawal, from its receipt: the one kept once its
+   * block was final, else the one DuskEVM gives now.
+   *
    * @param {string} txHash
    * @returns {Promise<ReceiptWithdrawal>}
    */
   async function receipt(txHash) {
     if (typeof txHash !== "string" || !/^0x[0-9a-fA-F]{64}$/.test(txHash)) throw new WithdrawalError("bad-hash");
 
-    return parseWithdrawalReceipt(net, await rpc("eth_getTransactionReceipt", [txHash.toLowerCase()]));
+    const hash = txHash.toLowerCase();
+
+    return keptReceipt(hash) ?? parseWithdrawalReceipt(net, await readReceipt(hash));
   }
 
   /**
@@ -2092,22 +2241,26 @@ function withdrawalFromLog(log) {
 const tooWide = (error) => /range|limit|too many|exceed/i.test(asError(error).message);
 
 /**
- * The highest DuskEVM block that can't be reorged away, and the requests it
- * took.
+ * The highest DuskEVM block that can't be reorged away, the requests it
+ * took, and the margin under it within which the blocks a run reads are
+ * read again on a later one: none under the RPC's finalized block. Where
+ * the RPC has none, the head is the latest less a margin, and the blocks
+ * read within the margin under it are read again, as a deeper reorg could
+ * still change them.
  *
  * @param {(method: string, params?: unknown[]) => Promise<any>} rpc
- * @returns {Promise<{ head: number, requests: number }>}
+ * @returns {Promise<{ head: number, margin: number, requests: number }>}
  */
 async function finalHead(rpc) {
   try {
     const block = await rpc("eth_getBlockByNumber", ["finalized", false]);
 
-    if (block?.number) return { head: Number(BigInt(block.number)), requests: 1 };
+    if (block?.number) return { head: Number(BigInt(block.number)), margin: 0, requests: 1 };
   } catch {
     // An RPC without "finalized": the latest block, less a margin.
   }
 
-  return { head: Math.max(0, Number(BigInt(await rpc("eth_blockNumber", []))) - UNFINALIZED_MARGIN), requests: 2 };
+  return { head: Math.max(0, Number(BigInt(await rpc("eth_blockNumber", []))) - UNFINALIZED_MARGIN), margin: UNFINALIZED_MARGIN, requests: 2 };
 }
 
 /**
@@ -2129,6 +2282,39 @@ function recheckOf(value, target) {
   return { at: kept.at, from: kept.from === null ? null : Math.min(kept.from, target), since: kept.since };
 }
 
+/**
+ * The blocks a state kept as read only under a head the RPC didn't call
+ * final, as far as they're still covered, as ranges, highest first; none
+ * for anything else.
+ *
+ * @param {unknown} value
+ * @param {number[][]} covered
+ * @returns {number[][]}
+ */
+function openOf(value, covered) {
+  const kept = Array.isArray(value) ? value.filter((range) => Array.isArray(range) && Number.isSafeInteger(range[0]) && Number.isSafeInteger(range[1]) && range[0] <= range[1]) : [];
+  /** @type {number[][]} */
+  let out = [];
+
+  for (const [a, b] of kept) {
+    for (const [c, d] of covered) {
+      if (Math.max(a, c) <= Math.min(b, d)) out = addCoverage(out, Math.max(a, c), Math.min(b, d));
+    }
+  }
+
+  return out;
+}
+
+/**
+ * Ranges of blocks, highest first, without blocks `lo` to `hi`.
+ *
+ * @param {number[][]} ranges
+ * @param {number} lo
+ * @param {number} hi
+ * @returns {number[][]}
+ */
+const without = (ranges, lo, hi) => ranges.flatMap(([a, b]) => [...(b > hi ? [[Math.max(a, hi + 1), b]] : []), ...(a < lo ? [[a, Math.min(b, lo - 1)]] : [])]);
+
 /**
  * @param {{ address: string, duskEvm: DuskEvmClient, network?: NetworkRef, bridge?: string, state?: WithdrawalScan | null, maxRequests?: number, now?: () => number }} options
  * @returns {Promise<{ found: FoundWithdrawal[], requests: number, state: WithdrawalScan }>}
@@ -2141,7 +2327,7 @@ export async function syncWithdrawals({ address, bridge, duskEvm, maxRequests =
   if (!contract) throw new TypeError("No DuskEVM bridge to read");
 
   const rpc = evmRpc(duskEvm, net);
-  const { head: target, requests: asked } = await finalHead(rpc);
+  const { head: target, margin, requests: asked } = await finalHead(rpc);
   const time = now();
   // Coverage kept above the final head, as an older run read the latest, is
   // read again, and what was found there is dropped with it: it may have
@@ -2155,6 +2341,11 @@ export async function syncWithdrawals({ address, bridge, duskEvm, maxRequests =
   let requests = asked;
   let recheck = recheckOf(state?.recheck, target);
   const topics = [ETH_BRIDGE_INITIATED_TOPIC, pad(sender)];
+  // Blocks read only under a head the RPC didn't call final, within its
+  // margin, are read again once they're under a run's margin too: a deeper
+  // reorg could still change them. Those kept above the final head go with
+  // its coverage.
+  let open = openOf(state?.open, covered);
 
   /**
    * The address's withdrawals in blocks `lo` to `hi`, those blocks covered;
@@ -2193,6 +2384,10 @@ export async function syncWithdrawals({ address, bridge, duskEvm, maxRequests =
     }
 
     covered = addCoverage(covered, lo, hi);
+    // Read under this run's margin, they're as final as its head; within it,
+    // under a head the RPC didn't call final, they're open.
+    open = without(open, lo, hi);
+    if (margin && hi > target - margin) open = addCoverage(open, Math.max(lo, target - margin + 1), hi);
 
     return true;
   };
@@ -2225,8 +2420,19 @@ export async function syncWithdrawals({ address, bridge, duskEvm, maxRequests =
       continue;
     }
 
-    // All the final blocks covered: they're read again, a pass at a time,
-    // from the newest down, with what a run has left.
+    // All the final blocks covered: those read only under a head the RPC
+    // didn't call final, and under this run's margin now, are read again
+    // first, the newest first. Then all of them, a pass at a time, from the
+    // newest down, with what a run has left.
+    const settling = open.find(([a]) => a <= target - margin);
+
+    if (settling) {
+      const b = Math.min(settling[1], target - margin);
+
+      await read(Math.max(settling[0], b - window + 1), b);
+      continue;
+    }
+
     if (recheck === null) recheck = { at: time + L2_RECHECK_MS, from: null, since: time };
     if (recheck.from === null && time < recheck.at) break;
 
@@ -2240,7 +2446,7 @@ export async function syncWithdrawals({ address, bridge, duskEvm, maxRequests =
 
   if (recheck === null && !topGap(covered, target)) recheck = { at: time + L2_RECHECK_MS, from: null, since: time };
 
-  return { found, requests, state: { covered, entries, ...(recheck ? { recheck } : {}), target, updatedAt: now(), window } };
+  return { found, requests, state: { covered, entries, ...(open.length ? { open: open.slice(0, L2_OPEN_RANGES) } : {}), ...(recheck ? { recheck } : {}), target, updatedAt: now(), window } };
 }
 
 /**