midnight-indexer:indexer-service

Indexer Service

Connect to and query the Midnight Network indexer for blockchain data including balances, transactions, and contract state.

When to Use

• Fetching account balances and UTXO data
• Listing transaction history for an address
• Reading contract state from the blockchain
• Querying shielded vs unshielded transaction data
• Building data-driven DApp backends
• Implementing pagination for large result sets

Key Concepts

Indexer Architecture

The Midnight indexer provides a GraphQL API for querying blockchain data. It indexes all on-chain activity and exposes it through structured queries.

API Versions

The indexer API has evolved through several versions. Ensure your queries are compatible with your target version.

UTXO Model

Midnight uses a UTXO (Unspent Transaction Output) model rather than an account model. Balance queries return the set of unspent outputs owned by an address.

Shielded Transactions

Midnight supports both transparent and shielded transactions. The indexer provides different access patterns:

• Transparent: Full transaction details visible
• Shielded: Only commitment hashes visible, details encrypted

References

Examples

Quick Start

1. Configure Indexer Client

import { createIndexerClient } from '@midnight-ntwrk/​midnight-js-indexer';

const indexer = createIndexerClient({
  uri: 'https://indexer.testnet.midnight.network/​api/​v1/​graphql',
  wsUri: 'wss://indexer.testnet.midnight.network/​api/​v1/​graphql',
});

2. Query Balance

const balance = await indexer.query({
  query: `
    query GetBalance($address: String!) {
      balance(address: $address) {
        total
        utxos {
          txHash
          outputIndex
          amount
        }
      }
    }
  `,
  variables: { address: 'addr_test1...' },
});

console.log('Total balance:', balance.data.balance.total);

3. List Transactions

const transactions = await indexer.query({
  query: `
    query GetTransactions($address: String!, $limit: Int!) {
      transactions(address: $address, first: $limit) {
        edges {
          node {
            hash
            blockNumber
            timestamp
            inputs { address amount }
            outputs { address amount }
          }
        }
        pageInfo {
          hasNextPage
          endCursor
        }
      }
    }
  `,
  variables: { address: 'addr_test1...', limit: 20 },
});

Common Patterns

Environment-Based Configuration

interface IndexerConfig {
  uri: string;
  wsUri: string;
}

function getIndexerConfig(): IndexerConfig {
  const network = process.env.MIDNIGHT_NETWORK || 'testnet';

  const configs: Record<string, IndexerConfig> = {
    testnet: {
      uri: 'https://indexer.testnet.midnight.network/​api/​v1/​graphql',
      wsUri: 'wss://indexer.testnet.midnight.network/​api/​v1/​graphql',
    },
    mainnet: {
      uri: 'https://indexer.midnight.network/​api/​v1/​graphql',
      wsUri: 'wss://indexer.midnight.network/​api/​v1/​graphql',
    },
  };

  return configs[network] ?? configs.testnet;
}

Pagination with Cursors

async function fetchAllTransactions(
  indexer: IndexerClient,
  address: string
): Promise<Transaction[]> {
  const allTransactions: Transaction[] = [];
  let cursor: string | null = null;
  let hasMore = true;

  while (hasMore) {
    const result = await indexer.query({
      query: TRANSACTIONS_QUERY,
      variables: {
        address,
        first: 100,
        after: cursor,
      },
    });

    const { edges, pageInfo } = result.data.transactions;
    allTransactions.push(...edges.map(e => e.node));

    hasMore = pageInfo.hasNextPage;
    cursor = pageInfo.endCursor;
  }

  return allTransactions;
}

Health Check

async function checkIndexerHealth(baseUrl: string): Promise<boolean> {
  try {
    const response = await fetch(`${baseUrl}/​health`);
    return response.ok;
  } catch {
    return false;
  }
}

Retry with Backoff

async function queryWithRetry<T>(
  indexer: IndexerClient,
  query: string,
  variables: Record<string, unknown>,
  maxRetries = 3
): Promise<T> {
  let lastError: Error | null = null;

  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      return await indexer.query({ query, variables });
    } catch (error) {
      lastError = error as Error;
      if (attempt < maxRetries) {
        await new Promise(r => setTimeout(r, 1000 * attempt));
      }
    }
  }

  throw lastError;
}

Related Skills

• event-subscriptions - Real-time WebSocket event streams
• midnight-tooling:contract-calling - Invoking contracts that change state
• midnight-dapp:state-management - Frontend state synchronization with indexer

Related Commands

• /​midnight-tooling:check - Verify indexer connectivity