The Application BlockChain Interface (ABCI)
The Application BlockChain Interface (ABCI) defines the boundary between the consensus engine (the blockchain) and an application to be replicated across a number of platforms. The ABCI lets the application logic communicate with the consensus engine in a transparent way so that all agents' internal state are synchronized. The application to be replicated can be written in any programming language, and it communicates with the consensus engine of each agent through a variety of methods, e.g., Unix or TCP sockets. In our case, we leverage the ABCI to replicate the sate of the FSM App within the agents of an agent service.
The ABCI standard was introduced with the Tendermint project. Nevertheless, an ABCI App can work with any consensus engine that is ABCI-compatible, e.g., Fantom. In the remaining of this section, we will consider Tendermint as the consensus engine.
ABCI Apps are only reactive and specify how a transaction updates the application state. On the other hand, FSM Apps rely on the low-level ABCI application layer to replicate the state consistently among different instances, but they also exhibit proactive behaviour. For example, periodically execute some routines, monitor the value of the crypto assets of the final customer, etc.
In other words, FSM Apps rely on the underlying ABCI, but an FSM App is not an ABCI App.
Brief Overview of Tendermint
Tendermint is a software for securely and consistently replicating an application on many machines. It ensures that the replication is Byzantine fault-tolerant (BFT), i.e., it has the ability to tolerate machines failing in arbitrary ways, including becoming malicious.
Tendermint consists of two chief technical components: a blockchain consensus engine, and a generic application interface:
- Tendermint Core is the underlying consensus engine, which ensures that the same transactions are recorded on every machine in the same order.
- The Application BlockChain Interface (ABCI) is the interface that enables the transactions to be processed in any programming language. Unlike other blockchain and consensus solutions, which come pre-packaged with built-in state machines, developers can use Tendermint for state machine replication of arbitrary applications written in any programming language and development environment.
In the picture below, you can see a simplified diagram showing how Tendermint modularizes a distributed state-machine replication system by clearly separating the business logic layer (the application) from the consensus and networking layer (Tendermint Core) through the ABCI layer:
A detailed description of the consensus algorithm implemented by Tendermint is out of the scope of this document. We refer the reader to the Tendermint documentation for the complete details.
The ABCI Protocol
The interaction between the consensus node and the ABCI App follows the client-server paradigm. It must be taken into account both the callbacks received by the consensus node, and the proactive execution of transactions that the application wishes to execute.
On one hand, the application (the server) listens for callbacks coming from the consensus node (the client), which sends requests to the ABCI App for different purposes. For example, check whether a transaction is valid and therefore if it can be added to the transaction pool, to notify the application that a block has been validated, or to get information from the application layer. The application must process and respond appropriately to such callbacks.
On the other hand, the application can exhibit a proactive behaviour, when it wishes to submit a transaction to the blockchain. For example, it can commit a certain observed value in an external server. This would be the "user role" when interacting with the blockchain.
Reactive Callbacks from the Consensus Node
The ABCI protocol specifies a number of method calls that follow request-response interactions between the consensus node and the ABCI App. That is, the application will receive a number of callbacks related to events occurring at the consensus layer that are grouped according to their specific functionality as follows:
- Methods related to the consensus protocol:
- Methods related to the mempool, used to validate new transactions before they are shared or included in a block:
- Methods for initialization and for queries from the user:
- Methods for serving and restoring state sync snapshots
Additionally, there is a
Flush method that is called on every connection, and an
Echo method that is just for debugging.
Some requests like
InitChain are proactively made by the consensus node upon genesis. Most of the requests instead depend on the transactions stored in the mempool.
Proactive Calls to the Blockchain
The ABCI App can submit transactions to the Tendermint blockchain using the Tendermint RPC protocol. See also the Protobuf definitions of those messages. The application can send a transaction by using the following Tendermint RPC methods:
broadcast_tx_sync, which is blocking until the transaction is considered valid and added to the mempool;
broadcast_tx_async, which does not wait until the transaction is considered valid and added to the mempool;
broadcast_tx_commit, which waits until the transaction is committed into a block and processed by the application.
Note that the above methods take as input a transaction, i.e., a sequence of bytes. The consensus node does not know the meaning of the content of the transaction, as its meaning resides in the ABCI App logic. This is a key feature that makes the application layer and the consensus layer highly decoupled.
A quick overview of the ABCI protocol is depicted in the diagram below. See the complete details here.
ABCI Apps and the Open Autonomy framework
The reader might have noticed that we have used the concepts of "reactive callbacks" from the Tendermint blockchain to the ABCI App, and "proactive calls" from the ABCI App to the blockchain. This is by no means a coincidence with the architecture of an AEA: the former are associated to reactive Handlers, whereas the latter are associated to proactive Behaviours in an AEA Skill.
Below, we depict sequence diagrams for the three transactions presented above, showing how both the proactive and reactive calls work.
The figure below shows the sequence of actions on the different components on a Tendermint application, e.g., for the request
- An application behaviour initiates the process by submitting a request, e.g.,
- The Tendermint nodes handle the transaction and handle any required networking or consensus actions to be done at this stage. This is transparent from the point of view of the application. Each Tendermint node notifies its associated application through the ABCI interface by calling, e.g.,
- The applications respond accordingly through the ABCI interface. Again, at this point the Tendermint nodes will handle the networking and consensus layer transparently.
- Finally, the calling behaviour receives response of the executed transaction (if applies).
A more detailed sequence diagram corresponding to this transaction is as follows:
Also, the ABCI App state can be queried by means of the
The sender has to provide the
path parameter (a string) and the
parameter (a string). The actual content will depend on the queries the ABCI App
supports. The consensus node forwards the query through the