# sorellalabs/angstrom architecture

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

- Interactive diagram: https://gitdiagram.com/sorellalabs/angstrom
- Repository: https://github.com/sorellalabs/angstrom

## Overview

Based on our analysis of the complete file tree and the minimal README, it appears that “Angstrom” is a multifaceted, Rust-based project that comprises many interconnected components. The project consists of several executable binaries (located under the bin folder), a rich set of Rust crates (found under the crates directory) that cover domains such as networking (angstrom-net), consensus, Ethereum interactions (eth), order matching and order pool management, RPC APIs, metrics export, and comprehensive types and utilities. In addition, there is a dedicated contracts directory housing Solidity (and possibly Huff) smart contracts with associated documentation, tests, and deployment scripts, as well as testing tools with simulation agents and network mocks. This indicates that the project is likely a full-stack decentralized system or blockchain-related node that includes both onchain smart contract logic and offchain network services.

##### Main Components
- Frontend/CLI & Command-Line Tools: Modules in bin/ (e.g., bin/angstrom, bin/testnet, bin/contract_test) which likely serve as different executables or client interfaces.
- Core Network & P2P Layer: The angstrom-net crate in crates/angstrom-net, which contains builders, session management, peer handlers, and reputation systems.
- Consensus Module: Under crates/consensus that handles leader selection, various rounds (bid aggregation, finalization, proposal, preproposal, etc.)—this is central to ensuring agreement among nodes.
- Matching Engine & Order Management: Found in crates/matching-engine (order matching, simulation, strategy) and crates/order-pool (order storage, validations, pending/parked order management).
- RPC API Layer: In crates/rpc which exposes APIs for quoting, orders, and subscriptions. This layer ties external communication to internal services.
- Blockchain/Ethereum-related Interfaces: The eth crate under crates/eth for handling Ethereum-specific operations.
- Smart Contracts and Deployment: The contracts directory (with subdirectories for docs, tests, deployment scripts, and multiple contract libraries such as solady, solmate, OpenZeppelin) that handle onchain logic.
- Metrics and Monitoring: The crates/metrics providing insights on consensus, order pools, and general system metrics.
- Shared Data Models and Types: Provided by crates/types which define common types, contract payloads, matching primitives, and contract bindings that are used across the project.
- Testing and Simulation Tools: The testing-tools directory that includes agents, mocks, network simulations, and type generators to validate various aspects of the system.
- Utilities and Helpers: Crates like utils and validation provide essential support functions across the modules.

##### Relationships and Interactions
- How the CLI tools (bin/ directories) invoke the functionalities provided by various internal crates.
- That the network layer (angstrom-net) is responsible for managing P2P sessions and interacts with both the consensus layer and the RPC layer.
- Consensus module with the matching engine/order pool components indicating that consensus rounds (proposal, aggregation, etc.) determine the system state applied to orders.
- Link the Ethereum integration (eth crate) and contracts modules to show that smart contracts are built, deployed, and interacted with through the decentralized node.
- Metrics and logging components at points where key events occur across consensus, matching, and network interactions.
- Testing and simulation flows that feed into various components (order generation, network mocks, etc.) to validate system behavior.

##### Architectural Patterns and Design Principles
- Separation of concerns: Different layers (CLI, network, consensus, business logic, contracts, and testing) maintain distinct responsibilities.
- Incorporate extensibility: The contracts and testing-tool directories suggest that the system is designed to allow easy integration of new modules or updates (e.g., extensible consensus rounds, various matching strategies, etc.).
- Usage of both synchronous and asynchronous patterns, likely within the P2P networking and RPC layers.

##### Relevant Technologies and Frameworks
- Rust (with Cargo as the build system)
- Smart contract frameworks and libraries (e.g., Foundry, solmate, solady, OpenZeppelin)
- Testing frameworks for Rust and Solidity
- Possibly a microservices-like or layered architecture for separating networking, consensus, and business logic (despite being in a monorepo, the physical separation into crates encourages logical separation)

## Diagram (Mermaid)

```mermaid
graph TD
    %% CLI Tools Subgraph
    subgraph "CLI Tools"
        CLI_A["Angstrom CLI"]:::cli
        CLI_T["Testnet CLI"]:::cli
        CLI_C["Contract Test CLI"]:::cli
    end

    %% Core Modules Subgraph
    subgraph "Core Modules"
        NET["Networking (angstrom-net)"]:::network
        CONS["Consensus Module"]:::consensus
        MATCH["Matching Engine"]:::matching
        ORDER["Order Pool"]:::order
        RPC["RPC API Layer"]:::rpc
        ETH["Ethereum Interface"]:::eth
        SC["Smart Contracts & Deployment"]:::contracts
        MET["Metrics & Monitoring"]:::metrics
        TYPES["Shared Data Models"]:::types
    end

    %% Utilities & Helpers Subgraph
    subgraph "Utilities & Helpers"
        UTILS["Utilities (utils)"]:::utils
        VALID["Validation (validation)"]:::utils
    end

    %% Testing Tools Subgraph
    subgraph "Testing Tools"
        TEST["Testing & Simulation Tools"]:::testing
    end

    %% Relationships from CLI Tools
    CLI_A -->|"invokes"| RPC
    CLI_T -->|"invokes"| RPC
    CLI_C -->|"invokes"| RPC

    %% RPC interactions
    RPC -->|"requests"| NET
    RPC -->|"forMatching"| MATCH
    RPC -->|"forContracts"| SC

    %% Networking and Consensus Flow
    NET -->|"managesP2P"| CONS
    CONS -->|"updates"| MATCH
    CONS -->|"updates"| ORDER

    %% Ethereum and Contracts
    ETH -->|"triggers"| SC

    %% Testing Tools interactions
    TEST -->|"simulates"| NET
    TEST -->|"simulates"| CONS
    TEST -->|"simulates"| MATCH
    TEST -->|"simulates"| ORDER

    %% Metrics Collection
    CONS -->|"reports"| MET
    MATCH -->|"reports"| MET
    NET -->|"reports"| MET

    %% Utilities support (dotted links)
    UTILS -.->|"supports"| CONS
    UTILS -.->|"supports"| MATCH
    UTILS -.->|"supports"| ORDER
    UTILS -.->|"supports"| RPC
    UTILS -.->|"supports"| NET

    VALID -.->|"validates"| CONS
    VALID -.->|"validates"| MATCH
    VALID -.->|"validates"| ORDER
    VALID -.->|"validates"| RPC
    VALID -.->|"validates"| NET

    %% Shared Types usage
    TYPES -.->|"provides"| CONS
    TYPES -.->|"provides"| MATCH
    TYPES -.->|"provides"| ORDER
    TYPES -.->|"provides"| RPC
    TYPES -.->|"provides"| NET
    TYPES -.->|"provides"| ETH
    TYPES -.->|"provides"| SC

    %% Click Events
    click CLI_A "https://github.com/sorellalabs/angstrom/tree/main/bin/angstrom"
    click CLI_T "https://github.com/sorellalabs/angstrom/tree/main/bin/testnet"
    click CLI_C "https://github.com/sorellalabs/angstrom/tree/main/bin/contract_test"
    click NET "https://github.com/sorellalabs/angstrom/tree/main/crates/angstrom-net"
    click CONS "https://github.com/sorellalabs/angstrom/tree/main/crates/consensus"
    click MATCH "https://github.com/sorellalabs/angstrom/tree/main/crates/matching-engine"
    click ORDER "https://github.com/sorellalabs/angstrom/tree/main/crates/order-pool"
    click RPC "https://github.com/sorellalabs/angstrom/tree/main/crates/rpc"
    click ETH "https://github.com/sorellalabs/angstrom/tree/main/crates/eth"
    click SC "https://github.com/sorellalabs/angstrom/tree/main/contracts"
    click MET "https://github.com/sorellalabs/angstrom/tree/main/crates/metrics"
    click TYPES "https://github.com/sorellalabs/angstrom/tree/main/crates/types"
    click TEST "https://github.com/sorellalabs/angstrom/tree/main/testing-tools"
    click UTILS "https://github.com/sorellalabs/angstrom/tree/main/crates/utils"
    click VALID "https://github.com/sorellalabs/angstrom/tree/main/crates/validation"

    %% Styles
    classDef cli fill:#ffcc00,stroke:#333,stroke-width:2px;
    classDef network fill:#bde0fe,stroke:#333,stroke-width:2px;
    classDef consensus fill:#ffd6a5,stroke:#333,stroke-width:2px;
    classDef matching fill:#caffbf,stroke:#333,stroke-width:2px;
    classDef order fill:#9bf6ff,stroke:#333,stroke-width:2px;
    classDef rpc fill:#ffc6ff,stroke:#333,stroke-width:2px;
    classDef eth fill:#ffeead,stroke:#333,stroke-width:2px;
    classDef contracts fill:#cdb4db,stroke:#333,stroke-width:2px;
    classDef metrics fill:#ffadad,stroke:#333,stroke-width:2px;
    classDef types fill:#ffd6a5,stroke:#333,stroke-width:2px;
    classDef utils fill:#d0f4de,stroke:#333,stroke-width:2px;
    classDef testing fill:#d3f8e2,stroke:#333,stroke-width:2px;
```
