blurt-rpc-core

Generic JSON-RPC 2.0 core for TypeScript projects.

This package is intentionally domain-agnostic. It provides implemented primitives for:

• JSON-RPC requests and responses;
• a RpcClient facade for single calls, raw calls, notifications and batches;
• fetch-based HTTP transport with timeout and abort support;
• retries and backoff;
• endpoint pools and selection strategies;
• ordered lifecycle hooks;
• generic metrics;
• optional explicit cache;
• structured public errors;
• testing helpers.

It does not implement blockchain logic, health checks, scoring, cryptographic signatures, chain validation or MCP server behavior.

Status

MVP implemented. The core is usable as a generic JSON-RPC engine and is covered by unit tests for client orchestration, transport, retry/failover, node-pool selection, cache, hooks, metrics and structured errors.

Install

npm install @beblurt/blurt-rpc-core

The package is ESM-only, targets Node.js >= 18, and also runs in browser runtimes that provide fetch, AbortController, URL and setTimeout.

Scripts

npm run build
npm run typecheck
npm run lint
npm test
npm audit --audit-level=high

Minimal usage

import { RpcClient } from '@beblurt/blurt-rpc-core'

const rpc = new RpcClient('https://rpc.example.org', { timeoutMs: 4000 })
const result = await rpc.call('namespace.method', { limit: 10 })

Raw responses

const response = await rpc.call('namespace.method', { limit: 10 }, { responseMode: 'response' })

Multiple endpoints and retry/failover

import { fixedBackoff, RpcClient } from '@beblurt/blurt-rpc-core'

const rpc = new RpcClient(['https://rpc-a.example.org', 'https://rpc-b.example.org'], {
  retry: { maxAttempts: 3, backoff: fixedBackoff(250) }
})

const value = await rpc.call('namespace.method')

Explicit cache

Caching is never implicit and the core never decides cacheability from method names.

import { MemoryCacheProvider, RpcClient } from '@beblurt/blurt-rpc-core'

const rpc = new RpcClient('https://rpc.example.org', {
  cache: { provider: new MemoryCacheProvider(), ttlMs: 5000 }
})

await rpc.call('namespace.method', { limit: 10 }, { cache: { ttlMs: 5000 } })

Hooks and metrics

import { InMemoryMetricsCollector, RpcClient } from '@beblurt/blurt-rpc-core'

const metrics = new InMemoryMetricsCollector()
const rpc = new RpcClient('https://rpc.example.org', {
  metrics,
  hooks: {
    beforeRequest: (request, context) => {
      // Return a replacement request to mutate, or void to continue unchanged.
    },
    afterAttempt: (outcome) => {
      // Observe success/error for each concrete attempt.
    }
  }
})

Documentation

Start with:

• ARCHITECTURE.md
• API.md
• DESIGN_DECISIONS.md
• docs/public-api.md
• docs/release-0.1.0.md
• module reference pages under docs/

Non-goals

No blockchain, scoring, signatures, health checks, method-specific behavior or MCP server code belongs in this package.