[![Crate][crate-image]][crate-link]
[![Docs][docs-image]][docs-link]

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][docs-link].

## 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:

* `http-client` - Provides `HttpClient`, which is a basic RPC client that
  interacts with remote Tendermint nodes via **JSON-RPC over HTTP or
  HTTPS**. This client does not provide `Event` subscription
  functionality. See the [Tendermint RPC] for more details.
* `websocket-client` - Provides `WebSocketClient`, which provides full
  client functionality, including general RPC functionality as well as
  `Event`] subscription functionality. Can be used over secure
  (`wss://`) and unsecure (`ws://`) connections.

### 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
# TENDERMINT_RPC_URL environment variable
export TENDERMINT_RPC_URL=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

- RPC [core types] in golang
  
- RPC endpoints REST interface documentation:
  <https://docs.tendermint.com/v0.34/rpc/>

## Testing

The RPC types are directly tested through the [integration
tests](./tests/integration.rs). 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][autogen-fixtures].

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](../tendermint/tests/integration.rs), which happens during
[CI](../.github/workflows/test.yml). 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
```

[//]: # (badges)

[crate-image]: https://img.shields.io/crates/v/tendermint-rpc.svg
[crate-link]: https://crates.io/crates/tendermint-rpc
[docs-image]: https://docs.rs/tendermint-rpc/badge.svg
[docs-link]: https://docs.rs/tendermint-rpc/

[//]: # (general links)

[repo root]: https://github.com/informalsystems/tendermint-rs
[tendermint]: https://github.com/tendermint/tendermint
[core types]: https://github.com/tendermint/tendermint/blob/8b4a30fada85fccd8f0cb15009344f1cbd8de616/rpc/core/types/responses.go#L1
[tendermint.rs]: https://crates.io/crates/tendermint
[Tendermint RPC]: https://docs.tendermint.com/v0.34/rpc/
[`/subscribe` endpoint]: https://docs.tendermint.com/v0.34/rpc/#/Websocket/subscribe
[autogen-fixtures]: https://github.com/informalsystems/tendermint-rs/issues/612