@meantjs/consent 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 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.3.0 — 2026-10-29
+
+- `@meantjs/consent/evm`: `eip712Consent`, the consent text of an EIP-712 signing request (spec §15.9, D-055),
+  matched to a message of the resolved form by its type hash and refused before anything is shown when its domain,
+  contract, type hash or values do not match (new codes `E_DOMAIN` and `E_TYPE_HASH`). The text ends with the
+  verifying contract, the EIP-712 digest and the note that a signature is not a transaction. `evmConsent` and
+  `eip712Consent` take `tokens`, the decimals and symbol of each token an amount's `token` field names; the token's
+  address is shown beside its symbol.
+- `@meantjs/consent/erc7730`: `erc7730Descriptor(resolved, { context: "eip712" })` writes the ERC-7730 file of the
+  messages (formats keyed by `encode_type`, field groups for arrays of tokens). It returns `notes`: a timestamp's
+  words and a template ERC-7730 cannot interpolate are left out with a note instead of refusing the file, for
+  functions as well. Every file 0.2.0 writes is written the same.
+- ICRC-21 fields: an amount at or above its threshold, and a timestamp shown as words, are `Text`, never a
+  `TokenAmount` or `TimestampSeconds` of the raw number.
+
 ## 0.2.0 — 2026-10-28
 
 - A call takes the `intent` and `effect` of the deepest tagged variant case its arguments hold, else the method's

package/README.md

@@ -63,26 +63,31 @@ bundles it with esbuild for the browser platform). The three SNS rows below are
 
 ## EVM contracts (experimental: `src/evm.mjs`, `src/erc7730.mjs`)
 
-Spec section 15, D-054. An EVM contract's resolved form (`"chain": "evm"`, from `resolveService({ abi })` of
+Spec section 15, D-054 and D-055 (EIP-712 messages, §15.9). An EVM contract's resolved form (`"chain": "evm"`, from `resolveService({ abi })` of
 `@meantjs/profile`) is read by two subpaths; the main entry refuses it with `E_RESOLVED_FORM`, and `evmConsent` refuses
 a Candid one.
 
 | Function | Does |
 |---|---|
 | `decodeCalldata(resolved, calldata, limits)` (`/evm`) | The function a selector names and its arguments, keyed by parameter name. Strict: values read from anything but their canonical ABI encoding are `E_DECODE`. |
-| `evmConsent({ resolved, calldata, to, chainId, refs, form, utcOffsetMinutes, rawArguments, limits })` (`/evm`) | The consent text of a call: the same model and the same two forms as ICRC-21, without its envelope (`"generic"` Markdown, or `"fields"` as an intent line and `[label, text]` rows), ending with the contract's address and chain, which a person must see because a pack matches any contract with the right functions. A call to a contract its profiles do not list is `E_DEPLOYMENT`; a payable function is `E_UNSUPPORTED_TYPE` (its native value has no position yet). |
-| `erc7730Descriptor(resolved, { deployments, owner, contractName, info, token })` (`/erc7730`) | The contract's ERC-7730 clear-signing file and its ERC-8176 `descriptorHash`: deterministic, `$schema` pinned to the exact 2.1.0 file, one entry per function a transaction calls. What an ERC-7730 file cannot say (a time in ms, `utf8` bytes, an amount in another token, an unnamed parameter, a placeholder over an array) is `E_EXPORT`, never written as something near it; no deployment is `E_DEPLOYMENT`. The mapping is the table in spec §15.7. |
+| `evmConsent({ resolved, calldata, to, chainId, refs, tokens, form, utcOffsetMinutes, rawArguments, limits })` (`/evm`) | The consent text of a call: the same model and the same two forms as ICRC-21, without its envelope (`"generic"` Markdown, or `"fields"` as an intent line and `[label, text]` rows), ending with the contract's address and chain, which a person must see because a pack matches any contract with the right functions. A call to a contract its profiles do not list is `E_DEPLOYMENT`; a payable function is `E_UNSUPPORTED_TYPE` (its native value has no position yet). `tokens`: the decimals and symbol of each token an amount's `token` field names, by address; the address is shown beside the symbol. |
+| `eip712Consent({ resolved, typedData, chainId, refs, tokens, form, utcOffsetMinutes, rawArguments, limits })` (`/evm`) | The consent text of an EIP-712 signing request (`eth_signTypedData_v4`'s JSON), matched to a message of the resolved form by its type hash, never its name. Refused before anything is shown: a domain for another chain than the wallet's, without `chainId` or `verifyingContract`, with a salt, or whose name or version is not its profiles' (`E_DOMAIN`); a contract its profiles do not list (`E_DEPLOYMENT`); no message with the type hash (`E_TYPE_HASH`); values that are not exactly the members, canonically written (`E_DECODE`); a token not in `tokens` (`E_REF_UNRESOLVED`). Ends with the verifying contract, the EIP-712 digest and "This is a signature, not a transaction: whoever holds it can submit it." Returns `typeHash`, `digest`, `verifyingContract` and `chainId` with the text. |
+| `erc7730Descriptor(resolved, { context, deployments, owner, contractName, info, token })` (`/erc7730`) | The contract's ERC-7730 clear-signing file and its ERC-8176 `descriptorHash`: deterministic, `$schema` pinned to the exact 2.1.0 file, one entry per function a transaction calls, or with `context: "eip712"` one per message, keyed by its `encodeType`. What an ERC-7730 file cannot say (a time in ms, `utf8` bytes, an amount in another token, an unnamed parameter) is `E_EXPORT`, never written as something near it; no deployment is `E_DEPLOYMENT`. What it cannot say but changes no value (a timestamp's "Never", a template over an array) is left out and listed in `notes`. The mapping is spec §15.7 and §15.9. |
 | `descriptorHash(descriptor)` (`/erc7730`) | Keccak-256 of the RFC 8785 form: the hash of a file someone edited. |
 | `erc8176Attestation({ descriptorHash, time, expirationTime, salt, refUID })` (`/erc7730`) | The unsigned ERC-8176 attestation (EAS offchain v2 typed data) and its EIP-712 digest, for a reviewer to sign with their own key. Nothing is signed or sent. |
 
 ```js
-import { evmConsent } from "@meantjs/consent/evm";
+import { eip712Consent, evmConsent } from "@meantjs/consent/evm";
 import { erc7730Descriptor, erc8176Attestation } from "@meantjs/consent/erc7730";
 
 evmConsent({ resolved, calldata, to: "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2", refs: { "query:decimals": 18, "query:symbol": "WETH" } }).message;
 // # Send tokens\n\nSend `1.5 WETH` to `0xfB69…d359`\n\n- **Amount:** `1.5 WETH`\n- **Recipient:** `0xfB69…d359`\n\n**Contract:** `0xC02a…6Cc2`
 const { descriptor, descriptorHash } = erc7730Descriptor(resolved, { deployments: [{ chainId: 1, address: "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2" }] });
 const { typedData, digest } = erc8176Attestation({ descriptorHash, time: 1777630591, expirationTime: 1785406591, salt });
+
+// A Permit2 signing request, with the profile in @meantjs/profile/packs/permit2.profile.json
+eip712Consent({ resolved: permit2, typedData, chainId: 1, tokens: { "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48": { decimals: 6, symbol: "USDC" } } }).message;
+// # Permit2: allow token spending\n\nLet `0x66a9…A8Af` spend up to `Unlimited USDC (0xA0b8…eB48)`. Allowance expires: …
 ```
 
 Every exported file in the tests is checked against the ERC-7730 2.1.0 JSON Schema (vendored in
@@ -243,5 +248,6 @@ Untrusted third-party data lives in `test/upstream/icrc21/` (the standard, commi
 - The caller's account (`From`) and a fee line: see `docs/oisy-comparison.md` for why they are absent.
 - Other languages; `device_spec` hints beyond the two forms.
 - Recursive and `func`/`service` positions (need a richer resolved form, or the Contract).
-- EVM: payable functions in the consent text, EIP-712 messages, ERC-7730 import, checking attestations, and the Rust
+- EVM: payable functions in the consent text, EIP-712 witness messages and the signer check (spec §15.9 O9, O13),
+  ERC-7730 import, checking attestations, and the Rust
   version.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meantjs/consent",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "ICRC-21 consent messages and SNS proposal validator renderings generated from a Candid Profile resolved form: any method, both GenericDisplayMessage and FieldsDisplayMessage, values formatted and escaped, nothing rounded.",
   "license": "Apache-2.0",
   "repository": {
@@ -64,8 +64,8 @@
   },
   "dependencies": {
     "@candid-core/schema": "0.5.0",
-    "@meantjs/format": "0.2.0",
-    "@meantjs/profile": "0.2.0"
+    "@meantjs/format": "0.3.0",
+    "@meantjs/profile": "0.3.0"
   },
   "devDependencies": {
     "@dfinity/didc": "0.0.4",

package/src/display.mjs

@@ -20,6 +20,23 @@ const CONFIG_CODES = new Set(["E_REF_UNRESOLVED", "E_ARG", "E_TAG_TYPE", "E_TAG_
 /** Budget for the text of one message: a consent message is read by a person (ICRC-21: short and concise). */
 export const MAX_MESSAGE_CHARS = 32 * 1024;
 
+/**
+ * An amount in the token a field of the same value names (spec section 15.9): the base units, the token's EIP-55
+ * address, and its decimals and symbol as the caller supplied them. evm.mjs puts one in place of each such amount of a
+ * decoded value; its text is the base units, so a view without formatters shows those.
+ */
+export class TokenAmount {
+  constructor(value, token, metadata) {
+    this.value = value;
+    this.token = token;
+    this.metadata = metadata;
+    Object.freeze(this);
+  }
+  toString() {
+    return this.value;
+  }
+}
+
 export class Renderer {
   /** Set while `plainTupleText` runs: no formatter applies. */
   #plain = false;
@@ -39,17 +56,24 @@ export class Renderer {
     this.usedZone = false;
   }
 
-  /** @returns {import("@meantjs/format").Formatter | null} */
-  formatter(node) {
-    if (this.formatters.has(node)) return this.formatters.get(node);
+  /**
+   * @param {object} node
+   * @param {TokenAmount} [amount]  a value whose token a field names: the formatter takes that token's metadata
+   * @returns {import("@meantjs/format").Formatter | null}
+   */
+  formatter(node, amount) {
+    const key = amount === undefined ? "" : amount.token;
+    if (!this.formatters.has(node)) this.formatters.set(node, new Map());
+    const cache = this.formatters.get(node);
+    if (cache.has(key)) return cache.get(key);
     let f;
     try {
-      f = formatterFor(node, { refs: this.refs });
+      f = formatterFor(node, { refs: this.refs, token: amount?.metadata });
     } catch (e) {
       if (e instanceof FormatError && CONFIG_CODES.has(e.code)) throw new ConsentError(e.code, e.message, { cause: e });
       throw e;
     }
-    this.formatters.set(node, f);
+    cache.set(key, f);
     return f;
   }
 
@@ -98,10 +122,21 @@ export class Renderer {
   /** The formatter's text, or null when the position has no value tag or the formatter refuses the value. */
   #formatted(node, value, where) {
     if (this.#plain) return null;
+    if (value instanceof TokenAmount) {
+      // The token's own symbol is its claim, so its address is always shown beside it (spec section 15.9).
+      const f = this.formatter(node, value);
+      try {
+        return `${f.display(value.value)} (${value.token})`;
+      } catch (e) {
+        if (!(e instanceof FormatError)) throw e;
+        this.diagnostics.push({ code: "W_FORMAT_FALLBACK", at: where, message: `the ${f.tag} formatter refused the value (${e.code}: ${e.message}); it is shown in base units` });
+        return `${value.value} (${value.token})`;
+      }
+    }
     const f = this.formatter(node);
     if (f === null) return null;
     try {
-      return f.tag === "timestamp" && this.utcOffsetMinutes !== null ? this.#zoned(f, value) : f.display(value);
+      return f.tag === "timestamp" && this.utcOffsetMinutes !== null && !this.#worded(f, value) ? this.#zoned(f, value) : f.display(value);
     } catch (e) {
       if (!(e instanceof FormatError)) throw e;
       this.diagnostics.push({ code: "W_FORMAT_FALLBACK", at: where, message: `the ${f.tag} formatter refused the value (${e.code}: ${e.message}); it is shown as raw Candid text` });
@@ -109,6 +144,13 @@ export class Renderer {
     }
   }
 
+  /** Whether a timestamp shows words instead of a time: a label for its value, or its threshold's message (spec section 15.9). */
+  #worded(f, value) {
+    if (typeof value !== "bigint" && !(typeof value === "string" && /^-?[0-9]+$/.test(value))) return false; // the formatter refuses it anyway
+    const v = BigInt(value);
+    return (f.args.labels !== undefined && Object.hasOwn(f.args.labels, v.toString())) || (f.args.threshold !== undefined && v >= BigInt(f.args.threshold));
+  }
+
   /** A timestamp in the requested zone: the instant shifted by whole minutes, then shown with the library's calendar code. */
   #zoned(f, value) {
     const offset = this.utcOffsetMinutes;
@@ -205,12 +247,14 @@ export class Renderer {
     try {
       if (f.tag === "amount") {
         const amount = BigInt(value);
-        const { decimals, symbol } = f.args;
+        const { decimals, symbol, threshold } = f.args;
         if (amount < 0n || amount > U64_MAX || typeof symbol !== "string") return null;
+        if (threshold !== undefined && amount >= BigInt(threshold)) return null; // shown as its message ("Unlimited ICP"), not a number
         f.display(value); // the library must accept the value too (type range), or it is shown as raw text
         return { TokenAmount: { decimals, amount, symbol } };
       }
       if (f.tag === "timestamp" || f.tag === "duration") {
+        if (f.tag === "timestamp" && this.#worded(f, value)) return null; // shown as its words ("Never"), not a time
         const seconds = BigInt(convertUnit(value, f.args.unit, "s")); // throws E_INEXACT when not whole seconds
         if (seconds < 0n || seconds > U64_MAX) return null;
         f.display(value);

package/src/erc7730.d.mts

@@ -19,20 +19,30 @@ export interface Erc7730Field {
   path: string;
   label: string;
   format: "tokenAmount" | "amount" | "date" | "duration" | "addressName" | "raw";
+  /** `tokenPath`: `@.to` (the contract, or a message's verifying contract) or a path to the token's address field. */
   params?: Record<string, unknown>;
 }
+/** The fields of each element of an array whose elements carry their own token (`path: "details.[]"`); paths relative. */
+export interface Erc7730FieldGroup {
+  path: string;
+  fields: (Erc7730Field | Erc7730FieldGroup)[];
+}
 export interface Erc7730Descriptor {
   $schema: typeof ERC7730_SCHEMA_URL;
-  context: { contract: { deployments: Erc7730Deployment[] } };
+  /** `contract` for a file of functions; `eip712` for a file of messages, with the domain name and version its profiles give. */
+  context: { contract: { deployments: Erc7730Deployment[] } } | { eip712: { domain?: { name?: string; version?: string }; deployments: Erc7730Deployment[] } };
   metadata?: {
     owner?: string;
     contractName?: string;
     info?: { url: string; deploymentDate?: string };
     token?: { name: string; ticker: string; decimals: number };
   };
-  display: { formats: Record<string, { intent: string; interpolatedIntent?: string; fields?: Erc7730Field[] }> };
+  /** Keyed by named signature (functions) or by encodeType (messages). */
+  display: { formats: Record<string, { intent: string; interpolatedIntent?: string; fields?: (Erc7730Field | Erc7730FieldGroup)[] }> };
 }
 export interface Erc7730Options {
+  /** "contract" (default): the functions a transaction calls. "eip712": the EIP-712 messages (spec section 15.9). */
+  context?: "contract" | "eip712";
   /** Default: the deployments every profile that lists deployments lists. Given, each must be listed by those profiles. */
   deployments?: Erc7730Deployment[];
   owner?: string;
@@ -43,9 +53,10 @@ export interface Erc7730Options {
 }
 /**
  * The ERC-7730 file of an EVM contract's resolved form and its ERC-8176 `descriptorHash`. What the profile says that an
- * ERC-7730 file cannot say is refused (E_EXPORT); no deployments is E_DEPLOYMENT.
+ * ERC-7730 file cannot say is refused (E_EXPORT); no deployments is E_DEPLOYMENT. What it cannot say but changes no
+ * value (a timestamp's words, an interpolation of an array) is left out and listed in `notes`.
  */
-export function erc7730Descriptor(resolved: ResolvedForm, options?: Erc7730Options): { descriptor: Erc7730Descriptor; descriptorHash: string };
+export function erc7730Descriptor(resolved: ResolvedForm, options?: Erc7730Options): { descriptor: Erc7730Descriptor; descriptorHash: string; notes: string[] };
 /** ERC-8176 `descriptorHash`: `0x` and the Keccak-256 of the RFC 8785 (JCS) form, for a descriptor without `includes`. */
 export function descriptorHash(descriptor: object): string;
 

package/src/erc7730.mjs

@@ -19,6 +19,17 @@
 // The descriptor binds to deployments (ERC-7730 `context.contract.deployments`): the profile's, or the caller's when
 // every profile that lists deployments lists them too. `effect`, `idempotency`, `outcome` and the other agent tags
 // have no ERC-7730 form and are left out: the file carries what a call says, not what it does.
+//
+// EIP-712 messages (spec section 15.9) are a file of their own (`options.context: "eip712"`): ERC-7730 binds a file to
+// a contract or to messages, not both. Its formats are keyed by each message's `encode_type`, whose Keccak-256 must be
+// the message's `type_hash`; `context.eip712` carries the deployments and the domain name and version the profiles
+// give. An amount whose token a field names is `tokenAmount` with that field's path, inside a field group of the array
+// the two share, as ERC-7730's PermitBatch example writes it.
+//
+// Some words a profile adds have no ERC-7730 form but change no value: a timestamp's `threshold`, `message` and
+// `labels` (written as a plain date), and an intent template ERC-7730 cannot interpolate (an array, a whole tuple, a
+// [ ] segment; `interpolatedIntent` is optional and a wallet falls back to `intent`). They are left out, and each is
+// returned as a note, instead of refusing the file.
 
 import { AbiError, jcs, keccak256Hex, parseSignature, readAddress, typedDataDigest } from "@meantjs/profile/evm";
 import { CODES, fail } from "./errors.mjs";
@@ -35,7 +46,7 @@ export const EAS_ADDRESS = "0xA1207F3BBa224E2c9c3c6D5aF63D0eb1582Ce587";
 
 const ZERO32 = `0x${"0".repeat(64)}`;
 const ZERO_ADDRESS = `0x${"0".repeat(40)}`;
-const OPTIONS = new Set(["deployments", "owner", "contractName", "info", "token"]);
+const OPTIONS = new Set(["context", "deployments", "owner", "contractName", "info", "token"]);
 const isObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
 const nonEmpty = (v) => typeof v === "string" && v.trim() !== "";
 
@@ -91,10 +102,32 @@ function erc20Metadata(resolved) {
   return isObject(d) && isObject(s) && d.mode === "query" && s.mode === "query" && d.signature === "decimals()" && s.signature === "symbol()" && /^uint\d+$/.test(d.results?.[0]?.abi ?? "") && s.results?.[0]?.abi === "string" && d.results.length === 1 && s.results.length === 1;
 }
 
-/** One ERC-7730 field for a leaf of a function's parameters. */
-function fieldOf(node, path, label, ctx, where) {
+/** The keys of a placeholder or token path through a viewed tree (`["details", "[]", "token"]`), or null. */
+function keysOf(method, relpath) {
+  const rp = resolvePath(method, relpath);
+  return rp.error ? null : rp.steps.map((st) => (st.kind === "elem" ? "[]" : st.key));
+}
+const startsWith = (keys, prefix) => prefix.length <= keys.length && prefix.every((k, i) => keys[i] === k);
+
+/**
+ * One ERC-7730 field for a leaf of a function's parameters or a message's members. `at` is where the leaf is:
+ * `{ method, abs, base }`, its keys from the root and the keys of the field group it is in (its path is relative to it).
+ */
+function fieldOf(node, path, label, ctx, where, at) {
   const field = { path, label };
   const amount = tagArgs(node, "amount");
+  if (amount?.token !== undefined) {
+    // In the token a field of the same value names (spec section 15.9): its path, relative to the group.
+    const keys = keysOf(at.method, String(amount.token));
+    if (keys === null) return ctx.problem(where, `amount.token ${JSON.stringify(amount.token)} does not resolve`);
+    if (!startsWith(keys, at.base)) return ctx.problem(where, "the amount is in an array group and its token is outside it; this export writes no path that leaves a group");
+    const params = { tokenPath: keys.slice(at.base.length).join(".") };
+    if (amount.threshold !== undefined) {
+      params.threshold = `0x${BigInt(amount.threshold).toString(16)}`;
+      params.message = amount.message ?? "Unlimited";
+    }
+    return { ...field, format: "tokenAmount", params };
+  }
   if (amount !== undefined) {
     const dynamic = amount.decimals?.from === "query:decimals" && amount.symbol?.from === "query:symbol";
     const literal = Number.isInteger(amount.decimals) && typeof amount.symbol === "string";
@@ -120,6 +153,8 @@ function fieldOf(node, path, label, ctx, where) {
   if (time !== undefined) {
     const kind = tagArgs(node, "timestamp") !== undefined ? "timestamp" : "duration";
     if (time.unit !== "s") return ctx.problem(where, `${kind} in ${time.unit}: ERC-7730 ${kind === "timestamp" ? "dates" : "durations"} are in seconds`);
+    const words = ["threshold", "labels"].filter((k) => time[k] !== undefined);
+    if (kind === "timestamp" && words.length) ctx.note(where, `the timestamp's ${words.join(" and ")} ha${words.length > 1 ? "ve" : "s"} no ERC-7730 date form and ${words.length > 1 ? "are" : "is"} left out; the file shows the date`);
     return kind === "timestamp" ? { ...field, format: "date", params: { encoding: "timestamp" } } : { ...field, format: "duration" };
   }
   const bytes = tagArgs(node, "bytes");
@@ -127,12 +162,30 @@ function fieldOf(node, path, label, ctx, where) {
   return { ...field, format: node.abi === "address" ? "addressName" : "raw" };
 }
 
-/** Every leaf of a viewed parameter tree, depth first in ABI order: its ERC-7730 path and its label. */
-function leaves(node, keys, out) {
-  if (node.candid === "record") for (const [k, child] of entriesOf(node.fields)) leaves(child, [...keys, k], out);
-  else if (node.candid === "vec") leaves(node.element, [...keys, "[]"], out);
-  else out.push({ node, path: keys.join("."), label: labelOf(node) ?? [...keys].reverse().find((k) => k !== "[]") });
-  return out;
+/** Whether a subtree holds an amount whose token path starts with `prefix` (it is in the same array element). */
+function tokenInside(node, method, prefix) {
+  if (node.candid === "record") return entriesOf(node.fields).some(([, child]) => tokenInside(child, method, prefix));
+  if (node.candid === "vec") return tokenInside(node.element, method, prefix);
+  const token = tagArgs(node, "amount")?.token;
+  const keys = token === undefined ? null : keysOf(method, String(token));
+  return keys !== null && startsWith(keys, prefix);
+}
+
+/**
+ * The ERC-7730 fields of a viewed parameter tree, depth first in ABI order. An array whose elements hold an amount
+ * whose token is in the same element is a field group (`{ path: "details.[]", fields }`), its paths relative to the
+ * element, as ERC-7730's PermitBatch example writes it; any other array is flattened (`legs.[].to`).
+ */
+function fieldsOf(node, abs, rel, ctx, method, name) {
+  if (node.candid === "record") return entriesOf(node.fields).flatMap(([k, child]) => fieldsOf(child, [...abs, k], [...rel, k], ctx, method, name));
+  if (node.candid === "vec") {
+    const element = [...abs, "[]"];
+    if (tokenInside(node.element, method, element)) return [{ path: [...rel, "[]"].join("."), fields: fieldsOf(node.element, element, [], ctx, method, name) }];
+    return fieldsOf(node.element, element, [...rel, "[]"], ctx, method, name);
+  }
+  const label = labelOf(node) ?? [...abs].reverse().find((k) => k !== "[]");
+  const where = `${name}(0).${abs.join(".").replaceAll(".[]", "[]")}`;
+  return [fieldOf(node, rel.join("."), label, ctx, where, { method, abs, base: abs.slice(0, abs.length - rel.length) })];
 }
 
 /** A parameter or tuple component without a name: an ERC-7730 key names every one, and paths need the names. */
@@ -150,23 +203,28 @@ function unnamed(params, at = "") {
   return null;
 }
 
-/** The template as an ERC-7730 interpolatedIntent: `{(0).to}` reads `{to}`, `[[` and `]]` are plain brackets. */
+/**
+ * The template as an ERC-7730 interpolatedIntent: `{(0).to}` reads `{to}`, `[[` and `]]` are plain brackets. A
+ * template ERC-7730 cannot interpolate gets none, and a note: `interpolatedIntent` is optional, and `intent` and the
+ * fields still say everything.
+ */
 function interpolated(template, method, ctx, where) {
+  const leftOut = (why) => ctx.note(where, `${why}; interpolatedIntent is left out`);
   let parts;
   try {
     parts = parseTemplate(template);
   } catch (e) {
-    return ctx.problem(where, e.message);
+    return leftOut(e.message);
   }
   let out = "";
   for (const p of parts) {
     if (p.t === "lit") out += p.text.replaceAll("{", "{{").replaceAll("}", "}}");
-    else if (p.t === "opt") return ctx.problem(where, "an optional [ ] segment has no ERC-7730 form");
+    else if (p.t === "opt") return leftOut("an optional [ ] segment has no ERC-7730 form");
     else {
       const rp = resolvePath(method, p.path);
       if (rp.error) return ctx.problem(where, `{${p.path}}: ${rp.error}`);
-      if (rp.steps.some((s) => s.kind === "elem")) return ctx.problem(where, `{${p.path}} reads every element of an array; an ERC-7730 interpolation shows one value`);
-      if (rp.node.candid === "record" || rp.node.candid === "vec") return ctx.problem(where, `{${p.path}} is a whole ${rp.node.abi}; an ERC-7730 interpolation shows one formatted field`);
+      if (rp.steps.some((s) => s.kind === "elem")) return leftOut(`{${p.path}} reads every element of an array; an ERC-7730 interpolation shows one value`);
+      if (rp.node.candid === "record" || rp.node.candid === "vec") return leftOut(`{${p.path}} is a whole ${rp.node.abi}; an ERC-7730 interpolation shows one formatted field`);
       out += `{${rp.steps.map((s) => s.key).join(".")}}`;
     }
   }
@@ -180,29 +238,20 @@ function checkText(v, where) {
   else if (isObject(v)) for (const [k, x] of Object.entries(v)) checkText(k, where), checkText(x, `${where}.${k}`);
 }
 
-/**
- * The ERC-7730 file of an EVM contract's resolved form, and its ERC-8176 `descriptorHash`.
- *
- * @param {object} resolved  an EVM contract's resolved form (`chain: "evm"`)
- * @param {object} [options]
- * @param {{ chainId: number, address: string }[]} [options.deployments]  default: the deployments every profile lists
- * @param {string} [options.owner]  ERC-7730 `metadata.owner`
- * @param {string} [options.contractName]  `metadata.contractName`
- * @param {{ url: string, deploymentDate?: string }} [options.info]  `metadata.info`
- * @param {{ name: string }} [options.token]  the contract is the token its literal amounts are in: `metadata.token`
- * @returns {{ descriptor: object, descriptorHash: string }}
- */
-export function erc7730Descriptor(resolved, options = {}) {
-  if (!isObject(resolved) || resolved.format !== "candid-profile-resolved" || !isObject(resolved.methods) || resolved.chain !== "evm") methodOf(resolved, "", "evm"); // throws the right error
-  if (!isObject(options)) fail(CODES.REQUEST, "options must be an object");
-  for (const k of Object.keys(options)) if (!OPTIONS.has(k)) fail(CODES.REQUEST, `unknown option ${JSON.stringify(k)}; expected one of ${[...OPTIONS].join(", ")}`);
-  if (options.token !== undefined && !(isObject(options.token) && nonEmpty(options.token.name) && Object.keys(options.token).length === 1)) fail(CODES.REQUEST, "options.token must be { name } with a non-empty string");
-
-  const problems = [];
-  const ctx = { erc20: erc20Metadata(resolved), tokenName: options.token?.name, token: null, dynamic: false, problem: (at, message) => void problems.push(`${at}: ${message}`) };
-  const deployments = deploymentsOf(resolved, options.deployments);
-  const metadata = metadataOf(options);
+/** One ERC-7730 format entry: the intent's title (else `describe.label`, else `fallback`), its template, the fields. */
+function entryOf(name, method, viewed, fallback, ctx) {
+  const intent = method.tags?.intent?.args;
+  const entry = { intent: nonEmpty(intent?.title) ? intent.title : (labelOf(method) ?? fallback) };
+  if (typeof intent?.template === "string") {
+    const text = interpolated(intent.template, viewed, ctx, `${name}: intent template`);
+    if (text !== undefined) entry.interpolatedIntent = text;
+  }
+  const fields = viewed.args.length ? fieldsOf(viewed.args[0], [], [], ctx, viewed, name) : [];
+  return { entry, fields };
+}
 
+/** The formats of every function a transaction calls, keyed by its named signature. */
+function functionFormats(resolved, ctx) {
   const formats = {};
   for (const [name, m] of entriesOf(resolved.methods)) {
     if (!isObject(m) || m.mode !== "update") continue;
@@ -221,26 +270,92 @@ export function erc7730Descriptor(resolved, options = {}) {
       continue;
     }
     const viewed = { ...method, args: method.args.map((n, i) => abiView(n, `${name}(${i})`)) };
-    const intent = method.tags?.intent?.args;
-    const entry = { intent: nonEmpty(intent?.title) ? intent.title : (labelOf(method) ?? `Call ${name}`) };
-    if (typeof intent?.template === "string") {
-      const text = interpolated(intent.template, viewed, ctx, `${name}: intent template`);
-      if (text !== undefined) entry.interpolatedIntent = text;
-    }
-    const fields = viewed.args.length ? leaves(viewed.args[0], [], []).map((l) => fieldOf(l.node, l.path, l.label, ctx, `${name}(0).${l.path.replaceAll(".[]", "[]")}`)) : [];
+    const { entry, fields } = entryOf(name, method, viewed, `Call ${name}`, ctx);
     if (method.state_mutability === "payable") fields.push({ path: "@.value", label: "Value sent", format: "amount" });
     if (fields.length) entry.fields = fields;
     formats[method.signature] = entry;
   }
+  if (Object.keys(formats).length === 0) ctx.problem("functions", "the contract has no function a transaction calls (every function is view or pure)");
+  return formats;
+}
+
+/** The formats of every EIP-712 message (spec section 15.9), keyed by its encode_type, which must hash to its type_hash. */
+function messageFormats(resolved, ctx) {
+  const formats = {};
+  for (const [name, m] of entriesOf(resolved.messages)) {
+    if (!isObject(m) || typeof m.encode_type !== "string" || !m.encode_type.startsWith(`${name}(`) || `0x${keccak256Hex(m.encode_type)}` !== m.type_hash) {
+      fail(CODES.RESOLVED_FORM, `messages.${name}: its encode_type does not hash to its type_hash, or names another type`);
+    }
+    if (!Array.isArray(m.args) || m.args.length !== 1) fail(CODES.RESOLVED_FORM, `messages.${name} has no args array of one struct`);
+    const viewed = { ...m, args: m.args.map((n, i) => abiView(n, `${name}(${i})`)) };
+    const { entry, fields } = entryOf(name, m, viewed, `Sign ${name}`, ctx);
+    if (fields.length) entry.fields = fields;
+    formats[m.encode_type] = entry;
+  }
+  if (Object.keys(formats).length === 0) ctx.problem("messages", "the resolved form describes no EIP-712 message");
+  return formats;
+}
+
+/** ERC-7730 `context.eip712.domain`: the name and version every profile that gives one gives. */
+function domainOf(resolved, ctx) {
+  const domain = {};
+  for (const p of Array.isArray(resolved.profiles) ? resolved.profiles : []) {
+    if (!isObject(p?.eip712_domain)) continue;
+    for (const [k, v] of Object.entries(p.eip712_domain)) {
+      if ((k !== "name" && k !== "version") || typeof v !== "string") fail(CODES.RESOLVED_FORM, `profile ${p.name}: eip712_domain has ${JSON.stringify(k)}; only a name and a version are bound by a profile`);
+      if (Object.hasOwn(domain, k) && domain[k] !== v) ctx.problem("domain", `profiles give the domain two ${k}s, ${JSON.stringify(domain[k])} and ${JSON.stringify(v)}`);
+      domain[k] = v;
+    }
+  }
+  return domain;
+}
+
+/**
+ * The ERC-7730 file of an EVM contract's resolved form, and its ERC-8176 `descriptorHash`.
+ *
+ * @param {object} resolved  an EVM contract's resolved form (`chain: "evm"`)
+ * @param {object} [options]
+ * @param {"contract" | "eip712"} [options.context]  the functions a transaction calls (default), or the EIP-712
+ *   messages (spec section 15.9): ERC-7730 binds one file to one of the two
+ * @param {{ chainId: number, address: string }[]} [options.deployments]  default: the deployments every profile lists
+ * @param {string} [options.owner]  ERC-7730 `metadata.owner`
+ * @param {string} [options.contractName]  `metadata.contractName`
+ * @param {{ url: string, deploymentDate?: string }} [options.info]  `metadata.info`
+ * @param {{ name: string }} [options.token]  the contract is the token its literal amounts are in: `metadata.token`
+ * @returns {{ descriptor: object, descriptorHash: string, notes: string[] }}  `notes`: what was left out because a
+ *   file cannot say it, though the file still shows every value (a timestamp's words, an interpolatedIntent)
+ */
+export function erc7730Descriptor(resolved, options = {}) {
+  if (!isObject(resolved) || resolved.format !== "candid-profile-resolved" || !isObject(resolved.methods) || resolved.chain !== "evm") methodOf(resolved, "", "evm"); // throws the right error
+  if (!isObject(options)) fail(CODES.REQUEST, "options must be an object");
+  for (const k of Object.keys(options)) if (!OPTIONS.has(k)) fail(CODES.REQUEST, `unknown option ${JSON.stringify(k)}; expected one of ${[...OPTIONS].join(", ")}`);
+  if (options.token !== undefined && !(isObject(options.token) && nonEmpty(options.token.name) && Object.keys(options.token).length === 1)) fail(CODES.REQUEST, "options.token must be { name } with a non-empty string");
+  const context = options.context ?? "contract";
+  if (context !== "contract" && context !== "eip712") fail(CODES.REQUEST, `options.context must be "contract" or "eip712", got ${JSON.stringify(options.context)}`);
+
+  const problems = [];
+  const notes = [];
+  const ctx = {
+    erc20: erc20Metadata(resolved),
+    tokenName: options.token?.name,
+    token: null,
+    dynamic: false,
+    problem: (at, message) => void problems.push(`${at}: ${message}`),
+    note: (at, message) => void notes.push(`${at}: ${message}`),
+  };
+  const deployments = deploymentsOf(resolved, options.deployments);
+  const metadata = metadataOf(options);
+  const formats = context === "eip712" ? messageFormats(resolved, ctx) : functionFormats(resolved, ctx);
+  const domain = context === "eip712" ? domainOf(resolved, ctx) : {};
   if (ctx.dynamic && ctx.token) problems.push("amounts: some read decimals() and symbol(), others are literal; an ERC-7730 wallet reads one token for @.to");
   if (problems.length) fail(CODES.EXPORT, `no ERC-7730 file: ${problems.join("; ")}`);
-  if (Object.keys(formats).length === 0) fail(CODES.EXPORT, "no ERC-7730 file: the contract has no function a transaction calls (every function is view or pure)");
 
   if (ctx.token) metadata.token = { name: ctx.tokenName, ticker: ctx.token.ticker, decimals: ctx.token.decimals };
-  const descriptor = { $schema: ERC7730_SCHEMA_URL, context: { contract: { deployments } } };
+  const bound = context === "eip712" ? { eip712: { ...(Object.keys(domain).length ? { domain } : {}), deployments } } : { contract: { deployments } };
+  const descriptor = { $schema: ERC7730_SCHEMA_URL, context: bound };
   if (Object.keys(metadata).length) descriptor.metadata = metadata;
   descriptor.display = { formats };
-  return { descriptor, descriptorHash: descriptorHash(descriptor) };
+  return { descriptor, descriptorHash: descriptorHash(descriptor), notes };
 }
 
 /** ERC-8176 `descriptorHash`: Keccak-256 of the RFC 8785 (JCS) form of a descriptor without `includes`. */

package/src/errors.mjs

@@ -22,6 +22,8 @@ export const CODES = Object.freeze({
   LANGUAGE: "E_LANGUAGE", // only with languagePolicy "error": the requested language is not supported
   REQUEST: "E_REQUEST", // the ICRC-21 request itself is malformed
   DEPLOYMENT: "E_DEPLOYMENT", // an EVM call's target is not a deployment its profile lists (spec section 15)
+  DOMAIN: "E_DOMAIN", // an EIP-712 request's domain is for another chain, contract or name than its profile's (spec section 15.9)
+  TYPE_HASH: "E_TYPE_HASH", // no message of the resolved form has the request's EIP-712 type hash (spec section 15.9)
   // this generator cannot describe the call (ICRC-21 ConsentMessageUnavailable)
   UNSUPPORTED_TYPE: "E_UNSUPPORTED_TYPE", // a position the resolved form cannot type (recursive cut, func, service)
   // the profile or the caller's context is wrong (ICRC-21 GenericError)

package/src/evm.d.mts

@@ -23,6 +23,11 @@ export interface EvmConsentInput {
   chainId?: number | bigint | string;
   /** Resolved dynamic refs, keyed by `from`: `{ "query:decimals": 6, "query:symbol": "USDC" }`. */
   refs?: Record<string, unknown>;
+  /**
+   * For an amount whose token a field names (spec section 15.9): each such token's `decimals()` and `symbol()`, keyed by
+   * its address. An amount in a token not listed is E_REF_UNRESOLVED; it is shown beside its token's address.
+   */
+  tokens?: Record<string, { decimals: number | bigint | string; symbol?: string }>;
   /** Default "generic" (Markdown). */
   form?: "generic" | "fields";
   /** Generic form only: show timestamps in this zone (default UTC). */
@@ -49,3 +54,53 @@ export function evmConsent(input: EvmConsentInput): {
   provenance: Provenance;
   model: Model;
 };
+
+/** An EIP-712 signing request, as `eth_signTypedData_v4` takes it. `types.EIP712Domain` may be left out. */
+export interface TypedData {
+  types: Record<string, { name: string; type: string }[]>;
+  primaryType: string;
+  domain: { name?: string; version?: string; chainId?: number | bigint | string; verifyingContract?: string; salt?: string };
+  message: Record<string, unknown>;
+}
+export interface Eip712ConsentInput {
+  /** An EVM contract's resolved form with `messages` (spec section 15.9). */
+  resolved: ResolvedForm;
+  typedData: TypedData;
+  /** The wallet's active chain: a domain for another chain is refused (E_DOMAIN). */
+  chainId: number | bigint | string;
+  /** Resolved dynamic refs; `query:` refs are calls to the verifying contract. */
+  refs?: Record<string, unknown>;
+  /** For an amount whose token a member names: each token's `decimals()` and `symbol()`, keyed by its address. */
+  tokens?: Record<string, { decimals: number | bigint | string; symbol?: string }>;
+  /** Default "generic" (Markdown). */
+  form?: "generic" | "fields";
+  /** Generic form only: show timestamps in this zone (default UTC). */
+  utcOffsetMinutes?: number | null;
+  /** Append the message's values (spec section 11 item 1). */
+  rawArguments?: boolean;
+  limits?: { maxBytes?: number; maxElements?: number };
+}
+/**
+ * The consent text of an EIP-712 signing request (spec section 15.9): the message a profile describes, matched by its
+ * type hash, in words, ending with the verifying contract, the digest and what a signature is. Refused before anything
+ * is shown: a domain for another chain, without a chainId or verifyingContract, with a salt, or whose name or version
+ * is not its profiles' (E_DOMAIN); a contract its profiles do not list (E_DEPLOYMENT); no message with the request's
+ * type hash (E_TYPE_HASH); values that are not exactly the members, canonically written (E_DECODE); an amount in a
+ * token not in `tokens` (E_REF_UNRESOLVED).
+ */
+export function eip712Consent(input: Eip712ConsentInput): {
+  form: "generic" | "fields";
+  /** Markdown for "generic"; the intent line and `[label, text]` rows for "fields". */
+  message: string | { intent: string; fields: [string, string][] };
+  primaryType: string;
+  /** `0x` and 64 hex digits. */
+  typeHash: string;
+  /** The EIP-712 digest the signature signs: `0x` and 64 hex digits. */
+  digest: string;
+  /** The verifying contract, in its EIP-55 form. */
+  verifyingContract: string;
+  chainId: string;
+  diagnostics: ConsentDiagnostic[];
+  provenance: Provenance;
+  model: Model;
+};

package/src/evm.mjs

@@ -13,13 +13,19 @@
 //      person must see which contract asks (spec section 11).
 //
 // Refused: a payable function (its native value has no position yet, O2), and a call with no matching selector.
+//
+// A typed message (EIP-712, spec section 15.9) is the other thing an EVM wallet is asked to sign: `eip712Consent`
+// gives it the same model and layouts, after checking that the request is the message a profile describes (its chain,
+// its contract, its domain, its type hash) and reading its values strictly. An amount whose token a field names is
+// shown with that token's decimals and symbol, which the caller supplies per address (`tokens`), and its address.
 
-import { AbiError, decodeParams, parseSignature, readAddress } from "@meantjs/profile/evm";
-import { Renderer } from "./display.mjs";
+import { AbiError, DEFAULT_ABI_LIMITS, decodeParams, eip712TypeHash, keccak256Hex, parseEip712Types, parseSignature, readAddress, typedDataDigest } from "@meantjs/profile/evm";
+import { Renderer, TokenAmount } from "./display.mjs";
 import { CODES, ConsentError, fail } from "./errors.mjs";
 import { modelOf } from "./model.mjs";
+import { resolvePath } from "./paths.mjs";
 import { renderGeneric, renderPlain } from "./render.mjs";
-import { abiView, methodOf } from "./resolved.mjs";
+import { abiView, entriesOf, methodOf, tagArgs } from "./resolved.mjs";
 import { codeSpan } from "./text.mjs";
 
 const isObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
@@ -85,6 +91,49 @@ function checkTarget(resolved, to, chain) {
   }
 }
 
+/** The caller's `tokens`: the decimals and symbol of each token, keyed by its address in any valid spelling. */
+function tokenTable(tokens) {
+  if (!isObject(tokens)) fail(CODES.REQUEST, "tokens must be an object of token address to { decimals, symbol }");
+  const out = new Map();
+  for (const [k, v] of Object.entries(tokens)) {
+    let address;
+    try {
+      address = readAddress(k);
+    } catch (e) {
+      if (e instanceof AbiError) fail(CODES.REQUEST, `tokens: ${e.message}`);
+      throw e;
+    }
+    if (!isObject(v)) fail(CODES.REQUEST, `tokens[${JSON.stringify(k)}] must be { decimals, symbol }`);
+    if (out.has(address)) fail(CODES.REQUEST, `tokens lists ${address} twice`);
+    out.set(address, { decimals: v.decimals, symbol: v.symbol });
+  }
+  return out;
+}
+
+/**
+ * The arguments with each amount whose token a field names (spec section 15.9) made a TokenAmount: its base units, the
+ * address that field holds in the same array element, and that token's metadata from `tokens`. A token the caller did
+ * not describe stops the message (E_REF_UNRESOLVED): a number without its decimals is never shown (spec section 12
+ * rule 10).
+ */
+function withTokens(name, viewed, args, tokens) {
+  const box = (node, value, keys, indices) => {
+    if (node.candid === "record") return Object.fromEntries(entriesOf(node.fields).map(([k, child]) => [k, box(child, value[k], [...keys, k], indices)]));
+    if (node.candid === "vec") return value.map((e, i) => box(node.element, e, [...keys, "[]"], [...indices, i]));
+    const token = tagArgs(node, "amount")?.token;
+    if (token === undefined) return value;
+    const where = `${name}(0)${keys.map((k) => (k === "[]" ? "[]" : `.${k}`)).join("")}`;
+    const rp = resolvePath(viewed, String(token));
+    let address = rp.error ? undefined : args[rp.index];
+    let n = 0;
+    for (const step of rp.steps ?? []) address = step.kind === "elem" ? address?.[indices[n++]] : address?.[step.key];
+    if (typeof address !== "string" || rp.node.abi !== "address" || n > indices.length) fail(CODES.RESOLVED_FORM, `${where}: amount.token ${JSON.stringify(token)} does not lead to an address in the same element`);
+    if (!tokens.has(address)) fail(CODES.REF_UNRESOLVED, `${where} is an amount of the token ${address}, whose decimals and symbol were not given (tokens); without them it has no text`);
+    return new TokenAmount(value, address, tokens.get(address));
+  };
+  return args.map((v, i) => box(viewed.args[i], v, [], []));
+}
+
 /**
  * The consent text of an EVM call.
  *
@@ -94,13 +143,15 @@ function checkTarget(resolved, to, chain) {
  * @param {string} input.to  the contract called (shown, and checked against the profiles' deployments)
  * @param {number | bigint | string} [input.chainId]  needed when a profile lists deployments
  * @param {Record<string, unknown>} [input.refs]  resolved dynamic refs, for example { "query:decimals": 6, "query:symbol": "USDC" }
+ * @param {Record<string, { decimals: number, symbol?: string }>} [input.tokens]  for an amount whose token a field
+ *   names (spec section 15.9): each such token's decimals() and symbol(), keyed by its address
  * @param {"generic" | "fields"} [input.form]  default "generic"
  * @param {number | null} [input.utcOffsetMinutes]  generic form only (default 0, UTC)
  * @param {boolean} [input.rawArguments]  append the decoded arguments (spec section 11 item 1)
  * @param {object} [input.limits]  decoder limits (maxBytes, maxDepth, maxElements)
  * @returns {{ form: string, message: string | { intent: string, fields: Array<[string, string]> }, method: string, selector: string, to: string, chainId: string | null, diagnostics: object[], provenance: object, model: object }}
  */
-export function evmConsent({ resolved, calldata, to, chainId, refs = {}, form = "generic", utcOffsetMinutes = null, rawArguments = false, limits }) {
+export function evmConsent({ resolved, calldata, to, chainId, refs = {}, tokens = {}, form = "generic", utcOffsetMinutes = null, rawArguments = false, limits }) {
   if (form !== "generic" && form !== "fields") fail(CODES.REQUEST, `form must be "generic" or "fields", got ${JSON.stringify(form)}`);
   let target;
   try {
@@ -115,7 +166,7 @@ export function evmConsent({ resolved, calldata, to, chainId, refs = {}, form =
   const method = methodOf(resolved, name, "evm");
   if (method.state_mutability === "payable") fail(CODES.UNSUPPORTED_TYPE, `${name} is payable: the native value a call sends has no position in a profile yet (spec section 15, O2)`);
   const viewed = { ...method, args: method.args.map((n, i) => abiView(n, `${name}(${i})`)) };
-  const model = modelOf(resolved, name, viewed, viewed.args.length ? [values] : []);
+  const model = modelOf(resolved, name, viewed, viewed.args.length ? withTokens(name, viewed, [values], tokenTable(tokens)) : []);
   const where = `${target}${chain === null ? "" : ` on chain ${chain}`}`;
   const done = (rest) => ({ ...rest, method: name, selector, to: target, chainId: chain, diagnostics: model.diagnostics, provenance: model.provenance, model });
   if (form === "fields") {
@@ -127,3 +178,181 @@ export function evmConsent({ resolved, calldata, to, chainId, refs = {}, form =
   const text = `${renderGeneric(model, renderer, { rawArguments })}\n\n**Contract:** ${codeSpan(target)}${chain === null ? "" : ` on chain ${chain}`}`;
   return done({ form, message: text });
 }
+
+// ---------------------------------------------------------------------------------------------- EIP-712 messages
+
+/** The domain's fields in the order EIP-712 lists them, with their types. */
+const DOMAIN_FIELDS = [
+  ["name", "string"],
+  ["version", "string"],
+  ["chainId", "uint256"],
+  ["verifyingContract", "address"],
+  ["salt", "bytes32"],
+];
+
+/** One value of a typed message, read strictly (spec section 15.9): the shapes decodeCalldata gives, or E_DECODE. */
+function readTyped(types, type, value, where, budget) {
+  const bad = (message) => fail(CODES.DECODE, `${where}: ${message}`);
+  const arr = /^(.*)\[(\d*)\]$/.exec(type);
+  if (arr) {
+    if (!Array.isArray(value)) bad(`${type} needs an array`);
+    if (arr[2] !== "" && value.length !== Number(arr[2])) bad(`${type} needs ${arr[2]} elements, got ${value.length}`);
+    budget.elements += value.length;
+    if (budget.elements > budget.maxElements) bad(`more than ${budget.maxElements} array elements in the message`);
+    return value.map((v, i) => readTyped(types, arr[1], v, `${where}[${i}]`, budget));
+  }
+  if (Object.hasOwn(types, type)) {
+    if (!isObject(value)) bad(`${type} needs an object of its members`);
+    const members = types[type];
+    for (const k of Object.keys(value)) if (!members.some((m) => m.name === k)) bad(`${type} has no member ${JSON.stringify(k)}`);
+    return Object.fromEntries(members.map((m) => [m.name, Object.hasOwn(value, m.name) ? readTyped(types, m.type, value[m.name], `${where}.${m.name}`, budget) : bad(`${type} needs its member ${m.name}`)]));
+  }
+  const int = /^(u?)int([0-9]+)$/.exec(type);
+  if (int) {
+    let x;
+    if (typeof value === "number" && Number.isSafeInteger(value)) x = BigInt(value);
+    else if (typeof value === "string" && /^-?(?:0|[1-9][0-9]*)$/.test(value) && value !== "-0") x = BigInt(value);
+    else bad(`${type} needs a decimal string or a JSON integer below 2^53, got ${JSON.stringify(value)}`);
+    const bits = BigInt(int[2]);
+    const [min, max] = int[1] === "u" ? [0n, 2n ** bits - 1n] : [-(2n ** (bits - 1n)), 2n ** (bits - 1n) - 1n];
+    if (x < min || x > max) bad(`${x} is outside ${type}`);
+    return x.toString();
+  }
+  if (type === "address") {
+    try {
+      return readAddress(value);
+    } catch (e) {
+      if (e instanceof AbiError) bad(e.message);
+      throw e;
+    }
+  }
+  if (type === "bool") return typeof value === "boolean" ? value : bad("bool needs true or false");
+  if (type === "string") return typeof value === "string" && value.isWellFormed() ? value : bad("string needs well-formed text");
+  const bytes = /^bytes([0-9]*)$/.exec(type);
+  if (bytes) {
+    if (typeof value !== "string" || !/^0x(?:[0-9a-fA-F]{2})*$/.test(value)) bad(`${type} needs 0x and hex digits`);
+    const b = Uint8Array.from(value.slice(2).match(/../g) ?? [], (h) => parseInt(h, 16));
+    if (bytes[1] !== "" && b.length !== Number(bytes[1])) bad(`${type} needs ${bytes[1]} bytes, got ${b.length}`);
+    if (b.length > budget.maxBytes) bad(`${b.length} bytes is over the limit of ${budget.maxBytes}`);
+    return b;
+  }
+  bad(`unknown type ${type}`);
+}
+
+/** The request's domain: only EIP-712's fields, no salt (O3), and its EIP712Domain type, if given, exactly those fields. */
+function readDomain(domain, declared) {
+  if (!isObject(domain)) fail(CODES.REQUEST, "typedData.domain must be an object");
+  for (const k of Object.keys(domain)) if (!DOMAIN_FIELDS.some(([f]) => f === k)) fail(CODES.DOMAIN, `the domain has a field ${JSON.stringify(k)} EIP-712 does not define`);
+  if (Object.hasOwn(domain, "salt")) fail(CODES.DOMAIN, "a domain with a salt is not supported yet (spec section 15.9, O3)");
+  const fields = DOMAIN_FIELDS.filter(([k]) => Object.hasOwn(domain, k)).map(([name, type]) => ({ name, type }));
+  // Each member's name and type, in order; the order of a member's JSON keys is not part of the type (as for the other structs).
+  const same = Array.isArray(declared) && declared.length === fields.length && declared.every((m, i) => isObject(m) && m.name === fields[i].name && m.type === fields[i].type);
+  if (declared !== undefined && !same) {
+    fail(CODES.DOMAIN, `types.EIP712Domain must list the domain's fields in EIP-712 order (${fields.map((f) => `${f.type} ${f.name}`).join(", ")})`);
+  }
+  for (const k of ["name", "version"]) if (Object.hasOwn(domain, k) && typeof domain[k] !== "string") fail(CODES.DOMAIN, `domain.${k} must be a string`);
+  if (!Object.hasOwn(domain, "chainId")) fail(CODES.DOMAIN, "the domain has no chainId, so the signature is valid on every chain; it is refused");
+  if (!Object.hasOwn(domain, "verifyingContract")) fail(CODES.DOMAIN, "the domain has no verifyingContract: the contract that will act on the signature must be known");
+  const chain = readTyped({}, "uint256", domain.chainId, "domain.chainId", { elements: 0, maxElements: 0, maxBytes: 0 });
+  let contract;
+  try {
+    contract = readAddress(domain.verifyingContract);
+  } catch (e) {
+    if (e instanceof AbiError) fail(CODES.DOMAIN, `domain.verifyingContract: ${e.message}`);
+    throw e;
+  }
+  return { fields, chain, contract };
+}
+
+/** The message of a resolved form whose type hash is the request's; the entry's own encode_type must hash to it. */
+function messageOf(resolved, primaryType, typeHash) {
+  if (!isObject(resolved) || resolved.format !== "candid-profile-resolved" || !isObject(resolved.methods) || resolved.chain !== "evm") methodOf(resolved, "", "evm"); // throws the right error
+  if (!isObject(resolved.messages)) fail(CODES.TYPE_HASH, "the resolved form describes no EIP-712 message");
+  const hit = entriesOf(resolved.messages).find(([, m]) => isObject(m) && m.type_hash === typeHash);
+  if (!hit) fail(CODES.TYPE_HASH, `no message of the resolved form has the type hash ${typeHash} (${primaryType}); a request is matched by its type hash, never by its name`);
+  const [name, m] = hit;
+  if (typeof m.encode_type !== "string" || `0x${keccak256Hex(m.encode_type)}` !== typeHash || name !== primaryType || !m.encode_type.startsWith(`${name}(`)) {
+    fail(CODES.RESOLVED_FORM, `messages.${name}: its encode_type does not hash to its type_hash, or names another type`);
+  }
+  if (!Array.isArray(m.args) || m.args.length !== 1) fail(CODES.RESOLVED_FORM, `messages.${name} has no args array of one struct`);
+  return { name, message: m };
+}
+
+/**
+ * Every profile that names the domain (`eip712_domain`) must name the request's: its name and its version each equal,
+ * and absent where the profile's is absent (Permit2's domain has no version; one with a version is another domain).
+ */
+function checkDomain(resolved, domain) {
+  for (const p of Array.isArray(resolved.profiles) ? resolved.profiles : []) {
+    if (!isObject(p?.eip712_domain)) continue;
+    for (const k of ["name", "version"]) {
+      const v = p.eip712_domain[k];
+      if (domain[k] === v) continue;
+      const theirs = domain[k] === undefined ? "a domain without one" : JSON.stringify(domain[k]);
+      fail(CODES.DOMAIN, v === undefined ? `profile ${p.name} describes a domain without a ${k}, not one whose ${k} is ${theirs}` : `profile ${p.name} describes the domain whose ${k} is ${JSON.stringify(v)}, not ${theirs}`);
+    }
+  }
+}
+
+/**
+ * The consent text of an EIP-712 signing request (spec section 15.9): the message a profile describes, its values in
+ * words, and what a signature is. Refused before anything is shown when the request does not match: a domain for
+ * another chain than the wallet's or without a chainId or verifyingContract (E_DOMAIN), a contract its profiles do not
+ * list (E_DEPLOYMENT), a domain name or version other than its profiles' (E_DOMAIN), no message with the request's
+ * type hash (E_TYPE_HASH), a message whose values are not exactly its members, canonically written (E_DECODE).
+ *
+ * @param {object} input
+ * @param {object} input.resolved  an EVM contract's resolved form with `messages`
+ * @param {{ types: object, primaryType: string, domain: object, message: object }} input.typedData  the request
+ *   (`eth_signTypedData_v4`'s JSON); `types.EIP712Domain` may be left out
+ * @param {number | bigint | string} input.chainId  the wallet's active chain
+ * @param {Record<string, unknown>} [input.refs]  resolved dynamic refs: `query:` refs are calls to the verifying contract
+ * @param {Record<string, { decimals: number, symbol?: string }>} [input.tokens]  each token an amount's `token` names
+ * @param {"generic" | "fields"} [input.form]  default "generic"
+ * @param {number | null} [input.utcOffsetMinutes]  generic form only (default 0, UTC)
+ * @param {boolean} [input.rawArguments]  append the message's values (spec section 11 item 1)
+ * @param {{ maxBytes?: number, maxElements?: number }} [input.limits]
+ */
+export function eip712Consent({ resolved, typedData, chainId, refs = {}, tokens = {}, form = "generic", utcOffsetMinutes = null, rawArguments = false, limits = {} }) {
+  if (form !== "generic" && form !== "fields") fail(CODES.REQUEST, `form must be "generic" or "fields", got ${JSON.stringify(form)}`);
+  if (!isObject(typedData) || !isObject(typedData.types) || typeof typedData.primaryType !== "string" || !isObject(typedData.message)) {
+    fail(CODES.REQUEST, "typedData must be { types, primaryType, domain, message }");
+  }
+  const active = chainOf(chainId);
+  if (active === null) fail(CODES.REQUEST, "give the wallet's active chainId: a signature for another chain is refused");
+  const { EIP712Domain: declared, ...own } = typedData.types;
+  const { fields: domainType, chain, contract } = readDomain(typedData.domain, declared);
+  if (chain !== active) fail(CODES.DOMAIN, `the domain is for chain ${chain}, the wallet is on chain ${active}`);
+  const parsed = parseEip712Types(own, "typedData.types");
+  if (parsed.errors.length) fail(CODES.REQUEST, parsed.errors.map((e) => `${e.at}: ${e.message}`).join("; "));
+  if (!Object.hasOwn(parsed.types, typedData.primaryType)) fail(CODES.REQUEST, `typedData.types has no ${JSON.stringify(typedData.primaryType)}`);
+  const typeHash = eip712TypeHash(parsed.types, typedData.primaryType);
+  const { name, message } = messageOf(resolved, typedData.primaryType, typeHash);
+  checkTarget(resolved, contract, chain);
+  checkDomain(resolved, typedData.domain);
+
+  const budget = { elements: 0, maxElements: limits.maxElements ?? DEFAULT_ABI_LIMITS.maxElements, maxBytes: limits.maxBytes ?? DEFAULT_ABI_LIMITS.maxBytes };
+  const values = readTyped(parsed.types, name, typedData.message, "message", budget);
+  let digest;
+  try {
+    digest = typedDataDigest({ domain: typedData.domain, types: { ...parsed.types, EIP712Domain: domainType }, primaryType: name, message: typedData.message });
+  } catch (e) {
+    if (e instanceof AbiError) fail(CODES.DECODE, e.message);
+    throw e;
+  }
+  const viewed = { ...message, args: message.args.map((n, i) => abiView(n, `${name}(${i})`)) };
+  const model = modelOf(resolved, name, viewed, withTokens(name, viewed, [values], tokenTable(tokens)));
+  const where = `${contract} on chain ${chain}`;
+  const done = (rest) => ({ ...rest, primaryType: name, typeHash, digest, verifyingContract: contract, chainId: chain, diagnostics: model.diagnostics, provenance: model.provenance, model });
+  if (form === "fields") {
+    const plain = renderPlain(model, new Renderer({ refs, diagnostics: model.diagnostics }), { rawArguments });
+    plain.fields.push(["Contract", where], ["Signature", SIGNATURE_NOTE], ["EIP-712 digest", digest]);
+    return done({ form, message: plain });
+  }
+  const renderer = new Renderer({ refs, utcOffsetMinutes: utcOffsetMinutes ?? 0, diagnostics: model.diagnostics });
+  const text = `${renderGeneric(model, renderer, { rawArguments })}\n\n**Contract:** ${codeSpan(contract)} on chain ${chain}\n\n**EIP-712 digest:** ${codeSpan(digest)}\n\n${SIGNATURE_NOTE}.`;
+  return done({ form, message: text });
+}
+
+/** What a typed-data signature is, said with every message (spec section 15.9). */
+const SIGNATURE_NOTE = "This is a signature, not a transaction: whoever holds it can submit it";

package/src/index.d.mts

@@ -207,6 +207,8 @@ export const CODES: Readonly<{
   LANGUAGE: "E_LANGUAGE";
   REQUEST: "E_REQUEST";
   DEPLOYMENT: "E_DEPLOYMENT";
+  DOMAIN: "E_DOMAIN";
+  TYPE_HASH: "E_TYPE_HASH";
   UNSUPPORTED_TYPE: "E_UNSUPPORTED_TYPE";
   RESOLVED_FORM: "E_RESOLVED_FORM";
   TEMPLATE: "E_TEMPLATE";