HOW TO CREATE A C COUNTER PROGRAM ON THRU

This repository is a comprehensive, beginner-friendly guide to building your first C program on the Thru blockchain. Whether you are a seasoned developer or just starting out, this guide will walk you through every step of the process.

---

CLONE THE REPOSITORY

Start by cloning this repository and navigating into the project directory:

git clone https://github.com/namedfarouk/thru-c-tutorial.git
cd thru-c-tutorial

---

🛠️ SETUP ENVIRONMENT

1. Install Dependencies

Open your terminal and run the following command to install the core build tools:

sudo apt update && sudo apt install -y build-essential pkg-config libssl-dev protobuf-compiler libclang-dev clang npm

2. Install Buf CLI

Thru uses Buf for protocol buffers. Install it globally via npm:

sudo npm install -g @bufbuild/buf

3. Install Rust

The Thru CLI is built with Rust. Install the Rust toolchain:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
# Press 1 to proceed with the default installation
source $HOME/.cargo/env

4. Install Thru CLI

Now, install the official Thru command-line interface:

cargo install thru-cli --locked

Note: We use --locked to ensure we use the exact versions of dependencies intended by the developers, avoiding version conflicts.

---

INITIALIZE WALLET & ACCOUNT

1. Create Directories

mkdir -p ~/.thru/cli

2. Generate Wallet

thru-cli keys generate default

🌐 RPC CONFIGURATION (REQUIRED)

By default, the Thru CLI may be configured to use a local RPC endpoint (127.0.0.1), which will not work unless you are running a local Thru node.

For this guide, you should use the Thru Alphanet RPC.

Edit the Thru CLI config file

nano ~/.thru/cli/config.yaml

Update [rpc_base_url]

Change this:

rpc_base_url: http://127.0.0.1:8472

To this:

rpc_base_url: https://rest.alphanet.thruput.org

Save and exit the file.

3. Create and Fund Account

This command will set up your default account on the Thru network:

thru-cli account create default

---

INSTALL TOOLCHAIN & SDK

To compile C code for the Thru VM (which runs on RISC-V), you need:

1. System dependencies
2. The Thru RISC-V toolchain
3. The Thru C SDK

1. System Dependencies (Linux / Codespaces / WSL)

sudo apt update
sudo apt install -y \
  build-essential \
  pkg-config \
  libssl-dev \
  gcc-riscv64-unknown-elf

2. Install the Thru Toolchain

thru-cli dev toolchain install

3. Install the Thru C SDK

thru-cli dev sdk install c

4. Verify Install

ls ~/.thru/sdk
which riscv64-unknown-elf-gcc

Expected output:

c  toolchain
/usr/bin/riscv64-unknown-elf-gcc

---

CREATE YOUR PROGRAM

1. Create the Makefile (GNUmakefile)

The Makefile tells the compiler how to build your project. Create a file named GNUmakefile in your root directory:

## Explicit configuration for the Thru SDK build

THRU_HOME := $(HOME)/.thru
BASEDIR := $(CURDIR)/build

THRU_C_SDK_DIR := $(THRU_HOME)/sdk/c/thru-sdk
THRU_RISCV_TOOLCHAIN := $(THRU_HOME)/sdk/toolchain

export THRU_HOME
export THRU_RISCV_TOOLCHAIN
export PATH := $(THRU_RISCV_TOOLCHAIN)/bin:$(PATH)

include $(THRU_C_SDK_DIR)/thru_c_program.mk

2. Create the Header File (examples/tn_counter.h)

This file defines the "shape" of your data and instructions.

#ifndef TN_COUNTER_H
#define TN_COUNTER_H
#include <thru-sdk/c/tn_sdk.h>

#define TN_COUNTER_ERR_INVALID_INSTRUCTION 0x1000UL
#define TN_COUNTER_INSTRUCTION_CREATE (0U)
#define TN_COUNTER_INSTRUCTION_INCREMENT (1U)

typedef struct __attribute__((packed)) {
    uint instruction_type;
    ushort account_index;
    uchar counter_program_seed[TN_SEED_SIZE];
    uint proof_size;
} tn_counter_create_args_t;

typedef struct __attribute__((packed)) {
    ulong counter_value;
} tn_counter_account_t;
#endif

3. Create the Logic File (examples/tn_counter.c)

This is where the actual "smart" logic of your program lives.

#include <thru-sdk/c/tn_sdk.h>
#include "tn_counter.h"

TSDK_ENTRYPOINT_FN void start(uchar const *data, ulong size) {
    if (size < sizeof(uint)) tsdk_revert(TN_COUNTER_ERR_INVALID_INSTRUCTION);
    uint const *type = (uint const *)data;

    if (*type == TN_COUNTER_INSTRUCTION_CREATE) {
        // Handle initialization
        tsdk_return(TSDK_SUCCESS);
    } else {
        tsdk_revert(TN_COUNTER_ERR_INVALID_INSTRUCTION);
    }
}

---

INSTALL TOOLCHAIN & SDK

...commands...

---

⚠️ Alphanet RPC Notice

Thru currently operates on Alphanet. You may occasionally encounter errors such as:

• service is currently unavailable
• transaction rejected
• Parse failed

These are network-side issues and NOT caused by your setup. If this happens:

• Wait 1–2 minutes
• Retry the command

---

⚠️ Important
Before building, ensure the RISC-V toolchain is exposed to make:

export THRU_HOME=$HOME/.thru
export THRU_RISCV_TOOLCHAIN=$THRU_HOME/sdk/toolchain
export PATH=$THRU_RISCV_TOOLCHAIN/bin:$PATH

---

COMPILE AND DEPLOY

1. Compile

rm -rf build
make

⚠️ Note Do not run make clean. The Thru C SDK may error during make clean even on a valid setup. To reset the build state, delete the build/ directory instead.

2. Deploy

Deploy your compiled program to the Thru blockchain:

thru-cli program create my_counter ./build/thruvm/bin/tn_counter_program_c.bin

---

🔍 VERIFY YOUR WORK

Visit scan.thru.org and paste your Program ID to see your program live on the blockchain!

---

🤝 CONNECT WITH ME

If you found this guide helpful, feel free to reach out!

• X (Twitter): @namedfarouk

Thanks for using my guide! Built with ❤️ for the Thru Community.