Here we cover the basics of using an RPC in the Cosmos ecosystem.
This article is for experienced developers new to Cosmos.
Remote procedure calls (RPCs) are frequently used in distributed computing and allow for inter-process communication (IPC).
In short, this means a program can create procedures to be executed on different machines.
To read and write to Cosmos blockchains you must have access to a node.
There are public nodes that expose endpoints for free.
These endpoints include the Cosmos SDK's gRPC and REST as well as the Tendermint RPC server.
Public nodes are great for initial testing, but when you ship a production build you will want to either set up your own node or use a private node provider.
Tendermint core is a platform for blockchain applications, similar to a web server and database.
The Cosmos SDK was developed to allow you to build “application specific blockchains” on top of Tendermint.
After a blockchain is deployed it's sandboxed and the only way for applications and users to interact with it is via a node's exposed endpoints.
Cosmos nodes expose three types of endpoints:
gRPC
REST
Tendermint RPC server
The Cosmos SDK uses Protobuf as an encoding library allowing the use of gRPC.
gRPC is an open-source RPC framework that is designed for high performance.
REST routes are also supported by the gRPC-gateway.
To learn more about using REST and gRPC to query state or broadcast a transaction check out the Cosmos SDK documentation here.
The easiest option to get started testing your application is to use the public Tendermint RPC server and that is what we will briefly cover below.
Tendermints RPC server is independent of the Cosmos SDK and easy to use.
Although the learning curve is faster compared to the Protobuf gRPC it's not ideal for large over-the-wire messages (like JSON).
Tendermint's RPC supports:
URI over HTTP
JSONRPC over HTTP
JSONRPC over websockets
To configure the RPC server change the parameters under the rpc
table in the $TMHOME/config/config.toml
file.
You can also use --rpc.X
flags in the command-line.
Note that the default listening address is tcp://0.0.0.0:26657
. To set another address, you can reference the docs here for more information.
There are also several Tendermint RPC endpoints directly related to the Cosmos SDK such as /abci_query
, which will query the application state.
The rest of the related endpoints can be found here in the Cosmos SDK docs.
Here we'll go over the basics of setting up an application and interacting with a local testnet with the Tendermint RPC.
We will use the command-line for this demo.
First, install the Tendermint binary by following these directions.
Now let's get started.
In your root directory run:
abci-cli kvstore
This will start a Kvstore application, which is a Merkle Tree. If your transaction has a =
then the value
will be stored with the associated key
.
If there's no =
in your transaction, the transaction bytes are stored as both the key
and the value
.
In a second terminal, start your Tendermint node:
tendermint node
Tendermint will now start making blocks.
To get the status of your node, run:
curl -s localhost:26657/status
Okay, now we can simply start sending transactions to our local blockchain, run:
curl -s 'localhost:26657/broadcast_tx_commit?tx="abcd"'
This sends a transaction with bytes abcd
to our Kvstore. Because there is no =
sign, abcd
will be stored as both the key
and value
in our Merkle tree.
We should get a response that looks like this:
{ "jsonrpc": "2.0", "id": "", "result": { "check_tx": {}, "deliver_tx": { "tags": [ { "key": "YXBwLmNyZWF0b3I=", "value": "amFl" }, { "key": "YXBwLmtleQ==", "value": "YWJjZA==" } ] }, "hash": "9DF66553F98DE3C26E3C3317A3E4CED54F714E39", "height": 14 } }
To double-check that the transaction worked, we can simply query our application, like this:
curl -s 'localhost:26657/abci_query?data="abcd"'
This will give us a response that's similar to this:
{ "jsonrpc": "2.0", "id": "", "result": { "response": { "log": "exists", "index": "-1", "key": "YWJjZA==", "value": "YWJjZA==" } } }
Note: the value abcd
is base64-encoded ASCII. There are ways to confirm this if you're using a python 2 or python 3 shell, you can learn more by checking out the Tendermint docs here.
Let's try another transaction.
This time we'll set a new key
and value
using an =
sign, run:
curl -s 'localhost:26657/broadcast_tx_commit?tx="name=satoshi"'
To confirm this worked, you can do the same as above and query the application, like so:
curl -s 'localhost:26657/abci_query?data="name"'
This will return satoshi
but in base64, so: c2F0b3NoaQ==
.
And that is the basics of a Kvstore app with a local Tendermint node.
To see more tutorials, check out the Tendermint getting started docs.
What if you want to interact with blockchains already deployed in the Cosmos ecosystem?
To do this, let's take a look at three major blockchains in the ecosystem that use both Tendermint core and the Cosmos SDK.
We'll need to reference each blockchain's docs.
First, let's look at the crypto.org chain.
Their stated goal is to allow global blockchain transactions between users and businesses.
You can access a public node for both mainnet and a testnet, check out how here.
You can also set up a node to access an RPC server and can learn more here.
The Haqq network is built with Cosmos SDK but is compatible with Ethereum.
Haqq has several API options.
These include JSON-RPC API to interact with the EVM as well as Cosmos' gRPC and the Tendermint RPC server.
Akash network is a decentralized cloud marketplace.
Akash also maintains public RPC nodes, which can be accessed here.
They also have a list of trusted community nodes.
Akash also has good documentation on setting up your own node, here.
Notice that using an RPC endpoint is slightly different for each of the three examples above.
Easy access to public node endpoints is an important resource for both developers and users, helping bootstrap activity on the blockchain.
Public nodes, however, are less ideal when the testing phase of application development is over.
They require expertise to maintain and a lot of computing resources, and because of this often enforce rate limits or experience downtime.
Unfortunately, this has caused an overreliance on high-quality node service providers leading to the centralization of blockchain access infrastructure.
Not only is this centralization less than ideal from a Web3 ethos perspective, but importantly, it introduces a single point of failure.
If one private node provider goes offline for any reason, many applications and users are at risk of losing access to the blockchain.
To help remedy this growing problem, the Lava Network was developed.
Lava Netowrk is a blockchain built with the Cosmos SDK and creates a trustless market for RPCs.
Using cryptoeconomic incentive structures, Lava aims to provide high-quality RPC access as decentralized publicly available infrastructure.
Check out Lava’s website to read the lite paper and learn more.
RPCs are a common method to access blockchains.
Nodes expose endpoints, and Tendermint is one such configurable RPC server.
It's not appropriate to use public nodes outside of testing, limiting the number of high-quality node providers available.
Lava aims to fix this by using crypto-economic incentives to develop decentralized public RPC infrastructure.