@thru/abi 0.1.29

package/src/expression.ts

@@ -0,0 +1,165 @@
+import type { BinaryOperator, Expression, UnaryOperator } from "./abiSchema";
+import type { DecodedStructValue, DecodedValue } from "./decodedValue";
+import { AbiDecodeError } from "./errors";
+import type { TypeRegistry } from "./typeRegistry";
+import { getConstSize, getTypeAlignment } from "./decoder";
+
+export interface FieldScope {
+  fields: Map<string, DecodedValue>;
+  parent?: FieldScope;
+}
+
+export function evaluateExpression(expression: Expression, scope: FieldScope | undefined, context: string, registry?: TypeRegistry): bigint {
+  switch (expression.type) {
+    case "literal":
+      return expression.value;
+    case "field-ref":
+      return toBigIntValue(resolveFieldPath(expression.path, scope, context), context);
+    case "binary":
+      return applyBinaryOperator(
+        expression.op,
+        evaluateExpression(expression.left, scope, `${context} (left)`, registry),
+        evaluateExpression(expression.right, scope, `${context} (right)`, registry),
+        context,
+      );
+    case "unary":
+      return applyUnaryOperator(
+        expression.op,
+        evaluateExpression(expression.operand, scope, `${context} (operand)`, registry),
+        context,
+      );
+    case "sizeof":
+      if (!registry) {
+        throw new AbiDecodeError(`Cannot evaluate sizeof(${expression.typeName}) without a TypeRegistry`);
+      }
+      const type = registry.get(expression.typeName);
+      // We need access to getConstSize from decoder.ts or similar logic
+      // Since getConstSize is currently internal to decoder.ts and not exported/accessible easily without refactoring
+      // We will assume getConstSize is made available or we implement a simple lookup if possible.
+      // However, decoder.ts imports expression.ts, so we have a circular dependency if we import getConstSize directly from decoder.ts
+      // ideally getConstSize should be in a separate file.
+      // For now, let's use the imported one if we can move it, or throw/stub it.
+      const size = getConstSize(type.kind, registry, new Map(), new Set());
+      if (size === null) {
+        throw new AbiDecodeError(`sizeof(${expression.typeName}) is not constant`);
+      }
+      return BigInt(size);
+    case "alignof":
+      if (!registry) {
+        throw new AbiDecodeError(`Cannot evaluate alignof(${expression.typeName}) without a TypeRegistry`);
+      }
+      const targetType = registry.get(expression.typeName);
+      const alignment = Math.max(getTypeAlignment(targetType.kind, registry), 1);
+      return BigInt(alignment);
+    default:
+      expression satisfies never;
+      throw new AbiDecodeError(`Unsupported expression encountered while decoding ${context}`);
+  }
+}
+
+export function resolveFieldPath(path: string[], scope: FieldScope | undefined, context: string): DecodedValue {
+  if (path.length === 0) {
+    throw new AbiDecodeError(`Invalid field-ref in ${context}: path cannot be empty`);
+  }
+  if (!scope) {
+    throw new AbiDecodeError(`Unable to resolve field '${path.join(".")}' in ${context}`);
+  }
+
+  const [head, ...tail] = path;
+
+  if (head === "..") {
+    if (!scope.parent) {
+      throw new AbiDecodeError(`Field reference in ${context} attempted to access parent scope, but none exists`);
+    }
+    return resolveFieldPath(tail, scope.parent, context);
+  }
+
+  if (scope.fields.has(head)) {
+    const value = scope.fields.get(head)!;
+    if (tail.length === 0) {
+      return value;
+    }
+    return resolveNestedStructValue(value, tail, context);
+  }
+
+  return resolveFieldPath(path, scope.parent, context);
+}
+
+function resolveNestedStructValue(value: DecodedValue, path: string[], context: string): DecodedValue {
+  if (value.kind !== "struct") {
+    throw new AbiDecodeError(
+      `Field reference '${path.join(".")}' in ${context} traversed through non-struct value of kind '${value.kind}'`,
+    );
+  }
+  const [head, ...tail] = path;
+  const nested = value.fields[head];
+  if (!nested) {
+    throw new AbiDecodeError(`Struct field '${head}' referenced in ${context} does not exist`);
+  }
+  if (tail.length === 0) {
+    return nested;
+  }
+  return resolveNestedStructValue(nested, tail, context);
+}
+
+function toBigIntValue(value: DecodedValue, context: string): bigint {
+  if (value.kind !== "primitive") {
+    throw new AbiDecodeError(`Expression in ${context} referenced non-primitive value of kind '${value.kind}'`);
+  }
+  return typeof value.value === "bigint" ? value.value : BigInt(value.value);
+}
+
+function applyBinaryOperator(op: BinaryOperator, left: bigint, right: bigint, context: string): bigint {
+  switch (op) {
+    case "add":
+      return left + right;
+    case "sub":
+      return left - right;
+    case "mul":
+      return left * right;
+    case "div":
+      if (right === 0n) {
+        throw new AbiDecodeError(`Division by zero while evaluating expression for ${context}`);
+      }
+      return left / right;
+    case "mod":
+      if (right === 0n) {
+        throw new AbiDecodeError(`Modulo by zero while evaluating expression for ${context}`);
+      }
+      return left % right;
+    case "bit-and":
+      return left & right;
+    case "bit-or":
+      return left | right;
+    case "bit-xor":
+      return left ^ right;
+    case "left-shift":
+      return left << right;
+    case "right-shift":
+      return left >> right;
+    default:
+      op satisfies never;
+      throw new AbiDecodeError(`Binary operator '${op}' is not supported in ${context}`);
+  }
+}
+
+function applyUnaryOperator(op: UnaryOperator, operand: bigint, context: string): bigint {
+  switch (op) {
+    case "bit-not":
+      return ~operand;
+    default:
+      op satisfies never;
+      throw new AbiDecodeError(`Unary operator '${op}' is not supported in ${context}`);
+  }
+}
+
+export function createScope(parent?: FieldScope): FieldScope {
+  return { fields: new Map(), parent };
+}
+
+export function addFieldToScope(scope: FieldScope | undefined, name: string, value: DecodedValue) {
+  if (scope) {
+    scope.fields.set(name, value);
+  }
+}
+

package/src/index.test.ts

@@ -0,0 +1,249 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+import YAML from "yaml";
+import {
+    AbiDecodeError,
+    AbiValidationError,
+    DecodedArrayValue,
+    DecodedPrimitiveValue,
+    DecodedStructValue,
+    DecodedValue,
+    decodeData,
+} from "./index";
+
+const here = fileURLToPath(new URL(".", import.meta.url));
+const repoRoot = path.resolve(here, "../../../..");
+const complianceRoot = path.join(repoRoot, "abi/abi_gen/tests/compliance_tests");
+
+const abiDefinitions = (relativePath: string) => fs.readFileSync(path.join(complianceRoot, "abi_definitions", relativePath), "utf8");
+const testCasePath = (relativePath: string) => path.join(complianceRoot, "test_cases", relativePath);
+
+const loadBinaryFromTestCase = (relativePath: string): Uint8Array => {
+  const raw = fs.readFileSync(testCasePath(relativePath), "utf8");
+  const parsed = YAML.parse(raw);
+  const hex = parsed?.["test-case"]?.["binary-hex"];
+  if (typeof hex !== "string") {
+    throw new Error(`Test case '${relativePath}' is missing binary-hex data`);
+  }
+  return hexToBytes(hex);
+};
+
+describe("decodeData happy path", () => {
+  it("decodes primitives with accurate numeric types", () => {
+    const abiText = abiDefinitions("primitives.abi.yaml");
+    const binary = loadBinaryFromTestCase("primitives/common_values.yaml");
+
+    const result = decodeData(abiText, "AllPrimitives", binary) as DecodedStructValue;
+
+    const fields = result.fields;
+    expect(asPrimitive(fields.u8_val).value).toBe(42);
+    expect(asPrimitive(fields.u16_val).value).toBe(1000);
+    expect(asPrimitive(fields.u32_val).value).toBe(0x12345678);
+    expect(asPrimitive(fields.u64_val).value).toBe(0x123456789abcdef0n);
+    expect(asPrimitive(fields.i8_val).value).toBe(-42);
+    expect(asPrimitive(fields.i16_val).value).toBe(-1234);
+    expect(asPrimitive(fields.i32_val).value).toBe(-123456);
+    expect(asPrimitive(fields.i64_val).value).toBe(-123_456_789n);
+    expect(asPrimitive(fields.f32_val).value).toBeCloseTo(3.14159, 5);
+    expect(asPrimitive(fields.f64_val).value).toBeCloseTo(2.718281828459045, 12);
+  });
+
+  it("handles interleaved variable-length arrays", () => {
+    const abiText = abiDefinitions("array_structs.abi.yaml");
+    const binary = loadBinaryFromTestCase("array_structs/dual_arrays.yaml");
+
+    const result = decodeData(abiText, "DualArrays", binary) as DecodedStructValue;
+    const arr1 = result.fields.arr1 as DecodedArrayValue;
+    const arr2 = result.fields.arr2 as DecodedArrayValue;
+
+    expect(arr1.length).toBe(3);
+    expect(arr1.elements.map((el) => asPrimitive(el).value)).toEqual([0x11, 0x22, 0x33]);
+
+    expect(arr2.length).toBe(2);
+    expect(arr2.elements.map((el) => asPrimitive(el).value)).toEqual([0x4444, 0x5555]);
+  });
+
+  it("evaluates array size expressions using field references", () => {
+    const abiText = abiDefinitions("array_structs.abi.yaml");
+    const binary = loadBinaryFromTestCase("array_structs/matrix.yaml");
+
+    const result = decodeData(abiText, "Matrix", binary) as DecodedStructValue;
+
+    const rows = Number(asPrimitive(result.fields.rows).value);
+    const cols = Number(asPrimitive(result.fields.cols).value);
+    const dataField = result.fields.data as DecodedArrayValue;
+
+    expect(dataField.length).toBe(rows * cols + 1);
+    expect(dataField.elements.map((el) => asPrimitive(el).value)).toEqual([1, 2, 3, 4, 5, 6, 255]);
+  });
+
+  it("selects size-discriminated union variants based on runtime size", () => {
+    const abiText = sizeDiscriminatedUnionAbi;
+    const shortData = hexToBytes("04 00 00 00");
+    const longData = hexToBytes("01 00 00 00 02 00 00 00");
+
+    const short = decodeData(abiText, "Payload", shortData);
+    expect(short.kind).toBe("size-discriminated-union");
+    if (short.kind === "size-discriminated-union") {
+      expect(short.variantName).toBe("Short");
+      const value = short.value as DecodedStructValue;
+      expect(asPrimitive(value.fields.value).value).toBe(4);
+    }
+
+    const long = decodeData(abiText, "Payload", longData);
+    expect(long.kind).toBe("size-discriminated-union");
+    if (long.kind === "size-discriminated-union") {
+      expect(long.variantName).toBe("Long");
+      const value = long.value as DecodedStructValue;
+      expect(asPrimitive(value.fields.head).value).toBe(1);
+      expect(asPrimitive(value.fields.tail).value).toBe(2);
+    }
+  });
+});
+
+describe("decodeData error cases", () => {
+  it("throws when buffer is too short", () => {
+    const abiText = abiDefinitions("primitives.abi.yaml");
+    const binary = loadBinaryFromTestCase("primitives/common_values.yaml").slice(0, 10);
+    expect(() => decodeData(abiText, "AllPrimitives", binary)).toThrowError(AbiDecodeError);
+  });
+
+  it("rejects references to unknown types", () => {
+    const abiText = `
+abi:
+  package: "test"
+  abi-version: 1
+types:
+  - name: "HasRef"
+    kind:
+      struct:
+        packed: true
+        fields:
+          - name: "missing"
+            field-type:
+              type-ref:
+                name: "Nope"
+`;
+    expect(() => decodeData(abiText, "HasRef", new Uint8Array()))
+      .toThrowError(AbiValidationError);
+  });
+
+  it("detects simple reference cycles", () => {
+    const abiText = `
+abi:
+  package: "test"
+  abi-version: 1
+types:
+  - name: "Loop"
+    kind:
+      struct:
+        packed: true
+        fields:
+          - name: "next"
+            field-type:
+              type-ref:
+                name: "Loop"
+`;
+    expect(() => decodeData(abiText, "Loop", new Uint8Array()))
+      .toThrowError(AbiValidationError);
+  });
+
+  it("reports unsupported expression operators", () => {
+    const abiText = `
+abi:
+  package: "test"
+  abi-version: 1
+types:
+  - name: "BadArray"
+    kind:
+      struct:
+        packed: true
+        fields:
+          - name: "length"
+            field-type:
+              primitive: u32
+          - name: "data"
+            field-type:
+              array:
+                size:
+                  pow:
+                    left:
+                      field-ref:
+                        path: ["length"]
+                    right:
+                      literal:
+                        u32: 2
+                element-type:
+                  primitive: u8
+`;
+    expect(() => decodeData(abiText, "BadArray", new Uint8Array()))
+      .toThrowError(AbiValidationError);
+  });
+
+  it("errors when no size-discriminated union variant matches", () => {
+    const data = hexToBytes("01 02 03");
+    expect(() => decodeData(sizeDiscriminatedUnionAbi, "Payload", data))
+      .toThrowError(AbiDecodeError);
+  });
+
+  it("throws when requested type is absent", () => {
+    const abiText = abiDefinitions("primitives.abi.yaml");
+    expect(() => decodeData(abiText, "MissingType", new Uint8Array()))
+      .toThrowError(AbiValidationError);
+  });
+});
+
+function hexToBytes(hex: string): Uint8Array {
+  const normalized = hex.replace(/[^a-fA-F0-9]/g, "");
+  if (normalized.length % 2 !== 0) {
+    throw new Error("Hex string must contain an even number of characters");
+  }
+  const bytes = new Uint8Array(normalized.length / 2);
+  for (let i = 0; i < bytes.length; i++) {
+    bytes[i] = Number.parseInt(normalized.slice(i * 2, i * 2 + 2), 16);
+  }
+  return bytes;
+}
+
+function asPrimitive(value: DecodedValue): DecodedPrimitiveValue {
+  if (value.kind !== "primitive") {
+    throw new Error(`Expected primitive value, received ${value.kind}`);
+  }
+  return value;
+}
+
+const sizeDiscriminatedUnionAbi = `
+abi:
+  package: "test.union"
+  abi-version: 1
+types:
+  - name: "Payload"
+    kind:
+      size-discriminated-union:
+        packed: true
+        variants:
+          - name: "Short"
+            expected-size: 4
+            variant-type:
+              struct:
+                packed: true
+                fields:
+                  - name: "value"
+                    field-type:
+                      primitive: u32
+          - name: "Long"
+            expected-size: 8
+            variant-type:
+              struct:
+                packed: true
+                fields:
+                  - name: "head"
+                    field-type:
+                      primitive: u32
+                  - name: "tail"
+                    field-type:
+                      primitive: u32
+`;
+

package/src/index.ts

@@ -0,0 +1,15 @@
+export { decodeData } from "./decoder";
+export { parseAbiDocument } from "./abiSchema";
+export { buildTypeRegistry, TypeRegistry } from "./typeRegistry";
+export type {
+  DecodedArrayValue,
+  DecodedEnumValue,
+  DecodedField,
+  DecodedPrimitiveValue,
+  DecodedSizeDiscriminatedUnionValue,
+  DecodedStructValue,
+  DecodedUnionValue,
+  DecodedValue,
+} from "./decodedValue";
+export { AbiError, AbiDecodeError, AbiParseError, AbiValidationError } from "./errors";
+

package/src/typeRegistry.ts

@@ -0,0 +1,172 @@
+import type {
+  AbiDocument,
+  ArrayType,
+  EnumType,
+  SizeDiscriminatedUnionType,
+  StructType,
+  TypeDefinition,
+  TypeKind,
+  TypeRefType,
+  UnionType,
+} from "./abiSchema";
+import { AbiValidationError } from "./errors";
+
+export class TypeRegistry {
+  private readonly types = new Map<string, TypeDefinition>();
+
+  constructor(definitions: Iterable<TypeDefinition>) {
+    for (const def of definitions) {
+      this.types.set(def.name, def);
+    }
+  }
+
+  get(typeName: string): TypeDefinition {
+    const definition = this.types.get(typeName);
+    if (!definition) {
+      throw new AbiValidationError(`Type '${typeName}' is not defined in this ABI file`, { typeName });
+    }
+    return definition;
+  }
+
+  has(typeName: string): boolean {
+    return this.types.has(typeName);
+  }
+
+  entries(): IterableIterator<[string, TypeDefinition]> {
+    return this.types.entries();
+  }
+}
+
+export function buildTypeRegistry(document: AbiDocument): TypeRegistry {
+  const registry = new TypeRegistry(document.types);
+  validateTypeReferences(registry);
+  detectReferenceCycles(registry);
+  return registry;
+}
+
+function validateTypeReferences(registry: TypeRegistry) {
+  for (const [, type] of registry.entries()) {
+    validateTypeKindReferences(type.kind, registry, type.name);
+  }
+}
+
+function validateTypeKindReferences(kind: TypeKind, registry: TypeRegistry, context: string) {
+  switch (kind.kind) {
+    case "type-ref":
+      ensureTypeExists(kind, registry, context);
+      break;
+    case "struct":
+      kind.fields.forEach((field) => validateTypeKindReferences(field.type, registry, `${context}.${field.name}`));
+      break;
+    case "array":
+      validateTypeKindReferences(kind.elementType, registry, `${context}[]`);
+      break;
+    case "enum":
+      kind.variants.forEach((variant) => validateTypeKindReferences(variant.type, registry, `${context}.${variant.name}`));
+      break;
+    case "union":
+      kind.variants.forEach((variant) => validateTypeKindReferences(variant.type, registry, `${context}.${variant.name}`));
+      break;
+    case "size-discriminated-union":
+      kind.variants.forEach((variant) => validateTypeKindReferences(variant.type, registry, `${context}.${variant.name}`));
+      break;
+    case "primitive":
+      break;
+    default:
+      kind satisfies never;
+  }
+}
+
+function ensureTypeExists(typeRef: TypeRefType, registry: TypeRegistry, context: string) {
+  if (!registry.has(typeRef.name)) {
+    throw new AbiValidationError(`Type '${context}' references unknown type '${typeRef.name}'`, {
+      typeName: context,
+      referencedType: typeRef.name,
+    });
+  }
+}
+
+function detectReferenceCycles(registry: TypeRegistry) {
+  const visiting = new Set<string>();
+  const visited = new Set<string>();
+
+  const visit = (typeName: string, stack: string[]) => {
+    if (visited.has(typeName)) {
+      return;
+    }
+    if (visiting.has(typeName)) {
+      const cyclePath = [...stack, typeName];
+      throw new AbiValidationError(`Cyclic type reference detected: ${cyclePath.join(" -> ")}`, { cycle: cyclePath });
+    }
+
+    visiting.add(typeName);
+    const type = registry.get(typeName);
+    const referencedTypes = collectTypeReferences(type.kind);
+    for (const referenced of referencedTypes) {
+      if (registry.has(referenced)) {
+        visit(referenced, [...stack, typeName]);
+      }
+    }
+    visiting.delete(typeName);
+    visited.add(typeName);
+  };
+
+  for (const [typeName] of registry.entries()) {
+    if (!visited.has(typeName)) {
+      visit(typeName, []);
+    }
+  }
+}
+
+function collectTypeReferences(kind: TypeKind, refs: Set<string> = new Set()): Set<string> {
+  switch (kind.kind) {
+    case "type-ref":
+      refs.add(kind.name);
+      break;
+    case "struct":
+      collectStructRefs(kind, refs);
+      break;
+    case "array":
+      collectTypeReferences(kind.elementType, refs);
+      break;
+    case "enum":
+      collectEnumRefs(kind, refs);
+      break;
+    case "union":
+      collectUnionRefs(kind, refs);
+      break;
+    case "size-discriminated-union":
+      collectSizeUnionRefs(kind, refs);
+      break;
+    case "primitive":
+      break;
+    default:
+      kind satisfies never;
+  }
+  return refs;
+}
+
+function collectStructRefs(struct: StructType, refs: Set<string>) {
+  for (const field of struct.fields) {
+    collectTypeReferences(field.type, refs);
+  }
+}
+
+function collectEnumRefs(enumType: EnumType, refs: Set<string>) {
+  for (const variant of enumType.variants) {
+    collectTypeReferences(variant.type, refs);
+  }
+}
+
+function collectUnionRefs(union: UnionType, refs: Set<string>) {
+  for (const variant of union.variants) {
+    collectTypeReferences(variant.type, refs);
+  }
+}
+
+function collectSizeUnionRefs(union: SizeDiscriminatedUnionType, refs: Set<string>) {
+  for (const variant of union.variants) {
+    collectTypeReferences(variant.type, refs);
+  }
+}
+

package/src/utils/bytes.ts

@@ -0,0 +1,7 @@
+export function bytesToHex(bytes: Uint8Array): string {
+  return Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+
+export function alignUp(offset: number, alignment: number): number {
+  return (offset + alignment - 1) & ~(alignment - 1);
+}