Wallet indexer — Quick guide

A fast, read-only wallet-history backend for Blurt. It indexes wallet-relevant blockchain operations into PostgreSQL and serves them to the wallet through a small JSON-RPC API, so history and reward screens paint instantly instead of paginating many chain-history calls in the browser.

It is an optional accelerator

The wallet indexer never touches consensus, blurtd, or public RPC behavior. Any wallet that uses it keeps a transparent fallback to the chain node, so nothing breaks if the service is absent or behind. It makes the wallet faster; it is never a hard dependency.

Where it sits

  blurtd  ──►  wallet-indexer  ──►  PostgreSQL  ──►  wallet-api  ──►  wallet
 (source)      (decode & write)     (events)        (read-only)      (front-end)

• wallet-indexer tails blocks from a blurtd node, decodes wallet-relevant operations (transfers, reward and vesting events, …) into normalized per-account events, and writes them to PostgreSQL with a resumable checkpoint.
• wallet-backfill loads historical blocks in parallel to populate a fresh database.
• wallet-api exposes a read-only JSON-RPC API over the same store. It never writes, signs, or broadcasts.

The wallet reaches the API through the same RPC endpoint it already uses: the deployment routes the wallet_history.* methods to wallet-api, so there is no new origin and no separate CORS setup.

Two indexers, don't confuse them

This is the standalone wallet indexer that answers wallet_history.*. It is not the internal indexer inside nexus-go that builds feeds and communities. See Architecture for the whole picture.

What the wallet gets

• Financial history, author rewards, and curation rewards, per account.
• Server-side reward totals — no client-side summing over long lists.
• Cursor-based pagination and optional date-range filtering.
• Freshness/lag reporting (get_status) so the client can fall back when the indexer is behind.
• Normalized, pre-decoded events: one render path whether the data came from the indexer or from the chain fallback.

Run it

Requirements: Docker with Compose, and a reachable blurtd JSON-RPC endpoint.

cp docker/.env.example docker/.env
# edit docker/.env: set the database passwords and BLURT_RPC_URL

docker compose -p wallet-indexer --env-file docker/.env up -d --build

On a fresh volume this provisions the database roles, applies the schema, and starts indexing from the configured block. The API listens on the loopback address you configure; put a reverse proxy in front to expose it, and route wallet_history.* to it.

To load history quickly instead of indexing from genesis, start the live tail at a recent block and populate the past separately with the backfill loader — see the Reference for the ingestion and configuration details.

Where it fits in the stack

The wallet indexer is a backend service derived from the chain, alongside nexus-go. Front-ends never talk to it directly: they reach it through the RPC proxy, which routes wallet_history.* to this service and everything else to the node or nexus-go. That is exactly how the social UIs consume nexus-go.

Next

• Reference — architecture, the full API contract, configuration, and the security posture.
• Source: blurt/blurt-wallet-indexer.