Client and Server

This section is for those looking to implement their own ABCI Server, perhaps in a new programming language.

You are expected to have read all previous sections of ABCI specification, namely Basic Concepts, Methods, Application Requirements, and Expected Behavior.

Message Protocol and Synchrony

The message protocol consists of pairs of requests and responses defined in the protobuf file.

Some messages have no fields, while others may include byte-arrays, strings, integers, or custom protobuf types.

For more details on protobuf, see the documentation.

Tenderdash creates one application client and delegates the request classes to it. Ordinary socket and gRPC configurations do not create separate consensus, mempool, query and state-sync connections automatically. A routed client can use multiple underlying clients when explicitly configured.

Each synchronous call waits for its own response. This does not serialize calls from independent callers. Execution order and concurrency depend on the transport and server implementation; see Connections.

Server Implementations

To use ABCI in your programming language of choice, there must be an ABCI server in that language. Tenderdash provides three Go implementations:

  • In-process
  • ABCI-socket
  • gRPC

See the server implementations and ABCI CLI guide. Out-of-process servers must implement Tenderdash's protobuf schema and application requirements.

In Process

The simplest implementation uses function calls in Golang. This means ABCI applications written in Golang can be linked with Tenderdash and run as a single binary. The local client delegates directly to application methods without a shared execution lock, so the application must synchronize concurrent access to its state.

GRPC

If you are not using Golang, but GRPC is available in your language, this is the easiest approach, though it will have significant performance overhead.

Please check GRPC's documentation to know to set up the Application as an ABCI GRPC server.

The client multiplexes calls over one grpc.ClientConn; application methods can execute concurrently. The abci.grpc-concurrency configuration limits streams per method or through the default * rule. Its default is {"*": 0}, which imposes no limit. A limit for one method does not serialize it with methods using a different limit. Protect state shared by concurrent calls.

Socket

Tenderdash's socket-based ABCI interface is an asynchronous, raw socket server which provides ordered message passing over unix or tcp. Messages are serialized using Protobuf3. Each message is prefixed by its byte length encoded as an unsigned protobuf varint. For example, a four-byte message DEADBEEF is sent as 04DEADBEEF. The receiver reads the varint length and then that many message bytes. See the codec.

This framing does not apply to gRPC. The socket client sends requests and matches responses in order on its connection. Tenderdash's reference socket server executes requests sequentially per connection, while separate connections can execute concurrently. A compatible socket server must preserve response order; it must not assume a fixed number of role-specific connections.

Client

There are currently two use-cases for an ABCI client. One is testing tools that allow ABCI requests to be sent to the actual application via command line. An example of this is abci-cli, which accepts CLI commands to send corresponding ABCI requests. The other is a consensus engine, such as Tenderdash, which makes ABCI requests to the application as prescribed by the consensus algorithm used.