@callcium/sdk 0.6.0 → 0.8.0

package/src/signature.ts

@@ -0,0 +1,97 @@
+import { keccak_256 } from "@noble/hashes/sha3.js";
+
+import { bytesToHex } from "./bytes";
+import { CallciumError } from "./errors";
+
+import type { Hex } from "./types";
+
+///////////////////////////////////////////////////////////////////////////
+// SignatureParser
+///////////////////////////////////////////////////////////////////////////
+
+/** Parsed components of an ABI function signature. */
+export type ParsedSignature = {
+  /** The 4-byte function selector as a 0x-prefixed hex string. */
+  selector: Hex;
+  /** Comma-separated parameter types, empty string for no-argument functions. */
+  types: string;
+};
+
+/** Return true if the char code is an ASCII letter. */
+function isAlpha(c: number): boolean {
+  return (c >= 0x41 && c <= 0x5a) || (c >= 0x61 && c <= 0x7a);
+}
+
+/** Return true if the char code is an ASCII alphanumeric character. */
+function isAlphanum(c: number): boolean {
+  return isAlpha(c) || (c >= 0x30 && c <= 0x39);
+}
+
+/**
+ * Parse an ABI function signature into its selector and types.
+ *
+ * Strict mode: no whitespace, name must match `[A-Za-z_][A-Za-z0-9_]*`,
+ * structure must be `name(types)` with the final `)` as the last character.
+ *
+ * @param signature - A function signature string, e.g. `"transfer(address,uint256)"`.
+ * @returns The 4-byte selector and the comma-separated types string.
+ * @throws {CallciumError} with code `"MALFORMED_SIGNATURE"`, `"SIGNATURE_CONTAINS_WHITESPACE"`, or
+ * `"INVALID_FUNCTION_NAME"` if the signature is malformed.
+ */
+function parse(signature: string): ParsedSignature {
+  if (signature.length < 3) {
+    throw new CallciumError("MALFORMED_SIGNATURE", `Invalid signature: too short, got "${signature}"`);
+  }
+
+  // Scan for whitespace, non-ASCII, and the opening parenthesis in one pass.
+  let openParen = -1;
+  for (let i = 0; i < signature.length; i++) {
+    const c = signature.charCodeAt(i);
+    if (c === 0x20 || c === 0x09 || c === 0x0a || c === 0x0d) {
+      throw new CallciumError("SIGNATURE_CONTAINS_WHITESPACE", "Signature must not contain whitespace");
+    }
+    if (c > 0x7e) {
+      throw new CallciumError("MALFORMED_SIGNATURE", "Signature must contain only ASCII characters");
+    }
+    if (openParen === -1 && c === 0x28) {
+      openParen = i;
+    }
+  }
+
+  if (openParen < 1) {
+    throw new CallciumError(
+      "MALFORMED_SIGNATURE",
+      `Invalid signature: must have a function name followed by parentheses, got "${signature}"`,
+    );
+  }
+
+  if (!signature.endsWith(")")) {
+    throw new CallciumError("MALFORMED_SIGNATURE", `Invalid signature: must end with ")", got "${signature}"`);
+  }
+
+  // Validate function name: [A-Za-z_][A-Za-z0-9_]*.
+  const firstChar = signature.charCodeAt(0);
+  if (!isAlpha(firstChar) && firstChar !== 0x5f) {
+    throw new CallciumError("INVALID_FUNCTION_NAME", "Function name must start with a letter or underscore");
+  }
+  for (let i = 1; i < openParen; i++) {
+    const c = signature.charCodeAt(i);
+    if (!isAlphanum(c) && c !== 0x5f) {
+      throw new CallciumError(
+        "INVALID_FUNCTION_NAME",
+        "Function name must contain only alphanumeric characters or underscores",
+      );
+    }
+  }
+
+  const encoded = new Uint8Array(signature.length);
+  for (let i = 0; i < signature.length; i++) encoded[i] = signature.charCodeAt(i);
+  const hash = keccak_256(encoded);
+
+  const selector = bytesToHex(hash.subarray(0, 4));
+  const types = signature.slice(openParen + 1, signature.length - 1);
+  return { selector, types };
+}
+
+/** ABI function signature parser. */
+export const SignatureParser = { parse };

package/src/type-desc.ts

@@ -0,0 +1,205 @@
+import { readU24, writeBE16, writeBE24 } from "./bytes";
+import { DescriptorFormat as DF, TypeCode } from "./constants";
+import { CallciumError } from "./errors";
+
+///////////////////////////////////////////////////////////////////////////
+// Internal helpers
+///////////////////////////////////////////////////////////////////////////
+
+/**
+ * Extract the staticWords count from a descriptor node.
+ *
+ * For elementary types (typeCode < STATIC_ARRAY), returns 1 unless the type is
+ * BYTES or STRING, which are ABI-dynamic and return 0. For composite types,
+ * reads the 24-bit meta field at offset 1 and shifts right by
+ * META_STATIC_WORDS_SHIFT.
+ */
+function extractStaticWords(desc: Uint8Array): number {
+  const typeCode = desc[0]!;
+  if (typeCode < TypeCode.STATIC_ARRAY) {
+    return typeCode === TypeCode.BYTES || typeCode === TypeCode.STRING ? 0 : 1;
+  }
+  return readU24(desc, 1) >> DF.META_STATIC_WORDS_SHIFT;
+}
+
+///////////////////////////////////////////////////////////////////////////
+// Elementary types
+///////////////////////////////////////////////////////////////////////////
+
+/** Build a descriptor node for `address`. */
+export function address(): Uint8Array {
+  return new Uint8Array([TypeCode.ADDRESS]);
+}
+
+/** Build a descriptor node for `bool`. */
+export function bool(): Uint8Array {
+  return new Uint8Array([TypeCode.BOOL]);
+}
+
+/** Build a descriptor node for `function`. */
+export function function_(): Uint8Array {
+  return new Uint8Array([TypeCode.FUNCTION]);
+}
+
+/**
+ * Build a descriptor node for `uintN`.
+ * @param bits - Bit width, 8–256 in steps of 8.
+ * @throws {CallciumError} With code `UNKNOWN_TYPE` if bits is out of range or not a multiple of 8.
+ */
+export function uintN(bits: number): Uint8Array {
+  if (bits < 8 || bits > 256 || bits % 8 !== 0) {
+    throw new CallciumError("UNKNOWN_TYPE", `Invalid uintN bits: ${bits}. Must be 8–256 in steps of 8.`);
+  }
+  return new Uint8Array([TypeCode.UINT_MIN + (bits / 8 - 1)]);
+}
+
+/**
+ * Build a descriptor node for `intN`.
+ * @param bits - Bit width, 8–256 in steps of 8.
+ * @throws {CallciumError} With code `UNKNOWN_TYPE` if bits is out of range or not a multiple of 8.
+ */
+export function intN(bits: number): Uint8Array {
+  if (bits < 8 || bits > 256 || bits % 8 !== 0) {
+    throw new CallciumError("UNKNOWN_TYPE", `Invalid intN bits: ${bits}. Must be 8–256 in steps of 8.`);
+  }
+  return new Uint8Array([TypeCode.INT_MIN + (bits / 8 - 1)]);
+}
+
+/** Build a descriptor node for `bytes` (dynamic). */
+export function bytes(): Uint8Array {
+  return new Uint8Array([TypeCode.BYTES]);
+}
+
+/** Build a descriptor node for `string`. */
+export function string_(): Uint8Array {
+  return new Uint8Array([TypeCode.STRING]);
+}
+
+/**
+ * Build a descriptor node for `bytesN`.
+ * @param n - Byte width, 1–32.
+ * @throws {CallciumError} With code `UNKNOWN_TYPE` if n is out of range.
+ */
+export function bytesN(n: number): Uint8Array {
+  if (n < 1 || n > 32) {
+    throw new CallciumError("UNKNOWN_TYPE", `Invalid bytesN size: ${n}. Must be 1–32.`);
+  }
+  return new Uint8Array([TypeCode.FIXED_BYTES_MIN + (n - 1)]);
+}
+
+///////////////////////////////////////////////////////////////////////////
+// Composite types
+///////////////////////////////////////////////////////////////////////////
+
+/**
+ * Build a descriptor node for a dynamic array `T[]` or static array `T[length]`.
+ *
+ * Dynamic form: `[0x81][meta:3][elemDesc]`
+ * Static form:  `[0x80][meta:3][elemDesc][length:be16]`
+ *
+ * @param elemDesc - Descriptor bytes for the element type.
+ * @param length - Fixed array length. When omitted, produces a dynamic array.
+ * @throws {CallciumError} If length is 0 or exceeds MAX_STATIC_ARRAY_LENGTH.
+ */
+export function array(elemDesc: Uint8Array, length?: number): Uint8Array {
+  if (length === undefined) {
+    // Dynamic array T[].
+    const nodeLength = DF.ARRAY_HEADER_SIZE + elemDesc.length;
+    if (nodeLength > DF.MAX_NODE_LENGTH) {
+      throw new CallciumError(
+        "NODE_LENGTH_TOO_LARGE",
+        `Dynamic array node length ${nodeLength} exceeds maximum ${DF.MAX_NODE_LENGTH}.`,
+      );
+    }
+    const meta24 = (0 << DF.META_STATIC_WORDS_SHIFT) | nodeLength;
+    const buf = new Uint8Array(1 + DF.COMPOSITE_META_SIZE + elemDesc.length);
+    buf[0] = TypeCode.DYNAMIC_ARRAY;
+    writeBE24(buf, 1, meta24);
+    buf.set(elemDesc, 4);
+    return buf;
+  }
+
+  // Static array T[length].
+  if (length <= 0 || length > DF.MAX_STATIC_ARRAY_LENGTH) {
+    throw new CallciumError(
+      "INVALID_ARRAY_LENGTH",
+      `Static array length ${length} out of range. Must be 1–${DF.MAX_STATIC_ARRAY_LENGTH}.`,
+    );
+  }
+  const nodeLength = DF.ARRAY_HEADER_SIZE + elemDesc.length + DF.ARRAY_LENGTH_SIZE;
+  if (nodeLength > DF.MAX_NODE_LENGTH) {
+    throw new CallciumError(
+      "NODE_LENGTH_TOO_LARGE",
+      `Static array node length ${nodeLength} exceeds maximum ${DF.MAX_NODE_LENGTH}.`,
+    );
+  }
+  const elemStaticWords = extractStaticWords(elemDesc);
+  const staticWords = elemStaticWords === 0 ? 0 : length * elemStaticWords;
+  if (staticWords > DF.MAX_STATIC_WORDS) {
+    throw new CallciumError(
+      "STATIC_WORDS_TOO_LARGE",
+      `Static array static words ${staticWords} exceeds maximum ${DF.MAX_STATIC_WORDS}.`,
+    );
+  }
+  const meta24 = (staticWords << DF.META_STATIC_WORDS_SHIFT) | nodeLength;
+  const buf = new Uint8Array(1 + DF.COMPOSITE_META_SIZE + elemDesc.length + DF.ARRAY_LENGTH_SIZE);
+  buf[0] = TypeCode.STATIC_ARRAY;
+  writeBE24(buf, 1, meta24);
+  buf.set(elemDesc, 4);
+  writeBE16(buf, 4 + elemDesc.length, length);
+  return buf;
+}
+
+/**
+ * Build a descriptor node for a tuple.
+ *
+ * Format: `[0x90][meta:3][fieldCount:be16][field0][field1]...`
+ *
+ * @param fieldDescs - Descriptor bytes for each field, in order.
+ * @throws {CallciumError} If fieldDescs is empty, exceeds MAX_TUPLE_FIELDS, or nodeLength overflows MAX_NODE_LENGTH.
+ */
+export function tuple(fieldDescs: Uint8Array[]): Uint8Array {
+  if (fieldDescs.length === 0 || fieldDescs.length > DF.MAX_TUPLE_FIELDS) {
+    throw new CallciumError(
+      "INVALID_TUPLE_FIELD_COUNT",
+      `Tuple field count ${fieldDescs.length} out of range. Must be 1–${DF.MAX_TUPLE_FIELDS}.`,
+    );
+  }
+  const totalFieldBytes = fieldDescs.reduce((sum, f) => sum + f.length, 0);
+  const nodeLength = DF.TUPLE_HEADER_SIZE + totalFieldBytes;
+  if (nodeLength > DF.MAX_NODE_LENGTH) {
+    throw new CallciumError(
+      "NODE_LENGTH_TOO_LARGE",
+      `Tuple node length ${nodeLength} exceeds maximum ${DF.MAX_NODE_LENGTH}.`,
+    );
+  }
+
+  let anyDynamic = false;
+  let staticWordsSum = 0;
+  for (const field of fieldDescs) {
+    const staticWords = extractStaticWords(field);
+    if (staticWords === 0) {
+      anyDynamic = true;
+    }
+    staticWordsSum += staticWords;
+  }
+  const staticWords = anyDynamic ? 0 : staticWordsSum;
+  if (staticWords > DF.MAX_STATIC_WORDS) {
+    throw new CallciumError(
+      "STATIC_WORDS_TOO_LARGE",
+      `Tuple static words ${staticWords} exceeds maximum ${DF.MAX_STATIC_WORDS}.`,
+    );
+  }
+  const meta24 = (staticWords << DF.META_STATIC_WORDS_SHIFT) | nodeLength;
+
+  const buf = new Uint8Array(1 + DF.COMPOSITE_META_SIZE + DF.TUPLE_FIELDCOUNT_SIZE + totalFieldBytes);
+  buf[0] = TypeCode.TUPLE;
+  writeBE24(buf, 1, meta24);
+  writeBE16(buf, 4, fieldDescs.length);
+  let offset = 6;
+  for (const field of fieldDescs) {
+    buf.set(field, offset);
+    offset += field.length;
+  }
+  return buf;
+}

package/src/types.ts

@@ -0,0 +1,280 @@
+///////////////////////////////////////////////////////////////////////////
+// Primitives
+///////////////////////////////////////////////////////////////////////////
+
+/** Hex-encoded byte string, 0x-prefixed. */
+export type Hex = `0x${string}`;
+
+/** Ethereum address, 0x-prefixed. */
+export type Address = `0x${string}`;
+
+/** Byte range in a source blob. */
+export type Span = { start: number; end: number };
+
+///////////////////////////////////////////////////////////////////////////
+// Enforce
+///////////////////////////////////////////////////////////////////////////
+
+/**
+ * Execution context for context-scoped rules.
+ * Each property maps to a well-known EVM execution environment value.
+ * Only the properties referenced by the policy need to be supplied.
+ */
+export type Context = {
+  msgSender?: Address;
+  msgValue?: bigint;
+  blockTimestamp?: bigint;
+  blockNumber?: bigint;
+  chainId?: bigint;
+  txOrigin?: Address;
+  baseFee?: bigint;
+  gasPrice?: bigint;
+};
+
+/** Result of enforcing a policy: pass with matched group index, or fail with one violation per failed group. */
+export type EnforceResult = { ok: true; matchedGroup: number } | { ok: false; violations: Violation[] };
+
+/** Subset of violation codes emitted by reader/navigation primitives. */
+export type NavigationViolationCode = "CALLDATA_OUT_OF_BOUNDS" | "ARRAY_INDEX_OUT_OF_BOUNDS";
+
+/** Calldata is shorter than the policy's selector slot. */
+export type MissingSelectorViolation = {
+  code: "MISSING_SELECTOR";
+};
+
+/** Calldata selector does not match the policy's expected selector. */
+export type SelectorMismatchViolation = {
+  code: "SELECTOR_MISMATCH";
+  /** Selector declared by the policy. */
+  expectedValue: Hex;
+  /** Selector observed in the calldata. */
+  resolvedValue: Hex;
+};
+
+/**
+ * A context-scoped rule referenced a property not supplied in the execution context.
+
+ */
+export type MissingContextViolation = {
+  code: "MISSING_CONTEXT";
+  group: number;
+  rule: number;
+  scope: number;
+  path: Hex;
+  /** Declared type of the missing context property. */
+  typeCode: number;
+  opCode?: number;
+  operandData?: Hex;
+};
+
+/**
+ * A rule's operator returned false against the loaded value.
+ *
+ * Field combinations:
+ * - `resolvedValue` present, `elementIndex` absent — scalar leaf or context value that failed the operator.
+ * - `resolvedValue` present, `elementIndex` present — universal-quantifier per-element failure.
+ * - `resolvedValue` absent, `elementIndex` absent — existential-aggregate failure (no element satisfied).
+ * - `resolvedValue` absent, `elementIndex` present — per-element failure where the leaf could not be loaded.
+ *
+ * For length operations (`isLengthOp(opCode)`), `resolvedValue` is a hex-encoded count
+ * rather than a 32-byte ABI word.
+ */
+export type ValueMismatchViolation = {
+  code: "VALUE_MISMATCH";
+  group: number;
+  rule: number;
+  scope: number;
+  path: Hex;
+  /** Operator code with the `Op.NOT` bit intact. */
+  opCode: number;
+  /** Full untruncated operand bytes declared by the rule. */
+  operandData: Hex;
+  /** Type code of the failing value's leaf. */
+  typeCode: number;
+  resolvedValue?: Hex;
+  elementIndex?: number;
+};
+
+/**
+ * Single-code shape for a calldata-navigation failure. Internal helper for de-duplication.
+ * @internal
+ */
+type CalldataNavigationVariant<C extends NavigationViolationCode> = {
+  code: C;
+  group: number;
+  rule: number;
+  scope: number;
+  path: Hex;
+  opCode?: number;
+  operandData?: Hex;
+  typeCode?: number;
+  elementIndex?: number;
+};
+
+/**
+ * Calldata structure prevented the rule from being evaluated.
+ *
+ * The operator was never applied; `opCode`, `operandData`, `typeCode`, and `elementIndex`
+ * are diagnostic context describing the failing site, not a constraint claim.
+ *
+ * A union of per-code variants, narrowable with `Extract<Violation, { code: "..." }>`.
+ */
+export type CalldataNavigationViolation =
+  | CalldataNavigationVariant<"CALLDATA_OUT_OF_BOUNDS">
+  | CalldataNavigationVariant<"ARRAY_INDEX_OUT_OF_BOUNDS">;
+
+/** A quantified array exceeded `Limits.MAX_QUANTIFIED_ARRAY_LENGTH`. */
+export type QuantifierLimitExceededViolation = {
+  code: "QUANTIFIER_LIMIT_EXCEEDED";
+  group: number;
+  rule: number;
+  scope: number;
+  path: Hex;
+  /** Hex-encoded element count of the offending array. */
+  resolvedValue: Hex;
+};
+
+/**
+ * A resolved word is not the canonical encoding of its declared type (spec §7.4).
+ *
+ * `resolvedValue` is the raw 32-byte word as it appeared in calldata, before any masking.
+ */
+export type NonCanonicalValueViolation = {
+  code: "NON_CANONICAL_VALUE";
+  group: number;
+  rule: number;
+  scope: number;
+  path: Hex;
+  /** Type code of the target whose encoding was violated. */
+  typeCode: number;
+  /** Raw 32-byte word as it appeared in calldata, before any masking. */
+  resolvedValue: Hex;
+  opCode?: number;
+  operandData?: Hex;
+  elementIndex?: number;
+};
+
+/** An `ANY` quantifier was applied to an empty array. */
+export type QuantifierEmptyArrayViolation = {
+  code: "QUANTIFIER_EMPTY_ARRAY";
+  group: number;
+  rule: number;
+  scope: number;
+  path: Hex;
+};
+
+/**
+ * Structured details of a single rule failure during enforcement.
+ *
+ * Carries semantic data only; no message strings.
+ * Discriminate on `code` to narrow to the matching variant.
+ */
+export type Violation =
+  | MissingSelectorViolation
+  | SelectorMismatchViolation
+  | MissingContextViolation
+  | ValueMismatchViolation
+  | CalldataNavigationViolation
+  | NonCanonicalValueViolation
+  | QuantifierLimitExceededViolation
+  | QuantifierEmptyArrayViolation;
+
+/** Machine-readable reason code for an enforcement violation. Derived from `Violation` to prevent drift. */
+export type ViolationCode = Violation["code"];
+
+///////////////////////////////////////////////////////////////////////////
+// Canonical policy types
+///////////////////////////////////////////////////////////////////////////
+
+/** Canonical structured representation of a policy. */
+export type PolicyData = {
+  isSelectorless: boolean;
+  selector: Hex;
+  descriptor: Hex;
+  groups: Constraint[][];
+  span?: Span;
+};
+
+/** A collection of operators targeting a specific value. */
+export type Constraint = {
+  scope: number;
+  path: Hex;
+  operators: Hex[];
+  /** Compiled hint block as carried on the wire; absent when the constraint has no encoding. */
+  hint?: Hex;
+  span?: Span;
+};
+
+///////////////////////////////////////////////////////////////////////////
+// Structural inspection types
+///////////////////////////////////////////////////////////////////////////
+
+/** A decoded value with its byte position in the source blob. */
+export type Field<T> = { value: T; span: Span };
+
+/** Structural representation of a decoded parameter within the descriptor. */
+export type DecodedParam = {
+  index: number;
+  typeCode: number;
+  isDynamic: boolean;
+  staticSize: number;
+  path: Hex;
+  span: Span;
+};
+
+/** Structural representation of a decoded rule with per-field spans. */
+export type DecodedRule = {
+  ruleSize: Field<number>;
+  scope: Field<number>;
+  pathDepth: Field<number>;
+  path: Field<Hex>;
+  /** Compiled hint block; present for calldata rules only. */
+  hint?: Field<Hex>;
+  opCode: Field<number>;
+  dataLength: Field<number>;
+  data: Field<Hex>;
+  span: Span;
+};
+
+/** Structural representation of a decoded group with metadata spans. */
+export type DecodedGroup = {
+  ruleCount: Field<number>;
+  groupSize: Field<number>;
+  rules: DecodedRule[];
+  span: Span;
+};
+
+/** Structural representation of a decoded policy with full byte-level spans. */
+export type DecodedPolicy = {
+  header: Field<number>;
+  selector: Field<Hex>;
+  descLength: Field<number>;
+  descriptor: { raw: Hex; header: Field<{ version: number; paramCount: number }>; params: DecodedParam[]; span: Span };
+  groupCount: Field<number>;
+  groups: DecodedGroup[];
+  span: Span;
+  version: number;
+  isSelectorless: boolean;
+};
+
+///////////////////////////////////////////////////////////////////////////
+// Validation issues
+///////////////////////////////////////////////////////////////////////////
+
+/** Severity of a validation issue. */
+export type IssueSeverity = "info" | "warning" | "error";
+
+/** Category of a validation issue. */
+export type IssueCategory = "typeMismatch" | "contradiction" | "redundancy" | "vacuity" | "compatibility";
+
+/** A single validation issue found during policy analysis. */
+export type Issue = {
+  severity: IssueSeverity;
+  category: IssueCategory;
+  groupIndex: number;
+  constraintIndex: number;
+  code: string;
+  value1: Hex;
+  value2: Hex;
+  message: string;
+};