---
title: Validation and roundtrip testing
description: Validate ABI YAML locally by analyzing it, generating code,
  building real payloads, and reflecting them back.
source_url:
  html: https://thru.org/docs/abi/validation-and-roundtrip-testing/
  md: https://thru.org/docs/abi/validation-and-roundtrip-testing.md
---

# Validation and roundtrip testing

Use this page when the ABI file exists and you need to prove it actually matches the bytes your program expects.

## The Core Loop

The highest-value local loop is:

```text
write ABI -> analyze -> codegen TypeScript -> build instruction data -> reflect it back
```

That loop catches the most common handwritten-ABI failures before you deploy anything.

## Recommended Workflow

1. **Analyze the schema**

   Run [ABI Analyze](https://thru.org/docs/cli-reference/abi-analyze.md) first to resolve imports, validate layout rules, and inspect IR if needed.

2. **Generate TypeScript**

   Run [ABI Codegen](https://thru.org/docs/cli-reference/abi-codegen.md) and use the generated TypeScript types/helpers to build real instruction data.

3. **Reflect the bytes back**

   Use [ABI Reflect](https://thru.org/docs/cli-reference/abi-reflect.md) on the resulting binary payload. If the reflected values do not match what you intended to send, the ABI is not ready yet.

4. **Only then move to deployment**

   Once the payload roundtrip is correct, move to [Publishing and Iteration](https://thru.org/docs/abi/deployment-and-program-testing.md).

## Why This Matters

ABIs are handwritten, so “looks right” is not good enough. The roundtrip loop proves:

- the schema resolves cleanly
- codegen can consume it
- the produced bytes match the schema when decoded back out

## Useful Command Split

| Goal | Best tool |
| - | - |
| Resolve imports and type graph | [ABI Analyze](https://thru.org/docs/cli-reference/abi-analyze.md) |
| Inspect layout IR or helper previews | [ABI Analyze](https://thru.org/docs/cli-reference/abi-analyze.md) with `--print-ir`, `--print-footprint`, or `--print-validate` |
| Generate TS for payload building | [ABI Codegen](https://thru.org/docs/cli-reference/abi-codegen.md) |
| Decode or validate a captured payload | [ABI Reflect](https://thru.org/docs/cli-reference/abi-reflect.md) |
| Normalize imports before publish or browser use | [ABI Flatten](https://thru.org/docs/cli-reference/abi-flatten.md), [ABI Prep for Publish](https://thru.org/docs/cli-reference/abi-prep-for-publish.md), or [ABI Bundle](https://thru.org/docs/cli-reference/abi-bundle.md) |

## Tooling Reality Today

A practical testing stack today often looks like:

- use ABI codegen to generate TypeScript
- use `@thru/sdk` to submit the transaction
- use ABI reflection tooling or the explorer to decode instruction, account, or transaction data afterward

That reflection step is still somewhat fragmented. In some flows, CLI or explorer tooling is the cleanest way to decode payloads even if you used `@thru/sdk` to send the transaction.

## Common Gotchas

- A schema can pass `analyze` and still be wrong for the actual bytes you are building.
- Generated code can expose awkward package or type structure that is hard to notice from YAML alone.
- Dynamic layouts need special attention; always prefer a real reflection roundtrip over eyeballing the schema.
- If context is tight, `analyze` plus `reflect --validate-only` is the fastest high-signal check.