# 0glabs/0g-storage-contracts architecture

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

- Interactive diagram: https://gitdiagram.com/0glabs/0g-storage-contracts
- Repository: https://github.com/0glabs/0g-storage-contracts

## Overview

##### Main Components
- Contracts Modules:
- Flow: Manages user data submissions and maintains the Merkle root of stored data.
- Market: Validates fee payment upon data submissions and supports different implementations (e.g., Cashier, FixedPrice).
- Reward: Distributes rewards based on the mining task results using various models (ChunkDecayReward, ChunkLinearReward, OnePoolReward).
- Miner: The component that validates mining submissions and requests corresponding rewards.
- Deployment and Upgrade Infrastructure:
- Deployment Scripts: Located in the src/deploy folder (deploy_blake2b_test.ts, deploy_fixed_price_flow.ts, etc.) used to deploy various contract configurations.
- Upgrade Tasks: Found under src/tasks/upgrade.ts and related tasks that manage upgrades following a detailed process (forceImportAll, upgrade:validate etc.).
- Network Configuration:
- Custom network configurations in src/networks (for example, zerog_contract_config.ts, zerog_testnet_contract_config_standard.ts) allowing for tailored deployments on local test networks or networks like Zero Gravity.

##### Relationships and Interactions
- Reward Distribution: After data submission is verified and the mining task is completed, Flow communicates with the Reward module to trigger reward calculations and releases.
- Contract Upgrades: Highlight the upgrade path via Hardhat tasks. Show how after initial deployments, artifacts are verified (via upgrade:validate) then upgraded, with deployments being stored and updated in the deployments folder.
- Deployment Options: Clearly demarcate between “market-enabled” and “non-market” deployments and illustrate how the different deployment scripts (FixedPrice, OnePoolReward, no-market, etc.) tie into that workflow.

##### Architectural Patterns & Design Principles
- Separation of Concerns: Differentiate between contract business logic, deployment scripts (in src/deploy), network configuration (in src/networks), and maintenance/upgrades (in src/tasks).
- Extensibility and Configuration: Emphasize that new networks can be added easily using the configuration files in the networks folder and that multiple economic models can be swapped in/out.

##### Relevant Technologies and Frameworks
- Hardhat Framework: Illustrate that the system is built and deployed using Hardhat (as evidenced by hardhat.config.ts) with specific tasks for deployment and upgrades.
- Testing Framework: Include Mocha configuration (.mocharc.json) showing that testing is robustly covered.
- Code Quality Tools: Mention ESLint (.eslintrc.js) and Prettier (.prettierrc) that enforce coding standards.
- Patch Files: Note the presence of patches that apply to third-party libraries (e.g., waffle-mock-contract) for enhanced functionality or bug fixes.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Entity
    USER("User"):::external

    %% Contracts Modules Subgraph
    subgraph "Contracts Modules"
        FLOW("Flow Module"):::contractModule
        MARKET("Market Module"):::contractModule
        REWARD("Reward Module"):::contractModule
        MINER("Miner Module"):::contractModule
    end

    %% Deployment & Upgrade Infrastructure Subgraph
    subgraph "Deployment & Upgrade Infrastructure"
        DEPLOY("Deployment Scripts"):::infra
        UPGRADE("Upgrade Tasks"):::infra
        NET("Network Configuration"):::infra
    end

    %% Support & QA Subgraph
    subgraph "Support & QA"
        TEST("Testing & Config"):::support
        CODE("Code Quality Tools"):::support
    end

    %% Relationships: User submitting data initiates process through Flow
    USER -->|"submits_data"| FLOW

    %% Flow interactions: calls Market for fee validation, calls Reward for distribution
    FLOW -->|"validates_fee"| MARKET
    FLOW -->|"triggers_reward"| REWARD

    %% Miner validates mining submissions and requests Reward
    MINER -->|"requests_reward"| REWARD

    %% Deployment Scripts deploys contract modules
    DEPLOY -->|"deploys"| FLOW
    DEPLOY -->|"deploys"| MARKET
    DEPLOY -->|"deploys"| REWARD
    DEPLOY -->|"deploys"| MINER

    %% Upgrade Tasks manage deployments/upgrades
    UPGRADE -->|"upgrades"| DEPLOY

    %% Network Configuration supplies deployment settings
    NET -->|"configures"| DEPLOY

    %% Testing & Config tests contract modules and deployment
    TEST -->|"tests"| FLOW
    TEST -->|"tests"| MARKET
    TEST -->|"tests"| REWARD
    TEST -->|"tests"| MINER
    TEST -->|"validates"| DEPLOY

    %% Code Quality Tools support testing and overall project quality
    CODE -->|"enforces_rules"| TEST

    %% Click Events for Flow Module
    click FLOW "https://github.com/0glabs/0g-storage-contracts/tree/main/contracts/dataFlow"
    click FLOW "https://github.com/0glabs/0g-storage-contracts/blob/main/src/deploy/deploy_flow.ts"
    click FLOW "https://github.com/0glabs/0g-storage-contracts/blob/main/src/tasks/flow.ts"

    %% Click Events for Market Module
    click MARKET "https://github.com/0glabs/0g-storage-contracts/tree/main/contracts/market"
    click MARKET "https://github.com/0glabs/0g-storage-contracts/tree/main/contracts/cashier"
    click MARKET "https://github.com/0glabs/0g-storage-contracts/tree/main/contracts/uploadMarket"
    click MARKET "https://github.com/0glabs/0g-storage-contracts/blob/main/src/deploy/deploy_fixed_price_market.ts"

    %% Click Events for Reward Module
    click REWARD "https://github.com/0glabs/0g-storage-contracts/tree/main/contracts/reward"
    click REWARD "https://github.com/0glabs/0g-storage-contracts/blob/main/src/deploy/deploy_chunk_linear_reward.ts"
    click REWARD "https://github.com/0glabs/0g-storage-contracts/blob/main/src/deploy/deploy_one_pool_reward.ts"
    click REWARD "https://github.com/0glabs/0g-storage-contracts/blob/main/src/tasks/reward.ts"

    %% Click Events for Miner Module
    click MINER "https://github.com/0glabs/0g-storage-contracts/tree/main/contracts/miner"
    click MINER "https://github.com/0glabs/0g-storage-contracts/blob/main/src/deploy/deploy_pora_mine.ts"
    click MINER "https://github.com/0glabs/0g-storage-contracts/blob/main/src/tasks/mine.ts"

    %% Click Event for Deployment Scripts
    click DEPLOY "https://github.com/0glabs/0g-storage-contracts/tree/main/src/deploy"

    %% Click Event for Upgrade Tasks
    click UPGRADE "https://github.com/0glabs/0g-storage-contracts/blob/main/src/tasks/upgrade.ts"

    %% Click Event for Network Configuration
    click NET "https://github.com/0glabs/0g-storage-contracts/tree/main/src/networks"

    %% Click Events for Testing Framework
    click TEST "https://github.com/0glabs/0g-storage-contracts/tree/main/test"
    click TEST "https://github.com/0glabs/0g-storage-contracts/blob/main/.mocharc.json"

    %% Click Events for Code Quality Tools
    click CODE "https://github.com/0glabs/0g-storage-contracts/blob/main/.eslintrc.js"
    click CODE "https://github.com/0glabs/0g-storage-contracts/blob/main/.prettierrc"
    click CODE "https://github.com/0glabs/0g-storage-contracts/blob/main/patches/@clrfund+waffle-mock-contract+0.0.11.patch"

    %% Styles
    classDef contractModule fill:#a8df65,stroke:#333,stroke-width:2px;
    classDef infra fill:#8ecae6,stroke:#333,stroke-width:2px;
    classDef support fill:#f4a261,stroke:#333,stroke-width:2px;
    classDef external fill:#ffd166,stroke:#333,stroke-width:2px;
```
