# xoxno/rs-liquid-staking-sc architecture

> Architecture diagram of the GitHub repository xoxno/rs-liquid-staking-sc, 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/xoxno/rs-liquid-staking-sc
- Repository: https://github.com/xoxno/rs-liquid-staking-sc

## Overview

##### 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”).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interaction Layer
    subgraph "User Interactions"
        UI["User Endpoints (delegate,unDelegate,withdraw)"]:::user
    end

    %% Protocol Core Layer
    subgraph "Protocol Core"
        DM["Delegation Module"]:::protocol
        LSMC["Liquid Staking Main Contract"]:::protocol
        PD1["Proxy Delegation Manager"]:::protocol
        PD2["Proxy Delegation"]:::protocol
        RC["Reward Compounding"]:::protocol
    end

    %% Testing Modules Layer
    subgraph "Testing Modules"
        MDM["Mock Delegation Manager"]:::testing
        MDM_WASM["Mock Delegation Manager WASM"]:::wasm
        MD["Mock Delegation Module"]:::testing
        MD_WASM["Mock Delegation Module WASM"]:::wasm
    end

    %% WASM Artifacts Layer
    subgraph "WASM Artifacts"
        LSMC_WASM["Liquid Staking WASM"]:::wasm
    end

    %% Deployment Environment Layer
    subgraph "Deployment Environment"
        BLOCK["MultiversX Blockchain"]:::deployment
        CONFIG["Configuration & Deployment (multiversx.json,sc-config.toml,CI/CD)"]:::deployment
    end

    %% Connections: User -> Core
    UI -->|"calls"| DM
    DM -->|"aggregates EGLD"| LSMC

    %% Connections: Core internal flows
    LSMC -->|"triggers batch"| PD1
    LSMC -->|"invokes proxy"| PD2
    PD1 -->|"sends to"| BLOCK
    PD2 -->|"sends to"| BLOCK
    LSMC -->|"compounds rewards"| RC
    RC -->|"updates"| LSMC
    LSMC -->|"deployed on"| BLOCK
    LSMC -->|"compiled to"| LSMC_WASM

    %% Connections: Testing Modules influence
    MDM -->|"simulates delegations"| LSMC
    MD -->|"simulates delegation"| LSMC
    MDM --> MDM_WASM
    MD --> MD_WASM

    %% Connections: Deployment Config
    CONFIG -->|"configures"| LSMC
    CONFIG -->|"configures"| MDM
    CONFIG -->|"configures"| MD

    %% Class Definitions for Colors
    classDef user fill:#d4edda,stroke:#333,stroke-width:2px;
    classDef protocol fill:#cce5ff,stroke:#333,stroke-width:2px;
    classDef testing fill:#f8d7da,stroke:#333,stroke-width:2px;
    classDef wasm fill:#fff3cd,stroke:#333,stroke-width:2px;
    classDef deployment fill:#e2e3e5,stroke:#333,stroke-width:2px;

    %% Click Events for Component Mapping
    click LSMC "https://github.com/xoxno/rs-liquid-staking-sc/blob/main/liquid-staking/src/lib.rs"
    click DM "https://github.com/xoxno/rs-liquid-staking-sc/blob/main/liquid-staking/src/delegation.rs"
    click PD1 "https://github.com/xoxno/rs-liquid-staking-sc/blob/main/liquid-staking/src/proxy/proxy_delegation_manager.rs"
    click PD2 "https://github.com/xoxno/rs-liquid-staking-sc/blob/main/liquid-staking/src/proxy/proxy_delegation.rs"
    click MDM "https://github.com/xoxno/rs-liquid-staking-sc/blob/main/delegation-manager-mock/src/delegation_manager.rs"
    click MDM_WASM "https://github.com/xoxno/rs-liquid-staking-sc/blob/main/delegation-manager-mock/wasm/src/lib.rs"
    click MD "https://github.com/xoxno/rs-liquid-staking-sc/blob/main/delegation-mock/src/delegation.rs"
    click MD_WASM "https://github.com/xoxno/rs-liquid-staking-sc/blob/main/delegation-mock/wasm/src/lib.rs"
    click LSMC_WASM "https://github.com/xoxno/rs-liquid-staking-sc/blob/main/liquid-staking/wasm/src/lib.rs"
```
