@meantjs/reconcile 0.0.0-bootstrap → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog: @meantjs/reconcile
+
+The five Candid Profile library packages (`@meantjs/profile`, `/format`, `/consent`, `/tools`, `/reconcile`) release together under one version and pin each other exactly; a version appears here even when this package did not change. Release steps: `docs/releasing.md` in the repository.
+
+## 0.1.0 — 2026-10-28
+
+First published version.
+
+Published under the `@meantjs` scope (D-051). Before any release, this package was `@candid-core/profile-reconcile`.
+
+- After an unknown outcome, the ICRC-3 block an ICRC-1/2 write leaves (`expectedTransaction`) and whether the blocks
+  read since the first send hold it: found, absent, not yet, or unreadable with a lookalike (`matchBlocks`). Every
+  rule errs on the safe side: never "absent" while a send may still land.
+- No transport and no Node built-in: runs in browsers.
+- TypeScript declarations.

package/README.md

@@ -1,5 +1,70 @@
-# @meantjs/reconcile 0.0.0-bootstrap
+# @meantjs/reconcile
 
-This version is a placeholder with no code. It exists because npm can attach a trusted publisher only to a
-package that is already on the registry. Every real version is published by the repository's release workflow.
-Install `@meantjs/reconcile` without a tag to get the latest released version.
+Consumer rule 1 (`docs/profile-v0.md` section 7.3) without a transport: after an unknown outcome, before any new
+attempt, is the original in the ledger's ICRC-3 history? One dependency: `@meantjs/format` (principal
+text to bytes).
+
+```sh
+npm install @meantjs/reconcile
+```
+
+- **Runs on:** Node 22 or later and browsers: no Node built-in, no `Buffer` (`test/browser-bundle.test.mjs`).
+- **Module format:** ES modules only, with hand-written TypeScript declarations for every entry.
+- **Spec:** [Candid Profile v0](https://github.com/B3Pay/Meant/blob/main/profile/docs/profile-v0.md). **Licence:** Apache-2.0.
+- **Versions:** the five Candid Profile packages (`@meantjs/profile`, `/format`, `/consent`, `/tools`,
+  `/reconcile`) release together under one version and pin each other exactly; in 0.x a minor is breaking,
+  and so is any change to generated text ([releasing](https://github.com/B3Pay/Meant/blob/main/profile/docs/releasing.md)).
+
+```js
+import { expectedTransaction, matchBlocks } from "@meantjs/reconcile";
+
+const expected = expectedTransaction("icrc1_transfer", arg, callerText, { minting });  // minting: icrc1_minting_account
+// Read the blocks yourself (certified, archives followed): every index from `floor` to `logLength - 1`.
+const r = matchBlocks(blocks, expected, { logLength, floor, inFlight: true, ledgerTime, windowNs });  // windowNs: the ledger's TX_WINDOW + PERMITTED_DRIFT
+r.status; // "found" (r.block) | "absent" (r.closedBy) | "not_yet" (r.openUntil) | "unreadable" (r.reason, r.lookalike?)
+```
+
+| Input | Shape |
+|---|---|
+| `arg` | the call's argument record as candid-core values: `amount`, `created_at_time`, `fee` bigint; accounts `{ owner: <principal text>, subaccount: Uint8Array \| null }`; `memo` Uint8Array or null |
+| `blocks` | `[{ id: bigint, block }]`, `block` an ICRC-3 value in `{ tag, value }` form (`Map`, `Array`, `Nat`, `Text`, `Blob`) |
+
+Rules, all in the safe direction (`src/index.mjs` header):
+
+- An absent field is part of the match: an empty memo is not no memo. An optional Nat (`fee`, `expires_at`,
+  `expected_allowance`) in another shape equals nothing, not even an absent one.
+- The operation is the block's `btype` when it has one (`1xfer`, `2xfer`, `1mint`, `1burn`, `2approve`; ICRC-3 makes
+  it authoritative), else the legacy `tx.op`. An unknown `btype` matches nothing, and a `btype` that is present but
+  not Text makes the block unreadable (no fallback to `tx.op`). A transfer also needs the btype its
+  method leaves (`1xfer` for `icrc1_transfer`, `2xfer` for `icrc2_transfer_from`) when the block has one.
+- A transfer from the minting account is a `mint`, one to it a `burn` (the same for a `transfer_from` from or to it);
+  a spender's own `transfer_from` matches only under a `2xfer` btype, with or without `spender` in the block: ICRC-3 lets an `icrc1_transfer` block carry `tx.spender` too, so a legacy block (no btype) reads the same and is a lookalike. A mint or burn through `transfer_from` with no `spender` in the block stays a lookalike: another spender's call reads the same.
+  A block with a `spender` the call does not have is another call.
+- A legacy `xfer` block with neither `btype` nor `spender` is the `icrc1_transfer`'s, by the owner's decision of
+  2026-10-19 (#29 review). ICRC-3 would also let another principal's `icrc2_transfer_from` with the caller's exact
+  stamp, amount, accounts, fee and memo leave such a block, so the match accepts that case. **Fact:** the pinned
+  DFINITY ledger writes no `btype` and records `spender` in every `transfer_from` block (the key set in
+  `test/reconcile.test.mjs:1-6`), so there such a block can only be the transfer. Treating it as a lookalike would
+  leave every `icrc1_transfer` on that ledger held for a person to review. In the accepted case the funds still moved
+  where the call asked, so a `found` cannot pay twice.
+- A call whose subaccount is not bytes maps to no block (`undefined`), so no side is dropped from the match.
+- A block with the call's stamp and amount from the call's account (or from an account it cannot read) in another
+  shape is a **lookalike**: `unreadable`
+  with that block, never `absent`. An amount above u64::MAX counts as u64::MAX (the DFINITY ledger's u64 build caps
+  an approval and writes the capped amount). A block of the same operation naming another recipient or spender is
+  another call. `notOriginal` takes blocks the person rejected out of the next read.
+- `absent` only when nothing can still land: every send answered (`answered`), a TooOld (`too_old`), or the
+  ledger's clock past stamp + `windowNs` (`window_passed`). `windowNs` is the ledger's own window (spec section 7.3:
+  the ledger defines it); without it nothing closes by the clock and the answer is `not_yet` with a `reason`.
+  `DEDUP_WINDOW_NS` (24 h 2 min, the DFINITY ledger's default) is exported for a caller that has checked its ledger
+  uses it. Otherwise `not_yet`. Without a ledger clock, the later of `ledgerTimeAtLeast` and the tip block's time stands in.
+- Blocks that do not cover `floor..logLength-1`, or a block in that range whose operation or amount (or stamp, when
+  it has one) cannot be read, are `unreadable`.
+
+Tests: `test/reconcile.test.mjs`, on blocks built in the shapes W2 recorded from the pinned DFINITY ledger wasm
+(`docs/status/W2.md`, 2026-10-09). **Fact:** each rule above has a test that fails when the rule is removed
+(memo lenience, mint mapping, u64 cap, the window, the coverage check, `btype`, the spender rule, unreadable blocks). **Not observed on a real ledger:** a `burn`,
+a spender's own `transfer_from`, a mint through `transfer_from` and a `btype` block; they follow ICRC-1/2/3 as written.
+
+Arm C's own matcher (`packages/mcp-adapters/src/arm-c/history.mjs`) does not use this module yet: that is an arm C
+change under D-015, proposed in `docs/proposals/w3b-reconcile-module.md`.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@meantjs/reconcile",
-  "version": "0.0.0-bootstrap",
-  "description": "Placeholder that registers the name for trusted publishing. Install a released version of @meantjs/reconcile instead.",
+  "version": "0.1.0",
+  "description": "Consumer rule 1 without a transport: the ICRC-3 block an ICRC-1/2 write leaves, and whether the blocks a caller read since its first send hold it (found, absent, not yet, or unreadable with a lookalike). Browser-safe.",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -9,8 +9,43 @@
     "directory": "profile/packages/reconcile"
   },
   "homepage": "https://github.com/B3Pay/Meant/tree/main/profile/packages/reconcile#readme",
+  "bugs": {
+    "url": "https://github.com/B3Pay/Meant/issues"
+  },
+  "keywords": [
+    "candid",
+    "internet-computer",
+    "icp",
+    "icrc-3",
+    "idempotency",
+    "reconcile"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./src/index.mjs",
+  "types": "./src/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.mts",
+      "default": "./src/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
   "files": [
-    "README.md",
+    "src",
+    "CHANGELOG.md",
     "LICENSE"
-  ]
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "test": "node --test \"test/*.test.mjs\""
+  },
+  "dependencies": {
+    "@meantjs/format": "0.1.0"
+  },
+  "devDependencies": {
+    "esbuild": "0.28.2"
+  }
 }

package/src/index.d.mts

@@ -0,0 +1,101 @@
+// Types for @meantjs/reconcile. Hand-written; the source is src/index.mjs.
+// test/types.test.mjs keeps the declared names equal to the runtime exports, and `npm run types` compiles a consumer
+// against these declarations under strict TypeScript.
+
+/** ICRC-1 TX_WINDOW plus PERMITTED_DRIFT of the DFINITY ledger (24 h 2 min, in ns). */
+export const DEDUP_WINDOW_NS: bigint;
+/** u64::MAX: where the DFINITY ledger's u64 build caps an approval above it. */
+export const U64_MAX: bigint;
+/** The methods this module maps to a block. */
+export const METHODS: readonly ["icrc1_transfer", "icrc2_approve", "icrc2_transfer_from"];
+export type ReconciledMethod = (typeof METHODS)[number];
+
+/** An account as ICRC-3 compares it: owner bytes and a 64-hex subaccount (all zero for the default). */
+export interface AccountKey {
+  owner: string;
+  subaccount: string;
+}
+/** An ICRC-1 account in candid-core's domain shape. */
+export interface Account {
+  owner: string;
+  subaccount?: Uint8Array | null;
+}
+
+/** The ICRC-3 transaction a call leaves in the log, as `expectedTransaction` maps it. */
+export interface ExpectedTransaction {
+  op: "xfer" | "mint" | "burn" | "approve";
+  /** `1xfer` or `2xfer` for a transfer (ICRC-3 makes `btype` authoritative when a block has one). */
+  btype?: "1xfer" | "2xfer";
+  ts: bigint;
+  amt: bigint;
+  /** Hex, or null for no memo (an empty memo is not no memo). */
+  memo: string | null;
+  fee: bigint | null;
+  from?: AccountKey;
+  to?: AccountKey;
+  spender?: AccountKey;
+  /** A mint by `transfer_from` whose spender is the minting account may leave `spender` out. */
+  spenderOptional?: true;
+  expires_at?: bigint | null;
+  expected_allowance?: bigint | null;
+}
+
+/**
+ * The ICRC-3 transaction a call leaves. `arg` is the call's argument record as candid-core values (`amount` and
+ * `created_at_time` bigint, accounts `{ owner: <principal text>, subaccount: Uint8Array | null }`, `memo` Uint8Array
+ * or null). Undefined for a method this module does not map, a call without a stamp, or an unreadable caller.
+ *
+ * @param options.minting the ledger's `icrc1_minting_account`: a transfer from it is a mint, to it a burn
+ */
+export function expectedTransaction(
+  method: string,
+  arg: Record<string, unknown>,
+  caller: string,
+  options?: { minting?: Account | null },
+): ExpectedTransaction | undefined;
+
+/** An ICRC-3 value in the `{ tag, value }` shape. */
+export type Icrc3Value =
+  | { tag: "Map"; value: [string, Icrc3Value][] }
+  | { tag: "Array"; value: Icrc3Value[] }
+  | { tag: "Nat"; value: bigint }
+  | { tag: "Int"; value: bigint }
+  | { tag: "Text"; value: string }
+  | { tag: "Blob"; value: Uint8Array };
+
+/** Whether an ICRC-3 block carries exactly this transaction. */
+export function blockMatches(block: Icrc3Value, expected: ExpectedTransaction | undefined): boolean;
+
+export interface MatchOptions {
+  /** The log length when the blocks were read (`icrc3_get_blocks` `log_length`). */
+  logLength: bigint;
+  /** The log length before the first send (default 0). */
+  floor?: bigint;
+  /** A send of the call had an unknown outcome, so it may still execute until refused. */
+  inFlight: boolean;
+  /** A send was answered TooOld (sound only for blocks read after that answer). */
+  stampExpired?: boolean;
+  /** The ledger's clock (ns), where the caller has it. */
+  ledgerTime?: bigint;
+  /** A time the ledger's clock is at least. */
+  ledgerTimeAtLeast?: bigint;
+  /** How long after its stamp a call can still execute (`DEDUP_WINDOW_NS` for the DFINITY ledger). */
+  windowNs?: bigint;
+  /** Blocks the person said are not the original. */
+  notOriginal?: bigint[];
+}
+
+export type ClockReading = { at: bigint; by: string };
+export type MatchResult =
+  | { status: "found"; block: bigint }
+  | { status: "absent"; closedBy: "answered" | "too_old" | "window_passed"; clock?: ClockReading }
+  | { status: "not_yet"; openUntil?: bigint; reason?: string; clock?: ClockReading }
+  | { status: "unreadable"; reason: string; lookalike?: { block: bigint; op: string; capped: boolean } };
+
+/**
+ * Judge the blocks a caller read since the call's first send: found, absent, not yet, or unreadable (never
+ * "absent" while a send may still land or a block in the range could not be read).
+ *
+ * @param blocks ICRC-3 blocks with their indices, together holding every index from `floor` to `logLength - 1`
+ */
+export function matchBlocks(blocks: { id: bigint; block: Icrc3Value }[], expected: ExpectedTransaction | undefined, options: MatchOptions): MatchResult;

package/src/index.mjs

@@ -0,0 +1,333 @@
+// Consumer rule 1 (docs/profile-v0.md section 7.3) without a transport. After an unknown outcome, before any new
+// attempt, look for the original in the ledger's history: the ICRC-3 blocks since the first send, matched on the
+// operation, the stamp, the amount, the fee, the accounts (the caller's included), the memo and, for an approval,
+// its expiry and expected allowance.
+//
+// The caller reads the blocks (certified, and from archives when it needs them) and passes them in; this module
+// only maps a call to the block it leaves and judges the blocks. It imports no Node built-in and needs no codec:
+// arguments are candid-core values (bigint, Uint8Array, principal text) and blocks are ICRC-3 values in the
+// `{ tag, value }` shape (`Map`, `Array`, `Nat`, `Int`, `Text`, `Blob`).
+//
+// Rules, each one in the safe direction:
+// - An absent field is part of the match: an empty memo is not no memo (a ledger keeps an empty memo and
+//   deduplicates it apart from none), and a block with a `spender` the call has not is another call.
+// - The operation is the block's `btype` when it has one (ICRC-3 makes it authoritative), else its legacy `tx.op`.
+// - A block in the range whose operation or amount (or stamp, when it has one) cannot be read is `unreadable`,
+//   never "no match".
+// - A call whose accounts cannot be read (a subaccount that is not bytes) maps to no block, so it is never
+//   matched with a side left out.
+// - A block that carries the call's stamp and amount from the call's account, in a shape the mapping does not know,
+//   is a lookalike: the answer is `unreadable` with that block, never `absent`. An amount above u64::MAX counts as
+//   u64::MAX here, because the DFINITY ledger's u64 build caps an approval there and writes the capped amount.
+// - A block of the call's own operation that names another recipient or spender is another call, not a lookalike.
+// - No block settles nothing while a send of the call may still land: `absent` only when no send is unknown, a send
+//   was answered TooOld, or the ledger's clock is past the stamp's window; otherwise `not_yet`.
+// - Blocks that do not cover every index from the first send to the tip are `unreadable`, never `absent`.
+//
+// Ledger knowledge the profile does not carry yet (no pack says it): the call-to-block mapping per method, the
+// minting account turning a transfer into a mint or a burn, and the window (ICRC-1 TX_WINDOW plus PERMITTED_DRIFT,
+// the DFINITY ledger's 24 hours and 2 minutes). The window is an option.
+import { principalFromText } from "@meantjs/format";
+
+/** ICRC-1 TX_WINDOW plus PERMITTED_DRIFT of the DFINITY ledger: how long after its stamp a call can still execute. */
+export const DEDUP_WINDOW_NS = (24n * 60n + 2n) * 60n * 1_000_000_000n;
+/** u64::MAX: where the DFINITY ledger's u64 build caps an approval above it. */
+export const U64_MAX = 2n ** 64n - 1n;
+/** The methods this module maps to a block. */
+export const METHODS = Object.freeze(["icrc1_transfer", "icrc2_approve", "icrc2_transfer_from"]);
+
+const ZERO = "0".repeat(64);
+const TypedArrayPrototype = Object.getPrototypeOf(Uint8Array.prototype);
+const typedArrayTag = Object.getOwnPropertyDescriptor(TypedArrayPrototype, Symbol.toStringTag).get;
+const typedArrayValues = TypedArrayPrototype.values;
+/**
+ * Whether a view's memory can be read now: not detached, and not out of bounds after its resizable buffer shrank.
+ * The intrinsic `values` validates the view the way reading it does (ValidateTypedArray) and throws otherwise.
+ */
+function isReadable(view) {
+  try {
+    typedArrayValues.call(view);
+    return true;
+  } catch {
+    return false;
+  }
+}
+/** A Uint8Array from any realm whose memory can be read (not detached, not out of bounds). */
+const isBytes = (v) => ArrayBuffer.isView(v) && typedArrayTag.call(v) === "Uint8Array" && isReadable(v);
+const hex = (bytes) => Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+
+/** An account as owner bytes and a 64-hex subaccount (zero for none): how ICRC-3 compares accounts. */
+function keyOf(owner, subaccount) {
+  let bytes;
+  try {
+    bytes = principalFromText(owner);
+  } catch {
+    return undefined;
+  }
+  if (subaccount !== null && subaccount !== undefined && !isBytes(subaccount)) return undefined;
+  return { owner: hex(bytes), subaccount: subaccount === null || subaccount === undefined ? ZERO : hex(subaccount) };
+}
+const accountKey = (account) => (account === null || account === undefined || typeof account !== "object" ? undefined : keyOf(account.owner, account.subaccount));
+const sameKey = (a, b) => a !== undefined && b !== undefined && a.owner === b.owner && a.subaccount === b.subaccount;
+const natOrNull = (v) => (typeof v === "bigint" ? v : null);
+const present = (key, value) => (value === undefined ? {} : { [key]: value });
+
+/**
+ * The ICRC-3 transaction a call leaves in the log.
+ *
+ * @param {string} method  `icrc1_transfer`, `icrc2_approve` or `icrc2_transfer_from`
+ * @param {Record<string, unknown>} arg  the call's argument record as candid-core values (`amount` and
+ *        `created_at_time` bigint, accounts `{ owner: <principal text>, subaccount: Uint8Array | null }`, `memo`
+ *        Uint8Array or null)
+ * @param {string} caller  the caller's principal text
+ * @param {{ minting?: { owner: string, subaccount?: Uint8Array | null } | null }} [options]  the ledger's
+ *        `icrc1_minting_account`: a transfer from it is a `mint` (no `from`), one to it a `burn` (no `to`)
+ * @returns the expected transaction (a transfer also carries the `btype` it leaves, `1xfer` or `2xfer`), or
+ *          `undefined` for a method this module does not map, a call without a stamp
+ *          (nothing makes its block specific) or an unreadable caller
+ */
+export function expectedTransaction(method, arg, caller, { minting = null } = {}) {
+  if (arg === null || typeof arg !== "object") return undefined;
+  const ts = arg.created_at_time;
+  if (typeof ts !== "bigint" || typeof arg.amount !== "bigint") return undefined;
+  if (arg.memo !== null && arg.memo !== undefined && !isBytes(arg.memo)) return undefined;
+  const callerKey = (sub) => keyOf(caller, sub);
+  if (callerKey(null) === undefined) return undefined;
+  for (const key of ["from_subaccount", "spender_subaccount"]) if (arg[key] !== null && arg[key] !== undefined && !isBytes(arg[key])) return undefined;
+  const common = { ts, amt: arg.amount, memo: isBytes(arg.memo) ? hex(arg.memo) : null, fee: natOrNull(arg.fee) };
+  const mint = accountKey(minting);
+  switch (method) {
+    case "icrc1_transfer": {
+      const from = callerKey(arg.from_subaccount);
+      const to = accountKey(arg.to);
+      if (from === undefined || to === undefined) return undefined;
+      if (sameKey(from, mint)) return { ...common, op: "mint", to };
+      if (sameKey(to, mint)) return { ...common, op: "burn", from };
+      return { ...common, op: "xfer", btype: "1xfer", from, to };
+    }
+    case "icrc2_approve": {
+      const spender = accountKey(arg.spender);
+      const from = callerKey(arg.from_subaccount);
+      if (spender === undefined || from === undefined) return undefined;
+      return {
+        ...common,
+        op: "approve",
+        from,
+        spender,
+        expires_at: natOrNull(arg.expires_at),
+        expected_allowance: natOrNull(arg.expected_allowance),
+      };
+    }
+    case "icrc2_transfer_from": {
+      const from = accountKey(arg.from);
+      const to = accountKey(arg.to);
+      if (from === undefined || to === undefined) return undefined;
+      const spender = callerKey(arg.spender_subaccount);
+      if (spender === undefined) return undefined;
+      // From the minting account it is a mint (no `from`), as the reference ledger classes it; to it, a burn (no `to`).
+      // A mint block may leave `spender` out; then it cannot tell which spender made the call, so that is optional
+      // only when the spender is the minting account itself.
+      if (sameKey(from, mint)) return { ...common, op: "mint", to, spender, ...(sameKey(spender, from) ? { spenderOptional: true } : {}) };
+      const burning = sameKey(to, mint);
+      return {
+        ...common,
+        op: burning ? "burn" : "xfer",
+        ...(burning ? {} : { btype: "2xfer" }),
+        from,
+        ...present("to", burning ? undefined : to),
+        spender,
+        // A spender spending its own account: a ledger may leave `spender` out of the block.
+        ...(sameKey(spender, from) ? { spenderOptional: true } : {}),
+      };
+    }
+    default:
+      return undefined;
+  }
+}
+
+// ---- ICRC-3 values -------------------------------------------------------------------------------------------
+
+const get = (value, key) => (value?.tag === "Map" && Array.isArray(value.value) ? value.value.find((e) => Array.isArray(e) && e[0] === key)?.[1] : undefined);
+const natOf = (v) => (v?.tag === "Nat" && typeof v.value === "bigint" ? v.value : undefined);
+/** An optional Nat field: null when absent, its value when a Nat, undefined when present but not a Nat (equal to nothing). */
+const optNat = (map, key) => {
+  const v = get(map, key);
+  return v === undefined ? null : natOf(v);
+};
+const textOf = (v) => (v?.tag === "Text" && typeof v.value === "string" ? v.value : undefined);
+const blobOf = (v) => (v?.tag === "Blob" && isBytes(v.value) ? v.value : undefined);
+/** ICRC-3 block types (the ICRC-1/2 block schema) as the legacy `tx.op` names. */
+const BTYPES = { "1xfer": "xfer", "2xfer": "xfer", "1mint": "mint", "1burn": "burn", "2approve": "approve" };
+/**
+ * A block's operation: its `btype` when it has one (authoritative), else `tx.op`. An unknown btype matches nothing; a
+ * `btype` that is present but not Text is unreadable (undefined), never a reason to fall back to `tx.op`.
+ */
+function opOf(block) {
+  const raw = get(block, "btype");
+  if (raw !== undefined) {
+    const btype = textOf(raw);
+    if (btype === undefined) return undefined;
+    return Object.hasOwn(BTYPES, btype) ? BTYPES[btype] : `btype:${btype}`;
+  }
+  return textOf(get(get(block, "tx"), "op"));
+}
+/** Whether a block's operation and amount can be read, and its stamp when it has one (a call without one leaves none). */
+function readable(block) {
+  const tx = get(block, "tx");
+  const ts = get(tx, "ts");
+  return opOf(block) !== undefined && natOf(get(tx, "amt")) !== undefined && (ts === undefined || natOf(ts) !== undefined);
+}
+
+/** An ICRC-3 account: `Array [Blob owner]` or `Array [Blob owner, Blob subaccount]`. */
+function keyOfValue(v) {
+  if (v?.tag !== "Array" || !Array.isArray(v.value) || v.value.length < 1 || v.value.length > 2) return undefined;
+  const owner = blobOf(v.value[0]);
+  const sub = v.value.length === 2 ? blobOf(v.value[1]) : undefined;
+  if (owner === undefined || (v.value.length === 2 && sub === undefined)) return undefined;
+  return { owner: hex(owner), subaccount: sub === undefined ? ZERO : hex(sub) };
+}
+
+/** Whether an ICRC-3 block carries exactly this transaction. */
+export function blockMatches(block, expected) {
+  const tx = get(block, "tx");
+  if (tx === undefined || expected === undefined) return false;
+  if (opOf(block) !== expected.op) return false;
+  // `1xfer` and `2xfer` both read as `xfer`, but the btype tells an icrc1_transfer from an icrc2_transfer_from.
+  const btype = textOf(get(block, "btype"));
+  if (btype !== undefined && expected.btype !== undefined && btype !== expected.btype) return false;
+  // A spender's own transfer_from moves the same funds as an icrc1_transfer from that account, and ICRC-3 lets either
+  // block carry `tx.spender` ("it CAN contain"), so only a `2xfer` btype tells them apart; a legacy block is a lookalike.
+  if (expected.op === "xfer" && expected.spenderOptional === true && btype !== "2xfer") return false;
+  if (natOf(get(tx, "ts")) !== expected.ts) return false;
+  if (natOf(get(tx, "amt")) !== expected.amt) return false;
+  if (optNat(tx, "fee") !== expected.fee) return false;
+  const memo = get(tx, "memo");
+  if (memo !== undefined && blobOf(memo) === undefined) return false;
+  if ((memo === undefined ? null : hex(blobOf(memo))) !== expected.memo) return false;
+  for (const side of ["from", "to", "spender"]) {
+    const want = expected[side];
+    const have = get(tx, side);
+    // Without `spender`, only a `2xfer` btype tells a spender's own transfer_from from an icrc1_transfer (or a mint or
+    // burn) with the same fields; a mint or burn stays a lookalike.
+    if (side === "spender" && expected.spenderOptional === true && have === undefined && btype === "2xfer") continue;
+    if (want === undefined) {
+      if (have !== undefined) return false;
+      continue;
+    }
+    if (!sameKey(keyOfValue(have), want)) return false;
+  }
+  if (expected.op === "approve") {
+    if (optNat(tx, "expires_at") !== (expected.expires_at ?? null)) return false;
+    if (optNat(tx, "expected_allowance") !== (expected.expected_allowance ?? null)) return false;
+  }
+  return true;
+}
+
+/**
+ * A block with the call's stamp and amount from the call's account (or from none), whatever else it says: it may
+ * be the original in a shape the mapping does not know. An amount above u64::MAX counts as u64::MAX too.
+ */
+function looksLikeIt(block, expected) {
+  const tx = get(block, "tx");
+  const amt = natOf(get(tx, "amt"));
+  const sameAmount = amt === expected.amt || (expected.amt > U64_MAX && amt === U64_MAX);
+  if (natOf(get(tx, "ts")) !== expected.ts || !sameAmount) return false;
+  // only a source that reads as another account rules the block out; one in a shape this cannot read may be the call's
+  const from = keyOfValue(get(tx, "from"));
+  if (from !== undefined && expected.from !== undefined && !sameKey(from, expected.from)) return false;
+  return !namesAnother(block, tx, expected);
+}
+
+/** A block of the call's own operation that names another recipient or spender than the call: another call. */
+function namesAnother(block, tx, expected) {
+  if (opOf(block) !== expected.op) return false;
+  // `1xfer` and `2xfer` both read as `xfer`, but the btype tells an icrc1_transfer from an icrc2_transfer_from.
+  const btype = textOf(get(block, "btype"));
+  if (btype !== undefined && expected.btype !== undefined && btype !== expected.btype) return false;
+  // A spender's own transfer_from moves the same funds as an icrc1_transfer from that account, and ICRC-3 lets either
+  // block carry `tx.spender` ("it CAN contain"), so only a `2xfer` btype tells them apart; a legacy block is a lookalike.
+  if (expected.op === "xfer" && expected.spenderOptional === true && btype !== "2xfer") return false;
+  return ["to", "spender"].some((side) => {
+    const want = expected[side];
+    const have = keyOfValue(get(tx, side));
+    return want !== undefined && have !== undefined && !sameKey(have, want);
+  });
+}
+
+/**
+ * Judge the blocks a caller read since the call's first send.
+ *
+ * @param {{ id: bigint, block: object }[]} blocks  ICRC-3 blocks with their indices, in any order; together they
+ *        must hold every index from `floor` to `logLength - 1`
+ * @param expected  from {@link expectedTransaction}
+ * @param {object} o
+ * @param {bigint} o.logLength  the log length when the blocks were read (`icrc3_get_blocks` `log_length`)
+ * @param {bigint} [o.floor]  the log length before the first send: the original is at this index or later (default 0)
+ * @param {boolean} o.inFlight  a send of the call had an unknown outcome, so it may still execute until refused
+ * @param {boolean} [o.stampExpired]  a send was answered TooOld: the ledger refuses the stamp from then on. Sound
+ *        only when `blocks` were read after that answer arrived: a block written before it is in them then.
+ * @param {bigint} [o.ledgerTime]  the ledger's clock (ns), where the caller has it; otherwise the later of
+ *        `ledgerTimeAtLeast` and the tip block's time stands in (both lower bounds on a clock that only moves forward)
+ * @param {bigint} [o.ledgerTimeAtLeast]  a time the ledger's clock is at least (this machine's clock less the
+ *        permitted drift, for a ledger that took this machine's stamps)
+ * @param {bigint} [o.windowNs]  how long after its stamp a call can still execute: the ledger's TX_WINDOW plus
+ *        PERMITTED_DRIFT ({@link DEDUP_WINDOW_NS} for the DFINITY ledger's defaults). Without it an in-flight call
+ *        stays `not_yet`: nothing closes by the clock.
+ * @param {bigint[]} [o.notOriginal]  blocks the person said are not the original: never a lookalike again
+ * @returns {{ status: "found", block: bigint }
+ *   | { status: "absent", closedBy: "answered" | "too_old" | "window_passed", clock?: { at: bigint, by: string } }
+ *   | { status: "not_yet", openUntil?: bigint, reason?: string, clock?: { at: bigint, by: string } }
+ *   | { status: "unreadable", reason: string, lookalike?: { block: bigint, op: string, capped: boolean } }}
+ */
+export function matchBlocks(blocks, expected, o) {
+  if (expected === undefined) return { status: "unreadable", reason: "no rule maps this call to a block (no stamp, or an unknown method)" };
+  if (typeof o?.logLength !== "bigint") throw new TypeError("matchBlocks: logLength (bigint) is required");
+  if (typeof o.inFlight !== "boolean") throw new TypeError("matchBlocks: inFlight (boolean) is required");
+  const floor = o.floor ?? 0n;
+  if (floor > o.logLength) return { status: "unreadable", reason: `the log has ${o.logLength} blocks, fewer than the ${floor} it had before the first send` };
+
+  const byId = new Map();
+  for (const b of blocks) if (typeof b?.id === "bigint") byId.set(b.id, b.block);
+  for (let id = floor; id < o.logLength; id++) {
+    if (!byId.has(id)) return { status: "unreadable", reason: `block ${id} since the first send was not read (an archive, or a short page)` };
+  }
+  // An exact original wins over blocks this module cannot read: another standard's blocks share the log (ICRC-3).
+  for (let id = o.logLength - 1n; id >= floor; id--) if (blockMatches(byId.get(id), expected)) return { status: "found", block: id };
+  for (let id = floor; id < o.logLength; id++) {
+    if (!readable(byId.get(id))) return { status: "unreadable", reason: `block ${id} has no operation or amount this module can read, or a stamp that is not a Nat` };
+  }
+
+  let lookalike;
+  for (let id = o.logLength - 1n; id >= floor; id--) {
+    const block = byId.get(id);
+    if (lookalike === undefined && !(o.notOriginal ?? []).includes(id) && looksLikeIt(block, expected)) {
+      const tx = get(block, "tx");
+      lookalike = { block: id, op: opOf(block) ?? "?", capped: natOf(get(tx, "amt")) !== expected.amt };
+    }
+  }
+  if (lookalike !== undefined) {
+    return {
+      status: "unreadable",
+      reason: lookalike.capped
+        ? `block ${lookalike.block} (op ${lookalike.op}) carries this call's stamp from its account with the amount capped at u64::MAX: it may be the original`
+        : `block ${lookalike.block} (op ${lookalike.op}) carries this call's stamp and amount from its account in another shape: it may be the original`,
+      lookalike,
+    };
+  }
+
+  if (!o.inFlight) return { status: "absent", closedBy: "answered" };
+  if (o.stampExpired === true) return { status: "absent", closedBy: "too_old" };
+  let clock;
+  if (typeof o.ledgerTime === "bigint") clock = { at: o.ledgerTime, by: "ledger" };
+  else {
+    const tipTime = o.logLength > 0n ? natOf(get(byId.get(o.logLength - 1n), "ts")) : undefined;
+    const host = typeof o.ledgerTimeAtLeast === "bigint" ? o.ledgerTimeAtLeast : undefined;
+    if (host !== undefined && (tipTime === undefined || host >= tipTime)) clock = { at: host, by: "host" };
+    else if (tipTime !== undefined) clock = { at: tipTime, by: "block" };
+  }
+  // The window is the ledger's (TX_WINDOW plus PERMITTED_DRIFT, spec 4.3): without it nothing closes by the clock.
+  if (typeof o.windowNs !== "bigint") return { status: "not_yet", reason: "no windowNs: the ledger's deduplication window is not known, so a send may still land", ...present("clock", clock) };
+  const openUntil = expected.ts + o.windowNs;
+  if (clock !== undefined && clock.at > openUntil) return { status: "absent", closedBy: "window_passed", clock };
+  return { status: "not_yet", openUntil, ...present("clock", clock) };
+}