# regolith-labs/drillx architecture

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

- Interactive diagram: https://gitdiagram.com/regolith-labs/drillx
- Repository: https://github.com/regolith-labs/drillx

## Overview

##### Project Type & Purpose
- This is a Rust-based proof-of-work algorithm library tailored for smart contract based cryptocurrency mining.
- Its purpose is to compute a proof-of-work using a modified Equihash algorithm (Equix plus an additional Keccak step) to generate and verify mining solutions, particularly for on-chain validation (e.g., on Solana).

##### Analyzing the File Structure
- Top-level Files:
– Cargo.lock, Cargo.toml, and README.md, which indicate that this is a Rust project.
– rust-toolchain.toml suggests that the Rust version is explicitly managed.
- Main Directories:
– drillx: This directory contains the core library (drillx/src/lib.rs) along with benchmarks (drillx/benches). It represents the heart of the proof-of-work algorithm implementation.
– program: Contains another Cargo project that seems to serve as a companion crate (or smart contract integration) where the library is utilized. It has its own lib.rs and test suite, likely used to validate the core algorithm in a program context.
– examples: Three separate example projects (example-1, example-2, example-3) that provide usage demonstrations of the library for miners and possibly integration scenarios.
- These components suggest a modular design with a clear separation between the core algorithm (library) and its application/integration contexts (program and example clients).

##### Key Components to Highlight
- Core Proof-of-Work Library (drillx):
– Includes modules such as the Equix solver, SolverMemory management, and hashing routines including Keccak.
– This is the computational engine and will be the central component.
- Smart Contract/Integration Module (program):
– Likely used to integrate and test on-chain verification of mining solutions.
– Contains tests which verify that the library’s proof-of-work outputs are valid.
- Example Clients (examples):
– Demonstrate how miners iterate through nonces and compute the hash to meet target difficulties.
– Serve as user interfaces or sample applications showing how developers might utilize the algorithm for mining operations.
- External Dependencies and Ecosystem Integration:
– Reference to Solana (via the README discussion on Keccak as a syscall and smart contract integration).
– The overall setup indicates that the design supports deployment within a blockchain environment, specifically for securing smart contract operations.

##### Relationships & Interactions
- The core library (drillx) is used by both the program module (for integration and testing with smart contracts) and by the examples (demonstrative miners).
- Miners use functions such as hash_with_memory and the SolverMemory utility from the core library for computing potential solutions.
- Smart contracts or blockchain programs then verify the solutions provided by the miners using the verification routines in the library.
- Directional dependencies should be shown from the external applications (miners and blockchain integration) feeding inputs (e.g., challenges and nonce iterations) into the core proof-of-work engine and receiving outputs (proof and difficulty measures).

##### Important Architectural Patterns & Design Principles
- Modular Design: The separation of the core algorithm (library) from integration tests and example applications.
- Reuse & Extensibility: The design encourages separate demonstration projects, while the core algorithm can be independently verified and used in multiple contexts.
- Clean API Boundaries: The library offers clear abstractions (SolverMemory, hash_with_memory, Solution types) to interact with the complex proof-of-work logic.
- Testing & Benchmarking: Incorporating benchmarks (drillx/benches) and tests (program/tests) ensures performance and correctness are kept central to the design.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Library Subgraph
    subgraph "Drillx Core Library"
        DCL["Drillx Core Library\n(Proof-of-Work Engine)"]:::library
        EQ["Equix Algorithm"]:::library
        KC["Keccak Hashing"]:::library
        SM["SolverMemory"]:::library
        BENCH["Benchmarks"]:::library
        DCL --> EQ
        DCL --> KC
        DCL --> SM
        DCL --> BENCH
    end

    %% Smart Contract / Integration Subgraph
    subgraph "Smart Contract / Integration"
        PROG["Program / Smart Contract Integration"]:::integration
        TESTS["Integration Tests"]:::integration
        PROG --> TESTS
    end

    %% Examples Subgraph
    subgraph "Examples / Client Applications"
        EX1["Example-1 Client"]:::example
        EX2["Example-2 Client"]:::example
        EX3["Example-3 Client"]:::example
    end

    %% External Integration
    BLOCKCHAIN["Blockchain (Solana)"]:::external

    %% Relationships
    EX1 -->|"uses"| DCL
    EX2 -->|"uses"| DCL
    EX3 -->|"uses"| DCL
    PROG -->|"validates"| DCL
    DCL -->|"providesProof"| BLOCKCHAIN
    PROG -->|"communicatesWith"| BLOCKCHAIN

    %% Click Events
    click DCL "https://github.com/regolith-labs/drillx/blob/master/drillx/src/lib.rs"
    click BENCH "https://github.com/regolith-labs/drillx/tree/master/drillx/benches/"
    click PROG "https://github.com/regolith-labs/drillx/blob/master/program/src/lib.rs"
    click TESTS "https://github.com/regolith-labs/drillx/blob/master/program/tests/test.rs"
    click EX1 "https://github.com/regolith-labs/drillx/blob/master/examples/example-1/src/main.rs"
    click EX2 "https://github.com/regolith-labs/drillx/blob/master/examples/example-2/src/main.rs"
    click EX3 "https://github.com/regolith-labs/drillx/blob/master/examples/example-3/src/main.rs"

    %% Styles
    classDef library fill:#a2d9ce,stroke:#1abc9c,stroke-width:2px;
    classDef integration fill:#aed6f1,stroke:#3498db,stroke-width:2px;
    classDef example fill:#f9e79f,stroke:#f1c40f,stroke-width:2px;
    classDef external fill:#d2b4de,stroke:#8e44ad,stroke-width:2px;
```
