Primodium Indexer

Primodium Indexer

The Primodium Indexer is an off-chain indexer implementation compliant with the open MUD standard (opens in a new tab). It comprises two separate npm packages with source (opens in a new tab) released under the MIT License.

Overview

All game state Primodium is stored fully on-chain within smart contracts structured around the open MUD standard. While state can be entirely fetched from an Ethereum node for the chain that Primodium is deployed on, the state cannot be efficiently queried. For context, in v0.9.0, querying the full state of the two-month-long round directly from the node via an RPC endpoint could take upwards of an hour.

Previous versions of Primodium used a hosted off-chain indexer (opens in a new tab) implemented by Lattice. Since state in Primodium is global across all players instead of round-based, initializing the Primodium client requires fetching the entire state from the off-chain indexer.

The default indexer implementation required a fallback for hydrating the state from RPC; however, state fetched from nodes via RPC cannot be selectively queried, which meant that state had to be fetched in whole by the off-chain indexer on initialization. Past a certain state size, the off-chain indexer container would run out of memory and always fall back to fetching from RPC.

The latest version of Primodium implements this off-chain indexer to address the above issues. Instead of fetching state directly from MUD-compliant contracts, this package suite always assumes the availability of a schemaful Postgres database that contains MUD-compliant state with no RPC fallback.

Deployment

See the Github Container Registry (opens in a new tab) for the latest Docker builds of @primodiumxyz/pg-indexer-read.

Additionally, @primodiumxyz/pg-indexer-read requires an existing schemaful Postgres database that conforms to the open MUD standard in production. Therefore, this package is best paired with the postgres-indexer (opens in a new tab) in @latticexyz/store-indexer, with its latest Docker builds available here (opens in a new tab).

The following is a sample YAML deployment of the above indexer architecture.

version: "3.8"
 
services:
  primodium-postgres:
    image: postgres:16.1
    restart: always
    platform: linux/amd64
    networks:
      - primodium-indexer
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: password
    volumes:
      - /home/ubuntu/postgresql/data:/var/lib/postgresql/data
 
  # @latticexyz/store-indexer
  primodium-postgres-index-write:
    image: ghcr.io/latticexyz/store-indexer:sha-735d957
    restart: always
    platform: linux/amd64
    networks:
      - primodium-indexer
    environment:
      RPC_HTTP_URL: https://primodium-bedrock.calderachain.xyz/replica-http
      DEBUG: "mud:*"
      DATABASE_URL: postgres://postgres:password@primodium-postgres/postgres
    command: pnpm tsx bin/postgres-indexer
 
  # @primodiumxyz/pg-indexer-read
  primodium-postgres-query-read:
    image: ghcr.io/primodiumxyz/pg-indexer-reader:sha-6ce624a
    restart: always
    platform: linux/amd64
    networks:
      - primodium-indexer
    environment:
      RPC_HTTP_URL: https://primodium-bedrock.calderachain.xyz/replica-http
      DEBUG: "mud:*"
      DATABASE_URL: postgres://postgres:password@primodium-postgres/postgres
    ports:
      - "3001:3001"
    command: pnpm tsx bin/postgres-frontend
 
networks:
  primodium-indexer:
    driver: bridge

After deploying a test or production indexer instance, the @primodiumxyz/sync-stack package can be used to hydrate and selectively query state from the new indexer. See its corresponding README.md (opens in a new tab) for more information.

Upgrade BountyPrimodium Game Tools