How code-423n4/2025-01-liquid-ron works
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.