@thru/abi 0.1.29

package/dist/index.js

@@ -0,0 +1,1106 @@
+import YAML from 'yaml';
+
+// src/abiSchema.ts
+
+// src/errors.ts
+var AbiError = class extends Error {
+  constructor(code, message, details) {
+    super(message);
+    this.code = code;
+    this.details = details;
+    this.name = this.constructor.name;
+  }
+};
+var AbiParseError = class extends AbiError {
+  constructor(message, details) {
+    super("PARSE_ERROR", message, details);
+  }
+};
+var AbiValidationError = class extends AbiError {
+  constructor(message, details) {
+    super("VALIDATION_ERROR", message, details);
+  }
+};
+var AbiDecodeError = class extends AbiError {
+  constructor(message, details) {
+    super("DECODE_ERROR", message, details);
+  }
+};
+
+// src/abiSchema.ts
+var PRIMITIVE_NAMES = ["u8", "u16", "u32", "u64", "i8", "i16", "i32", "i64", "f16", "f32", "f64"];
+function parseAbiDocument(yamlText) {
+  let parsed;
+  try {
+    parsed = YAML.parse(yamlText, { intAsBigInt: true });
+  } catch (error) {
+    throw new AbiParseError("Failed to parse ABI YAML", {
+      cause: error instanceof Error ? error.message : String(error)
+    });
+  }
+  const root = requireRecord(parsed, "ABI document");
+  const abiNode = requireRecord(root.abi, "abi metadata");
+  const typesNode = root.types;
+  if (!Array.isArray(typesNode)) {
+    throw new AbiValidationError("ABI file must contain a 'types' array");
+  }
+  const metadata = parseMetadata(abiNode);
+  const types = typesNode.map((entry, index) => parseTypeDefinition(entry, index));
+  ensureTypeNamesUnique(types);
+  return { metadata, types };
+}
+function parseMetadata(node) {
+  const pkg = requireString(node.package, "abi.package");
+  const abiVersionRaw = node["abi-version"];
+  if (abiVersionRaw === void 0 || abiVersionRaw === null) {
+    throw new AbiValidationError("abi.abi-version is required");
+  }
+  const abiVersion = Number(abiVersionRaw);
+  if (!Number.isFinite(abiVersion)) {
+    throw new AbiValidationError("abi.abi-version must be a number");
+  }
+  const imports = node.imports;
+  if (imports !== void 0) {
+    const importList = Array.isArray(imports) ? imports : [];
+    if (importList.length > 0) {
+      throw new AbiValidationError("Flattened ABI files cannot contain 'imports'");
+    }
+  }
+  const metadata = {
+    package: pkg,
+    abiVersion
+  };
+  if (typeof node["package-version"] === "string") {
+    metadata.packageVersion = node["package-version"];
+  }
+  if (typeof node.description === "string") {
+    metadata.description = node.description;
+  }
+  return metadata;
+}
+function parseTypeDefinition(entry, index) {
+  const node = requireRecord(entry, `types[${index}]`);
+  const name = requireString(node.name, `types[${index}].name`);
+  const kindNode = node.kind;
+  if (!kindNode || typeof kindNode !== "object") {
+    throw new AbiValidationError(`Type '${name}' is missing its 'kind' definition`);
+  }
+  const kind = parseTypeKind(kindNode, name);
+  return { name, kind };
+}
+function parseTypeKind(node, context) {
+  const keys = Object.keys(node);
+  if (keys.length !== 1) {
+    throw new AbiValidationError(`Type '${context}' kind must be a single-entry object`);
+  }
+  const key = keys[0];
+  const value = node[key];
+  switch (key) {
+    case "primitive":
+      return parsePrimitiveType(value, context);
+    case "struct":
+      return parseStructType(requireRecord(value, `struct for ${context}`), context);
+    case "array":
+      return parseArrayType(requireRecord(value, `array for ${context}`), context);
+    case "enum":
+      return parseEnumType(requireRecord(value, `enum for ${context}`), context);
+    case "union":
+      return parseUnionType(requireRecord(value, `union for ${context}`), context);
+    case "size-discriminated-union":
+      return parseSizeDiscriminatedUnionType(requireRecord(value, `size-discriminated-union for ${context}`), context);
+    case "type-ref":
+      return parseTypeRef(requireRecord(value, `type-ref for ${context}`), context);
+    default:
+      throw new AbiValidationError(`Type '${context}' uses unsupported kind '${key}'`);
+  }
+}
+function parsePrimitiveType(value, context) {
+  if (typeof value !== "string") {
+    throw new AbiValidationError(`Primitive type for '${context}' must be a string`);
+  }
+  if (!PRIMITIVE_NAMES.includes(value)) {
+    throw new AbiValidationError(`Type '${context}' references unknown primitive '${value}'`);
+  }
+  return { kind: "primitive", primitive: value };
+}
+function parseStructType(node, context) {
+  const attributes = parseContainerAttributes(node);
+  const fieldsNode = node.fields;
+  if (!Array.isArray(fieldsNode)) {
+    throw new AbiValidationError(`Struct '${context}' must define a 'fields' array`);
+  }
+  const fields = fieldsNode.map((fieldNode, index) => {
+    const field = requireRecord(fieldNode, `field ${index} in struct '${context}'`);
+    const name = requireString(field.name, `field ${index} name in struct '${context}'`);
+    const fieldTypeNode = field["field-type"];
+    if (!fieldTypeNode || typeof fieldTypeNode !== "object") {
+      throw new AbiValidationError(`Field '${name}' in struct '${context}' is missing 'field-type'`);
+    }
+    const type = parseTypeKind(fieldTypeNode, `${context}.${name}`);
+    return { name, type };
+  });
+  return { kind: "struct", attributes, fields };
+}
+function parseArrayType(node, context) {
+  const attributes = parseContainerAttributes(node);
+  const elementNode = node["element-type"];
+  if (!elementNode || typeof elementNode !== "object") {
+    throw new AbiValidationError(`Array '${context}' is missing 'element-type'`);
+  }
+  const elementType = parseTypeKind(elementNode, `${context}[]`);
+  const sizeNode = node.size;
+  if (!sizeNode || typeof sizeNode !== "object") {
+    throw new AbiValidationError(`Array '${context}' is missing its 'size' expression`);
+  }
+  const size = parseExpression(sizeNode, `array '${context}' size`);
+  return { kind: "array", attributes, elementType, size };
+}
+function parseEnumType(node, context) {
+  const attributes = parseContainerAttributes(node);
+  const tagRefNode = node["tag-ref"];
+  if (!tagRefNode || typeof tagRefNode !== "object") {
+    throw new AbiValidationError(`Enum '${context}' must define 'tag-ref'`);
+  }
+  const tagExpression = parseExpression(tagRefNode, `enum '${context}' tag-ref`);
+  const variantsNode = node.variants;
+  if (!Array.isArray(variantsNode) || variantsNode.length === 0) {
+    throw new AbiValidationError(`Enum '${context}' must include at least one variant`);
+  }
+  const variants = variantsNode.map((variantNode, index) => {
+    const variant = requireRecord(variantNode, `variant ${index} in enum '${context}'`);
+    const name = requireString(variant.name, `variant ${index} name in enum '${context}'`);
+    const tagValueRaw = variant["tag-value"];
+    if (tagValueRaw === void 0 || tagValueRaw === null) {
+      throw new AbiValidationError(`Variant '${name}' in enum '${context}' must define 'tag-value'`);
+    }
+    const tagValue = Number(tagValueRaw);
+    if (!Number.isSafeInteger(tagValue)) {
+      throw new AbiValidationError(`Variant '${name}' in enum '${context}' has invalid tag-value`);
+    }
+    const variantTypeNode = variant["variant-type"];
+    if (!variantTypeNode || typeof variantTypeNode !== "object") {
+      throw new AbiValidationError(`Variant '${name}' in enum '${context}' is missing 'variant-type'`);
+    }
+    const type = parseTypeKind(variantTypeNode, `${context}.${name}`);
+    return { name, tagValue, type };
+  });
+  return { kind: "enum", attributes, tagExpression, variants };
+}
+function parseUnionType(node, context) {
+  const attributes = parseContainerAttributes(node);
+  const variantsNode = node.variants;
+  if (!Array.isArray(variantsNode) || variantsNode.length === 0) {
+    throw new AbiValidationError(`Union '${context}' must include at least one variant`);
+  }
+  const variants = variantsNode.map((variantNode, index) => {
+    const variant = requireRecord(variantNode, `variant ${index} in union '${context}'`);
+    const name = requireString(variant.name, `variant ${index} name in union '${context}'`);
+    const variantTypeNode = variant["variant-type"];
+    if (!variantTypeNode || typeof variantTypeNode !== "object") {
+      throw new AbiValidationError(`Variant '${name}' in union '${context}' is missing 'variant-type'`);
+    }
+    const type = parseTypeKind(variantTypeNode, `${context}.${name}`);
+    return { name, type };
+  });
+  return { kind: "union", attributes, variants };
+}
+function parseSizeDiscriminatedUnionType(node, context) {
+  const attributes = parseContainerAttributes(node);
+  const variantsNode = node.variants;
+  if (!Array.isArray(variantsNode) || variantsNode.length === 0) {
+    throw new AbiValidationError(`Size-discriminated union '${context}' must include variants`);
+  }
+  const variants = variantsNode.map((variantNode, index) => {
+    const variant = requireRecord(variantNode, `variant ${index} in size-discriminated union '${context}'`);
+    const name = requireString(variant.name, `variant ${index} name in size-discriminated union '${context}'`);
+    const sizeRaw = variant["expected-size"];
+    if (sizeRaw === void 0 || sizeRaw === null) {
+      throw new AbiValidationError(`Variant '${name}' in '${context}' must define 'expected-size'`);
+    }
+    const expectedSize = Number(sizeRaw);
+    if (!Number.isSafeInteger(expectedSize) || expectedSize < 0) {
+      throw new AbiValidationError(`Variant '${name}' in '${context}' has invalid expected-size`);
+    }
+    const variantTypeNode = variant["variant-type"];
+    if (!variantTypeNode || typeof variantTypeNode !== "object") {
+      throw new AbiValidationError(`Variant '${name}' in '${context}' is missing 'variant-type'`);
+    }
+    const type = parseTypeKind(variantTypeNode, `${context}.${name}`);
+    return { name, expectedSize, type };
+  });
+  return { kind: "size-discriminated-union", attributes, variants };
+}
+function parseTypeRef(node, context) {
+  const name = requireString(node.name, `type-ref in '${context}'`);
+  return { kind: "type-ref", name };
+}
+function parseContainerAttributes(node) {
+  const packed = node.packed === true;
+  const alignedRaw = node.aligned;
+  const aligned = alignedRaw === void 0 ? 0 : Number(alignedRaw);
+  if (aligned < 0 || !Number.isFinite(aligned)) {
+    throw new AbiValidationError("Container alignment must be a positive number when specified");
+  }
+  const attrs = { packed, aligned };
+  if (typeof node.comment === "string") {
+    attrs.comment = node.comment;
+  }
+  return attrs;
+}
+function parseExpression(node, context) {
+  const keys = Object.keys(node);
+  if (keys.length !== 1) {
+    throw new AbiValidationError(`Expression for ${context} must contain exactly one operator`);
+  }
+  const key = keys[0];
+  const value = node[key];
+  switch (key) {
+    case "literal":
+      return parseLiteralExpression(requireRecord(value, `literal expression in ${context}`), context);
+    case "field-ref":
+      return parseFieldRefExpression(requireRecord(value, `field-ref expression in ${context}`), context);
+    case "add":
+    case "sub":
+    case "mul":
+    case "div":
+    case "mod":
+    case "bit-and":
+    case "bit-or":
+    case "bit-xor":
+    case "left-shift":
+    case "right-shift":
+      return parseBinaryExpression(key, requireRecord(value, `${key} expression in ${context}`), context);
+    case "bit-not":
+      return parseUnaryExpression(key, requireRecord(value, `${key} expression in ${context}`), context);
+    case "sizeof":
+      return parseSizeOfExpression(requireRecord(value, `sizeof expression in ${context}`), context);
+    case "alignof":
+      return parseAlignOfExpression(requireRecord(value, `alignof expression in ${context}`), context);
+    default:
+      throw new AbiValidationError(`Expression '${key}' in ${context} is not supported yet`);
+  }
+}
+function parseLiteralExpression(node, context) {
+  const keys = Object.keys(node);
+  if (keys.length !== 1) {
+    throw new AbiValidationError(`Literal expression for ${context} must specify exactly one primitive type`);
+  }
+  const literalType = keys[0];
+  if (!PRIMITIVE_NAMES.includes(literalType)) {
+    throw new AbiValidationError(`Literal in ${context} references unknown primitive '${literalType}'`);
+  }
+  const rawValue = node[literalType];
+  if (typeof rawValue !== "number" && typeof rawValue !== "bigint") {
+    throw new AbiValidationError(`Literal in ${context} must be a number`);
+  }
+  const value = toBigInt(rawValue);
+  return { type: "literal", literalType, value };
+}
+function parseFieldRefExpression(node, context) {
+  const pathNode = node.path;
+  if (!Array.isArray(pathNode) || pathNode.length === 0) {
+    throw new AbiValidationError(`field-ref in ${context} must define a non-empty path array`);
+  }
+  const path = pathNode.map((segment, index) => {
+    if (typeof segment !== "string") {
+      throw new AbiValidationError(`field-ref segment ${index} in ${context} must be a string`);
+    }
+    return segment;
+  });
+  return { type: "field-ref", path };
+}
+function parseBinaryExpression(op, node, context) {
+  const leftNode = node.left;
+  const rightNode = node.right;
+  if (!leftNode || typeof leftNode !== "object" || !rightNode || typeof rightNode !== "object") {
+    throw new AbiValidationError(`Binary expression '${op}' in ${context} must include 'left' and 'right'`);
+  }
+  const left = parseExpression(leftNode, `${context} (left operand)`);
+  const right = parseExpression(rightNode, `${context} (right operand)`);
+  return { type: "binary", op, left, right };
+}
+function parseUnaryExpression(op, node, context) {
+  const operandNode = node.operand;
+  if (!operandNode || typeof operandNode !== "object") {
+    throw new AbiValidationError(`Unary expression '${op}' in ${context} must include 'operand'`);
+  }
+  const operand = parseExpression(operandNode, `${context} (operand)`);
+  return { type: "unary", op, operand };
+}
+function parseSizeOfExpression(node, context) {
+  const typeName = requireString(node["type-name"], `${context}.type-name`);
+  return { type: "sizeof", typeName };
+}
+function parseAlignOfExpression(node, context) {
+  const typeName = requireString(node["type-name"], `${context}.type-name`);
+  return { type: "alignof", typeName };
+}
+function ensureTypeNamesUnique(types) {
+  const seen = /* @__PURE__ */ new Set();
+  for (const type of types) {
+    if (seen.has(type.name)) {
+      throw new AbiValidationError(`Duplicate type definition '${type.name}' found in ABI`);
+    }
+    seen.add(type.name);
+  }
+}
+function requireRecord(value, context) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new AbiValidationError(`${context} must be an object`);
+  }
+  return value;
+}
+function requireString(value, context) {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new AbiValidationError(`${context} must be a non-empty string`);
+  }
+  return value;
+}
+function toBigInt(value) {
+  if (typeof value === "bigint") {
+    return value;
+  }
+  if (!Number.isFinite(value) || !Number.isInteger(value)) {
+    throw new AbiValidationError("Literal values must be integers");
+  }
+  return BigInt(value);
+}
+
+// src/expression.ts
+function evaluateExpression(expression, scope, context, registry) {
+  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);
+      const size = getConstSize(type.kind, registry, /* @__PURE__ */ new Map(), /* @__PURE__ */ 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:
+      throw new AbiDecodeError(`Unsupported expression encountered while decoding ${context}`);
+  }
+}
+function resolveFieldPath(path, scope, context) {
+  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, path, context) {
+  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, context) {
+  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, left, right, context) {
+  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:
+      throw new AbiDecodeError(`Binary operator '${op}' is not supported in ${context}`);
+  }
+}
+function applyUnaryOperator(op, operand, context) {
+  switch (op) {
+    case "bit-not":
+      return ~operand;
+    default:
+      throw new AbiDecodeError(`Unary operator '${op}' is not supported in ${context}`);
+  }
+}
+function createScope(parent) {
+  return { fields: /* @__PURE__ */ new Map(), parent };
+}
+function addFieldToScope(scope, name, value) {
+  if (scope) {
+    scope.fields.set(name, value);
+  }
+}
+
+// src/typeRegistry.ts
+var TypeRegistry = class {
+  constructor(definitions) {
+    this.types = /* @__PURE__ */ new Map();
+    for (const def of definitions) {
+      this.types.set(def.name, def);
+    }
+  }
+  get(typeName) {
+    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) {
+    return this.types.has(typeName);
+  }
+  entries() {
+    return this.types.entries();
+  }
+};
+function buildTypeRegistry(document) {
+  const registry = new TypeRegistry(document.types);
+  validateTypeReferences(registry);
+  detectReferenceCycles(registry);
+  return registry;
+}
+function validateTypeReferences(registry) {
+  for (const [, type] of registry.entries()) {
+    validateTypeKindReferences(type.kind, registry, type.name);
+  }
+}
+function validateTypeKindReferences(kind, registry, context) {
+  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;
+  }
+}
+function ensureTypeExists(typeRef, registry, context) {
+  if (!registry.has(typeRef.name)) {
+    throw new AbiValidationError(`Type '${context}' references unknown type '${typeRef.name}'`, {
+      typeName: context,
+      referencedType: typeRef.name
+    });
+  }
+}
+function detectReferenceCycles(registry) {
+  const visiting = /* @__PURE__ */ new Set();
+  const visited = /* @__PURE__ */ new Set();
+  const visit = (typeName, stack) => {
+    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, refs = /* @__PURE__ */ new Set()) {
+  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;
+  }
+  return refs;
+}
+function collectStructRefs(struct, refs) {
+  for (const field of struct.fields) {
+    collectTypeReferences(field.type, refs);
+  }
+}
+function collectEnumRefs(enumType, refs) {
+  for (const variant of enumType.variants) {
+    collectTypeReferences(variant.type, refs);
+  }
+}
+function collectUnionRefs(union, refs) {
+  for (const variant of union.variants) {
+    collectTypeReferences(variant.type, refs);
+  }
+}
+function collectSizeUnionRefs(union, refs) {
+  for (const variant of union.variants) {
+    collectTypeReferences(variant.type, refs);
+  }
+}
+
+// src/utils/bytes.ts
+function bytesToHex(bytes) {
+  return Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+function alignUp(offset, alignment) {
+  return offset + alignment - 1 & ~(alignment - 1);
+}
+
+// src/decoder.ts
+function decodeData(yamlText, typeName, data) {
+  if (!(data instanceof Uint8Array)) {
+    throw new AbiDecodeError("decodeData expects account data as a Uint8Array");
+  }
+  const trimmedTypeName = typeName?.trim();
+  if (!trimmedTypeName) {
+    throw new AbiDecodeError("decodeData requires a non-empty typeName argument");
+  }
+  const abiDocument = parseAbiDocument(yamlText);
+  const registry = buildTypeRegistry(abiDocument);
+  return decodeWithRegistry(registry, trimmedTypeName, data);
+}
+function decodeWithRegistry(registry, typeName, data) {
+  const type = registry.get(typeName);
+  const state = {
+    registry,
+    data,
+    view: new DataView(data.buffer, data.byteOffset, data.byteLength),
+    offset: 0,
+    scope: void 0
+  };
+  const value = decodeKind(type.kind, state, typeName, type.name, state.view.byteLength);
+  if (state.offset !== data.byteLength) {
+    throw new AbiDecodeError("Decoded data did not consume the full buffer", {
+      expectedLength: data.byteLength,
+      consumedLength: state.offset,
+      remainingBytes: data.byteLength - state.offset
+    });
+  }
+  return value;
+}
+function decodeKind(kind, state, context, typeName, byteBudget) {
+  switch (kind.kind) {
+    case "primitive":
+      return decodePrimitive(kind.primitive, state, context, typeName);
+    case "struct":
+      return decodeStruct(kind, state, context, typeName, byteBudget);
+    case "array":
+      return decodeArray(kind, state, context, typeName);
+    case "enum":
+      return decodeEnum(kind, state, context, typeName);
+    case "union":
+      return decodeUnion(kind, state, context, typeName);
+    case "size-discriminated-union":
+      return decodeSizeDiscriminatedUnion(kind, state, context, typeName, byteBudget);
+    case "type-ref":
+      return decodeTypeReference(kind, state, context, byteBudget);
+    default:
+      throw new AbiDecodeError(`Type '${context}' uses unsupported kind '${kind.kind}'`);
+  }
+}
+function decodeTypeReference(typeRef, state, context, byteBudget) {
+  const referenced = state.registry.get(typeRef.name);
+  return decodeKind(referenced.kind, state, context, typeRef.name, byteBudget);
+}
+function decodePrimitive(primitive, state, context, typeName) {
+  const info = primitiveInfo[primitive];
+  if (!info) {
+    throw new AbiDecodeError(`Primitive type '${primitive}' is not supported yet`, { context });
+  }
+  if (info.byteLength > 0) {
+    ensureAvailable(state, info.byteLength, context);
+  }
+  const start = state.offset;
+  const value = info.read(state.view, state.offset);
+  state.offset += info.byteLength;
+  const rawHex = sliceHex(state.data, start, state.offset);
+  return {
+    kind: "primitive",
+    primitiveType: primitive,
+    value,
+    byteOffset: start,
+    byteLength: info.byteLength,
+    rawHex,
+    typeName
+  };
+}
+function decodeStruct(struct, state, context, typeName, byteBudget) {
+  const start = state.offset;
+  const previousScope = state.scope;
+  const scope = createScope(previousScope);
+  state.scope = scope;
+  const trailingSizes = computeTrailingConstantSizes(struct, state.registry);
+  const fields = {};
+  const fieldOrder = [];
+  try {
+    struct.fields.forEach((field, index) => {
+      const fieldContext = `${context}.${field.name}`;
+      if (!struct.attributes.packed) {
+        const alignment = getTypeAlignment(field.type, state.registry);
+        state.offset = alignUp(state.offset, alignment);
+      }
+      const tailSize = trailingSizes[index];
+      const bytesConsumed = state.offset - start;
+      const availableBytes = byteBudget !== void 0 ? Math.max(byteBudget - bytesConsumed, 0) : state.view.byteLength - state.offset;
+      const fieldBudget = tailSize !== null ? Math.max(availableBytes - tailSize, 0) : void 0;
+      const value = decodeKind(field.type, state, fieldContext, void 0, fieldBudget);
+      fields[field.name] = value;
+      fieldOrder.push({ name: field.name, value });
+      addFieldToScope(scope, field.name, value);
+    });
+  } finally {
+    state.scope = previousScope;
+  }
+  const end = state.offset;
+  return {
+    kind: "struct",
+    typeName,
+    fields,
+    fieldOrder,
+    byteOffset: start,
+    byteLength: end - start,
+    rawHex: sliceHex(state.data, start, end)
+  };
+}
+function decodeArray(array, state, context, typeName) {
+  const lengthBigInt = evaluateExpression(array.size, state.scope, `${context}[size]`, state.registry);
+  const length = bigintToLength(lengthBigInt, context);
+  const elements = [];
+  const start = state.offset;
+  for (let i = 0; i < length; i++) {
+    const elementContext = `${context}[${i}]`;
+    elements.push(decodeKind(array.elementType, state, elementContext));
+  }
+  const end = state.offset;
+  return {
+    kind: "array",
+    typeName,
+    length,
+    elements,
+    byteOffset: start,
+    byteLength: end - start,
+    rawHex: sliceHex(state.data, start, end)
+  };
+}
+function decodeEnum(enumType, state, context, typeName) {
+  const tagBigInt = evaluateExpression(enumType.tagExpression, state.scope, `${context}[tag]`, state.registry);
+  const tagValue = bigintToNumber(tagBigInt, context);
+  const variant = enumType.variants.find((entry) => entry.tagValue === tagValue);
+  if (!variant) {
+    throw new AbiDecodeError(`Enum '${context}' has no variant with tag ${tagValue}`, {
+      availableVariants: enumType.variants.map((entry) => entry.tagValue)
+    });
+  }
+  const start = state.offset;
+  const value = decodeKind(variant.type, state, `${context}.${variant.name}`);
+  const end = state.offset;
+  return {
+    kind: "enum",
+    typeName,
+    tagValue,
+    variantName: variant.name,
+    value,
+    byteOffset: start,
+    byteLength: end - start,
+    rawHex: sliceHex(state.data, start, end)
+  };
+}
+function decodeUnion(union, state, context, typeName) {
+  const start = state.offset;
+  const variantViews = [];
+  let unionSize = 0;
+  for (const variant of union.variants) {
+    const preview = previewDecode(variant.type, state, `${context}.${variant.name}`, start);
+    if (preview.value) {
+      unionSize = Math.max(unionSize, preview.size ?? 0);
+      variantViews.push({ name: variant.name, value: preview.value });
+    } else if (preview.error) {
+      variantViews.push({
+        name: variant.name,
+        value: createOpaqueValue(preview.error.message, state.data, start, start, variant.name)
+      });
+    }
+  }
+  ensureAvailable(state, unionSize, context);
+  state.offset = start + unionSize;
+  return {
+    kind: "union",
+    typeName,
+    variants: variantViews,
+    note: "Union decoding is ambiguous; showing all variant interpretations.",
+    byteOffset: start,
+    byteLength: unionSize,
+    rawHex: sliceHex(state.data, start, start + unionSize)
+  };
+}
+function decodeSizeDiscriminatedUnion(union, state, context, typeName, byteBudget) {
+  const start = state.offset;
+  const matches = [];
+  const attempts = {};
+  for (const variant of union.variants) {
+    if (byteBudget !== void 0 && variant.expectedSize > byteBudget) {
+      continue;
+    }
+    const preview = previewDecode(variant.type, state, `${context}.${variant.name}`, start, variant.expectedSize);
+    if (preview.value && preview.size === variant.expectedSize) {
+      matches.push({ variantName: variant.name, value: preview.value, size: preview.size ?? 0, expected: variant.expectedSize });
+    } else if (preview.error) {
+      attempts[variant.name] = preview.error.message;
+    }
+  }
+  if (matches.length === 0) {
+    throw new AbiDecodeError(`No size-discriminated union variant in '${context}' matched the provided data`, {
+      attempts
+    });
+  }
+  let winner = matches[0];
+  if (matches.length > 1) {
+    if (byteBudget !== void 0) {
+      const exact = matches.filter((match) => match.expected === byteBudget);
+      if (exact.length === 1) {
+        winner = exact[0];
+      } else {
+        throw new AbiDecodeError(`Multiple size-discriminated union variants in '${context}' matched the provided data`, {
+          matches: matches.map((match) => match.variantName)
+        });
+      }
+    } else {
+      throw new AbiDecodeError(`Multiple size-discriminated union variants in '${context}' matched the provided data`, {
+        matches: matches.map((match) => match.variantName)
+      });
+    }
+  }
+  ensureAvailable(state, winner.size, context);
+  state.offset = start + winner.size;
+  return {
+    kind: "size-discriminated-union",
+    typeName,
+    variantName: winner.variantName,
+    expectedSize: winner.expected,
+    value: winner.value,
+    byteOffset: start,
+    byteLength: winner.size,
+    rawHex: sliceHex(state.data, start, start + winner.size)
+  };
+}
+function previewDecode(kind, state, context, start, limit) {
+  const snapshotOffset = state.offset;
+  const snapshotScope = state.scope;
+  const snapshotView = state.view;
+  const snapshotData = state.data;
+  if (limit !== void 0) {
+    if (start + limit > snapshotView.byteLength) {
+      return { error: new AbiDecodeError(`Variant '${context}' requires ${limit} bytes but only ${snapshotView.byteLength - start} remain`) };
+    }
+    state.view = new DataView(snapshotView.buffer, snapshotView.byteOffset + start, limit);
+    state.data = new Uint8Array(snapshotData.buffer, snapshotData.byteOffset + start, limit);
+    state.offset = 0;
+  } else {
+    state.offset = start;
+  }
+  try {
+    const value = decodeKind(kind, state, context);
+    const size = limit !== void 0 ? state.offset : state.offset - start;
+    return { value, size };
+  } catch (error) {
+    if (error instanceof AbiDecodeError) {
+      return { error };
+    }
+    return { error: new AbiDecodeError(error.message ?? `Failed to decode variant for ${context}`) };
+  } finally {
+    state.offset = snapshotOffset;
+    state.scope = snapshotScope;
+    state.view = snapshotView;
+    state.data = snapshotData;
+  }
+}
+function bigintToLength(length, context) {
+  if (length < 0n) {
+    throw new AbiDecodeError(`Array length expression in '${context}' evaluated to a negative value`);
+  }
+  const number = Number(length);
+  if (!Number.isSafeInteger(number)) {
+    throw new AbiDecodeError(`Array length expression in '${context}' exceeds JavaScript's safe integer range`);
+  }
+  return number;
+}
+function bigintToNumber(value, context) {
+  const number = Number(value);
+  if (!Number.isSafeInteger(number)) {
+    throw new AbiDecodeError(`Expression in '${context}' resulted in a value outside of JS safe integer range`);
+  }
+  return number;
+}
+function ensureAvailable(state, size, context) {
+  if (state.offset + size > state.view.byteLength) {
+    throw new AbiDecodeError(`Insufficient data while decoding '${context}'`, {
+      requested: size,
+      remaining: state.view.byteLength - state.offset
+    });
+  }
+}
+function sliceHex(buffer, start, end) {
+  return bytesToHex(buffer.subarray(start, end));
+}
+function createOpaqueValue(description, buffer, start, end, typeName) {
+  return {
+    kind: "opaque",
+    description,
+    byteOffset: start,
+    byteLength: end - start,
+    rawHex: sliceHex(buffer, start, end),
+    typeName
+  };
+}
+function computeTrailingConstantSizes(struct, registry) {
+  const memo = /* @__PURE__ */ new Map();
+  const sizes = [];
+  for (let i = 0; i < struct.fields.length; i++) {
+    let total = 0;
+    let deterministic = true;
+    for (let j = i + 1; j < struct.fields.length; j++) {
+      const size = getConstSize(struct.fields[j].type, registry, memo, /* @__PURE__ */ new Set());
+      if (size === null) {
+        deterministic = false;
+        break;
+      }
+      total += size;
+    }
+    sizes.push(deterministic ? total : null);
+  }
+  return sizes;
+}
+function getConstSize(kind, registry, memo, stack) {
+  switch (kind.kind) {
+    case "primitive":
+      return primitiveInfo[kind.primitive].byteLength;
+    case "array": {
+      const elementSize = getConstSize(kind.elementType, registry, memo, stack);
+      if (elementSize === null) return null;
+      const length = evaluateConstExpression(kind.size);
+      if (length === null) return null;
+      return elementSize * Number(length);
+    }
+    case "struct": {
+      let total = 0;
+      for (const field of kind.fields) {
+        const size = getConstSize(field.type, registry, memo, stack);
+        if (size === null) return null;
+        total += size;
+      }
+      return total;
+    }
+    case "enum": {
+      let variantSize = null;
+      for (const variant of kind.variants) {
+        const size = getConstSize(variant.type, registry, memo, stack);
+        if (size === null) return null;
+        if (variantSize === null) variantSize = size;
+        else if (variantSize !== size) return null;
+      }
+      return variantSize;
+    }
+    case "union": {
+      let maxSize = 0;
+      for (const variant of kind.variants) {
+        const size = getConstSize(variant.type, registry, memo, stack);
+        if (size === null) return null;
+        maxSize = Math.max(maxSize, size);
+      }
+      return maxSize;
+    }
+    case "size-discriminated-union":
+      return null;
+    case "type-ref":
+      if (memo.has(kind.name)) {
+        return memo.get(kind.name) ?? null;
+      }
+      if (stack.has(kind.name)) {
+        return null;
+      }
+      stack.add(kind.name);
+      const resolved = registry.get(kind.name);
+      const resolvedSize = getConstSize(resolved.kind, registry, memo, stack);
+      stack.delete(kind.name);
+      memo.set(kind.name, resolvedSize);
+      return resolvedSize;
+    default:
+      return null;
+  }
+}
+function evaluateConstExpression(expression) {
+  switch (expression.type) {
+    case "literal":
+      return expression.value;
+    case "binary": {
+      const left = evaluateConstExpression(expression.left);
+      const right = evaluateConstExpression(expression.right);
+      if (left === null || right === null) return null;
+      switch (expression.op) {
+        case "add":
+          return left + right;
+        case "sub":
+          return left - right;
+        case "mul":
+          return left * right;
+        case "div":
+          if (right === 0n) return null;
+          return left / right;
+        default:
+          return null;
+      }
+    }
+    case "field-ref":
+    case "unary":
+    case "sizeof":
+    case "alignof":
+      return null;
+    default:
+      return null;
+  }
+}
+var primitiveInfo = {
+  u8: { byteLength: 1, read: (view, offset) => view.getUint8(offset) },
+  i8: { byteLength: 1, read: (view, offset) => view.getInt8(offset) },
+  u16: { byteLength: 2, read: (view, offset) => view.getUint16(offset, true) },
+  i16: { byteLength: 2, read: (view, offset) => view.getInt16(offset, true) },
+  u32: { byteLength: 4, read: (view, offset) => view.getUint32(offset, true) },
+  i32: { byteLength: 4, read: (view, offset) => view.getInt32(offset, true) },
+  u64: { byteLength: 8, read: (view, offset) => view.getBigUint64(offset, true) },
+  i64: { byteLength: 8, read: (view, offset) => view.getBigInt64(offset, true) },
+  f32: { byteLength: 4, read: (view, offset) => view.getFloat32(offset, true) },
+  f64: { byteLength: 8, read: (view, offset) => view.getFloat64(offset, true) },
+  f16: {
+    byteLength: 2,
+    read: (view, offset) => {
+      return view.getUint16(offset, true);
+    }
+  }
+};
+function getTypeAlignment(kind, registry) {
+  switch (kind.kind) {
+    case "primitive":
+      return primitiveInfo[kind.primitive].byteLength;
+    case "struct":
+      if (kind.attributes.aligned > 0) return kind.attributes.aligned;
+      return kind.fields.reduce((max, field) => Math.max(max, getTypeAlignment(field.type, registry)), 1);
+    case "array":
+      return getTypeAlignment(kind.elementType, registry);
+    case "enum":
+      if (kind.attributes.aligned > 0) return kind.attributes.aligned;
+      return 1;
+    // Fallback
+    case "union":
+      if (kind.attributes.aligned > 0) return kind.attributes.aligned;
+      return kind.variants.reduce((max, variant) => Math.max(max, getTypeAlignment(variant.type, registry)), 1);
+    case "size-discriminated-union":
+      if (kind.attributes.aligned > 0) return kind.attributes.aligned;
+      return kind.variants.reduce((max, variant) => Math.max(max, getTypeAlignment(variant.type, registry)), 1);
+    case "type-ref":
+      return getTypeAlignment(registry.get(kind.name).kind, registry);
+    default:
+      return 1;
+  }
+}
+
+export { AbiDecodeError, AbiError, AbiParseError, AbiValidationError, TypeRegistry, buildTypeRegistry, decodeData, parseAbiDocument };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map