RustChain Client

A Rust HTTP client library for interacting with RustChain node APIs. Provides easy access to health checks, miner information, epochs, balances, and network statistics.

Features

• ✅ Async/Await Support - Built on tokio for non-blocking I/O
• ✅ Type-Safe API - Strongly typed responses with serde
• ✅ Error Handling - Comprehensive error types with thiserror
• ✅ Retry Logic - Automatic retry with exponential backoff
• ✅ Timeout Management - Configurable request timeouts
• ✅ Full API Coverage - Health, miners, epochs, balances, transactions, network stats

Installation

Add this to your Cargo.toml:

[dependencies]
rustchain-client = "0.1.0"
tokio = { version = "1", features = ["full"] }

Quick Start

use rustchain_client::{RustChainClient, ClientConfig};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create client with default config
    let client = RustChainClient::new();
    
    // Check node health
    let health = client.health().await?;
    println!("Node status: {}", if health.healthy { "Online" } else { "Offline" });
    println!("Block height: {}", health.block_height);
    println!("Connected peers: {}", health.peer_count);
    
    // Get balance for an address
    let balance = client.get_balance("RTC1234567890").await?;
    println!("Available: {} RTC", balance.available);
    println!("Locked: {} RTC", balance.locked);
    println!("Total: {} RTC", balance.total);
    
    // Get current epoch info
    let epoch = client.get_epoch(None).await?;
    println!("Current epoch: {}", epoch.epoch);
    println!("Miners in epoch: {}", epoch.miner_count);
    
    // Get network statistics
    let stats = client.get_network_stats().await?;
    println!("Network hash rate: {} H/s", stats.network_hash_rate);
    println!("Current price: ${}", stats.price_usd);
    
    Ok(())
}

Advanced Usage

Custom Configuration

use rustchain_client::{RustChainClient, ClientConfig};

let config = ClientConfig {
    base_url: "https://custom-node.rustchain.io".to_string(),
    timeout_secs: 60,
    max_retries: 5,
};

let client = RustChainClient::with_config(config);

List All Miners

let miners = client.list_miners().await?;
for miner in miners {
    println!("Miner: {} | Blocks: {} | Rewards: {} RTC", 
             miner.address, miner.blocks_mined, miner.total_rewards);
}

Get Transaction History

let transactions = client.get_transactions("RTC1234567890", Some(10)).await?;
for tx in transactions {
    println!("Tx: {} | From: {} | To: {} | Amount: {} RTC",
             tx.hash, tx.from, tx.to, tx.amount);
}

Error Handling

use rustchain_client::{RustChainClient, RustChainError};

let client = RustChainClient::new();

match client.get_balance("INVALID_ADDRESS").await {
    Ok(balance) => println!("Balance: {} RTC", balance.total),
    Err(RustChainError::AddressNotFound(addr)) => {
        eprintln!("Address {} not found on network", addr);
    }
    Err(RustChainError::HttpError(e)) => {
        eprintln!("HTTP error: {}", e);
    }
    Err(e) => {
        eprintln!("Other error: {}", e);
    }
}

API Reference

Core Methods

Method	Description	Returns
health()	Check node health status	HealthStatus
get_miner(address)	Get specific miner info	MinerInfo
list_miners()	List all active miners	Vec<MinerInfo>
get_epoch(num)	Get epoch information	EpochInfo
get_balance(address)	Get address balance	Balance
get_transactions(address, limit)	Get transaction history	Vec<Transaction>
get_transaction(hash)	Get specific transaction	Transaction
get_network_stats()	Get network statistics	NetworkStats
get_block_height()	Get current block height	u64
address_exists(address)	Check if address exists	bool

Data Types

• HealthStatus: Node health, block height, peer count, version
• MinerInfo: Address, blocks mined, hash rate, rewards, status
• EpochInfo: Epoch number, timestamps, miner count, block count
• Balance: Address, available/locked/total balances
• Transaction: Hash, from/to, amount, fee, confirmations
• NetworkStats: Difficulty, hash rate, supply, price, volume

Configuration

Default configuration:

ClientConfig {
    base_url: "https://api.rustchain.io",
    timeout_secs: 30,
    max_retries: 3,
}

Error Handling

The library uses a custom error type RustChainError with variants for:

• HTTP request failures
• Invalid API responses
• Node health issues
• Address not found
• Serialization errors
• API version mismatches

Testing

Run the test suite:

cargo test

Examples

See the examples/ directory for complete working examples:

• examples/basic.rs - Basic usage demonstration
• examples/miner_monitor.rs - Miner monitoring script
• examples/balance_checker.rs - Multi-address balance checker

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Built for the RustChain ecosystem
• Part of the RustChain bounty program
• Made with ❤️ by the Rust community

Support

• Documentation: https://docs.rs/rustchain-client
• Issues: https://github.com/hauenzo/rustchain-client/issues
• RustChain: https://rustchain.io