> For the complete documentation index, see [llms.txt](https://docs.fast.poker/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.fast.poker/integrations/indexer-integration.md). # Indexer integration Use this guide if you want to run or build a Fast Poker indexer. An indexer is a read-side service. It watches protocol state, reconstructs useful views, and serves fast APIs for frontends, analytics, profile pages, leaderboards, and community tools. It does not custody funds, sign transactions, or replace Solana as the source of truth. Reference source: `https://github.com/FastPoker/indexer` ## What an indexer is for | Surface | Why index it | | -------------- | ----------------------------------------------------------------------------------------- | | Table lists | Avoid expensive repeated program scans from every browser. | | Hand history | Reassemble hand reports and expose player-friendly history views. | | Player stats | Aggregate hands, results, tournaments, earnings, and active tables. | | Jackpots | Track jackpot receipts and wallet/table attribution. | | Flat Bounty | Track point transfers, fractional holdings, scheduled duel stages, and final maturity. | | SNG settlement | Index per-game record finalization/payment without replacing chain balances as authority. | | Leaderboards | Serve ranked views without forcing every client to rescan history. | | Live updates | Fan out table, SNG, token, and jackpot events to clients. | ## What an indexer must not do * Do not sign player transactions. * Do not custody player funds. * Do not become the authority for balances or settlement. * Do not require users to trust private database rows for fund safety. * Do not depend on public/free Solana RPC for production operation. ## Required infrastructure | Requirement | Notes | | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | MongoDB | Required by the current indexer implementation. SQLite is not supported in this release. | | Paid/dedicated Solana RPC | Required for history, account reads, backfill, and safety reseeds. Free public RPC is not enough. | | WebSocket RPC | Required unless your provider's websocket endpoint can be derived from the HTTP RPC URL. | | Stream provider | Required for production FULL/live indexing. Optional only for local smoke tests. The bundled adapter is LaserStream/Geyser-compatible; the base `RPC_URL` is provider-neutral. | | Node 20+ | Required for the current Node-based indexer implementation. | ## Data model The current indexer stores chain-derived data in MongoDB collections such as: * `tables` * `hands` * `hand_reports` * `players` * `earnings` * `rake_ledger` * `tournaments` * `jackpot_receipts` * cursor/checkpoint state If you build your own indexer, keep the same principle: store derived reads and checkpoints, but reconcile important user-facing claims back to Solana. ## Ingestion model A Fast Poker indexer usually combines: | Path | Purpose | | ---------------------- | ------------------------------------------------------------------------------------------ | | Historical backfill | Catch up existing tables, hand reports, jackpot receipts, and player history. | | Live account stream | Keep active table, SNG pool, token registry, and jackpot state fresh. | | SNG sidecars | Follow delegated/L1 `SngDuelState` and transient `SngSettlementRecord` lifecycles. | | Hand-report events | Decode the fixed SNG duel event stages and point-transfer flag beside normal hand reports. | | Safety polling/reseeds | Heal missed stream events and provider interruptions. | | API cache | Serve read-heavy frontend screens quickly. | The current indexer can use an enhanced transaction-history method when a provider supports it, then fall back to standard Solana RPC history methods when it does not. That keeps `RPC_URL` provider-neutral while still allowing faster providers to be faster. ## Helius and free-tier expectations Helius is one possible provider, not a required provider. A free Helius key can work for local smoke tests, but current free-tier limits are intentionally small: low RPC request rate, low `getProgramAccounts` rate, standard LaserStream WebSocket methods, and no mainnet LaserStream gRPC. The current public indexer stream adapter expects a LaserStream/Geyser-compatible endpoint through `STREAM_ENDPOINT` and `STREAM_API_KEY`. If stream settings are blank, the indexer can still seed and reseed caches through RPC, but those caches can lag. Use that mode for development only. Production FULL mode requires a paid/dedicated RPC and a stream provider sized for your traffic. ## Indexer quickstart ```bash npm ci cp .env.example .env # edit .env before starting npm run start ``` Minimum `.env` shape: ```bash MONGO_URI=mongodb://localhost:27017 MONGO_DB=fastpoker_indexer RPC_URL=https://your-dedicated-mainnet-rpc.example RPC_WS_URL=wss://your-dedicated-mainnet-rpc-websocket.example PROGRAM_ID=PokerXYdXL2SKNnfGbv1WE7vJHipTpNsfZbZeVvoJLn INDEXER_PORT=3001 ``` Optional live stream settings: ```bash STREAM_PROVIDER=laserstream STREAM_ENDPOINT=https://your-stream-endpoint.example STREAM_API_KEY=YOUR_STREAM_KEY ``` Run a historical catch-up when needed: ```bash npm run backfill ``` ## Frontend wiring A frontend should opt into indexed reads explicitly: ```bash NEXT_PUBLIC_ENABLE_INDEXER=true INDEXER_BASE_URL=http://localhost:3001 NEXT_PUBLIC_INDEXER_WS_URL=ws://localhost:3001/ws ``` `INDEXER_BASE_URL` is a server-side URL used by the web process. The websocket URL must be browser-reachable if the frontend uses live push. ## API shape Common read surfaces include: * Health and metrics. * Live table lists and raw table account cache. * SNG pool snapshots. * Listed token snapshots. * Hand reports by table and hand number. * Player stats, earnings, hands, tournaments, and active tables. * Jackpot recent feed, wallet feed, and leaderboard. * Flat Bounty point/duel timeline and final maturity. * Settlement-record status and per-game payout delta, with live Player/Steel reads for cumulative claimables. * WebSocket topics for live client updates. Treat these APIs as convenience surfaces. For balances, vaults, settlement, and claim safety, verify against Solana accounts and transaction results. ## Builder checklist * Use MongoDB or design your own storage layer deliberately. * Use a paid/dedicated RPC; do not run production indexing on public/free RPC. * Store checkpoints so backfills can resume. * Keep stream ingestion and safety polling idempotent. * Expose read-only APIs. * Keep secrets server-side. * Document which data is derived and which data is verified directly from Solana.