This document is meant to be a starting point/placeholder for a full-fledged RPC specification that allows interaction with the nodes.
Pocket V0 has inspired a lot the first iteration but then we converged towards a spec-centric approach, where the boilerplate code (serialization, routing, etc) is derived from an OpenAPI 3.0 specification.
This approach will allow us to focus on the features and less on the boilerpate and ultimately to iterate more quickly as we discover the way ahead of us.
The current implementation uses code generation for ease of development.
The source of truth is the the OpenAPI3.0 yaml file (also conveniently visible here via the Swagger Editor)
Anytime we make changes to the yaml file, we need to regenerate the boilerplate code by running
make generate_rpc_openapi
The compilation errors should guide towards the next steps.
Currently, the API is in its simplest form. Basically a REST API.
As the codebase matures, we'll consider other transports such as JSON RPC 2.0 and GRPC.
The Swagger Editor with preview is available here.
Alternatively, you can run:
make swagger_ui
and browse/test it locally.
This first iteration includes the bare minimum:
- Node liveness check (GET /v1/health)
- Node version check (GET /v1/version)
These are pretty self-explanatory.
- Sync signed transaction submission (POST /v1/client/broadcast_tx_sync)
{
"address": "string",
"raw_hex_bytes": "string"
}
address
: specifies the address the transaction originates from.raw_hex_bytes
: hex encoded raw protobuf bytes of a signed transaction.
Currently only OK (HTTP Status code 200) or KO (HTTP Status code 4xx/5xx)
This API might be extended to return potentially useful information such as the transaction hash which is known at the moment of submission and can be used to query the blockchain.
Definitely we'll need ways to retrieve transactions as well so we can envisage:
- Get a transaction by hash (**GET /v1/query/tx **)
├── client.gen.config.yml # code generation config for the client
├── client.gen.go # generated client boilerplate code
├── doc # folder containing RPC specific docs
├── handlers.go # concrete implementation of the HTTP handlers invoked by the server
├── module.go # RPC module
├── noop_module.go # noop RPC module (used when the module is disabled)
├── server.gen.config.yml # code generation config for the server dtos
├── server.gen.go # generated server boilerplate code
├── server.go # RPC server configuration and initialization
├── types
│ ├── proto
│ │ └── rpc_config.proto # protobuf file describing the RPC module configuration
│ └── rpc_config.pb.go # protoc generated struct and methods for RPC config
└── v1
└── openapi.yaml # OpenAPI v3.0 spec (source for the generated files above)