@dusk-network/app-core 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 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.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,6 +30,7 @@ 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`) |
 
 Every entry point has its `.d.ts`. The one runtime dependency is `@dusk-network/networks`.
 
@@ -181,6 +182,34 @@ 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, 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: an entry's value holds any gas refund paid to the account. With `entries`, the payouts there of migrations the app didn't list come too (`unlisted`).
+- 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.
+
 ## License
 
 MPL-2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dusk-network/app-core",
-  "version": "0.1.0",
+  "version": "0.2.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,10 @@
       "types": "./src/activity.d.ts",
       "default": "./src/activity.js"
     },
+    "./bridge": {
+      "types": "./src/bridge.d.ts",
+      "default": "./src/bridge.js"
+    },
     "./package.json": "./package.json"
   },
   "files": [
@@ -35,7 +39,8 @@
     "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"
+    "smoke:history": "node scripts/smoke-history.js",
+    "smoke:bridge": "node scripts/smoke-bridge.js"
   },
   "dependencies": {
     "@dusk-network/networks": "0.3.0"

package/src/bridge.d.ts

@@ -0,0 +1,402 @@
+/**
+ * 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}`;
+  route: string;
+  /** What it paid, in lux. */
+  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. A payout of the migration of another
+ * amount leaves it unsure, not waiting: an entry's value holds any gas
+ * refund paid to the account; 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;
+  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. 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 }>;