@meantjs/profile 0.1.0 → 0.2.0

package/src/analyze.mjs

@@ -7,8 +7,8 @@ import { parseAddress } from "./address.mjs";
 import { jcs } from "./util.mjs";
 import { TagIndex, LayeredTags, positions } from "./tags.mjs";
 import {
-  NUMERIC, METHOD_TAGS, STALE_CODES, VALUE_CONVERSION_TAGS,
-  checkApplicability, checkDynamic, parseTemplate, outcomeCoverage,
+  NUMERIC, METHOD_TAGS, CASE_TAGS, CONFIRM_KINDS, STALE_CODES, VALUE_CONVERSION_TAGS, EVM_LATER_TAGS,
+  checkApplicability, checkDynamic, parseTemplate, outcomeCoverage, caseTargetError, otherCase, overlap, defaultEffect,
 } from "./checks.mjs";
 
 /** Spec section 8, highest precedence first. */
@@ -107,6 +107,40 @@ export function analyzeProfiles(iface, items, { attribute = true } = {}) {
   // A pack applied to a service is allowed to differ from its fragment in the ways Candid subtyping allows, so an
   // annotation that no longer holds on this service is dropped with an info, not reported as an error in the pack.
   const dropped = new Set();
+  const caseEntries = []; // case intents and effects, checked against each other and their method after the loop
+
+  /** An effect against the method's mode (spec 5.3); for a case effect, the mode of the method it sits in. */
+  const checkEffectMode = (m, { kind, irreversible, replicated }, diag, at) => {
+    if (m.mode !== "update" && m.mode !== "oneway" && kind !== "read") diag("error", "E_EFFECT_MODE", at, `${m.mode} method cannot have effect kind "${kind}"`);
+    // A read-only update (D-038): a read sent as an update so that its answer goes through consensus.
+    if (replicated === true) {
+      if (m.mode !== "update") diag("error", "E_EFFECT_MODE", at, `replicated: true applies to update methods, not to a ${m.mode} method`);
+      if (kind !== "read" || irreversible !== false) diag("error", "E_EFFECT_MODE", at, `replicated: true needs kind "read" and irreversible: false, found kind "${kind}" and irreversible: ${irreversible}`);
+    }
+    const replicatedRead = replicated === true && m.mode === "update" && kind === "read" && irreversible === false;
+    if ((m.mode === "update" || m.mode === "oneway") && kind === "read" && !replicatedRead) {
+      diag("warning", "W_EFFECT_MODE", at, `${m.mode} method declared as read${m.mode === "update" && replicated !== true ? "; a read sent as an update says irreversible: false, replicated: true" : ""}`);
+    }
+  };
+
+  /** An intent template's placeholders (spec section 6); `caseAddr` is the case a case intent sits on. */
+  const checkTemplate = (item, methodName, template, diag, at, caseAddr) => {
+    const t = parseTemplate(template);
+    if (t.error) return diag("error", "E_TEMPLATE", at, t.error);
+    if (iface.chain === "evm" && t.segments) return diag("error", "E_TEMPLATE", at, "an EVM contract's template has no [ ] segments: an ABI value is never absent (spec section 15)");
+    for (const p of t.placeholders) {
+      const r = iface.resolveRel(methodName, "args", p.path);
+      if (r.error && item.apply && p.inOptional) { // absent in this service: the optional segment renders empty (spec section 6)
+        item.diag("info", "I_PACK_ANNOTATION_SKIPPED", at, `intent: {${p.path}} is absent in this service (${r.error}); its optional segment renders empty`);
+        continue;
+      }
+      if (r.error) { diag("error", "E_TEMPLATE_PATH", at, `{${p.path}}: ${r.error}`); continue; }
+      const other = caseAddr && otherCase(iface, caseAddr, p.path);
+      if (other) { diag("error", "E_TEMPLATE_PATH", at, `{${p.path}}: ${other}`); continue; }
+      if (!p.inOptional && iface.node(r.ref).kind === "opt") diag("warning", "W_TEMPLATE_OPTIONAL", at, `{${p.path}} is optional but sits outside a [ ] segment`);
+    }
+  };
+
   const sets = new Map(); // names set -> { at, method, fields: { name, value, show?, kind? } } (spec 5.3, D-045)
   const named = []; // named positions, checked once every set is known
   for (const e of entries) {
@@ -118,22 +152,24 @@ export function analyzeProfiles(iface, items, { attribute = true } = {}) {
       item.diag("info", "I_PACK_ANNOTATION_SKIPPED", at, `${a.tag} dropped: ${code}: ${message}`);
     };
     const at = a.at;
+    if (iface.chain === "evm" && EVM_LATER_TAGS.has(a.tag)) {
+      diag("error", "E_TAG_TARGET", at, `${a.tag} is not defined for EVM contracts yet: it needs receipts, nonces or reads that a later phase adds (spec section 15)`);
+      continue;
+    }
+    // intent and effect on a case of a variant in the arguments (spec 5.2, D-053)
+    if (CASE_TAGS.has(a.tag) && !res.method) {
+      const why = caseTargetError(iface, addr, res, a.tag);
+      if (why) { diag("error", "E_TAG_TARGET", at, why); continue; }
+      const m = iface.methods.get(addr.method);
+      if (a.tag === "effect") checkEffectMode(m, a.args, diag, at);
+      else checkTemplate(item, addr.method, a.args.template, diag, at, addr);
+      caseEntries.push({ e, diag });
+      continue;
+    }
     if (METHOD_TAGS.has(a.tag)) {
       const m = res.method;
       const methodName = addr.method;
-      if (a.tag === "effect") {
-        const { kind, irreversible, replicated } = a.args;
-        if (m.mode !== "update" && m.mode !== "oneway" && kind !== "read") diag("error", "E_EFFECT_MODE", at, `${m.mode} method cannot have effect kind "${kind}"`);
-        // A read-only update (D-038): a read sent as an update so that its answer goes through consensus.
-        if (replicated === true) {
-          if (m.mode !== "update") diag("error", "E_EFFECT_MODE", at, `replicated: true applies to update methods, not to a ${m.mode} method`);
-          if (kind !== "read" || irreversible !== false) diag("error", "E_EFFECT_MODE", at, `replicated: true needs kind "read" and irreversible: false, found kind "${kind}" and irreversible: ${irreversible}`);
-        }
-        const replicatedRead = replicated === true && m.mode === "update" && kind === "read" && irreversible === false;
-        if ((m.mode === "update" || m.mode === "oneway") && kind === "read" && !replicatedRead) {
-          diag("warning", "W_EFFECT_MODE", at, `${m.mode} method declared as read${m.mode === "update" && replicated !== true ? "; a read sent as an update says irreversible: false, replicated: true" : ""}`);
-        }
-      }
+      if (a.tag === "effect") checkEffectMode(m, a.args, diag, at);
       if (a.tag === "idempotency") {
         if (m.mode !== "update") diag("error", "E_IDEMPOTENCY_MODE", at, "idempotency applies to update methods");
         const r = iface.resolveRel(methodName, "args", a.args.stamp);
@@ -153,19 +189,7 @@ export function analyzeProfiles(iface, items, { attribute = true } = {}) {
         outcomeCoverage(iface, methodName, classes, diag, at, Boolean(a.args.default));
         if (doc.kind === "pack" && !a.args.default) diag("warning", "W_PACK_NO_DEFAULT", at, "pack outcome without default: result cases a matching canister adds (spec §7) would be unclassified");
       }
-      if (a.tag === "intent") {
-        const t = parseTemplate(a.args.template);
-        if (t.error) diag("error", "E_TEMPLATE", at, t.error);
-        else for (const p of t.placeholders) {
-          const r = iface.resolveRel(methodName, "args", p.path);
-          if (r.error && item.apply && p.inOptional) { // absent in this service: the optional segment renders empty (spec section 6)
-            item.diag("info", "I_PACK_ANNOTATION_SKIPPED", at, `intent: {${p.path}} is absent in this service (${r.error}); its optional segment renders empty`);
-            continue;
-          }
-          if (r.error) { diag("error", "E_TEMPLATE_PATH", at, `{${p.path}}: ${r.error}`); continue; }
-          if (!p.inOptional && iface.node(r.ref).kind === "opt") diag("warning", "W_TEMPLATE_OPTIONAL", at, `{${p.path}} is optional but sits outside a [ ] segment`);
-        }
-      }
+      if (a.tag === "intent") checkTemplate(item, methodName, a.args.template, diag, at);
       if (a.tag === "names") {
         const effect = tags.methodTags(methodName).effect?.args;
         const replicatedRead = m.mode === "update" && effect?.kind === "read" && effect.irreversible === false && effect.replicated === true;
@@ -234,6 +258,28 @@ export function analyzeProfiles(iface, items, { attribute = true } = {}) {
     }
   }
 
+  // Tagged cases of one method must not overlap, and a case effect needs a method effect at least as strong
+  // (spec 5.2 and 5.3, D-053).
+  for (let j = 0; j < caseEntries.length; j++) {
+    const { e, diag } = caseEntries[j];
+    const { addr, ann: a } = e;
+    for (const { e: prev } of caseEntries.slice(0, j)) {
+      if (prev.ann.tag !== a.tag || prev.addr.method !== addr.method || prev.res.key === e.res.key) continue;
+      const why = overlap(iface, prev.addr, addr);
+      if (why) diag("error", "E_CASE_OVERLAP", a.at, `${a.tag} on "${prev.ann.at}" and on "${a.at}": one call can take both cases (${why})`);
+    }
+    if (a.tag !== "effect") continue;
+    const m = iface.methods.get(addr.method);
+    const declared = tags.methodTags(addr.method).effect?.args;
+    const method = declared ?? defaultEffect(m.mode);
+    const whose = `the method's effect is ${method.kind}${method.irreversible ? ", irreversible" : ""}${declared ? "" : " (the default)"}`;
+    if (CONFIRM_KINDS.has(a.args.kind) && !CONFIRM_KINDS.has(method.kind)) {
+      diag("error", "E_CASE_EFFECT", a.at, `case effect ${a.args.kind} needs a person's confirmation, but ${whose}; declare the method's effect as transfer, approve, admin or destroy, so that a consumer that reads only method tags confirms it too`);
+    } else if (a.args.irreversible === true && method.irreversible !== true) {
+      diag("error", "E_CASE_EFFECT", a.at, `case effect is irreversible, but ${whose}; a method with an irreversible case is irreversible`);
+    }
+  }
+
   // Dropping a value tag can leave an idempotency stamp without its timestamp tag: drop that idempotency too.
   if (dropped.size) {
     const without = buildLayers(entries, (e) => !dropped.has(e));

package/src/browser.d.mts

@@ -1,11 +1,11 @@
 // Types for @meantjs/profile/browser. Hand-written; the source is plain ES modules (src/*.mjs). The internal
 // graph classes (Iface, TagIndex, LayeredTags, SubtypeChecker) are declared opaquely.
 
-/** A Candid Profile document (docs/profile-v0.md): a canister profile or a pack. */
+/** A Candid Profile document (docs/profile-v0.md): a canister profile, a pack, or an EVM contract profile (section 15). */
 export interface ProfileDocument {
   format: "candid-profile";
   format_version: 0;
-  kind: "canister" | "pack";
+  kind: "canister" | "pack" | "contract";
   name: string;
   origin: "author" | "third_party" | "pack" | "inferred";
   annotations: { at: string; tag: string; args?: Record<string, unknown> }[];
@@ -17,6 +17,8 @@ export interface ResolvedForm {
   format: "candid-profile-resolved";
   format_version: 0;
   interface_id: string;
+  /** "evm" for an EVM contract's form (section 15.5); absent for a Candid service's. */
+  chain?: "evm";
   profiles: unknown[];
   methods: Record<string, unknown>;
   diagnostics: Diagnostic[];
@@ -54,14 +56,16 @@ export interface SchemaValidator {
 }
 
 export interface ResolveOptions {
-  /** Candid source of the service (exactly one of `did` and `envelope`). */
+  /** Candid source of the service (exactly one of `did`, `envelope` and `abi`). */
   did?: string;
   /** The service's candid-core ContractEnvelope. */
   envelope?: unknown;
+  /** An EVM contract's ABI: human-readable fragments or JSON ABI entries (section 15). */
+  abi?: readonly (string | Record<string, unknown>)[];
   didLabel?: string;
   /** Applied as given; a pack here must match. */
   profiles?: { doc: unknown; label?: string }[];
-  /** Tried by Candid subtyping; applied only if they match. */
+  /** Tried by Candid subtyping (an EVM pack by selector); applied only if they match. */
   packs?: { doc: unknown; label?: string }[];
   validateSchema: SchemaValidator;
 }

package/src/browser.mjs

@@ -10,6 +10,7 @@
 import schema from "../data/profile-v0.schema.json" with { type: "json" };
 import icrc1 from "../data/packs/icrc1.profile.json" with { type: "json" };
 import icrc2 from "../data/packs/icrc2.profile.json" with { type: "json" };
+import erc20 from "../data/packs/erc20.profile.json" with { type: "json" };
 import { compileSchema } from "./schema-core.mjs";
 
 export { init as initCompiler } from "@candid-core/cli";
@@ -33,6 +34,7 @@ export const PROFILE_SCHEMA = schema;
 
 /** The standard packs (copies of packs/*.profile.json), sorted by file name, in the shape `loadPacks` returns. */
 export const STANDARD_PACKS = Object.freeze([
+  { file: "erc20.profile.json", doc: erc20 },
   { file: "icrc1.profile.json", doc: icrc1 },
   { file: "icrc2.profile.json", doc: icrc2 },
 ]);

package/src/checks.mjs

@@ -1,25 +1,38 @@
 /**
  * Per-annotation semantic checks (spec sections 3 to 6). Moved verbatim from scripts/validate.mjs.
  */
-export const NUMERIC = new Set(["nat", "int", "nat8", "nat16", "nat32", "nat64", "int8", "int16", "int32", "int64"]);
-export const TIMEISH = new Set(["nat", "int", "nat32", "nat64", "int64"]);
+import { parseRelPath } from "./address.mjs";
+
+/** EVM integer types (spec section 15): uint8 to uint256 and int8 to int256. int8 to int64 are also Candid's, with the same bounds. */
+const ABI_BITS = Array.from({ length: 32 }, (_, i) => 8 * (i + 1));
+export const NUMERIC = new Set(["nat", "int", "nat8", "nat16", "nat32", "nat64", "int8", "int16", "int32", "int64", ...ABI_BITS.flatMap((b) => [`uint${b}`, `int${b}`])]);
+export const TIMEISH = new Set(["nat", "int", "nat32", "nat64", "int64", ...ABI_BITS.filter((b) => b >= 32).map((b) => `uint${b}`), ...ABI_BITS.filter((b) => b >= 64).map((b) => `int${b}`)]);
+/** Text: Candid's `text`, the ABI's `string`. */
+export const TEXT = new Set(["text", "string"]);
+/** Tags an EVM contract profile cannot use yet: they need receipts, nonces or reads that phase 2 adds (spec section 15). */
+export const EVM_LATER_TAGS = new Set(["idempotency", "outcome", "list", "names", "named"]);
 export const METHOD_TAGS = new Set(["intent", "effect", "idempotency", "outcome", "list", "names"]);
+/** Method tags that may also sit on a case of a variant in the arguments (spec 5.2, D-053). */
+export const CASE_TAGS = new Set(["intent", "effect"]);
+/** Effect kinds that need a person's confirmation (spec 5.3). */
+export const CONFIRM_KINDS = new Set(["transfer", "approve", "admin", "destroy"]);
 /** Tags that convert a value between its wire form and a human form; a stale profile must not supply them (spec section 7). */
 export const VALUE_CONVERSION_TAGS = new Set(["amount", "timestamp", "duration", "account", "subaccount", "bytes", "named"]);
-export const STALE_CODES = new Set(["E_ADDR_UNRESOLVED", "E_TYPE_NODE", "E_TAG_NOT_APPLICABLE", "E_REF_UNRESOLVED", "E_REF_NOT_QUERY", "E_REF_SHAPE", "E_REF_TYPE", "E_STAMP_UNTAGGED", "E_OUTCOME_NOT_CASE", "E_TEMPLATE_PATH", "E_TAG_TARGET", "E_NAMES_MODE", "E_NAMES_SHAPE", "E_NAMES_FIELD", "E_NAMED_SET", "E_NAMED_TYPE"]);
+export const STALE_CODES = new Set(["E_ADDR_UNRESOLVED", "E_TYPE_NODE", "E_TAG_NOT_APPLICABLE", "E_REF_UNRESOLVED", "E_REF_NOT_QUERY", "E_REF_SHAPE", "E_REF_TYPE", "E_STAMP_UNTAGGED", "E_OUTCOME_NOT_CASE", "E_TEMPLATE_PATH", "E_TAG_TARGET", "E_NAMES_MODE", "E_NAMES_SHAPE", "E_NAMES_FIELD", "E_NAMED_SET", "E_NAMED_TYPE", "E_CASE_OVERLAP", "E_CASE_EFFECT"]);
 
 export function checkApplicability(iface, tag, ref) {
   const { ref: r } = iface.unwrapOpt(ref);
   const p = iface.prim(r);
+  if (iface.chain === "evm" && (tag === "account" || tag === "subaccount")) return `${tag} is an ICRC type; an EVM address needs no tag (it is shown with its EIP-55 checksum, spec section 15)`;
   switch (tag) {
     case "amount": return NUMERIC.has(p) ? null : `amount needs a numeric type, found ${iface.describeType(ref)}`;
     case "timestamp":
-    case "duration": return TIMEISH.has(p) ? null : `${tag} needs nat/int/nat32/nat64/int64, found ${iface.describeType(ref)}`;
+    case "duration": return TIMEISH.has(p) ? null : `${tag} needs ${iface.chain === "evm" ? "uint32 to uint256 or int64 to int256" : "nat/int/nat32/nat64/int64"}, found ${iface.describeType(ref)}`;
     case "account": return iface.isAccount(r) ? null : `account needs record { owner : principal; subaccount : opt blob }, found ${iface.describeType(ref)}`;
     case "subaccount":
-    case "bytes": return iface.isBlob(r) ? null : `${tag} needs blob, found ${iface.describeType(ref)}`;
-    case "text": return p === "text" ? null : `text needs text, found ${iface.describeType(ref)}`;
-    case "range": return NUMERIC.has(p) || p === "text" || iface.node(r).kind === "vec" ? null : `range needs numeric, text or vec, found ${iface.describeType(ref)}`;
+    case "bytes": return iface.isBlob(r) ? null : `${tag} needs ${iface.chain === "evm" ? "bytes or bytesN" : "blob"}, found ${iface.describeType(ref)}`;
+    case "text": return TEXT.has(p) ? null : `text needs ${iface.chain === "evm" ? "string" : "text"}, found ${iface.describeType(ref)}`;
+    case "range": return NUMERIC.has(p) || TEXT.has(p) || iface.node(r).kind === "vec" ? null : `range needs numeric, text or vec, found ${iface.describeType(ref)}`;
     default: return null;
   }
 }
@@ -39,17 +52,18 @@ export function checkDynamic(iface, value, want, diag, at) {
   else {
     const p = iface.prim(iface.unwrapOpt(m.results[0]).ref);
     if (want === "numeric" && !NUMERIC.has(p)) diag("error", "E_REF_TYPE", at, `"${from}" returns ${p}, expected a number`);
-    if (want === "text" && p !== "text") diag("error", "E_REF_TYPE", at, `"${from}" returns ${p}, expected text`);
+    if (want === "text" && !TEXT.has(p)) diag("error", "E_REF_TYPE", at, `"${from}" returns ${p}, expected text`);
   }
 }
 
 export function parseTemplate(t) {
   const placeholders = [];
   let depth = 0;
+  let segments = 0;
   for (let i = 0; i < t.length; i++) {
     const c = t[i];
     if ((c === "{" || c === "}" || c === "[" || c === "]") && t[i + 1] === c) { i++; continue; } // escaped
-    if (c === "[") { if (depth) return { error: "nested [ ] segments are not allowed in v0" }; depth = 1; }
+    if (c === "[") { if (depth) return { error: "nested [ ] segments are not allowed in v0" }; depth = 1; segments++; }
     else if (c === "]") { if (!depth) return { error: "unbalanced ]" }; depth = 0; }
     else if (c === "{") {
       const end = t.indexOf("}", i);
@@ -59,7 +73,7 @@ export function parseTemplate(t) {
     } else if (c === "}") return { error: "unbalanced }" };
   }
   if (depth) return { error: "unclosed [" };
-  return { placeholders };
+  return { placeholders, segments };
 }
 
 export function outcomeCoverage(iface, methodName, classes, diag, at, hasDefault) {
@@ -79,3 +93,62 @@ export function outcomeCoverage(iface, methodName, classes, diag, at, hasDefault
   };
   visit(m.results[0], "");
 }
+
+/** The effect a method has without an effect tag (spec 5.3): queries read, updates write irreversibly. */
+export function defaultEffect(mode) {
+  return mode === "query" || mode === "composite_query" ? { kind: "read", irreversible: false } : { kind: "write", irreversible: true };
+}
+
+/** Why an intent or effect at a value address is not on a case of an argument (spec 5.2, D-053), or null. */
+export function caseTargetError(iface, addr, res, tag) {
+  if (addr.kind === "type") return `${tag} sits on a method or on a case of a variant in its arguments, never at a type: address (it can reach several methods)`;
+  if (addr.kind === "result") return `${tag} sits on a method or on a case of a variant in its arguments, not in its results`;
+  if (addr.segs.some((s) => s.kind === "elem")) return `${tag} on a case cannot step into a vector element ([]): one call holds many elements`;
+  if (res.parent?.kind !== "variant") return `${tag} sits on a method or on a case of a variant in its arguments; this address ends on ${res.parent ? "a record field" : "a whole argument"}`;
+  return null;
+}
+
+/**
+ * Walk two segment lists of one method argument side by side. Returns where they part: { kind } of the container at
+ * the first differing step, with the two labels, or null when one is a prefix of the other.
+ */
+function part(iface, start, a, b) {
+  let cur = start;
+  for (let k = 0; k < Math.min(a.length, b.length); k++) {
+    cur = iface.unwrapOpt(cur).ref;
+    const n = iface.node(cur);
+    const x = a[k];
+    const y = b[k];
+    if (x.kind === "elem" || y.kind === "elem") {
+      if (x.kind === y.kind) { cur = n.inner; continue; }
+      return { kind: n.kind };
+    }
+    if (x.id !== y.id) return { kind: n.kind, a: x.label, b: y.label };
+    cur = n.fields.find((f) => f.id === x.id).type;
+  }
+  return null;
+}
+
+/**
+ * A case template's placeholder that selects another case of a variant the case address passes through, so it can
+ * never be present (spec section 6, D-053): the reason, or null. Both paths resolve; `rel` is a method-tuple relpath.
+ */
+export function otherCase(iface, caseAddr, rel) {
+  const p = parseRelPath(rel);
+  const index = p.index ?? 0;
+  if (index !== caseAddr.index) return null;
+  const m = iface.methods.get(caseAddr.method);
+  const at = part(iface, m.args[index], caseAddr.segs, p.segs);
+  return at?.kind === "variant" ? `selects case "${at.b}" of a variant where this intent's case takes "${at.a}", so it is never present` : null;
+}
+
+/**
+ * Whether one call can take two tagged cases of one method (spec 5.2, D-053): the reason, or null when they exclude
+ * each other (they part at a variant) or nest.
+ */
+export function overlap(iface, a, b) {
+  if (a.index !== b.index) return "they sit in different arguments";
+  const m = iface.methods.get(a.method);
+  const at = part(iface, m.args[a.index], a.segs, b.segs);
+  return at && at.kind !== "variant" ? "their paths part at a record field" : null;
+}

package/src/cli.mjs

@@ -1,5 +1,5 @@
 /**
- * candid-profile resolve (<service.did> | --envelope <file>) [--profile p.json ...] [--packs] [--packs-dir dir]
+ * candid-profile resolve (<service.did> | --envelope <file> | --abi <file>) [--profile p.json ...] [--packs] [--packs-dir dir]
  *
  * Prints the resolved form (docs/profile-v0.md section 10) on stdout and a summary on stderr.
  * Exit code: 0 when no diagnostic is an error, 1 when one is (the resolved form is still printed when the service
@@ -13,9 +13,12 @@ import { resolveService } from "./resolve.mjs";
 
 export const USAGE = `usage: candid-profile resolve <service.did> [options] > resolved.json
        candid-profile resolve --envelope <file> [options] > resolved.json
+       candid-profile resolve --abi <file> [options] > resolved.json
 
   --envelope <file>   the service's candid-core ContractEnvelope (as \`candid-core-cli gen\` writes it), instead of
                       compiling a .did here
+  --abi <file>        an EVM contract's ABI, a JSON array of human-readable fragments or JSON ABI entries
+                      (experimental, spec section 15)
   --profile <file>    a profile to apply (repeatable). A pack given this way must match the service.
   --packs             try every pack in the packs directory; apply those that match
   --packs-dir <dir>   packs directory (default: the standard packs this package ships)
@@ -27,7 +30,7 @@ export const USAGE = `usage: candid-profile resolve <service.did> [options] > re
 class UsageError extends Error {}
 
 function parseArgs(argv) {
-  const opts = { did: null, envelope: null, profiles: [], packs: false, packsDir: DEFAULT_PACKS_DIR, verbose: false, quiet: false, help: false };
+  const opts = { did: null, envelope: null, abi: null, profiles: [], packs: false, packsDir: DEFAULT_PACKS_DIR, verbose: false, quiet: false, help: false };
   const args = [...argv];
   const value = (name, inline) => {
     if (inline !== undefined) return inline;
@@ -40,6 +43,7 @@ function parseArgs(argv) {
     const [flag, inline] = a.startsWith("--") && a.includes("=") ? [a.slice(0, a.indexOf("=")), a.slice(a.indexOf("=") + 1)] : [a, undefined];
     if (flag === "--profile") opts.profiles.push(value(flag, inline));
     else if (flag === "--envelope") opts.envelope = value(flag, inline);
+    else if (flag === "--abi") opts.abi = value(flag, inline);
     else if (flag === "--packs") opts.packs = true;
     else if (flag === "--packs-dir") opts.packsDir = value(flag, inline);
     else if (flag === "--verbose") opts.verbose = true;
@@ -73,10 +77,12 @@ export async function main(argv, io) {
     if (command !== "resolve") throw new UsageError(`unknown command ${command}`);
     const opts = parseArgs(rest);
     if (opts.help) { err(USAGE.trimEnd()); return 0; }
-    if (opts.did && opts.envelope) throw new UsageError("give <service.did> or --envelope, not both");
-    if (!opts.did && !opts.envelope) throw new UsageError("missing <service.did> (or --envelope <file>)");
+    const given = [opts.did, opts.envelope, opts.abi].filter((x) => x !== null).length;
+    if (given > 1) throw new UsageError("give only one of <service.did>, --envelope and --abi");
+    if (given === 0) throw new UsageError("missing <service.did> (or --envelope <file>, or --abi <file>)");
     const input = {};
     if (opts.envelope) input.envelope = await readJsonFile(opts.envelope, "envelope");
+    else if (opts.abi) input.abi = await readJsonFile(opts.abi, "ABI");
     else {
       try { input.did = await readFile(opts.did, "utf8"); } catch (e) { throw new UsageError(`cannot read ${opts.did}: ${e.message}`); }
     }
@@ -92,7 +98,7 @@ export async function main(argv, io) {
       for (const p of found) packs.push({ doc: p.doc, label: path.relative(process.cwd(), p.file) });
     }
 
-    const r = await resolveService({ ...input, didLabel: opts.did ?? opts.envelope, validateSchema, profiles, packs });
+    const r = await resolveService({ ...input, didLabel: opts.did ?? opts.envelope ?? opts.abi, validateSchema, profiles, packs });
     if (r.resolved) io.stdout.write(`${JSON.stringify(r.resolved, null, 2)}\n`);
     if (!opts.quiet) summary(r, opts, err);
     return r.ok ? 0 : 1;
@@ -104,7 +110,7 @@ export async function main(argv, io) {
 
 function summary(r, opts, err) {
   const count = (s) => r.diagnostics.filter((d) => d.severity === s).length;
-  if (r.resolved) err(`candid-profile: ${opts.did ?? opts.envelope}  ${r.resolved.interface_id}  [${Object.keys(r.resolved.methods).length} methods]`);
+  if (r.resolved) err(`candid-profile: ${opts.did ?? opts.envelope ?? opts.abi}  ${r.resolved.interface_id}  [${Object.keys(r.resolved.methods).length} methods]`);
   for (const p of r.profiles) err(`  ${p.status.padEnd(11)} ${String(p.name).padEnd(16)} ${String(p.origin ?? "?").padEnd(12)} ${p.profile_id ?? ""}`);
   err(`  ${count("error")} error, ${count("warning")} warning, ${count("info")} info`);
   for (const d of r.diagnostics) {

package/src/evm.d.mts

@@ -0,0 +1,86 @@
+// Types for @meantjs/profile/evm: the EVM helpers of spec section 15 (experimental), with no dependency, for a
+// browser bundle. Hand-written; the source is src/evm.mjs, src/abi.mjs and src/keccak.mjs.
+// test/types.test.mjs keeps the declared names equal to the runtime exports.
+
+/** An ABI type: `kind` is uint, int, address, bool, string, bytes, fixedbytes, array or tuple. */
+export type AbiType =
+  | { kind: "uint" | "int"; bits: number }
+  | { kind: "address" | "bool" | "string" | "bytes" }
+  | { kind: "fixedbytes"; size: number }
+  | { kind: "array"; element: AbiType; length: number | null }
+  | { kind: "tuple"; components: AbiParam[] };
+/** A parameter, output or tuple component; `name` is null when it has none. */
+export interface AbiParam {
+  name: string | null;
+  type: AbiType;
+}
+/** A function read from an ABI. */
+export interface AbiFunction {
+  name: string;
+  inputs: AbiParam[];
+  outputs: AbiParam[];
+  stateMutability: "pure" | "view" | "nonpayable" | "payable";
+  /** `transfer(address to,uint256 value)`: the ERC-7730 key, and a resolved form's `signature`. */
+  signature: string;
+  /** `transfer(address,uint256)`: what the selector hashes. */
+  typeSignature: string;
+  /** `0xa9059cbb` */
+  selector: string;
+  /** `function transfer(address to,uint256 value) returns (bool)` */
+  canonical: string;
+  /** Where it was read (`abi[3]`); parseSignature leaves it out. */
+  at?: string;
+}
+/** A decoded or encodable value: decimal strings (or bigints) for integers, EIP-55 text for addresses, Uint8Array for bytes. */
+export type AbiValue = string | bigint | boolean | Uint8Array | AbiValue[] | { [key: string]: AbiValue };
+export interface AbiLimits {
+  maxBytes?: number;
+  maxDepth?: number;
+  maxElements?: number;
+}
+/** Every failure of the ABI helpers: E_ABI (a fragment), E_ABI_ENCODE, E_ABI_DECODE, E_ADDRESS or E_ADDRESS_CHECKSUM. */
+export declare class AbiError extends Error {
+  constructor(code: string, message: string);
+  name: "AbiError";
+  code: string;
+}
+export interface TypedData {
+  domain: Record<string, unknown>;
+  types: Record<string, { name: string; type: string }[]>;
+  primaryType: string;
+  message: Record<string, unknown>;
+}
+
+/** Keccak-256 (Ethereum's, not NIST SHA3-256) of bytes or of a string's UTF-8 bytes. */
+export function keccak256(input: Uint8Array | string): Uint8Array;
+/** Keccak-256 as 64 lowercase hex digits, without `0x`. */
+export function keccak256Hex(input: Uint8Array | string): string;
+/** RFC 8785 canonical JSON. */
+export function jcs(value: unknown): string;
+export const DEFAULT_ABI_LIMITS: Readonly<Required<AbiLimits>>;
+/** Read an ABI (human-readable fragments or JSON ABI entries); only functions are read. Problems are listed, not thrown. */
+export function parseAbi(entries: unknown, label?: string): { functions: AbiFunction[]; errors: { at: string; message: string }[] };
+/** One function from its named signature, as a resolved form carries it. Throws AbiError. */
+export function parseSignature(signature: string, where?: string): AbiFunction;
+/** `candid-profile:evm-abi:v0:sha256:…`: SHA-256 over the JCS array of the canonical fragments, sorted. */
+export function abiInterfaceId(functions: readonly AbiFunction[]): string;
+export function canonicalFragment(f: Pick<AbiFunction, "name" | "inputs" | "outputs" | "stateMutability">): string;
+export function namedSignature(f: Pick<AbiFunction, "name" | "inputs">): string;
+export function typeSignature(f: Pick<AbiFunction, "name" | "inputs">): string;
+export function selectorOf(f: Pick<AbiFunction, "name" | "inputs">): string;
+/** Canonical type text; with `names`, tuple components keep their names. */
+export function typeString(type: AbiType, names?: boolean): string;
+/** A tuple component's key in values and resolved forms: its name, else `#` and its position. */
+export function componentKey(param: AbiParam, index: number): string;
+/** ABI-encode a parameter list's values, keyed like a tuple. Throws AbiError (E_ABI_ENCODE). */
+export function encodeParams(params: readonly AbiParam[], values: Record<string, AbiValue>): Uint8Array;
+/** The selector followed by the encoded parameters. */
+export function encodeCall(f: AbiFunction, values: Record<string, AbiValue>): Uint8Array;
+/** Decode strictly: the bytes must be the canonical encoding of the values read. Throws AbiError (E_ABI_DECODE). */
+export function decodeParams(params: readonly AbiParam[], data: Uint8Array, limits?: AbiLimits): Record<string, AbiValue>;
+/** The EIP-55 checksummed form of `0x` and 40 hex digits. */
+export function toChecksumAddress(address: string): string;
+/** Read an address: mixed case must match its EIP-55 checksum. Returns the checksummed form. */
+export function readAddress(text: string): string;
+/** The EIP-712 digest a signer signs, as `0x` and 64 hex digits. */
+export function typedDataDigest(typed: TypedData): string;

package/src/evm.mjs

@@ -0,0 +1,28 @@
+/**
+ * `@meantjs/profile/evm`: the EVM helpers of spec section 15 (D-054), browser-safe and without dependencies.
+ * Keccak-256, ABI fragments (reading, canonical text, selectors, the interface identity), a strict ABI codec, EIP-55
+ * addresses and EIP-712 digests. The consent package builds calldata display and the ERC-7730 export on them.
+ *
+ * test/evm.test.mjs checks the vectors; test/address-entry.test.mjs keeps this entry free of node:* imports.
+ */
+export { keccak256, keccak256Hex } from "./keccak.mjs";
+export {
+  AbiError,
+  DEFAULT_ABI_LIMITS,
+  abiInterfaceId,
+  canonicalFragment,
+  componentKey,
+  decodeParams,
+  encodeCall,
+  encodeParams,
+  namedSignature,
+  parseAbi,
+  parseSignature,
+  readAddress,
+  selectorOf,
+  toChecksumAddress,
+  typeSignature,
+  typeString,
+  typedDataDigest,
+} from "./abi.mjs";
+export { jcs } from "./util.mjs";

package/src/keccak.mjs

@@ -0,0 +1,108 @@
+// Keccak-256 in plain JavaScript, synchronous, as Ethereum uses it: the original Keccak padding (0x01), not the NIST
+// SHA3-256 one (0x06). For function selectors, EIP-55 checksums, ERC-8176 descriptor hashes and EIP-712 digests
+// (spec section 15, D-054). test/evm.test.mjs checks it against the known hashes of the empty string and of the
+// ERC-20 selectors, and against the ERC-8176 schema UID.
+//
+// The 1600-bit state is 25 lanes of 64 bits, each kept as two 32-bit halves: s[2i] the low half, s[2i + 1] the high.
+
+const RC = new Uint32Array([
+  // round constants, [low, high] per round
+  0x00000001, 0x00000000, 0x00008082, 0x00000000, 0x0000808a, 0x80000000, 0x80008000, 0x80000000,
+  0x0000808b, 0x00000000, 0x80000001, 0x00000000, 0x80008081, 0x80000000, 0x00008009, 0x80000000,
+  0x0000008a, 0x00000000, 0x00000088, 0x00000000, 0x80008009, 0x00000000, 0x8000000a, 0x00000000,
+  0x8000808b, 0x00000000, 0x0000008b, 0x80000000, 0x00008089, 0x80000000, 0x00008003, 0x80000000,
+  0x00008002, 0x80000000, 0x00000080, 0x80000000, 0x0000800a, 0x00000000, 0x8000000a, 0x80000000,
+  0x80008081, 0x80000000, 0x00008080, 0x80000000, 0x80000001, 0x00000000, 0x80008008, 0x80000000,
+]);
+// rotation offsets of the rho step, by lane index x + 5y
+const ROT = [0, 1, 62, 28, 27, 36, 44, 6, 55, 20, 3, 10, 43, 25, 39, 41, 45, 15, 21, 8, 18, 2, 61, 56, 14];
+// the lane the pi step moves lane x + 5y to: (y, 2x + 3y)
+const PI = ROT.map((_, i) => {
+  const x = i % 5;
+  const y = (i - x) / 5;
+  return y + 5 * ((2 * x + 3 * y) % 5);
+});
+const RATE = 136; // bytes: 1600 - 2 * 256 bits
+
+function permute(s) {
+  const c = new Uint32Array(10);
+  const b = new Uint32Array(50);
+  for (let round = 0; round < 24; round++) {
+    // theta
+    for (let x = 0; x < 5; x++) {
+      c[2 * x] = s[2 * x] ^ s[2 * x + 10] ^ s[2 * x + 20] ^ s[2 * x + 30] ^ s[2 * x + 40];
+      c[2 * x + 1] = s[2 * x + 1] ^ s[2 * x + 11] ^ s[2 * x + 21] ^ s[2 * x + 31] ^ s[2 * x + 41];
+    }
+    for (let x = 0; x < 5; x++) {
+      const next = (x + 1) % 5;
+      const prev = (x + 4) % 5;
+      const lo = c[2 * prev] ^ ((c[2 * next] << 1) | (c[2 * next + 1] >>> 31));
+      const hi = c[2 * prev + 1] ^ ((c[2 * next + 1] << 1) | (c[2 * next] >>> 31));
+      for (let y = 0; y < 25; y += 5) {
+        s[2 * (x + y)] ^= lo;
+        s[2 * (x + y) + 1] ^= hi;
+      }
+    }
+    // rho and pi
+    for (let i = 0; i < 25; i++) {
+      const lo = s[2 * i];
+      const hi = s[2 * i + 1];
+      const n = ROT[i];
+      const j = PI[i];
+      if (n === 0) {
+        b[2 * j] = lo;
+        b[2 * j + 1] = hi;
+      } else if (n < 32) {
+        b[2 * j] = (lo << n) | (hi >>> (32 - n));
+        b[2 * j + 1] = (hi << n) | (lo >>> (32 - n));
+      } else if (n === 32) {
+        b[2 * j] = hi;
+        b[2 * j + 1] = lo;
+      } else {
+        const m = n - 32;
+        b[2 * j] = (hi << m) | (lo >>> (32 - m));
+        b[2 * j + 1] = (lo << m) | (hi >>> (32 - m));
+      }
+    }
+    // chi
+    for (let y = 0; y < 25; y += 5) {
+      for (let x = 0; x < 5; x++) {
+        const i = x + y;
+        const i1 = ((x + 1) % 5) + y;
+        const i2 = ((x + 2) % 5) + y;
+        s[2 * i] = b[2 * i] ^ (~b[2 * i1] & b[2 * i2]);
+        s[2 * i + 1] = b[2 * i + 1] ^ (~b[2 * i1 + 1] & b[2 * i2 + 1]);
+      }
+    }
+    // iota
+    s[0] ^= RC[2 * round];
+    s[1] ^= RC[2 * round + 1];
+  }
+}
+
+/** Keccak-256 of a byte array (or a string, as its UTF-8 bytes), as 32 bytes. */
+export function keccak256(input) {
+  const bytes = typeof input === "string" ? new TextEncoder().encode(input) : input;
+  const s = new Uint32Array(50);
+  const blocks = Math.floor(bytes.length / RATE) + 1;
+  const padded = new Uint8Array(blocks * RATE);
+  padded.set(bytes);
+  padded[bytes.length] ^= 0x01;
+  padded[padded.length - 1] ^= 0x80;
+  for (let off = 0; off < padded.length; off += RATE) {
+    for (let k = 0; k < RATE; k += 4) {
+      s[k >> 2] ^= padded[off + k] | (padded[off + k + 1] << 8) | (padded[off + k + 2] << 16) | (padded[off + k + 3] << 24);
+    }
+    permute(s);
+  }
+  const out = new Uint8Array(32);
+  for (let k = 0; k < 32; k++) out[k] = (s[k >> 2] >>> (8 * (k & 3))) & 0xff;
+  return out;
+}
+
+/** Keccak-256 as 64 lowercase hex digits, without `0x`. */
+export function keccak256Hex(input) {
+  let hex = "";
+  for (const b of keccak256(input)) hex += b.toString(16).padStart(2, "0");
+  return hex;
+}