Crate Docs

See the [repo root] for build status, license, rust version, etc.

tendermint-rpc

A Rust implementation of the core types returned by a Tendermint node's RPC endpoint. These can be used to deserialize JSON-RPC responses.

All networking related features will be feature guarded to keep the dependencies small in cases where only the core types are needed.

Documentation

See documentation on crates.io.

Client

This crate optionally provides access to different types of RPC client functionality and different client transports based on which features you select when using it.

Several client-related features are provided at present:

CLI

A tendermint-rpc console application is provided for testing/experimentation purposes. To build this application:

```bash

From the tendermint-rpc crate's directory

cd rpc cargo build --bin tendermint-rpc --features cli

To run directly and show usage information

cargo run --bin tendermint-rpc --features cli -- --help

To install the binary to your Cargo binaries path

(should be globally accessible)

cargo install --bin tendermint-rpc --features cli --path . ```

The application sends its logs to stderr and its output to stdout, so it's relatively easy to capture RPC output.

Usage examples: (assuming you've installed the binary)

```bash

Check which RPC commands/endpoints are supported.

tendermint-rpc --help

Query the status of the Tendermint node bound to tcp://127.0.0.1:26657

tendermint-rpc status

Submit a transaction to the key/value store ABCI app via a Tendermint node

bound to tcp://127.0.0.1:26657

tendermint-rpc broadcast-tx-async somekey=somevalue

Query the value associated with key "somekey" (still assuming a key/value

store ABCI app)

tendermint-rpc abci-query somekey

To use an HTTP/S proxy to access your RPC endpoint

tendermint-rpc --proxy-url http://yourproxy:8080 abci-query somekey

To set your HTTP/S proxy for multiple subsequent queries

export HTTP_PROXY=http://yourproxy:8080 tendermint-rpc abci-query somekey

Subscribe to receive new blocks (must use the WebSocket endpoint)

Prints out all incoming events

tendermint-rpc -u ws://127.0.0.1:26657/websocket subscribe "tm.event='NewBlock'"

If you want to execute a number of queries against a specific endpoint and

don't feel like re-typing the URL over and over again, just set the

TENDERMINTRPCURL environment variable

export TENDERMINTRPCURL=ws://127.0.0.1:26657/websocket tendermint-rpc subscribe "tm.event='Tx'" ```

Mock Clients

Mock clients are included when either of the http-client or websocket-client features are enabled to aid in testing. This includes MockClient, which implements both Client and SubscriptionClient traits.

Related

Testing

The RPC types are directly tested through the integration tests. These tests use fixtures taken from running Tendermint nodes to ensure compatibility without needing access to a running node during testing. All of these fixtures were generated manually, and automatic regeneration of the fixtures is on our roadmap.

To run these tests locally:

```bash

From within the rpc crate

cargo test --all-features ```

The RPC client is also indirectly tested through the Tendermint integration tests, which happens during CI. All of these tests require a running Tendermint node, and are therefore ignored by default. To run these tests locally:

```bash

In one terminal, spin up a Tendermint node

docker pull tendermint/tendermint:latest docker run -it --rm -v "/tmp/tendermint:/tendermint" \ tendermint/tendermint init docker run -it --rm -v "/tmp/tendermint:/tendermint" \ -p 26657:26657 \ tendermint/tendermint node --proxy_app=kvstore

In another terminal, run the ignored Tendermint tests to connect to the node

running at tcp://127.0.0.1:26657

cd ../tendermint cargo test --all-features -- --ignored ```