@meantjs/profile 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -2,6 +2,29 @@
 
 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.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,38 @@ 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)
+
+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.
+- **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` and `typedDataDigest` (EIP-712). `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.
+
 ## 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/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/profile-v0.schema.json

@@ -24,7 +24,8 @@
     "kind": {
       "enum": [
         "canister",
-        "pack"
+        "pack",
+        "contract"
       ]
     },
     "name": {
@@ -100,14 +101,36 @@
           }
         }
       }
+    },
+    {
+      "if": {
+        "properties": {
+          "kind": {
+            "const": "contract"
+          }
+        }
+      },
+      "then": {
+        "properties": {
+          "origin": {
+            "enum": [
+              "author",
+              "third_party",
+              "inferred"
+            ]
+          },
+          "binds": {
+            "$ref": "#/$defs/contract_binds"
+          }
+        }
+      }
     }
   ],
   "$defs": {
     "pack_binds": {
       "type": "object",
       "required": [
-        "standard",
-        "requires"
+        "standard"
       ],
       "additionalProperties": false,
       "properties": {
@@ -123,8 +146,30 @@
           "type": "string",
           "minLength": 10,
           "description": "A Candid service fragment. The pack applies to a canister whose service type is a subtype of this fragment."
+        },
+        "abi": {
+          "$ref": "#/$defs/evm_abi",
+          "description": "An EVM pack (spec section 15, experimental): the functions it applies to. The pack applies to a contract that has each of them, with the same selector, outputs and kind of call."
         }
-      }
+      },
+      "oneOf": [
+        {
+          "required": [
+            "requires"
+          ],
+          "properties": {
+            "requires": true
+          }
+        },
+        {
+          "required": [
+            "abi"
+          ],
+          "properties": {
+            "abi": true
+          }
+        }
+      ]
     },
     "canister_binds": {
       "type": "object",
@@ -147,6 +192,73 @@
         }
       }
     },
+    "contract_binds": {
+      "type": "object",
+      "description": "An EVM contract (spec section 15, experimental): its ABI, and where it is deployed.",
+      "required": [
+        "abi"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "abi": {
+          "$ref": "#/$defs/evm_abi"
+        },
+        "deployments": {
+          "type": "array",
+          "minItems": 1,
+          "description": "The chain ids and addresses the profile describes (ERC-7730 context.contract.deployments). A consumer applies the profile to a call only when its target is listed.",
+          "items": {
+            "type": "object",
+            "required": [
+              "chain_id",
+              "address"
+            ],
+            "additionalProperties": false,
+            "properties": {
+              "chain_id": {
+                "type": "integer",
+                "minimum": 1
+              },
+              "address": {
+                "type": "string",
+                "pattern": "^0x[0-9a-fA-F]{40}$"
+              }
+            }
+          }
+        }
+      }
+    },
+    "evm_abi": {
+      "type": "array",
+      "minItems": 1,
+      "description": "EVM ABI function fragments: human-readable (`function transfer(address to, uint256 value) returns (bool)`) or JSON ABI entries. Only functions are read; events, errors, the constructor, fallback and receive are skipped. Parameter names are what addresses use.",
+      "items": {
+        "oneOf": [
+          {
+            "type": "string",
+            "pattern": "^\\s*(function|event|error|constructor|fallback|receive)\\b"
+          },
+          {
+            "type": "object",
+            "required": [
+              "type"
+            ],
+            "properties": {
+              "type": {
+                "enum": [
+                  "function",
+                  "event",
+                  "error",
+                  "constructor",
+                  "fallback",
+                  "receive"
+                ]
+              }
+            }
+          }
+        ]
+      }
+    },
     "value_address": {
       "type": "string",
       "description": "METHOD(i)path | METHOD->(i)path | type:DECL path. Paths: .label, .#id, [] (vec element). opt is transparent.",
@@ -244,8 +356,6 @@
             "properties": {
               "tag": {
                 "enum": [
-                  "intent",
-                  "effect",
                   "idempotency",
                   "outcome",
                   "list",
@@ -262,6 +372,32 @@
             }
           }
         },
+        {
+          "if": {
+            "properties": {
+              "tag": {
+                "enum": [
+                  "intent",
+                  "effect"
+                ]
+              }
+            }
+          },
+          "then": {
+            "properties": {
+              "at": {
+                "anyOf": [
+                  {
+                    "$ref": "#/$defs/method_address"
+                  },
+                  {
+                    "$ref": "#/$defs/value_address"
+                  }
+                ]
+              }
+            }
+          }
+        },
         {
           "if": {
             "properties": {
@@ -638,7 +774,23 @@
               "$ref": "#/$defs/dynamic"
             }
           ]
+        },
+        "threshold": {
+          "type": "string",
+          "pattern": "^(0|[1-9][0-9]{0,77})$",
+          "description": "Display only: a value at or above this (base units, a decimal string) displays as `message` and the symbol, for example \"Unlimited USDC\" (spec section 5.3)."
+        },
+        "message": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 32,
+          "description": "What a value at or above `threshold` displays as (default \"Unlimited\")."
         }
+      },
+      "dependentRequired": {
+        "message": [
+          "threshold"
+        ]
       }
     },
     "args_timestamp": {