Skip to content

feat(architecture): add a generic jsonrpc passthrough architecture - #2

Draft
snowkide wants to merge 2 commits into
mainfrom
feat/jsonrpc-passthrough-architecture
Draft

snowkide wants to merge 2 commits into
mainfrom
feat/jsonrpc-passthrough-architecture

Conversation

@snowkide

@snowkide snowkide commented Oct 15, 2026 •

Copy link
Copy Markdown

eRPC serves EVM and SVM chains, each with a chain model (chain-id or genesis detection, state poller, method hooks). Many other chains expose a plain JSON-RPC API (Bitcoin-family nodes, Stellar RPC and others) and only need eRPC's generic pipeline: upstream selection, failsafe policies, rate limiting, multiplexing, metrics and healthchecks.

Commits (can be split into two PRs):

  1. fix(json-rpc): treat "error": null in upstream responses as success. JSON-RPC 1.0-style servers always send the error member and set it to null on success; today every successful call to such a node is parsed as a server error and retried elsewhere. A null error member is now skipped in ParseFromStream (single HTTP and WebSocket responses) and NewJsonRpcResponseFromBytes (batch responses); ParseError itself is unchanged. Behaviour change: {"result":null,"error":null} is now a null-result success instead of an error, so the normal empty-result rules apply.
  2. feat(architecture): architecture: jsonrpc, providing the generic pipeline and nothing chain-specific.
    • Network id jsonrpc:<id>, where jsonRpc.id defaults to the alias; networks can be created lazily from /<project>/jsonrpc/<id>.
    • Upstreams: type: jsonrpc with jsonRpc.networkId (type inferred when set). Bootstrap sends nothing to the node. HTTP and WebSocket only; gRPC endpoints are rejected.
    • Requests are forwarded without normalization; finality is unknown unless set via methods.definitions; no cache (no block/slot model). Multiplexing uses a case-preserving key (as SVM), so params that differ only in letter case are not merged.
    • upstreams[].jsonRpc.omitEmptyParams leaves params out when empty instead of sending "params":[]. It defaults to true for type: jsonrpc only; EVM/SVM upstream configs and wire format are unchanged (a test asserts EVM still sends "params":[]).
    • Errors from jsonrpc upstreams fall through to the default (EVM) extractor.
    • Docs (config/projects/networks, config/projects/upstreams) and TypeScript config types.
networks:
  - architecture: jsonrpc
    alias: my-chain
upstreams:
  - endpoint: https://rpc.example.com
    jsonRpc:
      networkId: my-chain

Verification

Based on fork main @ f97c9f6 (erpc/erpc 0.5.0 @ 204f98c).

  • go build ./..., go vet on touched packages and gofmt -l on touched files are clean.
  • go test ./common/ ./clients/ ./util/ ./architecture/... ./upstream/: ok.
  • go test ./erpc/ -run 'JsonRpc|MultiplexKey|HealthCheck': ok; with -race on JsonRpcPassthrough|HealthCheckJsonRpc: ok.
  • Commit 1 alone: go test ./common/ -run 'ErrorNull|ParseError': ok.
  • New tests: TestJsonRpcResponse_ErrorNullIsSuccess, TestHttpServer_JsonRpcPassthrough, TestHealthCheckJsonRpcNetworkScope, TestJsonRpcPassthrough_MultiplexKeyPreservesCase, plus client, registry, defaults and id tests and jsonrpc.test-d.ts.

AI assistance

  • Model: anthropic/claude-opus-5.5
  • Harness / skills: Claude Code
  • Human-reviewed: no, pending

🤖 Generated with Claude Code

@snowkide
snowkide force-pushed the feat/jsonrpc-passthrough-architecture branch from 8ca1410 to e7acd75 Compare November 3, 2026 10:57
@snowkide snowkide changed the title feat(architecture): generic "jsonrpc" passthrough architecture for non-EVM JSON-RPC nodes feat(architecture): add a generic jsonrpc passthrough architecture Nov 3, 2026
@snowkide
snowkide changed the base branch from main to upstream-main November 3, 2026 11:07
@snowkide
snowkide force-pushed the feat/jsonrpc-passthrough-architecture branch from e7acd75 to e859e1b Compare November 3, 2026 11:23
@snowkide
snowkide changed the base branch from upstream-main to main November 3, 2026 11:23
@snowkide
snowkide force-pushed the feat/jsonrpc-passthrough-architecture branch from e859e1b to 69c766b Compare November 4, 2026 14:03
snowkide and others added 2 commits November 5, 2026 14:46
JSON-RPC 1.0 servers always include the "error" member and set it to null
on success. The response parser passed the literal null to ParseError,
which turned it into a server-side exception, so every successful call to
such a node was reported as failed and retried on other upstreams.

Skip a null error member in the streaming parser and in
NewJsonRpcResponseFromBytes (used by the batch path). ParseError itself is
unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
eRPC serves EVM and SVM chains, each with a chain model (chain id or
genesis detection, state poller, method hooks). Many other chains expose a
plain JSON-RPC API and only need the generic pipeline: upstream selection,
failsafe policies, rate limiting, multiplexing, metrics and healthchecks.

Add a third architecture, "jsonrpc", that provides exactly that:

- architecture/jsonrpc registers a no-op ArchitectureHandler; its error
  extractor claims nothing, so errors fall through to the default mapping.
- Networks: architecture jsonrpc with jsonRpc.id (defaults to the alias),
  network id "jsonrpc:<id>". Inferred from a jsonRpc block, never receives
  networkDefaults.evm, and can be created lazily from
  /<project>/jsonrpc/<id>.
- Upstreams: type jsonrpc with jsonRpc.networkId (type inferred when set).
  Bootstrap sends nothing to the node. The HTTP and WebSocket JSON-RPC
  clients are reused; gRPC endpoints are rejected.
- Requests are validated as JSON-RPC and forwarded without normalization.
  Finality is unknown unless set via methods.definitions, there is no
  cache, and multiplexing keys on the exact (case-preserved) params.
- upstreams[].jsonRpc.omitEmptyParams leaves "params" out of outbound
  requests whose params are empty, for servers that reject "params":[].
  It defaults to true for type jsonrpc only; evm and svm upstreams keep
  their wire format unless it is turned on.
- Healthcheck scoping and all:activeUpstreams understand jsonrpc networks.
- TypeScript config types and docs updated.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@snowkide
snowkide force-pushed the feat/jsonrpc-passthrough-architecture branch from 69c766b to 9f5c89c Compare November 5, 2026 13:52

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant