Skip to content

feat(electrum): return JSON-RPC 2.0 error objects (port of mempool/electrs#103)#222

Open
EddieHouston wants to merge 1 commit into
Blockstream:new-indexfrom
EddieHouston:feat/electrum-jsonrpc-error-objects
Open

feat(electrum): return JSON-RPC 2.0 error objects (port of mempool/electrs#103)#222
EddieHouston wants to merge 1 commit into
Blockstream:new-indexfrom
EddieHouston:feat/electrum-jsonrpc-error-objects

Conversation

@EddieHouston

@EddieHouston EddieHouston commented Jun 12, 2026

Copy link
Copy Markdown
Collaborator

Resolves #221 by porting mempool/electrs#103 onto new-index and extending it with
error categorization. Supersedes #220 — this includes that unknown-method fix in
error-object form.

What changes on the wire

All Electrum RPC error replies are now JSON-RPC 2.0 error objects instead of bare
strings, and malformed input gets a reply instead of a dropped connection:

Case Before After
Unknown method connection dropped {"code": -32601, "message": "unknown method <name>"}
Bad/missing params "error": "missing height" {"code": -32602, "message": "missing height"}
History too large (TooPopular) bare string {"code": 1, ...} (ElectrumX-style bad request)
bitcoind RPC error bare string {"code": 2, ...} (ElectrumX-style daemon error)
Other handler errors bare string {"code": -32603, ...}
Unparseable JSON connection dropped {"code": -32700, "message": "parse error"}, "id": null
Valid JSON, invalid request shape connection dropped {"code": -32600, "message": "invalid request"}, "id" echoed or null
Unknown method inside a batch whole batch + connection dropped that entry errors, others answered

Success replies are unchanged. Oversized batches, invalid UTF-8, and TLS bytes on the
plaintext port still close the connection (peers not speaking the protocol).

Implementation

  • JsonRpcV2Error enum and json_rpc_error() helper ported from Fix JSON-RPC v2 errors mempool/electrs#103
    (mempool/electrs@277b05b), with two deviations:
    the reply always includes "id" (null when undetectable, per spec — mempool omits
    it) and error messages don't echo request params back.
  • The envelope handling (-32700/-32600) is re-implemented rather than picked,
    since mempool's hunk targets their refactored connection layer; handle_value now
    returns Value and keeps this repo's RPC event logging.
  • New ErrorKind::InvalidParams carries param-validation failures from the
    *_from_value helpers to the dispatcher, where jsonrpc_code() maps error kinds to
    codes (InvalidParams → -32602, TooPopular → 1, RpcError (daemon) → 2,
    everything else → -32603). A few call sites stop wrapping param errors with
    chain_err, which previously erased the kind.

Testing

New integration test test_electrum_jsonrpc_errors covers: -32601 with the connection
left open, -32602 on a missing param, -32600 on a method-less request (id echoed),
-32700 on unparseable JSON (null id), a batch where an unknown method no longer kills
the other entries, and that the connection survives all of the above.

cargo test passes (lib + electrum + REST integration tests); cargo check is clean
on --features liquid and --features electrum-discovery.

…ectrs#103)

  Implements Blockstream#221. All Electrum RPC error replies are now JSON-RPC 2.0 error
  objects with codes instead of bare strings: -32601 unknown method, -32602
  invalid params (via a new ErrorKind::InvalidParams raised by the param
  helpers), 1 for history-too-large, 2 for bitcoind RPC errors, -32603
  otherwise. Malformed input now gets a reply instead of a dropped connection:
  -32700 for unparseable JSON (id null) and -32600 for valid JSON that is not a
  request object. A batch containing an unknown method answers its remaining
  entries instead of killing the connection.

  Deviations from the mempool port: replies always include 'id' (null when
  undetectable, per spec) and error messages do not echo request params back.
  Oversized batches and non-protocol bytes still close the connection.

  Co-authored-by: junderw <jonathan.underwood4649@gmail.com>
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.

Electrum RPC: return JSON-RPC 2.0 error objects instead of bare strings (port of mempool/electrs#103)

2 participants