# Rialo Python CDK

[![PyPI version](https://badge.fury.io/py/rialo-py-cdk.svg)](https://badge.fury.io/py/rialo-py-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-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

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

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

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

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

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

```python
from rialo_py_cdk import get_localnet_url

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

## Unit Conversions

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

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

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

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

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

## Contributing

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

## Support

- **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
