rialo-cdk 0.1.0

Python CDK for Rialo blockchain - wallet management, transactions, and RPC client

Rialo Python CDK

A comprehensive Python library for interacting with the Rialo blockchain. This package provides wallet management, transaction building, RPC communication, and program deployment capabilities through high-performance native Python bindings to the Rust CDK.

Features

• Wallet Management: Create, load, and manage Rialo wallets with BIP39 mnemonic support
• Transaction Building: Build, sign, and send transactions to the Rialo blockchain
• RPC Client: Communicate with Rialo nodes using JSON-RPC
• Program Deployment: Deploy and invoke programs on the Rialo blockchain
• Cryptographic Operations: Ed25519 signing, verification, and key management
• Multiple Storage Backends: In-memory and file-based wallet storage
• Type Safety: Full type hints and stubs for better development experience

Installation

From PyPI (Recommended)

pip install rialo-cdk

System Requirements

• Python: 3.8 or higher
• Operating System: Windows, macOS, or Linux
• Architecture: x86_64, ARM64

The package includes pre-built wheels for all major platforms, so no Rust toolchain is required for installation.

Quick Start

Basic Usage

from rialo_cdk import (
    generate_keypair,
    Wallet,
    create_wallet_with_mnemonic,
    HttpRpcClient,
    InMemoryWalletProvider,
)

# Generate a keypair and create a wallet
keypair = generate_keypair()
wallet = Wallet("my_wallet", keypair)
print(f"Wallet public key: {wallet.get_public_key_string()}")

# Create wallet with mnemonic for recovery
wallet_with_mnemonic, mnemonic = create_wallet_with_mnemonic("recoverable_wallet")
print(f"Save this mnemonic: {mnemonic}")

# Connect to Rialo devnet
client = HttpRpcClient(get_devnet_url())

# Check wallet balance (requires running node)
# balance = client.get_balance(wallet.get_public_key())
# print(f"Wallet balance: {balance} kelvin")

# Use wallet provider for persistence
provider = InMemoryWalletProvider()
persistent_wallet = provider.create("my_persistent_wallet", "secure_password")

Wallet Management

from rialo_cdk import InMemoryWalletProvider, FileWalletProvider

# In-memory wallet provider (for testing)
provider = InMemoryWalletProvider()
wallet = provider.create("my_wallet", "secure_password")

# File-based wallet provider (for production)
file_provider = FileWalletProvider("/path/to/wallets")
persistent_wallet = file_provider.create("my_wallet", "secure_password")

Building Transactions

from rialo_cdk import TransactionBuilder, rlo_to_kelvin

# Get recent blockhash
recent_blockhash = client.get_latest_blockhash()

# Build a transfer transaction
builder = TransactionBuilder(wallet.get_public_key(), recent_blockhash)
builder.add_transfer_instruction(
    wallet.get_public_key(),
    recipient_pubkey,
    int(rlo_to_kelvin(1.5))  # Transfer 1.5 RLO
)

# Sign and send
signed_tx = builder.sign(wallet)
signature = client.send_transaction(signed_tx)
print(f"Transaction sent: {signature}")

API Reference

Core Types

• PublicKey: Represents a Rialo public key
• Hash: Represents a blockchain hash (blockhash, transaction hash, etc.)
• Signature: Represents an Ed25519 signature
• Wallet: Main wallet interface for key management and signing
• Account: Represents a single account within a wallet

Wallet Providers

• InMemoryWalletProvider: Stores wallets in memory (temporary)
• FileWalletProvider: Stores wallets in encrypted files (persistent)

Transaction Types

• TransactionBuilder: Builds transactions with instructions
• Instruction: Represents a single blockchain instruction
• AccountMeta: Metadata about accounts used in instructions

RPC Client

• HttpRpcClient: JSON-RPC client for communicating with Rialo nodes

Program Management

• ProgramDeployment: Handles program deployment to the blockchain
• ProgramInvocation: Builds program invocation instructions

Running Examples

Setup

Make sure you have completed the development setup above. The examples require the package to be installed in your environment.

# Navigate to the project directory
cd rialo/cdk/rialo-py-cdk

# Activate your virtual environment
source develop_env/bin/activate

# Make sure the package is installed
maturin develop


# Or run individual examples
python examples/01-basic-operations.py
python examples/02-wallet-management.py
python examples/03-transaction-operations.py
python examples/04-airdrop-operations.py
python examples/05-alice-bob-transaction.py

# Legacy examples
python examples/basic_usage.py
python examples/wallet_management.py

Available Examples

The examples/ directory contains comprehensive examples matching the TypeScript CDK:

• 01-basic-operations.py: Core cryptographic operations, wallet creation, and RPC client setup
• 02-wallet-management.py: Advanced wallet provider functionality, mnemonic support, and account operations
• 03-transaction-operations.py: RPC operations, blockchain state queries, and transaction preparation
• 04-airdrop-operations.py: Requesting test tokens, balance checking, and unit conversions
• 05-alice-bob-transaction.py: Complete transfer workflow simulation between two accounts

Legacy examples:

• basic_usage.py: Getting started with keypairs, wallets, and basic operations (legacy format)
• wallet_management.py: Advanced wallet features and security (legacy format)

Troubleshooting Examples

If you get a ModuleNotFoundError: No module named 'rialo_cdk' when running examples:

1. Ensure you're in the correct directory:

   cd rialo/cdk/rialo-py-cdk
   

2. Activate your virtual environment:

   source develop_env/bin/activate
   

3. Install the package in development mode:

   maturin develop
   

4. Verify installation:

   python -c "import rialo_cdk; print('✓ rialo_cdk imported successfully')"
   

5. If still having issues, try a clean rebuild:

   maturin develop --release
   

Network Configuration

from rialo_cdk import get_localnet_url

# Connect to different networks
localhost_client = HttpRpcClient(get_localnet_url())      # Local development

Unit Conversions

from rialo_cdk import rlo_to_kelvin, kelvin_to_rlo, KELVIN_PER_RLO

# Convert between RLO and kelvin (smallest unit)
kelvin_amount = rlo_to_kelvin(5.5)  # Convert 5.5 RLO to kelvin
rlo_amount = kelvin_to_rlo(1000000)  # Convert kelvin back to RLO

print(f"1 RLO = {KELVIN_PER_RLO:,} kelvin")

Error Handling

from rialo_cdk import RialoException

try:
    wallet = await provider.load("nonexistent_wallet", "password")
except RialoException as e:
    print(f"Rialo error: {e}")
except Exception as e:
    print(f"Other error: {e}")

Security Best Practices

1. Password Security: Use strong, unique passwords for wallet encryption
2. Mnemonic Backup: Securely store mnemonic phrases offline
3. Private Key Management: Never log or expose private keys
4. Network Security: Use HTTPS endpoints for RPC communication
5. File Permissions: Restrict access to wallet files in production

Development

For contributors who want to build from source or contribute to the project:

Building from Source

# Clone the repository
git clone https://github.com/SubzeroLabs/rialo
cd rialo/cdk/rialo-py-cdk

# Setup development environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install maturin pytest pytest-asyncio

# Build in development mode
maturin develop

# Run tests
pytest tests/

# Format code
black python/ examples/ tests/
isort python/ examples/ tests/

Requirements for building from source:

• Python 3.8+
• Rust toolchain (latest stable)
• maturin for building Python extensions

Testing

# Run all tests
pytest tests/

# Run specific test file
pytest tests/test_basic.py

# Run with coverage
pytest --cov=rialo_cdk tests/

# Run tests with verbose output
pytest tests/ -v

Dry Run Release Testing

Before publishing to PyPI, you can perform comprehensive release testing to ensure everything works correctly:

1. Pre-Release Validation

# Run all tests with verbose output
pytest tests/ -v

# Run tests with coverage reporting
pytest tests/ --cov=rialo_cdk --cov-report=term-missing

# Install formatting tools (if not already installed)
pip install black isort

# Check code formatting
black --check python/ examples/
isort --check-only python/ examples/

2. Build and Test Wheels Locally

# Build wheels for current platform
maturin build --release --out dist

# Build source distribution
maturin build --sdist --out dist

# Test wheel installation in clean environment
python -m venv test_release_env
source test_release_env/bin/activate  # On Windows: test_release_env\Scripts\activate

# Install from built wheel
pip install dist/rialo_cdk-*.whl

# Test basic functionality
python -c "
import rialo_cdk
print(f'✅ rialo_cdk {rialo_cdk.__version__} installed successfully')
keypair = rialo_cdk.generate_keypair()
wallet = rialo_cdk.Wallet('test', keypair)
print(f'✅ Basic functionality working: {wallet.get_public_key_string()[:16]}...')
"

# Clean up
deactivate
rm -rf test_release_env

License

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

Contributing

Contributions are welcome! Please see the main CONTRIBUTING.md file for guidelines.

Support

• Documentation: docs.rialo.io
• Discord: discord.gg/rialo
• Issues: GitHub Issues

Changelog

0.1.0

• Initial alpha release
• Comprehensive wallet management with BIP39 mnemonic support
• High-performance RPC client implementation
• Complete transaction building and signing capabilities
• Program deployment and invocation support
• Cross-platform pre-built wheels
• Extensive documentation and examples
• Full type safety with Python stubs