davide
b292590cdc
docs/docs-as-code.md defines the workflow; docs/adr holds 31 ADRs (retroactive, reconstructed from code and changelog) with a template and index. docs/check-docs.sh validates ADR structure, index, cited code paths, relative links and CLAUDE.md/AGENTS.md sync.
1.4 KiB
1.4 KiB
0009. Hand-written Electrum JSON-RPC client with pipelining and an in-flight cap
- Status: Accepted
- Area: Network
- Recorded: 2026-11-03 (retroactive: reconstructed from code, comments and changelog)
Context
The wallet talks to an ElectrumX/Fulcrum-style indexing server (ports 50001/50002, not the node's P2P port 2333). No library matched the needs: protocol 1.4, a testable in-process transport and control over throughput on large wallets.
Decision
Implement ElectrumClient directly over TcpClient/SslStream, newline-delimited JSON-RPC 2.0. A single-reader channel batches writes (like Electrum's buffered writer); a read loop completes pending requests by id; a semaphore caps in-flight requests (DefaultMaxInFlight = 32, configurable per connection) to avoid server throttling and disconnects. Typed helpers live in ElectrumApi. The class is deliberately not an interface: tests run against a real in-process server instead (0025).
Consequences
- Full control over request pipelining and error mapping (
ElectrumServerException). - No single in-flight value suits every server, hence the per-connection knob.
- Protocol quirks (e.g.
server.versionallowed once per connection) are our responsibility; the server probe (0027) exists to catch server differences.
References
src/Core/Net/ElectrumClient.cssrc/Core/Net/ElectrumApi.cs