@dusk-network/app-core 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 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.0]
+
+### Added
+
+- `/duskevm-withdrawals`: a DuskEVM withdrawal's start, finding it again, its status and claim date, and its proof's and claim's calls, checked before they're handed over to sign
+
+### Fixed
+
+- `/bridge`: a migration is paid by its own route's payout account also where one account pays out both routes (a payout of one not listed then has a null `route`), and a payout read from an entry leaves out a gas refund paid with it, which `/history` entries now tell apart as `refund`
+
+## [0.2.0]
+
+### Added
+
+- `/bridge`: `depositArrivals`, `migrationPayouts` and `serviceArrivals`, where a deposit to DuskEVM, a migration and a transfer out to BNB Smart Chain arrived, each credit paying one transfer, in order
+
 ## [0.1.0]
 
 ### Added

package/README.md

@@ -30,8 +30,10 @@ The entry points are the same on both, under each registry's name: `@dusk-networ
 | `@dusk-network/app-core/history` | A public account's history from the Dusk archive, synced by block height into the app's store (`createHistory`), through the archive's GraphQL (`createArchive`, `historyArchiveUrl`); its entries as facts (`parseHistoryEntry`, `historyEntry`); a range of heights (`historyRange`); a transaction's details (`fetchTxDetails`, `fetchTxNonce`); and the heights a history covers (`addCoverage`, `topGap`, `shownDownTo`) |
 | `@dusk-network/app-core/shielded` | A profile's shielded history from the notes its shielded sync keeps, each block asked for among kept decoys (`shieldedHistory`); its entries as facts (`shieldedEntries`); the blocks at the notes' heights (`fetchShieldedBlocks`); the note tree's heights and the decoys drawn from them (`noteTreeHeights`, `readNoteHeights`, `createLeafHeightTap`, `pickHeights`, `leafInfo`) |
 | `@dusk-network/app-core/activity` | An account's activity as rows of facts, one per transaction, newest first, from its public and shielded history and the wallet's own sends (`activityRows`), and the sends the chain's rows now say all of (`settleSends`) |
+| `@dusk-network/app-core/bridge` | The other side of the bridge's routes: where a deposit to DuskEVM arrived (`depositArrivals`), a migration's payout on Dusk (`migrationPayouts`), and where a transfer out to BNB Smart Chain arrived (`serviceArrivals`); the history's entries as those transfers (`depositOf`, `migrationPayoutOf`, `serviceTransferOf`); and the arrivals as `/activity` takes them (`arrivalsOf`) |
+| `@dusk-network/app-core/duskevm-withdrawals` | A DuskEVM withdrawal's life, signing aside: its start on DuskEVM (`withdrawalCall`), finding an address's withdrawals (`syncWithdrawals`, `explorerWithdrawals`, `withdrawalsByNonce`), and on Dusk where each is, its proof and its claim, ready for the app's wallet to sign (`createWithdrawals`) |
 
-Every entry point has its `.d.ts`. The one runtime dependency is `@dusk-network/networks`.
+Every entry point has its `.d.ts`. The one runtime dependency is `@dusk-network/networks`. `/duskevm-withdrawals` also takes [viem](https://viem.sh) (`^2.55.2`), an optional peer: an app installs it to use that entry, and no other entry imports it.
 
 ## History
 
@@ -57,7 +59,7 @@ const { entries, complete } = await history.read({ limit: 50 });
 - `network` is the node's network or its chain ID, for the DuskEVM bridge's calls, the bridge's routes and Sozu. A node of a network there's no file for passes none.
 - `fillDetails(entries)` reads the details of entries shown before a run gave them any.
 
-An entry is facts, not text: `direction` ("in", "out", "self"), `kind` (`transfer`, `shield`, `unshield`, `contract_call`, `stake`, `unstake`, `withdraw_reward`), `counterparty`, `value` and `fee` in lux (a gas refund paid to another account counts in the sender's `value`), `memo`, and with its details its time, outcome, gas and call. A call to DuskEVM's bridge or Portal has `bridge`, what it did (`decodeBridgeCall`): a deposit's amount and DuskEVM address, or a withdrawal's proof or claim, its hash, whom it pays and its nonce. A transfer with one of the bridge's accounts has its `route` (`routeForAccount`), and a stake or an unstake with Sozu `sozu: true` (`isSozuCall`, with the pools the hub named in `read({ pools })`).
+An entry is facts, not text: `direction` ("in", "out", "self"), `kind` (`transfer`, `shield`, `unshield`, `contract_call`, `stake`, `unstake`, `withdraw_reward`), `counterparty`, `value` and `fee` in lux (a gas refund paid to another account counts in the sender's `value` and in that account's, told apart as `refund`), `memo`, and with its details its time, outcome, gas and call. A call to DuskEVM's bridge or Portal has `bridge`, what it did (`decodeBridgeCall`): a deposit's amount and DuskEVM address, or a withdrawal's proof or claim, its hash, whom it pays and its nonce. A transfer with one of the bridge's accounts has its `route` (`routeForAccount`), and a stake or an unstake with Sozu `sozu: true` (`isSozuCall`, with the pools the hub named in `read({ pools })`).
 
 ### The store
 
@@ -181,6 +183,79 @@ const { drop, keep } = settleSends({ public: entries, shielded, pending: sends }
 
 By default a send adds the name typed for its recipient, or a shielded send's recipient or memo, which the shielded history doesn't have; `keeps(send)` says what else does. A failed send that tried to move an amount is always kept: the chain's row says it moved nothing.
 
+## Bridge
+
+```js
+import { arrivalsOf, depositArrivals, depositOf } from "@dusk-network/app-core/bridge";
+
+const { arrivals } = await depositArrivals({
+  network: chainId,
+  deposits: entries.map((entry) => depositOf(entry, account)).filter(Boolean), // `/history`'s entries
+  taken: keptArrivals, // the DuskEVM transactions the app's other deposits arrived with
+  fetch,
+});
+// arrivals.get(hash): { state: "arrived", hash: "0x029e…", at: 1793080333000, amount: 500000000n, block: 3951755 }
+arrivalsOf(arrivals); // Map { hash => { hash: "0x029e…", at: 1793080333000 } }: `/activity`'s `arrivals`
+```
+
+- 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.
+- 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 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.
+
+A result is facts: `arrived`, with the other side's transaction, its block's time, the lux it paid and its block; `waiting`; or `unknown`, with why: `unsure` (a credit could be another's), `late` (none came in its window), `beyond` (the explorer's pages don't reach it), `searching` (carry on from `scan`), `expired`, `no-route`, `no-payout` or `error`. The words are the app's.
+
+`activityRows` of `/activity` takes the deposits that arrived as its `arrivals`: `arrivalsOf` gives them by the deposit's hash, the DuskEVM transaction that paid it and when, and the deposit's row says where it arrived. Its `claims` are DuskEVM withdrawals', which this entry point doesn't read.
+
+## DuskEVM withdrawals
+
+```js
+import { createWithdrawals, withdrawalCall } from "@dusk-network/app-core/duskevm-withdrawals";
+
+// The start, for the app's EVM wallet to send on DuskEVM.
+const start = withdrawalCall(chainId, { amountWei, sender: evmAddress, to: duskAccount }); // { to, data, value }
+
+const withdrawals = createWithdrawals({
+  network: chainId,
+  nodeUrl,
+  fetch: createMulticallFetch({ nodeUrl, multicallId }), // the reads one task starts go as one query
+  drivers: { optimismPortal: () => loadDriver(portalDriver), disputeGameFactory: () => loadDriver(factoryDriver) },
+  duskEvm: publicClient, // a viem client, or { url, fetch }
+});
+
+const status = await withdrawals.status(txHash, { submitter: account, proofGame });
+// { stage: "proven_waiting", reason: "game-in-progress", readyAt: 1793589639n, readyAtExact: false, facts: { amountWei, recipient, … }, … }
+
+const { call, claim } = await withdrawals.prepareProof(txHash, { submitter: account });
+// claim: when it can be claimed if proved now; call: { contractId, fnName, fnArgs, deposit: 0n, gasLimit, decoded }
+const claimCall = await withdrawals.claimCall(txHash, { submitter: account }); // once `status` says "ready_to_finalize"
+```
+
+- Only DUSK withdrawals on the bridge's route count, as Dusk's L1 bridge pays them out (`decodeWithdrawal` of `@dusk-network/networks/duskevm`): to Dusk's messenger, relaying DuskEVM's bridge to Dusk's, paying a Dusk account, or a contract only whole lux at the address DuskEVM gives it, and no one past a u64 of lux. Anything else is refused, for its status, its proof and its claim (`WithdrawalError`, `code: "not-a-withdrawal"`).
+- `stage` is where the withdrawal is for the account whose proof counts (`submitter`, a Dusk account or its Portal address; its recipient's account when none is given): "waiting_for_output", "ready_to_prove", "proven_waiting", "ready_to_finalize" or "finalized". `reason` says why it waits. A claim date is worked out as the Portal checks a claim (`claimFrom`), counted from Dusk's latest block, and is exact once the proof's game has resolved; `readyAt` is absent when the game can't be read now, so the date known so far stands. A claim is ready once the Portal takes it, its game has resolved for the defender, and its date has come: never while the game, the Portal's blacklist or the anchor state registry's word on it can't be read, nor on the Portal's own check alone, which may take just the proof and its game. A proof whose game the Portal refuses (blacklisted, retired, no longer respected, or won by the challenger) can't be claimed, whatever that check says (`proofRejected`, "proof-rejected"). `provenByOther` says another account holds a proof that stands, which this one can't claim with.
+- `proofGame`, the game the last status found the proof against, puts that game's reads in the same query as the Portal's: a check is one query.
+- A proof goes against a game that covers the withdrawal and has already resolved for its proposal, where the anchor state registry calls it proper and respected and it came after the respected game type last changed, so its claim date is exact when it's made; otherwise against the newest game that covers it, among the newest 64 (`gameSearchDepth`), that the Portal takes a proof against: a game the Portal blacklisted, the registry calls improper or not respected, or the challenger won is passed over for an older one, as is one whose standing can't be read. Where none of those is one the Portal takes, a status offers a proof against one that has resolved, as `prepareProof` finds it, to an account that never proved and to one whose proof the Portal refuses. A proof isn't prepared for a claimed withdrawal, nor over a proof of the account's that stands: it would cost its fee for nothing. One the Portal refuses is made again against another game it takes.
+- `prepareProof` and `claimCall` refuse what would do nothing or can't be made: "claimed", "proven", "no-proof", "not-ready" (with the status), and "gas" for a withdrawal whose own gas takes the limit over the app's bound (`gasLimitUpper`, 1,000,000,000 by default). The gas limit is 50M and the withdrawal's own gas, at least 1M; the price is the app's.
+- A call is encoded by the Portal's data driver the app loaded, as the network's file names and pins it, and read back before it's handed over: its arguments must say exactly the withdrawal, the game, the output root proof and the proof's nodes they were built from, as Dusk Wallet reads them (`decoded`), or it's refused ("bad-call"). It sends no DUSK along; the app signs `fnArgs` as given, with no amount and no one paid but the account itself.
+- `prepareProof` gives `at`, when it was prepared: an app that shows a proof's claim date sends that proof, for as long as it chooses.
+- `claims(hashes, { submitter })` reads when the withdrawals an account proved can be claimed, by their hashes: claimed, ready, a date, none, or to prove again. Its map is `/activity`'s `claims`.
+- `timing()` is how long a withdrawal takes: the Portal's two delays, and how often outputs come.
+
+### Finding withdrawals
+
+- `syncWithdrawals({ address, duskEvm, network, state })` reads an address's withdrawals from the bridge's own `ETHBridgeInitiated` events, the newest final blocks first, a window of 100,000 blocks at a time (narrower where the RPC asks for it), 8 requests a run. It gives the app the state to keep, and the next run carries on below and reads only what is new above. Under a final head lower than the last run's, what it covered and found above it is dropped, and read again.
+- `explorerWithdrawals({ address, network, fetch })` lists the address's own calls of the bridge on DuskEVM's explorer, each with the explorer's word for it (`explorerStage`), and `withdrawalsByNonce({ nonces, network, fetch })` finds the DuskEVM transactions of withdrawals known by the nonces their proofs and claims on Dusk carry.
+
+### Reads and caches
+
+- The Portal and the dispute game factory are read with the app's drivers; each game's hub and the anchor state registry raw. Reads go to the node's contracts through the app's `fetch` (its Multicall for Dusk batcher), sent again twice at most when the node answers 429, 502, 503 or 504; a refusal carries the contract's own words. `maxBatch` is how many reads one query holds (32 by default), each game checked taking 4: its status, the Portal's blacklist, and the registry's two answers. A game's status is read on its own hub, which the factory names: a game type's hub can change, and the games made before stay where they were.
+- What a deployment doesn't change is read once: each game's hub, each game type's hub, each hub's clock limit. `cache`, a `Map` of text by default, is where they're kept: an app can keep them across sessions.
+- Dusk's latest block comes from `latestBlock`, or the node's GraphQL. Without it, a proved withdrawal's status fails: its date can't be worked out, and no claim is built.
+
 ## License
 
 MPL-2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dusk-network/app-core",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Shared logic for the Dusk apps: public and shielded history, activity rows, bridge arrivals and DuskEVM withdrawals.",
   "license": "MPL-2.0",
   "type": "module",
@@ -21,6 +21,14 @@
       "types": "./src/activity.d.ts",
       "default": "./src/activity.js"
     },
+    "./bridge": {
+      "types": "./src/bridge.d.ts",
+      "default": "./src/bridge.js"
+    },
+    "./duskevm-withdrawals": {
+      "types": "./src/duskevm-withdrawals.d.ts",
+      "default": "./src/duskevm-withdrawals.js"
+    },
     "./package.json": "./package.json"
   },
   "files": [
@@ -35,9 +43,23 @@
     "typecheck": "npx --yes --package=typescript@5.9.3 -- tsc -p test-types",
     "check:versions": "node scripts/check-versions.js",
     "check:jsr": "npx --yes jsr@0.14.3 publish --dry-run --allow-dirty",
-    "smoke:history": "node scripts/smoke-history.js"
+    "fetch:drivers": "node scripts/fetch-drivers.js",
+    "smoke:history": "node scripts/smoke-history.js",
+    "smoke:bridge": "node scripts/smoke-bridge.js",
+    "smoke:withdrawals": "node scripts/smoke-withdrawals.js"
   },
   "dependencies": {
     "@dusk-network/networks": "0.3.0"
+  },
+  "peerDependencies": {
+    "viem": "^2.55.2"
+  },
+  "peerDependenciesMeta": {
+    "viem": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "viem": "2.55.2"
   }
 }

package/src/bridge.d.ts

@@ -0,0 +1,416 @@
+/**
+ * The other side of the bridge's routes, as facts, for the Dusk apps:
+ * whether a deposit to DuskEVM arrived there, whether a migration from BNB
+ * Smart Chain or Ethereum was paid out on Dusk, and whether a transfer out
+ * to another chain (Dusk to BNB Smart Chain) arrived there.
+ *
+ * - 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. 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 credit counts from 2 minutes before its transfer's block: Dusk's
+ *   clock and the other chain's can differ a little. A transfer's time is
+ *   its Dusk block's, never the device's clock; one without it yet isn't
+ *   looked for.
+ * - Where the credits don't say who sent the transfer (DuskEVM's explorer),
+ *   or the transfers that could have made them aren't all known, a credit
+ *   is a transfer's only when it can't be another's: within 2 minutes
+ *   either side of its block, once those minutes are over, and alone there
+ *   but for the credits of the other transfers given, a payment that
+ *   failed counting too. Otherwise the transfer is unsure.
+ * - 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. A transfer out arrives with the DUSK token's
+ *   `Transfer` from its route's payout address to the address its memo
+ *   gives, of what the route's account received less the bridge's fee, as
+ *   the transfer's own transaction says. A route without its payout account
+ *   or address in the network's file pays out nothing that can be told
+ *   apart. Facts that can't be read leave a transfer unsure, never paid.
+ * - Results are facts: arrived, with the other side's transaction, its
+ *   time, its amount in lux and its block; waiting; or unknown, and why.
+ *   The words are the app's.
+ * - 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.
+ *
+ * @example
+ * ```js
+ * import { arrivalsOf, depositArrivals, depositOf } from "@dusk/app-core/bridge";
+ *
+ * const { arrivals } = await depositArrivals({
+ *   network: chainId,
+ *   deposits: entries.map((entry) => depositOf(entry, account)).filter(Boolean),
+ *   taken: keptArrivals.map((arrival) => arrival.hash), // the DuskEVM transactions other deposits arrived with
+ *   fetch,
+ * });
+ * arrivals.get(hash); // { state: "arrived", hash: "0x029e…", at: 1793080333000, amount: 500000000n, block: 3951755 }
+ * arrivalsOf(arrivals); // `/activity`'s `arrivals`: the DuskEVM transaction that paid each deposit, and when
+ * ```
+ *
+ * @module
+ */
+
+import type { Account, EvmAddress, NetworkRef } from "@dusk-network/networks";
+import type { Archive, Direction, EntryKind } from "./history.js";
+
+/** 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;
+
+/**
+ * How long either side of its block a transfer's credit must come, where
+ * the credits can't otherwise be told apart: 2 minutes, in milliseconds.
+ */
+export declare const CREDIT_WINDOW_MS: 120000;
+
+/** How long a transfer is waited for by default before it is unknown: 7 days, in milliseconds. */
+export declare const WAIT_MS: 604800000;
+
+/** Pages of an address's incoming calls on DuskEVM's explorer read at most, by default. */
+export declare const EXPLORER_PAGES: 5;
+
+/** Blocks one log search asks for at once; narrower where the RPC asks for it. */
+export declare const LOG_WINDOW: 5000;
+
+/** Log searches one call makes for a group of equal transfers, by default. */
+export declare const LOG_WINDOWS: 8;
+
+/** Equal deposits sent within this of each other are paid in their order: 2 hours, in milliseconds. */
+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. */
+export declare const HISTORY_PAGES: 4;
+
+/** `Transfer(address,address,uint256)`: the DUSK token's transfer that pays a transfer out. */
+export declare const TRANSFER_TOPIC: "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef";
+
+/** `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";
+
+/**
+ * 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.
+ */
+export type Scan = { from: string; basis: number; search: string; seen?: ReadonlyArray<{ hash: string; block: string; at: number; sender: string | null }> };
+
+/**
+ * Why a transfer's credit is unknown:
+ * - "unsure": a credit could be another transfer's;
+ * - "late": its window closed without a credit, and one coming later can't be told apart;
+ * - "beyond": the explorer's pages don't reach back to it;
+ * - "searching": the search used its windows before it read all it needs; it carries on from `scan`;
+ * - "expired": sent longer ago than it's waited for;
+ * - "no-route": the network has no such route, or the route's payout account or address isn't known;
+ * - "no-payout": a transfer out pays nothing out, as the chain shows it (`problem`);
+ * - "error": a read failed (`error`).
+ */
+export type UnknownReason = "unsure" | "late" | "beyond" | "searching" | "expired" | "no-route" | "no-payout" | "error";
+
+/**
+ * Why a transfer out pays nothing out, as the chain shows it: it "failed"
+ * on Dusk, went "elsewhere" than the route's account, paid it no more than
+ * the bridge's fee ("under-fee"), or has a memo that isn't an address as
+ * the route's bridge reads it ("no-address").
+ */
+export type NoPayout = "failed" | "elsewhere" | "under-fee" | "no-address";
+
+/**
+ * What became of a transfer on the other side: "arrived", with the
+ * transaction there that paid it (an EVM transaction's hash, lower case, or
+ * a Dusk one's for a migration's payout), its block's time in milliseconds
+ * (null for a payout whose details aren't read yet), the lux it paid and its
+ * block; "waiting" for it; or "unknown", and why. `scan` is where the next
+ * search starts.
+ */
+export type Arrival =
+  | { state: "arrived"; hash: string; at: number | null; amount: bigint; block: number | null }
+  | { state: "waiting"; scan?: Scan }
+  | { state: "unknown"; reason: UnknownReason; error?: string; problem?: NoPayout; scan?: Scan };
+
+/** A `fetch`, as these reads use it: a GET of the explorer's JSON, or a POST of JSON-RPC, and the answer's status and text. */
+export type FetchLike = (
+  input: string,
+  init: { method: "GET" | "POST"; headers: Record<string, string>; body?: string; signal: AbortSignal }
+) => Promise<{ ok: boolean; status: number; text(): Promise<string> }>;
+
+/** The app's cache of a chain's block times, in milliseconds, by number, as a `Map` is. */
+export type BlockTimes = {
+  get(block: number): number | undefined;
+  set(block: number, at: number): unknown;
+};
+
+/** A deposit to DuskEVM that went through on Dusk (`depositOf`). Amounts in lux. */
+export type Deposit = {
+  /** Its Dusk transaction's hash. */
+  hash: string;
+  amount: bigint | number | string;
+  /** The DuskEVM address it pays. */
+  to: string;
+  /** Its Dusk block's time, in milliseconds; null until the node gave it: it isn't looked for until then. */
+  at: number | null;
+  /** The Dusk account that sent it: on the RPC, its credit is found by that account's DuskEVM address. */
+  sender?: string | null;
+  /** Its Dusk block's height: where the sender's history is read back from. */
+  height?: number | null;
+  /** A DuskEVM block its credit can't be before: the head the app read before sending it. */
+  notBefore?: bigint | number | string | null;
+  /** Where the last search for it stopped, as its result gave it. */
+  scan?: Scan | null;
+};
+
+/** What `depositArrivals` takes. */
+export type DepositArrivalOptions = {
+  /** The Dusk network, or its chain ID: its DuskEVM, and its URLs. */
+  network: NetworkRef;
+  /** The deposits waited for: each once, by hash. */
+  deposits: Iterable<Deposit>;
+  /**
+   * Where the credits are read: "explorer", the recipients' incoming calls
+   * on DuskEVM's explorer (its Blockscout API), the default; or "rpc",
+   * DuskEVM's bridge events on its RPC, by the sender's DuskEVM address.
+   */
+  via?: "explorer" | "rpc";
+  /** The `fetch` to send requests with; `globalThis.fetch` when not given. */
+  fetch?: FetchLike;
+  /** DuskEVM's explorer API; the network's by default. */
+  explorerUrl?: string;
+  /** DuskEVM's RPC; the network's by default. */
+  rpcUrl?: string;
+  /**
+   * `/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.
+   * 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.
+   */
+  archive?: Archive;
+  /**
+   * DuskEVM transactions the app's other deposits arrived with: pass those
+   * deposits through these alone, not among `deposits`. No deposit looked
+   * for takes them; one read from a sender's history may, as its own.
+   */
+  taken?: Iterable<string>;
+  /** DuskEVM's block times the app keeps, for "rpc". */
+  blockTimes?: BlockTimes;
+  /** The clock, in milliseconds. */
+  now?: number;
+  /** How long a deposit is waited for; `WAIT_MS` by default. */
+  waitMs?: number;
+  /** `CREDIT_WINDOW_MS` by default. */
+  windowMs?: number;
+  /** `EXPLORER_PAGES` by default. */
+  maxPages?: number;
+  /** `LOG_WINDOWS` by default. */
+  maxWindows?: number;
+  /** How long one request may take, in milliseconds: 8,000 by default. */
+  timeoutMs?: number;
+};
+
+/**
+ * Where each deposit arrived on DuskEVM, by its Dusk transaction's hash
+ * (lower case), in the order given, and the requests it took. Each credit
+ * pays one deposit, in the order they were sent.
+ *
+ * On the explorer, the recipient's incoming calls are read once for all its
+ * deposits, newest first, back past the oldest one waited for, at most
+ * `maxPages` pages; none is asked while every deposit's window is still
+ * open. On the RPC, a group of equal deposits from one sender is searched
+ * from about when the first was sent, `maxWindows` windows at most.
+ * 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.
+ */
+export declare function depositArrivals(options: DepositArrivalOptions): Promise<{ arrivals: Map<string, Arrival>; requests: number }>;
+
+/**
+ * A transfer out to another chain on a service route, sent to the route's
+ * account on Dusk (`serviceTransferOf`). What it paid that account, the
+ * address its memo gives, and its block's height and time are read from
+ * the chain.
+ */
+export type ServiceTransfer = {
+  /** Its Dusk transaction's hash. */
+  hash: string;
+  /** Its route's ID, as "dusk-to-bsc". */
+  route: string;
+  /** The bridge's fee, in lux; the route's by default. */
+  fee?: bigint | number | string | null;
+  /** A block of the other chain its payout can't be before: the head the app read before sending it. */
+  notBefore?: bigint | number | string | null;
+  scan?: Scan | null;
+};
+
+/** What `serviceArrivals` takes. */
+export type ServiceArrivalOptions = {
+  network: NetworkRef;
+  transfers: Iterable<ServiceTransfer>;
+  /** `/history`'s archive: each transfer, and the route's account's history, which lists the equal ones paid before. */
+  archive: Archive;
+  fetch?: FetchLike;
+  /** The other chain's RPC; the route's by default. */
+  rpcUrl?: string;
+  /** Transactions on the other chain that paid the app's other transfers, which aren't among `transfers`. */
+  taken?: Iterable<string>;
+  /** That chain's block times the app keeps. */
+  blockTimes?: BlockTimes;
+  now?: number;
+  waitMs?: number;
+  maxWindows?: number;
+  timeoutMs?: number;
+};
+
+/**
+ * Where each transfer out arrived on its chain, by its Dusk transaction's
+ * hash, in the order given, and the requests it took: the DUSK token's
+ * `Transfer` from the route's payout address to the address the memo gives,
+ * of what the route's account received less the fee. Each transfer is read
+ * from the chain, in one request: one the archive doesn't have yet is
+ * waiting, and one that pays nothing out is `no-payout`. The transfers the
+ * 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.
+ */
+export declare function serviceArrivals(options: ServiceArrivalOptions): Promise<{ arrivals: Map<string, Arrival>; requests: number }>;
+
+/** A migration into Dusk, as its chain shows it. */
+export type Migration = {
+  /** Its transaction's hash on its chain. */
+  hash: string;
+  /** Its route's ID, as "bsc-to-dusk". */
+  route: string;
+  /** The DUSK it migrates, in lux. */
+  amount: bigint | number | string;
+  /** When it was sent, in milliseconds: it's waited for `waitMs` from then. */
+  at?: number | null;
+};
+
+/** A payout of a migration, as the account's history has it (`migrationPayoutOf`). */
+export type MigrationPayout = {
+  /** The migration's transaction hash, from the memo, lower case. */
+  hash: `0x${string}`;
+  /**
+   * Its route's ID; null where its payer pays out more than one route's
+   * migrations, as one account set for both chains does: its transfer
+   * doesn't say which.
+   */
+  route: string | null;
+  /** The Dusk account that paid it: its route's payout account. */
+  payer: string;
+  /** What it paid, in lux: a gas refund paid to the account with it aside. */
+  amount: bigint;
+  /** The payout's Dusk transaction. */
+  payout: string;
+  /** Its block's time, in milliseconds; null before its details are read. */
+  at: number | null;
+  /** Its block's height. */
+  block: number;
+};
+
+/** What `migrationPayouts` takes: the account's entries, or the archive and the account. */
+export type MigrationPayoutOptions = {
+  network: NetworkRef;
+  migrations: Iterable<Migration>;
+  /** The account's public history, as `/history` reads or keeps it. */
+  entries?: Iterable<HistoryLike>;
+  /** Without `entries`: the archive's memo index is asked for each migration's payout, in one request. */
+  archive?: Archive;
+  /** The account the migrations pay, which the archive is read for. */
+  account?: string;
+  /** Payouts other migrations have. */
+  taken?: Iterable<string>;
+  now?: number;
+  waitMs?: number;
+};
+
+/**
+ * Each migration's payout on Dusk, by the migration's hash (lower case), in
+ * the order given; with `entries`, the payouts there of migrations not given
+ * (`unlisted`: sent from another device, or before); and the requests it
+ * took. Each payout pays one migration, of the route it was given with:
+ * from that route's payout account, even where that account pays out
+ * another route's too. A payout of the migration 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 (`refund` tells it apart now);
+ * the memo index gives each payout's own.
+ */
+export declare function migrationPayouts(
+  options: MigrationPayoutOptions
+): Promise<{ payouts: Map<string, Arrival>; unlisted: MigrationPayout[]; requests: number }>;
+
+/** An entry of an account's public history, as `/history` reads or keeps it: amounts as bigints or decimal strings. */
+export type HistoryLike = {
+  hash: string;
+  blockHeight: number;
+  direction: Direction;
+  kind: EntryKind;
+  counterparty: string | null;
+  value: bigint | string;
+  /** Of `value`, a gas refund paid to another account than the sender. */
+  refund?: bigint | string | null;
+  memo: string;
+  payer: boolean;
+  timestamp?: number | null;
+  success?: boolean | null;
+  bridge?: { kind: string; amount?: string; to?: string } | null;
+  [field: string]: unknown;
+};
+
+/**
+ * A deposit to DuskEVM the account sent, from its entry, once its details
+ * read its call: its amount and DuskEVM address, its block's time and
+ * height, and `account` as its sender. Null for any other entry, and for one
+ * that failed.
+ */
+export declare function depositOf(entry: HistoryLike, account?: Account): (Deposit & { amount: bigint; to: EvmAddress }) | null;
+
+/** A transfer to a service route's account, and why it pays nothing out, if it doesn't. */
+export type ServiceTransferFacts = {
+  hash: string;
+  route: string;
+  /** What left the account: the transfer, and any gas refund it paid another account, which the entry doesn't tell apart. */
+  sent: bigint;
+  /** 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. */
+  to: string | null;
+  at: number | null;
+  height: number | null;
+  /** "failed" on Dusk; "under-fee": no more than the fee left the account; "no-address": a memo that isn't an address; null when none is known. */
+  problem: "failed" | "under-fee" | "no-address" | null;
+};
+
+/**
+ * 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.
+ */
+export declare function serviceTransferOf(entry: HistoryLike, network: NetworkRef): 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.
+ */
+export declare function migrationPayoutOf(entry: HistoryLike, network: NetworkRef): MigrationPayout | null;
+
+/**
+ * The deposits that arrived, as `/activity`'s `arrivals` takes them: by the
+ * deposit's hash, the DuskEVM transaction that paid it and when.
+ */
+export declare function arrivalsOf(arrivals: ReadonlyMap<string, Arrival>): Map<string, { hash: string; at: number | null }>;