Protocol Overview
Sonata uses Protocol Buffers (protobuf) as its interface definition language, with ConnectRPC providing the RPC framework for client-server communication.
Overview
The protocol layer defines all data structures and service interfaces across the Sonata network. This includes chain state, API services, P2P messages, and storage operations.
Architecture
┌─────────────────────────────────────────────────────────┐
│ proto/ schemas │
│ (account, api, chain, composition, ddex, storage...) │
└─────────────────────────────┬───────────────────────────┘
│
buf generate
│
▼
┌─────────────────────────────────────────────────────────┐
│ gen/ output │
│ Go types + ConnectRPC service stubs │
└─────────────────────────────┬───────────────────────────┘
│
┌───────────────┴───────────────┐
▼ ▼
┌─────────────────────────┐ ┌─────────────────────────┐
│ Server (x/server) │ │ Clients (SDK) │
│ Implements services │ │ Consumes services │
└─────────────────────────┘ └─────────────────────────┘Key Components
| Component | Description |
|---|---|
| proto/ | Schema definitions in .proto files |
| gen/ | Generated Go code from protobuf schemas |
| Buf | Build tool for protobuf (linting, breaking change detection, generation) |
| ConnectRPC | Modern RPC framework compatible with gRPC, gRPC-Web, and HTTP/JSON |
Why This Stack?
- Protobuf: Strongly-typed, language-agnostic, efficient binary serialization
- ConnectRPC: Simpler than gRPC, browser-compatible, HTTP/JSON fallback
- Buf: Modern tooling for schema management and code generation
Schema Organization
The proto/ directory is organized by domain:
api/v1/— External API service definitionschain/v1/— On-chain transaction and state typesaccount/v1/— Account-related messagesstorage/v1/— File storage messagesddex/v1/— DDEX metadata typescomposition/v1/— Music composition typesp2p/v1/— Peer-to-peer network messagesstore/— Internal storage key schemas