Data service stack
The Econia data service stack (DSS) is a collection of services that provide assorted data endpoints for integration purposes. It exposes a REST API and a WebSocket server, which are powered internally by an aggregator, a database, and an indexer. To ensure composability, portability, and ease of use, each component is represented as a Docker service inside of a Docker compose environment. For more on Docker, see the official docs.
This page will show you how to run the DSS locally.
How it works
The DSS exposes a REST API and a WebSocket server.
The WebSocket server mainly provides notifications of any events emitted by the Econia Move package.
It can be addressed at
ws://0.0.0.0:3001 in the default local configuration of docker compose.
The REST API also provides all the events emitted by the Econia Move package., as well as aggregated data like order history and order book state.
It can be addressed at
http://0.0.0.0:3000 in the default local configuration of docker compose.
In order to access the WebSocket server, connect to the following URL:
[JWT] is a JSON Web Token (JWT).
You must generate the JWT yourself, see
src/python/sdk/examples/event.py for an example of how to do so.
To get a list of the different channels, please see the WebSocket server documentation.
There are two ways of running the DSS:
- Against a local chain.
- Against a public chain like Aptos devnet, testnet, or mainnet.
For continuous integration (CI) or development, running the DSS against a local chain is recommended.
This walkthrough will use the official Aptos testnet. The process is the same as running against mainnet, just with a slightly different config process.
Getting the API key
Unless you are an infrastructure provider or want to run a fullnode yourself, the simplest way to get indexed transaction data is from the Aptos Labs gRPC endpoint (indexer v2 API). To connect to this service, you'll need to get an API key here.
Generating a config
Once you have the API key, you'll need to create the processor configuration file.
A template can be found at
In the same folder as the template, create a copy of the file named
- econia_address: the testnet Econia address (
postgres://econia:econia@postgres:5432/econiaif you are using the database which comes with the Docker compose file.
https://grpc.testnet.aptoslabs.com:443for testnet. See the Aptos official documentation for other networks.
- auth_token: the key you got earlier.
- starting_version: where to start indexing.
For this walkthrough, use the first transaction of the Econia testnet account (
649555969), which is a prudent starting point that slightly precedes the publication of the Econia Move package on testnet.
starting_version that is too late will lead to missed events and corrupted data.
Hence, the complete
config.yaml file for testnet:
Similarly, for mainnet:
aptoslabs_grpc_token_or_token_for_another_grpc_endpoint for your token.
Checking out the right branch
The Econia DSS is developed on a Rust-like train schedule:
- Experimental DSS features are merged directly to
- The latest stable DSS features are merged from
Before you start working with the DSS, make sure you are on the right branch and have cloned submodules:
# From Econia repo root
git checkout dss-stable
git submodule update --init --recursive
Starting the DSS
If you've run the DSS before and want a clean build, clear your Docker containers, image cache, and volumes:
docker ps -aq | xargs docker stop | xargs docker rm
docker system prune -af
docker volume prune -af
If you want to redeploy all the same images with a fresh database, just run
docker volume prune -af to prune all Docker volumes.
From the Econia repo root, run the command corresponding to your preferred network (testnet or mainnet):
APTOS_NETWORK=testnet docker compose --file src/docker/compose.dss-global.yaml up
APTOS_NETWORK=mainnet docker compose --file src/docker/compose.dss-global.yaml up
This might take a while to start (expect anywhere from a couple minutes, to more, depending on the machine you have).
Then, to shut it down simply press
Alternatively, to run in detached mode (as a background process), simply add the
--detach flag, then to shut it down:
docker compose --file src/docker/compose.dss-global.yaml down
Verifying the DSS
Verify that the database is accessible by navigating your browser to
Once the processor has parsed all transactions up until the chain tip, then check that individual tables are visible/contain data by navigating to:
It may take up to ten minutes before the
market_registration_events_table has data in it on testnet, and several hours to fully sync to chain tip on both testnet and mainnet.
To see what transaction the DSS processor has synced through, check the logs:
docker logs docker-processor-1 --tail 5
To verify the aggregator is running:
docker logs docker-aggregator-1 --tail 5
To connect directly to the database:
Great job! You have successfully deployed Econia's DSS. You can now query port 3000 to access the REST API and port 3001 to access the WebSocket server.