Railguard

Railguard is structured as a Cargo workspace with multiple crates. This reference covers the public APIs of each crate.

Crate Overview

Crate	Description	Primary Exports
`rg-types`	Shared data structures	`Config`, `Verdict`, `Receipt`, `RpcRequest`
`rg-policy`	Policy engine	`RuntimePolicy`, `inspect()`, `decode_raw_transaction()`
`rg-proxy`	HTTP/JSON-RPC server	`AppState`, `start_server()`, `create_router()`
`rg-cloud`	Cloud integration	`device_code_flow()`, `sync_policy()`, `push_receipts()`

Quick Links

Types Reference — All data structures
Policy Engine — Deep dive into inspection logic
Configuration — Config file format

Usage Example

use rg_types::{Config, Verdict};
use rg_policy::{RuntimePolicy, inspect};
use rg_proxy::{AppState, start_server};
use tokio::sync::mpsc;
 
#[tokio::main]
async fn main() -> eyre::Result<()> {
    // Load config
    let config: Config = toml::from_str(&std::fs::read_to_string("railguard.toml")?)?;
 
    // Build runtime policy
    let policy = RuntimePolicy::from_config(&config.firewall)?;
 
    // Create event channel for TUI
    let (event_tx, _event_rx) = mpsc::channel(1000);
 
    // Create app state
    let state = AppState::new(&config, policy, event_tx)?;
 
    // Start server
    start_server(state).await?;
 
    Ok(())
}

Error Handling

Railguard uses different error types depending on context:

Crate	Error Type	Description
`rg-types`	—	No errors (pure data)
`rg-policy`	`PolicyError`	Config parsing, signature parsing
`rg-policy`	`DecodeError`	RLP/ABI decoding failures
`rg-proxy`	`ProxyError`	Server, client, config errors
`bin/rg`	`eyre::Report`	Top-level error handling

Example Error Handling

use rg_policy::{RuntimePolicy, PolicyError};
 
fn load_policy(config: &FirewallConfig) -> Result<RuntimePolicy, PolicyError> {
    RuntimePolicy::from_config(config)
}
 
// PolicyError variants:
// - InvalidSignature { signature, reason }
// - InvalidAddress { address }
// - ConfigParsing { source }

JSON-RPC Handling

Railguard implements JSON-RPC 2.0 with full spec compliance:

use rg_types::{RpcInput, RpcRequest, RpcResponse};
 
// Single request
let single: RpcRequest = serde_json::from_str(r#"
    {"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}
"#)?;
 
// Batch request
let batch: RpcInput = serde_json::from_str(r#"
    [
        {"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1},
        {"jsonrpc":"2.0","method":"eth_chainId","params":[],"id":2}
    ]
"#)?;
 
// Notification (no id = no response)
let notification: RpcRequest = serde_json::from_str(r#"
    {"jsonrpc":"2.0","method":"eth_subscribe","params":[]}
"#)?;
assert!(notification.id.is_none());

Thread Safety

All public types are designed for concurrent use:

RuntimePolicy is Send + Sync (wrapped in Arc in AppState)
AppState is Clone (uses Arc internally)
Event channels use tokio::sync::mpsc

Feature Flags

[dependencies]
rg-policy = { version = "0.1", features = ["simulation"] }

Feature	Description	Default
`simulation`	Enables `revm` integration for trace-based analysis	No
`cloud`	Enables Railguard Cloud integration	No

Minimum Supported Rust Version

Railguard requires Rust 1.75 or later.

Next Steps

Types Reference — Detailed type documentation
Configuration — Config file format
Policy Engine — Inspection logic deep dive

API Reference