How xoxno/rs-liquid-staking-sc works
Project Type and Purpose
• The project is a decentralized liquid staking protocol designed for the MultiversX blockchain network. It creates a system where users stake EGLD and get its liquid representation (xEGLD) with benefits such as instant un-staking and reward compounding.
• The design addresses issues in other staking protocols by employing advanced delegation pooling, daily batch delegation across multiple providers, dynamic un-delegation, and reward reinvestment.
File Structure and Key Insights
• Three main “sub-projects” or modules are visible:
• "delegation-manager-mock" – a mocked delegation manager component.
• "delegation-mock" – another delegation module, perhaps used for different test scenarios or environments.
• "liquid-staking" – the main protocol implementation, containing the majority of business logic (e.g., modules for delegation, rewards, un-delegation, proxy functionality).
• Each module contains:
• A “meta” directory: likely for deployment/management scripts and metadata.
• Source directories (src) outlining the contract logic.
• A WASM subdirectory: which indicates these contracts are compiled to WebAssembly for on-chain deployment.
• The presence of configuration files (e.g., multiversx.json, sc-config.toml) confirms these are smart contracts deployed on the MultiversX network.
Core Components
• Smart Contract / On-Chain Protocol:
• Liquid Staking Main Contract: Implements the primary logic for handling delegation pooling, batch delegations, instant un-staking, and rewards.
• Delegation Modules: Separate components or endpoints (as functions) that handle “delegate”, “unDelegate”, “withdraw” actions.
• Providers and their Interaction:
• Provider Management: Responsible for receiving batched delegations, handling their dynamic un-delegation and enabling decentralized provider selection.
• xEGLD and Token Dynamics:
• xEGLD Token Module: Represents the liquid token issued to users upon staking.
• Auxiliary Components:
• Mock Delegation Managers: “delegation-manager-mock” and “delegation-mock” for testing or simulation of delegation behavior.
• WASM Modules: The compiled WebAssembly libraries that hold the smart contract logic.
• Configuration & Deployment Artifacts: Tools (.github workflows and configuration files) that help with continuous integration and deployment.
• External Interfaces & Endpoints:
• User Endpoints: “delegate”, “unDelegate”, “withdraw” where user actions are received.
• Provider Endpoints: “delegatePending”, “unDelegatePending”, “withdrawPending”, “claimRewards”, “delegateRewards” which orchestrate provider-side operations.
Relationships and Interactions Between Components
• User interaction flows into the protocol via clearly defined endpoints:
• When a user calls the “delegate” endpoint, the protocol accumulates EGLD into a staking pool.
• Once per day, the “delegatePending” process kicks in, distributing the pooled EGLD across multiple providers using batch delegation logic.
• For un-staking, the system checks for available EGLD in the pool or sends the user into a tracking unbonding period, represented with NFT issuance.
• The reward compounding module automatically reinvests claimed rewards by minting fresh xEGLD.
• Communication and data flow between the smart contract modules (core logic in “liquid-staking” src) and the WASM components are central—so you want to indicate that connection clearly.
• Mock components are used during testing to simulate actual delegation events, ensuring safe deployment and predictability.
Architectural Patterns and Design Principles
• Modularity: Different directories and modules (e.g., delegation, proxy, reward) indicate a clear separation of concerns.
• Smart Contract Design: The use of WASM modules for on-chain execution with Rust indicates an immutable, audited core logic.
• Batch Processing: Daily batching of delegations minimizes transaction spam and optimizes resource usage.
• Decentralization and Autonomy: The protocol minimizes admin intervention by using public endpoints and autonomous update mechanisms.
Recommended Elements
• Use clearly labeled blocks representing:
• User Interface / API Endpoints (“delegate”, “unDelegate”, “withdraw”).
• Liquid Staking Contract (main business logic from “liquid-staking” source).
• Delegation Managers (mock and actual, representing both “delegation-manager-mock” and “delegation-mock”).
• Provider Interaction Modules (endpoints like “delegatePending”, “claimRewards”, etc.).
• WASM Compilation Process (indicate that the Rust source is compiled into WASM for on-chain deployment).
• Blockchain (MultiversX network) as the overarching deployment and execution environment.
• Data flow from users into the Primary Liquid Staking module.
• The periodic batch delegation to various providers.
• The feedback loop for rewards and reinvestment.
• Clear labels for every component, and, if possible, note key modules (like “Reward Compounding”, “Dynamic Un-delegation”, “Delegation Pooling”).