Recommended Development Pattern

View as Markdown

Use this page when you are building a Thru program end to end with agents, not just writing one function or ABI file in isolation.

Start Here

The typical flow looks like this:

set up toolchain -> write program and local tests -> write ABI -> roundtrip test ABI -> deploy program + ABI -> test on devnet -> debug and iterate -> upgrade

This page gives the workflow. Use the linked SDK and CLI reference pages when you need exact commands or API details.

Use This Page To Route

Use this page for:

deciding what to do next in the program development loop
understanding the required order of ABI validation, deployment, and testing
spotting the common failure points before they cost you time

Do not use this page as the only source for:

exact CLI flags
exact ABI command syntax
exact C SDK API behavior
detailed runtime or VM semantics

If you already know your task, jump directly to:

Build a C Program for the program scaffold and binary layout
Validation and roundtrip testing for ABI proof loops
Publishing and Iteration for ABI publishing flows
Program, ABI, Transaction, and Network for exact CLI usage

Prerequisites

Before writing code, make sure the environment is ready:

For most C program work, the important install steps are:

npm i -g thru
thru dev toolchain install
thru dev sdk install c

Phase 1: Write the Program

Start from the C SDK and the minimal program guides:

What tends to help most:

start from a small working scaffold
keep local C tests close to the program
validate account ordering and CPI assumptions early

Stop here and fix the program before moving on if:

account ordering is still unclear
the program entrypoint or instruction layout is still changing rapidly
CPI authorization assumptions are not yet nailed down

Authorization and CPI

One recurring gotcha is that a correct wire format is not enough if the authorization model is wrong.

This shows up most often around CPI:

the instruction bytes may be correct
but the program still fails because account access or CPI authorization is wrong

Treat the authorization model as part of the program design, not part of the ABI.

Phase 2: Write the ABI

Move to the ABI guides once the instruction and account model is stable enough to describe:

Important reality:

ABIs are handwritten today
they do not stay in sync with the program automatically
agents should assume the ABI must be validated explicitly after every meaningful program change

Do not publish or rely on the ABI yet. First prove that the handwritten schema matches the intended wire format.

Phase 3: Validate the ABI roundtrip

Before deployment, run the local proof loop:

The high-value loop is:

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

If the reflected payload does not match what you meant to send, stop and fix the ABI or the transaction-building code before deployment.

This is the main guardrail for agents. It catches a large share of handwritten-ABI mistakes before any on-chain deployment happens.

Phase 4: Deploy the Program and ABI

When the program and ABI are both ready:

thru program create my_program ./build/thruvm/bin/my_program_c.bin
thru abi account create my_program ./program.abi.yaml

Important rule:

the ABI and program should use the same seed

That seed match is what lets downstream tooling associate a deployed program with the ABI that should be used to reflect its data.

Do not treat seed selection as a minor naming choice. Changing it breaks the expected linkage between the deployed program and its ABI.

For the ABI-specific side of this step, use Publishing and Iteration and ABI Account.

Phase 5: Test Real On-Chain Behavior

Beyond local C tests, meaningful program testing currently means interacting with a live chain, usually a devnet.

Important constraints:

there is no localnet support yet
you need a devnet RPC URL
Network is the easiest CLI surface for managing endpoints

Common practical flow:

use ABI-generated TypeScript to build instruction data
use @thru/sdk to submit the transaction
read transaction or account data back from the chain
reflect it with ABI tooling or inspect it in the explorer

Keep this phase narrow:

verify the deployed program accepts the instruction bytes you think it accepts
verify the resulting account or event data reflects the way you expect
avoid inventing new ABI or program structure changes while debugging deployment behavior

If the fee payer or wallet account is unfunded, fund it before retrying. On networks where the faucet program is available, use thru faucet to withdraw funds into the account you want to use for live writes.

The explorer at scan.thru.org supports custom RPC endpoint configuration through query parameters, which is useful when debugging a non-default network.

Phase 6: Debug Failures

When deployment or testing fails, start by classifying the failure:

-765 means something in the program threw
other failures are runtime or system errors

For runtime and VM-side issues, see runtime errors.

Common causes include:

invalid memory access
ABI drift between the program and the handwritten schema
CPI account ordering or authorization mistakes
partial deployment state left behind from a failed previous attempt

Treat deployment failures and ABI mismatches separately:

if the payload shape is wrong, go back to ABI roundtrip validation
if the payload shape is right but execution still fails, inspect program logic, CPI authorization, memory access, and runtime errors

Phase 7: Recover and Iterate

If a create or upgrade flow fails partway through, cleanup is often necessary before retrying.

The usual recovery tools are:

Uploader cleanup
Program destroy
ABI Account close

If the program changes, rerun the ABI validation loop before you publish an updated ABI or send new transactions against the changed binary.

When you are ready to ship a new binary:

thru program upgrade my_program ./build/thruvm/bin/my_program_c.bin

If the ABI also changed, upgrade the ABI account too:

ABI Account

Recommended Traversal For Agents

Setup the DevKit
Build a C Program
ABI Overview
Validation and roundtrip testing
Publishing and Iteration
Program, ABI, and Network for exact commands