@meantjs/profile 0.1.0 → 0.3.0

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;
+}

package/src/resolve.mjs

@@ -15,6 +15,10 @@ import { profileId } from "./util.mjs";
 import { compileInterface, interfaceFromEnvelope } from "./compile.mjs";
 import { analyzeProfiles } from "./analyze.mjs";
 import { matchPack } from "./pack-match.mjs";
+import { abiInterface, checkDeployments, eip712Of } from "./abi-iface.mjs";
+import { matchAbiPack, translatePack } from "./abi-pack.mjs";
+import { abiInterfaceId, parseAbi } from "./abi.mjs";
+import { jcs } from "./util.mjs";
 import { resolvedForm } from "./resolved.mjs";
 import { schemaDiagnostics } from "./schema-core.mjs";
 
@@ -25,8 +29,9 @@ const describeReasons = (reasons) => {
 
 /**
  * @param opts.did           Candid source of the service, compiled here; or
- * @param opts.envelope      the service's candid-core ContractEnvelope, already compiled (exactly one of the two)
- * @param opts.didLabel      how E_CANDID (or E_ENVELOPE) names the input
+ * @param opts.envelope      the service's candid-core ContractEnvelope, already compiled; or
+ * @param opts.abi           an EVM contract's ABI: fragments or JSON ABI entries (spec section 15; exactly one of the three)
+ * @param opts.didLabel      how E_CANDID (or E_ENVELOPE, E_ABI) names the input
  * @param opts.profiles      [{ doc, label? }] explicit profiles, applied or rejected
  * @param opts.packs         [{ doc, label? }] candidate packs, applied only if they match
  * @param opts.validateSchema from createSchemaValidator()
@@ -37,7 +42,8 @@ const describeReasons = (reasons) => {
  */
 export async function resolveService(opts) {
   const fromEnvelope = opts.envelope !== undefined;
-  if (fromEnvelope === (opts.did !== undefined)) throw new TypeError("resolveService: give exactly one of `did` and `envelope`");
+  if ([opts.did, opts.envelope, opts.abi].filter((x) => x !== undefined).length !== 1) throw new TypeError("resolveService: give exactly one of `did`, `envelope` and `abi`");
+  if (opts.abi !== undefined) return resolveCompiled(opts, false);
   if (!fromEnvelope) return resolveCompiled(opts, false);
   // interfaceFromEnvelope checks the graph before anything walks it; anything it still misses in someone else's
   // document is reported against the envelope rather than thrown.
@@ -52,13 +58,32 @@ export async function resolveService(opts) {
 async function resolveCompiled(opts, fromEnvelope) {
   const diagnostics = [];
   const statuses = [];
+  if (opts.abi !== undefined) {
+    const label = opts.didLabel ?? "abi";
+    // The messages of an EVM contract come from its profiles and packs (spec section 15.9), so the interface is built
+    // again once they are known; an ABI without functions is refused only if none brings a message.
+    const build = (eip712, allowEmpty = false) => abiInterface(opts.abi, label, "contract", eip712, { allowEmpty });
+    const compiled = build(null, true);
+    if (compiled.failure) {
+      for (const d of compiled.failure) diagnostics.push({ severity: "error", code: "E_ABI", at: d.at, message: d.message });
+      return { ok: false, resolved: null, diagnostics, profiles: statuses };
+    }
+    return resolveWith(compiled.iface, opts, diagnostics, statuses, build);
+  }
   const compiled = fromEnvelope ? interfaceFromEnvelope(opts.envelope, "canister") : await compileInterface(opts.did, "canister");
   if (compiled.failure) {
     const [code, at] = fromEnvelope ? ["E_ENVELOPE", opts.didLabel ?? "envelope"] : ["E_CANDID", opts.didLabel ?? "service.did"];
     for (const d of compiled.failure) diagnostics.push({ severity: "error", code, at, message: `${d.code}: ${d.message}` });
     return { ok: false, resolved: null, diagnostics, profiles: statuses };
   }
-  const { iface } = compiled;
+  return resolveWith(compiled.iface, opts, diagnostics, statuses);
+}
+
+/** A profile or pack for an EVM contract (spec section 15) rather than a Candid service. */
+const isEvmDoc = (doc) => doc.kind === "contract" || (doc.kind === "pack" && doc.binds.abi !== undefined);
+
+async function resolveWith(iface, opts, diagnostics, statuses, rebuild = null) {
+  const evm = iface.chain === "evm";
 
   const candidates = [
     ...(opts.profiles ?? []).map((p, i) => ({ ...p, explicit: true, label: p.label ?? `profile #${i + 1}` })),
@@ -78,7 +103,46 @@ async function resolveCompiled(opts, fromEnvelope) {
     const pid = profileId(doc);
     if (taken.has(pid)) continue; // the same document given twice (for example explicitly and through the pack search)
     const status = { name: doc.name, origin: doc.origin, kind: doc.kind, profile_id: pid, status: "applied", explicit: c.explicit };
-    if (doc.kind === "pack") {
+    if (isEvmDoc(doc) !== evm) {
+      if (!c.explicit) continue; // a pack for the other kind of interface can never apply
+      const what = doc.kind === "pack" ? "this pack" : `a ${doc.kind} profile`;
+      note("error", "E_CHAIN", "kind", `${what} describes ${isEvmDoc(doc) ? "an EVM contract" : "a Candid service"}, but the interface is ${evm ? "an EVM contract's ABI" : "a Candid service"}`);
+      statuses.push({ ...status, status: "invalid" });
+      continue;
+    }
+    const eip712 = evm ? eip712Of(doc) : null;
+    if (eip712?.errors.length) {
+      for (const d of eip712.errors) note("error", "E_EIP712", d.at, d.message);
+      statuses.push({ ...status, status: "invalid" });
+      continue;
+    }
+    if (evm && doc.kind === "pack") {
+      const m = matchAbiPack(iface, doc);
+      if (m.error) {
+        for (const d of m.error) note("error", "E_ABI", d.at, d.message);
+        statuses.push({ ...status, status: "invalid" });
+        continue;
+      }
+      if (!m.matched) {
+        const why = describeReasons(m.reasons);
+        if (c.explicit) note("error", "E_PACK_NOT_MATCHED", doc.name, `the contract lacks functions of the pack's binds.abi: ${why}`);
+        else note("info", "I_PACK_NOT_MATCHED", doc.name, `pack does not apply: ${why}`);
+        statuses.push({ ...status, status: "not_matched" });
+        continue;
+      }
+      note("info", "I_PACK_MATCHED", doc.name, "the contract has every function of the pack's binds.abi (same selectors, outputs and kind of call)");
+      items.push({ doc: translatePack(doc, m.functions, iface), pid, rebinding: false, apply: true, status, eip712 });
+    } else if (evm) {
+      // A contract profile binds the functions of its `binds.abi`; one that only describes messages binds none.
+      const own = parseAbi(doc.binds.abi ?? [], "binds.abi");
+      if (own.errors.length) {
+        for (const d of own.errors) note("error", "E_ABI", d.at, d.message);
+        statuses.push({ ...status, status: "invalid" });
+        continue;
+      }
+      checkDeployments(doc, note);
+      items.push({ doc, pid, rebinding: doc.binds.abi !== undefined && abiInterfaceId(own.functions) !== iface.abiId, apply: false, status, eip712 });
+    } else if (doc.kind === "pack") {
       const m = await matchPack(iface, doc);
       if (m.error) {
         for (const d of m.error) note("error", "E_CANDID", "binds.requires", `${d.code}: ${d.message}`);
@@ -101,6 +165,33 @@ async function resolveCompiled(opts, fromEnvelope) {
     taken.add(pid);
   }
 
+  if (evm) {
+    // The EIP-712 types of every profile and pack applied, merged: one name, one struct (spec section 15.9).
+    const types = {};
+    const owner = {};
+    const messages = new Set();
+    for (const item of [...items]) {
+      const clash = Object.entries(item.eip712.types).find(([n, members]) => Object.hasOwn(types, n) && jcs(types[n]) !== jcs(members));
+      if (clash) {
+        diagnostics.push({ severity: "error", code: "E_EIP712", at: `binds.eip712.types.${clash[0]}`, message: `the type ${clash[0]} differs from the one profile "${owner[clash[0]]}" declares; one name is one struct`, profile: item.doc.name });
+        statuses.push({ ...item.status, status: "invalid" });
+        items.splice(items.indexOf(item), 1);
+        continue;
+      }
+      for (const [n, members] of Object.entries(item.eip712.types)) {
+        types[n] = members;
+        owner[n] ??= item.doc.name;
+      }
+      for (const n of item.eip712.messages) messages.add(n);
+    }
+    const built = Object.keys(types).length ? rebuild({ types, messages: [...messages].sort(), label: "binds.eip712.types" }) : iface.methods.size ? { iface } : rebuild(null);
+    if (built.failure) {
+      for (const d of built.failure) diagnostics.push({ severity: "error", code: d.at.startsWith("binds.eip712") ? "E_EIP712" : "E_ABI", at: d.at, message: d.message });
+      return { ok: false, resolved: null, diagnostics, profiles: [...items.map((i) => ({ ...i.status, status: "invalid" })), ...statuses] };
+    }
+    iface = built.iface;
+  }
+
   const analysis = analyzeProfiles(iface, items, { attribute: true });
   diagnostics.push(...analysis.diagnostics);
   for (const item of analysis.ordered) {

package/src/resolved.mjs

@@ -10,7 +10,8 @@ export function buildTree(iface, methodName, side, tags) {
   for (const pos of positions(iface, methodName, side)) {
     const { ref: r, optional } = iface.unwrapOpt(pos.ref);
     const n = iface.node(r);
-    const node = { candid: n.kind === "primitive" ? n.primitive : iface.isBlob(r) ? "blob" : n.kind };
+    const node = iface.chain === "evm" ? { abi: iface.abiType(r) } : { candid: n.kind === "primitive" ? n.primitive : iface.isBlob(r) ? "blob" : n.kind };
+    if (n.kind === "vec" && typeof n.length === "number") node.length = n.length; // an EVM fixed-size array, T[k]
     if (optional) node.optional = true;
     const t = tags.at(pos, iface);
     if (t) node.tags = t;
@@ -40,21 +41,36 @@ export function buildTree(iface, methodName, side, tags) {
  */
 export function resolvedForm(iface, profiles, tags, diagnostics) {
   const methods = {};
+  const messages = {};
   for (const [name, m] of [...iface.methods.entries()].sort(([a], [b]) => (a < b ? -1 : 1))) {
     const mt = { ...tags.methodTags(name) };
     if (!mt.effect) {
-      mt.effect = m.mode === "update" || m.mode === "oneway"
+      // A signed message authorizes what someone else submits later (spec section 15.9): as conservative as an update.
+      mt.effect = m.mode === "update" || m.mode === "oneway" || m.mode === "message"
         ? { args: { kind: "write", irreversible: true }, origin: "default" }
         : { args: { kind: "read", irreversible: false }, origin: "default" };
     }
-    methods[name] = { mode: m.mode, tags: mt, args: buildTree(iface, name, "args", tags), results: buildTree(iface, name, "results", tags) };
+    if (m.mode === "message") {
+      const { encodeType, typeHash } = iface.messages.get(name); // an EIP-712 message: what a consumer matches a request by
+      messages[name] = { encode_type: encodeType, type_hash: typeHash, tags: mt, args: buildTree(iface, name, "args", tags) };
+      continue;
+    }
+    const f = iface.functions?.get(name); // an EVM function: what a consumer needs to match and decode calldata
+    const abi = f ? { selector: f.selector, signature: f.signature, state_mutability: f.stateMutability } : {};
+    methods[name] = { mode: m.mode, ...abi, tags: mt, args: buildTree(iface, name, "args", tags), results: buildTree(iface, name, "results", tags) };
   }
+  const bound = (doc) => ({
+    ...(doc.binds?.deployments ? { deployments: doc.binds.deployments } : {}),
+    ...(doc.binds?.eip712?.domain ? { eip712_domain: doc.binds.eip712.domain } : {}),
+  });
   return {
     format: "candid-profile-resolved",
     format_version: 0,
+    ...(iface.chain === "evm" ? { chain: "evm" } : {}),
     interface_id: iface.contract.identities.interface ?? null,
-    profiles: profiles.map(({ doc, pid }) => ({ name: doc.name, origin: doc.origin, profile_id: pid })),
+    profiles: profiles.map(({ doc, pid }) => ({ name: doc.name, origin: doc.origin, profile_id: pid, ...bound(doc) })),
     methods,
+    ...(Object.keys(messages).length ? { messages } : {}),
     diagnostics,
   };
 }

package/src/validate.mjs

@@ -4,6 +4,7 @@
  */
 import { profileId } from "./util.mjs";
 import { compileInterface } from "./compile.mjs";
+import { abiInterface, checkDeployments, eip712Of } from "./abi-iface.mjs";
 import { analyzeProfiles } from "./analyze.mjs";
 import { resolvedForm } from "./resolved.mjs";
 import { schemaDiagnostics } from "./schema-core.mjs";
@@ -26,6 +27,21 @@ export async function validateProfile(doc, opts) {
   }
   const pid = profileId(doc);
 
+  // An EVM contract profile or pack carries its own ABI and EIP-712 types (spec sections 15 and 15.9): it is
+  // checked against them.
+  if (doc.kind === "contract" || (doc.kind === "pack" && doc.binds.abi !== undefined)) {
+    const eip712 = eip712Of(doc);
+    for (const d of eip712.errors) diag("error", "E_EIP712", d.at, d.message);
+    if (eip712.errors.length) return { ok: false, profile_id: pid, diagnostics };
+    const compiled = abiInterface(doc.binds.abi ?? [], "binds.abi", "contract", doc.binds.eip712 ? { ...eip712, label: "binds.eip712.types" } : null);
+    if (compiled.failure) {
+      for (const d of compiled.failure) diag("error", d.at.startsWith("binds.eip712") ? "E_EIP712" : "E_ABI", d.at, d.message);
+      return { ok: false, profile_id: pid, diagnostics };
+    }
+    if (doc.kind === "contract") checkDeployments(doc, diag);
+    return finish(doc, pid, compiled.iface, false, diagnostics, opts);
+  }
+
   let didSource;
   if (doc.kind === "pack") didSource = doc.binds.requires;
   else if (opts.did !== undefined && opts.did !== null) didSource = opts.did;
@@ -40,10 +56,14 @@ export async function validateProfile(doc, opts) {
   }
   const { iface } = compiled;
   const rebinding = doc.kind === "canister" && doc.binds.interface_id !== iface.interfaceId;
-  const analysis = analyzeProfiles(iface, [{ doc, pid, rebinding, apply: false }], { attribute: false });
+  return finish(doc, pid, iface, rebinding, diagnostics, opts);
+}
 
-  const ok = !analysis.diagnostics.some((d) => d.severity === "error");
-  const result = { ok, profile_id: pid, interface_id: iface.interfaceId, methods: iface.methods.size, annotations: doc.annotations.length, diagnostics: analysis.diagnostics };
-  if (opts.resolved) result.resolved = resolvedForm(iface, [{ doc, pid }], analysis.layered, analysis.diagnostics);
+function finish(doc, pid, iface, rebinding, earlier, opts) {
+  const analysis = analyzeProfiles(iface, [{ doc, pid, rebinding, apply: false }], { attribute: false });
+  const diagnostics = [...earlier, ...analysis.diagnostics];
+  const ok = !diagnostics.some((d) => d.severity === "error");
+  const result = { ok, profile_id: pid, interface_id: iface.interfaceId, methods: iface.methods.size, annotations: doc.annotations.length, diagnostics };
+  if (opts.resolved) result.resolved = resolvedForm(iface, [{ doc, pid }], analysis.layered, diagnostics);
   return result;
 }