@callcium/sdk 0.9.0 → 0.11.0

package/src/descriptor.ts

@@ -1,6 +1,8 @@
 import { readU16, readU24, writeBE16, writeBE32 } from "./bytes";
-import { DescriptorFormat as DF, PolicyFormat as PF, Quantifier, TypeCode, isQuantifier } from "./constants";
+import { DescriptorFormat as DF, PolicyFormat as PF, TypeCode } from "./constants";
 import { CallciumError } from "./errors";
+import { classifyTypeCode } from "./operators";
+import { Quantifier, isQuantifier } from "./path";
 
 ///////////////////////////////////////////////////////////////////////////
 // Public types
@@ -40,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;
 }
 
 /**
@@ -67,16 +105,22 @@ 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}).`);
+    throw new CallciumError("PARAM_INDEX_OUT_OF_BOUNDS", `Param index ${index} out of range (paramCount=${count})`);
   }
   let cursor = DF.HEADER_SIZE;
   for (let i = 0; i < index; i++) {
@@ -90,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 };
 }
 
 /**
@@ -130,19 +168,10 @@ function typeAt(desc: Uint8Array, steps: number[]): TypeInfo {
  */
 function walkPath(desc: Uint8Array, steps: number[]): { typeInfo: TypeInfo; quantifiedStaticLength: number } {
   if (steps.length === 0) {
-    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}).`,
-    );
+    throw new CallciumError("EMPTY_PATH", "Path must have at least one step");
   }
 
-  let cursor = paramOffset(desc, paramIndex);
+  let cursor = paramOffset(desc, steps[0]!);
   let quantifiedStaticLength = 0;
 
   for (let stepIndex = 1; stepIndex < steps.length; stepIndex++) {
@@ -154,7 +183,7 @@ function walkPath(desc: Uint8Array, steps: number[]): { typeInfo: TypeInfo; quan
       if (step >= fields) {
         throw new CallciumError(
           "TUPLE_FIELD_OUT_OF_BOUNDS",
-          `Tuple field index ${step} out of range (tuple has ${fields} fields).`,
+          `Tuple field index ${step} out of range (tuple has ${fields} fields)`,
         );
       }
       cursor = tupleFieldOffset(desc, cursor, step);
@@ -169,14 +198,14 @@ function walkPath(desc: Uint8Array, steps: number[]): { typeInfo: TypeInfo; quan
           if (step >= length) {
             throw new CallciumError(
               "STATIC_ARRAY_INDEX_OUT_OF_BOUNDS",
-              `Array index ${step} out of range (length=${length}).`,
+              `Array index ${step} out of range (length=${length})`,
             );
           }
         }
       }
       cursor = arrayElementOffset(cursor);
     } else {
-      throw new CallciumError("NOT_COMPOSITE", `Cannot descend into elementary type at offset ${cursor}.`);
+      throw new CallciumError("NOT_COMPOSITE", `Cannot descend into elementary type at offset ${cursor}`);
     }
   }
 
@@ -199,8 +228,8 @@ function tupleFieldCount(desc: Uint8Array, offset: number): number {
  */
 function staticArrayLength(desc: Uint8Array, offset: number): number {
   const elemOffset = arrayElementOffset(offset);
-  const elemLen = nodeLength(desc, elemOffset);
-  const lengthOffset = elemOffset + elemLen;
+  const elemNodeLength = nodeLength(desc, elemOffset);
+  const lengthOffset = elemOffset + elemNodeLength;
   return readU16(desc, lengthOffset);
 }
 
@@ -214,7 +243,7 @@ function arrayElementOffset(offset: number): number {
 
 /** Build the error for a path step that does not resolve to a hop-chain target. */
 function uncompilablePath(stepIndex: number): CallciumError {
-  return new CallciumError("UNCOMPILABLE_PATH", `Path step ${stepIndex} does not resolve to a hop-chain target.`);
+  return new CallciumError("UNCOMPILABLE_PATH", `Path step ${stepIndex} does not resolve to a hop-chain target`);
 }
 
 /** Return the combined head slot span of the `count` nodes at `offset`, and the offset of the node past them. */
@@ -353,7 +382,7 @@ function encodeHint(walk: HintWalk, targetMeta: number, typeCode: number, depth:
  */
 function compileHint(desc: Uint8Array, steps: number[]): Uint8Array {
   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");
   }
 
   const argIndex = steps[0]!;

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,7 +96,8 @@ export class CallciumError extends Error {
     super(`${prefix}${message}`);
     this.name = "CallciumError";
     this.code = code;
-    Object.setPrototypeOf(this, CallciumError.prototype);
+    // The property is declared optional, so it stays absent rather than present and undefined.
+    if (offset !== undefined) this.offset = offset;
   }
 }
 
@@ -106,7 +115,6 @@ export class ValidationError extends CallciumError {
     super("VALIDATION_ERROR", issues[0]?.message ?? "Policy validation failed");
     this.name = "ValidationError";
     this.issues = issues;
-    Object.setPrototypeOf(this, ValidationError.prototype);
   }
 }
 
@@ -126,7 +134,6 @@ export class PolicyViolationError extends Error {
     super(formatDiagnostic(violations[0]));
     this.name = "PolicyViolationError";
     this.violations = violations;
-    Object.setPrototypeOf(this, PolicyViolationError.prototype);
   }
 }
 

package/src/index.ts

@@ -3,7 +3,9 @@
 ///////////////////////////////////////////////////////////////////////////
 
 export { PolicyBuilder } from "./policy-builder";
-export { PolicyCoder, parsePathSteps } from "./policy-coder";
+export { PolicyCoder } from "./policy-coder";
+export { isQuantifier, lookupQuantifier, parsePathSteps, Quantifier } from "./path";
+export type { QuantifierInfo } from "./path";
 export { isOpAllowed, PolicyValidator } from "./policy-validator";
 export {
   arg,
@@ -41,29 +43,17 @@ export {
   Op,
   TypeCode,
   PolicyFormat,
-  Quantifier,
   Scope,
   ContextProperty,
-  Limits,
   MAX_CONTEXT_PROPERTY_ID,
+  findContextProperty,
   lookupOp,
   lookupScope,
   lookupContextProperty,
-  lookupQuantifier,
-  lookupTypeCode,
-  isQuantifier,
-} from "./constants";
-export { isLengthOp } from "./operators";
-export type {
-  Operands,
-  OpInfo,
-  ScopeInfo,
-  ContextPropertyInfo,
-  QuantifierInfo,
-  TypeCodeInfo,
-  TypeClassInfo,
-  TypeClass,
 } from "./constants";
+export { isLengthOp, lookupTypeCode } from "./operators";
+export type { TypeCodeInfo, TypeClassInfo, TypeClass } from "./operators";
+export type { Operands, OpInfo, ScopeInfo, ContextPropertyInfo } from "./constants";
 
 ///////////////////////////////////////////////////////////////////////////
 // Types
@@ -81,6 +71,7 @@ export type {
   DecodedRule,
   DecodedParam,
   Issue,
+  IssueCode,
   IssueSeverity,
   IssueCategory,
   Context,

package/src/operators.ts

@@ -1,6 +1,9 @@
-import { Op, TypeCode } 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);
@@ -28,7 +31,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 +106,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;
 }
@@ -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,9 +199,142 @@ 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;
   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;
+}
+
+/**
+ * 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
+///////////////////////////////////////////////////////////////////////////
+
+/** 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 ${formatCode(code, DF.TYPECODE_SIZE)}`);
+}
+
+// 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 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.
+ * @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,80 @@
+import { bytesToHex, hexToBytes, readU16, writeBE16 } from "./bytes";
+import { buildCodeMap, formatCode, 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((entry) => [entry.code, { label: entry.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 ${formatCode(code, PF.PATH_STEP_SIZE)}`);
+  return info;
+}
+
+///////////////////////////////////////////////////////////////////////////
+// Path steps
+///////////////////////////////////////////////////////////////////////////
+
+/**
+ * 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 * PF.PATH_STEP_SIZE);
+  for (let i = 0; i < steps.length; 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);
+}
+
+/**
+ * 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;
+}