@callcium/sdk 0.8.0 → 0.10.0

package/src/operators.ts

@@ -1,4 +1,4 @@
-import { Op, TypeCode } from "./constants";
+import { Op, TypeCode, operandsOf } from "./constants";
 import { CallciumError } from "./errors";
 
 /** Read a big-endian 256-bit unsigned integer from a 32-byte window. */
@@ -28,7 +28,7 @@ export function isLeftAligned(typeCode: number): boolean {
 }
 
 /**
- * Canonicalize a raw 256-bit calldata word to its ABI value for the declared type (Policy Spec §7.8).
+ * Canonicalize a raw 256-bit calldata word to its ABI value for the declared type.
  * A scalar loaded from untrusted calldata may carry bits outside the declared width; masking
  * unsigned/address/bool/function/bytesN to width and sign-extending signed integers makes the
  * comparison use the canonical ABI value rather than the raw bytes.
@@ -103,14 +103,14 @@ function compareTyped(a: bigint, b: bigint, typeCode: number): number {
 /** Binary search over a sorted array of 32-byte words. Comparison is always unsigned. */
 function isIn(value: bigint, data: Uint8Array): boolean {
   const count = data.length / 32;
-  let lo = 0;
-  let hi = count - 1;
-  while (lo <= hi) {
-    const mid = (lo + hi) >>> 1;
+  let low = 0;
+  let high = count - 1;
+  while (low <= high) {
+    const mid = (low + high) >>> 1;
     const elem = toBigInt(data, mid * 32);
     if (value === elem) return true;
-    if (value < elem) hi = mid - 1;
-    else lo = mid + 1;
+    if (value < elem) high = mid - 1;
+    else low = mid + 1;
   }
   return false;
 }
@@ -196,9 +196,114 @@ export function applyOperator(
     }
 
     default:
-      throw new CallciumError("UNKNOWN_OPERATOR", `Unknown operator code 0x${base.toString(16).padStart(2, "0")}.`);
+      throw new CallciumError("UNKNOWN_OPERATOR", `Unknown operator code 0x${base.toString(16).padStart(2, "0")}`);
   }
 
   const negate = (opCode & Op.NOT) !== 0;
   return negate ? !result : result;
 }
+
+/**
+ * Check whether an operator's data payload has the correct length.
+ * @param opBase - Base operator code with the NOT flag stripped.
+ * @param dataLength - Byte length of the operator's data payload.
+ * @returns True if the data length is valid for the given operator.
+ */
+export function isValidOperatorData(opBase: number, dataLength: number): boolean {
+  const operands = operandsOf(opBase);
+  if (operands === "single") return dataLength === 32;
+  if (operands === "range") return dataLength === 64;
+  if (operands === "variadic") return dataLength > 0 && dataLength % 32 === 0;
+  return false;
+}
+
+///////////////////////////////////////////////////////////////////////////
+// Type code classification
+///////////////////////////////////////////////////////////////////////////
+
+/** Structural category for a descriptor type code. */
+export type TypeClass = "elementary" | "tuple" | "staticArray" | "dynamicArray";
+
+/** Structural classification without label. */
+export type TypeClassInfo = { typeClass: TypeClass; isDynamic: boolean };
+
+/** Display metadata for a descriptor type code. */
+export type TypeCodeInfo = TypeClassInfo & { label: string };
+
+/** Throw an UNKNOWN_TYPE_CODE error. */
+function unknownTypeCode(code: number): never {
+  throw new CallciumError("UNKNOWN_TYPE_CODE", `Unknown type code 0x${code.toString(16).padStart(2, "0")}`);
+}
+
+// Pre-allocated constant objects for fixed type codes (avoids per-call allocation).
+const ELEMENTARY = { typeClass: "elementary", isDynamic: false } as const;
+const ELEMENTARY_DYNAMIC = { typeClass: "elementary", isDynamic: true } as const;
+const STATIC_ARR = { typeClass: "staticArray", isDynamic: false } as const;
+const DYNAMIC_ARR = { typeClass: "dynamicArray", isDynamic: true } as const;
+const TUPLE = { typeClass: "tuple", isDynamic: false } as const;
+
+/**
+ * Classify a type code into its structural category and dynamism.
+ * Lightweight variant of `lookupTypeCode` that skips label computation.
+ * @param code - A single-byte descriptor type code.
+ * @returns Type class and whether the type is ABI-dynamic.
+ * @throws {CallciumError} If the code is not a recognised type code.
+ */
+export function classifyTypeCode(code: number): TypeClassInfo {
+  if (code >= TypeCode.UINT_MIN && code <= TypeCode.UINT_MAX) return ELEMENTARY;
+  if (code >= TypeCode.INT_MIN && code <= TypeCode.INT_MAX) return ELEMENTARY;
+  if (code === TypeCode.ADDRESS || code === TypeCode.BOOL || code === TypeCode.FUNCTION) return ELEMENTARY;
+  if (code >= 0x44 && code <= 0x4f) unknownTypeCode(code);
+  if (code >= TypeCode.FIXED_BYTES_MIN && code <= TypeCode.FIXED_BYTES_MAX) return ELEMENTARY;
+  if (code === TypeCode.BYTES || code === TypeCode.STRING) return ELEMENTARY_DYNAMIC;
+  if (code >= 0x72 && code <= 0x7f) unknownTypeCode(code);
+  if (code === TypeCode.STATIC_ARRAY) return STATIC_ARR;
+  if (code === TypeCode.DYNAMIC_ARRAY) return DYNAMIC_ARR;
+  if (code >= 0x82 && code <= 0x8f) unknownTypeCode(code);
+  if (code === TypeCode.TUPLE) return TUPLE;
+  unknownTypeCode(code);
+}
+
+/**
+ * Determine whether a type code names a value an operator can read: a scalar word or a declared
+ * length. Tuples, static arrays, and undefined codes address nothing.
+ * @param code - A single-byte descriptor type code.
+ * @returns True when an operator can be applied to a target of this type.
+ */
+export function isAddressableTarget(code: number): boolean {
+  let info: TypeClassInfo;
+  try {
+    // An undefined code is reported by a throw, and addresses nothing either way.
+    info = classifyTypeCode(code);
+  } catch {
+    return false;
+  }
+  return info.typeClass === "elementary" || info.typeClass === "dynamicArray";
+}
+
+/** Compute the ABI type label for a type code. */
+function typeCodeLabel(code: number): string {
+  if (code >= TypeCode.UINT_MIN && code <= TypeCode.UINT_MAX) return `uint${(code - TypeCode.UINT_MIN + 1) * 8}`;
+  if (code >= TypeCode.INT_MIN && code <= TypeCode.INT_MAX) return `int${(code - TypeCode.INT_MIN + 1) * 8}`;
+  if (code === TypeCode.ADDRESS) return "address";
+  if (code === TypeCode.BOOL) return "bool";
+  if (code === TypeCode.FUNCTION) return "function";
+  if (code >= TypeCode.FIXED_BYTES_MIN && code <= TypeCode.FIXED_BYTES_MAX)
+    return `bytes${code - TypeCode.FIXED_BYTES_MIN + 1}`;
+  if (code === TypeCode.BYTES) return "bytes";
+  if (code === TypeCode.STRING) return "string";
+  if (code === TypeCode.STATIC_ARRAY) return "T[k]";
+  if (code === TypeCode.DYNAMIC_ARRAY) return "T[]";
+  if (code === TypeCode.TUPLE) return "tuple";
+  return `0x${code.toString(16).padStart(2, "0")}`;
+}
+
+/**
+ * Map a raw type code byte to its ABI type label, structural category, and dynamism.
+ * @param code - A single-byte descriptor type code.
+ * @returns Label, type class, and whether the type is ABI-dynamic.
+ * @throws {CallciumError} If the code is not a recognised type code.
+ */
+export function lookupTypeCode(code: number): TypeCodeInfo {
+  return { label: typeCodeLabel(code), ...classifyTypeCode(code) };
+}

package/src/path.ts

@@ -0,0 +1,71 @@
+import { bytesToHex, hexToBytes, readU16, writeBE16 } from "./bytes";
+import { buildCodeMap, PolicyFormat as PF } from "./constants";
+import { CallciumError } from "./errors";
+
+import type { Hex } from "./types";
+
+///////////////////////////////////////////////////////////////////////////
+// Quantifier steps
+///////////////////////////////////////////////////////////////////////////
+
+const QUANTIFIER_TABLE = [
+  { key: "ALL", code: 0xffff, label: "all" },
+  { key: "ANY", code: 0xfffe, label: "any" },
+] as const;
+
+/** Reserved path step values that trigger quantified evaluation over array elements. */
+export const Quantifier = buildCodeMap(QUANTIFIER_TABLE);
+
+/** Display metadata for a quantifier step. */
+export type QuantifierInfo = { label: string };
+
+const quantifierByCode: ReadonlyMap<number, QuantifierInfo> = new Map<number, QuantifierInfo>(
+  QUANTIFIER_TABLE.map((e) => [e.code, { label: e.label }]),
+);
+
+/** Check whether a path step is a quantifier (ALL or ANY). */
+export function isQuantifier(step: number): boolean {
+  return step >= Quantifier.ANY;
+}
+
+/**
+ * Map a quantifier path step to its display label.
+ * @param code - Quantifier step value.
+ * @returns Display metadata for the quantifier.
+ * @throws {CallciumError} If the code is not a recognised quantifier.
+ */
+export function lookupQuantifier(code: number): QuantifierInfo {
+  const info = quantifierByCode.get(code);
+  if (!info) throw new CallciumError("UNKNOWN_QUANTIFIER", `Unknown quantifier step 0x${code.toString(16)}`);
+  return info;
+}
+
+///////////////////////////////////////////////////////////////////////////
+// Path steps
+///////////////////////////////////////////////////////////////////////////
+
+/** Encode a sequence of uint16 path steps as a big-endian hex string. */
+export function encodePath(steps: readonly number[]): Hex {
+  const buffer = new Uint8Array(steps.length * 2);
+  for (let i = 0; i < steps.length; i++) {
+    writeBE16(buffer, i * 2, steps[i]!);
+  }
+  return bytesToHex(buffer);
+}
+
+/**
+ * Parse a BE16-encoded hex path into an array of step values.
+ * @param path - 0x-prefixed hex string containing BE16-encoded path steps.
+ * @returns Array of numeric step values.
+ */
+export function parsePathSteps(path: Hex): number[] {
+  const bytes = hexToBytes(path);
+  if (bytes.length % PF.PATH_STEP_SIZE !== 0) {
+    throw new CallciumError("MALFORMED_PATH", `Path byte length ${bytes.length} is not a whole number of steps`);
+  }
+  const steps: number[] = [];
+  for (let offset = 0; offset < bytes.length; offset += PF.PATH_STEP_SIZE) {
+    steps.push(readU16(bytes, offset));
+  }
+  return steps;
+}

package/src/policy-builder.ts

@@ -1,10 +1,11 @@
 import { bytesToHex } from "./bytes";
-import { Scope, TypeCode, isQuantifier, MAX_CONTEXT_PROPERTY_ID } from "./constants";
+import { Scope, TypeCode, MAX_CONTEXT_PROPERTY_ID } from "./constants";
 import { ConstraintBuilder } from "./constraint";
 import { Descriptor } from "./descriptor";
 import { DescriptorCoder } from "./descriptor-coder";
 import { CallciumError, ValidationError } from "./errors";
-import { PolicyCoder, parsePathSteps } from "./policy-coder";
+import { isQuantifier, parsePathSteps } from "./path";
+import { PolicyCoder } from "./policy-coder";
 import { PolicyValidator } from "./policy-validator";
 import { SignatureParser } from "./signature";
 
@@ -29,13 +30,13 @@ type PolicyDraft = {
 /** Validate a context-scope path. */
 function validateContextPath(steps: number[]): void {
   if (steps.length !== 1) {
-    throw new CallciumError("INVALID_CONTEXT_PATH", "Context-scope path must be exactly one step.");
+    throw new CallciumError("INVALID_CONTEXT_PATH", "Context-scope path must be exactly one step");
   }
   const step = steps[0]!;
   if (step > MAX_CONTEXT_PROPERTY_ID) {
     throw new CallciumError(
       "UNKNOWN_CONTEXT_PROPERTY",
-      `Unknown context property ID 0x${step.toString(16).padStart(4, "0")}.`,
+      `Unknown context property ID 0x${step.toString(16).padStart(4, "0")}`,
     );
   }
 }
@@ -47,7 +48,7 @@ function validateCalldataPath(steps: number[], desc: Uint8Array): void {
   if (argIndex >= paramCount) {
     throw new CallciumError(
       "PARAM_INDEX_OUT_OF_BOUNDS",
-      `Param index ${argIndex} out of range (descriptor has ${paramCount} params).`,
+      `Param index ${argIndex} out of range (descriptor has ${paramCount} params)`,
     );
   }
 
@@ -61,10 +62,10 @@ function validateCalldataPath(steps: number[], desc: Uint8Array): void {
 
     if (isQuantifier(step)) {
       if (!isArray) {
-        throw new CallciumError("QUANTIFIER_ON_NON_ARRAY", "Quantifier step is only valid on an array node.");
+        throw new CallciumError("QUANTIFIER_ON_NON_ARRAY", "Quantifier step is only valid on an array node");
       }
       if (hasQuantifier) {
-        throw new CallciumError("NESTED_QUANTIFIER", "Nested quantifiers are not allowed.");
+        throw new CallciumError("NESTED_QUANTIFIER", "Nested quantifiers are not allowed");
       }
       hasQuantifier = true;
     }
@@ -74,7 +75,7 @@ function validateCalldataPath(steps: number[], desc: Uint8Array): void {
       if (step >= fieldCount) {
         throw new CallciumError(
           "TUPLE_FIELD_OUT_OF_BOUNDS",
-          `Tuple field index ${step} out of range (tuple has ${fieldCount} fields).`,
+          `Tuple field index ${step} out of range (tuple has ${fieldCount} fields)`,
         );
       }
       offset = Descriptor.tupleFieldOffset(desc, offset, step);
@@ -84,13 +85,13 @@ function validateCalldataPath(steps: number[], desc: Uint8Array): void {
         if (step >= arrayLength) {
           throw new CallciumError(
             "STATIC_ARRAY_INDEX_OUT_OF_BOUNDS",
-            `Array index ${step} out of range (static array has ${arrayLength} elements).`,
+            `Array index ${step} out of range (static array has ${arrayLength} elements)`,
           );
         }
       }
       offset = Descriptor.arrayElementOffset(offset);
     } else {
-      throw new CallciumError("NOT_COMPOSITE", "Cannot descend into an elementary type.");
+      throw new CallciumError("NOT_COMPOSITE", "Cannot descend into an elementary type");
     }
   }
 }
@@ -150,13 +151,13 @@ export class PolicyBuilder {
     };
 
     if (c.operators.length === 0) {
-      throw new CallciumError("NO_CONSTRAINT_OPERATORS", "Constraint must have at least one operator.");
+      throw new CallciumError("NO_CONSTRAINT_OPERATORS", "Constraint must have at least one operator");
     }
 
     // Path shape is established before the scope decides how to navigate it.
     const steps = parsePathSteps(c.path);
     if (steps.length === 0) {
-      throw new CallciumError("EMPTY_PATH", "Path must have at least one step.");
+      throw new CallciumError("EMPTY_PATH", "Path must have at least one step");
     }
 
     if (c.scope === Scope.CONTEXT) {
@@ -164,13 +165,13 @@ export class PolicyBuilder {
     } else if (c.scope === Scope.CALLDATA) {
       validateCalldataPath(steps, this.draft.descriptor);
     } else {
-      throw new CallciumError("INVALID_SCOPE", `Unknown scope value ${c.scope}.`);
+      throw new CallciumError("INVALID_SCOPE", `Unknown scope value ${c.scope}`);
     }
 
     const key = `${c.scope}:${c.path.toLowerCase()}`;
     const currentHashes = this.draft.pathHashes[this.draft.pathHashes.length - 1]!;
     if (currentHashes.has(key)) {
-      throw new CallciumError("DUPLICATE_PATH_IN_GROUP", `Duplicate path ${c.path} in the same group.`);
+      throw new CallciumError("DUPLICATE_PATH_IN_GROUP", `Duplicate path ${c.path} in the same group`);
     }
 
     currentHashes.add(key);
@@ -182,7 +183,7 @@ export class PolicyBuilder {
   or(): this {
     const lastGroup = this.draft.groups[this.draft.groups.length - 1]!;
     if (lastGroup.length === 0) {
-      throw new CallciumError("EMPTY_GROUP", "Cannot start a new group when the current group is empty.");
+      throw new CallciumError("EMPTY_GROUP", "Cannot start a new group when the current group is empty");
     }
     this.draft.groups.push([]);
     this.draft.pathHashes.push(new Set());
@@ -233,7 +234,7 @@ export class PolicyBuilder {
   private checkGroups(): void {
     for (let i = 0; i < this.draft.groups.length; i++) {
       if (this.draft.groups[i]!.length === 0) {
-        throw new CallciumError("EMPTY_GROUP", `Group ${i} is empty.`);
+        throw new CallciumError("EMPTY_GROUP", `Group ${i} is empty`);
       }
     }
   }

package/src/policy-coder.ts

@@ -1,21 +1,12 @@
 import { keccak_256 } from "@noble/hashes/sha3.js";
 
 import { bytesToHex, hexToBytes, toHex, readU16, readU32, writeBE16, writeBE32 } from "./bytes";
-import {
-  DescriptorFormat as DF,
-  PolicyFormat as PF,
-  Scope,
-  Limits,
-  Op,
-  TypeCode,
-  isValidOperatorData,
-  isAddressableTarget,
-  MAX_CONTEXT_PROPERTY_ID,
-} from "./constants";
+import { DescriptorFormat as DF, PolicyFormat as PF, Scope, Op, TypeCode, MAX_CONTEXT_PROPERTY_ID } from "./constants";
 import { Descriptor } from "./descriptor";
 import { decodeDescriptor } from "./descriptor-coder";
 import { CallciumError } from "./errors";
-import { isLengthOp, isLengthValidType } from "./operators";
+import { isLengthOp, isLengthValidType, toBigInt, isAddressableTarget, isValidOperatorData } from "./operators";
+import { parsePathSteps } from "./path";
 
 import type {
   Constraint,
@@ -28,27 +19,6 @@ import type {
   PolicyData,
 } from "./types";
 
-///////////////////////////////////////////////////////////////////////////
-// Path helper
-///////////////////////////////////////////////////////////////////////////
-
-/**
- * Parse a BE16-encoded hex path into an array of step values.
- * @param path - 0x-prefixed hex string containing BE16-encoded path steps.
- * @returns Array of numeric step values.
- */
-export function parsePathSteps(path: Hex): number[] {
-  const bytes = hexToBytes(path);
-  if (bytes.length % PF.PATH_STEP_SIZE !== 0) {
-    throw new CallciumError("MALFORMED_PATH", `Path byte length ${bytes.length} is not a whole number of steps`);
-  }
-  const steps: number[] = [];
-  for (let offset = 0; offset < bytes.length; offset += PF.PATH_STEP_SIZE) {
-    steps.push(readU16(bytes, offset));
-  }
-  return steps;
-}
-
 ///////////////////////////////////////////////////////////////////////////
 // Policy field helper
 ///////////////////////////////////////////////////////////////////////////
@@ -321,14 +291,25 @@ export function decodePolicy(blob: Hex): { policy: DecodedPolicy; data: Uint8Arr
         }
       }
 
+      // An EQ_CTX operand word must be a defined context property ID.
+      if (opBase === Op.EQ_CTX) {
+        if (toBigInt(data, dataStart) > BigInt(MAX_CONTEXT_PROPERTY_ID)) {
+          throw new CallciumError(
+            "UNKNOWN_CONTEXT_PROPERTY",
+            "EQ_CTX operand references an undefined context property",
+            ruleOffset,
+          );
+        }
+      }
+
       // The path must be non-empty and within the depth cap.
       if (depthValue === 0) {
         throw new CallciumError("EMPTY_PATH", "Rule path must have at least one step", ruleOffset);
       }
-      if (depthValue > Limits.MAX_PATH_DEPTH) {
+      if (depthValue > PF.MAX_PATH_DEPTH) {
         throw new CallciumError(
           "PATH_TOO_DEEP",
-          `Path depth ${depthValue} exceeds maximum ${Limits.MAX_PATH_DEPTH}`,
+          `Path depth ${depthValue} exceeds maximum ${PF.MAX_PATH_DEPTH}`,
           ruleOffset,
         );
       }
@@ -419,7 +400,7 @@ function flattenConstraint(constraint: Constraint, desc: Uint8Array): Rule[] {
   const operators = constraint.operators.map(hexToBytes);
   for (const operator of operators) {
     if (operator.length < 1) {
-      throw new CallciumError("INVALID_OPERATOR_BYTES", "Operator must have at least one byte (opcode).");
+      throw new CallciumError("INVALID_OPERATOR_BYTES", "Operator must have at least one byte (opcode)");
     }
   }
 
@@ -427,14 +408,14 @@ function flattenConstraint(constraint: Constraint, desc: Uint8Array): Rule[] {
 
   // Path shape checks precede compilation: the compiler assumes a framed, depth-bounded path.
   if (path.length === 0) {
-    throw new CallciumError("EMPTY_PATH", "Rule path must have at least one step.");
+    throw new CallciumError("EMPTY_PATH", "Rule path must have at least one step");
   }
   if ((path.length & 1) !== 0) {
-    throw new CallciumError("MALFORMED_PATH", "Path byte length must be even.");
+    throw new CallciumError("MALFORMED_PATH", "Path byte length must be even");
   }
   const depth = path.length / 2;
-  if (depth > Limits.MAX_PATH_DEPTH) {
-    throw new CallciumError("PATH_TOO_DEEP", `Path depth ${depth} exceeds maximum ${Limits.MAX_PATH_DEPTH}.`);
+  if (depth > PF.MAX_PATH_DEPTH) {
+    throw new CallciumError("PATH_TOO_DEEP", `Path depth ${depth} exceeds maximum ${PF.MAX_PATH_DEPTH}`);
   }
 
   const hint =
@@ -473,7 +454,7 @@ function sortRules(rules: Rule[]): void {
 function encodeRule(rule: Rule): Uint8Array {
   const depth = rule.path.length / 2;
   if (rule.scope === Scope.CONTEXT && depth !== 1) {
-    throw new CallciumError("INVALID_CONTEXT_PATH", "Context-scope rules must have exactly one path step.");
+    throw new CallciumError("INVALID_CONTEXT_PATH", "Context-scope rules must have exactly one path step");
   }
   const data = rule.operator.subarray(1);
   const ruleSize = PF.RULE_FIXED_OVERHEAD + rule.path.length + rule.hint.length + data.length;