README.md

F1r3fly Documentation

Workspace Overview

The Cargo workspace contains 11 crates:

Crate	Role	Docs
shared	Foundation types, KV store abstraction, LMDB bindings	docs
crypto	Hashing (Blake2b, Keccak256, SHA256), signing (Secp256k1, Ed25519), TLS certs	docs
models	Protobuf-generated types, domain structs, Rholang AST, sorted collections	docs
rspace++	Tuple space engine: produce/consume matching, LMDB-backed trie history	docs
rholang	Rholang interpreter: parser, normalizer, reducer, cost accounting, system processes	docs
casper	CBC Casper consensus: block creation/validation, DAG, safety oracle, finalization	docs
block-storage	Block persistence, DAG storage (imbl), casper buffer, deploy index	docs
comm	P2P networking: Kademlia DHT, TLS transport, connection management	docs
node	Binary entry point: boot sequence, gRPC/HTTP servers, CLI, diagnostics	docs
graphz	Graphviz DOT generation for DAG visualization	docs

Architecture & Dependency Graph

                         ┌──────────┐
                         │   node   │  (binary, orchestrator)
                         └────┬─────┘
              ┌───────┬───────┼───────┬──────────┐
              v       v       v       v          v
          ┌──────┐ ┌──────┐ ┌──────┐ ┌───────┐ ┌──────┐
          │casper│ │ comm │ │graphz│ │rholang│ │block-│
          │      │ │      │ │      │ │       │ │store │
          └──┬───┘ └──┬───┘ └──────┘ └───┬───┘ └──┬───┘
             │        │                   │        │
     ┌───────┼────────┤                   │        │
     v       v        v                   v        v
  ┌──────┐ ┌──────┐ ┌──────┐        ┌────────┐ ┌──────┐
  │models│ │crypto│ │shared│        │rspace++│ │shared│
  └──┬───┘ └──┬───┘ └──────┘        └────┬───┘ │      │
     │        │                          │      └──────┘
     v        v                          v
  ┌──────┐ ┌──────┐                   ┌──────┐
  │crypto│ │shared│                   │shared│
  └──┬───┘ └──────┘                   └──────┘
     v
  ┌──────┐
  │shared│
  └──────┘

Dependency direction: shared is the leaf dependency; node is the root.

---

Module Documentation

Core Crates

Module	Description
shared	Foundation types, KV store abstraction, LMDB bindings
crypto	Hashing, signing, certificates
models	Protobuf types, Rholang AST, sorted collections
rspace	Tuple space engine, produce/consume matching, trie history
rholang	Interpreter, reducer, cost accounting, system processes
casper	CBC Casper consensus, block creation/validation, finalization
block-storage	Block persistence, DAG storage, deploy index
comm	P2P networking, Kademlia DHT, TLS transport
node	Binary entry point, gRPC/HTTP servers, CLI, diagnostics
graphz	Graphviz DOT generation for DAG visualization

Cross-Cutting

Document	Description
Data Flows	Block lifecycle and deploy execution flows
Patterns & Conventions	Concurrency, error handling, serialization, env vars

Consensus

Document	Description
Casper Overview	Block creation, validation, DAG merging, finalization
Consensus Protocol	End-to-end protocol walkthrough, abstraction boundaries for adding new consensus
Byzantine Fault Tolerance	BFT architecture, clique oracle, equivocation detection, slashing
Synchrony Constraint	Synchrony constraint mechanism, configuration, troubleshooting
Consensus Configuration	FTT and synchrony threshold semantics, recommended values

Rholang Language

Document	Description
Rholang Evaluator	Language overview, CLI usage, known issues
Rholang Module Docs	Interpreter internals, reducer, system processes
Rholang Tutorial	Language tutorial
Pattern Matching	Pattern matching guide
Ollama Integration	Local LLM integration via Ollama
Reference Documentation	Language reference by topic

Cryptography

Document	Description
Crypto Module	Hashing, signing, certificates
Schnorr/FROST Design	Schnorr and FROST signature scheme design
Schnorr/FROST Status	Implementation status

Architecture & Design

Document	Description
F1r3fly Architecture	High-level architecture overview
F1r3fly State Diagram	Node lifecycle state diagrams
Namespaces & Scaling	Namespace organization, regional namespaces
Rholang Language Analysis	Language design analysis
Features	Feature requirements and status

Genesis & Token Identity

The native token's name, symbol, and decimals are configured before genesis and baked into the on-chain TokenMetadata contract at rho:system:tokenMetadata. They are immutable after genesis and exposed via /api/status. See:

• defaults.conf — native-token-name, native-token-symbol, native-token-decimals under casper.genesis-block-data
• Docker Genesis Configuration — compose env var overrides, API and on-chain query examples
• Consensus Protocol § Configuration — genesis-locked parameters

Infrastructure

Document	Description
API Reference	Complete HTTP REST + gRPC endpoint reference with parameters and curl examples
WebSocket Events	/ws/events endpoint: 10 event types, startup replay, payload schemas
Docker Setup	Docker compose for shard, standalone, monitoring
RNode API	Protocol Buffer API documentation (legacy Scala reference)
LFS Requester Architecture	LFS tuple space concurrency design
Whiteblock Test Plan	Network testing plan

Archive

Legacy and superseded documents are in archive/.