Indexer

Overview

Users of Kwil networks want to be able to index network data and display it via a block explorer. This document outlines what should be included in the indexer. As more requirements are identified, phases in which they should be implemented will be added.

The indexer should be a Golang webserver built on Postgres. Data should be accessible via a REST API.

Phase 0

Phase 0 will be to simply build a CometBFT indexer. This will be built around CometBFT's RPC. The indexer should be able to be configured with a CometBFT RPC endpoint.

Metadata

It should track chain metadata, including:

• Chain ID
• Chain Version

Tables

It should index two tables, with the following columns (other columns and/or indexes may be added as the implementer sees fit, but these are core requirements):

• blocks
  • height (index should optimize for querying latest latest heights)
  • hash
  • proposer
  • app_hash
• transactions
  • block_height
  • sender
  • transaction_status (right now this can just be success/failure, but later we will support pending for mempool txs)
  • logs
  • gas_used
  • transaction body
  • index (which tx number this tx was in its respective block)

CometBFT RPCs

Some helpful RPCs from CometBFT's RPCs that will likely be used:

• /status
• /header
• /tx_search

API

The indexer should support the following APIs (all of these should bet GET). The implementer may decide if these should be broken down into smaller, simpler endpoints with less query-ability. The implementer should also support pagination, which is not covered below:

• /info- returns network info, such as chain ID and version
• /block- allows querying for blocks by:
  • height range (e.g. heights 100-200)
  • block producer
  • can be ordered by:
    • height (asc/desc)
• /tx- allows querying for transactions by:
  • block height (range)
  • sender
  • can be ordered by:
    • block height (asc/desc)

Config

The indexer should be configurable using command line flags.

The indexer should support the following configurations:

• pg-connection: a postgres connection string, for the underlying database.
• cometbft-endpoint: a cometbft endpoint.
• listen-address: the address on which the REST API will listen.
• poll-frequency: the frequency (in seconds) that the indexer should poll the node for changes. Default should be 5.
• max-block-pagination: the maximum number of records that can be included in a page from the /block endpoint. Default should be 30.
• max-tx-pagination: the maximum number of records that can be included in a page from the /tx endpoint. Default should be 30.

The implementer may add additional configuration as they see fit.