Add fee estimation RPC method and CLI command

[horologger]

Add fee estimation RPC method and CLI command

Summary

This PR adds fee estimation capabilities to spaced, allowing users to query Bitcoin fee estimates through both RPC and command-line interfaces. Previously, fee estimation was only available internally when wallet operations needed it, requiring users to call Bitcoin Core directly for fee information.

Features Added

1. RPC Method: estimatefee

A new RPC method that exposes Bitcoin Core's estimatesmartfee functionality through spaced, with automatic conversion from BTC/kB to sat/vB for consistency.

Parameters:

• conf_target (u32): Target number of blocks for confirmation (1-1008)
• estimate_mode (Option): Fee estimation mode - "unset", "conservative", or "economical" (defaults to "unset")

Response:

{
  "feerate_sat_vb": 1,
  "blocks": 6
}

2. CLI Command: space-cli estimatefee

A new command-line subcommand for easy fee estimation access.

Usage:

# Default (6 blocks, unset mode)
space-cli estimatefee

# Specify confirmation target
space-cli estimatefee --conf-target 1
space-cli estimatefee --conf-target 48

# Specify estimation mode
space-cli estimatefee --mode conservative
space-cli estimatefee --mode economical

# Combined options
space-cli estimatefee --conf-target 6 --mode conservative

# JSON output
space-cli --output-format json estimatefee

Changes

client/src/rpc.rs

• Added FeeEstimateResponse struct with feerate_sat_vb and blocks fields
• Added estimate_fee method to Rpc trait
• Implemented estimate_fee in RpcServerImpl:
  • Uses tokio::task::spawn_blocking to handle blocking Bitcoin RPC calls in async context
  • Calls Bitcoin Core's estimatesmartfee RPC
  • Converts fee rates from BTC/kB to sat/vB (multiplies by 100,000 and rounds up)
  • Returns structured response with error handling

client/src/bin/space-cli.rs

• Added EstimateFee variant to Commands enum
• Added command handler with support for:
  • Configurable confirmation target (default: 6 blocks)
  • Optional estimation mode parameter
  • Text and JSON output formats

Implementation Details

• Fee Rate Conversion: Converts Bitcoin Core's BTC/kB format to sat/vB using: (fee_rate * 100_000.0).ceil() as u64
• Async Handling: Uses spawn_blocking to handle blocking RPC calls without blocking the async runtime
• Error Handling: Properly handles RPC errors and missing fee rate data with descriptive error messages
• Consistency: Matches the internal fee estimation logic used in RpcWallet::estimate_fee_rate()

Usage Examples

RPC Call

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "estimatefee",
  "params": [6, "unset"]
}

CLI Output (Text)

Fee rate: 1 sat/vB
Blocks: 6

CLI Output (JSON)

{
  "feerate_sat_vb": 1,
  "blocks": 6
}

Benefits

1. Convenience: Users no longer need to call Bitcoin Core directly for fee estimates
2. Consistency: Fee rates are returned in sat/vB format, matching internal usage
3. Flexibility: Supports multiple confirmation targets and estimation modes
4. Integration: Works seamlessly with existing spaced infrastructure

Testing

• Code compiles successfully
• RPC method is properly exposed through jsonrpsee
• CLI command integrates with existing command structure
• Error handling tested for various scenarios

Impact

• Breaking changes: None
• Backward compatibility: Fully maintained - this is a new feature addition
• Dependencies: No new dependencies added
• Performance: Minimal impact - uses existing Bitcoin RPC infrastructure

Related Documentation

See example_fee_estimation_rpc.md for comprehensive examples and usage instructions covering:

• Spaced RPC method usage
• CLI command usage
• Direct Bitcoin Core RPC calls (for reference)
  PR_ESTIMATEFEE.md
  example_fee_estimation_rpc.md