@meantjs/consent 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 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.5.0 — 2026-10-30
+
+- Pins (spec §15.4, D-058): `evmConsent` and `eip712Consent` refuse a call or a signing request whose value at a
+  position a profile pins (`fixed`) is another address, before any text (new code `E_FIXED`). x402's Permit2 payment
+  needs it: its words hold only when the spender is x402's proxy. A pin whose value is not an address is
+  `E_RESOLVED_FORM`.
+- `erc7730Descriptor` writes a pinned position as a field with `visible: { mustMatch: [address] }`, which a wallet
+  hides and checks; a template that names one gets no `interpolatedIntent`, and `notes` says why.
+- x402 payments read with the new contract profiles of `@meantjs/profile` (`usdc`, `usdc-base-sepolia`,
+  `x402-exact-permit2`), and their grants pay the payee directly (`to`), so terms for one payee pass no payment to
+  another.
+- The ERC-7730 file of the `permit2` profile's messages lists its two new deployments (Base and Base Sepolia), so its
+  `descriptorHash` changed; a caller that passes the earlier `deployments` gets the earlier file.
+
 ## 0.4.0 — 2026-10-30
 
 - What a request grants (spec §5.3, D-056). `evmConsent`, `eip712Consent` and `generateConsent` also return `values`,

package/README.md

@@ -70,10 +70,10 @@ 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, 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. |
+| `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); an argument a profile pins (`fixed`) that holds another address is `E_FIXED`. `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 member a profile pins (`fixed`) that holds another address, such as x402's Permit2 payment with a spender other than x402's proxy (`E_FIXED`); 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. |
 | `values`, `grant` (both, `/evm`) | `evmConsent` and `eip712Consent` also return the decoded arguments or message by name (`values`), and what the call or signature grants (`grant`, below), or null. |
-| `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. |
+| `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`. A pinned position (`fixed`) is a field with `visible: { mustMatch: [address] }`, which a wallet hides and checks, and a template that names it has no `interpolatedIntent` (a note says why). 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. |
 
@@ -291,6 +291,9 @@ Untrusted third-party data lives in `test/upstream/icrc21/` (the standard, commi
 - A profile is a claim, not a proof (spec section 11 item 1). `provenance` tells the signer which profile wrote the words; `rawArguments: true` appends the decoded raw arguments for transfer, approve, admin and destroy.
 - Dynamic refs come from a single replica unless the caller certifies them (section 11 item 2). Resolve `decimals` and `symbol` through an update call or cross-check with `icrc1_metadata` before showing a transfer. Generation inside the canister avoids this.
 - The package has no I/O. Work is bounded: decoder budgets, field and element limits, message size.
+- A pin (`fixed`) protects only a consumer that reads it (section 11 item 11): x402's Permit2 payment pays its payee
+  only through x402's proxy, and a consumer that skips the tag shows its words for any spender. This package reads it
+  from 0.5.0; give a resolved form that holds pins to no older consumer.
 
 ## Not done
 
@@ -298,6 +301,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 witness messages and the signer check (spec §15.9 O9, O13),
+- EVM: payable functions in the consent text, EIP-712 witness messages other than x402's 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.4.0",
+  "version": "0.5.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": {
@@ -68,8 +68,8 @@
   },
   "dependencies": {
     "@candid-core/schema": "0.5.0",
-    "@meantjs/format": "0.4.0",
-    "@meantjs/profile": "0.4.0"
+    "@meantjs/format": "0.5.0",
+    "@meantjs/profile": "0.5.0"
   },
   "devDependencies": {
     "@dfinity/didc": "0.0.4",

package/src/erc7730.d.mts

@@ -21,6 +21,8 @@ export interface Erc7730Field {
   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>;
+  /** A position the profile pins (`fixed`): hidden, and a wallet refuses any other value (EIP-55 text). */
+  visible?: { mustMatch: string[] };
 }
 /** The fields of each element of an array whose elements carry their own token (`path: "details.[]"`); paths relative. */
 export interface Erc7730FieldGroup {

package/src/erc7730.mjs

@@ -109,12 +109,27 @@ function keysOf(method, relpath) {
 }
 const startsWith = (keys, prefix) => prefix.length <= keys.length && prefix.every((k, i) => keys[i] === k);
 
+/**
+ * ERC-7730 `visible` of a position a profile pins (`fixed`, spec section 15.4, D-058): `mustMatch` hides the field and
+ * makes a wallet refuse any other value, as `evmConsent` and `eip712Consent` do (E_FIXED). Empty for any other position.
+ */
+function pinOf(node, where) {
+  const fixed = tagArgs(node, "fixed");
+  if (fixed === undefined) return {};
+  try {
+    return { visible: { mustMatch: [readAddress(String(fixed.value))] } };
+  } catch (e) {
+    if (e instanceof AbiError) fail(CODES.RESOLVED_FORM, `${where}: fixed: ${e.message}`);
+    throw e;
+  }
+}
+
 /**
  * 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 field = { path, label, ...pinOf(node, where) };
   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.
@@ -225,6 +240,7 @@ function interpolated(template, method, ctx, where) {
       if (rp.error) return ctx.problem(where, `{${p.path}}: ${rp.error}`);
       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`);
+      if (tagArgs(rp.node, "fixed") !== undefined) return leftOut(`{${p.path}} is pinned (fixed), so its field is hidden (mustMatch); an ERC-7730 interpolation names only fields that are always shown`);
       out += `{${rp.steps.map((s) => s.key).join(".")}}`;
     }
   }

package/src/errors.mjs

@@ -24,6 +24,7 @@ export const CODES = Object.freeze({
   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)
+  FIXED: "E_FIXED", // a position a profile pins (`fixed`) holds another value: the profile does not describe the request (spec section 15.4)
   // 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.mjs

@@ -135,6 +135,31 @@ function withTokens(name, viewed, args, tokens) {
   return args.map((v, i) => box(viewed.args[i], v, [], []));
 }
 
+/**
+ * Every position a profile pins (`fixed`, spec section 15.4, D-058) holds its value: the profile describes the call or
+ * the message only with it, as x402's Permit2 message holds x402's proxy as its spender. Anything else is refused
+ * before any text (E_FIXED), since the words would be wrong for it.
+ */
+function checkFixed(name, viewed, args) {
+  const walk = (node, value, where) => {
+    if (node.candid === "record") return entriesOf(node.fields).forEach(([k, child]) => walk(child, value[k], `${where}.${k}`));
+    if (node.candid === "vec") return value.forEach((e) => walk(node.element, e, `${where}[]`));
+    const fixed = tagArgs(node, "fixed");
+    if (fixed === undefined) return;
+    let want;
+    try {
+      want = readAddress(String(fixed.value));
+    } catch (e) {
+      if (e instanceof AbiError) fail(CODES.RESOLVED_FORM, `${where}: fixed: ${e.message}`);
+      throw e;
+    }
+    if (typeof value !== "string" || value.toLowerCase() !== want.toLowerCase()) {
+      fail(CODES.FIXED, `${where} is ${String(value)}, but the profile describes ${name} only with ${want} there, so this request gets no text`);
+    }
+  };
+  args.forEach((v, i) => walk(viewed.args[i], v, `${name}(${i})`));
+}
+
 /**
  * The consent text of an EVM call.
  *
@@ -169,6 +194,7 @@ export function evmConsent({ resolved, calldata, to, chainId, refs = {}, tokens
   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})`)) };
+  if (viewed.args.length) checkFixed(name, viewed, [values]);
   const model = modelOf(resolved, name, viewed, viewed.args.length ? withTokens(name, viewed, [values], tokenTable(tokens)) : []);
   const grant = grantOf({ name, method: viewed, argValues: viewed.args.length ? [values] : [], called: target, diagnostics: model.diagnostics });
   const where = `${target}${chain === null ? "" : ` on chain ${chain}`}`;
@@ -348,6 +374,7 @@ export function eip712Consent({ resolved, typedData, chainId, refs = {}, tokens
     throw e;
   }
   const viewed = { ...message, args: message.args.map((n, i) => abiView(n, `${name}(${i})`)) };
+  checkFixed(name, viewed, [values]);
   const model = modelOf(resolved, name, viewed, withTokens(name, viewed, [values], tokenTable(tokens)));
   const grant = grantOf({ name, method: viewed, argValues: [values], called: contract, diagnostics: model.diagnostics });
   const where = `${contract} on chain ${chain}`;

package/src/index.d.mts

@@ -236,6 +236,7 @@ export const CODES: Readonly<{
   DEPLOYMENT: "E_DEPLOYMENT";
   DOMAIN: "E_DOMAIN";
   TYPE_HASH: "E_TYPE_HASH";
+  FIXED: "E_FIXED";
   UNSUPPORTED_TYPE: "E_UNSUPPORTED_TYPE";
   RESOLVED_FORM: "E_RESOLVED_FORM";
   TEMPLATE: "E_TEMPLATE";

package/src/render.mjs

@@ -2,7 +2,7 @@
 //
 // FieldsDisplayMessage (plain text, no formatting; times are UTC seconds, so the message does not depend on the
 // user's time zone):
-//   intent  = title + ": " + the rendered template      (no template: the title alone)
+//   intent  = title + ": " + the rendered template      (the title alone when the template renders empty or fell back)
 //   fields  = one (label, Value) row per placeholder; label = describe.label, else the field name
 //
 // GenericDisplayMessage (Markdown, the layout of the ICRC-21 examples: a `#` title, one paragraph, then