@dusk-network/app-core 0.4.0 → 0.4.1

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 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.4.1]
+
+### Changed
+
+- `/duskevm-withdrawals`: a withdrawal's receipt is kept in `cache` once its DuskEVM block is final, and read once
+
+### Fixed
+
+- `/bridge`: a memo of bytes that aren't text (`memoBinary`) gives no payout address, and names no migration
+
 ## [0.4.0]
 
 ### Added

package/README.md

@@ -206,8 +206,8 @@ arrivalsOf(arrivals); // Map { hash => { hash: "0x029e…", at: 1793080333000 }
 - 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 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 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 migration is paid by a transfer to the account from its route's payout account, with the migration's transaction hash as the memo, as text, 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, as text: a memo of bytes that aren't text gives none), and its block. It arrives with the DUSK token's `Transfer` from its route's payout address to that address, of what the account received less the fee. The account's history lists every transfer that named the same address, in any case: equal ones in the hours before (a given one's by its own fee) are paid first, and one that can't be read leaves the order unclear. One that pays nothing out is `no-payout`, with its `problem`. `serviceTransferOf` gives what left the account (`sent`), and what the account received (`amount`) only where no gas was left to refund: an entry's value holds any refund paid to another account.
 - With the archive, each transfer reads only its own hours of its account's history (its sender's for a deposit, the route's account's for a transfer out), further back while equal ones before it run on, and only once the archive lists the transfer there. A call reads 4 pages of it (`HISTORY_PAGES`) for each: a transfer whose history is longer waits, and the next call reads on from its `scan`.
 - A route without its payout account or address in the network's file pays out nothing that can be told apart: `no-route`.
 - An RPC search starts at a block from before the transfer, 10 minutes before it as the chain's pace says, checked by its time and stepped back until it is, and reads 8 windows at most: of 5,000 blocks, twice as many after each one the RPC answers whole, up to 100,000, and fewer where it asks for it, the width kept in the search's `scan` from call to call. A call reads a chain's head and pace once for all its searches. Once a deposit's windows are over and read, a search without its sender's history reads no further. It reads each block more than once: its window at the head reaches back 1,000 blocks, so the newest blocks are read again on each call, and once it has reached the head with a transfer not arrived, it reads its blocks again from the first, a pass at a time with the windows a call has left (one at least while a pass is under way, so 9 where the search ahead takes all 8): the first a minute later, each one after as long again as it has been since it reached the head. Where a later equal transfer, still without its credit, could have had the credit an earlier one takes, the earlier one waits until the blocks are read again 8 times since the credit was found, one pass after the other. 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. The block times the app keeps (`blockTimes`) are a chain's: for transfers out, a cache a chain by its chain ID, or one cache where the network's service routes are all on one chain.
@@ -258,7 +258,7 @@ const claimCall = await withdrawals.claimCall(txHash, { submitter: account }); /
 ### 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.
+- What a deployment doesn't change is read once: each game's hub, each game type's hub, each hub's clock limit, and a withdrawal's receipt once its DuskEVM block is final. A receipt is read after DuskEVM's finalized block, one read for the receipts read at the same time, and kept when its block is at or under that one; one that isn't final yet, or isn't a withdrawal's, is read again each time. `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

package/package.json

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

package/src/bridge.d.ts

@@ -409,6 +409,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 +435,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,16 +446,18 @@ 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;
 
 /**
  * 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;
 

package/src/bridge.js

@@ -1278,19 +1278,24 @@ function exactJson(text) {
   return JSON.parse(text.replace(TOKEN, (match, string) => string ?? (/^-?\d+$/.test(match) && !Number.isSafeInteger(Number(match)) ? `"${match}"` : match)));
 }
 
-const utf8 = new TextDecoder();
+const utf8 = new TextDecoder("utf-8", { fatal: true });
 
 /**
- * A memo's bytes, given as hex, as text, read as the route's bridge reads
- * them: as UTF-8, bytes that aren't UTF-8 becoming the replacement
- * character; "" for none.
+ * A memo's bytes, given as hex, as UTF-8 text; "" for none, and for bytes
+ * that aren't UTF-8: an address or a hash is read from text only.
  *
  * @param {unknown} hex
  */
 function memoOf(hex) {
   const text = String(hex ?? "").replace(/^0x/i, "");
 
-  return /^(?:[0-9a-fA-F]{2})+$/.test(text) ? utf8.decode(Uint8Array.from(text.match(/../g) ?? [], (byte) => parseInt(byte, 16))) : "";
+  if (!/^(?:[0-9a-fA-F]{2})+$/.test(text)) return "";
+
+  try {
+    return utf8.decode(Uint8Array.from(text.match(/../g) ?? [], (byte) => parseInt(byte, 16)));
+  } catch {
+    return "";
+  }
 }
 
 /**
@@ -2451,8 +2456,9 @@ export function serviceTransferOf(entry, network) {
   const spent = luxOf(entry.gasSpent);
   const price = luxOf(entry.gasPrice);
   const amount = limit !== null && spent !== null && price !== null && (limit - spent) * price <= 0n ? value : null;
-  // The address the memo gives, exactly as the bridge reads it.
-  const memo = typeof entry.memo === "string" ? entry.memo : "";
+  // The address the memo gives, exactly as the bridge reads it: from text.
+  // A memo of bytes that aren't text, which /history gives as 0x hex, gives none.
+  const memo = typeof entry.memo === "string" && entry.memoBinary !== true ? entry.memo : "";
   const to = EVM_ADDRESS.test(memo) ? memo : null;
   const problem = entry.success === false ? "failed" : value <= route.feeLux ? "under-fee" : to === null ? "no-address" : null;
 
@@ -2470,9 +2476,8 @@ export function migrationPayoutOf(entry, network) {
   const { at, hash, height, value } = factsOf(entry);
   // What the transfer paid: a gas refund paid to the account with it aside.
   const refund = entry?.refund === undefined || entry.refund === null ? 0n : luxOf(entry.refund);
-  const memo = String(entry?.memo ?? "")
-    .trim()
-    .toLowerCase();
+  // The migration's hash, as text: a memo of bytes that aren't text names none.
+  const memo = entry?.memoBinary === true ? "" : String(entry?.memo ?? "").trim().toLowerCase();
 
   if (!paying.length || entry.success === false || !hash || height === null || value === null || refund === null || refund > value || !EVM_HASH.test(memo)) {
     return null;

package/src/duskevm-withdrawals.d.ts

@@ -359,7 +359,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, each game
+   * type's hub, 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 +372,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

package/src/duskevm-withdrawals.js

@@ -773,6 +773,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
 // ---------------------------------------------------------------------------
@@ -1223,13 +1237,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));
   }
 
   /**