Dubhe Rust Indexer

dubhe-indexer is a high-performance Rust binary that listens to Sui blockchain events emitted by your Dubhe contract and writes them into a PostgreSQL database. It exposes a built-in GraphQL endpoint and a gRPC endpoint for querying indexed data in real time.

How it works

The indexer is event-driven — it processes the events emitted by the Dubhe framework and writes them into PostgreSQL. All Dubhe events are emitted by the framework package (not your DApp package); the indexer keeps only those whose dapp_key matches your config, and for resource tables, only those listed in your dubhe.config.json.

In v2 the indexer handles far more than the three core Store events — it also tracks the extended storage (objects/scenes), scene permits, the marketplace, session keys, and DApp runtime/fee/revenue state. The full event → table mapping:

Event family	Events	Destination table(s)
Store (records)	`StoreSetRecord`, `StoreSetField`, `StoreDeleteRecord`, `StoreDeleteField`	your resource tables (`player`, `stats`, …)
User storage	`UserStorageCreated`	`user_storages`
Object storage	`ObjectCreated`, `ObjectDestroyed`, `ObjectSetField`, `ObjectDeleteField`	`object_storages`, `object_storage_fields`
Scene storage	`SceneCreated`, `SceneDestroyed`, `SceneSetField`, `SceneDeleteField`	`scene_storages`, `scene_storage_fields`
Scene permits	`ScenePermitCreated`, `ScenePermitAccept`, `ScenePermitJoin`, `ScenePermitLeave`, `ScenePermitExpire`	`scene_permits`, `scene_permit_participants`
Marketplace	`ItemListed`, `ItemSold`, `ListingCancelled`, `ListingExpired`	`marketplace_listings`
Session keys	`SessionActivated`, `SessionDeactivated`	`sessions`
DApp runtime	`DappCreated`, `DappUpgraded`, `CreditRecharged`, `DappPausedChanged`, `DappRuntimeUpdate`, `DappRevenueShareSet`	`dapp_runtime_state`
Fees / revenue	`MarketplaceFeeSettled`, `DappFeeStateUpdated`, `DappRevenueStateUpdated`	`dapp_marketplace_fees`, `dapp_fee_state`, `dapp_revenue_state`

Your own resource tables still require a matching entry in dubhe.config.json. The framework system tables above are created and populated automatically — no config needed.

Important: The indexer can only process events it has seen. If start_checkpoint in dubhe.config.json is set later than your deployment checkpoint, events before that point are permanently missed and will not appear in the database.

Installation

Install dubhe-indexer using the Dubhe CLI:

pnpm dubhe doctor

The doctor command checks your environment and installs required binaries, including dubhe-indexer. You can also download the binary directly from GitHub releases.

Prerequisites

PostgreSQL — the indexer stores all indexed data in PostgreSQL.
dubhe.config.json — generated from dubhe.config.ts via dubhe convert-json.
A running Sui node or access to a remote checkpoint store (testnet/mainnet).

Configuration file

Generate dubhe.config.json from your TypeScript config before starting the indexer:

dubhe convert-json --config-path dubhe.config.ts --output-path dubhe.config.json

The JSON file must include start_checkpoint — the checkpoint from which the indexer begins reading. Set it to the checkpoint at or just before your contract was deployed:

{
  "name": "my_game",
  "description": "My on-chain game",
  "packageId": "0x123...",
  "originalPackageId": "0x123...",
  "start_checkpoint": "1000000",
  "resources": {
    "level": "u32",
    "stats": {
      "fields": { "attack": "u32", "hp": "u32" }
    }
  }
}

start_checkpoint is read from the config file. The --first-checkpoint CLI argument is present in --help output but is not used by the current binary — always set it in dubhe.config.json.

CLI reference

dubhe-indexer [OPTIONS]

Options:
  -c, --config-json <PATH>       Path to dubhe.config.json         [default: dubhe.config.json]
      --database-url <URL>       PostgreSQL connection string       [default: postgres://postgres@localhost:5432/postgres]
      --checkpoint-url <URL>     Checkpoint source: local directory (e.g. .chk) or
                                 remote http URL (e.g. https://checkpoints.testnet.sui.io)
                                                                    [default: .chk]
      --use-rpc-ingestion        Use gRPC to fetch checkpoints from --rpc-url instead
                                 of local path / remote store       [default: false]
      --rpc-url <URL>            gRPC endpoint (used with --use-rpc-ingestion)
                                                                    [default: http://localhost:9000]
      --port <PORT>              Proxy server port (GraphQL + gRPC via proxy, health, playground)
                                                                    [default: 8080]
      --grpc-port <PORT>         Direct gRPC backend port           [default: 8085]
      --graphql-port <PORT>      Independent GraphQL backend port   [default: 8089]
      --force                    Clear the database before starting [default: false]

Service ports

When the indexer starts, it launches three services:

Service	Default port	Description
Proxy server	8080	Serves `/graphql`, `/playground`, `/health`, `/metadata`, `/welcome`; forwards gRPC requests
gRPC backend	8085	Direct gRPC endpoint for `DubheGrpcClient`
GraphQL backend	8089	Independent PostGraphile GraphQL service

For most use cases, connect your client to the proxy at port 8080:

GraphQL queries: http://localhost:8080/graphql
GraphQL playground: http://localhost:8080/playground
gRPC (via proxy): http://localhost:8080 (prefix /dubhe_grpc.*)
Direct gRPC: http://localhost:8085

--grpc-port and --graphql-port must be different values. The binary exits immediately if they match.

Checkpoint sources

The --checkpoint-url argument controls where the indexer reads checkpoints from:

Value	Source	When to use
`.chk` (default)	Local directory	Localnet — the directory where `dubhe node` writes checkpoint files
`https://checkpoints.testnet.sui.io`	Remote store	Testnet
`https://checkpoints.mainnet.sui.io`	Remote store	Mainnet
`--use-rpc-ingestion` + `--rpc-url`	gRPC from a full node	When you have a full node with gRPC checkpoint API

Localnet

Use pnpm dubhe node to start the local Sui node. It writes checkpoint files to .chk by default, and the indexer reads from .chk by default — no extra flags needed:

# Terminal 1: start local node (writes checkpoints to .chk)
pnpm dubhe node
 
# Terminal 2: start indexer (reads from .chk by default)
dubhe-indexer \
  --config-json dubhe.config.json \
  --database-url postgres://postgres:postgres@localhost:5432/postgres

To clear the database and start fresh (useful after redeploying):

dubhe-indexer \
  --config-json dubhe.config.json \
  --database-url postgres://postgres:postgres@localhost:5432/postgres \
  --force

Testnet / Mainnet

Pass the remote checkpoint store URL via --checkpoint-url:

# Testnet
dubhe-indexer \
  --config-json dubhe.config.json \
  --checkpoint-url https://checkpoints.testnet.sui.io \
  --database-url postgres://user:password@localhost:5432/dubhe_prod
 
# Mainnet
dubhe-indexer \
  --config-json dubhe.config.json \
  --checkpoint-url https://checkpoints.mainnet.sui.io \
  --database-url postgres://user:password@localhost:5432/dubhe_prod

Framework system tables

Beyond your own resource tables, the indexer auto-creates and maintains a set of framework system tables. These hold the extended storage, marketplace, session, and DApp runtime state, and are queryable just like resource tables. In GraphQL they are exposed under dubhe-prefixed camelCase plural field names (via PostGraphile), and most have a dedicated typed helper on the GraphQL client.

PostgreSQL table	GraphQL field	Client helper	Holds
`user_storages`	`dubheUserStorages`	`getDubheUserStorages`	per-user registrations (canonical owner, session key, …)
`object_storages`	`dubheObjectStorages`	`getObjectStorages`	`ObjectStorage<T>` named entities (guilds, bosses)
`object_storage_fields`	`dubheObjectStorageFields`	—	object field values
`scene_storages`	`dubheSceneStorages`	`getSceneStorages`	`SceneStorage<T>` scene metadata (PvP matches, dungeons)
`scene_storage_fields`	`dubheSceneStorageFields`	`getSceneStorageFields`	scene field values
`scene_permits`	`dubheScenePermits`	—	`ScenePermit<T>` objects
`scene_permit_participants`	`dubheScenePermitParticipants`	—	permit participants
`marketplace_listings`	`dubheMarketplaceListings`	`getMarketplaceListings`	active/closed marketplace listings
`sessions`	`dubheSessions`	`getDubheSessions`	active/expired session keys
`dapp_runtime_state`	`dubheDappRuntimeStates`	—	admin, version, credit pool, paused/suspended flags
`dapp_marketplace_fees`	`dubheDappMarketplaceFees`	—	settled marketplace fees
`dapp_fee_state`	`dubheDappFeeState`	—	write-fee parameters and settled totals
`dapp_revenue_state`	`dubheDappRevenueState`	—	accrued DApp revenue

Tables without a dedicated helper are still queryable with getAllTables('<dubheGraphqlField>', …). See GraphQL Client for the typed helpers.

Querying indexed data

GraphQL client

import { createDubheGraphqlClient } from '@0xobelisk/graphql-client';
 
const client = createDubheGraphqlClient({
  endpoint: 'http://localhost:8080/graphql',
  subscriptionEndpoint: 'ws://localhost:8080/graphql'
});
 
// Your own resource table
const players = await client.getAllTables('player', {
  filter: { hp: { greaterThan: '50' } },
  orderBy: [{ field: 'hp', direction: 'DESC' }],
  first: 10
});
 
// Framework system tables — typed helpers
const scenes = await client.getSceneStorages({ dappKey, sceneType: 'pvp_match', first: 50 });
const guilds = await client.getObjectStorages({ dappKey, objectType: 'guild' });
 
// Or any system table generically by its GraphQL field name
const runtime = await client.getAllTables('dubheDappRuntimeState', { first: 1 });

gRPC client

import { DubheGrpcClient } from '@0xobelisk/grpc-client';
 
const grpc = new DubheGrpcClient({ baseUrl: 'http://localhost:8085' });
 
const result = await grpc.dubheGrpcClient.queryTable({
  tableId: 'player',
  filters: [],
  pagination: { page: 0, pageSize: 20 }
});

Via `createClient`

If you use @0xobelisk/client, both clients are created automatically:

import { createClient } from '@0xobelisk/client/sui';
 
const { graphqlClient, grpcClient } = createClient({
  network: 'localnet',
  packageId: PackageId,
  metadata,
  endpoints: {
    graphql: 'http://localhost:8080/graphql',
    grpc: 'http://localhost:8085'
  }
});

Monitoring and troubleshooting

Logging

# Info level (recommended)
RUST_LOG=info dubhe-indexer --config-json dubhe.config.json --database-url ...
 
# Debug level (verbose)
RUST_LOG=debug dubhe-indexer --config-json dubhe.config.json --database-url ...

Common issues

No data indexed, no errors

Check that start_checkpoint in dubhe.config.json is at or before the checkpoint of your contract deployment.
Check that originalPackageId matches the package ID from your first deployment (not an upgraded package ID).
Check that resource names in dubhe.config.json match the table names emitted by the contract.

Database connection refused

Verify PostgreSQL is running: pg_isready -h localhost.
Pass the connection string via --database-url, not via an environment variable — the indexer binary reads only the CLI argument.

Checkpoints not arriving (localnet)

Confirm pnpm dubhe node is running and writing to the .chk directory.
If you restarted the node, run with --force to clear stale data.

Production deployment

Docker

FROM ubuntu:22.04
 
RUN apt-get update && apt-get install -y ca-certificates && rm -rf /var/lib/apt/lists/*
 
COPY dubhe-indexer /usr/local/bin/dubhe-indexer
RUN chmod +x /usr/local/bin/dubhe-indexer
 
COPY dubhe.config.json /app/dubhe.config.json
WORKDIR /app
 
CMD ["dubhe-indexer", \
     "--config-json", "dubhe.config.json", \
     "--checkpoint-url", "https://checkpoints.mainnet.sui.io", \
     "--database-url", "postgres://user:password@db-host:5432/dubhe_prod", \
     "--port", "8080"]

Logging in production

RUST_LOG=info dubhe-indexer \
  --config-json dubhe.config.json \
  --checkpoint-url https://checkpoints.mainnet.sui.io \
  --database-url postgres://user:password@db-host:5432/dubhe_prod

GraphQL Server Production Deployment