@callcium/sdk 0.9.0 → 0.11.0

package/src/constraint.ts

@@ -1,15 +1,31 @@
-import { bytesToHex, toAddress, writeBE16 } from "./bytes";
-import { Op, Scope, ContextProperty, Limits, MAX_CONTEXT_PROPERTY_ID } from "./constants";
+import { bytesToHex, hexToBytes, toAddress } from "./bytes";
+import { PolicyFormat, Op, Scope, ContextProperty, lookupContextProperty } from "./constants";
 import { CallciumError } from "./errors";
+import { encodePath } from "./path";
 
-import type { Hex, Constraint } from "./types";
+import type { Address, Hex, Constraint } from "./types";
 
 ///////////////////////////////////////////////////////////////////////////
 // Value encoding helpers
 ///////////////////////////////////////////////////////////////////////////
 
 /** Accepted scalar value types for operator arguments. */
-export type ScalarValue = bigint | number | boolean | string;
+export type ScalarValue = bigint | boolean | string;
+
+// Bounds of the integers a 32-byte operand word represents, spanning signed and unsigned targets.
+const OPERAND_MIN = -(2n ** 255n);
+const OPERAND_MAX = 2n ** 256n - 1n;
+
+/**
+ * Require an operand within the integers a 32-byte word represents and return it.
+ * @throws {CallciumError} When the operand lies outside the word's range.
+ */
+function checkOperandRange(value: bigint): bigint {
+  if (value < OPERAND_MIN || value > OPERAND_MAX) {
+    throw new CallciumError("OPERAND_OVERFLOW", `Operand ${value} is outside the range a 32-byte word represents`);
+  }
+  return value;
+}
 
 /** Strip an optional 0x prefix and validate a 40-hex-char (20-byte) address body. */
 function addressBody(value: string): string {
@@ -27,15 +43,12 @@ function encodeWord(value: ScalarValue): Uint8Array {
 
   if (typeof value === "string") {
     // Address encoding: validate 20-byte hex and right-align into 32 bytes.
-    const body = addressBody(value);
-    for (let i = 0; i < 20; i++) {
-      word[12 + i] = parseInt(body.substring(i * 2, i * 2 + 2), 16);
-    }
+    word.set(hexToBytes(addressBody(value)), 12);
     return word;
   }
 
-  // bigint | number — unsigned 256-bit big-endian.
-  let bigValue = typeof value === "number" ? BigInt(value) : 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--) {
     word[i] = Number(bigValue & 0xffn);
     bigValue >>= 8n;
@@ -53,51 +66,47 @@ function singleOp(opCode: number, value: ScalarValue): Hex {
 
 /** Pack a range operator (opCode byte + min word + max word). */
 function rangeOp(opCode: number, min: bigint, max: bigint): Hex {
-  if (min > max) {
-    throw new CallciumError("INVALID_RANGE", `Range min (${min}) must not exceed max (${max})`);
+  // Order compares the operands as written; the encoded words of a signed range run the other way.
+  const minValue = checkOperandRange(min);
+  const maxValue = checkOperandRange(max);
+  if (minValue > maxValue) {
+    throw new CallciumError("INVALID_RANGE", `Range min (${minValue}) must not exceed max (${maxValue})`);
   }
   const buffer = new Uint8Array(65);
   buffer[0] = opCode;
-  buffer.set(encodeWord(min), 1);
-  buffer.set(encodeWord(max), 33);
+  buffer.set(encodeWord(minValue), 1);
+  buffer.set(encodeWord(maxValue), 33);
   return bytesToHex(buffer);
 }
 
-/** Require a defined context property ID and return it. */
-function checkContextPropertyId(contextPropertyId: number): number {
-  if (!Number.isInteger(contextPropertyId) || contextPropertyId < 0 || contextPropertyId > MAX_CONTEXT_PROPERTY_ID) {
-    throw new CallciumError("UNKNOWN_CONTEXT_PROPERTY", `Unknown context property ID ${contextPropertyId}`);
-  }
-  return contextPropertyId;
+/**
+ * Require an assigned context property ID and return it as an operand word.
+ * @throws {CallciumError} When the ID names no assigned property.
+ */
+function contextOperand(contextPropertyId: number): bigint {
+  lookupContextProperty(contextPropertyId);
+  return BigInt(contextPropertyId);
 }
 
-/** Largest member count whose 32-byte words still fit a rule's data length field. */
-export const MAX_SET_MEMBERS = Limits.MAX_SET_MEMBERS;
-
 /** Convert values to bigint, sort ascending (unsigned), deduplicate, and pack as set payload. */
 function setOp(opCode: number, values: readonly ScalarValue[]): Hex {
-  const bigs = values.map((v) => {
-    if (typeof v === "bigint") return v;
-    if (typeof v === "number") return BigInt(v);
-    if (typeof v === "boolean") return v ? 1n : 0n;
+  // 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.
+  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(v));
+    return BigInt("0x" + addressBody(value));
   });
 
-  bigs.sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
-
-  const deduped: bigint[] = [];
-  for (const value of bigs) {
-    if (deduped.length === 0 || deduped[deduped.length - 1] !== value) {
-      deduped.push(value);
-    }
-  }
+  const deduped = [...new Set(words)].toSorted((a, b) => (a < b ? -1 : a > b ? 1 : 0));
 
   if (deduped.length === 0) {
     throw new CallciumError("EMPTY_SET", "Set must contain at least one value");
   }
-  if (deduped.length > MAX_SET_MEMBERS) {
-    throw new CallciumError("SET_TOO_LARGE", `Set must contain at most ${MAX_SET_MEMBERS} values`);
+  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);
@@ -109,16 +118,28 @@ function setOp(opCode: number, values: readonly ScalarValue[]): Hex {
 }
 
 ///////////////////////////////////////////////////////////////////////////
-// Path encoding
+// Operand provenance
 ///////////////////////////////////////////////////////////////////////////
 
-/** Encode a sequence of uint16 path steps as a big-endian hex string. */
-function encodePath(steps: readonly number[]): Hex {
-  const buffer = new Uint8Array(steps.length * 2);
-  for (let i = 0; i < steps.length; i++) {
-    writeBE16(buffer, i * 2, steps[i]!);
-  }
-  return bytesToHex(buffer);
+/**
+ * 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.
+ */
+export type OperandExtremes = {
+  /** Most negative operand written, or zero when none was negative. */
+  leastNegative: bigint;
+  /** Greatest operand written, or zero when none exceeded it. */
+  greatest: bigint;
+};
+
+/**
+ * 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;
 }
 
 ///////////////////////////////////////////////////////////////////////////
@@ -129,20 +150,36 @@ function encodePath(steps: readonly number[]): Hex {
  * 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 implements Constraint {
+export class ConstraintBuilder<Operand extends ScalarValue = ScalarValue> implements Constraint {
   readonly scope: number;
   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}.
+   * @internal
+   */
+  readonly operandExtremes: OperandExtremes;
 
   /** @internal */
   constructor(scope: number, path: Hex) {
     this.scope = scope;
     this.path = path;
     this.operators = [];
+    this.operandExtremes = { leastNegative: 0n, greatest: 0n };
   }
 
-  /** Push a pre-encoded operator hex string and return this for chaining. */
-  private push(opHex: Hex): this {
+  /**
+   * 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) {
+      if (typeof value !== "bigint") continue;
+      if (value < this.operandExtremes.leastNegative) this.operandExtremes.leastNegative = value;
+      if (value > this.operandExtremes.greatest) this.operandExtremes.greatest = value;
+    }
     this.operators.push(opHex);
     return this;
   }
@@ -152,51 +189,51 @@ export class ConstraintBuilder implements Constraint {
   ///////////////////////////////////////////////////////////////////////////
 
   /** Assert the value equals `value`. */
-  eq(value: ScalarValue): this {
-    return this.push(singleOp(Op.EQ, value));
+  eq(value: Operand): this {
+    return this.push(singleOp(Op.EQ, value), [value]);
   }
 
   /** Assert the value does not equal `value`. */
-  neq(value: ScalarValue): this {
-    return this.push(singleOp(Op.EQ | Op.NOT, value));
+  neq(value: Operand): this {
+    return this.push(singleOp(Op.EQ | Op.NOT, value), [value]);
   }
 
   /** Assert the value equals the context property `contextPropertyId`. */
   eqCtx(contextPropertyId: number): this {
-    return this.push(singleOp(Op.EQ_CTX, checkContextPropertyId(contextPropertyId)));
+    return this.push(singleOp(Op.EQ_CTX, 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, checkContextPropertyId(contextPropertyId)));
+    return this.push(singleOp(Op.EQ_CTX | Op.NOT, contextOperand(contextPropertyId)));
   }
 
   /** Assert the value is greater than `bound`. */
-  gt(bound: bigint | number): this {
-    return this.push(singleOp(Op.GT, bound));
+  gt(bound: bigint): this {
+    return this.push(singleOp(Op.GT, bound), [bound]);
   }
 
   /** Assert the value is less than `bound`. */
-  lt(bound: bigint | number): this {
-    return this.push(singleOp(Op.LT, bound));
+  lt(bound: bigint): this {
+    return this.push(singleOp(Op.LT, bound), [bound]);
   }
 
   /** Assert the value is greater than or equal to `bound`. */
-  gte(bound: bigint | number): this {
-    return this.push(singleOp(Op.GTE, bound));
+  gte(bound: bigint): this {
+    return this.push(singleOp(Op.GTE, bound), [bound]);
   }
 
   /** Assert the value is less than or equal to `bound`. */
-  lte(bound: bigint | number): this {
-    return this.push(singleOp(Op.LTE, bound));
+  lte(bound: bigint): this {
+    return this.push(singleOp(Op.LTE, bound), [bound]);
   }
 
   /**
    * Assert the value is within [min, max] inclusive.
    * @throws {CallciumError} If min > max.
    */
-  between(min: bigint | number, max: bigint | number): this {
-    return this.push(rangeOp(Op.BETWEEN, BigInt(min), BigInt(max)));
+  between(min: bigint, max: bigint): this {
+    return this.push(rangeOp(Op.BETWEEN, min, max), [min, max]);
   }
 
   ///////////////////////////////////////////////////////////////////////////
@@ -208,16 +245,16 @@ export class ConstraintBuilder implements Constraint {
    * Values are sorted and deduplicated before encoding.
    * @throws {CallciumError} If the set is empty after deduplication.
    */
-  isIn(values: readonly ScalarValue[]): this {
-    return this.push(setOp(Op.IN, values));
+  isIn(values: readonly Operand[]): this {
+    return this.push(setOp(Op.IN, values), values);
   }
 
   /**
    * Assert the value is not a member of the set.
    * @throws {CallciumError} If the set is empty after deduplication.
    */
-  notIn(values: readonly ScalarValue[]): this {
-    return this.push(setOp(Op.IN | Op.NOT, values));
+  notIn(values: readonly Operand[]): this {
+    return this.push(setOp(Op.IN | Op.NOT, values), values);
   }
 
   ///////////////////////////////////////////////////////////////////////////
@@ -243,37 +280,37 @@ export class ConstraintBuilder implements Constraint {
   // Length operators
   ///////////////////////////////////////////////////////////////////////////
 
-  /** Assert the runtime length equals `n`. */
-  lengthEq(n: bigint | number): this {
-    return this.push(singleOp(Op.LENGTH_EQ, n));
+  /** Assert the runtime length equals `length`. */
+  lengthEq(length: bigint): this {
+    return this.push(singleOp(Op.LENGTH_EQ, length));
   }
 
-  /** Assert the runtime length is greater than `n`. */
-  lengthGt(n: bigint | number): this {
-    return this.push(singleOp(Op.LENGTH_GT, n));
+  /** Assert the runtime length is greater than `length`. */
+  lengthGt(length: bigint): this {
+    return this.push(singleOp(Op.LENGTH_GT, length));
   }
 
-  /** Assert the runtime length is less than `n`. */
-  lengthLt(n: bigint | number): this {
-    return this.push(singleOp(Op.LENGTH_LT, n));
+  /** Assert the runtime length is less than `length`. */
+  lengthLt(length: bigint): this {
+    return this.push(singleOp(Op.LENGTH_LT, length));
   }
 
-  /** Assert the runtime length is greater than or equal to `n`. */
-  lengthGte(n: bigint | number): this {
-    return this.push(singleOp(Op.LENGTH_GTE, n));
+  /** Assert the runtime length is greater than or equal to `length`. */
+  lengthGte(length: bigint): this {
+    return this.push(singleOp(Op.LENGTH_GTE, length));
   }
 
-  /** Assert the runtime length is less than or equal to `n`. */
-  lengthLte(n: bigint | number): this {
-    return this.push(singleOp(Op.LENGTH_LTE, n));
+  /** Assert the runtime length is less than or equal to `length`. */
+  lengthLte(length: bigint): this {
+    return this.push(singleOp(Op.LENGTH_LTE, length));
   }
 
   /**
    * Assert the runtime length is within [min, max] inclusive.
    * @throws {CallciumError} If min > max.
    */
-  lengthBetween(min: bigint | number, max: bigint | number): this {
-    return this.push(rangeOp(Op.LENGTH_BETWEEN, BigInt(min), BigInt(max)));
+  lengthBetween(min: bigint, max: bigint): this {
+    return this.push(rangeOp(Op.LENGTH_BETWEEN, min, max));
   }
 }
 
@@ -291,41 +328,41 @@ export function arg(...steps: number[]): ConstraintBuilder {
 }
 
 /** Target the `msg.sender` context property. */
-export function msgSender(): ConstraintBuilder {
+export function msgSender(): ConstraintBuilder<Address> {
   return new ConstraintBuilder(Scope.CONTEXT, encodePath([ContextProperty.MSG_SENDER]));
 }
 
 /** Target the `msg.value` context property. */
-export function msgValue(): ConstraintBuilder {
+export function msgValue(): ConstraintBuilder<bigint> {
   return new ConstraintBuilder(Scope.CONTEXT, encodePath([ContextProperty.MSG_VALUE]));
 }
 
 /** Target the `block.timestamp` context property. */
-export function blockTimestamp(): ConstraintBuilder {
+export function blockTimestamp(): ConstraintBuilder<bigint> {
   return new ConstraintBuilder(Scope.CONTEXT, encodePath([ContextProperty.BLOCK_TIMESTAMP]));
 }
 
 /** Target the `block.number` context property. */
-export function blockNumber(): ConstraintBuilder {
+export function blockNumber(): ConstraintBuilder<bigint> {
   return new ConstraintBuilder(Scope.CONTEXT, encodePath([ContextProperty.BLOCK_NUMBER]));
 }
 
 /** Target the `block.chainid` context property. */
-export function chainId(): ConstraintBuilder {
+export function chainId(): ConstraintBuilder<bigint> {
   return new ConstraintBuilder(Scope.CONTEXT, encodePath([ContextProperty.CHAIN_ID]));
 }
 
 /** Target the `tx.origin` context property. */
-export function txOrigin(): ConstraintBuilder {
+export function txOrigin(): ConstraintBuilder<Address> {
   return new ConstraintBuilder(Scope.CONTEXT, encodePath([ContextProperty.TX_ORIGIN]));
 }
 
 /** Target the `block.basefee` context property. */
-export function baseFee(): ConstraintBuilder {
+export function baseFee(): ConstraintBuilder<bigint> {
   return new ConstraintBuilder(Scope.CONTEXT, encodePath([ContextProperty.BASE_FEE]));
 }
 
 /** Target the `tx.gasprice` context property. */
-export function gasPrice(): ConstraintBuilder {
+export function gasPrice(): ConstraintBuilder<bigint> {
   return new ConstraintBuilder(Scope.CONTEXT, encodePath([ContextProperty.GAS_PRICE]));
 }

package/src/descriptor-coder.ts

@@ -1,7 +1,8 @@
-import { readU16, readU24 } from "./bytes";
-import { DescriptorFormat as DF, TypeCode, lookupTypeCode, classifyTypeCode } from "./constants";
-import { Descriptor } from "./descriptor";
+import { readU16 } from "./bytes";
+import { DescriptorFormat as DF, TypeCode } from "./constants";
+import { Descriptor, readNode } from "./descriptor";
 import { CallciumError } from "./errors";
+import { classifyTypeCode, lookupTypeCode } from "./operators";
 import { address, array, bool, bytes, bytesN, function_, intN, string_, tuple, uintN } from "./type-desc";
 
 import type { DecodedParam, Hex } from "./types";
@@ -22,11 +23,17 @@ function commaPositions(input: string, start: number, end: number): number[] {
     if (char === "(" || char === "[") {
       depth++;
     } else if (char === ")" || char === "]") {
+      if (depth === 0) {
+        throw new CallciumError("MALFORMED_TYPE_STRING", `Unmatched '${char}' at position ${i}`);
+      }
       depth--;
     } else if (char === "," && depth === 0) {
       positions.push(i);
     }
   }
+  if (depth !== 0) {
+    throw new CallciumError("MALFORMED_TYPE_STRING", `Unclosed '${input.slice(start, end)}'`);
+  }
   return positions;
 }
 
@@ -78,35 +85,35 @@ function parseTuple(input: string, start: number, end: number): Uint8Array {
     throw new CallciumError("MALFORMED_TYPE_STRING", `Expected '(' at position ${start}`);
   }
   let depth = 0;
-  let closePos = -1;
+  let closeIndex = -1;
   for (let i = start; i < end; i++) {
     if (input[i] === "(") depth++;
     else if (input[i] === ")") {
       depth--;
       if (depth === 0) {
-        closePos = i;
+        closeIndex = i;
         break;
       }
     }
   }
-  if (closePos === -1) {
+  if (closeIndex === -1) {
     throw new CallciumError("MALFORMED_TYPE_STRING", `Unmatched '(' at position ${start}`);
   }
-  if (closePos !== end - 1) {
-    throw new CallciumError("MALFORMED_TYPE_STRING", `Unexpected characters after ')' at position ${closePos + 1}`);
+  if (closeIndex !== end - 1) {
+    throw new CallciumError("MALFORMED_TYPE_STRING", `Unexpected characters after ')' at position ${closeIndex + 1}`);
   }
 
   const innerStart = start + 1;
-  const innerEnd = closePos;
+  const innerEnd = closeIndex;
   const commas = commaPositions(input, innerStart, innerEnd);
 
   const segments: Array<[number, number]> = [];
-  let segStart = innerStart;
+  let segmentStart = innerStart;
   for (const comma of commas) {
-    segments.push([segStart, comma]);
-    segStart = comma + 1;
+    segments.push([segmentStart, comma]);
+    segmentStart = comma + 1;
   }
-  segments.push([segStart, innerEnd]);
+  segments.push([segmentStart, innerEnd]);
 
   // An empty tuple has no fields to parse; the tuple builder rejects the count.
   if (segments.length === 1 && segments[0]![0] === segments[0]![1]) return tuple([]);
@@ -130,9 +137,11 @@ function parseBaseType(input: string, start: number, end: number): Uint8Array {
   if (segment === "string") return string_();
   if (segment.startsWith("(")) return parseTuple(input, start, end);
 
-  if (segment.startsWith("uint")) return uintN(parseUint(input, start + 4, end));
-  if (segment.startsWith("int")) return intN(parseUint(input, start + 3, end));
-  if (segment.startsWith("bytes")) return bytesN(parseUint(input, start + 5, end));
+  // A prefix with no width after it spells no type, so it falls through to the unknown-type report
+  // rather than being read as a width that is not there.
+  if (segment.length > 4 && segment.startsWith("uint")) return uintN(parseUint(input, start + 4, end));
+  if (segment.length > 3 && segment.startsWith("int")) return intN(parseUint(input, start + 3, end));
+  if (segment.length > 5 && segment.startsWith("bytes")) return bytesN(parseUint(input, start + 5, end));
 
   throw new CallciumError("UNKNOWN_TYPE", `Unrecognised type '${segment}'`);
 }
@@ -152,39 +161,31 @@ function parseType(input: string, start: number, end: number): Uint8Array {
     throw new CallciumError("MALFORMED_TYPE_STRING", "Empty type segment");
   }
 
-  // Collect array suffixes by scanning backward.
-  // Each suffix is either `[]` (dynamic) or `[N]` (static with length N).
-  const suffixes: Array<number | undefined> = [];
+  // Locate array suffixes by scanning backward, reading no length yet: the base names the type, so
+  // an unrecognised one is reported before a suffix it carries is parsed.
+  const spans: Array<[number, number]> = [];
   let baseEnd = end;
 
   while (baseEnd > start && input[baseEnd - 1] === "]") {
-    const closePos = baseEnd - 1;
-    let openPos = closePos - 1;
+    const closeIndex = baseEnd - 1;
+    let openIndex = closeIndex - 1;
     // Walk back past digits (for static arrays).
-    while (openPos > start && input[openPos] !== "[") {
-      openPos--;
+    while (openIndex > start && input[openIndex] !== "[") {
+      openIndex--;
     }
-    if (input[openPos] !== "[") {
-      throw new CallciumError("MALFORMED_TYPE_STRING", `Unmatched ']' at position ${closePos}`);
+    if (input[openIndex] !== "[") {
+      throw new CallciumError("MALFORMED_TYPE_STRING", `Unmatched ']' at position ${closeIndex}`);
     }
-    const innerStart = openPos + 1;
-    const innerEnd = closePos;
-    // A dynamic array spells no length at all.
-    suffixes.unshift(innerStart === innerEnd ? undefined : parseUint(input, innerStart, innerEnd));
-    baseEnd = openPos;
-  }
-
-  // Every `[` a base carries belongs to a suffix the scan above already took; one left behind is
-  // unclosed. A tuple base is exempt: the brackets inside it belong to its fields.
-  if (input[start] !== "(" && input.slice(start, baseEnd).includes("[")) {
-    throw new CallciumError("MALFORMED_TYPE_STRING", `Unmatched '[' in '${input.slice(start, baseEnd)}'`);
+    spans.unshift([openIndex + 1, closeIndex]);
+    baseEnd = openIndex;
   }
 
   let desc = parseBaseType(input, start, baseEnd);
 
   // Apply suffixes left-to-right: the leftmost suffix is the outermost array.
-  for (const length of suffixes) {
-    desc = array(desc, length);
+  // A dynamic array spells no length at all.
+  for (const [innerStart, innerEnd] of spans) {
+    desc = array(desc, innerStart === innerEnd ? undefined : parseUint(input, innerStart, innerEnd));
   }
 
   return desc;
@@ -201,6 +202,7 @@ function parseType(input: string, start: number, end: number): Uint8Array {
  * @returns Binary descriptor bytes starting with the version+paramCount header.
  * @throws {CallciumError} With code `MALFORMED_TYPE_STRING` for malformed input.
  * @throws {CallciumError} With code `UNKNOWN_TYPE` for unrecognised type names.
+ * @throws {CallciumError} With code `NESTING_TOO_DEEP` when composite nesting exceeds `MAX_NESTING_DEPTH`.
  */
 function fromTypes(typesCsv: string): Uint8Array {
   if (typesCsv === "") {
@@ -219,10 +221,7 @@ function fromTypes(typesCsv: string): Uint8Array {
 
   const paramDescs = segments.map(([start, end]) => parseType(typesCsv, start, end));
   if (paramDescs.length > DF.MAX_PARAMS) {
-    throw new CallciumError(
-      "TOO_MANY_PARAMS",
-      `Parameter count ${paramDescs.length} exceeds maximum ${DF.MAX_PARAMS}.`,
-    );
+    throw new CallciumError("TOO_MANY_PARAMS", `Parameter count ${paramDescs.length} exceeds maximum ${DF.MAX_PARAMS}`);
   }
   const totalBytes = paramDescs.reduce((sum, d) => sum + d.length, 0);
   const result = new Uint8Array(DF.HEADER_SIZE + totalBytes);
@@ -233,6 +232,8 @@ function fromTypes(typesCsv: string): Uint8Array {
     result.set(desc, offset);
     offset += desc.length;
   }
+  // Nesting depth is a property of the assembled descriptor, not of any single node.
+  decodeDescriptor(result);
   return result;
 }
 
@@ -242,7 +243,7 @@ function fromTypes(typesCsv: string): Uint8Array {
 
 /** Reconstruct an ABI type string from a descriptor node at the given offset. */
 function nodeToTypeString(desc: Uint8Array, offset: number): string {
-  const typeCode = desc[offset]!;
+  const { typeCode } = Descriptor.inspect(desc, offset);
 
   if (typeCode === TypeCode.TUPLE) {
     const fieldCount = Descriptor.tupleFieldCount(desc, offset);
@@ -298,21 +299,14 @@ type ParseResult = { typeCode: number; isDynamic: boolean; staticSize: number; n
 
 /** Recursively parse a single descriptor node starting at offset. */
 function parseNode(data: Uint8Array, offset: number, depth: number): ParseResult {
-  if (offset >= data.length) {
-    throw new CallciumError("UNEXPECTED_END", "Unexpected end of descriptor", offset);
-  }
-
-  const code = data[offset]!;
+  const { typeCode: code, staticWords, nodeLength } = readNode(data, offset);
   const info = classifyTypeCode(code);
-  const metaOffset = offset + DF.TYPECODE_SIZE;
+  const isDynamic = staticWords === 0;
+  const staticSize = isDynamic ? 0 : staticWords * 32;
+  const nodeEnd = offset + nodeLength;
 
   if (info.typeClass === "elementary") {
-    return {
-      typeCode: code,
-      isDynamic: info.isDynamic,
-      staticSize: info.isDynamic ? 0 : 32,
-      next: metaOffset,
-    };
+    return { typeCode: code, isDynamic, staticSize, next: nodeEnd };
   }
 
   // Only composites nest; a leaf below the deepest allowed composite is fine.
@@ -324,33 +318,8 @@ function parseNode(data: Uint8Array, offset: number, depth: number): ParseResult
     );
   }
 
-  const metaEnd = metaOffset + DF.COMPOSITE_META_SIZE;
-  if (metaEnd > data.length) {
-    throw new CallciumError("UNEXPECTED_END", "Incomplete composite metadata", offset);
-  }
-
-  const meta = readU24(data, metaOffset);
-  const staticWords = meta >> DF.META_STATIC_WORDS_SHIFT;
-  const nodeLength = meta & DF.META_NODE_LENGTH_MASK;
-
-  const minHeader = info.typeClass === "tuple" ? DF.TUPLE_HEADER_SIZE : DF.ARRAY_HEADER_SIZE;
-  if (nodeLength < minHeader) {
-    throw new CallciumError(
-      "NODE_LENGTH_TOO_SMALL",
-      `Composite node length ${nodeLength} is smaller than minimum header ${minHeader}`,
-      offset,
-    );
-  }
-  if (offset + nodeLength > data.length) {
-    throw new CallciumError("NODE_OVERFLOW", "Composite node extends beyond descriptor", offset);
-  }
-
-  const isDynamic = staticWords === 0;
-  const staticSize = isDynamic ? 0 : staticWords * 32;
-  const nodeEnd = offset + nodeLength;
-
   if (info.typeClass === "tuple") {
-    const fieldCountOffset = metaEnd;
+    const fieldCountOffset = offset + DF.TYPECODE_SIZE + DF.COMPOSITE_META_SIZE;
     if (fieldCountOffset + 2 > data.length) {
       throw new CallciumError("UNEXPECTED_END", "Incomplete tuple header", offset);
     }
@@ -428,12 +397,12 @@ export function decodeDescriptor(data: Uint8Array): { descriptor: DecodedDescrip
   let cursor: number = DF.HEADER_SIZE;
 
   while (cursor < data.length) {
-    if (params.length >= DF.MAX_PARAMS) {
+    const { typeCode, isDynamic, staticSize, next } = parseNode(data, cursor, 1);
+
+    if (params.length === DF.MAX_PARAMS) {
       throw new CallciumError("TOO_MANY_PARAMS", `Descriptor exceeds the maximum of ${DF.MAX_PARAMS} top-level params`);
     }
 
-    const { typeCode, isDynamic, staticSize, next } = parseNode(data, cursor, 1);
-
     params.push({
       index: params.length,
       typeCode,