@dusk-network/networks 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 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
+
+- `/duskevm`: when a DuskEVM withdrawal can be claimed, whether it can be claimed now, and which dispute games a proof can go against
+- `duskEvm.l1AdapterUrl`: the DuskEVM adapter's RPC beside DuskEVM's own
+
 ## [0.1.0]
 
 ### Added

package/README.md

@@ -28,6 +28,7 @@ The entry points are the same on both, under each registry's name: `@dusk-networ
 | `@dusk-network/networks` | `networks`, `networkFor(chainId)`, `labelFor(net, id)`, `isBlocked(net, account)`, `blockedReason(net, account)`, `routes(net)`, `bridgeLink(net, { route, to })` |
 | `@dusk-network/networks/sozu` | Sozu's fee, stDUSK and minimum rules, its gas, the hub's argument bytes, the reply decoders and `readSozuStatus` |
 | `@dusk-network/networks/rates` | `nativeRateEstimate` and `sozuRateEstimate`, as yearly fractions |
+| `@dusk-network/networks/duskevm` | When a DuskEVM withdrawal can be claimed (`claimFrom`), whether it can be claimed now (`claimReadiness`), the games a proof can go against (`isEligibleGame`), and the contracts' clock |
 | `@dusk-network/networks/format` | `formatDusk`, `formatDuskPlain`, `formatTime`, `formatContractId`, `shortAccount`, `formatEvmAddress` |
 | `@dusk-network/networks/networks/<name>.json` | `mainnet`, `testnet` or `devnet` as data |
 | `@dusk-network/networks/schema.json` | The files' JSON Schema |
@@ -71,6 +72,15 @@ const call = sozuCall(status.contracts.pool, SOZU_FN.STAKE, amount); // { contra
 const { limit, minimum } = SOZU_GAS[call.fnName]; // warn while typing under the minimum
 ```
 
+A DuskEVM withdrawal's claim date comes from the chain: the app reads the proof's dispute game on its hub, the Portal's two delays and Dusk's latest block, and `/duskevm` works out the date as the Portal checks a claim:
+
+```js
+import { claimFrom, claimReadiness } from "@dusk-network/networks/duskevm";
+
+const claim = claimFrom({ provenAt, game, portal, tip }); // { at, exact, overdue }: "about" until the game resolves
+claimReadiness({ claim, portalAccepts, tip }).ready; // the Portal's yes counts from the date only
+```
+
 The bridge takes a route and a Dusk recipient in its link. `bridgeLink` builds it, and gives null while the network's bridge has no published address:
 
 ```js

package/networks/testnet.json

@@ -44,6 +44,7 @@
       "symbol": "DUSK"
     },
     "rpcUrl": "https://rpc.testnet.evm.dusk.network",
+    "l1AdapterUrl": "https://rpc.testnet.evm.dusk.network/l1",
     "explorerUrl": "https://explorer.testnet.evm.dusk.network",
     "blockscoutApiUrl": "https://explorer.testnet.evm.dusk.network/api/v2",
     "predeploys": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dusk-network/networks",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Dusk's networks for the Dusk apps: endpoints, contracts, routes and labels, with Sozu's rules, reward estimates and shared formats.",
   "license": "MPL-2.0",
   "type": "module",
@@ -25,6 +25,10 @@
       "types": "./src/format.d.ts",
       "default": "./src/format.js"
     },
+    "./duskevm": {
+      "types": "./src/duskevm.d.ts",
+      "default": "./src/duskevm.js"
+    },
     "./networks/*.json": {
       "types": "./src/network-file.d.ts",
       "default": "./networks/*.json"

package/schema.json

@@ -250,12 +250,16 @@
     "duskEvm": {
       "type": "object",
       "additionalProperties": false,
-      "required": ["name", "chainId", "currency", "rpcUrl", "explorerUrl", "blockscoutApiUrl", "predeploys", "drivers", "contracts", "source"],
+      "required": ["name", "chainId", "currency", "rpcUrl", "l1AdapterUrl", "explorerUrl", "blockscoutApiUrl", "predeploys", "drivers", "contracts", "source"],
       "properties": {
         "name": { "description": "The chain's name as wallets list it.", "type": "string", "minLength": 1 },
         "chainId": { "type": "integer", "minimum": 1 },
         "currency": { "$ref": "#/$defs/currency" },
         "rpcUrl": { "$ref": "#/$defs/url" },
+        "l1AdapterUrl": {
+          "description": "The DuskEVM adapter's RPC beside the chain's own. It answers for DuskEVM (its chain ID); the bridge asks it which DuskEVM deposit a Dusk transaction made.",
+          "$ref": "#/$defs/url"
+        },
         "explorerUrl": { "$ref": "#/$defs/url" },
         "blockscoutApiUrl": { "$ref": "#/$defs/url" },
         "predeploys": {

package/src/duskevm.d.ts

@@ -0,0 +1,144 @@
+/**
+ * When a DuskEVM withdrawal can be claimed on Dusk, worked out the way the
+ * Portal checks a claim: from the later of the proof's maturity
+ * (`proofMaturityDelaySeconds` after it was made) and its dispute game's
+ * finality (`disputeGameFinalityDelaySeconds` after the game resolved).
+ * Exact once the game has resolved; before that, the earliest it can be,
+ * from the game's clock (`maxClockDuration`). Pure: each app reads the
+ * game, the Portal and Dusk's latest block itself.
+ *
+ * @example
+ * ```js
+ * import { claimFrom, claimReadiness } from "@dusk/networks/duskevm";
+ *
+ * const claim = claimFrom({
+ *   provenAt: 46_877_440n, // the Portal's proof time
+ *   game: { createdAt: 46_876_050n, resolvedAt: 0n, status: 0, maxClockDuration: 302_400n },
+ *   portal: { proofMaturityDelaySeconds: 604_800n, disputeGameFinalityDelaySeconds: 302_400n },
+ *   tip: { height: 4_704_959n, timestamp: 1_793_156_989n }, // Dusk's latest block
+ * });
+ * // { at: Date.UTC(2026, 10, 2, 3, 20, 39), exact: false, overdue: false }: "about Mon 2 Nov, 04:20 CET"
+ * claimReadiness({ claim, portalAccepts: false, tip }); // { ready: false, readyAt: 1793589639n, … }
+ * ```
+ *
+ * @module
+ */
+
+/** Dusk's latest block: its height, and its time in seconds. */
+export type DuskTip = { height: bigint | number; timestamp: bigint | number };
+
+/** What a deployment's contracts count: Dusk block height × 10 (testnet), or block time. */
+export type ContractClock = "height" | "timestamp";
+
+/** A dispute game as its hub gives it, with the hub's clock limit. */
+export type ClaimGame = {
+  createdAt: bigint | number;
+  resolvedAt: bigint | number;
+  status: number;
+  maxClockDuration: bigint | number;
+};
+
+/** The Portal's two delays, in the contracts' seconds. */
+export type PortalDelays = {
+  proofMaturityDelaySeconds: bigint | number;
+  disputeGameFinalityDelaySeconds: bigint | number;
+};
+
+/** What `claimFrom` takes. */
+export type ClaimInput = {
+  /** The Portal's proof time, in the contracts' time; none for a proof made now. */
+  provenAt?: bigint | number | null;
+  /** The proof's dispute game; none when it couldn't be read. */
+  game: ClaimGame | null | undefined;
+  portal: PortalDelays;
+  tip: DuskTip;
+  /** The deployment's clock; read from the game's own time when not given. */
+  clock?: ContractClock;
+};
+
+/**
+ * When a withdrawal can be claimed: `at` in milliseconds, `exact` once the
+ * game has resolved (else "about"), `overdue` when the game is more than
+ * an hour late to resolve. `at` is null when the challenger won, or the hub
+ * doesn't know the game.
+ */
+export type ClaimDate = { at: number | null; exact: boolean; overdue: boolean };
+
+/**
+ * What a claim date means now: `ready` to claim, from when (`readyAt`, in
+ * seconds), and `refused` when the date has passed while the Portal still
+ * refuses the claim, so the date says nothing more.
+ */
+export type ClaimReadiness = {
+  ready: boolean;
+  readyAt: bigint | null;
+  readyAtExact: boolean;
+  claimOverdue: boolean;
+  refused: boolean;
+};
+
+/** What decides which games a proof can go against. */
+export type GameRules = {
+  /** The anchor state registry's `respectedGameTypeUpdatedAt`: games created then or before are retired. */
+  respectedGameTypeUpdatedAt: bigint | number;
+  /** The L2 block of the withdrawal: a game must cover it. */
+  withdrawalBlockNumber: bigint | number;
+};
+
+/** A game with its hub's status and the registry's answers; null where one couldn't be read. */
+export type GameCheck = {
+  createdAt: bigint | number;
+  l2BlockNumber: bigint | number;
+  status: number | null;
+  proper: boolean | null;
+  respected: boolean | null;
+};
+
+/** A dispute game's status, as its hub gives it. */
+export declare const GAME_STATUS: Readonly<{ IN_PROGRESS: 0; CHALLENGER_WINS: 1; DEFENDER_WINS: 2 }>;
+
+/** A game still unresolved this long past the earliest it could resolve is overdue: an hour. */
+export declare const OVERDUE_SECONDS: bigint;
+
+/** The clock a deployment's contracts keep, read from one of their times and the tip. */
+export declare function contractClock(sample: bigint | number, tip: DuskTip): ContractClock;
+
+/** The contracts' time at the tip. */
+export declare function contractNow(clock: ContractClock, tip: DuskTip): bigint;
+
+/** A contract time as wall-clock milliseconds. */
+export declare function wallTime(seconds: bigint | number, clock: ContractClock, tip: DuskTip): number;
+
+/**
+ * When a withdrawal can be claimed: from max(proof + maturity, game
+ * resolved + finality), exact once the game has resolved, the earliest
+ * before.
+ */
+export declare function claimFrom(input: ClaimInput): ClaimDate;
+
+/**
+ * Whether a proven withdrawal can be claimed now: once the Portal's check
+ * passes and its date has come, not before.
+ */
+export declare function claimReadiness(input: {
+  claim: ClaimDate | null | undefined;
+  portalAccepts: boolean;
+  tip: DuskTip;
+}): ClaimReadiness;
+
+/**
+ * Whether a game is worth checking for a proof, before its status and the
+ * registry are read: it covers the withdrawal, and it was created after the
+ * respected game type last changed.
+ */
+export declare function isCandidateGame(
+  game: { createdAt: bigint | number; l2BlockNumber: bigint | number },
+  rules: GameRules
+): boolean;
+
+/**
+ * Whether a proof can go against a game and be claimed exactly its maturity
+ * delay later: a candidate that has resolved for its proposal (the defender
+ * won), and that the registry calls proper and respected.
+ */
+export declare function isEligibleGame(game: GameCheck, rules: GameRules): boolean;

package/src/duskevm.js

@@ -0,0 +1,170 @@
+/* @ts-self-types="./duskevm.d.ts" */
+/**
+ * When a DuskEVM withdrawal can be claimed on Dusk, worked out the way the
+ * Portal checks a claim:
+ * - the proof has matured: `proofMaturityDelaySeconds` after it was made;
+ * - its dispute game has resolved for its proposal and is final:
+ *   `disputeGameFinalityDelaySeconds` after it resolved.
+ * It's exact once the game has resolved. Before that, the game resolves no
+ * sooner than its clock runs out (`maxClockDuration` after it was created),
+ * which gives the earliest date, an estimate.
+ *
+ * The times are the contracts' own. The deployed testnet contracts count
+ * Dusk block height × 10; the others count block time and compare
+ * strictly, so a claim there comes a second later. Pure: each app reads the
+ * game, the Portal and Dusk's latest block itself, and passes them in.
+ *
+ * @module
+ */
+
+/** @typedef {import("./duskevm.js").DuskTip} DuskTip */
+/** @typedef {import("./duskevm.js").ContractClock} ContractClock */
+/** @typedef {import("./duskevm.js").ClaimDate} ClaimDate */
+
+/** A dispute game's status, as its hub gives it. */
+export const GAME_STATUS = Object.freeze({
+  CHALLENGER_WINS: 1,
+  DEFENDER_WINS: 2,
+  IN_PROGRESS: 0,
+});
+
+/** A game still unresolved this long past the earliest it could resolve is overdue. */
+export const OVERDUE_SECONDS = 3_600n;
+
+/** @type {ClaimDate} */
+const NO_DATE = Object.freeze({ at: null, exact: false, overdue: false });
+
+/**
+ * @param {bigint} a
+ * @param {bigint} b
+ */
+const distance = (a, b) => (a > b ? a - b : b - a);
+
+/**
+ * @param {bigint} a
+ * @param {bigint} b
+ */
+const later = (a, b) => (a > b ? a : b);
+
+/**
+ * At the tip the two clocks are decades apart, so a time is on whichever
+ * it's nearer.
+ *
+ * @param {bigint | number} sample
+ * @param {DuskTip} tip
+ * @returns {ContractClock}
+ */
+export function contractClock(sample, tip) {
+  const time = BigInt(sample);
+
+  return distance(time, 10n * BigInt(tip.height)) < distance(time, BigInt(tip.timestamp))
+    ? "height"
+    : "timestamp";
+}
+
+/**
+ * @param {ContractClock} clock
+ * @param {DuskTip} tip
+ * @returns {bigint}
+ */
+export const contractNow = (clock, tip) =>
+  clock === "height" ? 10n * BigInt(tip.height) : BigInt(tip.timestamp);
+
+/**
+ * On the height clock a time is counted from the tip, at Dusk's 10 seconds
+ * a block.
+ *
+ * @param {bigint | number} seconds
+ * @param {ContractClock} clock
+ * @param {DuskTip} tip
+ * @returns {number}
+ */
+export function wallTime(seconds, clock, tip) {
+  const time = BigInt(seconds);
+  const wall = clock === "height" ? BigInt(tip.timestamp) + time - 10n * BigInt(tip.height) : time;
+
+  return Number(wall) * 1_000;
+}
+
+/**
+ * @param {import("./duskevm.js").ClaimInput} input
+ * @returns {ClaimDate}
+ */
+export function claimFrom({ clock, game, portal, provenAt = null, tip }) {
+  if (!game) {
+    return NO_DATE;
+  }
+
+  const created = BigInt(game.createdAt);
+  const status = Number(game.status);
+
+  if (created === 0n || status === GAME_STATUS.CHALLENGER_WINS) {
+    return NO_DATE;
+  }
+
+  const counted = clock ?? contractClock(created, tip);
+  const now = contractNow(counted, tip);
+  // A block-time deployment compares strictly: a second after the delay.
+  const strict = counted === "height" ? 0n : 1n;
+  const resolved = status === GAME_STATUS.DEFENDER_WINS;
+  // The earliest the game resolves: once its clock has run out, and not before now.
+  const settles = created + BigInt(game.maxClockDuration);
+  const resolvedAt = resolved ? BigInt(game.resolvedAt) : later(now, settles);
+  const matured = (provenAt ? BigInt(provenAt) : now) + BigInt(portal.proofMaturityDelaySeconds);
+  const final = resolvedAt + BigInt(portal.disputeGameFinalityDelaySeconds);
+
+  return {
+    at: wallTime(later(matured, final) + strict, counted, tip),
+    exact: resolved,
+    overdue: !resolved && now > settles + OVERDUE_SECONDS,
+  };
+}
+
+/**
+ * A claim is ready from its date only: a Portal whose check takes just the
+ * proof and its game says yes before it, and refuses the claim itself. A
+ * date that has passed while the Portal still refuses the claim says
+ * nothing more.
+ *
+ * @param {{ claim: ClaimDate | null | undefined, portalAccepts: boolean, tip: DuskTip }} input
+ * @returns {import("./duskevm.js").ClaimReadiness}
+ */
+export function claimReadiness({ claim, portalAccepts, tip }) {
+  const readyAt = claim?.at == null ? null : BigInt(Math.floor(claim.at / 1_000));
+  const due = readyAt === null || readyAt <= BigInt(tip.timestamp);
+
+  if (portalAccepts && due) {
+    return { claimOverdue: false, ready: true, readyAt, readyAtExact: Boolean(claim?.exact), refused: false };
+  }
+
+  const refused = !portalAccepts && readyAt !== null && due;
+
+  return {
+    claimOverdue: Boolean(claim?.overdue),
+    ready: false,
+    readyAt: refused ? null : readyAt,
+    readyAtExact: refused ? false : Boolean(claim?.exact),
+    refused,
+  };
+}
+
+/**
+ * @param {{ createdAt: bigint | number, l2BlockNumber: bigint | number }} game
+ * @param {import("./duskevm.js").GameRules} rules
+ * @returns {boolean}
+ */
+export const isCandidateGame = (game, { respectedGameTypeUpdatedAt, withdrawalBlockNumber }) =>
+  BigInt(game.l2BlockNumber) >= BigInt(withdrawalBlockNumber) &&
+  BigInt(game.createdAt) > BigInt(respectedGameTypeUpdatedAt);
+
+/**
+ * @param {import("./duskevm.js").GameCheck} game
+ * @param {import("./duskevm.js").GameRules} rules
+ * @returns {boolean}
+ */
+export const isEligibleGame = (game, rules) =>
+  isCandidateGame(game, rules) &&
+  game.status != null &&
+  Number(game.status) === GAME_STATUS.DEFENDER_WINS &&
+  game.proper === true &&
+  game.respected === true;

package/src/index.d.ts

@@ -56,6 +56,8 @@ export type DuskEvm = ChainFields &
   Readonly<{
     /** The chain's name as wallets list it. */
     name: string;
+    /** The DuskEVM adapter's RPC beside the chain's own, which the bridge asks which DuskEVM deposit a Dusk transaction made. */
+    l1AdapterUrl: string;
     blockscoutApiUrl: string;
     predeploys: Readonly<{
       l1Block: EvmAddress;