Namada Indexers

There are two actively maintained indexers built for Namada -- Undexer and namada-indexer.

Undexer

Undexer (opens in a new tab) is a community-led project developed by the Mandragora and HackBG teams. It indexes transaction details, validator set updates, governance proposals and more, and serves the indexed data via a REST api.

Detailed installation and usage instructions for Undexer can be found on the project's repo (opens in a new tab).

Namada-Indexer

The namada-indexer (opens in a new tab) crawls a Namada blockchain to map details such as transactions, validator set updates, POS rewards, governance proposals and more. It stores the results in a Postgres database where it can be queried via a REST api.

Namada-indexer was created to power the Namadillo interface; however it can be generally useful for any application that needs to query historical data or perform analytics over the blockchain.

The remainder of this page will detail the process of configuring, running, and querying namada-indexer.

Setting up

The namada-indexer source code can be found here (opens in a new tab).

It's recommended to use Docker/Docker Compose (opens in a new tab) to run the indexer.

Prerequisites

(required): an available Namada RPC node
(required): Docker and Docker Compose (opens in a new tab)
(optional but recommended): Just (opens in a new tab) -- see the project's README for installation instructions for your system

RPC configuration

To configure your RPC node to serve historical data to the indexer, you will need to open its config.toml file (located in ~/.local/share/namada/$CHAIN_ID by default) and find the setting storage_read_past_height_limit. Change the default value of 3600 to an appropriately high number.

If you see the following error in your logs when running the indexer, it indicates that you have this value configured too low:

Info log: RPC error: Cannot query more than 3600 blocks in the past (configured via `shell.storage_read_past_height_limit`)., error code: 1

Running the indexer

The following steps will help you configure and run namada-indexer.

Clone repo

Begin by cloning the indexer repo:

git clone https://github.com/anoma/namada-indexer.git
cd namada-indexer

Set environment variables

The indexer configuration is stored in its .env file, found in the base directory of the repo. Refer to .env_sample to see which values can be set.

Create that file now:

cp .env_sample .env

It will have the following default values:

DATABASE_URL=postgres://postgres:password@postgres:5432/namada-indexer
TENDERMINT_URL=http://host.docker.internal:27657
CACHE_URL=redis://dragonfly:6379
WEBSERVER_PORT=5000

Change the value of TENDERMINT_URL to the url of your RPC node.

(Recommended) Change Postgres username and password

The default username and password (postgres and password respectively) will work for local development, however they should be changed if your indexer will be publicly accessible.

First, open the file docker-compose-db.yml and change the default values to something more secure:

environment:
  POSTGRES_PASSWORD: NEW_PASSWORD
  POSTGRES_USER: NEW_USERNAME
  PGUSER: NEW_USERNAME
  POSTGRES_DB: namada-indexer

Then, update the Postgres url in your .env file with the new values.

The schema for the url is postgres://{user_name}:{password}@{host}:{port}/{database_name}

DATABASE_URL=postgres://NEW_USERNAME:NEW_PASSWORD@postgres:5432/namada-indexer

Build the containers

Build the indexer containers by running:

docker compose build

Instead of building yourself, you can check the repo's container registry (opens in a new tab) for recent images.

Start the indexer

Start all indexer containers with this command:

just docker-up

You can expect to see some database connection errors in the logs during the time the database is being initialized -- these are normal and will resolve within a couple minutes.

Assuming you want to keep the indexer running persistently in the background, you will likely want to perform this step using something like screen or tmux.

Eg. In Ubuntu, using screen:

Start a new screen session: screen -S indexer
Start the indexer: just docker-up
Detach from the session, allowing it to run in the background: Press Ctrl+A and then d
To re-attach to the session at a later time: screen -d -r indexer

Stop the indexer with Ctrl+c. Remove all associated data with docker compose down --volumes.

REST API

Once the indexer has been started, the webserver container will serve requests at the port given by WEBSERVER_PORT in the .env file.

Available endpoints are documented in the swagger.yml file inside the repo.

Eg. to query the latest indexed block:

curl localhost:5000/api/v1/chain/block/latest

# response
{"block":"163445"}

Querying the database

You can also query the Postgres database directly.

Eg. to perform a simple query using pgcli on Ubuntu:

Install `pgcli`

sudo apt install pgcli

Connect to the database

(If you changed your Postgres username and/or password above, use the updated values.)

pgcli postgres://postgres:password@localhost:5435/namada-indexer

Run a query

Eg. Find a wrapper transaction by its hash:

SELECT * FROM wrapper_transactions WHERE id = 'cece56db36322f9b0728a0f2e127ef33c410a9fab74e2b9e135f97903c6c2c4e';

If you prefer to use a GUI, there are many free options available such as Beekeeper Studio (opens in a new tab) and pgAdmin (opens in a new tab).

Examples Namada Interface