blvm-node 0.1.0

Bitcoin Commons BLVM: Minimal Bitcoin node implementation using blvm-protocol and blvm-consensus
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128

# QUIC RPC Server

## Overview

blvm-node optionally supports JSON-RPC over QUIC using Quinn, providing improved performance and security compared to the standard TCP RPC server.

## Features

- **Encryption**: Built-in TLS encryption via QUIC
- **Multiplexing**: Multiple concurrent requests over single connection
- **Better Performance**: Lower latency, better congestion control
- **Backward Compatible**: TCP RPC server always available

## Usage

### Basic (TCP Only - Default)

```rust
use blvm_node::rpc::RpcManager;
use std::net::SocketAddr;

let tcp_addr: SocketAddr = "127.0.0.1:8332".parse().unwrap();
let mut rpc_manager = RpcManager::new(tcp_addr);
rpc_manager.start().await?;
```

### With QUIC Support

```rust
use blvm_node::rpc::RpcManager;
use std::net::SocketAddr;

let tcp_addr: SocketAddr = "127.0.0.1:8332".parse().unwrap();
let quinn_addr: SocketAddr = "127.0.0.1:18332".parse().unwrap();

// Option 1: Create with both transports
#[cfg(feature = "quinn")]
let mut rpc_manager = RpcManager::with_quinn(tcp_addr, quinn_addr);

// Option 2: Enable QUIC after creation
let mut rpc_manager = RpcManager::new(tcp_addr);
#[cfg(feature = "quinn")]
rpc_manager.enable_quinn(quinn_addr);

rpc_manager.start().await?;
```

## Configuration

QUIC RPC requires the `quinn` feature flag:

```toml
[dependencies]
blvm-node = { path = "../blvm-node", features = ["quinn"] }
```

Or when checking a build locally (prefer `check` over full `build` on resource-constrained hosts):

```bash
cargo check --features quinn
```

## Security Notes

- **Self-Signed Certificates**: Currently uses self-signed certificates for development
- **Production**: Should use proper certificate management for production
- **Bearer / HTTP auth vs QUIC**: JSON-RPC over QUIC does not carry HTTP `Authorization` headers. **When `rpc_auth.required` is true**, the node **does not start the QUIC JSON-RPC listener** (TCP HTTP JSON-RPC is used for authenticated access). A warning is logged at startup. P2P over QUIC (if enabled elsewhere) is unaffected by this RPC guard.
- **Optional QUIC RPC without mandatory auth**: If authentication is not required, QUIC RPC is subject to the same **IP-based** rate limiting and optional auth paths as configured; Bearer tokens still cannot be sent like on HTTP—use TCP RPC for header-based credentials.
- **Same Security Boundaries**: QUIC RPC has the same JSON-RPC surface boundaries as TCP RPC (e.g. no wallet access beyond what RPC exposes)

## P2P QUIC

Transport preferences for peer connections (e.g. `quinn` feature for P2P) are separate from JSON-RPC over QUIC. This document describes **JSON-RPC over QUIC** only.

## Client Usage

Clients need QUIC support. Example with `quinn`:

```rust
use quinn::Endpoint;
use std::net::SocketAddr;

let server_addr: SocketAddr = "127.0.0.1:18332".parse().unwrap();
let endpoint = Endpoint::client("0.0.0.0:0".parse().unwrap())?;
let connection = endpoint.connect(server_addr, "localhost")?.await?;

// Open bidirectional stream
let (mut send, mut recv) = connection.open_bi().await?;

// Send JSON-RPC request
let request = r#"{"jsonrpc":"2.0","method":"getblockchaininfo","params":[],"id":1}"#;
send.write_all(request.as_bytes()).await?;
send.finish().await?;

// Read response
let mut response = Vec::new();
recv.read_to_end(&mut response).await?;
let response_str = String::from_utf8(response)?;
```

## Benefits Over TCP

1. **Encryption**: Built-in TLS, no need for separate TLS layer
2. **Multiplexing**: Multiple requests without head-of-line blocking
3. **Connection Migration**: Survives IP changes
4. **Lower Latency**: Better congestion control
5. **Stream-Based**: Natural fit for request/response patterns

## Limitations

- **Ecosystem tooling**: Most JSON-RPC clients assume TCP RPC
- **Client Support**: Requires QUIC-capable clients
- **Certificate Management**: Self-signed certs need proper handling for production
- **Network Requirements**: Some networks may block UDP/QUIC

## When to Use

- **High-Performance Applications**: When you need better performance than TCP
- **Modern Infrastructure**: When all clients support QUIC
- **Enhanced Security**: When you want built-in encryption without extra TLS layer
- **Internal Services**: When you control both client and server

## When Not to Use

- **Ecosystem tooling**: Need TCP-only RPC scripts
- **Legacy Clients**: Clients that only support TCP/HTTP
- **Simple Use Cases**: TCP RPC is simpler and sufficient for most cases