Skip to content

README.md

Latest commit

 

History

History
170 lines (124 loc) · 3.58 KB

README.md

File metadata and controls

170 lines (124 loc) · 3.58 KB

RustChain Python SDK

A Python SDK for interacting with RustChain nodes. Install via pip install rustchain.

Features

  • 🚀 Async-first with synchronous fallbacks
  • 📝 Full type hints for IDE autocomplete
  • ⚡ httpx for modern HTTP handling
  • 🛡️ Pydantic models for data validation
  • 🔧 CLI tool included (rustchain command)

Installation

pip install rustchain

Quick Start

Async Usage

import asyncio
import rustchain

async def main():
    # Initialize client
    client = rustchain.RustChainClient()
    
    # Check node health
    health = await client.health()
    print(f"Node version: {health.version}")
    print(f"Uptime: {health.uptime_s}s")
    
    # Get epoch info
    epoch = await client.epoch()
    print(f"Current epoch: {epoch.epoch}")
    print(f"Enrolled miners: {epoch.enrolled_miners}")
    
    # List active miners
    miners = await client.miners()
    for miner in miners.value[:5]:
        print(f"  - {miner.miner} ({miner.hardware_type})")
    
    # Check wallet balance
    balance = await client.balance("your-wallet-id")
    print(f"Balance: {balance.balance} RTC")

asyncio.run(main())

Synchronous Usage

import rustchain

# All async methods have sync equivalents
client = rustchain.RustChainClient()

health = client.health_sync()
epoch = client.epoch_sync()
miners = client.miners_sync()
balance = client.balance_sync("your-wallet-id")

API Reference

Client

from rustchain import RustChainClient

client = RustChainClient(
    base_url="https://50.28.86.131",  # Default node
    timeout=30.0,                      # Request timeout
    verify_ssl=False,                  # For self-signed certs
)

Methods

Method Description Async Sync
health() Check node health ✅ health_sync()
epoch() Get current epoch info ✅ epoch_sync()
miners() List active miners ✅ miners_sync()
balance(wallet_id) Check wallet balance ✅ balance_sync()
transfer(from, to, amount, sig) Execute transfer ✅ transfer_sync()
attestation_status(miner_id) Check attestation ✅ attestation_status_sync()

Explorer API

# Access via client.explorer
blocks = await client.explorer.blocks(limit=10)
transactions = await client.explorer.transactions(limit=10)

# Sync versions
blocks = client.explorer.blocks_sync(limit=10)
txs = client.explorer.transactions_sync(limit=10)

CLI Usage

The SDK includes a command-line tool:

# Check node health
rustchain health

# Get epoch info
rustchain epoch

# List active miners
rustchain miners --limit 5

# Check wallet balance
rustchain balance <wallet-address>

# View recent blocks
rustchain blocks --limit 5

# View recent transactions
rustchain transactions

# JSON output
rustchain health --json
rustchain miners -j

Error Handling

from rustchain import RustChainClient
from rustchain.exceptions import (
    RustChainError,
    RustChainConnectionError,
    RustChainAPIError,
    RustChainValidationError,
)

client = RustChainClient()

try:
    balance = await client.balance("invalid")
except RustChainValidationError as e:
    print(f"Validation error: {e}")
except RustChainConnectionError as e:
    print(f"Connection failed: {e}")
except RustChainAPIError as e:
    print(f"API error (HTTP {e.status_code}): {e}")

Development

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run tests with coverage
pytest --cov=rustchain

License

MIT License