Skip to main content
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.
This page is a workflow map, not the source of truth for exact command syntax or SDK APIs. Use it to choose the next step, then follow the linked SDK and CLI reference pages for implementation details.

​
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:

​
Prerequisites

Before writing code, make sure the environment is ready: For most C program work, the important install steps are: 
cargo install thru-cli
thru-cli dev toolchain install
thru-cli 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-cli program create my_program ./build/thruvm/bin/my_program_c.bin
thru-cli 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:
  1. use ABI-generated TypeScript to build instruction data
  2. use @thru/thru-sdk to submit the transaction
  3. read transaction or account data back from the chain
  4. 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
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: 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-cli program upgrade my_program ./build/thruvm/bin/my_program_c.bin
If the ABI also changed, upgrade the ABI account too:
  1. Setup the DevKit
  2. Build a C Program
  3. ABI Overview
  4. Validation and roundtrip testing
  5. Publishing and Iteration
  6. Program, ABI, and Network for exact commands