How sorellalabs/angstrom works
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)