@meantjs/profile 0.0.0-stage → 0.2.0

package/src/abi-iface.mjs

@@ -0,0 +1,112 @@
+/**
+ * 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`)
+ */
+import { Iface } from "./iface.mjs";
+import { idlHash } from "./idl.mjs";
+import { AbiError, abiInterfaceId, componentKey, parseAbi, readAddress } from "./abi.mjs";
+
+export class AbiIface extends Iface {
+  /** @param functions from parseAbi */
+  constructor(envelope, functions, label) {
+    super(envelope, label);
+    this.chain = "evm";
+    this.functions = new Map(functions.map((f) => [f.name, f]));
+  }
+  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`)
+ * @returns {{ iface: AbiIface } | { failure: { at: string, message: string }[] }}
+ */
+export function abiInterface(entries, label = "abi", ifaceLabel = "contract") {
+  const { functions, errors } = parseAbi(entries, label);
+  if (errors.length) return { failure: errors };
+  if (functions.length === 0) return { failure: [{ 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 }) };
+  });
+  if (failure.length) return { failure };
+  const service = add({ kind: "service", methods });
+  const envelope = {
+    contract: { types, declarations: [], actor: { kind: "service", service }, identities: { interface: abiInterfaceId(functions) } },
+    extensions: { "org.candid-core.field-names/v1": names },
+  };
+  return { iface: new AbiIface(envelope, functions, ifaceLabel) };
+}
+
+/**
+ * `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,114 @@
+/**
+ * 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.
+ */
+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;
+    const args = a.tag === "intent" && typeof a.args?.template === "string" && method ? { ...a.args, template: mapTemplate(a.args.template, placeholder(method)) } : a.args;
+    return { ...a, at: at(a.at), args };
+  });
+  return { ...pack, annotations };
+}