# babylonlabs-io/babylon architecture

> Architecture diagram of the GitHub repository babylonlabs-io/babylon, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2024-12-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/babylonlabs-io/babylon
- Repository: https://github.com/babylonlabs-io/babylon

## Overview

Key Components to Include in the System Design:

##### Core Protocol Layer
- Bitcoin Timestamping Module (x/btccheckpoint)
- Bitcoin Staking Module (x/btcstaking)
- Bitcoin Light Client Module (x/btclightclient)
- Finality Module (x/finality)
- Checkpointing Module (x/checkpointing)
- Epoching Module (x/epoching)
- Incentive Module (x/incentive)
- Monitor Module (x/monitor)
- Mint Module (x/mint)

##### Infrastructure Layer
- Application Core (app/)
- Cryptographic Components (crypto/)
- Client Interface (client/)
- Command Line Interface (cmd/)
- WASM Bindings (wasmbinding/)

##### External Interactions
- Bitcoin Network Integration
- PoS Chain Interactions
- Client Applications

##### Use a Multi-Layer Architecture
- [External Systems Layer]
- Bitcoin Network <---> | BTC Light Client | <---> PoS Chains

- [Protocol Layer]     |  BTC Timestamping |
- BTC Staking       |
- Finality          |
- Checkpointing     |
- [Core Layer]        |  Application Core  |
- State Management  |
- [Infrastructure]    |  CLI/API/RPC       |

##### Elements
- Module boundaries and interfaces
- Data flow directions
- Security boundaries
- External service integration points
- State management components
- Consensus mechanisms

##### Technical Details to Highlight
- BLS signature verification (crypto/bls12381)
- ECDSA operations (crypto/ecdsa)
- Schnorr signature adaptation (crypto/schnorr-adaptor-signature)
- WASM smart contract integration
- Protocol upgrade paths

##### Bitcoin Integration
- BTC header validation flow
- Staking transaction verification
- Timestamp submission process

##### Security Features
- BLS signature aggregation
- Multi-signature schemes
- Transaction validation paths

##### State Management
- Epoch transitions
- Checkpoint creation and verification
- Finality gadget integration

## Diagram (Mermaid)

```mermaid
graph TB
    %% External Systems Layer
    subgraph External
        BTC[Bitcoin Network]
        PoS[PoS Chains]
    end

    %% Core Protocol Layer
    subgraph CoreProtocol
        BTCTime["BTC Timestamping"]:::protocol
        BTCStake["BTC Staking"]:::protocol
        BTCLight["BTC Light Client"]:::protocol
        Finality["Finality"]:::protocol
        Check["Checkpointing"]:::protocol
        Epoch["Epoching"]:::protocol
        Incentive["Incentive"]:::protocol
        Monitor["Monitor"]:::protocol
        Mint["Mint"]:::protocol
    end

    %% Infrastructure Layer
    subgraph Infrastructure
        AppCore["Application Core"]:::infra
        Crypto["Cryptographic Components"]:::security
        Client["Client Interface"]:::infra
        CLI["Command Line Interface"]:::infra
        WASM["WASM Bindings"]:::infra
    end

    %% Cryptographic Components
    subgraph CryptoComponents
        BLS["BLS Signatures"]:::security
        ECDSA["ECDSA Operations"]:::security
        Schnorr["Schnorr Signatures"]:::security
    end

    %% Relationships
    BTC <--> BTCLight
    BTCLight --> BTCTime
    BTCLight --> BTCStake
    BTCStake --> Finality
    BTCTime --> Check
    Check --> Epoch
    Epoch --> Incentive
    Monitor --> BTCLight
    Monitor --> BTCStake
    Mint --> Incentive

    AppCore --> CoreProtocol
    Crypto --> CryptoComponents
    Client --> AppCore
    CLI --> Client
    WASM --> AppCore

    PoS <--> Finality

    %% Click Events
    click BTCTime "https://github.com/babylonlabs-io/babylon/tree/main/x/btccheckpoint/"
    click BTCStake "https://github.com/babylonlabs-io/babylon/tree/main/x/btcstaking/"
    click BTCLight "https://github.com/babylonlabs-io/babylon/tree/main/x/btclightclient/"
    click Finality "https://github.com/babylonlabs-io/babylon/tree/main/x/finality/"
    click Check "https://github.com/babylonlabs-io/babylon/tree/main/x/checkpointing/"
    click Epoch "https://github.com/babylonlabs-io/babylon/tree/main/x/epoching/"
    click Incentive "https://github.com/babylonlabs-io/babylon/tree/main/x/incentive/"
    click Monitor "https://github.com/babylonlabs-io/babylon/tree/main/x/monitor/"
    click Mint "https://github.com/babylonlabs-io/babylon/tree/main/x/mint/"
    click AppCore "https://github.com/babylonlabs-io/babylon/tree/main/app/"
    click Crypto "https://github.com/babylonlabs-io/babylon/tree/main/crypto/"
    click Client "https://github.com/babylonlabs-io/babylon/tree/main/client/"
    click CLI "https://github.com/babylonlabs-io/babylon/tree/main/cmd/babylond/"
    click WASM "https://github.com/babylonlabs-io/babylon/tree/main/wasmbinding/"
    click BLS "https://github.com/babylonlabs-io/babylon/tree/main/crypto/bls12381/"
    click ECDSA "https://github.com/babylonlabs-io/babylon/tree/main/crypto/ecdsa/"
    click Schnorr "https://github.com/babylonlabs-io/babylon/tree/main/crypto/schnorr-adaptor-signature/"

    %% Styles
    classDef protocol fill:#2374ab
    classDef infra fill:#707070
    classDef security fill:#ffb347
    classDef external fill:#ffffff,stroke:#000000

    %% Legend
    subgraph Legend
        P["Protocol Module"]:::protocol
        I["Infrastructure Component"]:::infra
        S["Security Component"]:::security
        E["External System"]:::external
    end
```
