This page is intentionally shorter than the internal ABI design material. Treat the ABI tooling itself, especially
analyze, reflect, and codegen, as the current source of truth when command behavior and prose ever diverge.Design Goals
Deterministic
ABI layouts are byte-for-byte reproducible so every backend sees the same structure.
Zero-Copy Friendly
The format is designed so generated code can access buffers directly instead of copying data out first.
Cross-Language
The same ABI definition can drive C, Rust, TypeScript, and reflection tooling.
Core Rules
| Rule | What to keep in mind |
|---|---|
| Endianness | Multi-byte values are little-endian. |
| Primitive types | The core type system includes signed and unsigned integers, floating-point types, and char. |
| Struct layout | Packed structs have no padding. Aligned structs insert padding based on natural alignment. |
| Arrays | Arrays can be fixed-size or runtime-sized through field references. |
| Flexible Array Members | Once the first runtime-sized field appears, offsets for later fields become runtime-dependent. |
| Enums and unions | Variant layout and discriminator rules must still yield deterministic validation behavior. |
| Dynamic parameters | Runtime-sized fields, tags, and payload sizes are tracked explicitly so validators, reflection, and codegen can agree on the same layout math. |
What ABI YAML Represents
At a high level, an ABI file contains:- package metadata such as package name and version
- optional imports
- named type definitions
- primitive fields
- structs
- unions
- enums
- fixed-size arrays
- variable-size arrays whose size is driven by earlier fields
- references to imported or previously defined types
Imports
The ABI toolchain supports multiple import sources:- local path imports
- git imports
- HTTP imports
- on-chain imports
- local imports are fine while you are writing and testing
- on-chain publishing requires those local imports to be inlined or otherwise normalized first
Dynamic Layouts
The hardest ABI cases are the ones with runtime-sized fields. Common examples:- a
name_lenfield followed by a byte array of that size - nested field references such as
box.first - arrays whose element counts depend on earlier fields
- expressions over nested array elements such as state proof bitsets
- ABI Analyze for type resolution and layout inspection
- ABI Reflect for real payload decoding
Practical Interpretation
- Put the field that drives a variable-length array before the variable field itself.
- Expect fully flattened or publish-ready artifacts to differ from your authoring-time source if you use local imports.
- Treat
analyze --print-iras the fastest way to inspect what the toolchain thinks the layout really is.
Use This Spec Efficiently
- Load this page when you need the underlying rules.
- Move to Examples or Authoring Guide once you are ready to author YAML.
- Move to Validation and roundtrip testing when you need CLI-backed validation rather than more specification detail.