Skip to content

README.md

Latest commit

 

History

History
143 lines (116 loc) · 8.66 KB

README.md

File metadata and controls

143 lines (116 loc) · 8.66 KB
Raw

F1r3fly Documentation

Workspace Overview

The Cargo workspace contains 10 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 Philosophy Design principles, deploy-fairness remedy ladder, CBC Casper relation
Casper Glossary Canonical casper-domain terms (split from the central glossary)
Theory dossiers Fork choice, finalized floor, merge algebra, and slashing dossiers
Validation FV campaign gap analysis, merge-recovery validation plan
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
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:

Infrastructure

Document Description
Joining an Existing Network Attaching a node to a shard it did not start with: bootstrap address, required flags, what a completed join looks like, and bonding it as a validator
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
Formal Verification Verification method, verified areas, implementation obligations, and local tool runs
Release Process Exact-SHA canary, stable release, and Deployment Train strategy
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/.