@callcium/sdk 0.10.0 → 0.11.0

package/src/descriptor.ts

@@ -1,6 +1,7 @@
 import { readU16, readU24, writeBE16, writeBE32 } from "./bytes";
 import { DescriptorFormat as DF, PolicyFormat as PF, TypeCode } from "./constants";
 import { CallciumError } from "./errors";
+import { classifyTypeCode } from "./operators";
 import { Quantifier, isQuantifier } from "./path";
 
 ///////////////////////////////////////////////////////////////////////////
@@ -41,15 +42,51 @@ type HintWalk = {
 // Internal helpers
 ///////////////////////////////////////////////////////////////////////////
 
+/** A descriptor node's type code, static word count, and total byte length. */
+type Node = { typeCode: number; staticWords: number; nodeLength: number };
+
+/**
+ * Read the node at `offset`.
+ * Elementary nodes occupy exactly one byte; composite nodes encode their static
+ * word count and length in the 24-bit meta field that follows the type code.
+ * @throws {CallciumError} When the node starts past the descriptor, carries an undefined type code,
+ * or declares a length below its own header or beyond the descriptor.
+ */
+export function readNode(desc: Uint8Array, offset: number): Node {
+  if (offset >= desc.length) {
+    throw new CallciumError("UNEXPECTED_END", "Unexpected end of descriptor", offset);
+  }
+  const typeCode = desc[offset]!;
+  const info = classifyTypeCode(typeCode);
+  if (info.typeClass === "elementary") {
+    return { typeCode, staticWords: info.isDynamic ? 0 : 1, nodeLength: DF.TYPECODE_SIZE };
+  }
+
+  if (offset + DF.TYPECODE_SIZE + DF.COMPOSITE_META_SIZE > desc.length) {
+    throw new CallciumError("UNEXPECTED_END", "Incomplete composite metadata", offset);
+  }
+  const meta = readU24(desc, offset + DF.TYPECODE_SIZE);
+  const length = meta & DF.META_NODE_LENGTH_MASK;
+  const minHeader = info.typeClass === "tuple" ? DF.TUPLE_HEADER_SIZE : DF.ARRAY_HEADER_SIZE;
+  if (length < minHeader) {
+    throw new CallciumError(
+      "NODE_LENGTH_TOO_SMALL",
+      `Composite node length ${length} is smaller than minimum header ${minHeader}`,
+      offset,
+    );
+  }
+  if (offset + length > desc.length) {
+    throw new CallciumError("NODE_OVERFLOW", "Composite node extends beyond descriptor", offset);
+  }
+  return { typeCode, staticWords: meta >> DF.META_STATIC_WORDS_SHIFT, nodeLength: length };
+}
+
 /**
  * Return the byte length of the node at `offset`.
- * Elementary nodes occupy exactly one byte; composite nodes encode their
- * length in the lower 12 bits of the 24-bit meta field.
+ * @throws {CallciumError} When the descriptor holds no readable node at `offset`.
  */
 function nodeLength(desc: Uint8Array, offset: number): number {
-  const typeCode = desc[offset]!;
-  if (typeCode < TypeCode.STATIC_ARRAY) return DF.TYPECODE_SIZE;
-  return readU24(desc, offset + 1) & DF.META_NODE_LENGTH_MASK;
+  return readNode(desc, offset).nodeLength;
 }
 
 /**
@@ -68,14 +105,20 @@ function tupleFieldOffset(desc: Uint8Array, tupleOffset: number, fieldIndex: num
 // Public interface
 ///////////////////////////////////////////////////////////////////////////
 
-/** Return paramCount from header byte 1. */
+/**
+ * Return the declared top-level parameter count.
+ * @throws {CallciumError} When the descriptor is too short to hold a header.
+ */
 function paramCount(desc: Uint8Array): number {
+  if (desc.length < DF.HEADER_SIZE) {
+    throw new CallciumError("MALFORMED_HEADER", "Descriptor too short for header");
+  }
   return desc[1]!;
 }
 
 /** Return byte offset of the N-th top-level param (0-indexed). */
 function paramOffset(desc: Uint8Array, index: number): number {
-  const count = desc[1]!;
+  const count = paramCount(desc);
   if (index >= count) {
     throw new CallciumError("PARAM_INDEX_OUT_OF_BOUNDS", `Param index ${index} out of range (paramCount=${count})`);
   }
@@ -91,17 +134,11 @@ function paramOffset(desc: Uint8Array, index: number): number {
  * @param desc - Raw descriptor bytes.
  * @param offset - Byte position of the node.
  * @returns typeCode, isDynamic, and staticSize in bytes.
+ * @throws {CallciumError} When the descriptor holds no readable node at `offset`.
  */
 function inspect(desc: Uint8Array, offset: number): TypeInfo {
-  const typeCode = desc[offset]!;
-  let staticWords: number;
-  if (typeCode < TypeCode.STATIC_ARRAY) {
-    staticWords = typeCode === TypeCode.BYTES || typeCode === TypeCode.STRING ? 0 : 1;
-  } else {
-    staticWords = readU24(desc, offset + 1) >> DF.META_STATIC_WORDS_SHIFT;
-  }
-  const isDynamic = staticWords === 0;
-  return { typeCode, isDynamic, staticSize: staticWords * 32 };
+  const { typeCode, staticWords } = readNode(desc, offset);
+  return { typeCode, isDynamic: staticWords === 0, staticSize: staticWords * 32 };
 }
 
 /**
@@ -134,16 +171,7 @@ function walkPath(desc: Uint8Array, steps: number[]): { typeInfo: TypeInfo; quan
     throw new CallciumError("EMPTY_PATH", "Path must have at least one step");
   }
 
-  const paramIndex = steps[0]!;
-  const count = desc[1]!;
-  if (paramIndex >= count) {
-    throw new CallciumError(
-      "PARAM_INDEX_OUT_OF_BOUNDS",
-      `Param index ${paramIndex} out of range (paramCount=${count})`,
-    );
-  }
-
-  let cursor = paramOffset(desc, paramIndex);
+  let cursor = paramOffset(desc, steps[0]!);
   let quantifiedStaticLength = 0;
 
   for (let stepIndex = 1; stepIndex < steps.length; stepIndex++) {

package/src/errors.ts

@@ -1,8 +1,11 @@
 /**
  * Machine-readable error code for structural decoding and validation failures.
  *
- * Each code names one invariant and matches the Solidity error raised for the same
- * invariant, transliterated from `PascalCase` to `SCREAMING_SNAKE_CASE`.
+ * Each code names one invariant. Where Solidity detects the same invariant, the code is its error
+ * name transliterated from `PascalCase` to `SCREAMING_SNAKE_CASE`. The codes under "Inputs and
+ * validation" have no counterpart: they name input a Solidity signature cannot express.
+ * `OUT_OF_PHYSICAL_BOUNDS` names an invariant Solidity carries twice, as the error
+ * `PolicyBuilder.OutOfPhysicalBounds` and as an issue code, so the name is shared with `IssueCode`.
  */
 export type CallciumErrorCode =
   // Policy and descriptor framing.
@@ -47,6 +50,7 @@ export type CallciumErrorCode =
   | "EMPTY_SET"
   | "SET_TOO_LARGE"
   | "INVALID_RANGE"
+  | "OUT_OF_PHYSICAL_BOUNDS"
   // Descriptor nodes.
   | "UNKNOWN_TYPE_CODE"
   | "NODE_LENGTH_TOO_SMALL"
@@ -72,6 +76,10 @@ export type CallciumErrorCode =
   // Inputs and validation.
   | "UNKNOWN_QUANTIFIER"
   | "INVALID_HEX"
+  | "MALFORMED_SELECTOR"
+  | "PATH_STEP_OVERFLOW"
+  | "OPERAND_OVERFLOW"
+  | "CONTEXT_VALUE_OVERFLOW"
   | "VALIDATION_ERROR";
 
 /**
@@ -88,6 +96,8 @@ export class CallciumError extends Error {
     super(`${prefix}${message}`);
     this.name = "CallciumError";
     this.code = code;
+    // The property is declared optional, so it stays absent rather than present and undefined.
+    if (offset !== undefined) this.offset = offset;
   }
 }
 

package/src/index.ts

@@ -46,6 +46,7 @@ export {
   Scope,
   ContextProperty,
   MAX_CONTEXT_PROPERTY_ID,
+  findContextProperty,
   lookupOp,
   lookupScope,
   lookupContextProperty,

package/src/operators.ts

@@ -1,6 +1,9 @@
-import { Op, TypeCode, operandsOf } from "./constants";
+import { hexToBytes } from "./bytes";
+import { DescriptorFormat as DF, formatCode, Op, PolicyFormat as PF, TypeCode, operandsOf } from "./constants";
 import { CallciumError } from "./errors";
 
+import type { Hex } from "./types";
+
 /** Read a big-endian 256-bit unsigned integer from a 32-byte window. */
 export function toBigInt(bytes: Uint8Array, offset = 0): bigint {
   const view = new DataView(bytes.buffer, bytes.byteOffset + offset, 32);
@@ -128,7 +131,7 @@ function isIn(value: bigint, data: Uint8Array): boolean {
 export function applyOperator(
   opCode: number,
   value: bigint,
-  valueLength: number,
+  valueLength: bigint,
   operandData: Uint8Array,
   typeCode: number,
 ): boolean {
@@ -138,7 +141,7 @@ export function applyOperator(
   // value and the opcode maps onto its EQ/GT/LT/GTE/LTE/BETWEEN twin. Counts are non-negative,
   // so the comparison is always unsigned — force an unsigned type code regardless of the target.
   if (isLengthOp(base)) {
-    value = BigInt(valueLength);
+    value = valueLength;
     typeCode = TypeCode.UINT_MAX;
     base = lengthToValueOp(base);
   }
@@ -196,7 +199,7 @@ 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 ${formatCode(base, PF.RULE_OPCODE_SIZE)}`);
   }
 
   const negate = (opCode & Op.NOT) !== 0;
@@ -217,6 +220,20 @@ export function isValidOperatorData(opBase: number, dataLength: number): boolean
   return false;
 }
 
+/**
+ * Read an operator's encoding as bytes: one opcode byte followed by its data payload.
+ * @param operator - 0x-prefixed hex string holding a single operator.
+ * @returns The operator's bytes, opcode first.
+ * @throws {CallciumError} If the hex is malformed or carries no opcode byte.
+ */
+export function toOperatorBytes(operator: Hex): Uint8Array {
+  const bytes = hexToBytes(operator);
+  if (bytes.length < 1) {
+    throw new CallciumError("INVALID_OPERATOR_BYTES", "Operator must have at least one byte (opcode)");
+  }
+  return bytes;
+}
+
 ///////////////////////////////////////////////////////////////////////////
 // Type code classification
 ///////////////////////////////////////////////////////////////////////////
@@ -232,7 +249,7 @@ 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")}`);
+  throw new CallciumError("UNKNOWN_TYPE_CODE", `Unknown type code ${formatCode(code, DF.TYPECODE_SIZE)}`);
 }
 
 // Pre-allocated constant objects for fixed type codes (avoids per-call allocation).
@@ -264,6 +281,20 @@ export function classifyTypeCode(code: number): TypeClassInfo {
   unknownTypeCode(code);
 }
 
+/**
+ * Determine whether a type code names an elementary type.
+ * @param code - A single-byte descriptor type code.
+ * @returns True for an elementary code; false for a composite or unassigned one.
+ */
+export function isElementary(code: number): boolean {
+  try {
+    // An undefined code is reported by a throw, and names no elementary type either way.
+    return classifyTypeCode(code).typeClass === "elementary";
+  } catch {
+    return false;
+  }
+}
+
 /**
  * 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.

package/src/path.ts

@@ -1,5 +1,5 @@
 import { bytesToHex, hexToBytes, readU16, writeBE16 } from "./bytes";
-import { buildCodeMap, PolicyFormat as PF } from "./constants";
+import { buildCodeMap, formatCode, PolicyFormat as PF } from "./constants";
 import { CallciumError } from "./errors";
 
 import type { Hex } from "./types";
@@ -20,7 +20,7 @@ export const Quantifier = buildCodeMap(QUANTIFIER_TABLE);
 export type QuantifierInfo = { label: string };
 
 const quantifierByCode: ReadonlyMap<number, QuantifierInfo> = new Map<number, QuantifierInfo>(
-  QUANTIFIER_TABLE.map((e) => [e.code, { label: e.label }]),
+  QUANTIFIER_TABLE.map((entry) => [entry.code, { label: entry.label }]),
 );
 
 /** Check whether a path step is a quantifier (ALL or ANY). */
@@ -36,7 +36,8 @@ export function isQuantifier(step: number): boolean {
  */
 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)}`);
+  if (!info)
+    throw new CallciumError("UNKNOWN_QUANTIFIER", `Unknown quantifier step ${formatCode(code, PF.PATH_STEP_SIZE)}`);
   return info;
 }
 
@@ -44,11 +45,19 @@ export function lookupQuantifier(code: number): QuantifierInfo {
 // Path steps
 ///////////////////////////////////////////////////////////////////////////
 
-/** Encode a sequence of uint16 path steps as a big-endian hex string. */
+/**
+ * Encode a sequence of uint16 path steps as a big-endian hex string.
+ * @throws {CallciumError} When a step is not an integer the field holds. A wrapped step would
+ * address a different argument.
+ */
 export function encodePath(steps: readonly number[]): Hex {
-  const buffer = new Uint8Array(steps.length * 2);
+  const buffer = new Uint8Array(steps.length * PF.PATH_STEP_SIZE);
   for (let i = 0; i < steps.length; i++) {
-    writeBE16(buffer, i * 2, steps[i]!);
+    const step = steps[i]!;
+    if (!Number.isInteger(step) || step < 0 || step > PF.PATH_STEP_MAX) {
+      throw new CallciumError("PATH_STEP_OVERFLOW", `Path step ${step} is outside the path step field`);
+    }
+    writeBE16(buffer, i * PF.PATH_STEP_SIZE, step);
   }
   return bytesToHex(buffer);
 }

package/src/policy-builder.ts

@@ -1,9 +1,10 @@
 import { bytesToHex } from "./bytes";
-import { Scope, TypeCode, MAX_CONTEXT_PROPERTY_ID } from "./constants";
-import { ConstraintBuilder } from "./constraint";
+import { Scope, TypeCode, lookupContextProperty } from "./constants";
+import { readOperandExtremes } from "./constraint";
 import { Descriptor } from "./descriptor";
 import { DescriptorCoder } from "./descriptor-coder";
 import { CallciumError, ValidationError } from "./errors";
+import { isSigned } from "./operators";
 import { isQuantifier, parsePathSteps } from "./path";
 import { PolicyCoder } from "./policy-coder";
 import { PolicyValidator } from "./policy-validator";
@@ -20,29 +21,24 @@ type PolicyDraft = {
   selector: Hex;
   descriptor: Uint8Array;
   groups: Constraint[][];
-  pathHashes: Set<string>[];
+  /** Scope-qualified paths already taken in the group being built. */
+  groupPathKeys: Set<string>;
 };
 
 ///////////////////////////////////////////////////////////////////////////
 // Path validation
 ///////////////////////////////////////////////////////////////////////////
 
-/** Validate a context-scope path. */
-function validateContextPath(steps: number[]): void {
+/** Validate a context-scope path and return the referenced property's type code. */
+function validateContextPath(steps: number[]): number {
   if (steps.length !== 1) {
     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")}`,
-    );
-  }
+  return lookupContextProperty(steps[0]!).typeCode;
 }
 
-/** Validate a calldata-scope path against the descriptor. */
-function validateCalldataPath(steps: number[], desc: Uint8Array): void {
+/** Validate a calldata-scope path against the descriptor and return the target's type code. */
+function validateCalldataPath(steps: number[], desc: Uint8Array): number {
   const argIndex = steps[0]!;
   const paramCount = Descriptor.paramCount(desc);
   if (argIndex >= paramCount) {
@@ -94,6 +90,63 @@ function validateCalldataPath(steps: number[], desc: Uint8Array): void {
       throw new CallciumError("NOT_COMPOSITE", "Cannot descend into an elementary type");
     }
   }
+
+  return Descriptor.inspect(desc, offset).typeCode;
+}
+
+///////////////////////////////////////////////////////////////////////////
+// Operand domain
+///////////////////////////////////////////////////////////////////////////
+
+// Values a 32-byte word represents, which is the distance between an operand and its alias.
+const WORD_VALUES = 1n << 256n;
+
+/** Integers an integer target admits, or null for any other type. */
+function targetBounds(typeCode: number): { min: bigint; max: bigint } | null {
+  if (typeCode >= TypeCode.UINT_MIN && typeCode <= TypeCode.UINT_MAX) {
+    const bits = BigInt(typeCode - TypeCode.UINT_MIN + 1) * 8n;
+    return { min: 0n, max: (1n << bits) - 1n };
+  }
+  if (typeCode >= TypeCode.INT_MIN && typeCode <= TypeCode.INT_MAX) {
+    const bits = BigInt(typeCode - TypeCode.INT_MIN + 1) * 8n;
+    const half = 1n << (bits - 1n);
+    return { min: -half, max: half - 1n };
+  }
+  return null;
+}
+
+/** Reject an operand outside the target's range whose word carries a value inside it. */
+function reject(written: bigint, folded: bigint): never {
+  throw new CallciumError(
+    "OUT_OF_PHYSICAL_BOUNDS",
+    `Operand ${written} is outside the physical range of the type and encodes as ${folded}`,
+  );
+}
+
+/**
+ * Reject an operand that two's complement folds onto a value the target admits.
+ * Such an operand and the value it folds onto encode to one word, so the operands as written are
+ * the only place the two stay distinct. An operand spans no more than one word, which leaves two
+ * ways across: a negative's alias clears every target narrower than the whole word, and a positive
+ * reaches a signed range only at that type's own minimum word.
+ */
+function checkOperandDomain(constraint: Constraint, typeCode: number): void {
+  const bounds = targetBounds(typeCode);
+  const extremes = readOperandExtremes(constraint);
+  if (bounds === null || extremes === undefined) return;
+
+  // A negative operand occupies the word its unsigned alias does, which only the target holding
+  // the whole word can hold too.
+  if (extremes.leastNegative < 0n && typeCode === TypeCode.UINT_MAX) {
+    reject(extremes.leastNegative, extremes.leastNegative + WORD_VALUES);
+  }
+
+  if (!isSigned(typeCode)) return;
+  // An operand at or above the signed minimum's own word denotes that negative, and every such
+  // operand already exceeds the signed maximum.
+  if (extremes.greatest >= WORD_VALUES + bounds.min) {
+    reject(extremes.greatest, extremes.greatest - WORD_VALUES);
+  }
 }
 
 ///////////////////////////////////////////////////////////////////////////
@@ -120,7 +173,7 @@ export class PolicyBuilder {
       selector: parsed.selector,
       descriptor,
       groups: [[]],
-      pathHashes: [new Set()],
+      groupPathKeys: new Set(),
     });
   }
 
@@ -135,47 +188,54 @@ export class PolicyBuilder {
       selector: "0x00000000",
       descriptor,
       groups: [[]],
-      pathHashes: [new Set()],
+      groupPathKeys: new Set(),
     });
   }
 
   /**
    * Add a constraint to the current group.
    * @param constraint - A `Constraint` object or a `ConstraintBuilder` instance.
+   * @throws {CallciumError} With code `OUT_OF_PHYSICAL_BOUNDS` when a numeric operand lies outside
+   * the target type's range and encodes as a value inside it. Operands are read as written, so a
+   * `Constraint` carrying encoded operator bytes is left to {@link validate}.
    */
-  add(constraint: Constraint | ConstraintBuilder): this {
-    const c: Constraint = {
+  add(constraint: Constraint): this {
+    // A builder compiles no hint; one arrives only on a constraint that came already encoded.
+    const added: Constraint = {
       scope: constraint.scope,
       path: constraint.path,
       operators: [...constraint.operators],
+      ...("hint" in constraint && constraint.hint !== undefined && { hint: constraint.hint }),
     };
 
-    if (c.operators.length === 0) {
+    if (added.operators.length === 0) {
       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);
+    const steps = parsePathSteps(added.path);
     if (steps.length === 0) {
       throw new CallciumError("EMPTY_PATH", "Path must have at least one step");
     }
 
-    if (c.scope === Scope.CONTEXT) {
-      validateContextPath(steps);
-    } else if (c.scope === Scope.CALLDATA) {
-      validateCalldataPath(steps, this.draft.descriptor);
+    let targetTypeCode: number;
+    if (added.scope === Scope.CONTEXT) {
+      targetTypeCode = validateContextPath(steps);
+    } else if (added.scope === Scope.CALLDATA) {
+      targetTypeCode = validateCalldataPath(steps, this.draft.descriptor);
     } else {
-      throw new CallciumError("INVALID_SCOPE", `Unknown scope value ${c.scope}`);
+      throw new CallciumError("INVALID_SCOPE", `Unknown scope value ${added.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`);
+    checkOperandDomain(constraint, targetTypeCode);
+
+    const key = `${added.scope}:${added.path.toLowerCase()}`;
+    if (this.draft.groupPathKeys.has(key)) {
+      throw new CallciumError("DUPLICATE_PATH_IN_GROUP", `Duplicate path ${added.path} in the same group`);
     }
 
-    currentHashes.add(key);
-    this.draft.groups[this.draft.groups.length - 1]!.push(c);
+    this.draft.groupPathKeys.add(key);
+    this.draft.groups[this.draft.groups.length - 1]!.push(added);
     return this;
   }
 
@@ -186,7 +246,7 @@ export class PolicyBuilder {
       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());
+    this.draft.groupPathKeys.clear();
     return this;
   }
 
@@ -197,6 +257,8 @@ export class PolicyBuilder {
    * @returns The policy as a 0x-prefixed hex string.
    * @throws {CallciumError} If any group is empty.
    * @throws {ValidationError} If validation finds any issue.
+   * @throws {CallciumError} With code `RULE_SIZE_OVERFLOW` when a rule's encoded bytes exceed the
+   * width of the rule size field.
    */
   build(): Hex {
     this.checkGroups();