@meantjs/profile 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -2,6 +2,44 @@
 
 The five Candid Profile library packages (`@meantjs/profile`, `/format`, `/consent`, `/tools`, `/reconcile`) release together under one version and pin each other exactly; a version appears here even when this package did not change. Release steps: `docs/releasing.md` in the repository.
 
+## 0.3.0 — 2026-10-29
+
+- EIP-712 typed messages, experimental (spec §15.9, D-055). A contract profile or EVM pack may carry
+  `binds.eip712: { domain?, types }`, and a contract profile may have it instead of `binds.abi`. A message is a type
+  the same document tags with `intent`, addressed like a function (`PermitSingle(0).details.amount`); the resolved form
+  lists messages under a new `messages` map (`encode_type`, `type_hash`, `tags`, `args`) and the bound domain as
+  `profiles[].eip712_domain`. Without types, the resolved form and the interface id are unchanged.
+- `amount` takes `token`, a relative path to the `address` field that names its token (EVM only); `timestamp` takes
+  `threshold` with `message`, and `labels` (display only). New errors `E_EIP712` and `E_TOKEN_PATH`.
+- `@meantjs/profile/evm` exports `encodeType`, `eip712TypeHash` and `parseEip712Types`; `abiInterfaceId` takes the
+  struct types as a second argument.
+- New standard files: the `erc2612` pack (in `STANDARD_PACKS` and `loadPacks()`), and the `permit2` and `dai-permit`
+  contract profiles, shipped beside the packs (`@meantjs/profile/packs/permit2.profile.json`); `loadPacks()` returns
+  packs only, as before.
+
+## 0.2.0 — 2026-10-28
+
+- `intent` and `effect` may sit on a case of a variant in a method's arguments, such as `propose(0).Transfer`
+  (spec §5.2, D-053). The resolved form carries them on the case node. New errors: `E_CASE_OVERLAP` (two tagged cases
+  of one method that one call can hold both of) and `E_CASE_EFFECT` (a case effect that needs confirmation, or is
+  irreversible, under a method effect that does not or is not); `E_TAG_TARGET` for a case tag at any other value
+  address; `E_TEMPLATE_PATH` for a case template's placeholder through another case of a variant on its path. A
+  profile that 0.1.0 accepts resolves as before.
+- EVM contracts, experimental (spec §15, D-054). `kind: "contract"` profiles carry an ABI (`binds.abi`, human-readable
+  fragments or JSON entries) and optional `binds.deployments`; EVM packs carry `binds.abi` and apply by selector, with
+  their addresses and placeholders rewritten to the contract's parameter names. `resolveService({ abi })` and
+  `candid-profile resolve --abi <file>` resolve a contract; its resolved form has `"chain": "evm"`, `abi` nodes, and
+  each method's `selector`, `signature` and `state_mutability`. A new standard pack, `erc20`; `loadPacks()` and
+  `STANDARD_PACKS` now list it first, and a Candid service skips it. New errors: `E_ABI`, `E_CHAIN`,
+  `E_ADDRESS_CHECKSUM`; on a contract, `E_TAG_TARGET` for `idempotency`, `outcome`, `list`, `names` and `named`,
+  `E_TAG_NOT_APPLICABLE` for `account` and `subaccount`, and `E_TEMPLATE` for `[ ]` segments.
+- `@meantjs/profile/evm`, browser-safe and without dependencies: Keccak-256, ABI fragments (`parseAbi`,
+  `parseSignature`, canonical text, selectors, `abiInterfaceId`), a strict ABI codec (`encodeParams`, `encodeCall`,
+  `decodeParams`, which refuses anything but the canonical encoding), EIP-55 addresses (`toChecksumAddress`,
+  `readAddress`) and EIP-712 digests (`typedDataDigest`).
+- The schema: `amount` takes `threshold` and `message` (display only: a value at or above the threshold shows as the
+  message and the symbol, "Unlimited USDC").
+
 ## 0.1.0 — 2026-10-28
 
 First published version.

package/README.md

@@ -10,7 +10,8 @@ npm install @meantjs/profile
 
 - **Runs on:** Node 22 or later for the main entry and the `candid-profile` CLI. `@meantjs/profile/browser` is for
   browser bundles (checked with esbuild, and in Chromium under a CSP without `'unsafe-eval'`; the cli's wasm needs
-  `'wasm-unsafe-eval'`, below). `@meantjs/profile/address` has no dependency and runs anywhere.
+  `'wasm-unsafe-eval'`, below). `@meantjs/profile/address` and `@meantjs/profile/evm` have no dependency and run
+  anywhere.
 - **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`,
@@ -21,7 +22,7 @@ npm install @meantjs/profile
 import { createSchemaValidator, resolveService, loadPacks, validateProfile } from "@meantjs/profile";
 
 const validateSchema = await createSchemaValidator();                 // the schema this package ships
-const packs = await loadPacks();                                      // the standard packs it ships (ICRC-1, ICRC-2)
+const packs = await loadPacks();                                      // the standard packs it ships (ERC-20, ICRC-1, ICRC-2)
 const r = await resolveService({
   did: await readFile("ledger.did", "utf8"),
   validateSchema,
@@ -163,10 +164,46 @@ const r = await resolveService({ did: serviceText, profiles: served.ok ? [{ doc:
   serves, so a profile for another interface is `rebound` or `stale` as any other.
 - Tests: `test/served.test.mjs`; end to end on PocketIC in `packages/kit/pocketic/`.
 
+## EVM contracts (experimental, spec section 15, D-054 and D-055)
+
+A third input, `abi`: an EVM contract's ABI as human-readable fragments or JSON ABI entries. The resolver reads it as
+the graph a `.did` compiles to (a function is a method, its parameters one record at argument 0, a tuple a record in
+ABI order), so addresses, tags, layers and the resolved form work unchanged; the resolved form says `"chain": "evm"`,
+its nodes carry `abi` instead of `candid`, and each method has `selector`, `signature` and `state_mutability`.
+
+```js
+const r = await resolveService({ abi: ["function transfer(address dst, uint256 wad) returns (bool)", …], validateSchema, packs: (await loadPacks()).map(({ doc }) => ({ doc })) });
+r.resolved.methods.transfer.tags.intent.args.template; // "Send {wad} to {dst}": the erc20 pack's, in this contract's names
+```
+
+- **Contract profiles** (`kind: "contract"`) carry their ABI in `binds.abi` and the contracts they describe in
+  `binds.deployments` (EIP-55 checked: `E_ADDRESS_CHECKSUM`). **EVM packs** carry `binds.abi` and apply to a contract
+  that has every one of their functions, by selector, output types and kind of call (no subtyping); their addresses
+  and placeholders are rewritten to the contract's parameter names by position. A pack or profile for the other kind
+  of interface is `E_CHAIN` when given, and skipped in a pack search, so `loadPacks()` serves both kinds.
+- **EIP-712 messages** (spec §15.9, D-055): `binds.eip712: { domain?, types }` in a contract profile (with or without
+  `binds.abi`) or an EVM pack. A type the same document tags with `intent` is a message, addressed like a function
+  (`PermitSingle(0).details.amount`) and listed under the resolved form's `messages` with its `encode_type` and
+  `type_hash`. `amount.token` names an amount's token by an `address` field (`E_TOKEN_PATH` otherwise). Bad types, a
+  message named like a function and two meanings for one type name are `E_EIP712`. Standard files: the `erc2612`
+  pack, and the `permit2` and `dai-permit` contract profiles shipped beside the packs
+  (`@meantjs/profile/packs/permit2.profile.json`); `loadPacks()` returns the packs only.
+- **Refused for now:** overloaded function names and unreadable fragments (`E_ABI`); `idempotency`, `outcome`, `list`,
+  `names` and `named` on a contract (`E_TAG_TARGET`); `account` and `subaccount` (`E_TAG_NOT_APPLICABLE`); `[ ]`
+  template segments (`E_TEMPLATE`).
+- **`@meantjs/profile/evm`** is the toolkit underneath, browser-safe and without dependencies: `keccak256`, `parseAbi`,
+  `parseSignature`, `canonicalFragment`, `selectorOf`, `abiInterfaceId`, a strict codec (`encodeParams`, `encodeCall`,
+  `decodeParams`: a value read from anything but its canonical encoding is refused), `toChecksumAddress`,
+  `readAddress`, `typedDataDigest` (EIP-712), `encodeType`, `eip712TypeHash` and `parseEip712Types`.
+  `test/evm.test.mjs` checks Keccak against an independent implementation (and the block boundary), the ERC-20
+  selectors, the ERC-8176 schema UID, EIP-55's examples and EIP-712's Mail example; `test/eip712.test.mjs` the type
+  hashes of the standard messages (DAI's equals `dai.sol`'s constant).
+
 ## CLI
 
 ```sh
 node packages/resolver/bin/candid-profile.mjs resolve <service.did> [--profile p.json ...] [--packs] [--packs-dir dir] [--verbose] [--quiet] > resolved.json
+node packages/resolver/bin/candid-profile.mjs resolve --abi contract.abi.json [--profile p.json ...] [--packs]   # an EVM contract (section 15)
 # after `npm ci` the bin is also linked: npx candid-profile resolve ...
 ```
 

package/data/packs/dai-permit.profile.json

@@ -0,0 +1,113 @@
+{
+  "format": "candid-profile",
+  "format_version": 0,
+  "kind": "contract",
+  "name": "dai-permit",
+  "origin": "third_party",
+  "language": "en",
+  "description": "DAI's permit on Ethereum mainnet (spec section 15.9, experimental), older than EIP-2612 and different from it: `allowed` sets the allowance to all of the holder's DAI (true, uint256 max) or to none (false), and `expiry` 0 means the signature never expires (MakerDAO dss, src/dai.sol). Only the message is described; DAI's functions are ERC-20's and the erc20 pack covers them.",
+  "binds": {
+    "eip712": {
+      "domain": {
+        "name": "Dai Stablecoin",
+        "version": "1"
+      },
+      "types": {
+        "Permit": [
+          {
+            "name": "holder",
+            "type": "address"
+          },
+          {
+            "name": "spender",
+            "type": "address"
+          },
+          {
+            "name": "nonce",
+            "type": "uint256"
+          },
+          {
+            "name": "expiry",
+            "type": "uint256"
+          },
+          {
+            "name": "allowed",
+            "type": "bool"
+          }
+        ]
+      }
+    },
+    "deployments": [
+      {
+        "chain_id": 1,
+        "address": "0x6B175474E89094C44Da98b954EedeAC495271d0F"
+      }
+    ]
+  },
+  "annotations": [
+    {
+      "at": "Permit",
+      "tag": "intent",
+      "args": {
+        "title": "Permit DAI spending",
+        "template": "Set the DAI allowance {holder} gives {spender} to all of it if allowed is true, to none if false (allowed: {allowed}). Signature expires: {expiry}."
+      }
+    },
+    {
+      "at": "Permit",
+      "tag": "effect",
+      "args": {
+        "kind": "approve",
+        "irreversible": false
+      }
+    },
+    {
+      "at": "Permit(0).holder",
+      "tag": "describe",
+      "args": {
+        "label": "Holder"
+      }
+    },
+    {
+      "at": "Permit(0).spender",
+      "tag": "describe",
+      "args": {
+        "label": "Spender"
+      }
+    },
+    {
+      "at": "Permit(0).allowed",
+      "tag": "describe",
+      "args": {
+        "label": "Allowed (true: all, false: none)"
+      }
+    },
+    {
+      "at": "Permit(0).expiry",
+      "tag": "timestamp",
+      "args": {
+        "unit": "s",
+        "epoch": "unix",
+        "threshold": "115792089237316195423570985008687907853269984665640564039457584007913129639935",
+        "message": "Never",
+        "labels": {
+          "0": "Never"
+        }
+      }
+    },
+    {
+      "at": "Permit(0).expiry",
+      "tag": "describe",
+      "args": {
+        "label": "Signature expires"
+      }
+    },
+    {
+      "at": "Permit(0).nonce",
+      "tag": "describe",
+      "args": {
+        "label": "Nonce"
+      }
+    }
+  ]
+}

package/data/packs/erc20.profile.json

@@ -0,0 +1,221 @@
+{
+  "format": "candid-profile",
+  "format_version": 0,
+  "kind": "pack",
+  "name": "erc20",
+  "origin": "pack",
+  "language": "en",
+  "description": "Standard pack for EIP-20 tokens on EVM chains (spec section 15, experimental). Applies to any contract that has every function of `binds.abi` with the same selector, outputs and kind of call; parameter names may differ (they are matched by position). `name()` is left out: no annotation reads it and EIP-20 makes it optional. A token without `decimals()` or `symbol()` matches no pack and needs a contract profile with literal values.",
+  "binds": {
+    "standard": "ERC-20",
+    "spec_url": "https://eips.ethereum.org/EIPS/eip-20",
+    "abi": [
+      "function symbol() view returns (string)",
+      "function decimals() view returns (uint8)",
+      "function balanceOf(address owner) view returns (uint256)",
+      "function allowance(address owner, address spender) view returns (uint256)",
+      "function transfer(address to, uint256 value) returns (bool)",
+      "function approve(address spender, uint256 value) returns (bool)",
+      "function transferFrom(address from, address to, uint256 value) returns (bool)"
+    ]
+  },
+  "annotations": [
+    {
+      "at": "transfer",
+      "tag": "intent",
+      "args": {
+        "title": "Send tokens",
+        "template": "Send {value} to {to}"
+      }
+    },
+    {
+      "at": "transfer",
+      "tag": "effect",
+      "args": {
+        "kind": "transfer",
+        "irreversible": true
+      }
+    },
+    {
+      "at": "transfer(0).value",
+      "tag": "amount",
+      "args": {
+        "decimals": {
+          "from": "query:decimals"
+        },
+        "symbol": {
+          "from": "query:symbol"
+        }
+      }
+    },
+    {
+      "at": "transfer(0).value",
+      "tag": "describe",
+      "args": {
+        "label": "Amount"
+      }
+    },
+    {
+      "at": "transfer(0).to",
+      "tag": "describe",
+      "args": {
+        "label": "Recipient"
+      }
+    },
+    {
+      "at": "approve",
+      "tag": "intent",
+      "args": {
+        "title": "Approve spending",
+        "template": "Set {spender}'s allowance to {value}, replacing any existing allowance"
+      }
+    },
+    {
+      "at": "approve",
+      "tag": "effect",
+      "args": {
+        "kind": "approve",
+        "irreversible": false
+      }
+    },
+    {
+      "at": "approve(0).spender",
+      "tag": "describe",
+      "args": {
+        "label": "Spender"
+      }
+    },
+    {
+      "at": "approve(0).value",
+      "tag": "amount",
+      "args": {
+        "decimals": {
+          "from": "query:decimals"
+        },
+        "symbol": {
+          "from": "query:symbol"
+        },
+        "threshold": "115792089237316195423570985008687907853269984665640564039457584007913129639935",
+        "message": "Unlimited"
+      }
+    },
+    {
+      "at": "approve(0).value",
+      "tag": "describe",
+      "args": {
+        "label": "Allowance",
+        "help": "Maximum the spender may transfer. An approval replaces the previous allowance; it does not add to it."
+      }
+    },
+    {
+      "at": "transferFrom",
+      "tag": "intent",
+      "args": {
+        "title": "Transfer using allowance",
+        "template": "Move {value} from {from} to {to} using an allowance"
+      }
+    },
+    {
+      "at": "transferFrom",
+      "tag": "effect",
+      "args": {
+        "kind": "transfer",
+        "irreversible": true
+      }
+    },
+    {
+      "at": "transferFrom(0).from",
+      "tag": "describe",
+      "args": {
+        "label": "From"
+      }
+    },
+    {
+      "at": "transferFrom(0).to",
+      "tag": "describe",
+      "args": {
+        "label": "Recipient"
+      }
+    },
+    {
+      "at": "transferFrom(0).value",
+      "tag": "amount",
+      "args": {
+        "decimals": {
+          "from": "query:decimals"
+        },
+        "symbol": {
+          "from": "query:symbol"
+        }
+      }
+    },
+    {
+      "at": "transferFrom(0).value",
+      "tag": "describe",
+      "args": {
+        "label": "Amount"
+      }
+    },
+    {
+      "at": "balanceOf",
+      "tag": "describe",
+      "args": {
+        "label": "Balance of an address"
+      }
+    },
+    {
+      "at": "balanceOf(0).owner",
+      "tag": "describe",
+      "args": {
+        "label": "Owner"
+      }
+    },
+    {
+      "at": "balanceOf->(0)",
+      "tag": "amount",
+      "args": {
+        "decimals": {
+          "from": "query:decimals"
+        },
+        "symbol": {
+          "from": "query:symbol"
+        }
+      }
+    },
+    {
+      "at": "allowance",
+      "tag": "describe",
+      "args": {
+        "label": "Allowance of a spender"
+      }
+    },
+    {
+      "at": "allowance(0).owner",
+      "tag": "describe",
+      "args": {
+        "label": "Owner"
+      }
+    },
+    {
+      "at": "allowance(0).spender",
+      "tag": "describe",
+      "args": {
+        "label": "Spender"
+      }
+    },
+    {
+      "at": "allowance->(0)",
+      "tag": "amount",
+      "args": {
+        "decimals": {
+          "from": "query:decimals"
+        },
+        "symbol": {
+          "from": "query:symbol"
+        },
+        "threshold": "115792089237316195423570985008687907853269984665640564039457584007913129639935",
+        "message": "Unlimited"
+      }
+    }
+  ]
+}

package/data/packs/erc2612.profile.json

@@ -0,0 +1,196 @@
+{
+  "format": "candid-profile",
+  "format_version": 0,
+  "kind": "pack",
+  "name": "erc2612",
+  "origin": "pack",
+  "language": "en",
+  "description": "Standard pack for EIP-2612 permits on EVM chains (spec section 15.9, experimental): the signed `Permit` message that sets an ERC-20 allowance, and the `permit` function that submits one. Applies to a contract that has every function of `binds.abi` with the same selector, outputs and kind of call, `decimals()` and `symbol()` included, since the amounts read them. A signing request matches the `Permit` message by its EIP-712 type hash, and its verifying contract is the token, so `query:` refs are calls to that token. The domain's name and version are each token's own, so the pack names neither.",
+  "binds": {
+    "standard": "ERC-2612",
+    "spec_url": "https://eips.ethereum.org/EIPS/eip-2612",
+    "abi": [
+      "function permit(address owner, address spender, uint256 value, uint256 deadline, uint8 v, bytes32 r, bytes32 s)",
+      "function nonces(address owner) view returns (uint256)",
+      "function DOMAIN_SEPARATOR() view returns (bytes32)",
+      "function decimals() view returns (uint8)",
+      "function symbol() view returns (string)"
+    ],
+    "eip712": {
+      "types": {
+        "Permit": [
+          {
+            "name": "owner",
+            "type": "address"
+          },
+          {
+            "name": "spender",
+            "type": "address"
+          },
+          {
+            "name": "value",
+            "type": "uint256"
+          },
+          {
+            "name": "nonce",
+            "type": "uint256"
+          },
+          {
+            "name": "deadline",
+            "type": "uint256"
+          }
+        ]
+      }
+    }
+  },
+  "annotations": [
+    {
+      "at": "Permit",
+      "tag": "intent",
+      "args": {
+        "title": "Permit token spending",
+        "template": "Allow {spender} to spend up to {value} from {owner}. Signature expires: {deadline}."
+      }
+    },
+    {
+      "at": "Permit",
+      "tag": "effect",
+      "args": {
+        "kind": "approve",
+        "irreversible": false
+      }
+    },
+    {
+      "at": "Permit(0).value",
+      "tag": "amount",
+      "args": {
+        "decimals": {
+          "from": "query:decimals"
+        },
+        "symbol": {
+          "from": "query:symbol"
+        },
+        "threshold": "115792089237316195423570985008687907853269984665640564039457584007913129639935"
+      }
+    },
+    {
+      "at": "Permit(0).value",
+      "tag": "describe",
+      "args": {
+        "label": "Amount"
+      }
+    },
+    {
+      "at": "Permit(0).deadline",
+      "tag": "timestamp",
+      "args": {
+        "unit": "s",
+        "epoch": "unix",
+        "threshold": "115792089237316195423570985008687907853269984665640564039457584007913129639935",
+        "message": "Never"
+      }
+    },
+    {
+      "at": "Permit(0).deadline",
+      "tag": "describe",
+      "args": {
+        "label": "Signature expires"
+      }
+    },
+    {
+      "at": "Permit(0).owner",
+      "tag": "describe",
+      "args": {
+        "label": "Owner"
+      }
+    },
+    {
+      "at": "Permit(0).spender",
+      "tag": "describe",
+      "args": {
+        "label": "Spender"
+      }
+    },
+    {
+      "at": "Permit(0).nonce",
+      "tag": "describe",
+      "args": {
+        "label": "Nonce"
+      }
+    },
+    {
+      "at": "permit",
+      "tag": "intent",
+      "args": {
+        "title": "Submit a token permit",
+        "template": "Set {spender}'s allowance from {owner} to {value} with {owner}'s signature. Signature expires: {deadline}."
+      }
+    },
+    {
+      "at": "permit",
+      "tag": "effect",
+      "args": {
+        "kind": "approve",
+        "irreversible": false
+      }
+    },
+    {
+      "at": "permit(0).value",
+      "tag": "amount",
+      "args": {
+        "decimals": {
+          "from": "query:decimals"
+        },
+        "symbol": {
+          "from": "query:symbol"
+        },
+        "threshold": "115792089237316195423570985008687907853269984665640564039457584007913129639935"
+      }
+    },
+    {
+      "at": "permit(0).value",
+      "tag": "describe",
+      "args": {
+        "label": "Amount"
+      }
+    },
+    {
+      "at": "permit(0).deadline",
+      "tag": "timestamp",
+      "args": {
+        "unit": "s",
+        "epoch": "unix",
+        "threshold": "115792089237316195423570985008687907853269984665640564039457584007913129639935",
+        "message": "Never"
+      }
+    },
+    {
+      "at": "permit(0).deadline",
+      "tag": "describe",
+      "args": {
+        "label": "Signature expires"
+      }
+    },
+    {
+      "at": "permit(0).owner",
+      "tag": "describe",
+      "args": {
+        "label": "Owner"
+      }
+    },
+    {
+      "at": "permit(0).spender",
+      "tag": "describe",
+      "args": {
+        "label": "Spender"
+      }
+    },
+    {
+      "at": "permit(0).v",
+      "tag": "describe",
+      "args": {
+        "label": "Signature v"
+      }
+    }
+  ]
+}