@callcium/sdk 0.9.0 → 0.10.0

package/src/policy-validator.ts

@@ -1,31 +1,28 @@
 import { bigintToHex, bytesToHex, hexToBytes } from "./bytes";
-import {
-  classifyTypeCode,
-  isQuantifier,
-  isValidOperatorData,
-  Limits,
-  lookupContextProperty,
-  MAX_CONTEXT_PROPERTY_ID,
-  Op,
-  Quantifier,
-  Scope,
-  TypeCode,
-} from "./constants";
+import { PolicyFormat, lookupContextProperty, MAX_CONTEXT_PROPERTY_ID, Op, Scope, TypeCode } from "./constants";
 import { Descriptor, type TypeInfo } from "./descriptor";
 import { decodeDescriptor } from "./descriptor-coder";
 import { CallciumError, type CallciumErrorCode } from "./errors";
-import { canonicalize, isLeftAligned, isSigned, isLengthOp, isLengthValidType } from "./operators";
-import { parsePathSteps } from "./policy-coder";
+import {
+  canonicalize,
+  isLeftAligned,
+  isSigned,
+  isLengthOp,
+  isLengthValidType,
+  classifyTypeCode,
+  isValidOperatorData,
+} from "./operators";
+import { Quantifier, isQuantifier, parsePathSteps } from "./path";
 import * as ValidationIssue from "./validation-issue";
 
-import type { Constraint, Hex, Issue, PolicyData } from "./types";
+import type { Constraint, Hex, Issue, IssueCode, PolicyData } from "./types";
 
 ///////////////////////////////////////////////////////////////////////////
 // Internal types
 ///////////////////////////////////////////////////////////////////////////
 
 /** Codes a path walk raises when the path does not navigate the descriptor (PV-1). */
-const NAVIGABILITY_CODES: ReadonlySet<CallciumErrorCode> = new Set<CallciumErrorCode>([
+const navigabilityCodes: ReadonlySet<CallciumErrorCode> = new Set<CallciumErrorCode>([
   "EMPTY_PATH",
   "PARAM_INDEX_OUT_OF_BOUNDS",
   "TUPLE_FIELD_OUT_OF_BOUNDS",
@@ -159,7 +156,7 @@ function isBitmaskOp(opBase: number): boolean {
 ///////////////////////////////////////////////////////////////////////////
 
 /** Return the incompatibility reason, or null if the operator is allowed. */
-function getIncompat(opBase: number, typeInfo: TypeInfo): { code: string; message: string } | null {
+function getIncompat(opBase: number, typeInfo: TypeInfo): { code: IssueCode; message: string } | null {
   const { typeCode, isDynamic, staticSize } = typeInfo;
   if (isValueOp(opBase)) {
     if (isDynamic || staticSize !== 32) {
@@ -1036,13 +1033,13 @@ function validateGroup(data: PolicyData, descBytes: Uint8Array, groupIndex: numb
       let typeInfo: TypeInfo;
       if (constraint.scope === Scope.CALLDATA) {
         // Compatibility warnings against the limits the spec fixes (PWF-17, PV-7).
-        if (steps.length > Limits.MAX_PATH_DEPTH) {
+        if (steps.length > PolicyFormat.MAX_PATH_DEPTH) {
           issues.push(
             ValidationIssue.pathDepthExceeded(
               groupIndex,
               constraintIndex,
               bigintToHex(BigInt(steps.length)),
-              bigintToHex(BigInt(Limits.MAX_PATH_DEPTH)),
+              bigintToHex(BigInt(PolicyFormat.MAX_PATH_DEPTH)),
             ),
           );
         }
@@ -1051,7 +1048,7 @@ function validateGroup(data: PolicyData, descBytes: Uint8Array, groupIndex: numb
           walk = Descriptor.walkPath(descBytes, steps);
         } catch (error) {
           // Navigability faults become issues; anything else propagates.
-          if (error instanceof CallciumError && NAVIGABILITY_CODES.has(error.code)) {
+          if (error instanceof CallciumError && navigabilityCodes.has(error.code)) {
             issues.push(ValidationIssue.unnavigablePath(groupIndex, constraintIndex));
             continue;
           }
@@ -1062,13 +1059,13 @@ function validateGroup(data: PolicyData, descBytes: Uint8Array, groupIndex: numb
           issues.push(ValidationIssue.nestedQuantifier(groupIndex, constraintIndex));
           continue;
         }
-        if (walk.quantifiedStaticLength > Limits.MAX_QUANTIFIED_ARRAY_LENGTH) {
+        if (walk.quantifiedStaticLength > PolicyFormat.MAX_QUANTIFIED_ARRAY_LENGTH) {
           issues.push(
             ValidationIssue.quantifierOverStaticLimit(
               groupIndex,
               constraintIndex,
               bigintToHex(BigInt(walk.quantifiedStaticLength)),
-              bigintToHex(BigInt(Limits.MAX_QUANTIFIED_ARRAY_LENGTH)),
+              bigintToHex(BigInt(PolicyFormat.MAX_QUANTIFIED_ARRAY_LENGTH)),
             ),
           );
         }
@@ -1103,7 +1100,7 @@ function validateGroup(data: PolicyData, descBytes: Uint8Array, groupIndex: numb
     if (
       constraint.scope === Scope.CALLDATA &&
       constraint.hint !== undefined &&
-      ctx.steps.length <= Limits.MAX_PATH_DEPTH
+      ctx.steps.length <= PolicyFormat.MAX_PATH_DEPTH
     ) {
       const compiled = bytesToHex(Descriptor.compileHint(descBytes, ctx.steps));
       if (compiled !== constraint.hint.toLowerCase()) {

package/src/type-desc.ts

@@ -48,7 +48,7 @@ export function function_(): Uint8Array {
  */
 export function uintN(bits: number): Uint8Array {
   if (bits < 8 || bits > 256 || bits % 8 !== 0) {
-    throw new CallciumError("UNKNOWN_TYPE", `Invalid uintN bits: ${bits}. Must be 8–256 in steps of 8.`);
+    throw new CallciumError("UNKNOWN_TYPE", `Invalid uintN bits: ${bits}. Must be 8–256 in steps of 8`);
   }
   return new Uint8Array([TypeCode.UINT_MIN + (bits / 8 - 1)]);
 }
@@ -60,7 +60,7 @@ export function uintN(bits: number): Uint8Array {
  */
 export function intN(bits: number): Uint8Array {
   if (bits < 8 || bits > 256 || bits % 8 !== 0) {
-    throw new CallciumError("UNKNOWN_TYPE", `Invalid intN bits: ${bits}. Must be 8–256 in steps of 8.`);
+    throw new CallciumError("UNKNOWN_TYPE", `Invalid intN bits: ${bits}. Must be 8–256 in steps of 8`);
   }
   return new Uint8Array([TypeCode.INT_MIN + (bits / 8 - 1)]);
 }
@@ -82,7 +82,7 @@ export function string_(): Uint8Array {
  */
 export function bytesN(n: number): Uint8Array {
   if (n < 1 || n > 32) {
-    throw new CallciumError("UNKNOWN_TYPE", `Invalid bytesN size: ${n}. Must be 1–32.`);
+    throw new CallciumError("UNKNOWN_TYPE", `Invalid bytesN size: ${n}. Must be 1–32`);
   }
   return new Uint8Array([TypeCode.FIXED_BYTES_MIN + (n - 1)]);
 }
@@ -108,7 +108,7 @@ export function array(elemDesc: Uint8Array, length?: number): Uint8Array {
     if (nodeLength > DF.MAX_NODE_LENGTH) {
       throw new CallciumError(
         "NODE_LENGTH_TOO_LARGE",
-        `Dynamic array node length ${nodeLength} exceeds maximum ${DF.MAX_NODE_LENGTH}.`,
+        `Dynamic array node length ${nodeLength} exceeds maximum ${DF.MAX_NODE_LENGTH}`,
       );
     }
     const meta24 = (0 << DF.META_STATIC_WORDS_SHIFT) | nodeLength;
@@ -123,14 +123,14 @@ export function array(elemDesc: Uint8Array, length?: number): Uint8Array {
   if (length <= 0 || length > DF.MAX_STATIC_ARRAY_LENGTH) {
     throw new CallciumError(
       "INVALID_ARRAY_LENGTH",
-      `Static array length ${length} out of range. Must be 1–${DF.MAX_STATIC_ARRAY_LENGTH}.`,
+      `Static array length ${length} out of range. Must be 1–${DF.MAX_STATIC_ARRAY_LENGTH}`,
     );
   }
   const nodeLength = DF.ARRAY_HEADER_SIZE + elemDesc.length + DF.ARRAY_LENGTH_SIZE;
   if (nodeLength > DF.MAX_NODE_LENGTH) {
     throw new CallciumError(
       "NODE_LENGTH_TOO_LARGE",
-      `Static array node length ${nodeLength} exceeds maximum ${DF.MAX_NODE_LENGTH}.`,
+      `Static array node length ${nodeLength} exceeds maximum ${DF.MAX_NODE_LENGTH}`,
     );
   }
   const elemStaticWords = extractStaticWords(elemDesc);
@@ -138,7 +138,7 @@ export function array(elemDesc: Uint8Array, length?: number): Uint8Array {
   if (staticWords > DF.MAX_STATIC_WORDS) {
     throw new CallciumError(
       "STATIC_WORDS_TOO_LARGE",
-      `Static array static words ${staticWords} exceeds maximum ${DF.MAX_STATIC_WORDS}.`,
+      `Static array static words ${staticWords} exceeds maximum ${DF.MAX_STATIC_WORDS}`,
     );
   }
   const meta24 = (staticWords << DF.META_STATIC_WORDS_SHIFT) | nodeLength;
@@ -162,7 +162,7 @@ export function tuple(fieldDescs: Uint8Array[]): Uint8Array {
   if (fieldDescs.length === 0 || fieldDescs.length > DF.MAX_TUPLE_FIELDS) {
     throw new CallciumError(
       "INVALID_TUPLE_FIELD_COUNT",
-      `Tuple field count ${fieldDescs.length} out of range. Must be 1–${DF.MAX_TUPLE_FIELDS}.`,
+      `Tuple field count ${fieldDescs.length} out of range. Must be 1–${DF.MAX_TUPLE_FIELDS}`,
     );
   }
   const totalFieldBytes = fieldDescs.reduce((sum, f) => sum + f.length, 0);
@@ -170,7 +170,7 @@ export function tuple(fieldDescs: Uint8Array[]): Uint8Array {
   if (nodeLength > DF.MAX_NODE_LENGTH) {
     throw new CallciumError(
       "NODE_LENGTH_TOO_LARGE",
-      `Tuple node length ${nodeLength} exceeds maximum ${DF.MAX_NODE_LENGTH}.`,
+      `Tuple node length ${nodeLength} exceeds maximum ${DF.MAX_NODE_LENGTH}`,
     );
   }
 
@@ -187,7 +187,7 @@ export function tuple(fieldDescs: Uint8Array[]): Uint8Array {
   if (staticWords > DF.MAX_STATIC_WORDS) {
     throw new CallciumError(
       "STATIC_WORDS_TOO_LARGE",
-      `Tuple static words ${staticWords} exceeds maximum ${DF.MAX_STATIC_WORDS}.`,
+      `Tuple static words ${staticWords} exceeds maximum ${DF.MAX_STATIC_WORDS}`,
     );
   }
   const meta24 = (staticWords << DF.META_STATIC_WORDS_SHIFT) | nodeLength;

package/src/types.ts

@@ -130,7 +130,7 @@ export type CalldataNavigationViolation =
   | CalldataNavigationVariant<"CALLDATA_OUT_OF_BOUNDS">
   | CalldataNavigationVariant<"ARRAY_INDEX_OUT_OF_BOUNDS">;
 
-/** A quantified array exceeded `Limits.MAX_QUANTIFIED_ARRAY_LENGTH`. */
+/** A quantified array exceeded `PolicyFormat.MAX_QUANTIFIED_ARRAY_LENGTH`. */
 export type QuantifierLimitExceededViolation = {
   code: "QUANTIFIER_LIMIT_EXCEEDED";
   group: number;
@@ -142,7 +142,7 @@ export type QuantifierLimitExceededViolation = {
 };
 
 /**
- * A resolved word is not the canonical encoding of its declared type (spec §7.4).
+ * A resolved word is not the canonical encoding of its declared type.
  *
  * `resolvedValue` is the raw 32-byte word as it appeared in calldata, before any masking.
  */
@@ -274,13 +274,80 @@ export type IssueSeverity = "info" | "warning" | "error";
 /** Category of a validation issue. */
 export type IssueCategory = "typeMismatch" | "contradiction" | "redundancy" | "vacuity" | "compatibility";
 
+/**
+ * Machine-readable code for a policy validation issue.
+ *
+ * Each code names one finding of the semantic validator and matches the constant of the same
+ * name in the Solidity `IssueCode` library.
+ */
+export type IssueCode =
+  // Type mismatch.
+  | "VALUE_OP_ON_DYNAMIC"
+  | "VALUE_OP_ON_COMPOSITE"
+  | "NUMERIC_OP_ON_NON_NUMERIC"
+  | "BITMASK_ON_INVALID"
+  | "IN_ON_BOOL"
+  | "LENGTH_ON_STATIC"
+  | "CONTEXT_TYPE_MISMATCH"
+  | "UNKNOWN_OPERATOR"
+  | "NON_CANONICAL_OPERAND"
+  | "UNNAVIGABLE_PATH"
+  | "NESTED_QUANTIFIER"
+  | "HINT_MISMATCH"
+  // Contradiction.
+  | "EQ_NEQ_CONTRADICTION"
+  | "CONFLICTING_EQUALITY"
+  | "OUT_OF_PHYSICAL_BOUNDS"
+  | "IMPOSSIBLE_GT"
+  | "IMPOSSIBLE_LT"
+  | "BOUNDS_EXCLUDE_EQUALITY"
+  | "IMPOSSIBLE_RANGE"
+  | "SET_EXCLUDES_EQUALITY"
+  | "EMPTY_SET_INTERSECTION"
+  | "SET_FULLY_EXCLUDED"
+  | "LENGTH_EQ_NEQ_CONTRADICTION"
+  | "CONFLICTING_LENGTH"
+  | "BOUNDS_EXCLUDE_LENGTH"
+  | "IMPOSSIBLE_LENGTH_RANGE"
+  | "OUT_OF_PHYSICAL_LENGTH_BOUNDS"
+  | "IMPOSSIBLE_LENGTH_GT"
+  | "IMPOSSIBLE_LENGTH_LT"
+  | "BITMASK_CONTRADICTION"
+  | "BITMASK_ANY_IMPOSSIBLE"
+  | "UNSORTED_IN_SET"
+  | "EMPTY_GROUP"
+  // Redundancy.
+  | "DOMINATED_BOUND"
+  | "REDUNDANT_BOUND"
+  | "SET_REDUCTION"
+  | "SET_REDUNDANCY"
+  | "SET_PARTIALLY_EXCLUDED"
+  | "DOMINATED_LENGTH_BOUND"
+  | "REDUNDANT_LENGTH_BOUND"
+  | "REDUNDANT_BITMASK"
+  | "DUPLICATE_CONSTRAINT"
+  | "FUSIBLE_RANGE"
+  | "FUSIBLE_LENGTH_RANGE"
+  // Vacuity.
+  | "VACUOUS_GTE"
+  | "VACUOUS_LTE"
+  | "VACUOUS_LENGTH_GTE"
+  | "VACUOUS_LENGTH_LTE"
+  | "VACUOUS_NEGATED_RANGE"
+  | "VACUOUS_NEGATED_LENGTH_RANGE"
+  // Compatibility.
+  | "PATH_DEPTH_EXCEEDED"
+  | "QUANTIFIER_OVER_STATIC_LIMIT"
+  | "UNKNOWN_CONTEXT_PROPERTY"
+  | "NEGATION_UNDER_ANY";
+
 /** A single validation issue found during policy analysis. */
 export type Issue = {
   severity: IssueSeverity;
   category: IssueCategory;
   groupIndex: number;
   constraintIndex: number;
-  code: string;
+  code: IssueCode;
   value1: Hex;
   value2: Hex;
   message: string;

package/src/validation-issue.ts

@@ -1,4 +1,4 @@
-import type { Hex, Issue } from "./types";
+import type { Hex, Issue, IssueCode } from "./types";
 
 ///////////////////////////////////////////////////////////////////////////
 // Constants
@@ -12,7 +12,7 @@ const ZERO: Hex = `0x${"0".repeat(64)}`;
 
 /** Create an issue from operator compatibility results. */
 export function fromOpRule(
-  code: string,
+  code: IssueCode,
   message: string,
   groupIndex: number,
   constraintIndex: number,
@@ -304,7 +304,7 @@ export function unsortedInSet(groupIndex: number, constraintIndex: number): Issu
     code: "UNSORTED_IN_SET",
     value1: ZERO,
     value2: ZERO,
-    message: "isIn/notIn set is not strictly sorted and deduplicated.",
+    message: "isIn/notIn set is not strictly sorted and deduplicated",
   };
 }
 
@@ -318,7 +318,7 @@ export function emptyGroup(groupIndex: number): Issue {
     code: "EMPTY_GROUP",
     value1: ZERO,
     value2: ZERO,
-    message: "Group contains zero constraints.",
+    message: "Group contains zero constraints",
   };
 }