How fabriclabs/fabric works
Project Type and Purpose
• Project Type: Open-source reference client library & CLI for building peer-to-peer apps on Bitcoin.
• Purpose: Provide a JavaScript API (actor-model, event emitter) plus CLI tools to run Fabric nodes, interact with blockchains, and extend via plugins/services.
File Structure
• Top-Level Folders:
• /types: JS classes (Peer, Chain, Message, Contract, etc.) defining core abstractions.
• /services: Adapters for blockchain & network services (bitcoin, lightning, redis, zmq, local, etc.).
• /schemata: JSON schemas for message validation.
• /stores: Persistence layers (LevelDB, in-memory).
• /scripts: Command‐line scripts to spin up nodes, playnets, wallets, benchmarks.
• /examples & /assets: Front-end examples and static assets for demo web UIs.
• /docs: Generated API docs and guides.
• /functions: Utility functions (error handling, JSON/HTML formatting).
• /settings: Environment configurations (playnet, local, test).
• /tests: Unit/integration tests covering all modules.
• Configuration Files:
• package.json, nix files, .envrc, .gitignore.
• Build & CI workflows under .github/workflows.
Core Components & Boundaries
A. Fabric Core Node (Peer)
• Implements actor model, event emitter
• Loads modules from /types
• Manages protocol state (chain, mempool, contracts, sessions)
• Publishes and subscribes to messages
B. Services Layer
• Bitcoin Service (bitcoind RPC)
• Lightning Service (Lightning Daemon)
• Redis Service (pub/sub, caching)
• ZMQ Service (message bus)
• Local Service (in-process stub)
• Turntable, TXT, Exchange, etc.
Each service knows how to connect to its external system, expose data/events to the Core Node.
C. Persistence Layer (Stores)
• LevelDB or in-memory stores for blocks, transactions, state snapshots.
D. Schemata & Validation
• JSON schema definitions used by Core Node to validate incoming/outgoing messages.
E. CLI & Developer Interfaces
• fabric CLI (invokes scripts under /scripts)
• npm run dev HTTP dev interface
• npm run docs and npm run examples for local servers
F. Plugins & Extensions
• HTTP plugin, Hub plugin, Doorman, Zapier, etc.
• Each plugin subscribes to core events and provides an external interface.
G. External Systems
• Bitcoin full node (bitcoind)
• Lightning node
• Other Fabric peers (p2p network over TCP/ZeroMQ)
• Browser front-end (for examples)
Relationships and Data Flows
• CLI/Dev Interface ← listens to Core Node events and issues commands.
Architectural Patterns & Principles
• Actor Model / Event-Driven: everything communicates via messages/events.
• Modular & Plugin-Based: core logic is separated from service adapters and plugins.
• Layered: API layer (types), service adapters, persistence, transport.
Technologies & Frameworks
• Node.js (v16+), native modules: secp256k1, level, zeromq.
• JSON Schema for message validation.
• ZeroMQ / Redis for pub/sub.
• HTTP (Express or similar) for dev server.
• LevelDB for local storage.
• Nix/devshell for reproducible environments.
Essential Checklist
• [ ] Services adapters grouped together.
• [ ] Persistence layer (stores).
• [ ] Schemata validation component.
• [ ] Plugin boundary highlighting HTTP/Hub/Doorman.
• [ ] External dependencies (bitcoind, lightning, other Fabric peers).
• [ ] Developer interfaces (CLI, HTTP, Examples).