lbcwallet/rpc/documentation/serverchanges.md

Making API Changes

This document describes the process of how btcwallet developers must make changes to the RPC API and server. Due to the use of gRPC and Protocol Buffers for the RPC implementation, changes to this API require extra dependencies and steps before changes to the server can be implemented.

Requirements

• The Protocol Buffer compiler protoc installed with support for the proto3 language

  The protoc tool is part of the Protocol Buffers project. This can be installed from source, from an official binary release, or through an operating system's package manager.

• The gRPC protoc plugin for Go

  This plugin is written in Go and can be installed using go get:

  go get github.com/golang/protobuf/protoc-gen-go
  

• Knowledge of Protocol Buffers version 3 (proto3)

Note that a full installation of gRPC Core is not required, and only the protoc compiler and Go plugins are necessary. This is due to the project using a pure Go gRPC implementation instead of wrapping the C library from gRPC Core.

Step 1: Modify the .proto

Once the developer dependencies have been met, changes can be made to the API by modifying the Protocol Buffers descriptor file api.proto.

The API is versioned according to the rules of Semantic Versioning 2.0. After any changes, bump the API version in the API specification and add the changes to the spec.

Unless backwards compatibility is broken (and the version is bumped to represent this change), message fields must never be removed or changed, and new fields must always be appended.

It is forbidden to use the required attribute on a message field as this can cause errors during parsing when the new API is used by an older client. Instead, the (implicit) optional attribute is used, and the server implementation must return an appropriate error if the new request field is not set to a valid value.

Step 2: Compile the .proto

Once changes to the descriptor file and API specification have been made, the protoc compiler must be used to compile the descriptor into a Go package. This code contains interfaces (stubs) for each service (to be implemented by the wallet) and message types used for each RPC. This same code can also be imported by a Go client that then calls same interface methods to perform RPC with the wallet.

By committing the autogenerated package to the project repo, the proto3 compiler and plugin are not needed by users installing the project by source or by other developers not making changes to the RPC API.

A sh shell script is included to compile the Protocol Buffers descriptor. It must be run from the rpc directory.

$ sh regen.sh

If a sh shell is unavailable, the command can be run manually instead (again from the rpc directory).

protoc -I. api.proto --go_out=plugins=grpc:walletrpc

TODO(jrick): This step could be simplified and be more portable by putting the commands in a Go source file and executing them with go generate. It should, however, only be run when API changes are performed (not with go generate ./... in the project root) since not all developers are expected to have protoc installed.

Step 3: Implement the API change in the RPC server

After the Go code for the API has been regenated, the necessary changes can be implemented in the rpcserver package.

Additional Resources

• Protocol Buffers Language Guide (proto3)
• Protocol Buffers Basics: Go
• gRPC Basics: Go