Skip to main content

​
Introduction

Silvana Book relies on autonomous off-chain agents to perform sensitive operations such as cryptographic signing. When deployed on Google Cloud, these agents run as secure, scalable services with strict IAM boundaries and protected key storage.
Google Cloud provides a secure, scalable, and production-grade runtime for Silvana Book agents. When deployed on Google Cloud, the agent runs inside Cloud Run as a managed container, with private key storage handled by Secret Manager and external access controlled through API Gateway.
Silvana Book agents are not tied to a single hosting model: you can deploy the agent on your own infrastructure or run it on Google Cloud.
  • Self-hosted: Full infrastructure control, internal scaling and deployment management.
  • Google Cloud: Managed runtime, automatic scaling, built-in secret storage, faster production rollout.

​
Quick start

​
Step 1. Install prerequisites

  • Rust: install via rustup (stable toolchain)
  • Protobuf compiler (protoc):
    • Windows: winget install Google.Protobuf (or install protoc via Chocolatey/Scoop)
    • macOS: brew install protobuf
    • Linux: apt install protobuf-compiler
The following links are necessary for developers to access the protocol, library interface, and reference implementation:

​
Step 2. Generate / rebuild gRPC clients from .proto

From the repo root: 
cargo build -p orderbook-proto
That’s it. crates/orderbook-proto/build.rs runs protoc + tonic_prost_build and regenerates Rust types/clients into Cargo’s OUT_DIR. You do not commit generated Rust output.

​
Step 3. Build and run the cloud agent CLI

cargo build --release -p orderbook-cloud-agent
target/release/cloud-agent --help
To provision a dev identity and generate .env (talks to your Silvana RPC endpoint): 
target/release/cloud-agent onboard --rpc https://rpc.example.com
Then run the long-lived agent: 
target/release/cloud-agent agent
For end-user configuration details (.env, agent.toml, configuration.toml), see the root README.md.

​
Where things live

  • Proto definitions: proto/silvana/{ledger,orderbook,pricing,settlement,news}/v1/*.proto
  • Generated Rust modules + clients: crates/orderbook-proto/src/lib.rs
    • orderbook_proto::orderbook::* (OrderbookService)
    • orderbook_proto::settlement::* (SettlementService)
    • orderbook_proto::pricing::* (PricingService)
    • orderbook_proto::ledger::* (DAppProviderService)
  • Cloud agent binary: crates/orderbook-cloud-agent (bin name: cloud-agent)

​
Common developer workflows

​
Change a message / RPC

  1. Edit the .proto file under proto/silvana/....
  2. Rebuild the generated clients:
cargo build -p orderbook-proto
  1. Fix compile errors in crates that depend on the generated types (commonly orderbook-agent-logic and orderbook-cloud-agent).
  2. Run tests:
cargo test -p orderbook-proto

​
Add a new .proto file

  • Put it under proto/silvana/<service>/v1/.
  • If it’s a brand-new top-level service proto (not just an imported helper), you’ll typically need to add it to crates/orderbook-proto/build.rs so it’s compiled and a descriptor set is emitted.

​
Compatibility rules

  • Never renumber fields: once a field number is used, don’t change it.
  • Prefer additive changes: add new fields with new numbers; old clients will ignore unknown fields.
  • Reserve removed fields: use reserved for field numbers/names you delete so they can’t be reused accidentally.
  • Avoid breaking rename/move changes: changing package names, message names, or RPC names is effectively a breaking change for most clients.