Join our community of builders on Discord!

Worker API

An event-driven indexer and API layer for Lightchain AI worker activity. It watches on-chain events, stores derived entities in PostgreSQL, and serves the indexed data through Express and GraphQL.

Architecture Overview

At runtime, the service works like this:
CodeTEXT
Startup flow:
  1. CodeHTML
    loads environment variables and the GraphQL schema.
  2. A
    CodeHTML
    instance is created with
    CodeHTML
    .
  3. The EVM indexers are registered.
  4. Checkpoint starts polling configured contracts.
  5. Express serves REST routes under
    CodeHTML
    and GraphQL at
    CodeHTML
    .

What The Service Indexes

The current indexer watches three contracts:
  • CodeHTML
  • CodeHTML
  • CodeHTML
Current network config in the repository:
ParameterValue
Chain ID
CodeHTML
Chain name
CodeHTML
Native token
CodeHTML
Fetch interval
CodeHTML
Optimistic indexing
CodeHTML
Contract addresses and start blocks are still hardcoded in src/evm/config.ts. The repo ships with placeholder values and must be updated before real indexing will work.

Prerequisites

Before starting the service, make sure you have:
  • Bun
    CodeHTML
  • PostgreSQL
  • an RPC endpoint for the intended Lightchain AI-compatible chain
The project is Bun-first, even though the repository also contains
CodeHTML
.

Local Setup

1. Install dependencies

CodeBASH

2. Create your environment file

CodeBASH
Current environment variables:
VariableRequiredPurpose
CodeHTML
YesPostgreSQL connection string
CodeHTML
NoExpress port, defaults to
CodeHTML
CodeHTML
YesEVM RPC endpoint used by the indexer
Example:
CodeENV

3. Update contract config

Before indexing real chain data, replace the placeholders in
CodeHTML
:
  • CodeHTML
  • CodeHTML
  • CodeHTML
  • CodeHTML
  • CodeHTML
  • CodeHTML

4. Generate Checkpoint models

CodeBASH
This generates
CodeHTML
from
CodeHTML
.

5. Start the service

Development mode:
CodeBASH
Production-style build:
CodeBASH

Package Scripts

CommandWhat it does
CodeHTML
Runs
CodeHTML
CodeHTML
Runs codegen, then starts the app in watch mode
CodeHTML
Generates models and compiles TypeScript into
CodeHTML
CodeHTML
Starts the compiled server from
CodeHTML

Indexed Event Coverage

CodeHTML

  • CodeHTML
  • CodeHTML
  • CodeHTML
  • CodeHTML
  • CodeHTML
  • CodeHTML
  • CodeHTML
  • CodeHTML
  • CodeHTML
  • CodeHTML

CodeHTML

  • CodeHTML
  • CodeHTML
  • CodeHTML
  • CodeHTML
  • CodeHTML
  • CodeHTML
  • CodeHTML
  • CodeHTML
  • CodeHTML
  • CodeHTML
  • CodeHTML

CodeHTML

  • CodeHTML
  • CodeHTML
  • CodeHTML

Data Model

The GraphQL schema lives in
CodeHTML
. Main entities:
EntityPurpose
CodeHTML
Current worker state and counters
CodeHTML
Worker-to-model relationship
CodeHTML
Indexed job lifecycle state
CodeHTML
Session-level grouping of jobs
CodeHTML
Slash records with best-effort correlation
CodeHTML
Dispute state for a job
CodeHTML
Global counters
CodeHTML
Per-model whitelist and config state
Important identifier semantics:
  • CodeHTML
    is the worker address
  • CodeHTML
    is
    CodeHTML
  • CodeHTML
    is the stringified on-chain
    CodeHTML
  • CodeHTML
    is the stringified on-chain
    CodeHTML
  • CodeHTML
    is always
    CodeHTML
  • CodeHTML
    is
    CodeHTML

REST API

CodeHTML

Returns:
CodeJSON

CodeHTML

Returns:
CodeJSON
Current behavior:
  • the request body is unused
  • the route does not write to the database
  • it simply calls
    CodeHTML
    and returns the result

GraphQL Usage

Checkpoint mounts GraphQL at
CodeHTML
. Use
CodeHTML
as the source of truth for available entity types, then inspect the live GraphQL schema after startup to see the generated root queries, filters, and pagination arguments. In practice, the GraphQL API is centered on:
  • CodeHTML
  • CodeHTML
  • CodeHTML
  • CodeHTML
  • CodeHTML
  • CodeHTML
  • CodeHTML
  • CodeHTML

Derived Behavior To Know About

Some values in the API are derived rather than directly stored on-chain.

Worker status

The code derives worker status from:
  • CodeHTML
  • CodeHTML
  • CodeHTML
Practical interpretation:
StatusCondition
Online
CodeHTML
Offline
CodeHTML
Jailed
CodeHTML
Deregistered
CodeHTML

Slash correlation

The writer layer keeps an in-memory correlation map so a
CodeHTML
record can be linked to:
  • CodeHTML
  • CodeHTML
If that correlation is not available, the extra slash metadata remains
CodeHTML
.

Global counters

CodeHTML
is updated incrementally by handlers. It is not recomputed from scratch.

Known Caveats

These are current implementation realities:
  1. Online detection is stubbed.
    CodeHTML
    currently returns
    CodeHTML
    for every worker.
  2. Contract config is not environment-driven. Addresses and start blocks are hardcoded in
    CodeHTML
    .
  3. CodeHTML
    removals are not persisted as removals.
    CodeHTML
    updates the worker timestamp, but does not delete or deactivate the
    CodeHTML
    record.
  4. Some
    CodeHTML
    fields are placeholders.
    CodeHTML
    and
    CodeHTML
    are initialized, but are not populated from indexed events in the current implementation.
  5. CodeHTML
    is only partially modeled. Sessions are created as
    CodeHTML
    and are not fully transitioned through every on-chain state.
  6. Slash correlation is in-memory. A process restart can break same-block correlation between related events.
  7. There is no committed test suite yet. Changes should be validated manually or covered with new tests.
The API is useful today, but it should be treated as an evolving indexer rather than a finalized production data contract.

Common Maintenance Tasks

Add a new indexed event

  1. Update the ABI under
    CodeHTML
    if needed.
  2. Add the event mapping in
    CodeHTML
    .
  3. Implement the writer in
    CodeHTML
    .
  4. If the schema changes, update
    CodeHTML
    and rerun
    CodeHTML
    .

Replace the online check

Implement the real availability logic in
CodeHTML
. Current function contract:
CodeTYPESCRIPT

Move contract config to environment variables

If you want deployable environments without source edits:
  1. Read contract addresses and start blocks from
    CodeHTML
    .
  2. Extend
    CodeHTML
    .
  3. Validate those values near the top of
    CodeHTML
    .

Troubleshooting

CodeHTML
is missing

Run:
CodeBASH

The service starts but no data appears

Check these first:
  • CodeHTML
    points to the intended chain
  • the contract addresses are real
  • the configured start blocks are correct
  • PostgreSQL is reachable through
    CodeHTML

REST works but GraphQL is empty

That usually means Express is healthy but the indexer is not ingesting events. In this repository, the most common causes are:
  • placeholder contract config
  • RPC issues
  • database connectivity issues

Related Guides

Last updated: March 2026