[![Crate][crate-image]][crate-link]
[![Docs][docs-image]][docs-link]
See the [repo root] for build status, license, rust version, etc.
# cometbft-rpc
A Rust implementation of the core types returned by a CometBFT 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 CometBFT nodes via **JSON-RPC over HTTP or
HTTPS**. This client does not provide `Event` subscription
functionality. See the [CometBFT 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 `cometbft-rpc` console application is provided for testing/experimentation
purposes. To build this application:
```bash
# From the cometbft-rpc crate's directory
cd rpc
cargo build --bin cometbft-rpc --features cli
# To run directly and show usage information
cargo run --bin cometbft-rpc --features cli -- --help
# To install the binary to your Cargo binaries path
# (should be globally accessible)
cargo install --bin cometbft-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.
cometbft-rpc --help
# Query the status of the CometBFT node bound to tcp://127.0.0.1:26657
cometbft-rpc status
# Submit a transaction to the key/value store ABCI app via a CometBFT node
# bound to tcp://127.0.0.1:26657
cometbft-rpc broadcast-tx-async somekey=somevalue
# Query the value associated with key "somekey" (still assuming a key/value
# store ABCI app)
cometbft-rpc abci-query somekey
# To use an HTTP/S proxy to access your RPC endpoint
cometbft-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
cometbft-rpc abci-query somekey
# Subscribe to receive new blocks (must use the WebSocket endpoint)
# Prints out all incoming events
cometbft-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
# COMETBFT_RPC_URL environment variable
export COMETBFT_RPC_URL=ws://127.0.0.1:26657/websocket
cometbft-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.cometbft.com/v1/rpc/>
## Testing
The RPC types are directly tested through the [integration
tests](./tests/integration.rs). These tests use fixtures taken from running
CometBFT 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 [CometBFT integration
tests](../cometbft/tests/integration.rs), which happens during
[CI](../.github/workflows/test.yml). All of these tests require a running
CometBFT node, and are therefore ignored by default. To run these tests
locally:
```bash
# In one terminal, spin up a CometBFT node
docker pull cometbft/cometbft:latest
docker run -it --rm -v "/tmp/cometbft:/cometbft" \
cometbft/cometbft init
docker run -it --rm -v "/tmp/cometbft:/cometbft" \
-p 26657:26657 \
cometbft/cometbft node --proxy_app=kvstore
# In another terminal, run the ignored CometBFT tests to connect to the node
# running at tcp://127.0.0.1:26657
cd ../cometbft
cargo test --all-features -- --ignored
```
[//]: # (badges)
[crate-image]: https://img.shields.io/crates/v/cometbft-rpc.svg
[crate-link]: https://crates.io/crates/cometbft-rpc
[docs-image]: https://docs.rs/cometbft-rpc/badge.svg
[docs-link]: https://docs.rs/cometbft-rpc/
[//]: # (general links)
[repo root]: https://github.com/cometbft/cometbft-rs
[cometbft]: https://github.com/cometbft/cometbft
[core types]: https://github.com/cometbft/cometbft/blob/8b4a30fada85fccd8f0cb15009344f1cbd8de616/rpc/core/types/responses.go#L1
[cometbft.rs]: https://crates.io/crates/cometbft
[CometBFT RPC]: https://docs.cometbft.com/v1/rpc/
[`/subscribe` endpoint]: https://docs.cometbft.com/v1/rpc/#/Websocket/subscribe
[autogen-fixtures]: https://github.com/informalsystems/tendermint-rs/issues/612