---
title: C SDK Overview
description: Build on-chain Thru programs in C with the SDK headers, syscall
  layer, and RISC-V toolchain.
source_url:
  html: https://thru.org/docs/sdks/c/
  md: https://thru.org/docs/sdks/c.md
---

# C SDK Overview

Use the C SDK when you want direct access to the Thru VM and the lowest-level program development workflow.

## Install

Before using the C SDK, install the CLI and development prerequisites through [Set Up Thru DevKit](https://thru.org/docs/program-development/setting-up-thru-devkit.md).

Then make sure you have installed both the toolchain and the C SDK with `thru`:

```bash
thru dev toolchain install
thru dev sdk install c
```

This gives you the RISC-V toolchain plus the installed C SDK headers and build integration used by downstream C programs.

After installation, the C SDK lands under `~/.thru/sdk/c`, and the downstream build hook lives at `~/.thru/sdk/c/thru-sdk/thru_c_program.mk`.

## Verify your install

```bash
test -d ~/.thru/sdk/c
test -f ~/.thru/sdk/c/thru-sdk/thru_c_program.mk
test -d ~/.thru/sdk/toolchain/bin
test -x ~/.thru/sdk/toolchain/bin/riscv64-unknown-elf-gcc || test -x ~/.thru/sdk/toolchain/bin/riscv64-none-elf-gcc
```

## Start here

| If you need… | Open this page |
| - | - |
| A compact mental model of how a program is laid out and exits | [Program Structure](https://thru.org/docs/sdks/c-reference/program-structure.md) |
| The rules of the Thru VM C environment and what differs from normal user-space C | [VM C Environment](https://thru.org/docs/sdks/c-reference/vm-c-environment.md) |
| Which header to include and which macros/helpers are foundational | [Headers and Entry Points](https://thru.org/docs/sdks/c-reference/headers-and-entry-points.md) |
| How to read accounts, transaction fields, block context, and shadow stack data | [Accounts and Transaction Context](https://thru.org/docs/sdks/c-reference/accounts-and-transaction-context.md) |
| What each syscall does and when to use it | [Syscalls](https://thru.org/docs/sdks/c-reference/syscalls.md) |
| How `tsys_invoke` and `tsdk_invoke_auth_t` work | [Cross-Program Invocation](https://thru.org/docs/sdks/c-reference/cross-program-invocation.md) |
| How proof headers and proof bodies are laid out | [State Proofs](https://thru.org/docs/sdks/c-reference/state-proofs.md) |
| How success, revert, syscall, and CPI errors should be handled | [Error Handling and Return Codes](https://thru.org/docs/sdks/c-reference/error-handling-and-return-codes.md) |
| How to wire the installed SDK into a downstream C project | [Build Integration](https://thru.org/docs/sdks/c-reference/build-integration.md) |
| Short, copyable program patterns | [Common Patterns](https://thru.org/docs/sdks/c-reference/common-patterns.md) |
| The main failure modes agents should avoid | [Common Gotchas](https://thru.org/docs/sdks/c-reference/common-gotchas.md) |

## When to use it

| Use the C SDK when you want to… | Why it fits |
| - | - |
| Write on-chain programs that run directly inside the Thru VM | The SDK exposes raw transaction context, account pointers, syscalls, and VM-oriented helpers. |
| Control account mutation and CPI explicitly | The syscall layer gives you direct access to create, resize, transfer, compress, decompress, and invoke operations. |
| Minimize abstraction and stay close to runtime layout | The public structs and helper functions mirror transaction, account, block, shadow stack, and state proof shapes closely. |

## Core entry points

| Entry point | What it provides |
| - | - |
| `#include <thru-sdk/c/tn_sdk.h>` | Main umbrella include for most programs. |
| `#include <thru-sdk/c/tn_sdk_syscall.h>` | Explicit syscall wrappers for account mutation, CPI, logging, events, and exit. |
| `#include <thru-sdk/c/tn_sdk_txn.h>` | Transaction, account metadata, block context, shadow stack, and state proof structs. |
| `thru_c_program.mk` | The downstream makefile entrypoint for compiling against the installed SDK. |

## Additional headers

| Header | What it provides |
| - | - |
| `#include <thru-sdk/c/tn_sdk_sha256.h>` | SHA-256 hashing (incremental and one-shot). |
| `#include <thru-sdk/c/tn_crypto.h>` | BLS12-381 cryptography: key generation, signing, verification, aggregation. Available when the installed toolchain includes `libblst.a` and headers. |
| `#include <thru-sdk/c/tn_rle.h>` | Run-length encoding for compact bitset representation. |
| `#include <thru-sdk/c/tn_sdk_types.h>` | Base public types (`tn_pubkey_t`, `tn_hash_t`, `tn_signature_t`). |
| `#include <thru-sdk/c/tn_sdk_base.h>` | Low-level alignment, scratch-allocation, and utility macros. |

## Related guides

- [Set Up Thru DevKit](https://thru.org/docs/program-development/setting-up-thru-devkit.md)
- [Build a C Program](https://thru.org/docs/program-development/building-a-c-program.md)
- [Cross-program invocation](https://thru.org/docs/program-development/cross-program-invocation.md)
- [VM syscalls overview](https://thru.org/docs/spec/vm/syscalls/overview.md)
- [Runtime overview](https://thru.org/docs/spec/runtime/overview.md)