rialo-py-cdk 0.3.0a0

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-py-cdk

System Requirements

• Python: 3.9 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_py_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_py_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

import time
from rialo_py_cdk import TransactionBuilder, rlo_to_kelvin

# Get current timestamp for transaction validity
valid_from = int(time.time() * 1000)  # Current time in milliseconds

# Build a transfer transaction
builder = TransactionBuilder(wallet.get_public_key(), valid_from)
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

# Set up venv and install (one-time)
python3 -m venv .venv
source .venv/bin/activate

# Build and install the package using Maturin (PEP 517)
pip install -e ".[dev]"

# 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

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

Troubleshooting Examples

If you get ModuleNotFoundError: No module named 'rialo_py_cdk':

cd rialo/cdk/rialo-py-cdk
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
python -c "import rialo_py_cdk; print('OK')"

Network Configuration

from rialo_py_cdk import get_localnet_url

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

Unit Conversions

from rialo_py_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_py_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

git clone https://github.com/SubzeroLabs/rialo
cd rialo/cdk/rialo-py-cdk

python3 -m venv .venv
source .venv/bin/activate

# pip install builds the Rust extension automatically via PEP 517
# (maturin is auto-installed from [build-system].requires in pyproject.toml).
pip install -e ".[dev]"

pytest tests/

Requirements:

• Python 3.9+
• Rust toolchain (latest stable)

Note: pip install -e . triggers a full Rust build via maturin (PEP 517). No separate maturin install is needed. For faster rebuilds after editing Rust code, use maturin develop (included in [dev] deps).

Testing

pytest tests/                      # all tests
pytest tests/test_basic.py         # specific file
pytest tests/ -v                   # verbose
pytest --cov=rialo_py_cdk tests/      # with coverage

Build Wheel Locally

# PEP 517: builds a release wheel (maturin auto-installed)
pip wheel . --wheel-dir target/wheels

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

• 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