floresta is in early development and we made it work first, now we need to make it perfect.

Heres a pinterest picture saying the same thing — sure is the best mentality to have.

Heres some points that i wish was better, and Bitcoin Core shouldn’t be a stopping point — there are easy and addressable things that we can do differently. We have different contexts and tools; for example, integrating the corepc crate collection is an obvious go-to change. Right now the RPC implementation is spread across crates and the RPC pipeline interface isn’t clear: there is data handling at each call level, RPCs are implemented behind an inflight scheme that isn’t used at all, and so on.

To facilitate an actionable conversation, below is a prioritized list of what can be better, why, and how we can improve it. The list can be extended as development and discussions evolve.

What can be better

Each item includes:

• why: the concrete problem or risk
• how: suggested short-term and medium/long-term actions
• WIP: how we can track progress (issue/PR/RFC suggestions)
• priority: my idea of urgency (P0 — P3)

P3 — Process-level exit on startup failures

• why
  • server.create currently calls std::process::exit(-1) on bind failure. That makes embedding or tests brittle and destroys caller’s chance to handle error.

P2 — Long-running operations: no lifecycle / cancellation / op IDs

• why
  • Methods that spawn long-running work (rescanblockchain, load_descriptor) use tokio::spawn but provide no operation ID, progress or cancel API. This makes management and abuse detection hard.
  • inflight map uses serde_json::Value as key: Arc<RwLock<HashMap<Value, InflightRpc>>>, which is untyped and fragile. The locking strategy is coarse and could become a contention point.
• how
  • RpcCommand trait can be modular to be turned into a RpcTask<u64, RequestType>, we only need to know the request to execute the command with Request::work_into_response().
  • wrap background RpcTasks in an OperationManager that returns an operation ID and supports status/cancel or atleast load balancing.
  • introduce per-operation quotas, concurrency limits and authentication gating for expensive endpoints.
  • persist operation state for restart/monitoring and add progress notifications (SSE/WS) or a push mechanism.
• priority
  • P2 — operational and DoS risk.

P0 — Weak typing across server & client APIs (user-request)

• why
  • Client.rpc_call accepts &[serde_json::Value], and FlorestaRPC implementations build Value arrays manually — this loses static guarantees and makes refactors error-prone.
  • Duplication of types and ad-hoc serialization occurs in many places.
  • Data drifts happens all the time.
• how
  • Provide well typed request/response structs for the most-used RPCs. Add typed wrapper methods that accept serde-serializable types and return typed results. Requests implement From to have a stronger input handling, also they can implement Request::work_into_response(&RPCServer) -> Either<BitcoinCoreResponse, FlorestaFlavoredResponse, ...>.
  • Following floresta design pattern: A RpcCommand Trait, with associated types. we can abstract server handling in this trait without changing the interface every time we need a new command to be added on.
  • Centralize rpc types and server implementation in a single crate (floresta-rpc).
• priority
  • P0 — high developer ergonomics, improve debugging and development speed as well.

P3 — Client: blocking only implementation, no async functionalities

• why
  • Current client used in tests is synchronous (jsonrpc::Client::simple_http). Async-first ecosystems (tokio) will find it awkward to use or require spawn_blocking.
• priority
  • P3 maybe ?

P3 — Error model

• why
  • Server defines JsonRpcError types; client uses rpc_types::Error. Mapping is ad-hoc and unclear. JSON-RPC error fields are not consistently used/documented.
• how
  • rpc pipeline have clear error return. Telling precisely what can be returned and why.
• priority
  • P3.

P2 — Monolithic handler coupling and code-structure

• why
  • RpcImpl aggregates many concerns (chain, wallet, node, filters). Large server file is harder to maintain and to unit-test (though some modularization exists: blockchain.rs, network.rs).
  • File: crates/floresta-node/src/json_rpc/server.rs
• how

• split server.rs into smaller modules and move rpc pipeline handlers into their own files
  /rpcs
  /blockchain.rs
  /control.rs
  /networking.rs
  /rawtransactions.rs
  /signer.rs
  /util.rs
  /wallet.rs
  /zmq.rs

• BONUS: define small capability modifiers (ChainRead, ChainWrite, FilterStore, NodeOps) for rpc auth levels for each module to ensure user security and what server needs to expose for each.

• priority

  • P2.

  P0 -- Fast and Easy Scheme and Pipeline assertion.
  why

  • To develop RPCs, you need a running Bitcoin Core to validate many things, such as pipeline execution, but we currently automate that only through Python tests, and there’s nothing in code for that.
  • Python tests don’t validate all fields, only the ones we explicitly check, which can leave gaps in compatibility.
  • how
    • Using the corepc-client crate for RPC types in Floresta and electrum-client for Electrum types in Floresta enables type-safe RPC testing.
    • By integrating electrsd, which spins up both a bitcoind and an Electrum server using the same corepc-client and electrum-client types, we can directly compare Floresta’s responses with Bitcoin Core’s without field-by-field validation.

I wrote this so we can align things with the team, these points are often mentioned trough floresta development issues/discussions and meetings. They may not be problems but they can be improvement points that we can dream of implementing. Also an easy place to redirect someone if it comes to talk about rpc in floresta.