@callcium/sdk 0.11.1 → 0.13.0

package/src/constants.ts

@@ -7,6 +7,7 @@ import { CallciumError } from "./errors";
 /** Binary layout constants for the Callcium descriptor format. */
 export const DescriptorFormat = {
   VERSION: 0x02,
+  HEADER_PARAMCOUNT_OFFSET: 1,
   HEADER_SIZE: 2,
   TYPECODE_SIZE: 1,
   COMPOSITE_META_SIZE: 3,
@@ -28,27 +29,23 @@ export const DescriptorFormat = {
 // Policy format
 ///////////////////////////////////////////////////////////////////////////
 
-/** Byte width of a rule's data length field. */
-const RULE_DATALENGTH_SIZE = 2;
-
-/** Byte width of one path step. */
-const PATH_STEP_SIZE = 2;
-
-/** Byte overhead of a rule header, excluding the path and the operator payload. */
-const RULE_FIXED_OVERHEAD = 7;
-
-/** Highest value a big-endian field of `byteWidth` bytes holds. */
+/** Highest value a big-endian field of `byteWidth` bytes can represent. */
 export function fieldMax(byteWidth: number): number {
   return 256 ** byteWidth - 1;
 }
 
+/** Lowest minor version, the minor of a blob that uses no extension. */
+const MINOR = 0;
+
 /** Binary layout constants and normative limits for the Callcium policy format. */
 export const PolicyFormat = {
-  VERSION: 0x02,
-  VERSION_MASK: 0x0f,
-  FLAG_NO_SELECTOR: 0x10,
-  RESERVED_MASK: 0xe0,
-  HEADER_SIZE: 1,
+  MAJOR: 3,
+  MINOR,
+  SUPPORTED_MINOR: MINOR,
+  MAJOR_SHIFT: 5,
+  MINOR_SHIFT: 1,
+  MINOR_MASK: 0x0f,
+  FLAG_NO_SELECTOR: 0x01,
   SELECTOR_OFFSET: 1,
   SELECTOR_SIZE: 4,
   DESC_LENGTH_OFFSET: 5,
@@ -56,18 +53,20 @@ export const PolicyFormat = {
   DESC_OFFSET: 7,
   GROUP_COUNT_SIZE: 1,
   GROUP_RULECOUNT_SIZE: 2,
-  GROUP_SIZE_SIZE: 4,
   GROUP_HEADER_SIZE: 6,
   RULE_SIZE_SIZE: 2,
   RULE_SCOPE_OFFSET: 2,
+  RULE_SCOPE_SIZE: 1,
   RULE_DEPTH_OFFSET: 3,
+  RULE_DEPTH_SIZE: 1,
   RULE_PATH_OFFSET: 4,
-  PATH_STEP_SIZE,
-  PATH_STEP_MAX: fieldMax(PATH_STEP_SIZE),
+  PATH_STEP_SIZE: 2,
+  PROPERTY_ID_SIZE: 2,
+  RULE_QUANTIFIER_OFFSET: 3,
+  RULE_QUANTIFIER_SIZE: 1,
+  LOOP_DEPTH_OFFSET: 4,
   RULE_OPCODE_SIZE: 1,
-  RULE_DATALENGTH_SIZE,
-  RULE_FIXED_OVERHEAD,
-  RULE_MIN_SIZE: RULE_FIXED_OVERHEAD + PATH_STEP_SIZE,
+  RULE_DATALENGTH_SIZE: 2,
   HINT_HEADER_SIZE: 1,
   HINT_HOP_SIZE: 8,
   HINT_HOP_INDEX_OFFSET: 4,
@@ -78,15 +77,10 @@ export const PolicyFormat = {
   HINT_TARGET_SIZE: 7,
   HINT_TARGET_META_OFFSET: 4,
   HINT_TARGET_TYPECODE_OFFSET: 6,
-  HINT_KIND_NONE: 0x0,
-  HINT_KIND_ALL: 0x1,
-  HINT_KIND_ANY: 0x2,
-  HINT_KIND_MAX: 0x2,
-  HINT_KIND_SHIFT: 6,
   HINT_HOP_COUNT_MASK: 0x3f,
-  HINT_SUFFIX_RESERVED_MASK: 0xc0,
+  HINT_HEADER_RESERVED_MASK: 0xc0,
   HINT_NO_INDEX: 0xffff,
-  HINT_INDEX_RESERVED: 0xfffe,
+  PATH_MARKER_BASE: 0xff00,
   HINT_META_ELEM_DYNAMIC: 0x8000,
   HINT_META_DYNAMIC_ARRAY: 0x4000,
   HINT_META_RESERVED_MASK: 0x3000,
@@ -94,7 +88,6 @@ export const PolicyFormat = {
   // Normative limits.
   MAX_PATH_DEPTH: 32,
   MAX_QUANTIFIED_ARRAY_LENGTH: 256,
-  MAX_SET_MEMBERS: Math.floor(fieldMax(RULE_DATALENGTH_SIZE) / 32),
 } as const satisfies Record<string, number>;
 
 ///////////////////////////////////////////////////////////////////////////
@@ -113,7 +106,7 @@ type CodeMap<T extends readonly { readonly key: string; readonly code: number }[
  * Render a wire code as fixed-width hex.
  * @param code - Code value.
  * @param byteWidth - Byte width of the field the code occupies.
- * @returns The code as `0x`-prefixed hex, or its decimal form when no such field holds it.
+ * @returns The code as `0x`-prefixed hex, or its decimal form when no such field can represent it.
  */
 export function formatCode(code: number, byteWidth: number): string {
   if (!Number.isInteger(code) || code < 0 || code > fieldMax(byteWidth)) return String(code);
@@ -128,37 +121,6 @@ export function buildCodeMap<T extends readonly { readonly key: string; readonly
   return Object.fromEntries(table.map((entry) => [entry.key, entry.code])) as CodeMap<T>;
 }
 
-///////////////////////////////////////////////////////////////////////////
-// Scope codes
-///////////////////////////////////////////////////////////////////////////
-
-const SCOPE_TABLE = [
-  { key: "CONTEXT", code: 0x00, label: "context" },
-  { key: "CALLDATA", code: 0x01, label: "calldata" },
-] as const;
-
-/** Rule scope discriminant: context (EVM environment) vs. calldata (ABI payload). */
-export const Scope = buildCodeMap(SCOPE_TABLE);
-
-/** Display metadata for a scope code. */
-export type ScopeInfo = { label: string };
-
-const scopeByCode: ReadonlyMap<number, ScopeInfo> = new Map<number, ScopeInfo>(
-  SCOPE_TABLE.map((entry) => [entry.code, { label: entry.label }]),
-);
-
-/**
- * Map a scope code to its display label.
- * @param code - Scope byte value.
- * @returns Display metadata for the scope.
- * @throws {CallciumError} If the code is not a recognised scope.
- */
-export function lookupScope(code: number): ScopeInfo {
-  const info = scopeByCode.get(code);
-  if (!info) throw new CallciumError("INVALID_SCOPE", `Unknown scope value ${code}`);
-  return info;
-}
-
 ///////////////////////////////////////////////////////////////////////////
 // Type code ranges
 ///////////////////////////////////////////////////////////////////////////
@@ -233,17 +195,96 @@ export function lookupContextProperty(code: number): ContextPropertyInfo {
   if (!info) {
     throw new CallciumError(
       "UNKNOWN_CONTEXT_PROPERTY",
-      `Unknown context property ID ${formatCode(code, PATH_STEP_SIZE)}`,
+      `Unknown context property ID ${formatCode(code, PolicyFormat.PROPERTY_ID_SIZE)}`,
     );
   }
   return info;
 }
 
+///////////////////////////////////////////////////////////////////////////
+// Scope codes
+///////////////////////////////////////////////////////////////////////////
+
+const SCOPE_TABLE = [
+  { key: "CONTEXT", code: 0x00, label: "context" },
+  { key: "CALLDATA", code: 0x01, label: "calldata" },
+  { key: "LOOP", code: 0x02, label: "loop" },
+] as const;
+
+/** Rule scope discriminant: context (EVM environment), calldata (ABI payload) or loop (array elements). */
+export const Scope = buildCodeMap(SCOPE_TABLE);
+
+/** A defined scope code. */
+export type ScopeCode = (typeof SCOPE_TABLE)[number]["code"];
+
+/** Display metadata for a scope code. */
+export type ScopeInfo = { label: string };
+
+const scopeByCode: ReadonlyMap<number, ScopeInfo> = new Map<number, ScopeInfo>(
+  SCOPE_TABLE.map((entry) => [entry.code, { label: entry.label }]),
+);
+
+/** Check whether a scope byte is a defined scope code. */
+export function isScopeCode(code: number): code is ScopeCode {
+  return scopeByCode.has(code);
+}
+
+/**
+ * Map a scope code to its display label.
+ * @param code - Scope byte value.
+ * @returns Display metadata for the scope.
+ * @throws {CallciumError} If the code is not a recognised scope.
+ */
+export function lookupScope(code: number): ScopeInfo {
+  const info = scopeByCode.get(code);
+  if (!info) throw new CallciumError("UNKNOWN_SCOPE", `Unknown scope value ${code}`);
+  return info;
+}
+
+///////////////////////////////////////////////////////////////////////////
+// Quantifier codes
+///////////////////////////////////////////////////////////////////////////
+
+const QUANTIFIER_TABLE = [
+  { key: "ALL", code: 0x01, label: "all" },
+  { key: "ANY", code: 0x02, label: "any" },
+] as const;
+
+/** Loop quantifier: the body holds for every element (`ALL`) or for some element (`ANY`). */
+export const LoopQuantifier = buildCodeMap(QUANTIFIER_TABLE);
+
+/** A defined loop quantifier code. */
+export type QuantifierCode = (typeof QUANTIFIER_TABLE)[number]["code"];
+
+/** Display metadata for a loop quantifier code. */
+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 quantifier byte is a defined quantifier code. */
+export function isQuantifierCode(code: number): code is QuantifierCode {
+  return quantifierByCode.has(code);
+}
+
+/**
+ * Map a loop quantifier code to its display label.
+ * @param code - Quantifier byte 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 value ${code}`);
+  return info;
+}
+
 ///////////////////////////////////////////////////////////////////////////
 // Operator codes
 ///////////////////////////////////////////////////////////////////////////
 
-/** Operand count category for operator data validation. */
+/** Operand count category of an operator. */
 export type Operands = "single" | "range" | "variadic";
 
 /** @internal */
@@ -255,20 +296,33 @@ const OP_TABLE = [
   { key: "LTE", code: 0x05, label: "<=", operands: "single" },
   { key: "BETWEEN", code: 0x06, label: "between", operands: "range" },
   { key: "IN", code: 0x07, label: "in", operands: "variadic" },
-  { key: "EQ_CTX", code: 0x08, label: "== ctx", operands: "single" },
   { key: "BITMASK_ALL", code: 0x10, label: "bitmask all", operands: "single" },
   { key: "BITMASK_ANY", code: 0x11, label: "bitmask any", operands: "single" },
   { key: "BITMASK_NONE", code: 0x12, label: "bitmask none", operands: "single" },
-  { key: "LENGTH_EQ", code: 0x20, label: "length ==", operands: "single" },
-  { key: "LENGTH_GT", code: 0x21, label: "length >", operands: "single" },
-  { key: "LENGTH_LT", code: 0x22, label: "length <", operands: "single" },
-  { key: "LENGTH_GTE", code: 0x23, label: "length >=", operands: "single" },
-  { key: "LENGTH_LTE", code: 0x24, label: "length <=", operands: "single" },
-  { key: "LENGTH_BETWEEN", code: 0x25, label: "length between", operands: "range" },
+  { key: "LENGTH_EQ", code: 0x18, label: "length ==", operands: "single" },
+  { key: "LENGTH_GT", code: 0x19, label: "length >", operands: "single" },
+  { key: "LENGTH_LT", code: 0x1a, label: "length <", operands: "single" },
+  { key: "LENGTH_GTE", code: 0x1b, label: "length >=", operands: "single" },
+  { key: "LENGTH_LTE", code: 0x1c, label: "length <=", operands: "single" },
+  { key: "LENGTH_BETWEEN", code: 0x1d, label: "length between", operands: "range" },
 ] as const;
 
-/** Callcium policy operator codes. */
-export const Op: CodeMap<typeof OP_TABLE> & { readonly NOT: 0x80 } = { ...buildCodeMap(OP_TABLE), NOT: 0x80 };
+/** Callcium policy operator codes, with the NOT flag and the operand source fields. */
+export const Op = { ...buildCodeMap(OP_TABLE), NOT: 0x80, SOURCE_SHIFT: 5, COMPARISON_MASK: 0x1f } as const;
+
+/** A defined comparison code. */
+export type ComparisonCode = (typeof OP_TABLE)[number]["code"];
+
+const SOURCE_TABLE = [
+  { key: "CONSTANT", code: 0, labelSuffix: "" },
+  { key: "CONTEXT", code: 1, labelSuffix: " ctx" },
+] as const;
+
+/** Operand source: constant values, or a context property. */
+export const Source = buildCodeMap(SOURCE_TABLE);
+
+/** A defined operand source code. */
+export type SourceCode = (typeof SOURCE_TABLE)[number]["code"];
 
 /** Display metadata for an operator code. */
 export type OpInfo = { label: string; operands: Operands };
@@ -277,24 +331,44 @@ const opByCode: ReadonlyMap<number, OpInfo> = new Map<number, OpInfo>(
   OP_TABLE.map((entry) => [entry.code, { label: entry.label, operands: entry.operands }]),
 );
 
+const labelSuffixBySource: ReadonlyMap<number, string> = new Map<number, string>(
+  SOURCE_TABLE.map((entry) => [entry.code, entry.labelSuffix]),
+);
+
+/** Check whether a comparison is a defined comparison code. */
+export function isComparisonCode(code: number): code is ComparisonCode {
+  return opByCode.has(code);
+}
+
+/** Check whether a source is a defined operand source code. */
+export function isSourceCode(code: number): code is SourceCode {
+  return labelSuffixBySource.has(code);
+}
+
+/** The comparison bits of an operator code. */
+export function comparisonOf(opCode: number): number {
+  return opCode & Op.COMPARISON_MASK;
+}
+
+/** The operand source bits of an operator code. */
+export function sourceOf(opCode: number): number {
+  return (opCode & ~Op.NOT) >> Op.SOURCE_SHIFT;
+}
+
 /**
- * Map an operator code to its display label. Strips the NOT flag automatically.
- * @param code - Operator byte value (may include the NOT flag).
+ * Map an operator code to its display label. Strips the NOT flag automatically. A context source adds ` ctx`.
+ * @param code - Operator byte value (can include the NOT flag).
  * @returns Display metadata for the base operator.
  * @throws {CallciumError} If the base code is not a recognised operator.
  */
 export function lookupOp(code: number): OpInfo {
   const base = code & ~Op.NOT;
-  const info = opByCode.get(base);
-  if (!info)
+  const info = opByCode.get(comparisonOf(base));
+  const labelSuffix = labelSuffixBySource.get(sourceOf(base));
+  if (!info || labelSuffix === undefined)
     throw new CallciumError(
       "UNKNOWN_OPERATOR",
       `Unknown operator code ${formatCode(base, PolicyFormat.RULE_OPCODE_SIZE)}`,
     );
-  return info;
-}
-
-/** Operand count category for an operator code, or undefined when unrecognised. */
-export function operandsOf(opBase: number): Operands | undefined {
-  return opByCode.get(opBase)?.operands;
+  return { label: `${info.label}${labelSuffix}`, operands: info.operands };
 }

package/src/constraint.ts

@@ -1,9 +1,10 @@
 import { bytesToHex, hexToBytes, toAddress } from "./bytes";
-import { PolicyFormat, Op, Scope, ContextProperty, lookupContextProperty } from "./constants";
+import { ContextProperty, lookupContextProperty, Op, Scope, Source } from "./constants";
 import { CallciumError } from "./errors";
 import { encodePath } from "./path";
 
-import type { Address, Hex, Constraint } from "./types";
+import type { Address, Hex } from "./types";
+import type { Constraint } from "./types";
 
 ///////////////////////////////////////////////////////////////////////////
 // Value encoding helpers
@@ -32,6 +33,17 @@ function addressBody(value: string): string {
   return toAddress(value).slice(2);
 }
 
+/**
+ * Require an operand that reached the builder untyped to be a bigint and return it.
+ * @throws {CallciumError} When the operand is of another type, as a JavaScript `number` is.
+ */
+function requireBigint(value: unknown): bigint {
+  if (typeof value !== "bigint") {
+    throw new CallciumError("MALFORMED_OPERAND", "Operand is not a bigint, a boolean or an address string");
+  }
+  return value;
+}
+
 /** Convert a scalar value to a 32-byte big-endian word. */
 function encodeWord(value: ScalarValue): Uint8Array {
   const word = new Uint8Array(32);
@@ -47,6 +59,8 @@ function encodeWord(value: ScalarValue): Uint8Array {
     return word;
   }
 
+  requireBigint(value);
+
   // A negative operand occupies the word in two's complement, which is the signed target's encoding.
   let bigValue = checkOperandRange(value);
   for (let i = 31; i >= 0; i--) {
@@ -79,6 +93,9 @@ function rangeOp(opCode: number, min: bigint, max: bigint): Hex {
   return bytesToHex(buffer);
 }
 
+/** The `source` bits of an operator code whose operand is a context property. */
+const CONTEXT_SOURCE = Source.CONTEXT << Op.SOURCE_SHIFT;
+
 /**
  * Require an assigned context property ID and return it as an operand word.
  * @throws {CallciumError} When the ID names no assigned property.
@@ -90,14 +107,13 @@ function contextOperand(contextPropertyId: number): bigint {
 
 /** Convert values to bigint, sort ascending (unsigned), deduplicate, and pack as set payload. */
 function setOp(opCode: number, values: readonly ScalarValue[]): Hex {
-  // PWF-21 orders members by their 32-byte encodings, so a negative operand and its unsigned
-  // alias are one member at one position. Normalising after the domain check keeps an
-  // out-of-range value an error rather than folding it into the word.
+  // PWF-21 orders members by their 32-byte encodings, so a negative operand and its unsigned alias are one member at
+  // one position. Normalising after the domain check keeps an out-of-range value an error rather than a word.
   const words = values.map((value) => {
     if (typeof value === "bigint") return BigInt.asUintN(256, checkOperandRange(value));
     if (typeof value === "boolean") return value ? 1n : 0n;
-    // String address.
-    return BigInt("0x" + addressBody(value));
+    if (typeof value === "string") return BigInt("0x" + addressBody(value));
+    return requireBigint(value);
   });
 
   const deduped = [...new Set(words)].toSorted((a, b) => (a < b ? -1 : a > b ? 1 : 0));
@@ -105,9 +121,6 @@ function setOp(opCode: number, values: readonly ScalarValue[]): Hex {
   if (deduped.length === 0) {
     throw new CallciumError("EMPTY_SET", "Set must contain at least one value");
   }
-  if (deduped.length > PolicyFormat.MAX_SET_MEMBERS) {
-    throw new CallciumError("SET_TOO_LARGE", `Set must contain at most ${PolicyFormat.MAX_SET_MEMBERS} values`);
-  }
 
   const buffer = new Uint8Array(1 + deduped.length * 32);
   buffer[0] = opCode;
@@ -122,8 +135,8 @@ function setOp(opCode: number, values: readonly ScalarValue[]): Hex {
 ///////////////////////////////////////////////////////////////////////////
 
 /**
- * Extremes of the numeric operands a builder's value operators received, as written. Encoding folds
- * a negative operand onto its unsigned alias, so the sign survives nowhere else.
+ * Extremes of the numeric operands a builder's equality, comparison and set operators received, as written. Encoding
+ * folds a negative operand onto its unsigned alias, so the sign survives nowhere else.
  */
 export type OperandExtremes = {
   /** Most negative operand written, or zero when none was negative. */
@@ -133,10 +146,9 @@ export type OperandExtremes = {
 };
 
 /**
- * Extremes of the numeric operands the value operators of `constraint` received, as written.
- * They outlive edits to `operators`: removing an operator does not remove what was written to
- * produce it, and a fresh builder starts at zero. Undefined for a plain `Constraint`, whose
- * operators arrive already encoded.
+ * Extremes of the numeric operands the value operators of `constraint` received, as written. They outlive edits to
+ * `operators`: removing an operator does not remove what was written to produce it, and a fresh builder starts at zero.
+ * Undefined for a plain `Constraint`, whose operators arrive already encoded.
  */
 export function readOperandExtremes(constraint: Constraint | ConstraintBuilder): OperandExtremes | undefined {
   return "operandExtremes" in constraint ? constraint.operandExtremes : undefined;
@@ -147,23 +159,21 @@ export function readOperandExtremes(constraint: Constraint | ConstraintBuilder):
 ///////////////////////////////////////////////////////////////////////////
 
 /**
- * Mutable builder that accumulates operators targeting a single path.
- * Implements the `Constraint` interface so it can be passed directly to policy builders.
+ * Mutable builder that accumulates operators targeting a single path. Implements the `Constraint` interface so it can
+ * be passed directly to policy builders.
  */
 export class ConstraintBuilder<Operand extends ScalarValue = ScalarValue> implements Constraint {
-  readonly scope: number;
+  readonly scope: Constraint["scope"];
   readonly path: Hex;
   readonly operators: Hex[];
   /**
-   * Extremes of the numeric operands the value operators received, as written. Only the extremes
-   * can offend: an operand folds into a target's range from below it or from above it, and
-   * whichever reaches furthest arrives first. Read it through {@link readOperandExtremes}.
+   * Extremes of the numeric operands the value operators received, as written.
    * @internal
    */
   readonly operandExtremes: OperandExtremes;
 
   /** @internal */
-  constructor(scope: number, path: Hex) {
+  constructor(scope: Constraint["scope"], path: Hex) {
     this.scope = scope;
     this.path = path;
     this.operators = [];
@@ -171,8 +181,8 @@ export class ConstraintBuilder<Operand extends ScalarValue = ScalarValue> implem
   }
 
   /**
-   * Push a pre-encoded operator hex string and return this for chaining.
-   * `values` are the operands as written; the numeric ones join the record.
+   * Push a pre-encoded operator hex string and return this for chaining. `values` are the operands as written. The
+   * numeric ones join the record.
    */
   private push(opHex: Hex, values: readonly ScalarValue[] = []): this {
     for (const value of values) {
@@ -200,12 +210,32 @@ export class ConstraintBuilder<Operand extends ScalarValue = ScalarValue> implem
 
   /** Assert the value equals the context property `contextPropertyId`. */
   eqCtx(contextPropertyId: number): this {
-    return this.push(singleOp(Op.EQ_CTX, contextOperand(contextPropertyId)));
+    return this.push(singleOp(Op.EQ | CONTEXT_SOURCE, contextOperand(contextPropertyId)));
   }
 
   /** Assert the value does not equal the context property `contextPropertyId`. */
   neqCtx(contextPropertyId: number): this {
-    return this.push(singleOp(Op.EQ_CTX | Op.NOT, contextOperand(contextPropertyId)));
+    return this.push(singleOp(Op.EQ | CONTEXT_SOURCE | Op.NOT, contextOperand(contextPropertyId)));
+  }
+
+  /** Assert the value is greater than the context property `contextPropertyId`. */
+  gtCtx(contextPropertyId: number): this {
+    return this.push(singleOp(Op.GT | CONTEXT_SOURCE, contextOperand(contextPropertyId)));
+  }
+
+  /** Assert the value is less than the context property `contextPropertyId`. */
+  ltCtx(contextPropertyId: number): this {
+    return this.push(singleOp(Op.LT | CONTEXT_SOURCE, contextOperand(contextPropertyId)));
+  }
+
+  /** Assert the value is greater than or equal to the context property `contextPropertyId`. */
+  gteCtx(contextPropertyId: number): this {
+    return this.push(singleOp(Op.GTE | CONTEXT_SOURCE, contextOperand(contextPropertyId)));
+  }
+
+  /** Assert the value is less than or equal to the context property `contextPropertyId`. */
+  lteCtx(contextPropertyId: number): this {
+    return this.push(singleOp(Op.LTE | CONTEXT_SOURCE, contextOperand(contextPropertyId)));
   }
 
   /** Assert the value is greater than `bound`. */
@@ -241,9 +271,8 @@ export class ConstraintBuilder<Operand extends ScalarValue = ScalarValue> implem
   ///////////////////////////////////////////////////////////////////////////
 
   /**
-   * Assert the value is a member of the set.
-   * Values are sorted and deduplicated before encoding.
-   * @throws {CallciumError} If the set is empty after deduplication.
+   * Assert the value is a member of the set. Values are sorted and deduplicated before encoding.
+   * @throws {CallciumError} If the set is empty or a value is not encodable as an operand word.
    */
   isIn(values: readonly Operand[]): this {
     return this.push(setOp(Op.IN, values), values);
@@ -251,7 +280,7 @@ export class ConstraintBuilder<Operand extends ScalarValue = ScalarValue> implem
 
   /**
    * Assert the value is not a member of the set.
-   * @throws {CallciumError} If the set is empty after deduplication.
+   * @throws {CallciumError} If the set is empty or a value is not encodable as an operand word.
    */
   notIn(values: readonly Operand[]): this {
     return this.push(setOp(Op.IN | Op.NOT, values), values);
@@ -319,8 +348,7 @@ export class ConstraintBuilder<Operand extends ScalarValue = ScalarValue> implem
 ///////////////////////////////////////////////////////////////////////////
 
 /**
- * Target a calldata argument by path.
- * Each argument is a big-endian uint16 step; multiple steps navigate into nested types.
+ * Target a calldata argument by path. Each argument is a big-endian uint16 step. Further steps navigate nested types.
  */
 export function arg(p0: number, ...rest: number[]): ConstraintBuilder;
 export function arg(...steps: number[]): ConstraintBuilder {