feat(evm-rpc): Resilient JSON-RPC client for EVM chains

[Emmyt24]

Depends on: #217. Blocks: #219, #221, #225.

Description

Octo talks to Stellar through two purpose-built clients —
crates/ingest/src/horizon.rs for deposit polling and
crates/api/src/horizon.rs for API-side reads/submits — both
wrapped in octo-resilience. EVM needs the equivalent over
JSON-RPC 2.0.

Build crates/evm-rpc (octo-evm-rpc) as a typed client covering the methods this epic needs,
with the same resilience posture.

Requirements and context

• Honour the submit-asymmetry rule (AD-5). eth_call, eth_getLogs, eth_blockNumber,
  eth_getTransactionReceipt are CallKind::Read and retryable.
  eth_sendRawTransaction must not be transparently retried — see the header comment in
  crates/ingest/src/horizon.rs for the established reasoning.
• JSON-RPC error handling is a trap. A JSON-RPC error is HTTP 200 with an error member. A
  client that only checks HTTP status will treat every failure as success. Handle the error object
  explicitly and distinguish transport failure from protocol error from execution revert.
• Providers differ in real, breaking ways: eth_getLogs block-range caps (Alchemy 2k, Infura 10k,
  others unbounded), rate-limit responses, and inconsistent revert-data encoding. The client must
  surface a typed RangeTooLarge so feat(ingest): EVM ingest worker — ERC-20 Transfer log scanning #221 can adaptively bisect rather than stall.
• All quantities are hex-encoded strings (0x-prefixed, minimal-length). Parse into the U256
  type chosen in feat(evm-core): secp256k1 keys, BIP-44 derivation, and EIP-55 addresses #217 — never into u64 or f64.
• Security: RPC URLs contain API keys — never log the URL (see feat(config): Per-chain configuration and runtime chain registry #216). Cap response body size;
  a malicious or compromised RPC returning a multi-GB response must not OOM the worker.

Suggested execution

Branch: feat/evm-rpc-client

Implement changes

• Add crates/evm-rpc using the workspace reqwest (already rustls-tls, no OpenSSL).
• Implement typed wrappers: eth_blockNumber, eth_getBlockByNumber, eth_getLogs,
  eth_getTransactionReceipt, eth_getTransactionCount, eth_call, eth_estimateGas,
  eth_feeHistory, eth_chainId, eth_sendRawTransaction.
• Wire execute(CallKind::Read, ..) with per-chain RetryPolicy/CircuitBreaker from feat(config): Per-chain configuration and runtime chain registry #216 for reads
  only; document at the call site why the submit path is excluded.
• Add a startup assertion that eth_chainId matches the configured CAIP-2 chain id — a
  misconfigured RPC pointing at the wrong chain is a fund-loss bug, and this one-line check
  prevents it.
• Typed errors: Transport, JsonRpc { code, message }, Revert { data }, RangeTooLarge,
  RateLimited { retry_after }, CircuitOpen.

Test and commit

• Mock-server tests in the style of
  crates/ingest/tests/horizon_mock_tests.rs and
  crates/api/tests/horizon_resilience_tests.rs.
• A test that HTTP 200 with a JSON-RPC error member is treated as an error, not success.
• Test retry/backoff on 5xx and the circuit opening after failure_threshold.
• A test asserting eth_sendRawTransaction is called exactly once on failure — no silent retry.
• Test hex parsing edge cases: 0x0, values above u64::MAX, malformed input, and a response body
  exceeding the size cap.
• Test the chain-id mismatch guard rejects at startup.

Example commit message

feat(evm-rpc): typed JSON-RPC client with per-chain resilience

Reads go through octo-resilience retry + circuit breaker;
eth_sendRawTransaction deliberately does not, preserving the
submit-asymmetry rule.

JSON-RPC errors arrive as HTTP 200 with an error member, so status-only
checking would read every failure as success — handled explicitly.

Startup asserts eth_chainId matches the configured CAIP-2 id; an RPC
pointed at the wrong chain is a fund-loss bug.

Refs #218

Guidelines

Do not pull in a full EVM SDK for this. A focused client keeps the dependency audit small and the
cargo deny surface reviewable.

---

[Peculiarr7]

Hi! I came across this issue and would love to work on it. I have experience with similar tasks and I'm confident I can investigate, implement a clean solution, and thoroughly test it before submitting a PR. If the issue is still open, I would appreciate it if you could assign it to me. I’ll prioritize this immediately and ensure a reliable solution is delivered as soon as possible. Thank you!

[Lost-Z]

Hi maintainers! I'd like to take on this issue and work on the typed EVM JSON-RPC client.

I've reviewed the requirements and the existing Stellar architecture, and I understand that the goal is to introduce crates/evm-rpc (octo-evm-rpc) as the EVM equivalent of the existing Horizon clients, while preserving the project's established resilience and security patterns.

I also understand that this is a dependency of several downstream issues, so I'll keep the implementation focused, typed, and easy to build on rather than introducing a full EVM SDK or unnecessary dependencies.

Implementation approach

I'll create crates/evm-rpc using the workspace's existing reqwest configuration and implement typed wrappers for the required JSON-RPC methods:

• eth_blockNumber
• eth_getBlockByNumber
• eth_getLogs
• eth_getTransactionReceipt
• eth_getTransactionCount
• eth_call
• eth_estimateGas
• eth_feeHistory
• eth_chainId
• eth_sendRawTransaction

I'll make the JSON-RPC layer explicitly distinguish between transport failures, protocol-level JSON-RPC errors, and execution/revert failures. In particular, I won't rely on HTTP status codes alone because JSON-RPC errors commonly arrive as HTTP 200 responses containing an error object.

Resilience and submit asymmetry

I'll follow the existing octo-resilience patterns and the AD-5 submit-asymmetry rule carefully.

Read operations such as eth_call, eth_getLogs, eth_blockNumber, and eth_getTransactionReceipt will use the appropriate per-chain retry and circuit-breaker policies introduced by #216.

eth_sendRawTransaction will deliberately not be transparently retried. I'll document this directly at the call site so the reasoning is clear to future maintainers: automatically retrying a transaction submission can create dangerous ambiguity around whether the first transaction was accepted, which is particularly important for financial operations.

I'll also ensure resilience state is isolated per chain so failures against one RPC don't affect another chain.

Typed errors

I'll introduce structured errors for:

• Transport failures.
• JSON-RPC errors containing the RPC error code and message.
• Execution reverts with available revert data.
• RangeTooLarge for provider-specific eth_getLogs range limitations.
• Rate limiting with retry_after where available.
• Open circuit conditions.

The RangeTooLarge handling is especially important because downstream indexing logic needs to be able to react by adaptively bisecting block ranges rather than getting stuck on provider-specific limits.

RPC safety and correctness

I'll make sure all JSON-RPC quantities are handled as 0x-prefixed hexadecimal values and parsed into the U256 representation selected by #217. I won't use u64 or floating-point types for blockchain quantities where that could introduce truncation or precision issues.

I'll also enforce a response-body size limit before deserializing responses. This protects the worker from an unexpectedly large or malicious RPC response consuming excessive memory.

RPC URLs will never be logged or exposed through errors, consistent with the security requirements from #216, since provider URLs can contain API credentials.

One particularly important startup check I'll implement is verifying that eth_chainId returned by the configured RPC matches the chain ID configured by the application. A misconfigured RPC endpoint pointing to the wrong network could result in funds being sent or monitored on an unintended chain, so I agree that this should fail fast during startup rather than becoming a runtime discovery.

Testing

I'll follow the existing mock-server testing style from the Horizon tests and cover the critical failure modes, including:

• HTTP 200 responses containing JSON-RPC error objects.
• Successful JSON-RPC responses.
• Transport failures.
• Retry/backoff behavior on 5xx responses.
• Circuit breaker opening after the configured failure threshold.
• Verification that eth_sendRawTransaction is attempted exactly once when it fails, with no silent retry.
• eth_getLogs range-limit detection and typed RangeTooLarge errors.
• Rate-limit handling.
• Hex parsing of 0x0.
• Values larger than u64::MAX.
• Malformed hexadecimal values.
• Oversized response bodies being rejected.
• Chain-ID mismatch rejection during startup.
• Revert-data handling and typed execution errors.

I'll also make sure the implementation integrates cleanly with the existing workspace conventions and doesn't introduce a full EVM SDK, keeping the dependency surface small and the cargo deny review manageable.

Before submitting the PR, I'll run the relevant unit and integration tests, formatting/lint checks, and the workspace build checks to ensure the client is reliable and doesn't regress the existing Stellar functionality.

I'd be happy to take this issue and work through the JSON-RPC edge cases carefully, particularly the retry asymmetry, provider-specific log limits, error classification, and chain-ID safety check.

Thanks for considering my application!