rialo-py-cdk

Python bindings for the Rialo CDK, generated with PyO3 and built via Maturin. The extension wraps rialo-cdk and exposes its full client-side surface — keyring management, transaction building, JSON-RPC communication, program deployment, and TEE secret encryption — as a synchronous Python API. All async Rust operations are bridged internally through a shared Tokio runtime; callers do not use async/await. Requires Python ≥ 3.10 (targets the Python Stable ABI abi3-py310, so a single wheel per platform covers CPython 3.10 and later).

Installation

pip install rialo-py-cdk

Pre-built wheels are published for Linux (x86_64/aarch64), macOS (x86_64/arm64), and Windows. See Building from source if no wheel is available for your platform.

Key public types

Primitive types

Keyring management

Transaction and RPC

Note: Wallet, InMemoryWalletProvider, FileWalletProvider, and Account are retained as deprecated aliases; prefer the Keyring/KeyringProvider names in new code.

Warning: Keypair bytes in the low-level API are always 64 bytes: 32-byte Ed25519 secret key followed by 32-byte public key. Provider methods that accept a secret_key argument take the raw 32-byte secret only. Passing the wrong length raises RialoException at call time.

Usage

Create a keyring and send a transfer

import time
from rialo_py_cdk import (
    InMemoryKeyringProvider,
    HttpRpcClient,
    TransactionBuilder,
    get_devnet_url,
    rlo_to_kelvin,
)

provider = InMemoryKeyringProvider()
keyring, mnemonic = provider.create_with_mnemonic("main", 128, "password")
print("Save mnemonic:", mnemonic)

client = HttpRpcClient(get_devnet_url())
config_hash = client.get_config_hash_prefix()   # required by every transaction

recipient = keyring.get_public_key()            # replace with the real recipient

valid_from = int(time.time() * 1000)
tx_bytes = (
    TransactionBuilder(keyring.get_public_key(), valid_from, config_hash)
    .add_transfer_instruction(keyring.get_public_key(), recipient, int(rlo_to_kelvin(1.0)))
    .sign_with_keyring(keyring)   # signs and serialises; use .build() for unsigned bytes
)
sig = client.send_transaction(tx_bytes)
print("Transaction signature:", sig)            # base58 string

Recover a keyring from a mnemonic

recovered = provider.recover_from_mnemonic("main", mnemonic, "password")
print("Recovered public key:", recovered.get_public_key())

Manage multiple keypairs

Each keyring can hold several derived keypairs. Use derive_keypair to add more at the next available BIP44 index, set_active_keypair to switch between them, and sign_with_keypair to sign with a specific one without switching the active key.

# Derive an additional keypair (index assigned automatically)
info = provider.derive_keypair("main", 1, "password")
print("New keypair pubkey:", info["pubkey_string"])

# Switch the active signing key
keyring.set_active_keypair(1)
print("Now signing with:", keyring.get_public_key_string())

# Sign with a specific keypair without changing the active key
sig_bytes = keyring.sign_with_keypair(message_bytes, 1)

# List all keypairs in the keyring
for kp in keyring.get_keypairs_info():
    print(f"  index={kp['index']}  pubkey={kp['pubkey_string']}")

# Import an existing 32-byte secret key at a custom derivation path
provider.import_secret_key("main", secret_key_bytes, "m/44'/756'/5'", "password")

Deploy a program

from rialo_py_cdk import ProgramDeployment, PyLoaderType

deployment = ProgramDeployment("/path/to/program.so")
deployment.with_loader_type(PyLoaderType.RiscV)   # default is LoaderV4
program_id = deployment.deploy_with_keyring(client, keyring)
print("Deployed program:", program_id)

Invoke a program

from rialo_py_cdk import ProgramInvocation

invocation = ProgramInvocation(program_id)
invocation.add_writable_account(state_account_pubkey)
invocation.add_readonly_account(config_account_pubkey)
invocation.with_data(instruction_data_bytes)

sig = invocation.invoke_with_keyring(client, keyring)
print("Invocation signature:", sig)

# Build an instruction without submitting, e.g. to include in a larger transaction
ix = invocation.into_instruction()

Encrypt a secret for TEE execution

from rialo_py_cdk import encrypt_secret, PublicKey

sk_pub = PublicKey.from_string(client.get_secret_sharing_pubkey())
ciphertext = encrypt_secret("Bearer sk-…", keyring.get_public_key(), sk_pub)
# Pass ciphertext in your instruction data; the TEE program decrypts it.

Configure the network

Config lets you persist the active network URL without threading a client everywhere. It defaults to localnet.

from rialo_py_cdk import Config

cfg = Config("devnet")          # sets rpc_url automatically
print(cfg.rpc_url)              # https://api.devnet.rialo.xyz
cfg.set_network("testnet")      # switch network; rpc_url updates
print(cfg.network)              # "testnet" (read-only)

d = cfg.to_dict()
cfg2 = Config.from_dict(d)

Subscription workflows (REX)

subscription = client.get_subscription(subscriber_pubkey_str, nonce)
print("Topic:", subscription["topic"])

triggered = client.get_triggered_transactions(subscription_account_str, 10)
for tx in triggered:
    print(f"sig={tx['signature']}  block={tx['block_number']}")

Workflow lineage

lineage = client.get_workflow_lineage("5UfDuX...")
# lineage["nodes"] contains the DAG of related transactions.

Typed RPC client

rialo_py_cdk.generated ships a fully typed RialoRPCClient that wraps the PyO3 HttpRpcClient with dataclass return types — useful when you want IDE autocompletion and static analysis with mypy/pyright.

from rialo_py_cdk import HttpRpcClient, get_devnet_url
from rialo_py_cdk.generated import RialoRPCClient
from rialo_py_cdk.generated.types import AccountInfo, EpochInfo

raw_client = HttpRpcClient(get_devnet_url())
client = RialoRPCClient(raw_client)

# Return types are dataclasses, not raw dicts
epoch: EpochInfo = client.get_epoch_info()
print(f"Epoch {epoch.epoch}, slot {epoch.absolute_slot}")

account: AccountInfo = client.get_account_info(pubkey_string)
print(f"Balance: {account.kelvin} kelvin, owner: {account.owner}")

Tip: The underlying HttpRpcClient is still accessible via client._client when you need methods not yet promoted to the typed layer.

Error handling

All CDK errors surface as RialoException. The .code attribute carries the numeric error code for programmatic handling.

from rialo_py_cdk import RialoException

try:
    sig = client.send_transaction(tx_bytes)
except RialoException as exc:
    if exc.code == 1001:                    # example: insufficient funds
        print("Funding required before sending")
    else:
        raise                               # re-raise unexpected errors

Tip: exc.message contains a human-readable description with the error category and code, e.g. [Transaction:1001] insufficient funds.

Error code ranges

RPC reference

Tip: Use RialoRPCClient from rialo_py_cdk.generated to get typed dataclass return values instead of raw dict/list from HttpRpcClient.

Low-level utilities

The module exposes a stateless, provider-free API for scripts and tools:

airdrop_rlo is a convenience wrapper that converts RLO to kelvin before calling request_airdrop. Prefer it over calling request_airdrop with a manual conversion.

from rialo_py_cdk import airdrop_rlo, HttpRpcClient, get_devnet_url

client = HttpRpcClient(get_devnet_url())
sig = airdrop_rlo(client, pubkey, 2.5)    # request 2.5 RLO; devnet/testnet only
print("Airdrop:", sig)

Network helpers

from rialo_py_cdk import (
    get_localnet_url,    # "http://127.0.0.1:4104"
    get_devnet_url,      # "https://api.devnet.rialo.xyz"
    get_testnet_url,     # "https://api.testnet.rialo.xyz"
    get_mainnet_url,     # "https://api.mainnet.rialo.xyz"
    get_rpc_url_for_network,
    list_available_networks,
)

url = get_rpc_url_for_network("devnet")
networks = list_available_networks()   # ["localnet", "devnet", "testnet", "mainnet"]

Constants

from rialo_py_cdk import KELVIN_PER_RLO, FILE_STORAGE_AVAILABLE

# Currency: 1 RLO = 1_000_000_000 kelvin
kelvin = int(1.5 * KELVIN_PER_RLO)     # 1_500_000_000

# True when the wheel was compiled with the file-storage feature
if FILE_STORAGE_AVAILABLE:
    from rialo_py_cdk import FileKeyringProvider

Feature flags

All features are enabled by default in the shipped wheel. They can be toggled on the underlying rialo-cdk dependency when building from source with default-features = false.

FILE_STORAGE_AVAILABLE is exposed as a module-level boolean constant reflecting whether file-storage was compiled in.

Building from source

cd developer-frameworks/cdk/rialo-py-cdk
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"     # triggers maturin via PEP 517; requires Rust stable
pytest tests/

For faster incremental Rust rebuilds use maturin develop (included in the [dev] extras).

Caveats

• config_hash_prefix — every TransactionBuilder requires a config hash prefix fetched live from client.get_config_hash_prefix(). There is no in-process example constant that live nodes will accept.

• Currency units — the smallest unit is kelvin; 1 RLO = KELVIN_PER_RLO (1 000 000 000) kelvin. All RPC amounts are in kelvin. Use rlo_to_kelvin and kelvin_to_rlo to convert.

• Derivation path — Rialo uses BIP44 coin type 756 (m/44'/756'/{index}'). Keys derived on other coin types are not compatible.

• Synchronous API — all calls block the calling thread. Wrap with asyncio.get_event_loop().run_in_executor or use a thread pool if you need to drive multiple operations concurrently from an async Python application.

• Keypair bytes — keypair bytes in the low-level API are 64 bytes (secret ++ public). Provider methods that accept secret_key take the raw 32-byte secret only. Passing the wrong length raises RialoException.

• wallet module — Wallet, InMemoryWalletProvider, FileWalletProvider, and Account are deprecated aliases retained for backward compatibility. Prefer Keyring/KeyringProvider names in new code.

See also

• rialo-cdk — the underlying Rust crate; source of truth for types and error codes
• rialo-ts-cdk — TypeScript CDK with equivalent API surface
• developer-frameworks/cdk/rialo-py-cdk/pyproject.toml — Python package metadata and Maturin build configuration
• docs/developer/ — contributor setup guide including Rust toolchain requirements