# dinero-protocol/pirex-eth-contracts architecture

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

- Interactive diagram: https://gitdiagram.com/dinero-protocol/pirex-eth-contracts
- Repository: https://github.com/dinero-protocol/pirex-eth-contracts

## Overview

##### Project Type & Purpose
- This is a smart contract-based protocol written for Ethereum. The project centers around liquid staking where users deposit ETH and receive pxETH, with rewards coming from MEV and the core blockchain protocols (Execution, Consensus layers).
- The README and contracts list clearly indicate that the system is a decentralized financial product that leverages staking and autocompounding features.

##### File Structure Insights
- The top-level directories include multiple components:
– “src” contains the Solidity contracts (organized by interfaces, tokens, libraries, etc.) that implement key protocol logic.
– “lib” includes third-party contracts and libraries such as OpenZeppelin, forge-std, and solmate, which support role-based access control and ERC standards.
- The repository also includes configuration and build files (foundry.toml, package.json, remappings.txt) to support the smart contract development workflow.

##### Key Components of the System (Main Contracts)
- PirexEthValidators – Manages validator queues, deposits to the beacon chain deposit contract, and handles validator lifecycle events (e.g., slashing, topping up).
- PirexEth – Acts as the main user entry point where users deposit ETH and receive pxETH; it oversees fee management.
- AutoPxEth – An autocompounding vault for pxETH where users stake their tokens and rewards are compounded over time.
- OracleAdapter – Functions as an intermediary for off-chain notifications and state updates (e.g., validator exit notifications).
- PirexFees – Responsible for fee distribution among treasury and contributors.
- DineroERC20 & PxEth – Token contracts managing the issuance and lifecycle of the protocol’s tokens; they include extended functionality with permissioned roles like MINTER, BURNER, and OPERATOR.
- ERC1155Solmate – A modified token implementation for permissioned minting/burning actions.
- RewardRecipient – Consolidates reward harvesting operations, validator dissolution/slashing, and inter-contract synchronization when state changes occur.

##### External Components & Interactions
- Beacon Chain Deposit – The Validators contract interacts with external beacon chain deposit contracts to stake ETH into the Ethereum staking mechanism.
- User Wallets – Represent the entry/exit point for ETH deposits and pxETH redemptions.

##### Relationships & Data Flows
- How ETH (from users) flows into PirexEth, gets staked through the AutoPxEth vault, and converts into pxETH/upxETH as users redeem or compound rewards.
- Inter-contract calls between:
- PirexEth and PirexEthValidators (e.g., depositing ETH leads to the validator queue operations).
- AutoPxEth’s reward harvesting flows feeding back into the token balance (compounded rewards).
- OracleAdapter notifying PirexEth or RewardRecipient about validator exits/slashing.
- PirexFees receiving fee amounts and distributing them to treasury and governance channels.

##### Architectural Patterns & Design Principles
- Modular Contract Structure: Each component (staker vault, fees, rewards, token issuance) has its own contract to ensure separation of responsibilities.
- Upgradeability: Although not explicitly detailed, the presence of “proxy” directories and OpenZeppelin’s patterns may indicate support for upgradeable contracts.
- Interoperability: Emphasize that the system integrates with external Ethereum contracts (e.g., for deposits) and third-party libraries that manage token standards and testing frameworks.

## Diagram (Mermaid)

```mermaid
flowchart TD

    %% External Entities
    External1("User Wallet"):::external
    External2("Governance/MultiSig"):::external
    External3("Beacon Chain Deposit"):::external

    %% Subgraph for Staking and Validator Management
    subgraph "Staking & Validator Management"
        PEV("PirexEthValidators"):::contract
        OA("OracleAdapter"):::contract
    end

    %% Subgraph for Token Management
    subgraph "Token Management"
        PE("PirexEth"):::contract
        DERC("DineroERC20"):::token
        PXT("PxEth"):::token
        ERC1155("ERC1155Solmate"):::library
    end

    %% Subgraph for Reward & Fee Aggregation
    subgraph "Reward & Fee Aggregation"
        AP("AutoPxEth"):::contract
        RR("RewardRecipient"):::contract
        PF("PirexFees"):::contract
    end

    %% Relationships & Data Flows

    %% User deposits ETH into PirexEth
    External1 -->|"depositsETH"| PE

    %% PirexEth triggers deposit to validators
    PE -->|"initiatesDeposit"| PEV

    %% Validators contract interacts with Beacon Chain Deposit
    PEV -->|"stakesETH"| External3

    %% OracleAdapter notifies RewardRecipient about validator exits/slashing
    OA -->|"notifies"| RR

    %% AutoPxEth compounds rewards and feeds RewardRecipient
    AP -->|"compoundsRewards"| RR

    %% PirexEth manages token issuance
    PE -->|"mintsTokens"| DERC
    PE -->|"mintsTokens"| PXT

    %% ERC1155Solmate represents a permissioned token implementation
    %% (No direct flow but part of token management)

    %% RewardRecipient updates token balances
    RR -->|"updatesBalance"| PE

    %% Fee management flow
    PE -->|"paysFees"| PF
    PF -->|"distributesFees"| External2

    %% Governance role controlling contracts
    External2 -->|"controls"| PE
    External2 -->|"controls"| PEV
    External2 -->|"controls"| PF

    %% Styles
    classDef contract fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef token fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef external fill:#D5F5E3,stroke:#196F3D,stroke-width:2px;
    classDef library fill:#F5B7B1,stroke:#922B21,stroke-width:2px;

    %% Click Events
    click PEV "https://github.com/dinero-protocol/pirex-eth-contracts/tree/master/src/"
    click PE "https://github.com/dinero-protocol/pirex-eth-contracts/tree/master/src/"
    click AP "https://github.com/dinero-protocol/pirex-eth-contracts/tree/master/src/"
    click OA "https://github.com/dinero-protocol/pirex-eth-contracts/tree/master/src/interfaces"
    click PF "https://github.com/dinero-protocol/pirex-eth-contracts/tree/master/src/"
    click DERC "https://github.com/dinero-protocol/pirex-eth-contracts/tree/master/src/tokens"
    click PXT "https://github.com/dinero-protocol/pirex-eth-contracts/tree/master/src/tokens"
    click ERC1155 "https://github.com/dinero-protocol/pirex-eth-contracts/tree/master/lib/solmate/src/tokens"
    click RR "https://github.com/dinero-protocol/pirex-eth-contracts/tree/master/src/"
```
