# code-423n4/2025-01-liquid-ron architecture

> Architecture diagram of the GitHub repository code-423n4/2025-01-liquid-ron, 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/code-423n4/2025-01-liquid-ron
- Repository: https://github.com/code-423n4/2025-01-liquid-ron

## Overview

##### Project Type and Purpose
- Liquid Ron is a smart contract-based staking protocol built on the Ronin chain. Its purpose is to automate user staking actions via a vault mechanism that issues a liquid token (Liquid RON) representing a user’s stake while auto-compounding rewards.
- The README confirms the automated flow for depositing RON, auto-compounding rewards, and managing staking actions. It also specifies roles (Owner, Operators) and the flow of funds (User ⇆ Vault ⇆ Proxies ⇆ Staking Protocol).

##### Analyzing the File Structure
- Top-Level Files: You see configuration files (.gitignore, foundry.toml, remappings.txt, etc.) and various README and report documents.
- Directories:
- src: Contains the Solidity contracts which implement the core business logic. It includes:
- Core contracts (LiquidRon.sol, LiquidProxy.sol, ValidatorTracker.sol, etc.)
- Helper contracts (RonHelper.sol, Pausable.sol)
- Interfaces and mocks (in subdirectories) – indicating abstraction layers and testing strategies.
- lib: Contains the OpenZeppelin contracts, underscoring reliance on well-established libraries for ERC20/ERC4626 and access control.
- script and test: Provide deployment scripts and tests (using Foundry) to validate the logic.
- This structure indicates a modular smart contract project with separation between production code, interfaces/mocks, and testing tooling.

##### Key Components
a. Main Components:
- User Interfaces: The external interactions come via the ERC4626-compliant vault functions and the custom deposit and redeem functions.
- Vault (LiquidRon.sol): Acts as the core contract managing deposits and withdrawals along with compounding rewards.
- Proxies (LiquidProxy.sol): Responsible for routing funds to staking protocols and segregating stake management logic.
- Staking Protocol: The external staking mechanism on the Ronin chain where funds are staked. This could be represented as an external system.
- Auxiliary Contracts: ValidatorTracker, RonHelper, Pausable, and Escrow – each with their own roles supporting the core function.
- OpenZeppelin Libraries: Underlying contracts (ERC4626, Ownable, Math, etc.) providing standard functionalities such as token standard compliance and role management.

b. Relationships and Data Flow:
- Users interact with the Vault (LiquidRon) via ERC4626 and custom functions.
- The Vault, in turn, routes user funds to deployed Proxies.
- Proxies interact with the external staking protocol.
- ValidatorTracker (and possibly other helper contracts) maintains staking state and validator data.
- Clearly incorporate role-based access: Owner, Operators, and external users. Note that only the owner can deploy new proxies, while operators control staking flows.

c. Architectural Patterns & Design Principles:
- Layered Architecture: There’s a clear separation between contract logic (controllers) and helper/util libraries (provided by OpenZeppelin).
- Proxy Pattern: Use of LiquidProxy indicates upgradeability or separation of concerns even if standard upgradeability isn’t in scope.
- Encapsulation of staking logic: The design clearly separates users' interactions from the actual staking mechanics to ensure invariants are met (e.g., funds shouldn’t jump directly from one component to another).

d. Key Technologies/Frameworks:
- Solidity smart contracts.
- Foundry for deployment and tests (indicated by foundry.toml, script, and test folders).
- OpenZeppelin libraries for secure implementations of ERC standards and access control.

##### Essential Details
- Every component is clearly labeled.
- For example, “User deposits RON → Vault processes via ERC4626 functions → Funds forwarded to LiquidProxy → Funds staked on Ronin staking protocol.”
- Architectural invariants (only route funds via the intended chain) to reinforce security considerations.
- Dependencies on OpenZeppelin libraries by adding a brief note next to the involved contracts.
- Roles and interactions between Owner, Operators, and Users for clarity.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Main Flow
    UI["User Interface / Wallet Interaction"]:::user
    Vault["Vault (LiquidRon Contract)"]:::contract
    Proxy["Liquid Proxy (LiquidProxy Contract)"]:::contract
    Staking["Staking Protocol (Ronin Network)"]:::external

    UI -->|"deposit tokens"| Vault
    Vault -->|"forward funds"| Proxy
    Proxy -->|"stake assets"| Staking

    %% Administrative Roles
    Owner["Owner"]:::admin
    Operators["Operators"]:::admin

    Owner ---|"admin access"| Vault
    Operators ---|"control flows"| Vault
    Operators ---|"manage proxy"| Proxy

    %% Helper Contracts Subgraph
    subgraph "Helper Contracts"
        VT["Validator Tracker (Helper Contract)"]:::helper
        RH["Ron Helper (Helper Contract)"]:::helper
        Pause["Pausable (Helper Contract)"]:::helper
    end

    Vault ---|"tracks validators"| VT
    Vault ---|"utilizes"| RH
    Vault ---|"emergency stop"| Pause

    %% Development & Libraries Subgraph
    subgraph "Development & Libraries" 
        OZ["OpenZeppelin Libraries"]:::dev
        IM["Interfaces & Mocks"]:::dev
        DS["Deployment Scripts"]:::dev
        Test["Tests"]:::dev
    end

    Vault ---|"secure functions"| OZ
    Proxy ---|"inherits control"| OZ
    DS ---|"deployment"| Vault
    DS ---|"deployment"| Proxy
    Test ---|"validation"| Vault
    Test ---|"validation"| Proxy
    Test ---|"validation"| VT

    %% Click Events
    click Vault "https://github.com/code-423n4/2025-01-liquid-ron/blob/main/src/LiquidRon.sol"
    click Proxy "https://github.com/code-423n4/2025-01-liquid-ron/blob/main/src/LiquidProxy.sol"
    click VT "https://github.com/code-423n4/2025-01-liquid-ron/blob/main/src/ValidatorTracker.sol"
    click RH "https://github.com/code-423n4/2025-01-liquid-ron/blob/main/src/RonHelper.sol"
    click Pause "https://github.com/code-423n4/2025-01-liquid-ron/blob/main/src/Pausable.sol"
    click IM "https://github.com/code-423n4/2025-01-liquid-ron/tree/main/src/interfaces"
    click IM "https://github.com/code-423n4/2025-01-liquid-ron/tree/main/src/mock"
    click OZ "https://github.com/code-423n4/2025-01-liquid-ron/tree/main/lib/openzeppelin-contracts"
    click DS "https://github.com/code-423n4/2025-01-liquid-ron/tree/main/script"
    click Test "https://github.com/code-423n4/2025-01-liquid-ron/tree/main/test"

    %% Styles
    classDef user fill:#FFD966,stroke:#B45F06,stroke-width:2px;
    classDef contract fill:#9FC5E8,stroke:#1155CC,stroke-width:2px;
    classDef external fill:#C9E265,stroke:#6AA84F,stroke-width:2px;
    classDef admin fill:#F6B26B,stroke:#E69138,stroke-width:2px;
    classDef helper fill:#FFF2CC,stroke:#BF9000,stroke-width:2px;
    classDef dev fill:#D9D2E9,stroke:#8E7CC3,stroke-width:2px;
```
