# nervosnetwork/fiber architecture

> Architecture diagram of the GitHub repository nervosnetwork/fiber, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nervosnetwork/fiber
- Repository: https://github.com/nervosnetwork/fiber

## Overview

##### Main Components
- Core Node Application – Represented by the main binary (src/main.rs) that ties together all modules.
- Payment Channel & Micropayment Functionality (“fiber” module) – This contains the heart of the protocol: channel management (opening/closing), payment routing, fee calculations, gossip, network path management, and key management.
- Cross-Chain & CKB Interaction (“ckb” and “cch” modules) – “ckb” handles interactions with the Nervos CKB blockchain (signing, funding transactions, smart contracts), while “cch” seems to focus on cross-chain orders and integration (e.g. for payments across networks).
- Invoice Management (“invoice” module) – Manages invoice creation, validation, and cancellation for payment processing.
- RPC Interface (“rpc” module) – Provides external APIs for interacting with node operations such as channel listing, payment status, and configuration.
- Persistence & Storage (“store” module) – Manages local databases, migrations, and storage of channel states and other persistent data.
- Watchtower – Provides additional safety mechanisms for channel security by monitoring channel status and alerting about malicious actions.
- Migration Tools (“migrate” directory) – Offers tools to transition the storage formats between node versions.
- Configuration/Environment – Config files under “config” (for mainnet/testnet), as well as different environment setups within tests.

##### Relationships and Interactions
- The RPC layer for external control.
- The wallet and blockchain modules (ckb) for signing and funding transactions.
- The cross-chain handling (cch) to facilitate swap transactions and asset transitions.
- Payment requests flow from the RPC interface to the fiber module. Within fiber, internal actors take care of channel operations, which then may trigger invoice generation (invoice module) and persist state (store module).
- The watchtower monitors the state by interfacing with both the fiber and store modules, ensuring channel integrity and providing alerts if needed.
- Migration components act as a separate tooling flow (triggered externally or via upgrade procedures) that reads and transforms data in the persistent store.

##### Architectural Patterns & Design Principles
- Modular separation: Although this is a monolithic binary, the code is structured into modules (fiber, ckb, cch, invoice, rpc, store, watchtower) that follow separation of concerns.
- Actor Model: Several modules such as the fiber network, CKB operations, and watchtower use “actor” patterns to manage asynchronous events and communications.
- Configuration-driven: Use of configuration files (YAML) to manage node settings for different networks (mainnet vs. testnet).

##### Relevant Technologies and Frameworks
- Rust & Cargo: The entire project is in Rust, so it inherently uses Rust modules, Cargo for dependencies and build management.
- YAML configurations: For network/node parameters.
- External CLI tools: e.g. ckb-cli for wallet operations.
- GitHub Actions & CI: The workflows and CI configurations hint at continuous integration pipelines that could be noted as supporting processes outside the core runtime.

##### Be Detailed Yet Structured
- That every module shown in the file structure (especially those under src/ such as fiber, ckb, cch, invoice, rpc, watchtower, and store) is represented with its key responsibilities.
- Configuration management and migration processes since they are critical during upgrades.

## Diagram (Mermaid)

```mermaid
flowchart TD
    A["Core Node Application"]:::core
    B["Fiber Payment Module"]:::payment
    C["CKB Interaction Module"]:::blockchain
    D["Cross-Chain Handler (CCH)"]:::blockchain
    E["Invoice Service"]:::payment
    F["RPC Interface"]:::rpc
    G["Persistence Layer"]:::storage
    H["Watchtower"]:::storage
    I["Migration Tool"]:::utility
    J["Configuration & Environment"]:::utility

    A -->|"initializes"| B
    A -->|"exposes_API"| F
    A -->|"reads_config"| J
    F -->|"triggers_payment_request"| B
    B -->|"initiates_invoice"| E
    B -->|"updates_channel_state"| G
    B -->|"sends_transaction_requests"| C
    B -->|"facilitates_crosschain"| D
    H -->|"monitors_channels"| B
    H -->|"monitors_state"| G
    I -->|"migrates_data"| G

    click A "https://github.com/nervosnetwork/fiber/blob/develop/src/main.rs"
    click B "https://github.com/nervosnetwork/fiber/tree/develop/src/fiber"
    click C "https://github.com/nervosnetwork/fiber/tree/develop/src/ckb"
    click D "https://github.com/nervosnetwork/fiber/tree/develop/src/cch"
    click E "https://github.com/nervosnetwork/fiber/tree/develop/src/invoice"
    click F "https://github.com/nervosnetwork/fiber/tree/develop/src/rpc"
    click G "https://github.com/nervosnetwork/fiber/tree/develop/src/store"
    click H "https://github.com/nervosnetwork/fiber/tree/develop/src/watchtower"
    click I "https://github.com/nervosnetwork/fiber/tree/develop/migrate"
    click J "https://github.com/nervosnetwork/fiber/tree/develop/config"

    classDef core fill:#FFD700,stroke:#333,stroke-width:2px;
    classDef payment fill:#90EE90,stroke:#333,stroke-width:2px;
    classDef blockchain fill:#ADD8E6,stroke:#333,stroke-width:2px;
    classDef rpc fill:#FFA07A,stroke:#333,stroke-width:2px;
    classDef storage fill:#DDA0DD,stroke:#333,stroke-width:2px;
    classDef utility fill:#F0E68C,stroke:#333,stroke-width:2px;
```
