@meantjs/consent 0.1.0 → 0.3.0

package/src/evm.mjs

@@ -0,0 +1,358 @@
+// EVM calldata -> the consent text of a call (spec section 15, D-054). ICRC-21 is the Internet Computer's, so an EVM
+// call gets the same model and the same two layouts without the ICRC-21 envelope: the generic form (Markdown) and the
+// fields form as plain text.
+//
+// Steps:
+//   1. the resolved form must be an EVM contract's (`chain: "evm"`), and the call's target, when a profile lists
+//      deployments, one of them (a profile describes the contracts it binds, never a look-alike);
+//   2. the selector picks the function; its `signature` gives the parameter types, and calldata is decoded strictly
+//      (`@meantjs/profile/evm` decodeParams: anything but the canonical encoding of the values read is refused);
+//   3. the resolved tree is read as a Candid-shaped view (a tuple is a record, an array a vec), so the template, the
+//      paths and the fields are those of a Candid call (model.mjs);
+//   4. the text ends with the contract's address and chain: a pack applies to any contract whose functions match, so a
+//      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, 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, entriesOf, methodOf, tagArgs } from "./resolved.mjs";
+import { codeSpan } from "./text.mjs";
+
+const isObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+
+function bytesOf(calldata) {
+  if (calldata instanceof Uint8Array) return calldata;
+  if (typeof calldata === "string" && /^0x(?:[0-9a-fA-F]{2})*$/.test(calldata)) return Uint8Array.from(calldata.slice(2).match(/../g) ?? [], (h) => parseInt(h, 16));
+  fail(CODES.REQUEST, "calldata must be a Uint8Array or 0x hex text");
+}
+
+function chainOf(chainId) {
+  if (chainId === undefined || chainId === null) return null;
+  const s = typeof chainId === "number" && Number.isSafeInteger(chainId) ? String(chainId) : typeof chainId === "bigint" ? chainId.toString() : chainId;
+  if (typeof s !== "string" || !/^[1-9][0-9]{0,19}$/.test(s)) fail(CODES.REQUEST, `chainId must be a positive integer, got ${String(chainId)}`);
+  return s;
+}
+
+/** The function of a selector, from the resolved form; its signature is checked against the selector. */
+function functionOf(resolved, selector) {
+  const hit = Object.entries(resolved.methods).find(([, m]) => isObject(m) && m.selector === selector);
+  if (!hit) fail(CODES.METHOD_UNKNOWN, `the resolved form has no function with selector ${selector}`);
+  const [name, method] = hit;
+  let f;
+  try {
+    f = parseSignature(String(method.signature), `methods.${name}.signature`);
+  } catch (e) {
+    if (e instanceof AbiError) fail(CODES.RESOLVED_FORM, e.message);
+    throw e;
+  }
+  if (f.name !== name || f.selector !== selector) fail(CODES.RESOLVED_FORM, `methods.${name}: the signature ${method.signature} does not hash to ${selector}`);
+  return { name, method: methodOf(resolved, name, "evm"), f };
+}
+
+/**
+ * Decode one EVM call against a resolved form: which function, and its arguments.
+ *
+ * @param {object} resolved  an EVM contract's resolved form (`chain: "evm"`)
+ * @param {Uint8Array | string} calldata  the selector and the ABI-encoded arguments
+ * @param {{ maxBytes?: number, maxDepth?: number, maxElements?: number }} [limits]
+ * @returns {{ method: string, selector: string, values: Record<string, unknown> }}
+ */
+export function decodeCalldata(resolved, calldata, limits) {
+  if (!isObject(resolved) || resolved.format !== "candid-profile-resolved" || !isObject(resolved.methods) || resolved.chain !== "evm") methodOf(resolved, "", "evm"); // throws the right error
+  const data = bytesOf(calldata);
+  if (data.length < 4) fail(CODES.DECODE, `calldata of ${data.length} bytes has no selector`);
+  const selector = `0x${[...data.subarray(0, 4)].map((b) => b.toString(16).padStart(2, "0")).join("")}`;
+  const { name, f } = functionOf(resolved, selector);
+  try {
+    return { method: name, selector, values: decodeParams(f.inputs, data.subarray(4), limits) };
+  } catch (e) {
+    if (e instanceof AbiError) throw new ConsentError(CODES.DECODE, `${name}: ${e.message}`, { cause: e });
+    throw e;
+  }
+}
+
+/** Every profile that lists deployments must list this one (chain id and address). */
+function checkTarget(resolved, to, chain) {
+  for (const p of Array.isArray(resolved.profiles) ? resolved.profiles : []) {
+    if (!Array.isArray(p?.deployments)) continue;
+    if (chain === null) fail(CODES.REQUEST, `profile ${p.name} binds deployments: give the chainId of the call`);
+    const listed = p.deployments.some((d) => String(d.chain_id) === chain && typeof d.address === "string" && d.address.toLowerCase() === to.toLowerCase());
+    if (!listed) fail(CODES.DEPLOYMENT, `profile ${p.name} describes ${p.deployments.map((d) => `${d.address} on chain ${d.chain_id}`).join(", ")}, not ${to} on chain ${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.
+ *
+ * @param {object} input
+ * @param {object} input.resolved  an EVM contract's resolved form
+ * @param {Uint8Array | string} input.calldata
+ * @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 = {}, 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 {
+    target = readAddress(to);
+  } catch (e) {
+    if (e instanceof AbiError) fail(CODES.REQUEST, `to: ${e.message}`);
+    throw e;
+  }
+  const chain = chainOf(chainId);
+  const { method: name, selector, values } = decodeCalldata(resolved, calldata, limits);
+  checkTarget(resolved, target, chain);
+  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 ? 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") {
+    const plain = renderPlain(model, new Renderer({ refs, diagnostics: model.diagnostics }), { rawArguments });
+    plain.fields.push(["Contract", where]);
+    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(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

@@ -206,6 +206,9 @@ export const CODES: Readonly<{
   TOO_LARGE: "E_TOO_LARGE";
   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";
@@ -214,6 +217,7 @@ export const CODES: Readonly<{
   ARG: "E_ARG";
   TAG_TYPE: "E_TAG_TYPE";
   TAG_CONFLICT: "E_TAG_CONFLICT";
+  EXPORT: "E_EXPORT";
 }>;
 export type ConsentErrorCode = (typeof CODES)[keyof typeof CODES];
 /** ICRC-21 `GenericError.error_code` values this package uses. */

package/src/model.mjs

@@ -3,9 +3,10 @@
 // disagree about which values the call carries.
 //
 // Which fields appear:
-//   - a method with an `intent` tag: the placeholders of its template that are present (spec section 6; section 12:
-//     "one (label, Value) row per placeholder"), in template order, once per distinct path;
-//   - a method without one: the generic intent. Title from `describe.label` of the method, else `Call <method>`;
+//   - a call with an intent, its case's (spec section 5.2, D-053) or else its method's: the placeholders of its template
+//     that are present (spec section 6; section 12: "one (label, Value) row per placeholder"), in template order,
+//     once per distinct path;
+//   - a call without one: the generic intent. Title from `describe.label` of the method, else `Call <method>`;
 //     one field per leaf of the decoded arguments (records are flattened, tagged positions such as accounts are
 //     leaves, absent optionals are left out). More than MAX_FIELDS fields or MAX_ELEMENTS list elements is
 //     refused (E_TOO_LARGE), never truncated.
@@ -13,7 +14,7 @@
 import { VALUE_TAGS } from "@meantjs/format";
 import { decodeArguments } from "./decode.mjs";
 import { CODES, ConsentError, fail } from "./errors.mjs";
-import { effectKind, entriesOf, labelOf, methodOf } from "./resolved.mjs";
+import { callTag, effectKind, entriesOf, labelOf, methodOf } from "./resolved.mjs";
 import { parseTemplate } from "./template.mjs";
 import { resolvePath, valuesAt } from "./paths.mjs";
 
@@ -31,9 +32,9 @@ export const MAX_ELEMENTS = 256;
  *
  * @typedef {object} Model
  * @property {string} method
- * @property {string} effect  the effect kind of the method (spec section 5.3)
+ * @property {string} effect  the effect kind of the call: its case's, else its method's (spec section 5.3, D-053)
  * @property {string} title
- * @property {SentencePart[] | null} sentence  null for a method without an intent template
+ * @property {SentencePart[] | null} sentence  null for a call without an intent template
  * @property {Field[]} fields
  * @property {object[]} argNodes
  * @property {unknown[]} argValues
@@ -48,13 +49,18 @@ export const MAX_ELEMENTS = 256;
  */
 export function buildModel({ resolved, method: name, arg, limits }) {
   const method = methodOf(resolved, name);
-  const argValues = decodeArguments(method, arg, limits);
+  return modelOf(resolved, name, method, decodeArguments(method, arg, limits));
+}
+
+/** The model of a call whose arguments are decoded already (evm.mjs decodes calldata, then comes here). */
+export function modelOf(resolved, name, method, argValues) {
   const diagnostics = [];
-  const intent = method.tags?.intent?.args;
+  const intentTag = callTag(method, argValues, "intent"); // the call's intent: its case's, else its method's (D-053)
+  const intent = intentTag?.args;
   const title = typeof intent?.title === "string" && intent.title.trim() !== "" ? intent.title : (labelOf(method) ?? `Call ${name}`);
-  const tagOrigin = intent ? { origin: method.tags.intent.origin, ...(method.tags.intent.profile === undefined ? {} : { profile: method.tags.intent.profile }) } : null;
+  const tagOrigin = intent ? { origin: intentTag.origin, ...(intentTag.profile === undefined ? {} : { profile: intentTag.profile }) } : null;
   const provenance = { intent: tagOrigin, profiles: Array.isArray(resolved.profiles) ? resolved.profiles : [] };
-  const base = { method: name, effect: effectKind(method), title, argNodes: method.args, argValues, diagnostics, provenance };
+  const base = { method: name, effect: effectKind(method, callTag(method, argValues, "effect")), title, argNodes: method.args, argValues, diagnostics, provenance };
 
   if (intent && typeof intent.template === "string") {
     try {

package/src/render.mjs

@@ -50,6 +50,24 @@ export function renderFields(model, renderer, { rawArguments = false } = {}) {
   return { intent, fields };
 }
 
+/**
+ * The fields form as plain text, for a message that is not ICRC-21's (an EVM call, spec section 15): the same intent
+ * line as renderFields, and each row's values joined by ", ".
+ *
+ * @returns {{ intent: string, fields: Array<[string, string]> }}
+ */
+export function renderPlain(model, renderer, { rawArguments = false } = {}) {
+  const title = plainLabel(model.title, model.method);
+  let intent = title;
+  if (model.sentence !== null) {
+    const sentence = model.sentence.map((p) => ("lit" in p ? oneLine(p.lit) : fieldPlain(p.field, renderer))).join("");
+    if (sentence.trim() !== "") intent = `${title}: ${sentence.trim()}`;
+  }
+  const fields = model.fields.map((f) => [plainLabel(f.label, f.path), fieldPlain(f, renderer)]);
+  if (rawArguments) fields.push(["Raw arguments", visible(renderer.tupleText(model.argNodes, model.argValues))]);
+  return { intent, fields };
+}
+
 /** One row's ICRC-21 Value: typed when the field is a single value the typed form carries exactly, else Text. */
 function fieldValue(field, renderer) {
   if (field.values.length === 1) {

package/src/resolved.mjs

@@ -6,11 +6,17 @@ import { CODES, fail } from "./errors.mjs";
 
 const isObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
 
-/** The method entry of a resolved form, or a ConsentError. */
-export function methodOf(resolved, name) {
+/**
+ * The method entry of a resolved form, or a ConsentError. `chain` is "evm" for an EVM contract's form (spec section 15);
+ * a Candid entry point never reads one, whose positions are ABI types, not Candid.
+ */
+export function methodOf(resolved, name, chain = undefined) {
   if (!isObject(resolved) || resolved.format !== "candid-profile-resolved" || !isObject(resolved.methods)) {
     fail(CODES.RESOLVED_FORM, "not a candid-profile-resolved document (format, methods)");
   }
+  if (resolved.chain !== chain) {
+    fail(CODES.RESOLVED_FORM, resolved.chain === "evm" ? "this resolved form is an EVM contract's (chain evm): use evmConsent, not a Candid entry point" : `expected the resolved form of an EVM contract (chain evm), found ${resolved.chain === undefined ? "a Candid service's" : `chain ${JSON.stringify(resolved.chain)}`}`);
+  }
   if (typeof name !== "string" || !Object.hasOwn(resolved.methods, name)) {
     fail(CODES.METHOD_UNKNOWN, `the resolved form has no method ${JSON.stringify(String(name))}`);
   }
@@ -24,6 +30,20 @@ export function keyId(key) {
   return /^#(0|[1-9][0-9]{0,9})$/.test(key) ? Number(key.slice(1)) : idlHash(key);
 }
 
+/**
+ * A position of an EVM contract's resolved form (spec section 15) read as the Candid shapes the model walks: a tuple is
+ * a record, an array a vec, any other ABI type a primitive of that name. `abi` is kept, so display writes ABI text.
+ */
+export function abiView(node, where, depth = 0) {
+  if (!isObject(node) || typeof node.abi !== "string") fail(CODES.RESOLVED_FORM, `${where}: not an EVM resolved-form position`);
+  if (depth > 64) fail(CODES.UNSUPPORTED_TYPE, `${where}: nested deeper than 64`);
+  if (node.abi === "tuple") {
+    return { ...node, candid: "record", fields: Object.fromEntries(entriesOf(node.fields).map(([k, c]) => [k, abiView(c, `${where}.${k}`, depth + 1)])) };
+  }
+  if (node.abi === "array") return { ...node, candid: "vec", element: abiView(node.element, `${where}[]`, depth + 1) };
+  return { ...node, candid: node.abi };
+}
+
 /** Own entries of a `fields` or `cases` object (never walks the prototype chain). */
 export function entriesOf(bucket) {
   return isObject(bucket) ? Object.entries(bucket) : [];
@@ -39,7 +59,44 @@ export function tagArgs(node, tag) {
   return node?.tags && Object.hasOwn(node.tags, tag) ? (node.tags[tag]?.args ?? {}) : undefined;
 }
 
-/** The effect kind of a method: its tag, or the spec default (section 5.3: queries read, updates write). */
-export function effectKind(method) {
-  return method.tags?.effect?.args?.kind ?? (method.mode === "query" || method.mode === "composite_query" ? "read" : "write");
+/**
+ * The effect kind of a call: its effect tag (the call's, `callTag`; the method's by default), or the spec default
+ * (section 5.3: queries read, updates write).
+ */
+export function effectKind(method, tag = method.tags?.effect) {
+  return tag?.args?.kind ?? (method.mode === "query" || method.mode === "composite_query" ? "read" : "write");
+}
+
+/**
+ * The `intent` or `effect` entry (`{ args, origin, profile }`) a call takes: that of the deepest tagged variant case
+ * its decoded arguments hold (spec section 5.2, D-053), else the method's. The resolver lets the tagged cases of one
+ * method only exclude each other or nest, so the cases one call holds are a chain; a resolved form with tagged cases
+ * that one call holds side by side is not one a resolver writes, and the method's entry is used for it.
+ *
+ * @param {object} method  a method of the resolved form
+ * @param {unknown[]} argValues  its decoded arguments (decode.mjs: records by key, variants as { tag, value })
+ * @param {"intent" | "effect"} tag
+ */
+export function callTag(method, argValues, tag) {
+  let best = null; // { entry, chain }: the hit with the most hits above and at it
+  let hits = 0;
+  const visit = (node, value, chain) => {
+    if (!isObject(node) || node.recursive === true || !isObject(value)) return; // null: an absent optional, a bare case
+    if (node.candid === "record") {
+      for (const [key, child] of entriesOf(node.fields)) if (Object.hasOwn(value, key)) visit(child, value[key], chain);
+    } else if (node.candid === "variant") {
+      const hit = entriesOf(node.cases).find(([key]) => key === value.tag);
+      if (hit === undefined) return;
+      const child = hit[1];
+      const entry = isObject(child) && isObject(child.tags) && Object.hasOwn(child.tags, tag) ? child.tags[tag] : undefined;
+      if (isObject(entry)) {
+        chain += 1;
+        hits += 1;
+        if (best === null || chain > best.chain) best = { entry, chain };
+      }
+      visit(child, value.value, chain);
+    }
+  };
+  method.args.forEach((node, i) => visit(node, argValues[i], 0));
+  return best !== null && best.chain === hits ? best.entry : method.tags?.[tag];
 }

package/src/sns.mjs

@@ -26,8 +26,8 @@
 //   1. The body is the generic consent message of spec section 12 with the title at heading level 3, so it nests
 //      under governance's `## Payload:`. Times are shown in UTC (`2026-10-09 12:00:00 UTC`, rule 6 of section 12):
 //      a proposal has many readers and no user preferences.
-//   2. Then the method the rendering describes and its effect (spec section 5.3; the default for an update without
-//      an `effect` tag is said to be a default).
+//   2. Then the method the rendering describes and the call's effect (spec section 5.3: its case's, else its
+//      method's, D-053; the default for an update without an `effect` tag is said to be a default).
 //   3. Then the arguments as Candid text with no formatter applied (base units, nanoseconds, bytes), always: there is
 //      no signer between the text and the voter to show them (spec section 11 item 1).
 //   4. Then where the words come from: every profile with its profile_id, the interface_id, and these rules.
@@ -43,7 +43,7 @@ import { bytesOf } from "./bytes.mjs";
 import { ConsentError, CODES, fail } from "./errors.mjs";
 import { buildModel } from "./model.mjs";
 import { renderGeneric } from "./render.mjs";
-import { methodOf } from "./resolved.mjs";
+import { callTag, methodOf } from "./resolved.mjs";
 import { codeBlock, codeSpan, escapeMarkdown, oneLine } from "./text.mjs";
 
 /** The name and version of the rules this module renders by. Part of every rendering, so a re-render knows what to compare. */
@@ -114,7 +114,7 @@ function renderSnsPayload({ payload, resolved, method: name, refs, limits }) {
   const model = buildModel({ resolved, method: name, arg: payload, limits });
   const renderer = new Renderer({ refs, utcOffsetMinutes: 0, diagnostics: model.diagnostics });
   const blocks = [renderGeneric(model, renderer, { headingLevel: 3 })];
-  blocks.push(`**Method:** ${codeSpan(name)}. **Effect:** ${effectText(method)}.`);
+  blocks.push(`**Method:** ${codeSpan(name)}. **Effect:** ${effectText(method, callTag(method, model.argValues, "effect"))}.`);
   blocks.push(`**Arguments (Candid, as sent, no units applied):**\n\n${codeBlock(renderer.plainTupleText(model.argNodes, model.argValues))}`);
   blocks.push(sourceText(resolved));
   const text = blocks.join("\n\n");
@@ -125,12 +125,12 @@ function renderSnsPayload({ payload, resolved, method: name, refs, limits }) {
 const isQuery = (method) => method.mode === "query" || method.mode === "composite_query";
 
 /**
- * The effect kind and reversibility (spec section 5.3), and whether a profile stated them. The resolver writes the
+ * The effect kind and reversibility of the call (spec section 5.3; `tag` is its effect entry, `callTag`), and whether
+ * a profile stated them. The resolver writes the
  * section 5.3 default with origin "default" when no profile has an `effect` tag; this says so instead of passing a
  * default off as the author's word.
  */
-function effectText(method) {
-  const tag = method.tags?.effect;
+function effectText(method, tag) {
   const query = isQuery(method);
   const kind = typeof tag?.args?.kind === "string" ? tag.args.kind : query ? "read" : "write";
   const irreversible = typeof tag?.args?.irreversible === "boolean" ? tag.args.irreversible : tag ? null : !query;