# renzo-protocol/contracts-public architecture

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

- Interactive diagram: https://gitdiagram.com/renzo-protocol/contracts-public
- Repository: https://github.com/renzo-protocol/contracts-public

## Overview

##### Main Architectural Components
- Core Protocol Component: Representing the Renzo Protocol itself, which manages deposits, withdrawals, collateral management, and reward accrual.
- Delegation Module: Manages which EL operators to delegate to and on what percentage.
- Deposit/Withdrawal Modules: Handling user deposits that mint ezETH and withdrawals that burn ezETH.
- Bridge Components: Found under the “contracts/Bridge” directory:
- Connext (with further divisions into core, integration, and libraries) – for cross-chain or cross-layer interactions.
- L1 and L2 specifics including Oracle and PriceFeed components, and the xERC20 modules, suggesting capability for bridged token interactions.
- EigenLayer Integration: The “contracts/EigenLayer” directory indicates specific logic for working with the underlying EigenLayer, with provided interfaces and libraries.
- Oracle and RateProvider Modules: These provide data feeds (from Binance, Mantle, etc.) which are likely used for pricing collateral and reward distribution.
- Rewards Module: Coordinates reward accrual from AVSs and ensures that they are properly credited through the protocol.
- Permissions and Errors: Security and error tracking constructs which are critical for smart contract safety.
- Token Management: Under “contracts/token” and parts of the collateral deposit logic, handling the ezETH minting and burning process.

##### Interactions and Relationships
- User Interaction: Users deposit collateral via the Deposits module. This triggers the minting of ezETH (appearing as a token management process).
- Governance/Delegation: Once collateral is deposited, the Delegation component manages the community’s decision on how to distribute stakes among EL operators.
- Reward Flow: When AVSs (provided by EigenLayer) issue rewards, the Rewards module integrates this payout to the protocol, updating the community’s stake and value.
- Cross-Chain/Layer Interaction: The Bridge components (Connext, L1, L2, Oracle modules) facilitate interactions with external systems and other blockchain layers.
- Oracle and Pricing: The Oracle and RateProvider components collect external price feeds (e.g., Binance, Mantle) and feed this data to smart contracts for proper valuation and execution of reward calculations.

##### Architectural Design Patterns and Important Principles
- Modularity / Separation of Concerns: Each directory (Delegation, Deposits, Bridge, etc.) is a distinct module with its own interfaces and libraries. This modularity helps isolate functionalities.
- Layered Architecture: There’s a clear separation between business logic (deposit/withdraw, delegation, rewards) and integration logic (Bridge for cross-chain communication, Oracle for pricing) as well as security (Permissions, Errors).
- Smart Contract Design Best Practices: Given the presence of extensive security audits (various PDFs in the Audit directory), it’s crucial to emphasize secure interactions between components – showing dependency flows carefully.

##### Recommended Process for the Principal Software Engineer
- Double-check that all key functionalities described in the README (stake pooling, collateral deposit, reward accrual, and delegation) are explicitly featured.
- Notes on the reliance on secure contract patterns and integration with external components (EigenLayer, Oracle sources, etc.).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interaction
    U("User"):::external

    %% On-Chain Smart Contracts
    subgraph "On-Chain Smart Contracts"
        RP("Renzo Protocol (Core)"):::core
        D("Deposits Contract"):::core
        W("Withdrawal Contract"):::core
        DG("Delegation Contract"):::core
        R("Rewards Contract"):::core
        TM("Token Management"):::core
    end

    %% Integration Modules
    subgraph "Integration Modules"
        EL("EigenLayer Integration"):::integration
        subgraph "Bridge Components"
            CN("Connext Components"):::integration
            L1("Bridge L1 (Oracle & PriceFeed)"):::integration
            L2("Bridge L2 (Oracle & PriceFeed)"):::integration
            XERC20("xERC20 Functionality"):::integration
        end
        OF("Oracle Feeds (Binance/Mantle)"):::integration
        RPVD("RateProvider"):::integration
    end

    %% Security Modules
    subgraph "Security Modules"
        P("Permissions"):::security
        E("Errors"):::security
    end

    %% Data Flow Connections
    U -->|"deposit_flow"| D
    D -->|"mint_ezETH"| TM
    TM -->|"burn_ezETH"| W
    D -->|"deposit_notification"| RP
    TM -->|"token_state_update"| RP
    RPVD -->|"price_updates"| D
    RPVD -->|"feed_to_rewards"| R
    DG -->|"stake_distribution"| EL
    EL -->|"reward_accrual"| R
    RP -->|"delegation_info"| DG
    RP -->|"valuation_data"| R
    OF -->|"price_feed"| RPVD

    %% Bridge / External Integration Connections
    RP -->|"cross-chain_interaction"| CN
    CN -->|"bridge_communication"| L1
    CN -->|"bridge_communication"| L2
    R -->|"external_payout"| XERC20

    %% Security Influence
    P --- RP
    P --- D
    P --- W
    P --- DG
    P --- R
    P --- TM
    E --- RP
    E --- D
    E --- W
    E --- DG
    E --- R
    E --- TM

    %% Click Events
    click RP "https://github.com/renzo-protocol/contracts-public/tree/master/contracts"
    click D "https://github.com/renzo-protocol/contracts-public/tree/master/contracts/Deposits"
    click W "https://github.com/renzo-protocol/contracts-public/tree/master/contracts/Withdraw"
    click DG "https://github.com/renzo-protocol/contracts-public/tree/master/contracts/Delegation"
    click R "https://github.com/renzo-protocol/contracts-public/tree/master/contracts/Rewards"
    click TM "https://github.com/renzo-protocol/contracts-public/tree/master/contracts/token"
    click CN "https://github.com/renzo-protocol/contracts-public/tree/master/contracts/Bridge/Connext"
    click L1 "https://github.com/renzo-protocol/contracts-public/tree/master/contracts/Bridge/L1"
    click L2 "https://github.com/renzo-protocol/contracts-public/tree/master/contracts/Bridge/L2"
    click XERC20 "https://github.com/renzo-protocol/contracts-public/tree/master/contracts/Bridge/xERC20"
    click EL "https://github.com/renzo-protocol/contracts-public/tree/master/contracts/EigenLayer"
    click OF "https://github.com/renzo-protocol/contracts-public/tree/master/contracts/Oracle"
    click RPVD "https://github.com/renzo-protocol/contracts-public/tree/master/contracts/RateProvider"
    click P "https://github.com/renzo-protocol/contracts-public/tree/master/contracts/Permissions"
    click E "https://github.com/renzo-protocol/contracts-public/tree/master/contracts/Errors"

    %% Styles
    classDef core fill:#AED6F1,stroke:#1F618D,stroke-width:2px;
    classDef integration fill:#ABEBC6,stroke:#229954,stroke-width:2px;
    classDef security fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef external fill:#F5B7B1,stroke:#922B21,stroke-width:2px;
```
