# iexecblockchaincomputing/poco architecture

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

- Interactive diagram: https://gitdiagram.com/iexecblockchaincomputing/poco
- Repository: https://github.com/iexecblockchaincomputing/poco

## Overview

##### Project type and purpose
- This is an on-chain protocol implementation: the iExec “Proof-of-Contribution” (PoCo) smart‐contract system, written in Solidity, packaged with Hardhat/Truffle migrations, TypeScript/JavaScript deploy & test scripts, UML docs, and off‐chain tooling.
- Its goal is to manage task orders, worker staking, revealiation, and governance via a modular, upgradeable smart-contract architecture (ERC1538 modules + proxy + create2 factory).

##### File structure
- Top‐level dirs:
- contracts/             ← Solidity sources, organized into external interfaces, libs, modules (core PoCo logic), registries (apps, datasets, workerpools), testing tools
- build/ & build/contracts-min/ ← compiled artifacts + ABIs
- deploy/ + migrations/ ← Hardhat & Truffle deployment scripts (TypeScript & JS)
- scripts/               ← specialized tasks: module boost, ENS, factory upgrades, timelock
- test/                  ← comprehensive test suite (JS/TS) covering flows, edge cases, back-to-back FullChain scenarios
- config/                ← per-chain configuration for native vs ERC20 escrow, factory salt, v3/v5 bridging
- Key config: hardhat.config.ts, .mocharc.json, slither.config.json

##### README for additional insights
- The README describes:
- Modular ERC1538 design (contracts split into delegates/modules behind proxy)
- create2-based factory for deterministic deployments
- Dual escrow support (native vs ERC20)
- Multi-chain support (config/config*.json)
- Provided UMLs for: high-level actor/contract architecture, sequence workflows (nominal/boost/TEE), storage layouts
- It points to comprehensive PoCo docs, solidity API docs, and UML artifacts in docs/uml.

a. Main components to show
- Off-chain environment: Hardhat/Truffle CLI, deploy & test scripts, config files, UML/tooling
- Ethereum network (public or sidechain)
- Factory contract (GenericFactory) + create2 salt → Proxy instances
- Proxy (ERC1538 upgradeable)
- Delegate modules (IexecPoco1, IexecPoco2, IexecEscrowNative/Token, IexecCategoryManager, IexecOrderManagement, IexecRelay, etc.)
- Registries: AppRegistry, DatasetRegistry, WorkerpoolRegistry
- Libraries: IexecLibCore, IexecLibOrders, SafeMath, EnumerableMap/Set
- Token contract (RLC) or native token handling
- External services: ENSIntegration, IOracle (oracle consumer)
- Off-chain data flows: test harness, score transfer v3→v5 bridge
b. Relationships & interactions
- Scripts read config → call factory.deploy() → deploy Proxy + modules
- Proxy forwards calls to modules via delegatecall (ERC1538)
- Modules invoke libraries for core logic (staking, task matching, payout)
- Registries store metadata (apps, datasets, workerpools)
- Escrow modules lock/unlock tokens/native based on PoCo events
- Oracles feed external data into contracts
- ENSIntegration modules resolve names during deployment or naming flows
c. Architectural patterns & design principles
- Modular proxy upgradeability (ERC1538): each module adds/removes functions at runtime
- Deterministic deployment (create2 factory) for multi-chain consistency
- Separation of concerns: registries vs business logic vs payment (escrow) vs metadata
- Extensibility: new modules can be added via factory or governance
d. Key technologies
- Solidity + Hardhat + Truffle migrations
- TypeScript/JavaScript deploy & test scripts
- create2 GenericFactory, ERC1538 upgrade proxy
- JSON artifacts for ABI/bytecode

##### Detail
- Contract family (core PoCo, boost, maintenance, relay) as separate modules
- NIexecLibOrders & NIexecLibCore libraries that underpin business logic
- Dual‐mode escrow path (ERC20 vs native) branching from PoCo modules
- Inter-module dependencies (e.g., OrderManagement calls CategoryManager & Poc oDelegate)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Off-chain Tooling & Deployment
    subgraph "Off-chain Tooling & Deployment"
        Hardhat["Hardhat CLI & Config"]:::offchain
        Truffle["Truffle Migrations & JS/TS"]:::offchain
        Config["Chain Config Files"]:::offchain
        Test["Test Suite"]:::offchain
        UML["PlantUML Docs"]:::offchain
        Tools["Diagram & UML Tools"]:::offchain
    end

    %% Ethereum Network Boundary
    subgraph "Ethereum Network"  
        direction TB
        User["User/EOA"]:::external
        Factory["GenericFactory (create2 factory)"]:::factory
        Proxy["ERC1538Proxy"]:::proxy

        subgraph "ERC1538 Interfaces"
            Store["ERC1538Store"]:::proxy
            Query["ERC1538QueryDelegate"]:::proxy
            Update["ERC1538UpdateDelegate"]:::proxy
        end

        subgraph "Modules (delegatecalls)"
            direction TB
            Poco1["IexecPoco1Delegate"]:::core
            Poco2["IexecPoco2Delegate"]:::core
            Boost["IexecPocoBoostDelegate"]:::core
            Relay["IexecRelayDelegate"]:::core
            OrderMgmt["IexecOrderManagementDelegate"]:::core
            Category["IexecCategoryManagerDelegate"]:::core
            EscrowNative["IexecEscrowNativeDelegate"]:::escrow
            EscrowToken["IexecEscrowTokenDelegate"]:::escrow
            EscrowSwap["IexecEscrowTokenSwapDelegate"]:::escrow
            ENSInt["ENSIntegrationDelegate"]:::core
        end

        subgraph "Registries & Libraries"
            direction TB
            AppReg["AppRegistry"]:::storage
            DataReg["DatasetRegistry"]:::storage
            WorkerReg["WorkerpoolRegistry"]:::storage
            LibCore["IexecLibCore_v5"]:::storage
            LibOrders["IexecLibOrders_v5"]:::storage
            SafeMath["SafeMath"]:::storage
            EMap["EnumerableMap"]:::storage
            ESet["EnumerableSet"]:::storage
            RLC["RLC Token"]:::storage
            AccessCtrl["AccessControl/Ownable"]:::storage
        end

        subgraph "External Services"
            Oracle["IOracle / IOracleConsumer"]:::external
            ENSsvc["ENS Service"]:::external
        end
    end

    %% Off-chain to On-chain flows
    Hardhat -->|"deploy()"| Factory
    Truffle -->|"migrate()"| Factory
    Config --> Factory
    Test --> Hardhat
    UML --> Tools

    %% On-chain deployment & interactions
    Factory --> Proxy
    Proxy --> Store
    Proxy --> Query
    Proxy --> Update
    Proxy --> Poco1
    Proxy --> Poco2
    Proxy --> Boost
    Proxy --> Relay
    Proxy --> OrderMgmt
    Proxy --> Category
    Proxy --> EscrowNative
    Proxy --> EscrowToken
    Proxy --> EscrowSwap
    Proxy --> ENSInt

    User --> Proxy
    Oracle --> ENSInt
    ENSsvc --> ENSInt

    %% Module dependencies
    Poco1 -->|uses| LibCore
    Poco2 -->|uses| LibCore
    Poco2 -->|uses| LibOrders
    OrderMgmt -->|uses| Category
    EscrowNative -->|locks/unlocks| RLC
    EscrowToken -->|locks/unlocks| RLC
    EscrowSwap -->|assists swap| EscrowToken
    Proxy --> AppReg
    Proxy --> DataReg
    Proxy --> WorkerReg

    %% Click Events
    click Factory "https://github.com/iexecblockchaincomputing/poco/blob/main/contracts/external/GenericFactory.sol"
    click Proxy "https://github.com/iexecblockchaincomputing/poco/blob/main/contracts/modules/interfaces/ERC1538Proxy.sol"
    click Store "https://github.com/iexecblockchaincomputing/poco/blob/main/contracts/modules/interfaces/ERC1538Store.sol"
    click Query "https://github.com/iexecblockchaincomputing/poco/blob/main/contracts/modules/interfaces/ERC1538QueryDelegate.sol"
    click Update "https://github.com/iexecblockchaincomputing/poco/blob/main/contracts/modules/interfaces/ERC1538UpdateDelegate.sol"
    click Poco1 "https://github.com/iexecblockchaincomputing/poco/blob/main/contracts/modules/delegates/IexecPoco1Delegate.sol"
    click Poco2 "https://github.com/iexecblockchaincomputing/poco/blob/main/contracts/modules/delegates/IexecPoco2Delegate.sol"
    click Boost "https://github.com/iexecblockchaincomputing/poco/blob/main/contracts/modules/delegates/IexecPocoBoostDelegate.sol"
    click Relay "https://github.com/iexecblockchaincomputing/poco/blob/main/contracts/modules/delegates/IexecRelayDelegate.sol"
    click EscrowNative "https://github.com/iexecblockchaincomputing/poco/blob/main/contracts/modules/delegates/IexecEscrowNativeDelegate.sol"
    click EscrowToken "https://github.com/iexecblockchaincomputing/poco/blob/main/contracts/modules/delegates/IexecEscrowTokenDelegate.sol"
    click EscrowSwap "https://github.com/iexecblockchaincomputing/poco/blob/main/contracts/modules/delegates/IexecEscrowTokenSwapDelegate.sol"
    click OrderMgmt "https://github.com/iexecblockchaincomputing/poco/blob/main/contracts/modules/delegates/IexecOrderManagementDelegate.sol"
    click Category "https://github.com/iexecblockchaincomputing/poco/blob/main/contracts/modules/delegates/IexecCategoryManagerDelegate.sol"
    click AppReg "https://github.com/iexecblockchaincomputing/poco/blob/main/contracts/registries/apps/AppRegistry.sol"
    click DataReg "https://github.com/iexecblockchaincomputing/poco/blob/main/contracts/registries/datasets/DatasetRegistry.sol"
    click WorkerReg "https://github.com/iexecblockchaincomputing/poco/blob/main/contracts/registries/workerpools/WorkerpoolRegistry.sol"
    click LibCore "https://github.com/iexecblockchaincomputing/poco/blob/main/contracts/libs/IexecLibCore_v5.sol"
    click LibOrders "https://github.com/iexecblockchaincomputing/poco/blob/main/contracts/libs/IexecLibOrders_v5.sol"
    click SafeMath "https://github.com/iexecblockchaincomputing/poco/blob/main/contracts/libs/SafeMath.sol"
    click EMap "https://github.com/iexecblockchaincomputing/poco/blob/main/contracts/libs/EnumerableMap.sol"
    click ESet "https://github.com/iexecblockchaincomputing/poco/blob/main/contracts/libs/EnumerableSet.sol"
    click Oracle "https://github.com/iexecblockchaincomputing/poco/blob/main/contracts/external/interfaces/IOracle.sol"
    click ENSsvc "https://github.com/iexecblockchaincomputing/poco/blob/main/contracts/modules/delegates/ENSIntegrationDelegate.sol"
    click RLC "https://github.com/iexecblockchaincomputing/poco/blob/main/contracts/external/RLC.sol"
    click AccessCtrl "https://github.com/iexecblockchaincomputing/poco/blob/main/contracts/external/AccessControl.sol"
    click Hardhat "https://github.com/iexecblockchaincomputing/poco/blob/main/hardhat.config.ts"
    click Truffle "https://github.com/iexecblockchaincomputing/poco/tree/main/migrations/"
    click Config "https://github.com/iexecblockchaincomputing/poco/blob/main/config/config.json"
    click Test "https://github.com/iexecblockchaincomputing/poco/tree/main/test/"
    click UML "https://github.com/iexecblockchaincomputing/poco/tree/main/docs/uml/"
    click Tools "https://github.com/iexecblockchaincomputing/poco/blob/main/tools/sol-to-uml.mjs"

    %% Styles
    classDef core fill:#BBE1FA,stroke:#000
    classDef escrow fill:#FFCC99,stroke:#000
    classDef storage fill:#B2CCB2,stroke:#000
    classDef offchain fill:#D8BFD8,stroke:#000
    classDef factory fill:#A0C4FF,stroke:#000
    classDef proxy fill:#90E0EF,stroke:#000
    classDef external fill:#E3B23C,stroke:#000
    classDef network fill:#CCCCCC,stroke:#000
```
