Agent skill
midnight-indexer:indexer-service
Use when querying the Midnight indexer for blockchain data, fetching account balances, listing transactions, reading contract state, or building data-driven DApp backends.
Install this agent skill to your Project
npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/other/other/indexer-service
SKILL.md
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.
| Component | Purpose |
|---|---|
| GraphQL API | Query interface for blockchain data |
| WebSocket | Real-time subscriptions (see event-subscriptions skill) |
| REST Health | Service health checks |
API Versions
The indexer API has evolved through several versions. Ensure your queries are compatible with your target version.
| Version | Key Features | Breaking Changes |
|---|---|---|
| 2.0.0 | Base GraphQL schema | Initial release |
| 2.1.0 | Enhanced filters, pagination | Query parameter changes |
| 2.1.4 | Performance optimizations | None from 2.1.0 |
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
| Document | Description |
|---|---|
| api-versions.md | Version differences and migration guide |
| query-patterns.md | Common query patterns and optimization |
Examples
| Example | Description |
|---|---|
| balance-query/ | Query account balance and UTXOs |
| transaction-list/ | List transaction history with pagination |
| contract-state/ | Read deployed contract state |
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 streamsmidnight-tooling:contract-calling- Invoking contracts that change statemidnight-dapp:state-management- Frontend state synchronization with indexer
Related Commands
/midnight-tooling:check- Verify indexer connectivity
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
majiayu000/claude-skill-registry
agent-ops-spec
Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.
majiayu000/claude-skill-registry
agent-ops-state
Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.
majiayu000/claude-skill-registry
agent-ops-spec
Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.
majiayu000/claude-skill-registry
agent-ops-testing
Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.
majiayu000/claude-skill-registry
agent-ops-testing
Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.
majiayu000/claude-skill-registry
agent-ops-state
Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.
Didn't find tool you were looking for?