soma-sdk

Python SDK for interacting with the SOMA network. Built with PyO3 and Maturin, providing native-speed bindings to the Rust SDK.

Install

pip install soma-sdk

Or with uv:

uv add soma-sdk

Requires Python >= 3.10.

Quick Start

import asyncio
from soma_sdk import SomaClient, Keypair

async def main():
    # Connect using a chain preset
    client = await SomaClient(chain="testnet")   # or chain="localnet"

    # Generate a keypair and fund it
    keypair = Keypair.generate()
    await client.request_faucet(keypair.address())

    # Check balance (returned as SOMA float)
    balance = await client.get_balance(keypair.address())
    print(f"Balance: {balance:.2f} SOMA")

    # Query network state
    state = await client.get_latest_system_state()
    print(f"Epoch: {state.epoch}, Validators: {len(state.validators.validators)}")

asyncio.run(main())

Classes

Keypair

Ed25519 keypair for signing SOMA transactions.

# Generate a new random keypair
keypair = Keypair.generate()

# Restore from a secret key (hex string or bytes)
keypair = Keypair.from_secret_key("0x...")

# Restore from a BIP-39 mnemonic
keypair = Keypair.from_mnemonic("word1 word2 ...")

keypair.address()        # SOMA address (hex string — addresses use hex)
keypair.to_secret_key()  # Export secret key (hex string)
keypair.sign(tx_bytes)   # Sign raw transaction data bytes

SomaClient

The main client for querying chain state, building transactions, and executing them via gRPC.

# Named chain presets (recommended)
client = await SomaClient(chain="testnet")    # auto-configures RPC + faucet URLs
client = await SomaClient(chain="localnet")   # auto-configures RPC + faucet + admin + scoring

# Explicit URLs
client = await SomaClient("https://fullnode.testnet.soma.org", faucet_url="https://faucet.testnet.soma.org")

# Override scoring_url with any chain preset
client = await SomaClient(chain="testnet", scoring_url="http://my-scorer:9124")

Chain presets:

• "testnet" — https://fullnode.testnet.soma.org + faucet
• "localnet" — http://127.0.0.1:9000 + faucet, admin, scoring

Note: chain and rpc_url/faucet_url cannot be combined (raises ValueError). scoring_url is always configurable.

Chain & Node Info

Objects & State

object_type can be: "coin", "staked_soma", "target", "submission", "system_state".

Targets

Checkpoints

Transactions

Scoring (requires scoring_url)

Faucet (requires faucet_url)

Proxy Fetch (via fullnode)

Epoch Helpers

Static Utilities

SomaClient.to_shannons(1.5)                # 1_500_000_000
SomaClient.to_soma(1_500_000_000)           # 1.5
SomaClient.commitment(data)                 # Blake2b-256 Base58 digest
SomaClient.encrypt_weights(data)            # (encrypted_bytes, key_base58)
SomaClient.decrypt_weights(data, key)       # decrypted bytes (key: bytes or Base58 string)

High-Level Convenience Methods

These methods handle building, signing, and executing in one call. Amounts are in SOMA (float), not shannons.

# Transfer coins
await client.transfer_coin(signer=keypair, recipient="0xADDR", amount=0.5)

# Multi-recipient payment
await client.pay_coins(signer=keypair, recipients=["0xA", "0xB"], amounts=[0.25, 0.25])

# Stake with a validator
await client.add_stake(signer=keypair, validator="0xVALIDATOR", amount=10.0)

# Register a model (commit step — publishes manifest + commitments)
await client.commit_model(
    signer=keypair,
    weights_url="https://storage.example.com/weights.safetensors",
    encrypted_weights=encrypted_bytes,
    decryption_key=key_base58,
    embedding=[0.1, 0.2, ...],
    commission_rate=1000,          # 10%
    stake_amount=10.0,             # SOMA — optional, defaults to minimum
)

# Reveal model (next epoch — provides decryption key + embedding)
await client.reveal_model(
    signer=keypair,
    model_id=model_id,
    decryption_key=key_base58,
    embedding=[0.1, 0.2, ...],
)

# Submit data to a target
await client.submit_data(
    signer=keypair,
    target_id="0xTARGET",
    data=raw_bytes,
    data_url="https://storage.example.com/data.bin",
    model_id="0xMODEL",
    embedding=[0.1, 0.2, ...],
    distance_score=0.42,
    loss_score=[0.1, 0.2, ...],
)

# Claim rewards
await client.claim_rewards(signer=keypair, target_id="0xTARGET")

WalletContext

Manages keys from a local wallet config file (e.g. ~/.soma/client.yaml). Useful for CLI-style workflows.

wallet = WalletContext("/path/to/client.yaml")

Building from Source

Requires Rust and Python >= 3.10.

# Install maturin
pip install maturin

# Development build (editable install)
cd python-sdk
maturin develop

# Release build
maturin build --release

License

Apache-2.0