> ## Documentation Index
> Fetch the complete documentation index at: https://docs.silvana.one/llms.txt
> Use this file to discover all available pages before exploring further.

# Google Cloud Agents

# 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.

<Note>
  [**Google Cloud**](https://cloud.google.com/) 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.
</Note>

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`

<Note>
  The following links are **necessary** for developers to access the protocol, library interface, and reference implementation:

  * [**Proto specification**](https://github.com/SilvanaOne/silvana-book-agent/tree/main/proto/silvana)
  * [**NPM library**](https://www.npmjs.com/package/@silvana-one/orderbook)
  * [**Agent code repository**](https://github.com/SilvanaOne/silvana-book-agent)
</Note>

## Step 2. Generate / rebuild gRPC clients from `.proto`

From the repo root:

```javascript theme={null}
cargo build -p orderbook-proto
```

<Check>
  **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.
</Check>

## Step 3. Build and run the cloud agent CLI

```text theme={null}
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):

```text theme={null}
target/release/cloud-agent onboard --rpc https://rpc.example.com
```

Then run the long-lived agent:

```text theme={null}
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:

```text theme={null}
cargo build -p orderbook-proto
```

3. Fix compile errors in crates that depend on the generated types (commonly `orderbook-agent-logic` and `orderbook-cloud-agent`).
4. Run tests:

```text theme={null}
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

<Warning>
  * **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.
</Warning>