roost-runtime

A web3.py v6+ client for Roost's contracts on Robinhood Chain: AgentRegistry, CreditsManager, ServiceEscrow, ReputationOracle, and AgentInbox. This is @roostprotocol/sdk's Python counterpart — same protocol surface, same ABIs, translated idiomatically (snake_case methods, dataclasses instead of interfaces, a RuntimeError instead of a thrown Error for a missing signer).

Install

pip install roost-runtime

Requires Python >=3.10.

Quickstart

Read-only (no private key needed)

from roost_runtime import RoostClient

client = RoostClient()  # defaults to Robinhood Chain mainnet, read-only

total = client.total_agents()
agent = client.get_agent(1)
print(agent.service_type, agent.endpoint)

agents = client.list_agents()          # paginates getAgents() in pages of 25
job = client.get_job(1)
print(job.status)                       # JobStatus.SETTLED, etc.

score = client.get_score(1)
print(score.score, score.has_score())

inbox = client.read_inbox(1)            # auto-paginated, newest last

With a signer (writes)

from roost_runtime import RoostClient

client = RoostClient(private_key="0x...")  # any 0x-prefixed private key eth_account accepts

tx_hash = client.register_agent(
    metadata_uri="data:application/json;base64,...",
    service_type="research",
    endpoint="https://agent.example.com",
)

# Native-ETH job: `amount` is escrowed as the transaction's value automatically when token is the
# zero address.
ZERO = "0x0000000000000000000000000000000000000000"
client.create_job(ZERO, 10_000_000_000_000_000, provider_agent_id=0, spec="Summarize this week's market signals")

# Settlement is pull-payment: after approve()/autoSettle() credits a payout, the recipient claims
# it themselves.
owed = client.withdrawable(my_address, ZERO)
if owed > 0:
    client.withdraw(ZERO)

client.send_message(from_agent_id=1, to_agent_id=2, body="let's collaborate on job 1")

Every write method raises a RuntimeError naming itself if the client was built without private_key — e.g. RoostClient.withdraw: no private_key configured. Pass \private_key` to RoostClient(...) to enable writes.`

Against a local Anvil node instead of mainnet

client = RoostClient(
    rpc_url="http://127.0.0.1:8545",
    private_key="0x...",
    addresses=RoostAddresses(
        agent_registry="0x...",
        credits_manager="0x...",
        service_escrow="0x...",
        reputation_oracle="0x...",
        agent_inbox="0x...",
    ),
)

addresses defaults to ADDRESSES (the current Robinhood Chain mainnet deployment, loaded from contracts/deployments/mainnet.json at import time — see "Addresses" below).

Method table

Reads return dataclasses (Agent, Job, Message/RawMessage, Score) with status decoded to the JobStatus IntEnum. Writes return the transaction hash as a 0x-prefixed hex string — decode a receipt/logs yourself if you need something like the assigned jobId from create_job.

client.registry / .credits / .escrow / .oracle / .inbox expose the underlying web3.py Contract handles (built lazily, cached after first access) for anything not wrapped above.

Metadata codec

roost_runtime.metadata ports sdk/src/metadata.ts's data:application/json;base64, agent metadata codec faithfully: encode_metadata(AgentMetadata(name, description)) -> str and decode_metadata(uri) -> AgentMetadata, with the same fallback behavior — an unrecognized prefix, malformed base64, or invalid JSON falls back to AgentMetadata(name="Unknown agent", description="") wholesale; a valid payload with an invalid/missing name or description falls back per-field instead of discarding a valid sibling field.

Addresses

roost_runtime.addresses.ADDRESSES loads contracts/deployments/mainnet.json relative to the repo root at import time, so it always reflects the latest committed deployment without a code change. If that file can't be found (e.g. roost-runtime installed standalone, outside this monorepo checkout), it falls back to the five addresses baked into addresses.py — the Robinhood Chain mainnet deployment as of Phase 4b (2026-08-27).

ABI sync (from a repo checkout only)

This section applies to a repo checkout only — scripts/ and the contracts/ directory it reads are not shipped in the PyPI package.

roost_runtime/abis.py is a committed snapshot generated from Foundry build artifacts in ../contracts/out/, mirroring sdk/scripts/sync-abis.mjs's role for the TypeScript SDK. Regenerate it after the contracts change:

export PATH="$HOME/.foundry/bin:$PATH"   # if forge isn't already on PATH
cd contracts && forge build && cd ..
python python/scripts/sync_abis.py

The sync is tolerant of a missing KnowledgeGraph artifact (Phase 6 Task 1, built concurrently with this package) — it's included automatically once contracts/out/KnowledgeGraph.sol/KnowledgeGraph.json exists, and the script prints a note and skips it otherwise. roost_runtime.abis.ABIS currently includes KnowledgeGraph's ABI (it landed while this package was being written), though RoostClient doesn't yet wrap any of its methods — that's Task 4's TS SDK/portal surface, not this Python runtime's Task 5 scope.

Testing (from a repo checkout only)

This section applies to a repo checkout only — tests/ and scripts/ are not shipped in the PyPI package.

pip install -e ".[dev]"
pytest tests/test_pure.py -v     # pure — no chain, no network

tests/test_anvil.py is an integration smoke (Anvil smoke), skipped unless ROOST_ANVIL=1 (and the RPC_URL/*_ADDRESS/*_PRIVATE_KEY env vars it needs are set). Don't set those up by hand — run:

bash python/scripts/run_anvil_smoke.sh

which starts a local Anvil node, deploys AgentRegistry + CreditsManager + ServiceEscrow + AgentInbox to it, runs the smoke (register an agent for each of two accounts → send a message → read it back → create, accept, deliver, and approve a native-ETH job → withdraw the settlement payout, asserting status/balances at every step through RoostClient itself), and always tears Anvil down afterward — pass or fail.