Architecture.

Where key material stops, and where to read the rest.

System map

One page, the whole system: the stack from agent to pool, the three layers, a deal start to finish, how an offer becomes five notes, who sees what, and what the system does and does not claim.

Know the boundary

agents→mcp-server→sdk/py→sdk/rs→Starknet

You write agents; everything after it is Erebus infrastructure. Key material never crosses one arrow — an enforced boundary at sdk/rs, not a convention. The policy engine decides what to do and never touches keys.

The CLI protocol

erebus-cli reads one JSON request on stdin and writes one envelope on stdout. Key paths cross the boundary; key values never do.

request

echo '{"method":"doctor","params":{"config":{...}}}' | erebus-cli

response

{"ok": true, "protocol": 4, "result": {"ready": true, "checks": [...]}}

protocol is the contract version. A consumer should refuse a mismatch by name rather than failing on a changed shape later — erebus-sdk does this on every call, and the MCP server handshakes at startup.

version, generate_pool_key, doctor, balance, allowance, approve, shield, open_channel, propose_offer, counter_offer, read_channel_state, accept_and_settle, reconcile, resume_operation, rebuild_state, grant_viewing_key, reveal

All except version and generate_pool_key take a config object. Every chain write also takes operation_id.

Build from source

clone

git clone https://github.com/PoulavBhowmick03/Erebus && cd Erebus

rust

cd sdk/rs && cargo test --all-targets && cd ../.. # 351 passed, 2 ignored

python

uv sync --all-packages && uv run pytest          # 154 tests

uv sync without --all-packages skips the workspace members’ editable installs, and the erebus-* packages will not be importable.

The TypeScript SDK is a differential-test oracle and ships nothing; it needs a sibling checkout of starkware-libs/starknet-privacy. Toolchain: scarb 2.17.0 / starknet-foundry 0.59.0, Node 20+, Rust stable.

Read the source of truth

Unaudited, with no external security review. Do not use it for value you care about.