@dusk-network/app-core 0.4.0 → 0.5.0

package/src/bridge-explorer.js

@@ -0,0 +1,186 @@
+/* @ts-self-types="./bridge-explorer.d.ts" */
+/**
+ * Where a deposit to DuskEVM arrived, followed on DuskEVM's explorer alone:
+ * what `/bridge`'s `depositArrivals` does with `via: "explorer"`, for an
+ * app that reads only the explorer, without the RPC path and `/history`.
+ *
+ * @module
+ */
+
+import {
+  CREDIT_WINDOW_MS,
+  EXPLORER_PAGES,
+  TIMEOUT_MS,
+  WAIT_MS,
+  WEI_PER_LUX,
+  allOpen,
+  depositsIn,
+  evmHashOf,
+  groupBy,
+  inOrder,
+  messageOf,
+  quantityOf,
+  queued,
+  reader,
+  settle,
+  urlOf,
+  withPast,
+} from "./bridge-common.js";
+
+/** @typedef {import("./bridge.js").Arrival} Arrival */
+/** @typedef {import("./bridge-common.js").Credit} Credit */
+/** @typedef {import("./bridge-common.js").DepositItem} DepositItem */
+/** @typedef {import("./bridge-common.js").Reader} Reader */
+/** @typedef {import("./bridge-explorer.js").ExplorerDepositOptions} ExplorerDepositOptions */
+
+/**
+ * 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"));
+
+/**
+ * @param {ExplorerDepositOptions} options
+ * @returns {Promise<{ arrivals: Map<string, Arrival>, requests: number }>}
+ */
+export async function depositArrivalsFromExplorer({
+  network,
+  deposits,
+  fetch: fetchFn,
+  explorerUrl,
+  taken,
+  now = Date.now(),
+  waitMs = WAIT_MS,
+  windowMs = CREDIT_WINDOW_MS,
+  maxPages = EXPLORER_PAGES,
+  timeoutMs = TIMEOUT_MS,
+}) {
+  const { evm, list, live, past, results, used } = depositsIn({ deposits, network, now, taken, waitMs });
+  const read = reader(fetchFn, timeoutMs);
+
+  if (evm) {
+    const api = urlOf(explorerUrl, evm.blockscoutApiUrl, "DuskEVM explorer");
+
+    await onExplorer(read, live, { api, bridge: evm.predeploys.l2StandardBridge.toLowerCase(), maxPages, now, past, results, 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" });
+        }
+      }
+    }
+  }
+}

package/src/bridge.d.ts

@@ -34,9 +34,15 @@
  * - The app owns all I/O and storage: it passes `fetch`, the URLs (the
  *   network's file's by default), `/history`'s archive for the Dusk side,
  *   and its own caches: the credits it gave other transfers, where the last
- *   search stopped, and the chain's block times. Nothing here keeps state
- *   outside the calls, so it runs in an extension's service worker as well
- *   as in a page.
+ *   search stopped, the chain's block times, and what can't change any
+ *   more. Nothing here keeps state outside the calls, so it runs in an
+ *   extension's service worker as well as in a page.
+ * - A network is a network file, or its chain ID; on a chain there's no
+ *   file for, one the app builds from its own settings (`NetworkSettings`),
+ *   checked as a file's fields are.
+ * - An app that follows deposits on DuskEVM's explorer alone imports
+ *   `depositArrivalsFromExplorer` from `/bridge-explorer`, without the RPC
+ *   path and `/history`.
  *
  * @example
  * ```js
@@ -55,9 +61,44 @@
  * @module
  */
 
-import type { Account, EvmAddress, NetworkRef } from "@dusk-network/networks";
+import type { Account, EvmAddress, Network, NetworkRef } from "@dusk-network/networks";
 import type { Archive, Direction, EntryKind } from "./history.js";
 
+export { depositArrivalsFromExplorer, type ExplorerDepositOptions } from "./bridge-explorer.js";
+
+/**
+ * A network an app builds from its own settings, for a chain there's no
+ * network file for: its chain ID as the node gives it, and DuskEVM's bridge,
+ * RPC (for "rpc") and explorer API (for "explorer"), as a network file has
+ * them. Its fields are checked as a file's are: a TypeError for one that
+ * isn't (an address that isn't 0x and 40 hex digits, a URL that isn't
+ * http(s) or ends with a slash). It has no routes to other chains unless it
+ * gives them as a file does: transfers out and migrations on it are
+ * `no-route`.
+ */
+export type NetworkSettings = {
+  chainId: number;
+  /** DuskEVM, or null where it has none: then no deposit is followed. */
+  duskEvm?: {
+    rpcUrl?: string;
+    blockscoutApiUrl?: string;
+    predeploys: { l2StandardBridge: string };
+    /**
+     * DuskEVM's contracts on Dusk, by their names in a network file: with
+     * the bridge's and the Portal's (`l1_standard_bridge`,
+     * `optimism_portal`), a deposit's sender's history is read on "rpc".
+     */
+    contracts?: Record<string, { contractId: string; evmAddress?: string }>;
+  } | null;
+  routes?: Network["routes"];
+};
+
+/** The network a read takes: a network file, its chain ID, or one built from an app's settings. */
+export type BridgeNetwork = NetworkRef | NetworkSettings;
+
+/** The app's cache of what can't change any more, as text: a Map does. */
+export type FactCache = { get(key: string): string | null | undefined; set(key: string, value: string): unknown };
+
 /** How long before its transfer's block a credit still counts: Dusk's clock and the other chain's can differ. 2 minutes, in milliseconds. */
 export declare const CLOCK_SLACK_MS: 120000;
 
@@ -209,8 +250,8 @@ export type Deposit = {
 
 /** What `depositArrivals` takes. */
 export type DepositArrivalOptions = {
-  /** The Dusk network, or its chain ID: its DuskEVM, and its URLs. */
-  network: NetworkRef;
+  /** The Dusk network, its chain ID, or one built from the app's settings: its DuskEVM, and its URLs. */
+  network: BridgeNetwork;
   /** The deposits waited for: each once, by hash. */
   deposits: Iterable<Deposit>;
   /**
@@ -231,8 +272,11 @@ export type DepositArrivalOptions = {
    * 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.
+   * Without it, while it can't be read, on a network that doesn't name
+   * DuskEVM's bridge and Portal on Dusk, or for a deposit without its sender
+   * and height, its credit is a deposit's only as where they can't be told
+   * apart; a deposit is an `error` only when DuskEVM's RPC can't be read
+   * either.
    */
   archive?: Archive;
   /**
@@ -243,6 +287,15 @@ export type DepositArrivalOptions = {
   taken?: Iterable<string>;
   /** DuskEVM's block times the app keeps, for "rpc". */
   blockTimes?: BlockTimes;
+  /**
+   * Where the calls of the deposits a sender's history lists are kept, for
+   * "rpc" with the archive: each is kept once its block is final and its
+   * answer says all a match reads of it (that it failed, that it's another
+   * call than a deposit, or a deposit's amount and DuskEVM address), and
+   * isn't asked for again. One whose arguments come cut short is asked for
+   * again.
+   */
+  cache?: FactCache;
   /** The clock, in milliseconds. */
   now?: number;
   /** How long a deposit is waited for; `WAIT_MS` by default. */
@@ -269,7 +322,8 @@ export type DepositArrivalOptions = {
  * from about when the first was sent, `maxWindows` windows at most (one more
  * where the search ahead takes them all while its blocks are read again).
  * A network without DuskEVM asks nothing. Throws a TypeError for a deposit
- * that isn't one, and for a network there's no file for.
+ * that isn't one, for a network that isn't one, and for one without the URL
+ * the reads go to where none is given.
  */
 export declare function depositArrivals(options: DepositArrivalOptions): Promise<{ arrivals: Map<string, Arrival>; requests: number }>;
 
@@ -293,7 +347,7 @@ export type ServiceTransfer = {
 
 /** What `serviceArrivals` takes. */
 export type ServiceArrivalOptions = {
-  network: NetworkRef;
+  network: BridgeNetwork;
   transfers: Iterable<ServiceTransfer>;
   /** `/history`'s archive: each transfer, and the route's account's history, which lists the equal ones paid before. */
   archive: Archive;
@@ -328,8 +382,8 @@ export type ServiceArrivalOptions = {
  * 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.
+ * `scan`. Throws a TypeError without an archive, and for a network that
+ * isn't one.
  */
 export declare function serviceArrivals(options: ServiceArrivalOptions): Promise<{ arrivals: Map<string, Arrival>; requests: number }>;
 
@@ -369,7 +423,7 @@ export type MigrationPayout = {
 
 /** What `migrationPayouts` takes: the account's entries, or the archive and the account. */
 export type MigrationPayoutOptions = {
-  network: NetworkRef;
+  network: BridgeNetwork;
   migrations: Iterable<Migration>;
   /** The account's public history, as `/history` reads or keeps it. */
   entries?: Iterable<HistoryLike>;
@@ -409,6 +463,8 @@ export type HistoryLike = {
   /** Of `value`, a gas refund paid to another account than the sender. */
   refund?: bigint | string | null;
   memo: string;
+  /** True when `memo` is bytes that aren't text, given as 0x hex: no address or hash is read from it. */
+  memoBinary?: boolean;
   payer: boolean;
   timestamp?: number | null;
   success?: boolean | null;
@@ -433,7 +489,7 @@ export type ServiceTransferFacts = {
   /** What the route's account received: known only where no gas was left to refund; null otherwise. */
   amount: bigint | null;
   fee: bigint;
-  /** The address its memo gives, exactly as the bridge reads it; null when it isn't one. */
+  /** The address its memo gives, exactly as the bridge reads it; null when it isn't one, or the memo isn't text. */
   to: string | null;
   at: number | null;
   height: number | null;
@@ -444,18 +500,20 @@ export type ServiceTransferFacts = {
 /**
  * A transfer the account sent to a service route's account, as its entry
  * says it; null for any other entry. The memo is read as the route's bridge
- * reads it: 0x and 40 hex digits, any case, nothing around them.
+ * reads it: 0x and 40 hex digits, any case, nothing around them, as text. A
+ * memo of bytes that aren't text (`memoBinary`) gives no address.
  */
-export declare function serviceTransferOf(entry: HistoryLike, network: NetworkRef): ServiceTransferFacts | null;
+export declare function serviceTransferOf(entry: HistoryLike, network: BridgeNetwork): ServiceTransferFacts | null;
 
 /**
  * A payout of a migration, from its entry: a transfer the account received
  * from a migration route's payout account, with a transaction hash as the
- * memo, of its value less any gas `refund` paid to the account with it. Its
- * route is null where that account pays out more than one route. Null for
- * any other entry, and on a route without its payout account.
+ * memo as text, of its value less any gas `refund` paid to the account with
+ * it. Its route is null where that account pays out more than one route.
+ * Null for any other entry, a memo of bytes that aren't text included, and
+ * on a route without its payout account.
  */
-export declare function migrationPayoutOf(entry: HistoryLike, network: NetworkRef): MigrationPayout | null;
+export declare function migrationPayoutOf(entry: HistoryLike, network: BridgeNetwork): MigrationPayout | null;
 
 /**
  * The deposits that arrived, as `/activity`'s `arrivals` takes them: by the