@meantjs/consent 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -2,6 +2,37 @@
 
 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`,
+  the decoded arguments or message, and `grant`: who may take tokens because of the request, which token, how many
+  and until when, read from the effect's `grant` (`{ kind, spender | to, token, amount: { units, unlimited }, ends }`),
+  or null. Addresses are EIP-55, accounts their ICRC-1 text, units a decimal string and ends exact seconds, never
+  rounded. A grant that cannot be read is null with a `W_GRANT` diagnostic, and the text is the same.
+  `generateConsent` takes `canisterId`, the ledger called, and reads the grant only then, so an ICRC-21 message is
+  unchanged.
+- `@meantjs/consent/terms`, new: terms the user confirms for one task, and the check of a request's grant against them
+  (spec §5.3, "Confirmed terms"; §11 item 10). `readTerms` reads an agent's terms in the wallet's values (a token by
+  its symbol, an app by its name, an amount never rounded, an end as a date, a length, hours or "never") or throws a
+  `TermsError` with a message for the agent; `termsText` writes them out exactly for the wallet's own screen;
+  `confirmTerms` freezes them with an id; `checkGrant` says whether a grant fits, and why not; `termsGate` keeps the
+  order (confirmed before the request is read, fixed after, one request, named by the id the wallet gives it). It runs
+  in browsers.
+
 ## 0.3.0 — 2026-10-29
 
 - `@meantjs/consent/evm`: `eip712Consent`, the consent text of an EIP-712 signing request (spec §15.9, D-055),

package/README.md

@@ -6,8 +6,8 @@ ICRC-21 consent messages, and the text an SNS proposal's validator returns, from
 npm install @meantjs/consent
 ```
 
-- **Runs on:** Node 22 or later and browsers for the main entry and the EVM subpaths (no Node built-in, no `Buffer`;
-  checked with esbuild). `@meantjs/consent/sns` hashes with `node:crypto` and is Node only.
+- **Runs on:** Node 22 or later and browsers for the main entry, the EVM subpaths and `./terms` (no Node built-in, no
+  `Buffer`; checked with esbuild). `@meantjs/consent/sns` hashes with `node:crypto` and is Node only.
 - **Module format:** ES modules only, with hand-written TypeScript declarations for every entry.
 - **Spec:** [Candid Profile v0](https://github.com/B3Pay/Meant/blob/main/profile/docs/profile-v0.md). **Licence:** Apache-2.0.
 - **Versions:** the five Candid Profile packages (`@meantjs/profile`, `/format`, `/consent`, `/tools`,
@@ -47,7 +47,7 @@ bundles it with esbuild for the browser platform). The three SNS rows below are
 | `snsValidatorRendering({ payload, resolved, method, refs, limits })` | An SNS generic-function validator as a function: payload bytes in, `{ Ok: text }` or `{ Err: text }` out (section below). Non-enumerable `diagnostics` and `provenance`, as above. |
 | `handleSnsValidatorCall(payload, context)` / `encodeValidatorResult` / `decodeValidatorResult` | The canister-side wrapper and the codec of `variant { Ok : text; Err : text }`. |
 | `verifySnsRendering({ payloadTextRendering, payload, resolved, targetCanisterId, method, refs })`, `parseGovernanceRendering(text)` | The reviewer's check of a stored proposal rendering; `SNS_RENDERING_RULES` names the rules. |
-| `generateConsent({ resolved, method, arg, refs, form, utcOffsetMinutes, rawArguments })` | One form without the ICRC-21 envelope; returns `{ message, zoneSensitive, diagnostics, provenance, model }`. |
+| `generateConsent({ resolved, method, arg, refs, form, utcOffsetMinutes, rawArguments, canisterId })` | One form without the ICRC-21 envelope; returns `{ message, zoneSensitive, values, grant, diagnostics, provenance, model }`. `values`: the decoded arguments. `grant`: what the call grants (section "Terms the user confirms"), read only when `canisterId` names the canister called, its token; else null. |
 | `decodeArguments(method, bytes, limits)` | Step 1 alone: argument bytes to the value tree. |
 | `parseTemplate`, `resolvePath`, `valuesAt`, `Renderer`, `renderFields`, `renderGeneric`, `codeSpan`, `escapeMarkdown`, `visible` | The parts. |
 
@@ -70,9 +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. |
-| `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. |
+| `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`. 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. |
 
@@ -96,6 +97,55 @@ independent implementation. **Fact** (ERC-7730): a wallet that finds no ticker f
 raw value instead with an 'Unknown token' warning"; this package would produce no message there, and a file cannot make
 a wallet refuse. The Rust version does not cover EVM.
 
+## Terms the user confirms (`src/terms.mjs`, `@meantjs/consent/terms`)
+
+Spec §5.3 ("What a call grants", "Confirmed terms") and §11 item 10, D-056. An agent that signs for a user should sign
+only what the user asked for. The consent functions above return each request's `grant`, read from the profile's
+`effect.grant`:
+
+```js
+{ kind: "approve", spender: "0x66a9893cC07D91D95644AEDD05D03f95e1dBA8Af", token: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
+  amount: { units: "500000000", unlimited: false }, ends: { at: "1796083199" } } // or { never: true }, or { now: true } for a transfer
+```
+
+Addresses are EIP-55, accounts their ICRC-1 text, a canister's token its canonical id, units a decimal string and ends
+exact seconds, never rounded. A Permit2 allowance whose expiration is 0 ends at `sigDeadline`, and an EIP-2612 or DAI
+permit never ends (their deadlines are the signature's). A batch, a request without a grant, or a grant that cannot be
+read is null; the last with a `W_GRANT` diagnostic, and the text is the same.
+
+The subpath compares a grant with terms the user confirmed for one task:
+
+| Function | Does |
+|---|---|
+| `readTerms(fields, wallet)` | The agent's terms (`token`, `spender` or `to`, `max_amount`, `expires_by`, as a tool takes them) in the wallet's values: a token by its symbol and an app by its name from the wallet's lists, never guessed; an address or account the user gave, checked; the most never rounded; the end as a date (its whole day in the user's zone), a length ("30 days", "1 month", calendar months), hours from now (an exact time) or "never". "unlimited" and "never" only as those words. Throws `TermsError` with a code and a message for the agent. `wallet`: `{ tokens, apps, now, utcOffsetMinutes }`, `now` in nanoseconds as a bigint. |
+| `termsText(terms)` | The terms in words, exactly, for the wallet's own screen: "Uniswap (0x66a9893cC07D91D95644AEDD05D03f95e1dBA8Af) may spend at most 500 USDC, until the end of 30 November 2026 (UTC)." "any amount (unlimited)" and "never ends" are written out. |
+| `confirmTerms(terms)` | Once the user confirmed exactly that text, never through a tool the agent can call: the terms frozen, with `id`, the SHA-256 of their canonical JSON. |
+| `checkGrant(confirmed, grant, wallet)` | `{ fits, reasons }`. A grant fits when its token and its spender or recipient are the terms', its amount is at most the most (unlimited only under unlimited terms; a grant of nothing under any), and it ends no later than the terms (never only under never; a transfer while the terms have not ended). A request that fits needs no second yes; one that does not is refused with the reasons, and the agent asks the user for new terms. A null grant is not covered by terms. |
+| `termsGate()` | The order, kept: `propose(terms)` returns the text to show, `confirm(shown)` takes the text the user confirmed, `read()` before the agent reads the request, `check(grant, wallet, requestId)`. The request cannot be read before the terms are confirmed, the terms cannot change once it is read, and they cover one request: `requestId` names it (`eip712Consent`'s `digest`, or the wallet's own id of a call), and another is refused even when it grants the same. Out of order is `E_TERMS_ORDER`. |
+
+```js
+import { checkGrant, readTerms, termsGate, termsText } from "@meantjs/consent/terms";
+import { eip712Consent } from "@meantjs/consent/evm";
+
+const wallet = {
+  tokens: { USDC: { address: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", decimals: 6 } },
+  apps: { Uniswap: "0x66a9893cC07D91D95644AEDD05D03f95e1dBA8Af" },
+  now: BigInt(Date.now()) * 1_000_000n,
+};
+const gate = termsGate();
+const shown = gate.propose(readTerms({ token: "USDC", spender: "Uniswap", max_amount: "500", expires_by: "2026-11-30" }, wallet));
+// the wallet shows `shown` on its own screen; when the user confirms it:
+gate.confirm(shown);
+gate.read(); // now the agent may read the request
+const { grant, digest } = eip712Consent({ resolved: permit2, typedData, chainId: 1, tokens });
+gate.check(grant, wallet, digest); // { fits: true, reasons: [] }, or { fits: false, reasons: ["the request is unlimited, the terms say at most 500 USDC"] }
+```
+
+The rules come from Meant's signing test, where the comparison in code held every time and the terms agents wrote from
+everyday words were the weak point (spec §11 item 10); hence the user's confirmation. The checks cover the eight
+requests of the proposal (Permit2 `PermitSingle` and `PermitTransferFrom`, EIP-2612, DAI, ERC-20 `approve` and
+`transfer`, ICRC-2 `icrc2_approve`, ICRC-1 `icrc1_transfer`) end to end, both traps, and the test's planted faults.
+
 ## SNS proposal validators (`src/sns.mjs`)
 
 The governance counterpart of ICRC-21. An SNS proposal that executes a generic nervous system function calls a dapp method with a payload. Apart from the proposer's own title and summary, the only description of that payload governance shows is the text the dapp's validator method returns. `snsValidatorRendering` is that validator, generated from the profile. Proposal for the spec text: `docs/proposals/w4-sns-validator-rendering.md`.
@@ -241,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
 
@@ -248,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.3.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": {
@@ -46,6 +46,10 @@
       "types": "./src/erc7730.d.mts",
       "default": "./src/erc7730.mjs"
     },
+    "./terms": {
+      "types": "./src/terms.d.mts",
+      "default": "./src/terms.mjs"
+    },
     "./package.json": "./package.json"
   },
   "files": [
@@ -64,8 +68,8 @@
   },
   "dependencies": {
     "@candid-core/schema": "0.5.0",
-    "@meantjs/format": "0.3.0",
-    "@meantjs/profile": "0.3.0"
+    "@meantjs/format": "0.5.0",
+    "@meantjs/profile": "0.5.0"
   },
   "devDependencies": {
     "@dfinity/didc": "0.0.4",

package/src/consent.mjs

@@ -2,8 +2,10 @@
 // `icrc21.mjs` wraps this into the ICRC-21 request/response shapes.
 
 import { Renderer } from "./display.mjs";
+import { canisterText, grantOf } from "./grant.mjs";
 import { buildModel } from "./model.mjs";
 import { renderFields, renderGeneric } from "./render.mjs";
+import { methodOf } from "./resolved.mjs";
 
 /**
  * @param {object} input
@@ -15,14 +17,20 @@ import { renderFields, renderGeneric } from "./render.mjs";
  * @param {number | null} [input.utcOffsetMinutes]  generic form only: show timestamps in this zone (default 0, UTC). The fields form is always UTC seconds
  * @param {boolean} [input.rawArguments]  append the decoded raw arguments (spec section 11 item 1)
  * @param {object} [input.limits]  decoder limits (maxBytes, maxDepth, maxElements)
- * @returns {{ form: "fields" | "generic", message: object, zoneSensitive: boolean, diagnostics: object[], provenance: object, model: object }}
+ * @param {string} [input.canisterId]  the canister called: the token of a grant (spec section 5.3, D-056). Without it
+ *   nothing is read: `grant` is null and no diagnostic says so, since a caller that does not name the canister is not
+ *   asking what the call grants (an ICRC-21 message, for one)
+ * @returns {{ form: "fields" | "generic", message: object, zoneSensitive: boolean, values: unknown[], grant: object | null, diagnostics: object[], provenance: object, model: object }}
  *   `message` is `{ FieldsDisplayMessage: { intent, fields } }` or `{ GenericDisplayMessage: string }` (ICRC-21 shapes,
- *   integers as bigint). `zoneSensitive` is true when a timestamp was shown in the requested zone.
+ *   integers as bigint). `zoneSensitive` is true when a timestamp was shown in the requested zone. `values` are the
+ *   decoded arguments as `decodeArguments` gives them, and `grant` what the call grants (`grant.mjs`), or null.
  */
-export function generateConsent({ resolved, method, arg, refs = {}, form = "generic", utcOffsetMinutes = null, rawArguments = false, limits }) {
+export function generateConsent({ resolved, method, arg, refs = {}, form = "generic", utcOffsetMinutes = null, rawArguments = false, limits, canisterId }) {
+  const called = canisterId === undefined ? undefined : canisterText(canisterId);
   const model = buildModel({ resolved, method, arg, limits });
   const diagnostics = model.diagnostics;
-  const done = (rest) => ({ ...rest, diagnostics: dedupe(diagnostics), provenance: model.provenance, model });
+  const grant = called === undefined ? null : grantOf({ name: method, method: methodOf(resolved, method), argValues: model.argValues, called, diagnostics });
+  const done = (rest) => ({ ...rest, values: model.argValues, grant, diagnostics: dedupe(diagnostics), provenance: model.provenance, model });
   if (form === "fields") {
     const renderer = new Renderer({ refs, utcOffsetMinutes: null, diagnostics });
     const { intent, fields } = renderFields(model, renderer, { rawArguments });

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.d.mts

@@ -1,7 +1,7 @@
 // Types for @meantjs/consent/evm: the consent text of an EVM call (spec section 15, D-054). Hand-written; the source is
 // src/evm.mjs. scripts/types.test.mjs keeps the declared names equal to the runtime exports.
 import type { AbiLimits, AbiValue } from "@meantjs/profile/evm";
-import type { ConsentDiagnostic, Model, Provenance, ResolvedForm } from "./index.mjs";
+import type { ConsentDiagnostic, Grant, Model, Provenance, ResolvedForm } from "./index.mjs";
 
 /** An EVM contract's resolved form: `chain: "evm"`, and each method with its selector and named signature. */
 export type EvmResolvedForm = ResolvedForm & { chain: "evm" };
@@ -50,6 +50,10 @@ export function evmConsent(input: EvmConsentInput): {
   /** The contract, in its EIP-55 form. */
   to: string;
   chainId: string | null;
+  /** The decoded arguments by parameter name, as `decodeCalldata` gives them. */
+  values: Record<string, AbiValue>;
+  /** What the call grants (its token is the contract called, unless the amount's tag names a field), or null; a W_GRANT diagnostic says why one cannot be read. */
+  grant: Grant | null;
   diagnostics: ConsentDiagnostic[];
   provenance: Provenance;
   model: Model;
@@ -100,6 +104,10 @@ export function eip712Consent(input: Eip712ConsentInput): {
   /** The verifying contract, in its EIP-55 form. */
   verifyingContract: string;
   chainId: string;
+  /** The message's values by member name, as read from the typed data: integers as decimal strings, addresses in EIP-55 form. */
+  values: Record<string, AbiValue>;
+  /** What the signature grants (its token is the verifying contract, unless the amount's tag names a member), or null; a W_GRANT diagnostic says why one cannot be read. */
+  grant: Grant | null;
   diagnostics: ConsentDiagnostic[];
   provenance: Provenance;
   model: Model;

package/src/evm.mjs

@@ -22,6 +22,7 @@
 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 { grantOf } from "./grant.mjs";
 import { modelOf } from "./model.mjs";
 import { resolvePath } from "./paths.mjs";
 import { renderGeneric, renderPlain } from "./render.mjs";
@@ -134,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.
  *
@@ -149,7 +175,9 @@ function withTokens(name, viewed, args, tokens) {
  * @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 }}
+ * @returns {{ form: string, message: string | { intent: string, fields: Array<[string, string]> }, method: string, selector: string, to: string, chainId: string | null, values: Record<string, unknown>, grant: object | null, diagnostics: object[], provenance: object, model: object }}
+ *   `values` are the decoded arguments as `decodeCalldata` gives them, and `grant` what the call grants (spec section
+ *   5.3, D-056; its token is the contract called unless the amount's tag names a field), or null.
  */
 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)}`);
@@ -166,9 +194,11 @@ 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}`}`;
-  const done = (rest) => ({ ...rest, method: name, selector, to: target, chainId: chain, diagnostics: model.diagnostics, provenance: model.provenance, model });
+  const done = (rest) => ({ ...rest, method: name, selector, to: target, chainId: chain, values, grant, 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]);
@@ -312,6 +342,9 @@ function checkDomain(resolved, domain) {
  * @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]
+ * @returns the text, `primaryType`, `typeHash`, `digest`, `verifyingContract`, `chainId`, `values` (the message as read
+ *   from the typed data, by member name), `grant` (what the signature grants, spec section 5.3, D-056; its token is
+ *   the verifying contract unless the amount's tag names a field), or null, `diagnostics`, `provenance` and `model`
  */
 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)}`);
@@ -341,9 +374,11 @@ 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}`;
-  const done = (rest) => ({ ...rest, primaryType: name, typeHash, digest, verifyingContract: contract, chainId: chain, diagnostics: model.diagnostics, provenance: model.provenance, model });
+  const done = (rest) => ({ ...rest, primaryType: name, typeHash, digest, verifyingContract: contract, chainId: chain, values, grant, 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]);

package/src/grant.mjs

@@ -0,0 +1,140 @@
+// What a call or a signature grants (docs/profile-v0.md section 5.3, D-056): who may take tokens because of it, which
+// token, how many and until when, read from its effect's `grant` and its decoded values. A wallet compares it with the
+// terms the user confirmed (`@meantjs/consent/terms`).
+//
+// A grant that cannot be read is no grant: `null`, with a W_GRANT diagnostic. The request then needs its confirmation,
+// as any request without a grant does, and the consent text is the same either way.
+
+import { displayAccount, principalFromText, principalToText } from "@meantjs/format";
+import { CODES, fail } from "./errors.mjs";
+import { callTag, tagArgs } from "./resolved.mjs";
+import { resolvePath, valuesAt } from "./paths.mjs";
+
+const isObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+const NATURAL = /^(0|[1-9][0-9]*)$/;
+const INTEGER = /^-?(0|[1-9][0-9]*)$/;
+/** Nanoseconds per unit of a `timestamp` tag (spec section 5.3); every grant end is compared in nanoseconds, exactly. */
+const NS = { s: 1_000_000_000n, ms: 1_000_000n, us: 1_000n, ns: 1n };
+
+/** Nanoseconds as exact seconds: a decimal string with a fraction only when there is one, never rounded. */
+export function secondsText(ns) {
+  const sign = ns < 0n ? "-" : "";
+  const a = ns < 0n ? -ns : ns;
+  const frac = (a % NS.s).toString().padStart(9, "0").replace(/0+$/, "");
+  return `${sign}${a / NS.s}${frac ? `.${frac}` : ""}`;
+}
+
+/** The canonical text of a canister id; anything else is E_REQUEST. */
+export function canisterText(id) {
+  try {
+    return principalToText(principalFromText(id));
+  } catch {
+    fail(CODES.REQUEST, `canisterId must be a principal's text, got ${JSON.stringify(String(id))}`);
+  }
+}
+
+class Skip extends Error {}
+
+/**
+ * @param {object} input
+ * @param {string} input.name  the method or message, for the diagnostic
+ * @param {object} input.method  its resolved-form entry (an EVM one as abiView reads it)
+ * @param {unknown[]} input.argValues  its decoded arguments, before any amount is boxed with its token
+ * @param {string | undefined} input.called  the contract or canister the call is for: the token, unless the amount's
+ *   tag names a field that holds it (spec section 15.9)
+ * @param {object[]} input.diagnostics  where W_GRANT goes
+ * @returns {null | { kind: "transfer" | "approve", spender?: string, to?: string, token: string,
+ *   amount: { units: string | null, unlimited: boolean }, ends: { at: string } | { never: true } | { now: true } }}
+ */
+export function grantOf({ name, method, argValues, called, diagnostics }) {
+  const effect = callTag(method, argValues, "effect");
+  const grant = effect?.args?.grant;
+  if (grant === undefined) return null;
+  try {
+    return read(method, argValues, effect, grant, called);
+  } catch (e) {
+    if (!(e instanceof Skip)) throw e;
+    diagnostics.push({ code: "W_GRANT", at: name, message: `${e.message}; the request has no grant, so terms the user confirmed cannot cover it` });
+    return null;
+  }
+}
+
+function read(method, argValues, effect, grant, called) {
+  const skip = (why) => {
+    throw new Skip(why);
+  };
+  if (effect !== method.tags?.effect) skip("a grant on the effect of a case is not read in this version (D-056)");
+  const { kind } = effect.args;
+  if (kind !== "transfer" && kind !== "approve") skip(`a grant goes with effect kind transfer or approve, not ${String(kind)}`);
+  if (!isObject(grant) || (grant.spender === undefined) === (grant.to === undefined)) skip("the grant names neither or both of spender and to");
+
+  /** The one value at a grant position: no [] and no case of a variant on the way, so a call holds it once at most. */
+  const at = (what, path, mayBeAbsent = false) => {
+    if (typeof path !== "string") skip(`grant ${what} is not a path`);
+    const rp = resolvePath(method, path);
+    if (rp.error) skip(`grant ${what} ${JSON.stringify(path)}: ${rp.error}`);
+    if (rp.steps.some((s) => s.kind !== "field")) skip(`grant ${what} ${JSON.stringify(path)} steps into [] or a case of a variant`);
+    const values = valuesAt(rp, argValues);
+    if (values.length === 0 && !mayBeAbsent) skip(`grant ${what} ${JSON.stringify(path)} is absent from this call`);
+    return { node: rp.node, value: values[0] };
+  };
+
+  const who = grant.spender !== undefined ? "spender" : "to";
+  const party = at(who, grant[who]);
+  let address;
+  if (party.node.abi === "address" && typeof party.value === "string") address = party.value; // EIP-55, as decoded
+  else if (tagArgs(party.node, "account") !== undefined && isObject(party.value)) {
+    try {
+      address = displayAccount(party.value);
+    } catch (e) {
+      skip(`grant ${who}: ${e.message}`);
+    }
+  } else skip(`grant ${who} ${JSON.stringify(grant[who])} is neither an address nor an account`);
+
+  const amt = at("amount", grant.amount);
+  const tag = tagArgs(amt.node, "amount");
+  let amount;
+  if ((amt.node.abi ?? amt.node.candid) === "bool" && typeof amt.value === "boolean") {
+    amount = amt.value ? { units: null, unlimited: true } : { units: "0", unlimited: false }; // DAI's allowed (spec 15.9)
+  } else {
+    if (tag === undefined || typeof amt.value !== "string" || !NATURAL.test(amt.value)) skip(`grant amount ${JSON.stringify(grant.amount)} is neither an amount nor a bool`);
+    if (tag.threshold !== undefined && (typeof tag.threshold !== "string" || !NATURAL.test(tag.threshold))) skip("the amount tag's threshold is not a decimal string");
+    amount = { units: amt.value, unlimited: tag.threshold !== undefined && BigInt(amt.value) >= BigInt(tag.threshold) };
+  }
+
+  let token;
+  if (tag?.token !== undefined) {
+    const t = at("amount token", tag.token);
+    if (t.node.abi !== "address" || typeof t.value !== "string") skip(`the amount's token ${JSON.stringify(tag.token)} is not an address`);
+    token = t.value;
+  } else if (typeof called === "string") token = called;
+  else skip("the canister the call is for was not given (canisterId), so its token is not known");
+
+  let ends;
+  if (grant.ends === undefined) ends = kind === "approve" ? { never: true } : { now: true };
+  else {
+    if (!Array.isArray(grant.ends) || grant.ends.length === 0) skip("grant ends is not a list of paths");
+    let latest = null;
+    let never = false;
+    for (const path of grant.ends) {
+      const end = at("ends", path, true);
+      if (end.value === undefined) { // an optional end left out: the grant never ends (spec 5.3)
+        never = true;
+        continue;
+      }
+      const ts = tagArgs(end.node, "timestamp");
+      if (ts === undefined || !Object.hasOwn(NS, ts.unit) || (ts.epoch ?? "unix") !== "unix" || typeof end.value !== "string" || !INTEGER.test(end.value)) {
+        skip(`grant ends ${JSON.stringify(path)} is not a unix timestamp`);
+      }
+      if (ts.threshold !== undefined && (typeof ts.threshold !== "string" || !NATURAL.test(ts.threshold))) skip(`the timestamp tag of ${JSON.stringify(path)} has a threshold that is not a decimal string`);
+      if (ts.threshold !== undefined && BigInt(end.value) >= BigInt(ts.threshold)) { // at its threshold: never (spec 5.3)
+        never = true;
+        continue;
+      }
+      const ns = BigInt(end.value) * NS[ts.unit]; // a label is how a value is shown; here it is the time it is
+      if (latest === null || ns > latest) latest = ns;
+    }
+    ends = never ? { never: true } : { at: secondsText(latest) };
+  }
+  return { kind, [who]: address, token, amount, ends };
+}

package/src/index.d.mts

@@ -126,6 +126,24 @@ export interface Model {
   [key: string]: unknown;
 }
 
+/**
+ * What a call or a signature grants (spec section 5.3, D-056): who may take tokens because of it, which token, how many
+ * and until when, read from its effect's `grant`. Compare it with terms the user confirmed (`@meantjs/consent/terms`).
+ */
+export interface Grant {
+  kind: "transfer" | "approve";
+  /** Who may take the tokens: an EIP-55 address, or an account in its ICRC-1 text. Exactly one of `spender` and `to`. */
+  spender?: string;
+  /** Who is paid directly: an EIP-55 address, or an account in its ICRC-1 text. */
+  to?: string;
+  /** The token: an EIP-55 address, or a canister id in its canonical text. */
+  token: string;
+  /** Base units as a decimal string; `null` when unlimited without a count (DAI's `allowed: true`). A grant of nothing is `"0"`. */
+  amount: { units: string | null; unlimited: boolean };
+  /** `at`: exact seconds since the Unix epoch as a decimal string, never rounded ("1767225600.123456789"). `now`: a transfer, made when it is sent. */
+  ends: { at: string } | { never: true } | { now: true };
+}
+
 export interface GenerateConsentInput {
   resolved: ResolvedForm;
   method: string;
@@ -138,12 +156,21 @@ export interface GenerateConsentInput {
   utcOffsetMinutes?: number | null;
   rawArguments?: boolean;
   limits?: DecodeLimits;
+  /**
+   * The canister called, the token of a grant. Without it nothing asks what the call grants: `grant` is null, with no
+   * diagnostic. Any spelling of a principal; anything else is E_REQUEST.
+   */
+  canisterId?: string;
 }
 /** One form without the ICRC-21 envelope. `zoneSensitive` is true when a timestamp was shown in the requested zone. */
 export function generateConsent(input: GenerateConsentInput): {
   form: "fields" | "generic";
   message: Icrc21ConsentMessage;
   zoneSensitive: boolean;
+  /** The decoded arguments, one value tree per argument, as `decodeArguments` gives them. */
+  values: unknown[];
+  /** What the call grants, or null: no `canisterId`, no grant in its effect, or one that cannot be read (a W_GRANT diagnostic says why). */
+  grant: Grant | null;
   diagnostics: ConsentDiagnostic[];
   provenance: Provenance;
   model: Model;
@@ -209,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