Skip to main content
Use this page when you need to know which header to include, which macros are foundational, and what the public C entry surface actually is.

​
Include selection

IncludeUse it when
#include <thru-sdk/c/tn_sdk.h>Default starting point for almost every downstream C program. It pulls in the base macros, transaction helpers, and core runtime helpers.
#include <thru-sdk/c/tn_sdk_syscall.h>You need explicit syscall wrappers such as account mutation, CPI, logging, event emission, or direct exit.
#include <thru-sdk/c/tn_sdk_txn.h>You need the public struct layouts for transactions, account metadata, block context, shadow stack, or state proofs.
#include <thru-sdk/c/tn_sdk_types.h>You only need base public types like tn_pubkey_t, tn_hash_t, or tn_signature_t.
#include <thru-sdk/c/tn_sdk_base.h>You need the low-level alignment, scratch-allocation, or utility macros directly. Most programs can stay at tn_sdk.h.
#include <thru-sdk/c/tn_sdk_sha256.h>You need SHA-256 hashing for address derivation, data integrity, or custom hashing logic.
#include <thru-sdk/c/tn_crypto.h>You need BLS12-381 cryptography: key generation, signing, verification, or signature aggregation. Use it when the installed toolchain includes libblst.a and headers.
#include <thru-sdk/c/tn_rle.h>You need run-length encoding for compact bitset representation (e.g., guardian sets, validator bitmaps).

​
Main entry macro

TSDK_ENTRYPOINT_FN marks a function as the VM entrypoint by placing it in the startup text section and marking it noreturn. 
#include <thru-sdk/c/tn_sdk.h>

TSDK_ENTRYPOINT_FN void
start( void ) {
  tsdk_return( TSDK_SUCCESS );
}

​
Core macros

MacroWhat it does
TSDK_ENTRYPOINT_FNMarks the entrypoint function.
TSDK_SUCCESSCanonical success return code (0UL).
TSDK_ASSERT_OR_REVERT(cond, error_code)Revert immediately if a required condition is false.
TSDK_LOAD(T, src)Safely load a value of type T from potentially unaligned memory.
TSDK_STORE(T, dst, val)Safely store a value of type T to potentially unaligned memory.
TSDK_PARAM_UNUSEDSilence unused-parameter warnings in helper functions.
TSDK_LIKELY and TSDK_UNLIKELYBranch prediction hints.
TSDK_LAYOUT_* and TSDK_SCRATCH_ALLOC_*Helpers for computing and carving out scratch memory regions.

​
Core runtime helpers from tn_sdk.h

HelperPurpose
tsdk_get_txn()Root pointer for transaction reads.
tsdk_get_account_meta(account_idx)Account metadata for a transaction account index.
tsdk_get_account_data_ptr(account_idx)Raw account-data pointer for a transaction account index.
tsdk_get_current_block_ctx()Current block context pointer.
tsdk_get_past_block_ctx(blocks_in_past)Historical block context pointer spaced by TSDK_BLOCK_CTX_VM_SPACING.
tsdk_get_shadow_stack()Shadow stack pointer for CPI and call-depth context.
tsdk_printf(...)Format a string and emit it through tsys_log.
tsdk_return(code)Exit successfully with a return code.
tsdk_revert(code)Exit unsuccessfully with a revert code.

​
Segment and address constants

Most applications do not need to build VM addresses manually, but the SDK exposes the segment constants that back helpers like tsdk_get_txn() and tsdk_get_account_meta():
  • TSDK_SEG_TYPE_READONLY_DATA
  • TSDK_SEG_TYPE_ACCOUNT_METADATA
  • TSDK_SEG_TYPE_ACCOUNT_DATA
  • TSDK_SEG_TYPE_STACK
  • TSDK_SEG_TYPE_HEAP
  • TSDK_SEG_IDX_TXN_DATA
  • TSDK_SEG_IDX_SHADOW_STACK
  • TSDK_SEG_IDX_PROGRAM
  • TSDK_SEG_IDX_BLOCK_CTX
If you are not doing very low-level VM work, prefer the helper functions over manual TSDK_ADDR(...) usage.

​
SHA-256 hashing helpers from tn_sdk_sha256.h

HelperPurpose
tsdk_sha256_init(sha)Initialize a tsdk_sha256_t context for incremental hashing.
tsdk_sha256_append(sha, data, sz)Append sz bytes to the hash context. Returns sha for chaining.
tsdk_sha256_fini(sha, hash)Finalize and write the 32-byte digest to hash.
tsdk_sha256_hash(data, sz, hash)One-shot: hash sz bytes and write the 32-byte digest to hash.
#include <thru-sdk/c/tn_sdk_sha256.h>

tsdk_sha256_t sha[1];
tsdk_sha256_init( sha );
tsdk_sha256_append( sha, data, data_len );
uchar hash[32];
tsdk_sha256_fini( sha, hash );

​
BLS cryptography helpers from tn_crypto.h

The Thru VM machine config includes the with-blst.mk layer automatically. In practice, tn_crypto.h is available when the installed toolchain ships libblst.a and the matching headers.
HelperPurpose
tn_crypto_generate_keypair(pubkey, private_key, seed)Generate a BLS keypair from a seed.
tn_crypto_derive_pubkey(pubkey, private_key)Derive a public key from a private key.
tn_crypto_sign_message(signature, message, message_len, private_key)Sign a message.
tn_crypto_verify_signature(signature, pubkey, message, message_len)Verify a single signature.
tn_crypto_aggregate_signatures(aggregate, sig1, sig2)Aggregate two signatures.
tn_crypto_aggregate_pubkeys(aggregate, pk1, pk2)Aggregate two public keys.
tn_crypto_verify_aggregate(aggregate_sig, aggregate_pk, message, message_len)Verify an aggregate signature.
tn_crypto_serialize_pubkey(serialized, pubkey)Serialize a G1 pubkey to 96-byte uncompressed format.
tn_crypto_deserialize_pubkey(pubkey, serialized)Deserialize from 96-byte uncompressed format.
tn_crypto_serialize_signature(serialized, signature)Serialize a G2 signature to 192-byte uncompressed format.
tn_crypto_deserialize_signature(signature, serialized)Deserialize from 192-byte uncompressed format.
All functions return TN_CRYPTO_SUCCESS (0) on success or a negative error code.

​
RLE helpers from tn_rle.h

Run-length encoding for compact bitset representation.
HelperPurpose
tn_rle_footprint(max_runs)Memory footprint in bytes for an RLE with max_runs.
tn_rle_new(shmem, max_runs)Initialize an RLE structure in pre-allocated memory.
tn_rle_encode(rle, max_runs, bitset, bit_count)Encode a ulong bitset into RLE format.
tn_rle_decode(rle, bitset, max_bits, out_bit_count)Decode RLE back to a ulong bitset.
tn_rle_decode_bytes(rle, bitset, max_bits, out_bit_count)Decode RLE to a byte-oriented bitset.
tn_rle_iter_init(iter, rle)Initialize a memory-efficient iterator over set bits.
tn_rle_iter_next_set(iter, max_bits)Return the next set bit index, or TN_RLE_ITER_DONE.

​
Notes

  • Start with tn_sdk.h unless the task clearly requires lower-level syscall or struct work.
  • Prefer TSDK_LOAD and TSDK_STORE when reading or writing fields out of byte buffers with uncertain alignment.
  • Treat tsdk_return and tsdk_revert as terminal control-flow points, not ordinary function calls.
  • For downstream user code, prefer the installed include path form <thru-sdk/c/…> consistently.
  • The additional headers (tn_sdk_sha256.h, tn_crypto.h, tn_rle.h) are opt-in. Most programs only need tn_sdk.h and tn_sdk_syscall.h.