tfchain_client

What this is

A Rust client library for interacting with the Ledger Chain blockchain infrastructure and the ThreeFold Grid. It provides modules for direct blockchain queries (twins, farms, nodes, balances) and Grid Proxy API access with optional Redis caching. A tfchain CLI binary is also provided for running Rhai scripts against the Ledger Chain.

What this repository contains

• src/tfchain/ — Ledger Chain blockchain client with dynamic metadata support
• src/explorer/ — Grid Explorer API client with optional Redis caching
• Examples for mainnet and explorer usage
• scripts/install.sh — Quick install script for the tfchain CLI binary

Role in the stack

The Ledger Chain client provides programmatic access to the blockchain layer that underpins the ThreeFold Grid. It is used by other components to query twins, farms, nodes, balances, and to interact with the Grid Proxy API for node discovery and pricing.

Relation to ThreeFold

This technology is used within the ThreeFold ecosystem and was first deployed on the ThreeFold Grid. The component itself is designed as reusable infrastructure technology and should be understood by its technical function first, independent of any specific deployment.

Ownership

This repository is owned and maintained by TF-Tech NV, a Belgian company responsible for the development and maintenance of this technology.

License

This project is licensed under the Apache License 2.0 — see the LICENSE file for details.

---

Install Binary

Quick Install (recommended)

curl -sSL https://forge.ourworld.tf/geomind_code/tfchain_client/raw/branch/main/scripts/install.sh | bash

Usage

# Run a Rhai script
tfchain script.rhai

# Show help
tfchain --help

Or call the Rhai script directly — it has a shebang on top.

Modules

This library provides two main modules:

Module	Description
tfchain	Ledger Chain blockchain client with dynamic metadata support
explorer	Grid Explorer API client with optional Redis caching

Quick Start

Ledger Chain Client

Query the blockchain directly for twins, farms, nodes, and balances:

use mycelium_tfchain_client::{Client, KeyPair, KeyType};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let keypair = KeyPair::from_phrase(KeyType::Sr25519, "your mnemonic here", None)?;
    let client = Client::new("wss://tfchain.grid.tf:443").await?;

    if let Some(info) = client.get_balance(&keypair.account_id()).await? {
        println!("Balance: {} TFT", info.free as f64 / 10_000_000.0);
    }

    Ok(())
}

Explorer Client

Query the Grid Proxy API for nodes, farms, and grid statistics:

use mycelium_tfchain_client::explorer::GridExplorerBuilder;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let explorer = GridExplorerBuilder::new().mainnet().build()?;

    let stats = explorer.get_stats().await?;
    println!("Grid has {} nodes", stats.nodes);

    // Find nodes for a VM with 4 cores, 8GB RAM, 100GB disk
    let nodes = explorer.find_nodes_for_vm(4, 8, 100, Some(5)).await?;
    for node in nodes {
        println!("Node {} - ${:.4}/hr", node.id, node.price_usd);
    }

    Ok(())
}

Examples

Run the examples:

# Ledger Chain client example (requires TFCHAIN_SECRET env var)
cargo run --example mainnet

# Explorer client examples
cargo run --example tfgrid3-explorer-client
cargo run --example tfgrid3-explorer-client-highlevel

Network Endpoints

Ledger Chain (WebSocket)

Network	URL
Mainnet	wss://tfchain.grid.tf:443
Testnet	wss://tfchain.test.grid.tf:443
Devnet	wss://tfchain.dev.grid.tf:443

Grid Proxy (HTTP)

Network	URL
Mainnet	https://gridproxy.grid.tf
Testnet	https://gridproxy.test.grid.tf
Devnet	https://gridproxy.dev.grid.tf

Installation

Add to your Cargo.toml:

[dependencies]
mycelium_tfchain_client = "0.1"
tokio = { version = "1", features = ["rt-multi-thread", "macros"] }

Environment

Make sure your key is in the environment:

export TFCHAIN_KEY=...