Rpc Readme

RPC

This document is meant to be a starting point/placeholder for a full-fledged RPC specification that allows interaction with the nodes.

Contents

• Inspiration
• Code generation
• Endpoints
• Spec
  • Node related
  • Transaction related
    • Payload:
    • Return:
    • What's next?
• Code Organization

Inspiration

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.

Code generation

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.

Endpoints

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.

Spec

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 related

• Node liveness check (GET /v1/health)
• Node version check (GET /v1/version)

These are pretty self-explanatory.

Transaction related

• Sync signed transaction submission (POST /v1/client/broadcast_tx_sync)

Payload:

{
  "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.

Return:

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.

What's next?

Definitely we'll need ways to retrieve transactions as well so we can envisage:

• Get a transaction by hash (**GET /v1/query/tx **)

Code Organization

├── 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)