# Rialo Python CDK

[![PyPI version](https://badge.fury.io/py/rialo-cdk.svg)](https://badge.fury.io/py/rialo-cdk)
[![Python versions](https://img.shields.io/pypi/pyversions/rialo-cdk.svg)](https://pypi.org/project/rialo-cdk/)
[![License](https://img.shields.io/github/license/subzero-labs/rialo.svg)](https://github.com/SubzeroLabs/rialo/blob/main/LICENSE)

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)

```bash
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

```python
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

```python
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

```python
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.

```bash
# 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:**
   ```bash
   cd rialo/cdk/rialo-py-cdk
   ```

2. **Activate your virtual environment:**
   ```bash
   source develop_env/bin/activate
   ```

3. **Install the package in development mode:**
   ```bash
   maturin develop
   ```

4. **Verify installation:**
   ```bash
   python -c "import rialo_cdk; print('✓ rialo_cdk imported successfully')"
   ```

5. **If still having issues, try a clean rebuild:**
   ```bash
   maturin develop --release
   ```

## Network Configuration

```python
from rialo_cdk import get_localnet_url

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

## Unit Conversions

```python
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

```python
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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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](../../LICENSE) file for details.

## Contributing

Contributions are welcome! Please see the main [CONTRIBUTING.md](../../CONTRIBUTING.md) file for guidelines.

## Support

- **Documentation**: [docs.rialo.io](https://docs.rialo.io/outside/latest/)
- **Discord**: [discord.gg/rialo](https://discord.gg/RialoProtocol)
- **Issues**: [GitHub Issues](https://github.com/SubzeroLabs/rialo/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
