[REFACTOR][RPC] Centralize RPC traits and method names by moisesPompilio · Pull Request #1067 · getfloresta/Floresta

moisesPompilio · 2026-05-15T20:47:09Z

Description and Notes

The RPC trait and method definitions were centralized so that floresta-rpc and floresta-node stay aligned and compatible.

At the moment, floresta-rpc implements RPC methods that are consumed by the node, while floresta-node exposes the server-side implementation that serves the same methods. To avoid inconsistencies between both crates, this change introduces shared RPC traits that define the contract for these methods in a single place.

The main challenge is that floresta-rpc needs synchronous traits, while floresta-node needs asynchronous ones. To solve this, this change introduces the maybe-async macro, which allows the same trait definitions to support both sync and async implementations through a single code path.

In addition to the trait unification, the RPC macros were reorganized into categories similar to Bitcoin Core:

wallet
blockchain
control
network
util
rawtransactions

It also introduces RpcMethods, an enum that acts as the single source of truth for all RPC method names. It provides to_string(), as_str(), and FromStr implementations so both floresta-rpc and floresta-node can use the same method definitions safely. This prevents spelling mismatches and avoids duplicating method names across the codebase.

How to verify the changes you have done?

Build floresta-rpc and floresta-node to confirm the shared RPC traits compile correctly in both sync and async contexts.
Verify that RpcMethods can be converted with to_string(), as_str(), and FromStr.
Check that RPC method names are now defined in a single place and reused consistently across the codebase.
Confirm that the RPC trait categories are correctly split into:
- wallet
- blockchain
- control
- network
- util
- rawtransactions
Ensure the workspace builds correctly after the maybe-async integration and the crate-by-crate build adjustment.

moisesPompilio · 2026-05-21T20:08:07Z

167b5c2 I rebased

Davidson-Souza · 2026-06-03T18:14:07Z

-        self.call("loaddescriptor", &[Value::String(descriptor)])
-    }
-
-    fn get_block_filter(&self, height: u32) -> Result<String> {


You removed get_block_filter?

Yes, get_block_filter exists only in floresta-rpc, but it is not implemented in floresta-node

Davidson-Souza · 2026-06-03T18:14:34Z

@@ -0,0 +1,156 @@
+use core::fmt::Debug;


SPDX headers and module-level docs

Davidson-Souza · 2026-06-03T18:14:52Z

+use core::fmt::Debug;
+use std::str::FromStr;
+
+macro_rules! define_rpc_methods {


Docs for this macro would be nice!

@lorenzolfm don't look over here.

Davidson-Souza · 2026-06-03T18:17:24Z

        Methods::GetBlockCount => serde_json::to_string_pretty(&client.get_block_count()?)?,
        Methods::GetTxOut { txid, vout } => {
-            serde_json::to_string_pretty(&client.get_tx_out(txid, vout)?)?
+            serde_json::to_string_pretty(&client.get_tx_out(txid, vout, false)?)?


What's this false for?

In Bitcoin Core, get_tx_out has a third argument, include_mempool. Since we haven’t fully implemented the mempool, that value doesn’t really make much difference in our case, but I set it to false to reflect how the option would be handled in Bitcoin Core

Could yout add a TODO mentioning this?

Davidson-Souza · 2026-06-03T18:18:02Z

    /// Returns the transaction, assuming it is cached by our watch only wallet
    #[command(name = "gettransaction")]
-    GetTransaction { txid: Txid, verbose: Option<bool> },
+    GetTransaction { txid: Txid, verbose: Option<u32> },


verbosity then

Davidson-Souza · 2026-06-03T18:19:39Z

        script: String,
-        height_hint: u32,
-    ) -> Result<Value> {
+        height: u32,


I prefer height_hint

Davidson-Souza · 2026-06-03T18:22:03Z

+        if result.is_null() {
+            return Err(Error::TxOutNotFound);
+        }


Is this right? Shouldn't this be handled at server side?

This shouldn’t return an error. The result is an Option, so I changed it so that when the value is null, it returns None instead of an error.

Davidson-Souza · 2026-06-03T18:29:48Z

+          #!/usr/bin/env bash
+          set -e
+          CRATES=$(cargo metadata --format-version 1 --no-deps | jq -r '.packages[] | select(.source == null and (.targets | map(.kind | contains(["lib"])) | any)) | .name' | tr '\n' ' ')
+          echo "Building docs for crates: $CRATES"
+          for crate in $CRATES; do
+            echo "Running cargo doc for: $crate"
+            RUSTDOCFLAGS="--cfg docsrs -D warnings" cargo +nightly doc -p "$crate" --no-deps --lib --all-features --document-private-items || exit 1
+          done


Hmm, we need to make sure we can build docs for https://docs.gefloresta.sh

What specific error is happening in this case? In my tests, it is being generated correctly and I’m able to access it.

Replace hardcoded method name strings with a single source of truth. The RpcMethods enum provides FromStr, to_string(), and as_str() for type-safe method name handling, preventing divergence across codebase.

Split RPC methods into category-specific traits (Blockchain, Wallet, Network, RawTransaction, Control) for better code organization, segregation, and flexible implementation across RPC and CLI.

Introduce maybe_async procedural macro to NetworkRpc trait to support both async and sync implementations. This allows: - Shared trait definitions between floresta-node (async) and floresta-rpc (sync) - Consistent interface across different implementations - NetworkRpc trait now implemented in floresta-node to ensure network operations are compatible between floresta-node and floresta-rpc Fix build compatibility issue: - maybe_async feature conflicts when building entire workspace - Adjusted justfile to compile individual crates by path instead of workspace super-set to prevent async feature leaking into floresta-cli - floresta-cli now builds without async feature to preserve RPC implementation

Add maybe_async support to WalletRpc trait enabling async/sync flexibility. WalletRpc now implemented in floresta-node to ensure consistency.

…a-node Enable async/sync flexibility for ControlRpc trait with maybe_async. Provides unified interface for control operations (get_memory_info, get_rpc_info, stop, uptime) across floresta-node and floresta-rpc.

…esta-node Enable async/sync flexibility for BlockchainRpc trait with maybe_async. Provides unified interface for blockchain operations across floresta-node and floresta-rpc, completing the RPC trait migration pattern.

Enable async/sync flexibility for RawTransactionRpc trait with maybe_async. Remove corepc_types dependency from floresta-node, centralizing all RPC types in floresta-rpc as single source of truth.

moisesPompilio force-pushed the centralize-trait-and-type-rpc branch from ed4a6ff to 2443380 Compare May 15, 2026 21:43

luisschwab assigned moisesPompilio May 15, 2026

luisschwab added code quality Generally improves code readability and maintainability RPC Changes something with our JSON-RPC interface labels May 15, 2026

luisschwab added this to Floresta May 15, 2026

github-project-automation Bot moved this to Backlog in Floresta May 15, 2026

moisesPompilio added the reliability Related to runtime reliability, stability and production readiness label May 15, 2026

moisesPompilio added this to the Q2/2026 milestone May 15, 2026

moisesPompilio moved this from Backlog to Needs review in Floresta May 15, 2026

moisesPompilio requested review from Davidson-Souza and jaoleal May 15, 2026 23:08

moisesPompilio mentioned this pull request May 18, 2026

rpcserver: Support named and null parameters, Review optionals on rpc internal methods, Stronger Response and Error codes #831

Merged

3 tasks

moisesPompilio force-pushed the centralize-trait-and-type-rpc branch 2 times, most recently from c357d5a to 167b5c2 Compare May 21, 2026 19:53

Davidson-Souza reviewed Jun 3, 2026

View reviewed changes

refactor(rpc): centralize RPC method names with RpcMethods enum

1df887e

Replace hardcoded method name strings with a single source of truth. The RpcMethods enum provides FromStr, to_string(), and as_str() for type-safe method name handling, preventing divergence across codebase.

moisesPompilio force-pushed the centralize-trait-and-type-rpc branch from 167b5c2 to f163a85 Compare June 8, 2026 20:44

moisesPompilio added 6 commits June 8, 2026 18:10

refactor(rpc): add modular trait-based RPC interfaces

ecab927

Split RPC methods into category-specific traits (Blockchain, Wallet, Network, RawTransaction, Control) for better code organization, segregation, and flexible implementation across RPC and CLI.

refactor(rpc): implement WalletRpc with maybe_async for compatibility

acc2d65

Add maybe_async support to WalletRpc trait enabling async/sync flexibility. WalletRpc now implemented in floresta-node to ensure consistency.

refactor(rpc): add maybe_async to ControlRpc and implement in florest…

0431dc0

…a-node Enable async/sync flexibility for ControlRpc trait with maybe_async. Provides unified interface for control operations (get_memory_info, get_rpc_info, stop, uptime) across floresta-node and floresta-rpc.

refactor(rpc): add maybe_async to RawTransactionRpc and centralize types

c5b471f

Enable async/sync flexibility for RawTransactionRpc trait with maybe_async. Remove corepc_types dependency from floresta-node, centralizing all RPC types in floresta-rpc as single source of truth.

moisesPompilio force-pushed the centralize-trait-and-type-rpc branch from f163a85 to c5b471f Compare June 8, 2026 21:13

Conversation

moisesPompilio commented May 15, 2026

Description and Notes

How to verify the changes you have done?

Uh oh!

moisesPompilio commented May 21, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants