@meantjs/profile 0.4.0 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meantjs/profile",
-  "version": "0.4.0",
+  "version": "0.6.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": {

package/src/analyze.mjs

@@ -9,7 +9,7 @@ import { TagIndex, LayeredTags, positions } from "./tags.mjs";
 import {
   NUMERIC, METHOD_TAGS, CASE_TAGS, CONFIRM_KINDS, STALE_CODES, VALUE_CONVERSION_TAGS, EVM_LATER_TAGS,
   checkApplicability, checkDynamic, parseTemplate, outcomeCoverage, caseTargetError, otherCase, overlap, defaultEffect,
-  tokenPathError, grantError,
+  tokenPathError, grantError, pinError,
 } from "./checks.mjs";
 
 /** Spec section 8, highest precedence first. */
@@ -29,7 +29,9 @@ function buildLayers(entries, keep = () => true) {
 
 /**
  * @param iface  the interface every address resolves against
- * @param items  [{ doc, pid, rebinding, apply }]; `apply` marks a pack that matched a service and is applied to it
+ * @param items  [{ doc, pid, rebinding, bound, apply }]; `apply` marks a pack that matched a service and is applied to it;
+ *   `bound` is { at, id, given }, what a profile binds to against what was given, when it is not `binds.interface_id`
+ *   against the interface's id (a contract profile binds by its own ABI, spec section 15.3)
  * @param opts.attribute  add `profile` to each diagnostic (multi-profile output)
  * @returns { diagnostics, layered, ordered, stale }  `ordered` is items by precedence; `stale` the stale items
  */
@@ -44,11 +46,24 @@ export function analyzeProfiles(iface, items, { attribute = true } = {}) {
       item.diags.push(d);
     };
   }
-  const interfaceId = iface.interfaceId;
+  const boundOf = (item) => item.bound ?? { at: "binds.interface_id", id: item.doc.binds.interface_id, given: iface.interfaceId };
+
+  // A pin (`fixed`, spec 15.4, D-058) holds the value the profile's words were written for. A profile with a pin that
+  // does not hold keeps only its effects, without grants, and its pins that hold: never its words without the pin. A
+  // pin's problem is always an error, never a pack annotation skipped.
+  const unpinned = new Set();
+  const pinFailed = (item, code, at, message) => {
+    unpinned.add(item);
+    item.diag("error", code, at, `${message}; this profile keeps only its effects (without grants) and its pins that hold, since its words were written for the pinned value (spec section 15.4)`);
+  };
+  const pins = new Map(); // position key -> { value, item, at }: every profile pins a position to one value (spec 15.4)
+  const badPins = new Set(); // pin entries that do not hold, left out of the resolved form
 
   for (const item of ordered) {
     if (item.rebinding) {
-      item.diag("warning", "W_REBOUND", "binds.interface_id", `profile is bound to ${item.doc.binds.interface_id} but the given interface is ${interfaceId}; checking whether every address still resolves`);
+      const { at, id, given } = boundOf(item);
+      const what = at === "binds.abi" ? "ABI" : "interface";
+      item.diag("warning", "W_REBOUND", at, `profile is bound to ${id} but the given ${what} is ${given}; checking whether every address still resolves`);
     }
   }
 
@@ -64,16 +79,28 @@ export function analyzeProfiles(iface, items, { attribute = true } = {}) {
       let a = original;
       const at = a.at;
       const addr = parseAddress(at);
-      if (!addr) { diag("error", "E_ADDR_SYNTAX", at, "address does not parse"); continue; }
-      if (doc.kind === "pack" && addr.kind === "type") { diag("error", "E_PACK_TYPE_REF", at, "packs must use method addresses (declaration names are not standardized)"); continue; }
+      const pinned = a.tag === "fixed";
+      const fail = pinned ? (code, message) => pinFailed(item, code, at, message) : (code, message) => diag("error", code, at, message);
+      if (!addr) { fail("E_ADDR_SYNTAX", "address does not parse"); continue; }
+      if (doc.kind === "pack" && addr.kind === "type") { fail("E_PACK_TYPE_REF", "packs must use method addresses (declaration names are not standardized)"); continue; }
       const res = iface.resolve(addr);
       if (res.error) {
         // A pack applied to a service that is a narrower subtype (fewer result cases, fewer optional fields) cannot
         // address what is not there. That is expected, not an error in the pack.
-        if (item.apply) diag("info", "I_PACK_ANNOTATION_SKIPPED", at, `${a.tag}: ${res.error}`);
-        else diag("error", res.code ?? "E_ADDR_UNRESOLVED", at, res.error);
+        if (item.apply && !pinned) diag("info", "I_PACK_ANNOTATION_SKIPPED", at, `${a.tag}: ${res.error}`);
+        else fail(res.code ?? "E_ADDR_UNRESOLVED", res.error);
         continue;
       }
+      if (pinned) {
+        const prev = pins.get(res.key);
+        const value = String(a.args.value).toLowerCase();
+        if (prev && prev.value !== value) {
+          const where = prev.item === item ? `"${prev.at}"` : `profile "${prev.item.doc.name}" "${prev.at}"`;
+          pinFailed(item, "E_CONFLICT", at, `fixed pins this position to ${a.args.value}, where ${where} pins it to another value`);
+          continue;
+        }
+        if (!prev) pins.set(res.key, { value, item, at });
+      }
       if (addr.kind === "type") {
         const others = (iface.aliases.get(iface.decls.get(addr.decl)) ?? []).filter((n) => n !== addr.decl);
         if (others.length) diag("warning", "W_STRUCTURAL_ALIAS", at, `declaration "${addr.decl}" is structurally identical to ${others.map((n) => `"${n}"`).join(", ")}; the tag reaches every one of them`);
@@ -252,6 +279,14 @@ export function analyzeProfiles(iface, items, { attribute = true } = {}) {
       }
       continue;
     }
+    if (a.tag === "fixed") {
+      const why = pinError(iface, addr, res, a.args.value);
+      if (why) {
+        badPins.add(e);
+        pinFailed(item, why.code, at, why.message);
+      }
+      continue;
+    }
     if (res.method) {
       if (a.tag !== "describe") diag("error", "E_TAG_TARGET", at, `${a.tag} is a value tag; address a value, not a method`);
       continue;
@@ -326,12 +361,19 @@ export function analyzeProfiles(iface, items, { attribute = true } = {}) {
     }
   }
 
-  // Binding (spec section 7): a canister profile whose interface changed is stale when anything no longer holds.
+  // Binding (spec sections 7 and 15.3): a canister or contract profile whose interface changed is stale when anything
+  // no longer holds.
   const stale = new Set(ordered.filter((item) => item.rebinding && item.diags.some((d) => STALE_CODES.has(d.code))));
   // A stale profile must not supply value-conversion tags, and a dropped pack annotation is not applied: keep both
-  // out of the merged result.
-  const keep = (e) => !dropped.has(e) && !(stale.has(e.item) && VALUE_CONVERSION_TAGS.has(e.ann.tag));
-  const final = stale.size || dropped.size ? buildLayers(entries, keep) : tags;
+  // out of the merged result. A profile with a pin that does not hold supplies its effects, without grants, and its
+  // pins that hold (spec 15.4, D-058).
+  for (const e of entries) {
+    if (!unpinned.has(e.item) || e.ann.tag !== "effect" || e.entry.args.grant === undefined) continue;
+    const { grant, ...args } = e.entry.args;
+    e.entry.args = args;
+  }
+  const keep = (e) => !dropped.has(e) && !badPins.has(e) && !(stale.has(e.item) && VALUE_CONVERSION_TAGS.has(e.ann.tag)) && !(unpinned.has(e.item) && e.ann.tag !== "effect" && e.ann.tag !== "fixed");
+  const final = stale.size || dropped.size || unpinned.size ? buildLayers(entries, keep) : tags;
 
   // Overrides: the same tag at the same position in a lower layer (W_OVERRIDDEN, spec section 8).
   if (final.layers.length > 1) {
@@ -372,7 +414,7 @@ export function analyzeProfiles(iface, items, { attribute = true } = {}) {
   }
 
   for (const item of stale) {
-    item.diag("error", "E_STALE", "binds.interface_id", "the interface changed and some annotations no longer hold; value-conversion tags must not be used (the resolved form omits this profile's value-conversion tags)");
+    item.diag("error", "E_STALE", boundOf(item).at, "the interface changed and some annotations no longer hold; value-conversion tags must not be used (the resolved form omits this profile's value-conversion tags)");
   }
   return { diagnostics, layered: final, ordered, stale };
 }

package/src/browser.mjs

@@ -35,7 +35,8 @@ export const PROFILE_SCHEMA = schema;
 
 /**
  * The standard packs (copies of packs/*.profile.json whose kind is "pack"), sorted by file name, in the shape
- * `loadPacks` returns. The standard contract profiles there (Permit2, DAI's permit) are under `./packs/*` too.
+ * `loadPacks` returns. The standard contract profiles there (Permit2, DAI's permit, USDC under its two domain names,
+ * x402's two Permit2 payments) are under `./packs/*` too.
  */
 export const STANDARD_PACKS = Object.freeze([
   { file: "erc20.profile.json", doc: erc20 },

package/src/checks.mjs

@@ -1,6 +1,7 @@
 /**
  * Per-annotation semantic checks (spec sections 3 to 6). Moved verbatim from scripts/validate.mjs.
  */
+import { AbiError, readAddress } from "./abi.mjs";
 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. */
@@ -20,6 +21,24 @@ export const CONFIRM_KINDS = new Set(["transfer", "approve", "admin", "destroy"]
 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", "E_CASE_OVERLAP", "E_CASE_EFFECT", "E_TOKEN_PATH", "E_GRANT"]);
 
+/**
+ * Why a pin (`fixed`, spec 15.4, D-058) does not hold, as `{ code, message }`, or null. A pin sits on an `address` in the
+ * arguments of an EVM function or message, where a consumer reads it from what is sent or signed before any text, and
+ * its value is an address (§15.2: in mixed case, with its EIP-55 checksum).
+ */
+export function pinError(iface, addr, res, value) {
+  if (res.method || addr.kind !== "arg") return { code: "E_TAG_TARGET", message: "fixed pins a value in the arguments of a function or a message, where a consumer reads it before it shows text" };
+  const wrong = checkApplicability(iface, "fixed", res.ref);
+  if (wrong) return { code: "E_TAG_NOT_APPLICABLE", message: wrong };
+  try {
+    readAddress(String(value));
+  } catch (e) {
+    if (!(e instanceof AbiError)) throw e;
+    return { code: "E_ADDRESS_CHECKSUM", message: `fixed: ${e.message}` };
+  }
+  return null;
+}
+
 export function checkApplicability(iface, tag, ref) {
   const { ref: r } = iface.unwrapOpt(ref);
   const p = iface.prim(r);
@@ -33,6 +52,9 @@ export function checkApplicability(iface, tag, 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)}`;
+    case "fixed":
+      if (iface.chain !== "evm") return "fixed pins an EVM address; a Candid position cannot carry it yet (spec section 15.4)";
+      return p === "address" ? null : `fixed needs an address, found ${iface.describeType(ref)}`;
     default: return null;
   }
 }

package/src/resolve.mjs

@@ -141,7 +141,9 @@ async function resolveWith(iface, opts, diagnostics, statuses, rebuild = null) {
         continue;
       }
       checkDeployments(doc, note);
-      items.push({ doc, pid, rebinding: doc.binds.abi !== undefined && abiInterfaceId(own.functions) !== iface.abiId, apply: false, status, eip712 });
+      // It binds by the identity of its own ABI (spec section 15.1), compared with the given ABI's functions only.
+      const bound = doc.binds.abi === undefined ? null : { at: "binds.abi", id: abiInterfaceId(own.functions), given: iface.abiId };
+      items.push({ doc, pid, rebinding: bound !== null && bound.id !== bound.given, bound, apply: false, status, eip712 });
     } else if (doc.kind === "pack") {
       const m = await matchPack(iface, doc);
       if (m.error) {

package/src/served.mjs

@@ -2,11 +2,11 @@
  * A profile served by its canister (spec section 8.1, D-048): the public custom section `icp:public candid:profile`,
  * read by a consumer through a certified `read_state` at `/canister/<id>/metadata/candid:profile`.
  *
- * This module reads the section's bytes; it does not fetch them, so the library keeps no agent dependency (the kit's
- * `fetch` does the network part). What it checks is what only a served profile can get wrong: the bytes are UTF-8
- * JSON of at most 1 MiB, the document is a `canister` profile of origin `author`, and its `binds.canister_id`, when
- * given, is the canister that served it. Everything else (the schema, the binding to the interface the same canister
- * serves as `candid:service`, every tag) is `resolveService`'s, as for any profile.
+ * This module reads the section's bytes; it does not fetch them, so the library keeps no agent dependency (the caller
+ * does the network part, for example with `@icp-sdk/core`'s `readState`). What it checks is what only a served profile
+ * can get wrong: the bytes are UTF-8 JSON of at most 1 MiB, the document is a `canister` profile of origin `author`,
+ * and its `binds.canister_id`, when given, is the canister that served it. Everything else (the schema, the binding to
+ * the interface the same canister serves as `candid:service`, every tag) is `resolveService`'s, as for any profile.
  *
  * New diagnostic code (spec section 13): E_SERVED.
  */
@@ -23,7 +23,7 @@ const decoder = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
 /**
  * @param bytes          the content of the canister's `candid:profile` metadata (a Uint8Array)
  * @param opts.canisterId the textual id of the canister that served it; null only before the module is installed
- *                       anywhere (the kit's `embed`), which leaves `binds.canister_id` unchecked
+ *                       anywhere (a section added to a built module), which leaves `binds.canister_id` unchecked
  * @param opts.label     how diagnostics name the input (default "candid:profile")
  * @returns { ok, doc, diagnostics }  `doc` is the parsed profile, or null when it cannot be used (E_SERVED)
  */