HotShot Query Service

The HotShot Query Service is a minimal, generic query service that can be integrated into any decentralized application running on the HotShot consensus layer. It provides all the features that HotShot itself expects of a query service (such as providing consensus-related data for catchup and synchronization) as well as some application-level features that deal only with consensus-related or application-agnostic data. In addition, the query service is provided as an extensible library, which makes it easy to add additional, application-specific features (such as a JSON-RPC service in the case of an EVM application).

Features

• Provides a query interface to a persistent store containing the history of a blockchain (represented as a chain of HotShot leaves)
• Provides a query interface for validator status and metrics
• Integrates with HotShot to populate the persistent database
• Generic over application types (within a leaf, the block and block commitment can be any type the application specifieds)
• Transparently handles asynchronous data availability — block commitments are provided as soon as they are committed by consensus; block data is provided once it has disseminated from the data availability committee; missing data is fetched asynchronously from other nodes
• Serves as a source of data for HotShot catchup
• Easily extensible with application-specific functionality

Development

git clone git@github.com:EspressoSystems/hotshot-query-service
cd hotshot-query-service

Environment

We recommend installing dependencies with the nix package manager, which will ensure you use the same Rust version and related tools as everyone else using a Nix environment (including the CI system). If you prefer not to use Nix, you should still be able to build the project with the normal rustup-installed toolchain, and you can skip this section.

Install nix

Installation instructions can be found here. If in a rush, running the following command and following the on-screen instructions should work in most cases

curl -L https://nixos.org/nix/install | sh

Activate the nix environment

To activate a shell with the development environment run

nix-shell

from within the top-level directory of the repo.

Note: for the remainder of this README it is necessary that this environment is active.

direnv (optional, but recommended for development)

To avoid manually activating the nix shell each time, the direnv shell extension can be used to activate the environment when entering the local directory of this repo. Note that direnv needs to be hooked into the shell to function.

To enable direnv run

direnv allow

from the root directory of this repo.

Building and testing

Once you have Cargo installed (either via Nix or Rustup) you can build the project with cargo build or cargo build --release. To run unit tests, we recommend using

cargo test --release --all-features

You can also run unit tests using the development profile, but without the optimizations of the release profile, some stack sizes exceed the default Rust stack. Therefore, you will need to configure a default stack size to run the development build. 3MB seems to work well:

RUST_MIN_STACK=3145728 cargo test --all-features

Doctest

Doctests require the testing feature. Due to a limitation of doctest it is recommended to run doctests via

cargo test --doc --features testing