[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.

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 · 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?

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?

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?

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

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 added 2 commits May 21, 2026 16:31

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

c6b5215

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.

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

bd3fa59

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

moisesPompilio force-pushed the centralize-trait-and-type-rpc branch from 2443380 to c357d5a Compare May 21, 2026 19:48

moisesPompilio added 5 commits May 21, 2026 16:53

refactor(rpc): implement WalletRpc with maybe_async for compatibility

6a576ee

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…

d86609b

…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

167b5c2

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 c357d5a to 167b5c2 Compare May 21, 2026 19:53

Davidson-Souza reviewed Jun 3, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[REFACTOR][RPC] Centralize RPC traits and method names#1067

[REFACTOR][RPC] Centralize RPC traits and method names#1067
moisesPompilio wants to merge 7 commits into
getfloresta:masterfrom
moisesPompilio:centralize-trait-and-type-rpc

moisesPompilio commented May 15, 2026

Uh oh!

moisesPompilio commented May 21, 2026

Uh oh!

Davidson-Souza Jun 3, 2026

Uh oh!

Davidson-Souza Jun 3, 2026

Uh oh!

Davidson-Souza Jun 3, 2026

Uh oh!

Davidson-Souza Jun 3, 2026

Uh oh!

Davidson-Souza Jun 3, 2026

Uh oh!

Davidson-Souza Jun 3, 2026

Uh oh!

Davidson-Souza Jun 3, 2026

Uh oh!

Davidson-Souza Jun 3, 2026

Uh oh!

Davidson-Souza Jun 3, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants