# QUIC RPC Server
## Overview
blvm-node optionally supports JSON-RPC over **HTTP/3 on QUIC** using Quinn + **`h3`**, sharing the same **`RpcServer`** instance as TCP HTTP JSON-RPC.
## 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**: The listener generates a short-lived self-signed certificate by default (development-style).
- **Production**: Use operational certificate provisioning appropriate for your deployment (or terminate TLS at a QUIC-aware proxy you trust).
- **HTTP/3 + `[rpc_auth]`**: QUIC JSON-RPC speaks **HTTP/3** (TLS ALPN **`h3`**). **`Authorization: Bearer …`** and all **`RpcAuthManager`** / **`rpc_auth.required`** semantics match **TCP HTTP JSON-RPC** (shared `dispatch_json_rpc_post_body` on the same **`Arc<RpcServer>`**).
- **Same handler surface**: QUIC HTTP/3 hits the live node handlers (storage, mempool, etc.), not a stub server.
## 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
Use an **HTTP/3** stack on top of QUIC (**ALPN `h3`**): issue **`POST /`** with **`Content-Type: application/json`** and the same JSON-RPC body as TCP HTTP. Supply **`Authorization`** headers exactly like HTTP/1.
Development/tests in-tree use **`h3`** + **`h3-quinn`** (see `tests/quic_rpc_smoke_tests.rs` behind **`--features quinn`**).
Raw “JSON bytes only” QUIC streams are **not** the RPC wire format anymore.
## 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