Authoring Guide

Use this page when you are creating or editing ABI YAML by hand.

Caution

Thru ABIs are handwritten today. They do not automatically stay in sync with a program, so every ABI change should be treated like real source code and validated explicitly.

Best Starting Point

Do not start from a blank file unless you have to.

The fastest path is:

1. copy a shape from ABI Examples
2. rename packages and types
3. trim it down to the smallest schema that still represents your program
4. validate it with ABI Analyze

Authoring Priorities

Priority	Why it matters
Stable package and type names	Codegen output and import resolution stay predictable.
Clear field names for counts, tags, and payloads	Reflection and generated code become much easier to use.
Small, reusable imported packages	Shared types stay manageable without bloating the root file.
Earlier size-driving fields	The resolver rejects forward references in dynamic layouts.
A root ABI that is easy to read	Agents can reason about the file without loading too much context.

What To Put In The File

At minimum, most ABIs need:

• abi.package
• abi.abi-version
• abi.package-version
• abi.description
• types

Program-facing ABIs often also need:

• imports for shared or on-chain types
• options.program-metadata.root-types so tooling knows which types are the instruction root, account root, errors, and events

Imports

Use imports intentionally:

• path imports are the easiest authoring-time choice
• onchain imports are useful when you intentionally depend on a published ABI package
• remote imports are powerful, but they make publishing rules stricter

Practical rule:

• use local imports while you are iterating
• move to publish-safe normalization later with ABI Prep for Publish

Handwritten ABI Gotchas

• The ABI will not auto-update when the program changes.
• A valid-looking schema can still be wrong for the actual wire format your program emits or expects.
• Packing everything blindly is risky if the consumer expects alignment behavior.
• A schema can resolve successfully and still be awkward to use once you generate code from it.

Special Note On Authorization

The ABI describes data layout. It does not describe the full authorization model of your program.

That matters most for CPI-heavy programs:

• account indices and instruction payloads may be correct
• but the callee can still fail because the authorization or account-access model is wrong

For CPI behavior, validate the program logic and SDK flow separately. The ABI only gives you the wire format.

Best Next Step

Once the file exists, move immediately to Validation and roundtrip testing. That is where you prove the ABI actually matches the bytes you intend to send.