Zoryth is a double-entry ledger engine built for programmatic consumption. It replaces session-based human authentication with cryptographic signatures and API keys. Human users interact via a web dashboard that manages an Ed25519 keypair locally, utilizing the same cryptographic API protocol as automated agents.
Note
Use-Case & Maturity Disclaimer:
- For Learning / Experimentation: It is an excellent, clean, and highly educational codebase. It demonstrates how to combine Web3 cryptographic models (keypairs, signatures) with traditional relational databases.
- For Prototyping / Internal Dev Tools: It is ready to run. You can deploy it to orchestrate testnets, simulate agentic banking environments, or run internal virtual credit systems.
- For Real Financial Settlement: It should be treated as a reference architecture. The design is solid, but the infrastructure surrounding key security, network transport, and database scale requires hardening.
- Ed25519 Signatures: Requests are authenticated statelessly using an
X-Zoryth-Signatureheader generated by signing a canonical request payload (containing method, path, timestamp, and body hash). Replay attacks are mitigated via a 5-minute timestamp window check. - API Key Auth: A secondary authentication method using hashed API keys (
X-Zoryth-Api-Key) mapped to specific permission scopes. - Zero Sessions: All cookie and database-backed session tables have been removed.
- Standardized JSON Contract: Every response follows a wrapper of
{ data: T, request_id: String, timestamp: DateTime }or returns a structured machine-readable error format. - Idempotency Keys: All write/mutating endpoints require an
X-Idempotency-Keyheader, allowing consumers to safely retry operations.
- At-Least-Once Webhooks: Mutation events are written to a database-backed
event_outboxtable during the ledger transaction and delivered asynchronously using exponential backoff. - HMAC Payload Signing: Webhook payloads are signed using an HMAC-SHA256 secret.
- Server-Sent Events (SSE): Real-time event broadcasting is available via
/v1/events/stream.
- Pre-Transaction Checks: Configurable spending limit and whitelist constraints evaluated inside the ledger transaction.
- Post-Transaction Rules: Autonomous conditional transfer sweeping triggered by balance conditions.
- Cross-Node Relaying: Nodes register each other as peers, exchange capability manifests, and automatically discover and route transfers targeting wallets hosted on other nodes.
- Per-Agent Limits: Token buckets are tracked in concurrent memory (
DashMap) and enforced based on agent tier (Free: 10 req/min, Standard: 100 req/min, Premium: 1000 req/min).
Requests utilizing signature authentication must calculate the signature over a canonical representation of the request:
{HTTP_METHOD}\n{PATH_AND_QUERY}\n{TIMESTAMP}\n{BODY_SHA256_HEX}
This string is signed with the agent's Ed25519 private key, and the resulting signature is sent in the X-Zoryth-Signature header alongside the public key in X-Zoryth-Key and the timestamp in X-Zoryth-Timestamp.
| Route | Method | Purpose | Authentication |
|---|---|---|---|
/v1/identity/register |
POST | Registers an agent; accepts/generates keys | None |
/v1/identity/me |
GET | Returns own profile, active wallets, and tier | Ed25519 / API Key |
/v1/identity/keys |
POST | Generates scoped API keys | Ed25519 / API Key |
/v1/identity/keys/:prefix |
DELETE | Revokes a scoped API key | Ed25519 / API Key |
/v1/wallets |
POST | Creates a ledger wallet for the agent | Ed25519 / API Key |
/v1/wallets |
GET | Lists wallets owned by the agent | Ed25519 / API Key |
/v1/wallets/:id |
GET | Returns balance and details of a wallet | Ed25519 / API Key |
/v1/wallets/:id/ledger |
GET | Returns double-entry ledger lines for a wallet | Ed25519 / API Key |
/v1/transfers |
POST | Executes a double-entry money transfer | Ed25519 / API Key |
/v1/transfers/batch |
POST | Processes multiple transfers atomically | Ed25519 / API Key |
/v1/transfers/:id |
GET | Retrieves details of a specific transaction | Ed25519 / API Key |
/v1/transfers/:id/reverse |
POST | Performs double-entry reversal of a transaction | Ed25519 / API Key |
/v1/events/subscribe |
POST | Registers a webhook subscription | Ed25519 / API Key |
/v1/events/subscriptions |
GET | Lists active webhook subscriptions | Ed25519 / API Key |
/v1/events/subscriptions/:id |
DELETE | Deletes a webhook subscription | Ed25519 / API Key |
/v1/events/stream |
GET | Subscribes to real-time events via SSE | Ed25519 / API Key |
/v1/policies |
POST | Creates a pre/post-transaction ledger policy | Ed25519 / API Key |
/v1/policies |
GET | Lists policies active for the agent | Ed25519 / API Key |
/v1/policies/:id |
DELETE | Removes/deactivates a policy | Ed25519 / API Key |
/v1/network/health |
GET | Uptime, peer count, database stats | None |
/v1/network/capabilities |
GET | Returns MCP-compatible capability schema | None |
/v1/network/peers |
GET | Lists connected node peers | Ed25519 / API Key |
/v1/network/peers |
POST | Registers a new peer node | Ed25519 / API Key |
/v1/audit |
GET | Runs system-wide balance verification | Ed25519 / API Key |
To run the entire Zoryth ecosystem (PostgreSQL, Redis, Rust backend, and Python queue worker) with a single command:
- Docker and Docker Compose installed.
- Start the stack:
This automatically creates the databases, runs migrations, and connects all components.
docker compose up --build -d
- Check services health status:
docker compose ps
- View logs:
docker compose logs -f
To stop the containers:
docker compose down- Rust toolchain (Cargo)
- PostgreSQL 15+
- Redis 7+
- Create a database named
zoryth. - Configure
.envin the repository root:DATABASE_URL=postgres://username:password@localhost:5432/zoryth RUST_LOG=zoryth=info PORT=8000 NODE_IDENTIFIER=zth_node_alpha NODE_ENDPOINT=http://localhost:8000
- Run migrations and start the server:
cargo run
- Start the Python queue worker:
cd queue_service pip install -r requirements.txt uvicorn main:app --port 8001 - Run integration tests:
cargo test