This repository keeps the gRPC protocol definition file and related documentation on the gRPC interface exposed by concordium-node.
The V2 API consists of three services
and an auxiliary file with all the types for requests and responses
The two health services exist to expose a different API. The first health service returns status via grpc status codes. The second health service is a standard Google health service that communicates service health via response values.
The rendered documentation for the V2 API is available at http://developer.concordium.software/concordium-grpc-api/
Generated Code & Compilation Requirements
To generate the gRPC and Protobuf stubs, you need to use protoc, the Protocol Buffers compiler. Below are the steps and requirements to compile the .proto files.
Dependencies
protoc version 28.3 is recommended. This version provides full support for handling optional fields in proto3 and ensures compatibility with all recent features of Protocol Buffers.
Compilation Example
Use the following command to generate the gRPC files for different languages:
protoc --proto_path=concordium_protos \ --<language>_out=concordium_protos/generated \ --grpc_out=concordium_protos/generated \ --experimental_allow_proto3_optional \ concordium_protos/*.proto
- Replace with the desired target language (e.g., cpp, java, python, go, php, js, etc.).
- Replace paths as needed.
- Ensure all .proto files are in the appropriate folder.
Useful References
-
gRPC GitHub Repository: The official gRPC repository contains source code, documentation, and examples for using gRPC across different languages, making it a valuable resource for understanding and implementing gRPC services.
-
Protocol Buffers Documentation: This reference documentation is essential for understanding the syntax, features, and capabilities of Protocol Buffers, including how to define messages and services in .proto files.
-
Protocol Buffers Third-Party Plugins: This page provides information on third-party plugins available for use with Protocol Buffers, which can help in generating code for various languages and platforms beyond the official support.
Notes from Experience
- Make sure you are using the correct version of protoc. Older versions may have limitations when handling proto3 optional fields, leading to compilation issues.
- If compilation errors occur related to optional fields, upgrading protoc to version 28.3 should resolve these issues.
- The generated files should include both the gRPC client/service stubs and the data classes defined in types.proto.
- If protoc is not compiling the appropriate files, 3rd party plugins may be the solution depending on case, older versions of protoc had more dependencies on plugins.