@umbra-privacy/indexer-read-service-client

TypeScript HTTP client for the Umbra Indexer Read Service. Provides typed methods for querying UTXO data, Merkle proofs, tree metadata, and health status from the Umbra indexer.

Installation

pnpm add @umbra-privacy/indexer-read-service-client

Usage

import { ReadServiceClient } from "@umbra-privacy/indexer-read-service-client";

const client = new ReadServiceClient({
  endpoint: "https://acqzie0a1h.execute-api.eu-central-1.amazonaws.com",
});

// Health checks
const health = await client.health();
const detailed = await client.healthDetailed();
const liveness = await client.liveness();
const readiness = await client.readiness();

// Global stats
const stats = await client.getStats();

// Tree metadata
const treeInfo = await client.getTreeInfo(0);

// Merkle proofs
const proof = await client.getProof(0, 42);

// UTXO queries
const utxos = await client.getUtxoData({ start: 0, limit: 100 });
const single = await client.getUtxo(42);
const treeUtxos = await client.getTreeUtxos(0, { cursor: 0, limit: 50 });

// Columnar format (better compression for large datasets)
const columnar = await client.getUtxoDataColumnar({ start: 0, limit: 1000 });

// Auto-paginated fetch
const allUtxos = await client.getAllUtxoData(0);

API

ReadServiceClient

Constructor

• new ReadServiceClient({ endpoint, fetch? }) — Create a client. Optionally provide a custom fetch implementation.

Health

• health() — Basic health check
• healthDetailed() — Detailed health with version, uptime, and storage status
• liveness() — Kubernetes-style liveness probe
• readiness() — Kubernetes-style readiness probe

Stats & Trees

• getStats() — Global UTXO count and latest index
• getTreeInfo(treeIndex) — Merkle tree metadata (root, leaf count)

Proofs

• getProof(treeIndex, insertionIndex) — Merkle inclusion proof for a specific leaf

UTXOs

• getUtxoData(params?) — Paginated UTXO query by absolute index range
• getUtxoDataColumnar(params?) — Same query in columnar layout for better compression
• getUtxo(absoluteIndex) — Single UTXO by absolute index (returns null on 404)
• getTreeUtxos(treeIndex, params?) — UTXOs scoped to a specific tree
• getAllUtxoData(start?, end?, pageSize?) — Auto-paginated fetch of all UTXOs

Error Handling

All methods throw IndexerReadError on failure:

import { IndexerReadError } from "@umbra-privacy/indexer-read-service-client";

try {
  await client.getUtxo(999999);
} catch (err) {
  if (err instanceof IndexerReadError) {
    console.log(err.operation);  // "getUtxo"
    console.log(err.statusCode); // 404, 500, etc.
    console.log(err.message);
  }
}

Transport

All responses are protobuf-encoded (application/protobuf). The client handles deserialization automatically using @umbra-privacy/indexer-proto-gen schemas.

Dependencies

• @bufbuild/protobuf ^2.0.0
• @umbra-privacy/indexer-proto-gen

License

MIT