thru-base

Use thru-base when you need the shared Rust building blocks behind Thru accounts, transactions, address handling, and proof workflows.

Install

cargo add thru-base

When to use it

Choose this crate when you want to:

• Generate or load Thru keypairs and validate Thru-formatted addresses and signatures.
• Build raw Thru transactions in Rust, including transfers, account operations, token flows, uploader flows, and program-management instructions.
• Derive deterministic program, uploader, and manager account addresses.
• Encode, decode, or inspect state proofs and related proof metadata.
• Reuse shared request and filter types around Rust-side RPC tooling.

Choose another crate when

• You want to call Thru gRPC services directly: use thru-grpc-client.
• You want a more ergonomic RPC client instead of raw primitives plus generated service types: use a higher-level wrapper such as thru-client.

Entry points

Module or export	What it provides
thru_base::tn_tools::{KeyPair, Pubkey, Signature}	Key generation, private-key loading, Thru address validation, and signature encoding helpers.
thru_base::TransactionBuilder and thru_base::txn_tools	Transaction builders plus program constants such as EOA_PROGRAM, SYSTEM_PROGRAM, TOKEN_PROGRAM, UPLOADER_PROGRAM, and more.
thru_base::{StateProof, StateProofBody, StateProofHeader, StateProofType}	Rust-side state proof creation, serialization, and parsing helpers.
thru_base::{derive_manager_program_accounts, derive_uploader_program_accounts}	Deterministic derived-account helpers for common program flows.
thru_base::tn_public_address exports	Encode and decode Thru addresses and create program-defined addresses.
thru_base::rpc_types	Shared Rust request-side types such as GetProgramAccountsConfig, ProgramAccountFilter, and MakeStateProofConfig.

Start here

This crate is most useful at the edges of a Rust integration: parse keys, build a transaction, sign it, then hand the bytes to a client layer.

use thru_base::tn_tools::{KeyPair, Pubkey};
use thru_base::txn_tools::EOA_PROGRAM;
use thru_base::TransactionBuilder;

fn build_transfer(
    from_private_key_hex: &str,
    to: &str,
    amount: u64,
    nonce: u64,
    start_slot: u64,
) -> Result<Vec<u8>, Box<dyn std::error::Error>> {
    let from = KeyPair::from_hex_private_key("sender", from_private_key_hex)?;
    let to = Pubkey::new(to.to_string())?;

    let mut tx = TransactionBuilder::build_transfer(
        from.public_key,
        EOA_PROGRAM,
        to.to_bytes()?,
        amount,
        1,
        nonce,
        start_slot,
    )?;

    tx.sign(&from.private_key)?;
    Ok(tx.to_wire())
}

Common workflows

Task	Main entrypoints
Parse or validate account addresses	Pubkey::new, Pubkey::from_hex, Pubkey::to_bytes, Pubkey::from_bytes
Parse or format signatures	Signature::new, Signature::to_bytes, Signature::from_bytes
Create or load a signer	KeyPair::generate, KeyPair::from_hex_private_key
Build basic transactions	TransactionBuilder::build_transfer, build_create_account, build_resize_account, build_write_data
Build program-management flows	build_manager_create, build_manager_upgrade, build_manager_set_pause, build_manager_set_authority
Build token and wrapped-token flows	build_token_initialize_mint, build_token_transfer, build_wthru_deposit, build_wthru_withdraw
Work with proofs	StateProof, StateProofHeader, StateProofBody, MakeStateProofConfig, ProofType
Derive deterministic accounts	derive_program_address, derive_manager_program_accounts, derive_uploader_program_accounts

Notes for agents

• Pubkey and Signature are string-backed wrapper types for Thru-formatted ta... addresses and ts... signatures, not raw byte arrays.
• The builder methods usually expect raw [u8; 32] public keys for account arguments, so convert Pubkey wrappers with to_bytes() when needed.
• thru-base is broad: if your task is “call node RPC and read chain data,” this crate alone is probably not enough without a client layer.
• build_wthru_deposit builds only the deposit instruction: the wrapped Thru program mints the vault’s unaccounted native balance delta to the destination token account and does not transfer the funds itself. The native transfer into the vault must be in the same transaction as the deposit instruction (for example batched through the multicall program); submitted separately, the delta is unattributed on-chain and any caller can be credited it. See the wrapped Thru CLI reference.