@meantjs/profile 0.3.0 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meantjs/profile",
-  "version": "0.3.0",
+  "version": "0.5.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,
+  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`);
@@ -147,6 +174,18 @@ export function analyzeProfiles(iface, items, { attribute = true } = {}) {
     }
   };
 
+  /**
+   * A grant that does not hold (spec 5.3, D-056). A pack applied to a service loses only its grant, never the effect:
+   * dropping the effect would leave a transfer or approve with the default effect, which needs no confirmation.
+   */
+  const grants = []; // effects whose grant holds, checked again once dropped tags are known
+  const badGrant = (e, diag, why) => {
+    if (!e.item.apply) return diag("error", "E_GRANT", e.ann.at, why);
+    const { grant, ...args } = e.entry.args;
+    e.entry.args = args;
+    e.item.diag("info", "I_PACK_ANNOTATION_SKIPPED", e.ann.at, `effect grant dropped, the effect kept: E_GRANT: ${why}`);
+  };
+
   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) {
@@ -167,8 +206,10 @@ export function analyzeProfiles(iface, items, { attribute = true } = {}) {
       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);
+      if (a.tag === "effect") {
+        checkEffectMode(m, a.args, diag, at);
+        if (a.args.grant) badGrant(e, diag, "a grant sits on the effect of a method, not of a case, in this version (D-056)");
+      } else checkTemplate(item, addr.method, a.args.template, diag, at, addr);
       caseEntries.push({ e, diag });
       continue;
     }
@@ -176,6 +217,11 @@ export function analyzeProfiles(iface, items, { attribute = true } = {}) {
       const m = res.method;
       const methodName = addr.method;
       if (a.tag === "effect") checkEffectMode(m, a.args, diag, at);
+      if (a.tag === "effect" && a.args.grant) {
+        const why = grantError(iface, tags, methodName, a.args);
+        if (why) badGrant(e, diag, why);
+        else grants.push({ e, diag });
+      }
       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);
@@ -233,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;
@@ -289,9 +343,14 @@ export function analyzeProfiles(iface, items, { attribute = true } = {}) {
     }
   }
 
-  // Dropping a value tag can leave an idempotency stamp without its timestamp tag: drop that idempotency too.
+  // Dropping a value tag can leave an idempotency stamp without its timestamp tag: drop that idempotency too. It can
+  // also leave a grant without the amount, timestamp or account tag it needs.
   if (dropped.size) {
     const without = buildLayers(entries, (e) => !dropped.has(e));
+    for (const { e, diag } of grants) {
+      const why = !dropped.has(e) && grantError(iface, without, e.addr.method, e.entry.args);
+      if (why) badGrant(e, diag, `${why} (a tag it needs was dropped in this service)`);
+    }
     for (const e of entries) {
       if (!e.item.apply || e.ann.tag !== "idempotency" || dropped.has(e)) continue;
       const r = iface.resolveRel(e.addr.method, "args", e.ann.args.stamp);
@@ -302,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) {
@@ -348,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, x402's Permit2 payment) 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. */
@@ -18,7 +19,25 @@ export const CASE_TAGS = new Set(["intent", "effect"]);
 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", "E_CASE_OVERLAP", "E_CASE_EFFECT", "E_TOKEN_PATH"]);
+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);
@@ -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;
   }
 }
@@ -57,6 +79,55 @@ export function tokenPathError(iface, addr, token) {
   return null;
 }
 
+/**
+ * An effect's grant (spec 5.3, D-056): who may take the tokens, how many and until when, as positions in the arguments
+ * of the method the effect is on. `tags` is the merged view: the amount, timestamp and account tags a grant needs may
+ * come from another profile. The reason it is wrong, or null.
+ */
+export function grantError(iface, tags, methodName, { kind, grant }) {
+  if (kind !== "transfer" && kind !== "approve") return `a grant goes with effect kind transfer or approve, not ${kind}`;
+  if ((grant.spender === undefined) === (grant.to === undefined)) return "a grant names exactly one of spender and to";
+  if (kind === "approve" && grant.to !== undefined) return "an approve's grant names a spender: an allowance is taken by its spender, not paid to it";
+  const at = (name, rel, mayBeAbsent) => {
+    const p = parseRelPath(rel);
+    const r = iface.resolveRel(methodName, "args", rel);
+    const what = `grant ${name} ${JSON.stringify(rel)}`;
+    if (!p || r.error) return { error: `${what}: ${r.error ?? "not a relative path"}` };
+    if (p.segs.some((s) => s.kind === "elem")) return { error: `${what} steps into []: a grant covers one token, so a request that grants several has none` };
+    // The value must be in every call: no case of a variant on the way, and no opt unless it may be left out.
+    let cur = iface.methods.get(methodName).args[p.index ?? 0];
+    let optional = false;
+    for (const s of p.segs) {
+      const u = iface.unwrapOpt(cur);
+      optional ||= u.optional;
+      const n = iface.node(u.ref);
+      if (n.kind === "variant") return { error: `${what} passes through a case of a variant, so a call need not hold it` };
+      cur = n.fields.find((f) => f.id === s.id).type;
+    }
+    if ((optional || iface.unwrapOpt(cur).optional) && !mayBeAbsent) return { error: `${what} is optional, but a grant needs its ${name} in every call` };
+    return { r, t: tags.at(r, iface) ?? {} };
+  };
+  const who = grant.spender !== undefined ? "spender" : "to";
+  const party = at(who, grant[who], false);
+  if (party.error) return party.error;
+  if (iface.prim(party.r.ref) !== "address" && !party.t.account) {
+    return `grant ${who} ${JSON.stringify(grant[who])} is ${iface.describeType(party.r.ref)}; it must be an address or carry an account tag`;
+  }
+  const amount = at("amount", grant.amount, false);
+  if (amount.error) return amount.error;
+  const p = iface.prim(amount.r.ref);
+  if (p !== "bool") {
+    if (!amount.t.amount) return `grant amount ${JSON.stringify(grant.amount)} is ${iface.describeType(amount.r.ref)} without an amount tag; it must carry one, or be a bool`;
+    if (!/^(nat|uint)/.test(p)) return `grant amount ${JSON.stringify(grant.amount)} is ${p}; an amount granted is never negative, so its type is unsigned`;
+  }
+  for (const rel of grant.ends ?? []) {
+    const end = at("ends", rel, true);
+    if (end.error) return end.error;
+    if (!end.t.timestamp) return `grant ends ${JSON.stringify(rel)} has no timestamp tag`;
+  }
+  return null;
+}
+
 export function checkDynamic(iface, value, want, diag, at) {
   if (!value || typeof value !== "object") return;
   const from = value.from;

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)
  */