# regolith-labs/ore architecture

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

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

## Overview

##### Main Components
- API Layer (located in the “api” directory):
- Contains modules such as consts, error, event, instruction, and a “state” sub-folder.
- Exposes model definitions and helpers (e.g., SDK to interact with the on-chain program) as well as state management.
- On-chain Program (located in the “program” directory):
- Implements individual instruction handlers that represent distinct operations (Claim, Close, Open, Mine, Reset, Update, and Initialize).
- State Accounts (in “api/src/state”):
- Bus: Tracks and limits the amount of mined ORE per epoch.
- Config: Singleton managing program-wide settings.
- Proof: Per-miner account tracking the hash and stake.
- Treasury: Singleton for minting ORE and holding user stakes.
- Security Audits:
- Though separate, the provided PDF audit documents serve as additional reference points for security considerations in your architecture.
- Testing & Deployment Tools:
- The project includes Cargo and toolchain configs for building and testing with Solana.

##### Understand the Relationships and Interactions
- The API layer acts as an interface or façade through which external clients can interact with the blockchain program. It encapsulates the program-level instructions and provides support functionality (constants, errors, events).
- The Program instructions (each in their separate module) are the actual on-chain handlers that execute core functions. They modify or read the state accounts.
- Each instruction has a clearly defined role (for example, “Mine” verifies a hash then increments a miner’s balance, whereas “Initialize” sets up global accounts). The interactions between these instructions and the state accounts need to be depicted.

##### Architectural Patterns & Design Principles
- The state account model is clearly central to the system – representing persistent blockchain data such as miner proofs and treasury balances.
- A modular design is used, with each instruction encapsulated in its own module.
- There is an emphasis on clarity and traceability of operations (e.g., from initializing the program to updating state).

○ A group labeled “State Accounts” containing Bus, Config, Proof, Treasury.
○ Illustrate data flow from the API layer to each Program instruction, indicating that external inputs (or client interactions via the SDK/API) trigger these instructions.
- Optionally, you could also include blocks for testing (e.g., “cargo test-sbf” process) and note security audits as external document review/validation points.

##### Final Checklist
- Clear and descriptive labels for each component (e.g., “API – SDK & Helper Functions”, “Program – Claim Instruction”, “State – Bus Account”).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Entities
    EC("External Client"):::external
    TD("Cargo & Solana Toolchain"):::tools
    SA("Security Audits Documentation"):::external

    %% API Layer Subgraph
    subgraph "API Layer"
        A1("Constants Module"):::api
        A2("Error Handling Module"):::api
        A3("Event Definitions Module"):::api
        A4("Instruction Definitions (SDK/API Interface)"):::api
        A5("SDK & Helpers"):::api
        A6("State Management"):::api
    end

    %% Program Instructions Subgraph
    subgraph "Program Instructions"
        P1("Claim Instruction"):::inst
        P2("Close Instruction"):::inst
        P3("Initialize Instruction"):::inst
        P4("Mine Instruction"):::inst
        P5("Open Instruction"):::inst
        P6("Reset Instruction"):::inst
        P7("Update Instruction"):::inst
    end

    %% State Accounts Subgraph
    subgraph "State Accounts"
        S1("Bus Account"):::state
        S2("Config Account"):::state
        S3("Proof Account"):::state
        S4("Treasury Account"):::state
    end

    %% Connections from External Client to API Layer
    EC -->|"calls"| A4
    EC -->|"uses"| A5

    %% Connections from API Layer to Program Instructions
    A4 -->|"triggers"| P1
    A4 -->|"triggers"| P2
    A4 -->|"triggers"| P3
    A4 -->|"triggers"| P4
    A4 -->|"triggers"| P5
    A4 -->|"triggers"| P6
    A4 -->|"triggers"| P7

    %% Connections from Program Instructions to State Accounts
    P3 -->|"init_config"| S2
    P3 -->|"init_treasury"| S4
    P4 -->|"update_bus"| S1
    P4 -->|"update_proof"| S3
    P1 -->|"claim"| S3
    P5 -->|"open_account"| S3
    P2 -->|"close_account"| S3
    P6 -->|"reset_bus"| S1
    P7 -->|"update_treasury"| S4

    %% Connections from Testing & Deployment Tools
    TD ---|"builds"| A1
    TD ---|"builds"| P3

    %% Connections from Security Audits to overall system (informational)
    SA ---|"reviews"| A4
    SA ---|"reviews"| P4

    %% Click Events for API Layer
    click A1 "https://github.com/regolith-labs/ore/blob/master/api/src/consts.rs"
    click A2 "https://github.com/regolith-labs/ore/blob/master/api/src/error.rs"
    click A3 "https://github.com/regolith-labs/ore/blob/master/api/src/event.rs"
    click A4 "https://github.com/regolith-labs/ore/blob/master/api/src/instruction.rs"
    click A5 "https://github.com/regolith-labs/ore/blob/master/api/src/sdk.rs"
    click A6 "https://github.com/regolith-labs/ore/blob/master/api/src/state/mod.rs"

    %% Click Events for State Accounts (API Side)
    click S1 "https://github.com/regolith-labs/ore/blob/master/api/src/state/bus.rs"
    click S2 "https://github.com/regolith-labs/ore/blob/master/api/src/state/config.rs"
    click S3 "https://github.com/regolith-labs/ore/blob/master/api/src/state/proof.rs"
    click S4 "https://github.com/regolith-labs/ore/blob/master/api/src/state/treasury.rs"

    %% Click Events for On-chain Program Instructions
    click P1 "https://github.com/regolith-labs/ore/blob/master/program/src/claim.rs"
    click P2 "https://github.com/regolith-labs/ore/blob/master/program/src/close.rs"
    click P3 "https://github.com/regolith-labs/ore/blob/master/program/src/initialize.rs"
    click P4 "https://github.com/regolith-labs/ore/blob/master/program/src/mine.rs"
    click P5 "https://github.com/regolith-labs/ore/blob/master/program/src/open.rs"
    click P6 "https://github.com/regolith-labs/ore/blob/master/program/src/reset.rs"
    click P7 "https://github.com/regolith-labs/ore/blob/master/program/src/update.rs"

    %% Click Event for Security Audits Documentation
    click SA "https://github.com/regolith-labs/ore/tree/master/security/"

    %% Styling Classes
    classDef api fill:#AED6F1,stroke:#333,stroke-width:2px;
    classDef inst fill:#F9E79F,stroke:#333,stroke-width:2px;
    classDef state fill:#A9DFBF,stroke:#333,stroke-width:2px;
    classDef tools fill:#D7BDE2,stroke:#333,stroke-width:2px;
    classDef external fill:#F5B7B1,stroke:#333,stroke-width:2px;
```
