@callcium/sdk 0.10.0 → 0.11.0

package/src/policy-coder.ts

@@ -1,11 +1,27 @@
 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, Op, TypeCode, MAX_CONTEXT_PROPERTY_ID } from "./constants";
+import {
+  DescriptorFormat as DF,
+  fieldMax,
+  formatCode,
+  MAX_CONTEXT_PROPERTY_ID,
+  Op,
+  PolicyFormat as PF,
+  Scope,
+  TypeCode,
+} from "./constants";
 import { Descriptor } from "./descriptor";
 import { decodeDescriptor } from "./descriptor-coder";
-import { CallciumError } from "./errors";
-import { isLengthOp, isLengthValidType, toBigInt, isAddressableTarget, isValidOperatorData } from "./operators";
+import { CallciumError, type CallciumErrorCode } from "./errors";
+import {
+  isLengthOp,
+  isLengthValidType,
+  toBigInt,
+  isAddressableTarget,
+  isValidOperatorData,
+  toOperatorBytes,
+} from "./operators";
 import { parsePathSteps } from "./path";
 
 import type {
@@ -28,6 +44,24 @@ function field<T>(value: T, start: number, end: number): Field<T> {
   return { value, span: { start, end } };
 }
 
+/**
+ * Wrap the hex rendering of `data[start, end)` with its span, rendering on first read.
+ * Enforcement reads the span as bytes, so the string is built only for a caller that asks.
+ * The field reads and assigns like the plain one it replaces.
+ */
+function hexField(data: Uint8Array, start: number, end: number): Field<Hex> {
+  let hex: Hex | undefined;
+  return {
+    get value(): Hex {
+      return (hex ??= toHex(data, start, end));
+    },
+    set value(replacement: Hex) {
+      hex = replacement;
+    },
+    span: { start, end },
+  };
+}
+
 ///////////////////////////////////////////////////////////////////////////
 // Hint block
 ///////////////////////////////////////////////////////////////////////////
@@ -123,7 +157,7 @@ function hintTargetTypeCode(data: Uint8Array, hintStart: number, hintSize: numbe
 /** Decode a policy blob, returning the structural representation and the blob bytes it spans. */
 export function decodePolicy(blob: Hex): { policy: DecodedPolicy; data: Uint8Array } {
   const data = hexToBytes(blob);
-  if (data.length < PF.DESC_OFFSET + 1) {
+  if (data.length < PF.DESC_OFFSET) {
     throw new CallciumError("MALFORMED_HEADER", "Policy blob is too short");
   }
 
@@ -169,7 +203,8 @@ export function decodePolicy(blob: Hex): { policy: DecodedPolicy; data: Uint8Arr
       end: descStart + param.span.end,
     },
   }));
-  const descriptorRaw = toHex(data, descStart, descEnd);
+
+  const descriptorRaw = hexField(data, descStart, descEnd);
 
   const groupCountStart = groupCountOffset;
   const groupCountEnd = groupCountStart + PF.GROUP_COUNT_SIZE;
@@ -191,6 +226,10 @@ export function decodePolicy(blob: Hex): { policy: DecodedPolicy; data: Uint8Arr
     const groupBodyStart = offset + PF.GROUP_HEADER_SIZE;
     const groupEnd = groupBodyStart + groupSizeValue;
 
+    if (groupEnd > data.length) {
+      throw new CallciumError("GROUP_OVERFLOW", "Group extends beyond policy blob", offset);
+    }
+
     const ruleCountStart = offset;
     const ruleCountValue = readU16(data, ruleCountStart);
     if (ruleCountValue === 0) {
@@ -199,9 +238,6 @@ export function decodePolicy(blob: Hex): { policy: DecodedPolicy; data: Uint8Arr
     if (groupSizeValue < ruleCountValue * PF.RULE_MIN_SIZE) {
       throw new CallciumError("GROUP_TOO_SMALL", "Declared group size is too small for its rule count", offset);
     }
-    if (groupEnd > data.length) {
-      throw new CallciumError("GROUP_OVERFLOW", "Group extends beyond policy blob", offset);
-    }
 
     const rules: DecodedRule[] = [];
     let ruleOffset = groupBodyStart;
@@ -219,8 +255,8 @@ export function decodePolicy(blob: Hex): { policy: DecodedPolicy; data: Uint8Arr
           ruleOffset,
         );
       }
-      if (ruleOffset + ruleSizeValue > groupEnd) {
-        throw new CallciumError("RULE_OVERFLOW", "Rule extends beyond group boundary", ruleOffset);
+      if (ruleOffset + ruleSizeValue > data.length) {
+        throw new CallciumError("RULE_OVERFLOW", "Rule extends beyond policy blob", ruleOffset);
       }
 
       const scopeOffset = ruleOffset + PF.RULE_SCOPE_OFFSET;
@@ -282,12 +318,13 @@ export function decodePolicy(blob: Hex): { policy: DecodedPolicy; data: Uint8Arr
       // IN operands must be strictly ascending (unsigned); strictness also rejects duplicates.
       if (opBase === Op.IN) {
         const wordCount = dataLengthValue / 32;
+        let prev = toBigInt(data, dataStart);
         for (let word = 1; word < wordCount; word++) {
-          const prev = data.subarray(dataStart + (word - 1) * 32, dataStart + word * 32);
-          const cur = data.subarray(dataStart + word * 32, dataStart + (word + 1) * 32);
-          if (compareBytes(prev, cur) >= 0) {
+          const cur = toBigInt(data, dataStart + word * 32);
+          if (cur <= prev) {
             throw new CallciumError("UNSORTED_IN_SET", "IN operands must be strictly ascending", ruleOffset);
           }
+          prev = cur;
         }
       }
 
@@ -327,7 +364,7 @@ export function decodePolicy(blob: Hex): { policy: DecodedPolicy; data: Uint8Arr
         if (contextPropertyId > MAX_CONTEXT_PROPERTY_ID) {
           throw new CallciumError(
             "UNKNOWN_CONTEXT_PROPERTY",
-            `Context rule references undefined context property 0x${contextPropertyId.toString(16).padStart(4, "0")}`,
+            `Context rule references undefined context property ${formatCode(contextPropertyId, PF.PATH_STEP_SIZE)}`,
             ruleOffset,
           );
         }
@@ -340,14 +377,17 @@ export function decodePolicy(blob: Hex): { policy: DecodedPolicy; data: Uint8Arr
         pathDepth: field(depthValue, depthOffset, depthOffset + 1),
         path: field(pathHex, pathStart, pathStart + pathLength),
         ...(hintSize > 0 && {
-          hint: field(toHex(data, hintStart, hintStart + hintSize), hintStart, hintStart + hintSize),
+          hint: hexField(data, hintStart, hintStart + hintSize),
         }),
         opCode: field(opCodeValue, opCodeOffset, opCodeOffset + PF.RULE_OPCODE_SIZE),
         dataLength: field(dataLengthValue, dataLengthOffset, dataLengthOffset + PF.RULE_DATALENGTH_SIZE),
-        data: field(toHex(data, dataStart, dataStart + dataLengthValue), dataStart, dataStart + dataLengthValue),
+        data: hexField(data, dataStart, dataStart + dataLengthValue),
         span: { start: ruleOffset, end: ruleOffset + ruleSizeValue },
       });
 
+      if (ruleOffset + ruleSizeValue > groupEnd) {
+        throw new CallciumError("RULE_OVERFLOW", "Rule extends beyond group boundary", ruleOffset);
+      }
       ruleOffset += ruleSizeValue;
     }
 
@@ -374,7 +414,12 @@ export function decodePolicy(blob: Hex): { policy: DecodedPolicy; data: Uint8Arr
     selector: field(selectorHex, selectorStart, selectorEnd),
     descLength: field(descLengthValue, descLengthStart, descLengthStart + PF.DESC_LENGTH_SIZE),
     descriptor: {
-      raw: descriptorRaw,
+      get raw(): Hex {
+        return descriptorRaw.value;
+      },
+      set raw(replacement: Hex) {
+        descriptorRaw.value = replacement;
+      },
       header: field({ version: desc.version, paramCount: desc.params.length }, descStart, descStart + DF.HEADER_SIZE),
       params,
       span: { start: descStart, end: descEnd },
@@ -395,15 +440,11 @@ export function decodePolicy(blob: Hex): { policy: DecodedPolicy; data: Uint8Arr
 
 type Rule = { scope: number; path: Uint8Array; operator: Uint8Array; hint: Uint8Array };
 
-/** Flatten a Constraint into one Rule per operator, compiling its hint against the descriptor. */
-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)");
-    }
-  }
+/** The path bytes and compiled hint every rule a constraint produces carries. */
+type ConstraintTarget = { path: Uint8Array; hint: Uint8Array };
 
+/** Read a constraint's path and compile the hint its rules carry. */
+function readConstraintTarget(constraint: Constraint, desc: Uint8Array): ConstraintTarget {
   const path = hexToBytes(constraint.path);
 
   // Path shape checks precede compilation: the compiler assumes a framed, depth-bounded path.
@@ -422,7 +463,21 @@ function flattenConstraint(constraint: Constraint, desc: Uint8Array): Rule[] {
     constraint.scope === Scope.CALLDATA
       ? Descriptor.compileHint(desc, parsePathSteps(constraint.path))
       : new Uint8Array(0);
-  return operators.map((operator) => ({ scope: constraint.scope, path, operator, hint }));
+  return { path, hint };
+}
+
+/** Flatten a Constraint into one Rule per operator, compiling its hint against the descriptor. */
+function flattenConstraint(constraint: Constraint, desc: Uint8Array): Rule[] {
+  // The rule is the unit these checks run over: each rule's operator is established before the
+  // path and hint it shares with its siblings. A constraint carrying no operator produces no rule,
+  // so its path is never read.
+  let target: ConstraintTarget | undefined;
+
+  return constraint.operators.map((operatorHex) => {
+    const operator = toOperatorBytes(operatorHex);
+    target ??= readConstraintTarget(constraint, desc);
+    return { scope: constraint.scope, operator, ...target };
+  });
 }
 
 /** Compare two byte arrays lexicographically. */
@@ -447,6 +502,12 @@ function sortRules(rules: Rule[]): void {
   });
 }
 
+/** Require a value to fit the big-endian field of `byteWidth` bytes. */
+function requireFieldFits(value: number, byteWidth: number, code: CallciumErrorCode, subject: string): void {
+  const max = fieldMax(byteWidth);
+  if (value > max) throw new CallciumError(code, `${subject} ${value} exceeds maximum ${max}`);
+}
+
 /**
  * Serialize a single rule to its wire format bytes.
  * Path shape and operator framing are established by `flattenConstraint`.
@@ -458,9 +519,7 @@ function encodeRule(rule: Rule): Uint8Array {
   }
   const data = rule.operator.subarray(1);
   const ruleSize = PF.RULE_FIXED_OVERHEAD + rule.path.length + rule.hint.length + data.length;
-  if (ruleSize > 0xffff) {
-    throw new CallciumError("RULE_SIZE_OVERFLOW", `Rule size ${ruleSize} exceeds maximum 65535`);
-  }
+  requireFieldFits(ruleSize, PF.RULE_SIZE_SIZE, "RULE_SIZE_OVERFLOW", "Rule size");
 
   const buf = new Uint8Array(ruleSize);
   writeBE16(buf, 0, ruleSize);
@@ -511,9 +570,7 @@ function encode(data: PolicyData): Hex {
   if (data.groups.length === 0) {
     throw new CallciumError("EMPTY_POLICY", "Policy must contain at least one group");
   }
-  if (data.groups.length > 0xff) {
-    throw new CallciumError("GROUP_COUNT_OVERFLOW", `Group count ${data.groups.length} exceeds maximum 255`);
-  }
+  requireFieldFits(data.groups.length, PF.GROUP_COUNT_SIZE, "GROUP_COUNT_OVERFLOW", "Group count");
 
   // Flatten constraints into rules and sort within each group. Hints are compiled first because
   // they are part of the rule bytes the group hash covers.
@@ -523,20 +580,13 @@ function encode(data: PolicyData): Hex {
     return rules;
   });
 
-  if (descBytes.length > 0xffff) {
-    throw new CallciumError("DESC_LENGTH_OVERFLOW", `Descriptor length ${descBytes.length} exceeds maximum 65535`);
-  }
+  requireFieldFits(descBytes.length, PF.DESC_LENGTH_SIZE, "DESC_LENGTH_OVERFLOW", "Descriptor length");
 
   const encodedGroups = sortedGroups.map((rules, groupIndex) => {
     if (rules.length === 0) {
       throw new CallciumError("EMPTY_GROUP", `Group ${groupIndex} is empty`);
     }
-    if (rules.length > 0xffff) {
-      throw new CallciumError(
-        "RULE_COUNT_OVERFLOW",
-        `Group ${groupIndex} rule count ${rules.length} exceeds maximum 65535`,
-      );
-    }
+    requireFieldFits(rules.length, PF.GROUP_RULECOUNT_SIZE, "RULE_COUNT_OVERFLOW", `Group ${groupIndex} rule count`);
     return { wireBytes: encodeGroupRules(rules), ruleCount: rules.length };
   });
 
@@ -547,7 +597,13 @@ function encode(data: PolicyData): Hex {
     encodedGroups.sort((a, b) => compareBytes(hashes.get(a)!, hashes.get(b)!));
   }
 
-  const selectorBytes = data.isSelectorless ? new Uint8Array(4) : hexToBytes(data.selector);
+  const selectorBytes = data.isSelectorless ? new Uint8Array(PF.SELECTOR_SIZE) : hexToBytes(data.selector);
+  if (selectorBytes.length !== PF.SELECTOR_SIZE) {
+    throw new CallciumError(
+      "MALFORMED_SELECTOR",
+      `Selector must be ${PF.SELECTOR_SIZE} bytes, got ${selectorBytes.length}`,
+    );
+  }
 
   const headerByte = PF.VERSION | (data.isSelectorless ? PF.FLAG_NO_SELECTOR : 0);
 
@@ -599,8 +655,8 @@ function decode(blob: Hex): PolicyData {
   const { policy } = decodePolicy(blob);
 
   const groups: Constraint[][] = policy.groups.map((group) => {
+    // A Map keeps its insertion order, which is the order the rules named their constraints in.
     const constraintMap = new Map<string, Constraint>();
-    const constraintOrder: string[] = [];
 
     for (const rule of group.rules) {
       const hintHex = rule.hint?.value;
@@ -619,11 +675,10 @@ function decode(blob: Hex): PolicyData {
           span: rule.span,
         };
         constraintMap.set(key, constraint);
-        constraintOrder.push(key);
       }
     }
 
-    return constraintOrder.map((k) => constraintMap.get(k)!);
+    return [...constraintMap.values()];
   });
 
   return {