@callcium/sdk 0.5.0 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@callcium/sdk",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "TypeScript implementation of the Callcium policy engine",
   "keywords": [
     "abi",
@@ -22,7 +22,8 @@
     "directory": "packages/sdk"
   },
   "files": [
-    "dist"
+    "dist",
+    "src"
   ],
   "type": "module",
   "sideEffects": false,

package/src/bytes.ts

@@ -0,0 +1,100 @@
+import { CallciumError } from "./errors";
+
+import type { Address, Hex } from "./types";
+
+/** Regex that matches a valid hex body (even number of hex chars). */
+const HEX_BODY_RE = /^[0-9a-fA-F]*$/;
+
+// Nibble value per ASCII code, -1 for every character that is not a hex digit.
+const HEX_DIGITS = "0123456789abcdef";
+const NIBBLE = new Int8Array(128).fill(-1);
+for (let value = 0; value < 16; value++) {
+  NIBBLE[HEX_DIGITS.charCodeAt(value)] = value;
+  NIBBLE[HEX_DIGITS.toUpperCase().charCodeAt(value)] = value;
+}
+
+/** Convert a hex string to a byte array, stripping the 0x prefix if present. */
+export function hexToBytes(hex: string): Uint8Array {
+  const clean = hex.startsWith("0x") ? hex.slice(2) : hex;
+  if (clean.length % 2 !== 0) {
+    throw new CallciumError("INVALID_HEX", "Odd-length hex string");
+  }
+  const bytes = new Uint8Array(clean.length / 2);
+  for (let i = 0; i < bytes.length; i++) {
+    const high = NIBBLE[clean.charCodeAt(i * 2)] ?? -1;
+    const low = NIBBLE[clean.charCodeAt(i * 2 + 1)] ?? -1;
+    if (high < 0 || low < 0) {
+      throw new CallciumError("INVALID_HEX", "Invalid hex characters");
+    }
+    bytes[i] = (high << 4) | low;
+  }
+  return bytes;
+}
+
+// Pre-computed hex lookup avoids per-byte toString + padStart in the hot path.
+const HEX_LUT = Array.from({ length: 256 }, (_, i) => i.toString(16).padStart(2, "0"));
+
+/** Convert a byte array to a 0x-prefixed lowercase hex string. */
+export function bytesToHex(bytes: Uint8Array): Hex {
+  let body = "";
+  for (let i = 0; i < bytes.length; i++) body += HEX_LUT[bytes[i]!];
+  return `0x${body}`;
+}
+
+/** Extract a subarray and return it as a 0x-prefixed hex string. */
+export function toHex(data: Uint8Array, start: number, end: number): Hex {
+  return bytesToHex(data.subarray(start, end));
+}
+
+/** Read a big-endian uint16 from a byte array at the given offset. */
+export function readU16(data: Uint8Array, offset: number): number {
+  return (data[offset]! << 8) | data[offset + 1]!;
+}
+
+/** Read a big-endian uint24 from a byte array at the given offset. */
+export function readU24(data: Uint8Array, offset: number): number {
+  return (data[offset]! << 16) | (data[offset + 1]! << 8) | data[offset + 2]!;
+}
+
+/** Read a big-endian uint32 from a byte array at the given offset. */
+export function readU32(data: Uint8Array, offset: number): number {
+  return ((data[offset]! << 24) | (data[offset + 1]! << 16) | (data[offset + 2]! << 8) | data[offset + 3]!) >>> 0;
+}
+
+/** Write a 16-bit big-endian value into a Uint8Array at offset. */
+export function writeBE16(buffer: Uint8Array, offset: number, value: number): void {
+  buffer[offset] = (value >>> 8) & 0xff;
+  buffer[offset + 1] = value & 0xff;
+}
+
+/** Write a 24-bit big-endian value into a Uint8Array at offset. */
+export function writeBE24(buffer: Uint8Array, offset: number, value: number): void {
+  buffer[offset] = (value >>> 16) & 0xff;
+  buffer[offset + 1] = (value >>> 8) & 0xff;
+  buffer[offset + 2] = value & 0xff;
+}
+
+/** Write a 32-bit big-endian value into a Uint8Array at offset. */
+export function writeBE32(buffer: Uint8Array, offset: number, value: number): void {
+  buffer[offset] = (value >>> 24) & 0xff;
+  buffer[offset + 1] = (value >>> 16) & 0xff;
+  buffer[offset + 2] = (value >>> 8) & 0xff;
+  buffer[offset + 3] = value & 0xff;
+}
+
+/** Format a bigint as a zero-padded 32-byte hex string. */
+export function bigintToHex(value: bigint): Hex {
+  return `0x${value.toString(16).padStart(64, "0")}`;
+}
+
+/** Validate and brand a hex string as an address. Throws if the runtime length is not exactly 20 bytes. */
+export function toAddress(hex: string): Address {
+  const body = hex.startsWith("0x") ? hex.slice(2) : hex;
+  if (body.length !== 40) {
+    throw new CallciumError("INVALID_HEX", `Invalid address length: expected 40 hex chars, got ${body.length}`);
+  }
+  if (!HEX_BODY_RE.test(body)) {
+    throw new CallciumError("INVALID_HEX", "Invalid hex characters in address");
+  }
+  return `0x${body}`;
+}

package/src/calldata-reader.ts

@@ -0,0 +1,38 @@
+import type { NavigationViolationCode } from "./types";
+
+///////////////////////////////////////////////////////////////////////////
+// Result types
+///////////////////////////////////////////////////////////////////////////
+
+/** Result of a calldata read: success with data, or failure with a navigation violation code. */
+export type ReadResult<T> = T | { code: NavigationViolationCode };
+
+///////////////////////////////////////////////////////////////////////////
+// Calldata reading primitives
+///////////////////////////////////////////////////////////////////////////
+
+/** Read 32 bytes at offset, bounds-checked. */
+export function loadWord(callData: Uint8Array, offset: number): ReadResult<Uint8Array> {
+  if (offset < 0 || offset + 32 > callData.length) {
+    return { code: "CALLDATA_OUT_OF_BOUNDS" };
+  }
+  return callData.subarray(offset, offset + 32);
+}
+
+/**
+ * Read an ABI pointer (offset or length) from a 32-byte slot.
+ *
+ * A number cannot hold a 256-bit word, so the high 28 bytes must be zero for the narrowing to be
+ * lossless; a wider value is rejected as out of bounds, which is the verdict a bounds comparison
+ * over the full word reaches for any offset that far past the end of calldata.
+ */
+export function readPointer(callData: Uint8Array, head: number): ReadResult<number> {
+  const word = loadWord(callData, head);
+  if (word instanceof Uint8Array) {
+    for (let i = 0; i < 28; i++) {
+      if (word[i] !== 0) return { code: "CALLDATA_OUT_OF_BOUNDS" };
+    }
+    return ((word[28]! << 24) | (word[29]! << 16) | (word[30]! << 8) | word[31]!) >>> 0;
+  }
+  return word; // propagate CALLDATA_OUT_OF_BOUNDS
+}

package/src/constants.ts

@@ -0,0 +1,395 @@
+import { CallciumError } from "./errors";
+
+///////////////////////////////////////////////////////////////////////////
+// Descriptor format
+///////////////////////////////////////////////////////////////////////////
+
+/** Binary layout constants for the Callcium descriptor format. */
+export const DescriptorFormat = {
+  VERSION: 0x02,
+  HEADER_SIZE: 2,
+  TYPECODE_SIZE: 1,
+  COMPOSITE_META_SIZE: 3,
+  TUPLE_HEADER_SIZE: 6,
+  ARRAY_HEADER_SIZE: 4,
+  ARRAY_LENGTH_SIZE: 2,
+  TUPLE_FIELDCOUNT_SIZE: 2,
+  META_STATIC_WORDS_SHIFT: 12,
+  META_NODE_LENGTH_MASK: 0x0fff,
+  MAX_NODE_LENGTH: 0x0fff,
+  MAX_STATIC_ARRAY_LENGTH: 4095,
+  MAX_TUPLE_FIELDS: 4089,
+  MAX_STATIC_WORDS: 4095,
+  MAX_PARAMS: 255,
+  MAX_NESTING_DEPTH: 64,
+} as const satisfies Record<string, number>;
+
+///////////////////////////////////////////////////////////////////////////
+// Policy format
+///////////////////////////////////////////////////////////////////////////
+
+/** Binary layout constants for the Callcium policy format. */
+export const PolicyFormat = {
+  VERSION: 0x02,
+  VERSION_MASK: 0x0f,
+  FLAG_NO_SELECTOR: 0x10,
+  RESERVED_MASK: 0xe0,
+  HEADER_SIZE: 1,
+  SELECTOR_OFFSET: 1,
+  SELECTOR_SIZE: 4,
+  DESC_LENGTH_OFFSET: 5,
+  DESC_LENGTH_SIZE: 2,
+  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_DEPTH_OFFSET: 3,
+  RULE_PATH_OFFSET: 4,
+  PATH_STEP_SIZE: 2,
+  RULE_OPCODE_SIZE: 1,
+  RULE_DATALENGTH_SIZE: 2,
+  RULE_FIXED_OVERHEAD: 7,
+  RULE_MIN_SIZE: 9,
+  HINT_HEADER_SIZE: 1,
+  HINT_HOP_SIZE: 8,
+  HINT_HOP_INDEX_OFFSET: 4,
+  HINT_HOP_META_OFFSET: 6,
+  HINT_FRAME_PREFIX_SIZE: 8,
+  HINT_FRAME_COUNT_OFFSET: 4,
+  HINT_FRAME_META_OFFSET: 6,
+  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_NO_INDEX: 0xffff,
+  HINT_INDEX_RESERVED: 0xfffe,
+  HINT_META_ELEM_DYNAMIC: 0x8000,
+  HINT_META_DYNAMIC_ARRAY: 0x4000,
+  HINT_META_RESERVED_MASK: 0x3000,
+  HINT_META_STRIDE_MASK: 0x0fff,
+} as const satisfies Record<string, number>;
+
+///////////////////////////////////////////////////////////////////////////
+// Table-derived helpers
+///////////////////////////////////////////////////////////////////////////
+
+/**
+ * Extract a `{ KEY: code }` map from a table with `key` and `code` fields.
+ * @internal
+ */
+type CodeMap<T extends readonly { readonly key: string; readonly code: number }[]> = {
+  readonly [E in T[number] as E["key"]]: E["code"];
+};
+
+/** Build a plain `{ KEY: code }` object from a table at runtime. */
+function buildCodeMap<T extends readonly { readonly key: string; readonly code: number }[]>(table: T): CodeMap<T> {
+  // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- derived from the same const table that defines the type.
+  return Object.fromEntries(table.map((e) => [e.key, e.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 = new Map<number, ScopeInfo>(SCOPE_TABLE.map((e) => [e.code, { label: e.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
+///////////////////////////////////////////////////////////////////////////
+
+/** ABI type code ranges and sentinel values for the descriptor format. */
+export const TypeCode = {
+  UINT_MIN: 0x01,
+  UINT_MAX: 0x20,
+  INT_MIN: 0x21,
+  INT_MAX: 0x40,
+  ADDRESS: 0x41,
+  BOOL: 0x42,
+  FUNCTION: 0x43,
+  FIXED_BYTES_MIN: 0x50,
+  FIXED_BYTES_MAX: 0x6f,
+  BYTES: 0x70,
+  STRING: 0x71,
+  STATIC_ARRAY: 0x80,
+  DYNAMIC_ARRAY: 0x81,
+  TUPLE: 0x90,
+} as const satisfies Record<string, number>;
+
+///////////////////////////////////////////////////////////////////////////
+// Context property IDs
+///////////////////////////////////////////////////////////////////////////
+
+const CTX_PROP_TABLE = [
+  { key: "MSG_SENDER", code: 0x0000, label: "msg.sender", typeCode: TypeCode.ADDRESS },
+  { key: "MSG_VALUE", code: 0x0001, label: "msg.value", typeCode: TypeCode.UINT_MAX },
+  { key: "BLOCK_TIMESTAMP", code: 0x0002, label: "block.timestamp", typeCode: TypeCode.UINT_MAX },
+  { key: "BLOCK_NUMBER", code: 0x0003, label: "block.number", typeCode: TypeCode.UINT_MAX },
+  { key: "CHAIN_ID", code: 0x0004, label: "block.chainid", typeCode: TypeCode.UINT_MAX },
+  { key: "TX_ORIGIN", code: 0x0005, label: "tx.origin", typeCode: TypeCode.ADDRESS },
+  { key: "BASE_FEE", code: 0x0006, label: "block.basefee", typeCode: TypeCode.UINT_MAX },
+  { key: "GAS_PRICE", code: 0x0007, label: "tx.gasprice", typeCode: TypeCode.UINT_MAX },
+] as const;
+
+/** Well-known context property IDs for context-scope rules. */
+export const ContextProperty = buildCodeMap(CTX_PROP_TABLE);
+
+/** Maximum valid context property ID. */
+export const MAX_CONTEXT_PROPERTY_ID = Math.max(...CTX_PROP_TABLE.map((e) => e.code));
+
+/** Display metadata for a context property code. */
+export type ContextPropertyInfo = { label: string; contextKey: keyof import("./types").Context; typeCode: number };
+
+/** Maps each context property table key to its camelCase Context key. */
+const CTX_KEY_MAP: Record<(typeof CTX_PROP_TABLE)[number]["key"], keyof import("./types").Context> = {
+  MSG_SENDER: "msgSender",
+  MSG_VALUE: "msgValue",
+  BLOCK_TIMESTAMP: "blockTimestamp",
+  BLOCK_NUMBER: "blockNumber",
+  CHAIN_ID: "chainId",
+  TX_ORIGIN: "txOrigin",
+  BASE_FEE: "baseFee",
+  GAS_PRICE: "gasPrice",
+};
+
+const ctxPropByCode = new Map<number, ContextPropertyInfo>(
+  CTX_PROP_TABLE.map((e) => [e.code, { label: e.label, contextKey: CTX_KEY_MAP[e.key], typeCode: e.typeCode }]),
+);
+
+/**
+ * Map a context property code to its display label and ABI type code.
+ * @param code - Context property ID.
+ * @returns Display metadata including the ABI type code for the property value.
+ * @throws {CallciumError} If the code is not a recognised context property.
+ */
+export function lookupContextProperty(code: number): ContextPropertyInfo {
+  const info = ctxPropByCode.get(code);
+  if (!info) throw new CallciumError("UNKNOWN_CONTEXT_PROPERTY", `Unknown context property ${code}`);
+  return info;
+}
+
+///////////////////////////////////////////////////////////////////////////
+// Protocol limits
+///////////////////////////////////////////////////////////////////////////
+
+/** Protocol-imposed safety limits for path depth and quantifier array size. */
+export const Limits = {
+  MAX_PATH_DEPTH: 32,
+  MAX_QUANTIFIED_ARRAY_LENGTH: 256,
+  MAX_SET_MEMBERS: Math.floor((256 ** PolicyFormat.RULE_DATALENGTH_SIZE - 1) / 32),
+} as const satisfies Record<string, number>;
+
+///////////////////////////////////////////////////////////////////////////
+// Operator codes
+///////////////////////////////////////////////////////////////////////////
+
+/** Operand count category for operator data validation. */
+export type Operands = "single" | "range" | "variadic";
+
+/** @internal */
+const OP_TABLE = [
+  { key: "EQ", code: 0x01, label: "==", operands: "single" },
+  { key: "GT", code: 0x02, label: ">", operands: "single" },
+  { key: "LT", code: 0x03, label: "<", operands: "single" },
+  { key: "GTE", code: 0x04, label: ">=", operands: "single" },
+  { key: "LTE", code: 0x05, label: "<=", operands: "single" },
+  { key: "BETWEEN", code: 0x06, label: "between", operands: "range" },
+  { key: "IN", code: 0x07, label: "in", operands: "variadic" },
+  { 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" },
+] as const;
+
+/** Callcium policy operator codes. */
+export const Op: CodeMap<typeof OP_TABLE> & { readonly NOT: 0x80 } = { ...buildCodeMap(OP_TABLE), NOT: 0x80 };
+
+/** Display metadata for an operator code. */
+export type OpInfo = { label: string; operands: Operands };
+
+const opByCode = new Map<number, OpInfo>(OP_TABLE.map((e) => [e.code, { label: e.label, operands: e.operands }]));
+
+/**
+ * Map an operator code to its display label. Strips the NOT flag automatically.
+ * @param code - Operator byte value (may 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)
+    throw new CallciumError("UNKNOWN_OPERATOR", `Unknown operator code 0x${base.toString(16).padStart(2, "0")}`);
+  return info;
+}
+
+/**
+ * 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 = opByCode.get(opBase)?.operands;
+  if (operands === "single") return dataLength === 32;
+  if (operands === "range") return dataLength === 64;
+  if (operands === "variadic") return dataLength > 0 && dataLength % 32 === 0;
+  return false;
+}
+
+///////////////////////////////////////////////////////////////////////////
+// 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 = new Map<number, QuantifierInfo>(QUANTIFIER_TABLE.map((e) => [e.code, { label: e.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 0x${code.toString(16)}`);
+  return info;
+}
+
+/** 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 0x${code.toString(16).padStart(2, "0")}`);
+}
+
+// Pre-allocated constant objects for fixed type codes (avoids per-call allocation).
+const ELEMENTARY = { typeClass: "elementary", isDynamic: false } as const;
+const ELEMENTARY_DYN = { 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_DYN;
+  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 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) };
+}