# riftresearch/protocol architecture

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

- Interactive diagram: https://gitdiagram.com/riftresearch/protocol
- Repository: https://github.com/riftresearch/protocol

## Overview

##### Project type and purpose
- Rift Protocol is a Rust-based monorepo implementing a trustless cross-chain swap protocol between Bitcoin and Ethereum.
- It contains:
- On-chain smart contracts (in `contracts/`) for auctions, order settlement, and light-client state.
- Rust “circuits” (`crates/bitcoin-light-client-core`, `crates/rift-core`) for verifying Bitcoin consensus and handling state updates.
- Off-chain indexers and servers (e.g. `bin/hypernode`, `bin/data-engine-server`) that watch both chains, build proofs, and submit transactions.
- Auxiliary tooling: devnet launcher, market-maker bot, checkpoint downloader, benchmarks, SDK, and Python lab experiments.

##### File structure
Top-level layout:
├─ contracts/            Solidity code, artifacts, tests, Foundry config
├─ crates/               Core Rust libraries: light-client, rift-core, data-engine, SDK, Sol-bindings
├─ bin/                  Executables: devnet, hypernode, data-engine-server, market-maker, etc.
├─ integration-tests/    End-to-end tests across components
├─ lab/                  Python research scripts (optional)
├─ test-data/            Sample Bitcoin blocks and headers for local testing
├─ Dockerfile.* / Makefile / GitHub workflows for CI/CD and container builds

Patterns & clues:
- “crates” embody core business logic and proof circuits.
- “bin” modules wire those crates into runnable services.
- “contracts” deploy on Ethereum and form the trust root for swaps.
- Integration tests simulate full protocol flows.

##### README
- Emphasizes three pillars:
1. Bitcoin light-client circuit (`bitcoin-light-client-core`)
2. Settlement & proof circuit (`rift-core`)
3. Solidity contracts (`contracts/`)
- Highlights `hypernode` as the off-chain indexer+relayer.
- Mentions DevNet to stand up local test chains.

a. Main components:
- Bitcoin Network (Full Node RPC)
- Ethereum Network (RPC + Smart Contracts)
- Off-chain Services:
– Hypernode (indexer, proof generator, watcher)
– Data Engine Server (database for block data, MMR leaves)
– Market-maker bot, checkpoint downloader, benchmarks
- Proof circuits (Rust crates)
- DevNet orchestrator / Docker environment
- SDK for client integrations

b. Relationships & interactions:
1. Hypernode polls Bitcoin full node → feeds blocks to Data Engine → runs light-client circuit to update MMR state.
2. Proof generator (rift-core) builds SPV/settlement proofs → submits them via Ethereum RPC to Contracts.
3. Ethereum Contracts emit events (OrderCreated, ChallengeRaised) → Hypernode listens → triggers off-chain actions.
4. Market-maker or external client calls Contracts → Contracts lock/swap assets → events.
5. DevNet simulates both chains locally for end-to-end loops.

c. Architectural patterns/design principles:
- Microservice style: each binary is a standalone service using shared crates.
- Clean separation: “crates” for domain logic, “bin” for orchestration.
- On-chain vs off-chain trust boundary: circuits + proofs vs Solidity code.
- Event-driven interplay between chains mediated by hypernode.

d. Key technologies & frameworks:
- Rust + Cargo for core logic and services.
- Foundry + SP1 for contract development & succinct proofs.
- Docker for DevNet & CI workflows.
- PostgreSQL or embedded KV (dep. of data-engine-server).
- Ethereum & Bitcoin node RPC endpoints.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Bitcoin Zone
    subgraph "Bitcoin Zone"
        direction TB
        BN["Bitcoin Full Node RPC"]:::blockchain
    end

    %% Crates Core Logic
    subgraph "Crates (Core)"
        direction TB
        BLCC["Bitcoin Light-Client Circuit"]:::crate
        RC["Settlement & Proof Circuit"]:::crate
        BCRS["Bitcoin Core RPC Lib"]:::crate
        BDE["Bitcoin Data Engine Crate"]:::crate
        DE["Data Engine Library"]:::crate
        SB["Solidity Bindings"]:::crate
    end

    %% Data Engine Server & DB
    subgraph "Data Engine Server & DB"
        direction TB
        DES["Data Engine Server"]:::service
        DB["Data Engine DB"]:::db
    end

    %% Ethereum Zone
    subgraph "Ethereum Zone"
        direction TB
        EN["Ethereum JSON-RPC"]:::blockchain
        SC["Solidity Smart Contracts"]:::contract
    end

    %% Off-chain Services
    subgraph "Off-chain Services"
        direction TB
        HN["Hypernode"]:::service
        MM["Market-Maker Bot"]:::service
        CD["Checkpoint Downloader"]:::service
        BM["Light-Client Benchmarks"]:::service
        SU["Utilities for Contracts"]:::service
        DN["DevNet Launcher"]:::service
    end

    %% SDK
    SDK["Rust SDK"]:::sdk

    %% Auxiliary
    subgraph "Auxiliary Tools & Tests"
        direction TB
        IT["End-to-End Integration Tests"]:::test
        LAB["Python Lab Experiments"]:::test
        TD["Test Data"]:::test
    end

    %% Connections
    HN -->|JSON-RPC polls| BN
    HN -->|feeds blocks| DES
    DES -->|stores leaves| DB
    DES -->|uses library| DE
    BLCC -->|uses hasher/MMR| DE
    BLCC -->|interfaces| BCRS
    DES -->|uses data engine crate| BDE
    HN -->|generates proofs via| RC
    HN -->|submits txs| EN
    EN -->|emits events| HN
    SC -->|ABI types via| SB
    MM -->|interacts with| SC
    BM -->|benchmarks| BLCC
    CD -->|fetches checkpoints| DB
    SU -->|scripts for| SC
    DN -->|simulates| BN
    DN -->|simulates| EN
    SDK -->|builds proofs| RC
    SDK -->|calls| SC
    IT -->|tests full flow| HN
    IT -->|uses| SC
    IT -->|uses| DES
    LAB -->|analyzes| TD

    %% Click Events
    click SC "https://github.com/riftresearch/protocol/tree/main/contracts/"
    click BLCC "https://github.com/riftresearch/protocol/tree/main/crates/bitcoin-light-client-core/"
    click RC "https://github.com/riftresearch/protocol/tree/main/crates/rift-core/"
    click HN "https://github.com/riftresearch/protocol/tree/main/bin/hypernode/"
    click DES "https://github.com/riftresearch/protocol/tree/main/bin/data-engine-server/"
    click MM "https://github.com/riftresearch/protocol/tree/main/bin/market-maker/"
    click CD "https://github.com/riftresearch/protocol/tree/main/bin/checkpoint-downloader/"
    click BM "https://github.com/riftresearch/protocol/tree/main/bin/benchmark-light-client/"
    click DN "https://github.com/riftresearch/protocol/tree/main/bin/devnet/"
    click SDK "https://github.com/riftresearch/protocol/tree/main/crates/rift-sdk/"
    click SB "https://github.com/riftresearch/protocol/tree/main/crates/sol-bindings/"
    click BCRS "https://github.com/riftresearch/protocol/tree/main/crates/bitcoin-core-rs/"
    click BDE "https://github.com/riftresearch/protocol/tree/main/crates/bitcoin-data-engine/"
    click DE "https://github.com/riftresearch/protocol/tree/main/crates/data-engine/"
    click SU "https://github.com/riftresearch/protocol/tree/main/bin/sol-utils/"
    click IT "https://github.com/riftresearch/protocol/tree/main/integration-tests/"
    click LAB "https://github.com/riftresearch/protocol/tree/main/lab/"
    click TD "https://github.com/riftresearch/protocol/tree/main/test-data/"

    %% Styles
    classDef blockchain fill:#AEDFF7,stroke:#0366d6,color:#000
    classDef service fill:#DFF7DF,stroke:#228B22,color:#000
    classDef crate fill:#F7F4DF,stroke:#DAA520,color:#000
    classDef contract fill:#F7DFDF,stroke:#d62728,color:#000
    classDef db fill:#DFE3F7,stroke:#551A8B,color:#000
    classDef sdk fill:#E8DFF7,stroke:#800080,color:#000
    classDef test fill:#F0F0F0,stroke:#888,color:#000
```
