rindexer Documentation

Standard JSON-RPC specs often do not expose block timestamps in log results, forcing indexers to perform an additional RPC lookup per log. rindexer uses several strategies to mitigate this bottleneck:

1. RPC Support: Leveraging node implementations (like GETH and RETH) that include timestamps directly in logs.
2. Delta Run-Length Encoding: For chains with roughly fixed block times, rindexer uses highly compressed binary files (kB to MB scale) to store "runs" of the delta between timestamps. This optimizes backfill operations.
3. Fixed Timestamps Chains: For the simplest networks, rindexer treats the entire chain as a single "run," allowing timestamp calculation for any block up to a validated consistency point.
4. Sampled & Batched Lookups: If no precomputed mapping exists, rindexer performs optimized, concurrent, and batched RPC calls.
   • Loose Time-Ordering (Sampling): Users can configure a sample rate to fetch timestamps at spaced intervals (e.g., every 50 blocks) and interpolate between them. This significantly reduces network latency and RPC processing at the cost of slight timestamp inaccuracy.

You can apply filters to event data before it is streamed to Kafka using the conditions key within an event configuration. This is particularly useful for filtering on non-indexed fields in the Solidity event.

Supported operators:

• >: Greater than (numbers only)
• <: Less than (numbers only)
• =: Equals
• >=: Greater than or equal to (numbers only)
• <=: Less than or equal to (numbers only)
• ||: Logical OR
• &&: Logical AND

Use the input names defined in your ABI to reference fields. For tuples, use object notation (e.g., tupleName.fieldName).

Note: For performance, it is advised to filter indexed fields in the contract details section of rindexer.yaml rather than using conditions, as indexed fields can be filtered at the request level.

events:
  - event_name: Transfer
    conditions:
      - "value": ">=2000000000000000000 && value <=4000000000000000000"
      - "from": "0x0338ce5020c447f7e668dc2ef778025ce3982662 || 0x0338ce5020c447f7e668dc2ef778025ce398266u"
      - "quoteParams.profileId": "=1"

You can trigger table operations on a schedule using cron in addition to event-driven events. This is useful for periodic data fetching (polling on-chain state), price feeds, snapshots, or heartbeat data.

Tables can define events, cron, or both. When using cron, you must use either interval (for simple time durations) or schedule (for standard cron expressions), but not both.

Available Variables in Cron Operations: Because cron runs on a schedule rather than in response to an event, event-specific fields like $from, $to, or $value are NOT available. You can only use:

• $call(...): View function calls
• $contract: The contract address from contract details
• $rindexer_block_number: The latest block number at execution time
• $rindexer_timestamp: The current timestamp
• Literals: String or number values (e.g., "eth-usd", 100)

tables:
  - name: eth_price
    columns:
      - name: id
        type: string
      - name: price
        type: int256
    cron:
      - interval: 5s
        operations:
          - type: upsert
            where:
              id: "eth-usd"
            set:
              - column: price
                action: set
                value: $call($contract, "latestAnswer()")

Custom tables are the primary way to perform no-code indexing. Instead of just logging raw events, you can maintain derived state (like token balances or ownership) by defining how events update specific columns.

When using tables, you do not need to specify include_events; rindexer automatically subscribes to the events referenced in your table definitions.

Example: Tracking ERC20 balances To track balances, you use upsert operations on a balances table, using $to and $from to identify the accounts and $value to adjust the amount.

contracts:
  - name: USDC
    details:
      - network: ethereum
        address: "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
        start_block: 18600000
    abi: ./abis/ERC20.json
    tables:
      - name: balances
        columns:
          - name: holder
          - name: balance
            default: "0"
        events:
          - event: Transfer
            operations:
              - type: upsert
                where:
                  holder: $to
                if: "$to != 0x0000000000000000000000000000000000000000"
                set:
                  - column: balance
                    action: add
                    value: $value
              - type: upsert
                where:
                  holder: $from
                if: "$from != 0x0000000000000000000000000000000000000000"
                set:
                  - column: balance
                    action: subtract
                    value: $value

Rindexer performs specific checks to determine the status of its core components:

Database Health Check

Verifies PostgreSQL connectivity by executing a SELECT 1 query.

• healthy: PostgreSQL is enabled and the query succeeds.
• unhealthy: PostgreSQL is enabled but connection or query fails.
• not_configured: PostgreSQL is enabled but no database client is available.
• disabled: PostgreSQL is not enabled in the configuration.

Indexing Health Check

Monitors the indexer process state via the global IS_RUNNING flag.

• healthy: The indexer is currently running.
• stopped: The indexer is not running.

Sync Health Check

Verifies data synchronization based on the storage backend:

• PostgreSQL: Queries information_schema.tables for user-created event tables. Status is no_data if no event tables exist (common in new deployments).
• CSV: Checks if the CSV directory exists and contains .csv files. Status is no_data if the directory is missing or empty.