@meantjs/profile 0.1.0 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meantjs/profile",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Candid Profile resolver: validates profiles, matches packs by Candid subtyping, merges layers (spec section 8) and emits the resolved form (spec section 10).",
   "license": "Apache-2.0",
   "repository": {
@@ -19,6 +19,9 @@
     "icrc-1",
     "icrc-2",
     "profile",
+    "evm",
+    "erc-20",
+    "erc-7730",
     "resolver",
     "json-schema"
   ],
@@ -39,6 +42,10 @@
       "types": "./src/browser.d.mts",
       "default": "./src/browser.mjs"
     },
+    "./evm": {
+      "types": "./src/evm.d.mts",
+      "default": "./src/evm.mjs"
+    },
     "./schema.json": "./data/profile-v0.schema.json",
     "./packs/*": "./data/packs/*",
     "./package.json": "./package.json"

package/src/abi-iface.mjs

@@ -0,0 +1,154 @@
+/**
+ * An EVM contract interface as the resolver sees one (spec section 15, D-054): its function fragments laid out as the
+ * graph a Candid interface compiles to, so that addresses, tags, merging and the resolved form work unchanged.
+ *
+ *   a function       a method; `view` and `pure` are queries, `nonpayable` and `payable` updates
+ *   its parameters   one record at argument index 0 (`transfer(0).to`); a function without parameters has no argument
+ *   its outputs      the result tuple (`balanceOf->(0)`)
+ *   a tuple          a record whose fields keep the ABI order; a named component's id is the Candid hash of its name,
+ *                    an unnamed one's is its position (`#1`)
+ *   T[] and T[k]     a vector (`[]`); T[k] keeps its length
+ *   anything else    a primitive named by its canonical ABI type (`uint256`, `address`, `bytes32`, `string`)
+ *   an EIP-712       a method of mode "message" (spec section 15.9) whose one argument is the struct, a record of its
+ *   message          members in order (`PermitSingle(0).details.amount`); it has no results
+ */
+import { Iface } from "./iface.mjs";
+import { idlHash } from "./idl.mjs";
+import { AbiError, abiInterfaceId, componentKey, eip712AbiType, eip712TypeHash, encodeType, parseAbi, parseEip712Types, readAddress } from "./abi.mjs";
+
+export class AbiIface extends Iface {
+  /**
+   * @param functions from parseAbi
+   * @param eip712  { types, messages } (spec section 15.9): the struct types, and which of them are messages
+   */
+  constructor(envelope, functions, label, eip712 = { types: {}, messages: [] }) {
+    super(envelope, label);
+    this.chain = "evm";
+    this.functions = new Map(functions.map((f) => [f.name, f]));
+    /** The identity of the functions alone: what a contract profile's `binds.abi` binds to (spec section 15.1). */
+    this.abiId = abiInterfaceId(functions);
+    this.structs = eip712.types;
+    this.messages = new Map(eip712.messages.map((name) => [name, { encodeType: encodeType(eip712.types, name), typeHash: eip712TypeHash(eip712.types, name) }]));
+  }
+  resolve(addr) {
+    const r = super.resolve(addr);
+    if (r.error && addr.kind !== "type" && !this.methods.has(addr.method) && Object.hasOwn(this.structs, addr.method)) {
+      return { error: `${addr.method} is an EIP-712 type but not a message: tag its name with intent to make it one, or address it through a message that contains it` };
+    }
+    return r;
+  }
+  isBlob(ref) {
+    const p = this.prim(ref);
+    return p === "bytes" || /^bytes\d+$/.test(p ?? "");
+  }
+  isAccount() { return false; }
+  /** The canonical ABI type of a position: `uint256`, `address[]`, `(address,uint256)`. */
+  describeType(ref) {
+    const n = this.types[ref];
+    if (n.kind === "primitive") return n.primitive;
+    if (n.kind === "vec") return `${this.describeType(n.inner)}[${n.length ?? ""}]`;
+    return `(${n.fields.map((f) => this.describeType(f.type)).join(",")})`;
+  }
+  /** The `abi` of a resolved-form node: the primitive's type, `tuple` or `array`. */
+  abiType(ref) {
+    const n = this.types[ref];
+    return n.kind === "primitive" ? n.primitive : n.kind === "record" ? "tuple" : "array";
+  }
+}
+
+/**
+ * @param entries  an ABI: human-readable fragments or JSON ABI entries (parseAbi)
+ * @param label    how diagnostics name it (`binds.abi`, `abi`)
+ * @param eip712   { types, messages, label } (spec section 15.9): struct types already read by parseEip712Types, the
+ *                 names of those that are messages, and how diagnostics name the types; null for none
+ * @param opts.allowEmpty  an interface with no function and no message is not refused (resolveService adds the
+ *                 messages of its profiles later)
+ * @returns {{ iface: AbiIface } | { failure: { at: string, message: string }[] }}
+ */
+export function abiInterface(entries, label = "abi", ifaceLabel = "contract", eip712 = null, { allowEmpty = false } = {}) {
+  const { functions, errors } = parseAbi(entries, label);
+  if (errors.length) return { failure: errors };
+  const messages = eip712?.messages ?? [];
+  if (functions.length === 0 && messages.length === 0 && !allowEmpty) return { failure: [eip712 ? { at: eip712.label, message: "the ABI has no functions and no type is a message (tag a type's name with intent)" } : { at: label, message: "the ABI has no functions" }] };
+  const types = [];
+  const names = [];
+  const failure = [];
+  const add = (node) => types.push(node) - 1;
+  const build = (t, where) => {
+    if (t.kind === "tuple") {
+      const ref = add(null);
+      const ids = new Map();
+      const fields = t.components.map((c, i) => {
+        const id = c.name === null ? i : idlHash(c.name);
+        const key = componentKey(c, i);
+        if (ids.has(id)) failure.push({ at: where, message: `components ${ids.get(id)} and ${key} have the same field id ${id}; rename one` });
+        ids.set(id, key);
+        names.push([ref, id, key]);
+        return { id, type: build(c.type, `${where}.${key}`) };
+      });
+      types[ref] = { kind: "record", fields };
+      return ref;
+    }
+    if (t.kind === "array") {
+      const ref = add(null);
+      types[ref] = { kind: "vec", inner: build(t.element, `${where}[]`), length: t.length };
+      return ref;
+    }
+    return add({ kind: "primitive", primitive: t.kind === "uint" || t.kind === "int" ? `${t.kind}${t.bits}` : t.kind === "fixedbytes" ? `bytes${t.size}` : t.kind });
+  };
+  const methods = functions.map((f) => {
+    const args = f.inputs.length ? [build({ kind: "tuple", components: f.inputs }, `${f.name}(0)`)] : [];
+    const results = f.outputs.map((o, i) => build(o.type, `${f.name}->(${i})`));
+    const mode = f.stateMutability === "view" || f.stateMutability === "pure" ? "query" : "update";
+    return { name: f.name, function: add({ kind: "func", mode, args, results }) };
+  });
+  for (const name of messages) {
+    const at = `${eip712.label}.${name}`;
+    if (functions.some((f) => f.name === name)) {
+      failure.push({ at, message: `a function and a message are both named ${name}; an address names one of them` });
+      continue;
+    }
+    methods.push({ name, function: add({ kind: "func", mode: "message", args: [build(eip712AbiType(eip712.types, name), `${name}(0)`)], results: [] }) });
+  }
+  if (failure.length) return { failure };
+  const service = add({ kind: "service", methods });
+  const structs = eip712?.types ?? {};
+  const envelope = {
+    contract: { types, declarations: [], actor: { kind: "service", service }, identities: { interface: abiInterfaceId(functions, structs) } },
+    extensions: { "org.candid-core.field-names/v1": names },
+  };
+  return { iface: new AbiIface(envelope, functions, ifaceLabel, { types: structs, messages }) };
+}
+
+/**
+ * The messages a profile or pack declares (spec section 15.9): the types of `binds.eip712` whose name the same
+ * document tags with `intent`. Returns { types, messages, errors }.
+ */
+export function eip712Of(doc, label = "binds.eip712.types") {
+  const spec = doc.binds?.eip712;
+  if (spec === undefined) return { types: {}, messages: [], errors: [] };
+  const { types, errors } = parseEip712Types(spec.types, label);
+  const messages = [...new Set(doc.annotations.filter((a) => a.tag === "intent" && Object.hasOwn(types, a.at)).map((a) => a.at))].sort();
+  return { types, messages, errors };
+}
+
+/**
+ * `binds.deployments` of a contract profile: an address in mixed case must match its EIP-55 checksum, and a deployment
+ * is listed once. `diag(severity, code, at, message)`.
+ */
+export function checkDeployments(doc, diag) {
+  const seen = new Set();
+  (doc.binds.deployments ?? []).forEach((d, i) => {
+    const at = `binds.deployments[${i}]`;
+    let address;
+    try {
+      address = readAddress(d.address);
+    } catch (e) {
+      if (!(e instanceof AbiError)) throw e;
+      return diag("error", "E_ADDRESS_CHECKSUM", `${at}.address`, e.message);
+    }
+    const key = `${d.chain_id}:${address}`;
+    if (seen.has(key)) diag("warning", "W_DUPLICATE", at, `chain ${d.chain_id} ${address} is listed twice`);
+    seen.add(key);
+  });
+}

package/src/abi-pack.mjs

@@ -0,0 +1,117 @@
+/**
+ * EVM packs (spec section 15, D-054). A pack with `binds.abi` applies to a contract that has every one of its
+ * functions: the same selector (so the same name and parameter types), the same output types, and the same kind of
+ * call (a query, or an update that is payable exactly when the pack's is). There is no subtyping.
+ *
+ * Parameter names are not part of a selector, and contracts name the parameters of one standard differently (EIP-20
+ * says `_to`, OpenZeppelin `to`, WETH `dst`). A pack's addresses and template placeholders use the pack's own names;
+ * when the pack applies, they are rewritten to the contract's names, component by component, by position. So is an
+ * amount's `token` path (spec section 15.9).
+ */
+import { parseAddress, parseRelPath } from "./address.mjs";
+import { componentKey, parseAbi, typeString } from "./abi.mjs";
+
+/**
+ * @param iface  an AbiIface
+ * @param pack   a schema-valid pack document with `binds.abi`
+ * @returns {{ matched: boolean, reasons: { at: string, message: string }[], relaxed: [], functions: object[] } | { error: { at: string, message: string }[] }}
+ */
+export function matchAbiPack(iface, pack) {
+  const { functions, errors } = parseAbi(pack.binds.abi, "binds.abi");
+  if (errors.length) return { error: errors };
+  const reasons = [];
+  const kind = (f) => (f.stateMutability === "view" || f.stateMutability === "pure" ? "a query (view or pure)" : f.stateMutability === "payable" ? "payable" : "not payable");
+  const outputs = (f) => `(${f.outputs.map((o) => typeString(o.type)).join(",")})`;
+  for (const f of functions) {
+    const g = iface.functions.get(f.name);
+    if (!g || g.selector !== f.selector) reasons.push({ at: f.name, message: `no function ${f.typeSignature} (selector ${f.selector})` });
+    else if (outputs(g) !== outputs(f)) reasons.push({ at: f.name, message: `returns ${outputs(g)}, the pack's ${outputs(f)}` });
+    else if (kind(g) !== kind(f)) reasons.push({ at: f.name, message: `is ${kind(g)}, the pack's ${kind(f)}` });
+  }
+  return { matched: reasons.length === 0, reasons, relaxed: [], functions };
+}
+
+/** A path through the pack's type, spelled with the contract's names; null when the pack's own type lacks it. */
+function mapSegs(packT, ownT, segs) {
+  let p = packT;
+  let c = ownT;
+  let out = "";
+  for (const s of segs) {
+    if (s.kind === "elem") {
+      if (p.kind !== "array") return null;
+      out += "[]";
+      p = p.element;
+      c = c.element;
+      continue;
+    }
+    if (p.kind !== "tuple") return null;
+    const i = p.components.findIndex((comp, j) => componentKey(comp, j) === s.label);
+    if (i < 0) return null;
+    out += `.${componentKey(c.components[i], i)}`;
+    p = p.components[i].type;
+    c = c.components[i].type;
+  }
+  return out;
+}
+
+const tupleOf = (params) => ({ kind: "tuple", components: params });
+
+/** A template with each placeholder rewritten by `map` (null keeps it); escapes and literal text are kept as written. */
+function mapTemplate(template, map) {
+  let out = "";
+  for (let i = 0; i < template.length; i++) {
+    const c = template[i];
+    if ((c === "{" || c === "}" || c === "[" || c === "]") && template[i + 1] === c) {
+      out += c + c;
+      i++;
+      continue;
+    }
+    if (c === "{") {
+      const end = template.indexOf("}", i);
+      if (end < 0) return template; // does not parse: left for E_TEMPLATE
+      const path = template.slice(i + 1, end);
+      out += `{${map(path) ?? path}}`;
+      i = end;
+      continue;
+    }
+    out += c;
+  }
+  return out;
+}
+
+/**
+ * The pack with its addresses and templates in the contract's names. `functions` are the pack's (matchAbiPack).
+ * A document whose names already agree comes back equal to the original.
+ */
+export function translatePack(pack, functions, iface) {
+  const mine = new Map(functions.map((f) => [f.name, f]));
+  const pair = (name) => (mine.has(name) && iface.functions.has(name) ? [mine.get(name), iface.functions.get(name)] : null);
+  const at = (text) => {
+    const addr = parseAddress(text);
+    const fs = addr && addr.kind !== "type" ? pair(addr.method) : null;
+    if (!fs || addr.kind === "method") return text;
+    const [p, c] = fs;
+    if (addr.kind === "arg") {
+      const mapped = addr.index === 0 && p.inputs.length ? mapSegs(tupleOf(p.inputs), tupleOf(c.inputs), addr.segs) : null;
+      return mapped === null ? text : `${addr.method}(0)${mapped}`;
+    }
+    const out = p.outputs[addr.index];
+    const mapped = out ? mapSegs(out.type, c.outputs[addr.index].type, addr.segs) : null;
+    return mapped === null ? text : `${addr.method}->(${addr.index})${mapped}`;
+  };
+  const placeholder = (method) => (path) => {
+    const fs = pair(method);
+    const rel = parseRelPath(path);
+    if (!fs || !rel || (rel.index ?? 0) !== 0 || !fs[0].inputs.length) return null;
+    const mapped = mapSegs(tupleOf(fs[0].inputs), tupleOf(fs[1].inputs), rel.segs);
+    return mapped === null ? null : `${rel.index === null ? "" : "(0)"}${rel.index === null ? mapped.slice(1) : mapped}`;
+  };
+  const annotations = pack.annotations.map((a) => {
+    const method = parseAddress(a.at)?.method;
+    let args = a.args;
+    if (a.tag === "intent" && typeof a.args?.template === "string" && method) args = { ...a.args, template: mapTemplate(a.args.template, placeholder(method)) };
+    if (a.tag === "amount" && typeof a.args?.token === "string" && method) args = { ...a.args, token: placeholder(method)(a.args.token) ?? a.args.token };
+    return { ...a, at: at(a.at), args };
+  });
+  return { ...pack, annotations };
+}