Rieko
Operational intelligence engine for Bitcoin and Lightning infrastructure
A deterministic systems engine written in Rust that ingests live telemetry from Bitcoin Core and LND, builds an in-memory graph, evaluates typed detectors, generates prioritized operational recommendations, and executes deterministic what-if simulations.
"Rieko helps Bitcoin and Lightning operators understand what is happening, why it matters, and what actions they should consider—deterministically, safely, and without blind automation."
Telemetry Volume vs. Actionable Signal
Operating Bitcoin Core and LND nodes generates massive streams of telemetry: channel capacities, HTLC forwarding events, peer disconnections, and dynamic fee fluctuations.
Operators face two failure modes: drowning in noisy dashboards without clear root-cause context, or relying on black-box automated rebalancing scripts that execute dangerous, costly mutations against live channels without deterministic simulation.
Typed Pipeline & Mathematical Projections
Rieko structures node management as an immutable intelligence pipeline. Raw REST/RPC events are normalized into domain models, mapped onto a typed routing graph, and evaluated by deterministic detectors.
Instead of unverified rebalancing, Rieko v2 computes deterministic what-if simulations: projecting the exact mathematical outcome of a liquidity transfer against a historical snapshot with zero node contact.
Deterministic execution from raw LND telemetry to replayable what-if projections
Ingestion & Normalization
Pulls channel, peer, and forwarding telemetry via LND REST or Bitcoin Core RPC normalizers into canonical domain models.
Engineering Principles & Safety Model
Deterministic Detection
Every finding has a stable identity derived from canonical evidence. Replaying a snapshot produces zero duplicate alerts.
Typed Operational Evidence
Findings and recommendations are typed Rust structs with strictly validated invariants.
Decoupled LLM Layer
Language models provide optional human-readable summaries; they never participate in threshold evaluation or detector decisions.
Zero Node Mutation
The simulation subsystem produces local projections only. Simulation routes cannot contact or mutate a live node.
Single-Writer WAL Persistence
SQLite runs in WAL mode with synchronous=NORMAL. Monitor locks prevent dual writers while enabling concurrent read-only queries.
Append-Only Auditability
State changes and simulation projections are recorded into an append-only audit trail enforced by database triggers.
Modular Kernel & Engine Crates
Organized into clear domain layers ensuring pure mathematical logic is decoupled from side effects.
Core domain primitives, channel models, and balance types
Typed Lightning topology graph with path-finding algorithms
Pure mathematical simulation models for liquidity redistribution
SQLite WAL backend, transaction management, and migrations
Typed findings, recommendation schemas, and fingerprinting
Deterministic liquidity and drift detection algorithms
Finding-to-recommendation mapping and prioritization
Simulation orchestration, projection comparisons, and reporting
Alert deduplication, persistent cooldowns, and Telegram dispatcher
Optional OpenAI/Groq client for plain-language evidence explanation
O(1) system health assessment and node connectivity status
LND REST client, macaroon authentication, and data normalizer
Bitcoin Core RPC client and mempool/block normalizer
axum HTTP API routes, middleware, and embedded frontend delivery
Command-line interface entrypoint for scan, monitor, and simulations
Feature-gated node mutation module with strict runtime interlocks
Pure Liquidity Redistribution Model
Every simulation is bound to exact source and destination channel snapshots observed at runtime. Replaying with identical inputs generates the same cryptographic SHA-256 fingerprint.
- ›Projections compute baselines, deltas, assumptions, and confidence bounds.
- ›Rate-limited to 5 requests/sec to prevent local compute exhaustion.
- ›Contains explicit safety statement guaranteeing zero mutation.
Single-Writer WAL Architecture
Rieko uses an embedded SQLite database versioned transactionally with automatic schema upgrades. Readers query concurrently while a single monitor thread holds write authority.
- ›WAL mode with synchronous=NORMAL and finite busy timeouts.
- ›Append-only audit trail enforced by database triggers.
- ›Status queries execute in O(1) time without full table scans.