@integraledger/lcp-binding-canton-x402 0.9.0

package/src/adapter.ts

@@ -0,0 +1,265 @@
+/**
+ * The Canton adapter — thin I/O over an injected participant-reader port. It is a **Canton-native
+ * surface**, NOT binding-core's `WeldAdapter`: that port is EVM-shaped (`SettlementRef` is a `0x`-hex tx
+ * hash, `ChainReader` speaks `eth_getLogs`), whereas a Canton settlement is a ledger update read via the
+ * Daml JSON Ledger API over HTTP.
+ *
+ * **THE CARRIER.** x402's `exact` scheme for Canton: the seller advertises `PaymentRequirements.extra.memo`,
+ * the payer MUST echo it into the transfer's metadata under `x402.memo`, and the facilitator MUST reject
+ * `invalid_exact_canton_memo_mismatch` if the two disagree. One transaction settles each payment (scheme
+ * §Protocol Flow): the payer signs a `TransferFactory_Transfer` naming the merchant as receiver and does
+ * NOT submit it; the facilitator relays the signed submission and pays the traffic fee; the merchant's
+ * standing `TransferPreapproval` resolves it `direct`.
+ *
+ * So the weld, the value and the settlement are one on-ledger event, and `recover` reads all three off a
+ * single update. The `LcpAnchor` overlay this replaced pointed at a SEPARATE contract — which is exactly
+ * why it could bind no asset: the thing it referenced was not the thing that moved the money.
+ *
+ * `recover` refuses rather than throwing: an update under audit may be any transaction on the party's
+ * stream, and "this is not an LCP settlement" is an answer, not an error. `propose` throws, because a
+ * seller advertising a malformed memo is a wiring defect and the facilitator would reject the payment.
+ */
+import type { BindingManifest, Outcome } from "@integraledger/lcp-binding-core";
+import { atrHashEquals, isAtrHash } from "@integraledger/lcp-kernel";
+import { readTransferMemoAtrHash, x402MemoRequirement } from "./memo.js";
+
+/**
+ * A Canton settlement reference — the ledger update id of the transfer the facilitator relayed.
+ *
+ * One id, because one transaction settles each payment.
+ */
+export interface CantonX402SettlementRef {
+  updateId: string;
+}
+
+/**
+ * A settled `TransferFactory_Transfer` as one participant sees it.
+ *
+ * The asset fields are carried rather than decoded and discarded, and that is what lets the manifest
+ * declare `assetBinding: "carried"` honestly: the axis asks whether a CONSUMER can reach the asset the
+ * weld is attached to, not merely whether the chain recorded it.
+ */
+export interface CantonX402TransferView {
+  /** The transfer's on-ledger metadata map. The memo rides `x402.memo` (scheme safety check 12). */
+  meta: Readonly<Record<string, string>>;
+  /** Receiving party id — the merchant's `payTo` in the scheme's `PaymentRequirements`. */
+  receiver: string;
+  /** Atomic units as an integer string (1 CC = 1e10 units), exactly as the ledger records it. */
+  amount: string;
+  /** The Canton Coin instrument identifier `{ admin, id }`. */
+  instrumentId: { admin: string; id: string };
+}
+
+/** What a settled LCP transfer yields: the weld, and the asset it is welded to. */
+export interface CantonX402Settlement {
+  state: "settled";
+  atrHash: `0x${string}`;
+  receiver: string;
+  amount: string;
+  instrumentId: { admin: string; id: string };
+}
+
+/**
+ * Reads the participant's update stream over the Daml JSON Ledger API. Injected so the adapter is pure
+ * and testable; a live implementation wraps a participant URL and a party bearer JWT.
+ */
+export interface CantonX402Reader {
+  /** One settled transfer by ledger update id, or `null` if the participant has no such update. */
+  transferView(updateId: string): Promise<CantonX402TransferView | null>;
+  /** Update ids of transfers visible to `party`, most recent first. A participant view, not an index. */
+  transfersFor(party: string, limit?: number): Promise<string[]>;
+}
+
+/** The Canton x402 rail's surface. `propose` returns an `extra` fragment for the SELLER to merge into its
+ *  `PaymentRequirements` — this rail's weld is committed by the seller and echoed by the payer, unlike the
+ *  memo rails where the payer chooses the value. Its reach is exactly x402's `exact` Canton scheme, which
+ *  settles Canton Coin only; anything else on Canton needs `@integraledger/lcp-binding-canton`'s overlay. */
+export interface CantonX402Adapter {
+  manifest: BindingManifest;
+  /**
+   * The `extra` fragment the seller merges into its x402 `PaymentRequirements`, committing it to the memo
+   * the payer must echo. Throws on a malformed atrHash.
+   */
+  propose(atrHash: string): { readonly memo: string };
+  /** Recover the atrHash from a settled transfer, or a `verification-failure` Refusal if none binds. */
+  recover(
+    ref: CantonX402SettlementRef,
+    reader: CantonX402Reader,
+  ): Promise<Outcome<`0x${string}`>>;
+  /** Report the `settled` transition, with the asset the weld is attached to. */
+  observe(
+    ref: CantonX402SettlementRef,
+    reader: CantonX402Reader,
+  ): Promise<Outcome<CantonX402Settlement>>;
+  /** Scan one party's visible transfers for `atrHash` — a participant view, never a global index. */
+  enumerate(
+    atrHash: string,
+    party: string,
+    reader: CantonX402Reader,
+    limit?: number,
+  ): Promise<CantonX402SettlementRef[]>;
+}
+
+/** Config for a live Daml JSON Ledger API participant reader. */
+export interface CantonX402ReaderConfig {
+  /** JSON Ledger API base URL — e.g. `https://164.92.95.184.nip.io`. */
+  jsonLedgerUrl: string;
+  /** Bearer JWT authenticating the reading party on the participant. */
+  bearerJwt: string;
+}
+
+/**
+ * A live `CantonX402Reader` over the Daml JSON Ledger API, PURE `fetch` — no Daml SDK.
+ *
+ * Fails LOUD on a non-2xx response or a Daml `errors[]` envelope; an absent update surfaces as `null`,
+ * because a reference the participant cannot see is a value the caller must classify, not a transport
+ * failure. No package id is required — the memo rides the CIP-56 token-standard transfer, so unlike the
+ * overlay this replaced there is no deployment-specific DAR to deploy or configure.
+ */
+export function makeCantonX402Reader(
+  cfg: CantonX402ReaderConfig,
+): CantonX402Reader {
+  if (cfg.jsonLedgerUrl.length === 0)
+    throw new Error("makeCantonX402Reader: jsonLedgerUrl is empty");
+  if (cfg.bearerJwt.length === 0)
+    throw new Error("makeCantonX402Reader: bearerJwt is empty");
+
+  async function ledgerCall<T>(path: string, body: unknown): Promise<T> {
+    const res = await fetch(`${cfg.jsonLedgerUrl}${path}`, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        authorization: `Bearer ${cfg.bearerJwt}`,
+      },
+      body: JSON.stringify(body),
+    });
+    if (!res.ok) {
+      const text = await res.text().catch(() => "");
+      throw new Error(`Daml ${path} HTTP ${res.status}: ${text}`);
+    }
+    const envelope = (await res.json()) as { result?: T; errors?: string[] };
+    if (envelope.errors !== undefined && envelope.errors.length > 0)
+      throw new Error(`Daml ${path} errors: ${envelope.errors.join("; ")}`);
+    if (envelope.result === undefined)
+      throw new Error(`Daml ${path} returned no result`);
+    return envelope.result;
+  }
+
+  return {
+    async transferView(
+      updateId: string,
+    ): Promise<CantonX402TransferView | null> {
+      const result = await ledgerCall<CantonX402TransferView | null>(
+        "/v1/updates/transfer",
+        { updateId },
+      );
+      return result ?? null;
+    },
+    async transfersFor(party: string, limit?: number): Promise<string[]> {
+      return ledgerCall<string[]>("/v1/updates/transfers", {
+        party,
+        ...(limit !== undefined ? { limit } : {}),
+      });
+    },
+  };
+}
+
+/** Construct the Canton x402 adapter. **The manifest is injected, not baked in** — pass this package's own
+ *  `CANTON_X402_MANIFEST`; a manifest whose `rail` is not `"canton:x402"` throws, because an adapter over
+ *  another rail's manifest would publish that rail's claims as its own. Nothing has to be deployed first:
+ *  the memo rides the token-standard transfer, so there is no DAR here. This is the package's entry point. */
+export function createCantonX402Adapter(
+  manifest: BindingManifest,
+): CantonX402Adapter {
+  // Fail-fast: an adapter constructed over another rail's manifest would report that rail's claims as
+  // this one's. The EVM adapters bake their module const in; the injectable factories refuse instead.
+  // Stryker disable next-line all: the guard runs during test-module load (the repository's
+  // test suite constructs the adapter at describe scope), so its mutants are 'static' — outside the vitest
+  // runner's per-test attribution and unkillable by any test that in fact kills them behaviorally
+  // (each rail pins both arms: valid manifest constructs, wrong rail throws by message).
+  if (manifest.rail !== "canton:x402")
+    throw new Error(
+      `createCantonX402Adapter: manifest.rail "${manifest.rail}" is not "canton:x402"`,
+    );
+
+  // Closure helper (not `this`) so the returned methods stay destructure-safe.
+  async function readSettlement(
+    ref: CantonX402SettlementRef,
+    reader: CantonX402Reader,
+  ): Promise<Outcome<CantonX402Settlement>> {
+    const view = await reader.transferView(ref.updateId);
+    if (view === null)
+      return {
+        refused: true,
+        haltClass: "verification-failure",
+        code: "canton/no-such-update",
+        detail: `the participant has no transfer at updateId ${ref.updateId}`,
+      };
+    const atrHash = readTransferMemoAtrHash(view.meta);
+    if (atrHash === null)
+      return {
+        refused: true,
+        haltClass: "verification-failure",
+        code: "canton/no-lcp-memo",
+        detail: `the transfer at updateId ${ref.updateId} carries no well-formed atrHash under x402.memo`,
+      };
+    return {
+      ok: true,
+      value: {
+        state: "settled",
+        atrHash,
+        receiver: view.receiver,
+        amount: view.amount,
+        instrumentId: view.instrumentId,
+      },
+    };
+  }
+
+  return {
+    manifest,
+
+    propose(atrHash: string): { readonly memo: string } {
+      return x402MemoRequirement(atrHash);
+    },
+
+    async recover(
+      ref: CantonX402SettlementRef,
+      reader: CantonX402Reader,
+    ): Promise<Outcome<`0x${string}`>> {
+      const settlement = await readSettlement(ref, reader);
+      return "refused" in settlement
+        ? settlement
+        : { ok: true, value: settlement.value.atrHash };
+    },
+
+    observe(
+      ref: CantonX402SettlementRef,
+      reader: CantonX402Reader,
+    ): Promise<Outcome<CantonX402Settlement>> {
+      return readSettlement(ref, reader);
+    },
+
+    async enumerate(
+      atrHash: string,
+      party: string,
+      reader: CantonX402Reader,
+      limit?: number,
+    ): Promise<CantonX402SettlementRef[]> {
+      // Fail-fast, like propose: a malformed atrHash can never match a decoded memo, and the silent []
+      // it would produce is indistinguishable from "this party has no settlements".
+      if (!isAtrHash(atrHash))
+        throw new Error(
+          `enumerate: atrHash must be a 0x-prefixed 32-byte value, got "${atrHash}"`,
+        );
+      const updateIds = await reader.transfersFor(party, limit);
+      const out: CantonX402SettlementRef[] = [];
+      for (const updateId of updateIds) {
+        const view = await reader.transferView(updateId);
+        const found = view === null ? null : readTransferMemoAtrHash(view.meta);
+        if (found !== null && atrHashEquals(found, atrHash))
+          out.push({ updateId });
+      }
+      return out;
+    },
+  };
+}

package/src/constants.ts

@@ -0,0 +1,65 @@
+/**
+ * Canton / Daml constants for the LCP transfer-memo binding.
+ *
+ * **Canton has a native arbitrary-bytes carrier, and this binding uses it.** x402's `exact` scheme for
+ * Canton defines `PaymentRequirements.extra.memo` — "Seller-defined UTF-8 string, max 256 bytes. When
+ * present, the client MUST include it in the transfer's metadata" — and its facilitator rule 12 rejects
+ * `invalid_exact_canton_memo_mismatch` when the transfer metadata does not carry the identical value under
+ * `x402.memo`. Seller-committed, payer-echoed, facilitator-verified, and riding the same transaction as
+ * the value.
+ *
+ * Daml is often said to have no native arbitrary-bytes carrier — no memo, no metadata label, no nonce. That
+ * is true of the LEDGER's own primitives and false of a payment settled through x402, which is why this
+ * rail exists beside `@integraledger/lcp-binding-canton`'s overlay contract rather than instead of it.
+ */
+
+/**
+ * The transfer-metadata key the facilitator compares against `extra.memo`. The host's, read exactly: a
+ * metadata map carrying our value under a different key is a transfer no facilitator checked.
+ */
+export const CANTON_X402_MEMO_KEY = "x402.memo";
+
+/** The scheme's stated ceiling for `extra.memo`. A canonical atrHash is 66 UTF-8 bytes. */
+export const CANTON_X402_MEMO_MAX_BYTES = 256;
+
+/** The three Canton environments this binding ships constants for. */
+export type CantonX402Network = "sandbox" | "devnet" | "mainnet";
+
+/** Per-network constants. Same shape as the overlay rail's and for the same reason: a Canton participant
+ *  node is a deployment's own, so there is no endpoint to pin here. */
+export interface CantonX402NetworkConfig {
+  network: CantonX402Network;
+  /** Explorer base for a contract link (Daml Sandbox has no public explorer — Navigator stand-in). */
+  explorerBase: string;
+  /** CAIP-2-style identifier — Canton has no canonical namespace yet (informal, like Cardano's). */
+  caip2: string;
+}
+
+const SANDBOX: CantonX402NetworkConfig = {
+  network: "sandbox",
+  explorerBase: "http://localhost:7500",
+  caip2: "canton:sandbox",
+};
+
+const DEVNET: CantonX402NetworkConfig = {
+  network: "devnet",
+  explorerBase: "https://scan.global.dev.sync.global",
+  caip2: "canton:devnet",
+};
+
+const MAINNET: CantonX402NetworkConfig = {
+  network: "mainnet",
+  explorerBase: "https://scan.sync.global",
+  caip2: "canton:mainnet",
+};
+
+/** The constants for one environment. Which Canton rail you want is the real choice: this one only reaches
+ *  payments settled through x402's Canton-Coin scheme, and `@integraledger/lcp-binding-canton`'s overlay
+ *  covers everything else. */
+export function getCantonX402Config(
+  network: CantonX402Network,
+): CantonX402NetworkConfig {
+  if (network === "sandbox") return SANDBOX;
+  if (network === "devnet") return DEVNET;
+  return MAINNET;
+}

package/src/index.ts

@@ -0,0 +1,24 @@
+export {
+  type CantonX402Adapter,
+  type CantonX402Reader,
+  type CantonX402ReaderConfig,
+  type CantonX402Settlement,
+  type CantonX402SettlementRef,
+  type CantonX402TransferView,
+  createCantonX402Adapter,
+  makeCantonX402Reader,
+} from "./adapter.js";
+export {
+  CANTON_X402_MEMO_KEY,
+  CANTON_X402_MEMO_MAX_BYTES,
+  type CantonX402Network,
+  type CantonX402NetworkConfig,
+  getCantonX402Config,
+} from "./constants.js";
+export { CANTON_X402_MANIFEST } from "./manifest.js";
+export {
+  decodeTransferMemo,
+  encodeTransferMemo,
+  readTransferMemoAtrHash,
+  x402MemoRequirement,
+} from "./memo.js";

package/src/manifest.ts

@@ -0,0 +1,82 @@
+import type { BindingManifest } from "@integraledger/lcp-binding-core";
+import { CANTON_X402_MEMO_KEY } from "./constants.js";
+
+/**
+ * The Canton transfer-memo binding manifest.
+ *
+ * **pattern = "native-field"** (canonical LCP §8.3.1). x402's `exact` scheme for Canton defines
+ * `PaymentRequirements.extra.memo` — "Seller-defined UTF-8 string, max 256 bytes. When present, the
+ * client MUST include it in the transfer's metadata" — and its facilitator safety check 12 rejects
+ * `invalid_exact_canton_memo_mismatch` unless the transfer metadata carries the identical value under
+ * `x402.memo`. The atrHash therefore rides a field the host defined, on the transaction that moves the
+ * money.
+ *
+ * **THIS IS A SECOND CANTON RAIL, NOT A REPLACEMENT.** `@integraledger/lcp-binding-canton` binds the same
+ * chain through an `LcpAnchor` overlay contract, and it is not obsolete: x402's exact-Canton scheme
+ * settles **Canton Coin only** ("`asset`: `\"CC\"`. Settles Canton Coin only", instrument fixed to
+ * `Amulet`, via `transfer-factory`, relayed by a facilitator). Every other Canton deployment — any
+ * instrument, any synchronizer, DvP and fund and bond workflows, no facilitator — still has no native
+ * field to ride, and the overlay is the only carrier there.
+ *
+ * Where BOTH apply, this one wins on every axis: the weld rides the SAME transaction as the payment
+ * rather than a separate contract create; it is enforced by the facilitator rather than by nobody; and it
+ * binds the asset rather than declaring `assetBinding: "none"`. That is LCP §8.3's own ordering, and it is
+ * why the overlay's docblock now says it is an overlay by CHOICE rather than by necessity — the claim that
+ * Daml has no native arbitrary-bytes carrier was simply false.
+ *
+ * One chain, two carriers, two bindings, for the same reason EVM has three (`evm:x402`, `evm:escrow`,
+ * `evm:mpp`): a manifest can honestly describe exactly one carrier.
+ *
+ * **protocol = "x402"**, and the declaration is substantive. `extra.memo` is x402's field, its 256-byte
+ * ceiling is x402's ceiling, and the enforcement is an x402 facilitator's. A deployment settling Canton
+ * Coin outside x402 does not get this carrier, and saying so is the point of the axis: an absent
+ * `protocol` is a positive claim of protocol-neutrality, which this binding cannot make.
+ *
+ * **assetBinding = "carried"** — the memo rides a `TransferFactory_Transfer` whose own fields name the
+ * receiver, the amount and the instrument, and `CantonX402TransferView` carries all three to the caller. That
+ * is the axis's actual test: not that the value exists on-chain, but that a consumer can reach it. The
+ * overlay could not, which is why it honestly said `"none"`.
+ *
+ * **recovery.zeroPartyRecoverable = false** — unchanged, and for the unchanged reason. Daml contract and
+ * transaction visibility is limited to stakeholders, so a neutral verifier holding only a settlement
+ * reference sees nothing until the payer, the merchant or the DSO grants access. §8.3 asks whether an
+ * auditor can reconstruct the atrHash from the settlement reference alone WITHOUT trusting either party to
+ * produce records; on Canton they cannot, whichever carrier is used. WLD-3 makes the direction of the
+ * error normative — understating costs nothing, overstating is non-conformance.
+ *
+ * **recovery.forwardIndexable = false** — a participant's update stream is one participant's view, not a
+ * chain-global forward index, and the memo is a metadata value rather than an indexed key. Honest for the
+ * same reason the overlay's participant query was.
+ *
+ * **successGate = "structural"** — a Canton transfer that did not commit produces no update, so there is
+ * no failed view whose memo could be misread as a settlement. The transfer either executed and its
+ * metadata exists, or it did not and nothing does.
+ *
+ * **weldGrades["x402-memo"] = "tx"** — the memo is committed by the payer's signed
+ * `TransferFactory_Transfer`, not by a detached signature over the atrHash bytes. The payer signs the
+ * prepared transaction (which contains the memo), so the commitment rides the transaction. Per LCP §8.3 /
+ * WLD-3 that is tx-grade.
+ *
+ * **finality.reversible = false** — once the transfer executes, its input holdings are consumed and Canton
+ * has no reversal; recourse is the record's elected forum (PAY-3/RCS-5), never dispute resolution.
+ */
+export const CANTON_X402_MANIFEST: BindingManifest = {
+  rail: "canton:x402",
+  pattern: "native-field",
+  protocol: "x402",
+  nativeField: CANTON_X402_MEMO_KEY,
+  recovery: {
+    onChain: true,
+    zeroPartyRecoverable: false,
+    forwardIndexable: false,
+  },
+  assetBinding: "carried",
+  successGate: "structural",
+  indexing: `participant-updates:transfer.meta.${CANTON_X402_MEMO_KEY}`,
+  finality: {
+    reversible: false,
+    note: "a Canton transfer consumes the input holdings it names and Canton has no reversal, so an executed transfer's memo is permanent; recourse is the record's elected forum (PAY-3/RCS-5), never dispute resolution",
+  },
+  weldGrades: { "x402-memo": "tx" },
+  lifecycleStates: ["proposed", "settled"],
+};

package/src/memo.ts

@@ -0,0 +1,80 @@
+/**
+ * The Canton transfer-memo atrHash codec — PURE, no Daml SDK, no HTTP.
+ *
+ * **THE CARRIER.** x402's `exact` scheme for Canton defines `PaymentRequirements.extra.memo`:
+ *
+ * > `extra.memo` (optional): Seller-defined UTF-8 string, max 256 bytes. When present, the client MUST
+ * > include it in the transfer's metadata.
+ *
+ * and makes it facilitator-enforced (scheme §Safety Checks, rule 12):
+ *
+ * > **Memo.** If `paymentRequirements.extra.memo` is set, the transfer metadata MUST carry the identical
+ * > value under `x402.memo`. Reject with `invalid_exact_canton_memo_mismatch`.
+ *
+ * So the SELLER names the value, the PAYER must echo it into the transfer that moves the money, and a
+ * THIRD PARTY refuses to relay the payment if they disagree. That is a §8.3.1 Native Field with an
+ * unusually strong commitment story, and it rides the same transaction as the value — which is what the
+ * overlay it replaces could never do.
+ *
+ * **WHY THIS CARRIER AND NOT AN OVERLAY CONTRACT.** Canton's other binding,
+ * `@integraledger/lcp-binding-canton`, welds through a custom `LcpAnchor` Daml template. Where this scheme
+ * applies, the memo is stronger on every axis: it rides the SAME transaction as the payment rather than a
+ * separate contract create, the facilitator checks it before relaying, and the transfer's own fields name
+ * the asset. LCP §8.3's ordering puts Overlay Contract below Native Field for exactly these reasons. The
+ * overlay covers what this scheme cannot reach — it settles Canton Coin only.
+ *
+ * **THE 256-BYTE CEILING NEEDS NO RUNTIME CHECK.** A canonical atrHash is exactly 66 UTF-8 bytes and the
+ * host allows 256, so a length guard here could never fire — it would be an unreachable branch asserting
+ * a fact the type of the input already settles. `CANTON_X402_MEMO_MAX_BYTES` records the host's limit and
+ * `constants.test.ts` proves an atrHash fits inside it; that is where a fact about the host belongs.
+ *
+ * `encodeTransferMemo` fails LOUD on a malformed atrHash (never advertise a memo we could not later
+ * verify); `decodeTransferMemo` returns `null` for anything that is not one, so a scan over a party's
+ * transfers can skip foreign memos without treating them as errors.
+ */
+import { canonicalAtrHash, isAtrHash } from "@integraledger/lcp-kernel";
+import { CANTON_X402_MEMO_KEY } from "./constants.js";
+
+/**
+ * The `extra` fragment a Canton seller merges into its x402 `PaymentRequirements`.
+ *
+ * Returned as an object rather than a bare string so the call site reads as what it is — the seller
+ * ADVERTISING a value it is committing to — and so a future scheme field can join it without changing
+ * every caller. Mirrors `binding-tempo-mpp`'s `mppMethodDetailsMemo`.
+ */
+export function x402MemoRequirement(atrHash: string): {
+  readonly memo: string;
+} {
+  return { memo: encodeTransferMemo(atrHash) };
+}
+
+/**
+ * The memo string carrying `atrHash`: the canonical `0x`-prefixed lowercase form, verbatim.
+ *
+ * No bare-hex variant is emitted or accepted. The host calls this a "seller-defined UTF-8 string" and
+ * compares it byte-for-byte against the transfer metadata, so any second spelling would be a second wire
+ * value that a facilitator would reject against the first.
+ */
+export function encodeTransferMemo(atrHash: string): string {
+  return canonicalAtrHash(atrHash, "encodeTransferMemo");
+}
+
+/** Decode a memo string back to an atrHash, or `null` if it is not a well-formed one. */
+export function decodeTransferMemo(memo: string): `0x${string}` | null {
+  return isAtrHash(memo) ? canonicalAtrHash(memo, "decodeTransferMemo") : null;
+}
+
+/**
+ * Read the atrHash out of a transfer's on-ledger metadata map, or `null` if it carries none.
+ *
+ * The key is the host's — `x402.memo`, quoted in rule 12 above — and it is read EXACTLY. A metadata map
+ * carrying our value under some other key is a transfer that no facilitator checked, so treating it as a
+ * weld would assert a commitment nobody made.
+ */
+export function readTransferMemoAtrHash(
+  meta: Readonly<Record<string, string>> | undefined,
+): `0x${string}` | null {
+  // `?? ""` rather than an `undefined` branch: an absent key and a foreign memo are the same answer, and
+  // "" is not a well-formed atrHash, so the decoder already gives it.
+  return decodeTransferMemo(meta?.[CANTON_X402_MEMO_KEY] ?? "");
+}