# resolv-im/resolv-contracts-public architecture

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

- Interactive diagram: https://gitdiagram.com/resolv-im/resolv-contracts-public
- Repository: https://github.com/resolv-im/resolv-contracts-public

## Overview

##### Project type and purpose
- This is a suite of Ethereum smart-contracts (Solidity) implementing a DeFi protocol (“Resolv”) that issues and manages ERC-20 tokens (USR, RLP, stUSR, wstUSR), interacts with external liquidity protocols (Aave, Dinero, Lido), collects price data via on-chain oracles, enforces a whitelist, handles redemption and requests, and distributes rewards.

##### File structure
- Top-level:
- README.md — project overview, deployed addresses, audit history
- contracts/ — all Solidity code
- contracts/interfaces/external/…
- aave, dinero, lido, oracles — interfaces to external protocols and on-chain price sources
- contracts/oracles/ — implementations of price storage contracts
- Other modules implied by README (not in tree): connectors, request managers, treasury, reward distributor

##### README for additional insights
- Lists all core contracts and their roles (ERC20 tokens, Whitelist, RequestsManager, RewardDistributor).

a. Main components:
1. ERC20 Tokens module (USR, RLP, stUSR, wstUSR)
2. Requests Managers (USRRequestsManager, RLPRequestsManager, externalRequestsManager)
3. Treasury & Connectors (Treasury, AaveV3TreasuryConnector, DineroTreasuryConnector, LidoTreasuryConnector)
4. Oracles & PriceStorage (UsrPriceStorage, RlpPriceStorage)
5. Whitelist module
6. RewardDistributor
7. External Services (Aave, Dinero, Lido, Chainlink oracles)
b. Relationships & interactions:
- Users → (whitelisted) → RequestsManager → mints/burns ERC20 tokens
- RequestsManager ↔ TreasuryConnectors → external DeFi protocols (lend/borrow, stake)
- Oracles pull price data from external on-chain sources → PriceStorage contracts
- RewardDistributor reads balances & price data → issues rewards to token holders
c. Architectural patterns:
- Modular “Connector” pattern: isolates each external protocol behind an interface
- Separation of concerns: token logic, treasury logic, oracle logic, reward logic, access control via Whitelist
- Upgradable vs. non-upgradable components (see “Upgradeable” suffix in contracts)
d. Key technologies & libraries:
- Solidity, ERC20 (OpenZeppelin)
- Hardhat/Truffle (implied), Etherscan verification
- On-chain oracles (Chainlink or custom oracle feeds)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User flow
    Users["Users"]:::external
    Users -->|"access"| Whitelist

    %% Whitelist
    Whitelist["Whitelist"]:::control
    Whitelist -->|"authorize"| USRReqMgr
    Whitelist -->|"authorize"| RLPReqMgr
    Whitelist -->|"authorize"| ExtReqMgr

    %% Requests Managers
    subgraph "Requests Layer"
        direction TB
        USRReqMgr["USRRequestsManager"]:::contract
        RLPReqMgr["RLPRequestsManager"]:::contract
        ExtReqMgr["ExternalRequestsManager"]:::contract
    end
    USRReqMgr -->|"mint/burn"| Tokens
    RLPReqMgr -->|"mint/burn"| Tokens
    ExtReqMgr -->|"mint/burn"| Tokens

    %% Tokens
    subgraph "Token Layer"
        direction TB
        Tokens["USR, RLP, stUSR, wstUSR (ERC20)"]:::contract
    end

    %% Treasury Connectors
    subgraph "Treasury Connectors" 
        direction TB
        AaveConnector["AaveV3TreasuryConnector"]:::connector
        DineroConnector["DineroTreasuryConnector"]:::connector
        LidoConnector["LidoTreasuryConnector"]:::connector
    end
    USRReqMgr -->|"deposit/withdraw"| AaveConnector
    USRReqMgr -->|"deposit/withdraw"| DineroConnector
    USRReqMgr -->|"deposit/withdraw"| LidoConnector
    RLPReqMgr -->|"deposit/withdraw"| AaveConnector
    RLPReqMgr -->|"deposit/withdraw"| DineroConnector
    RLPReqMgr -->|"deposit/withdraw"| LidoConnector
    ExtReqMgr -->|"deposit/withdraw"| AaveConnector
    ExtReqMgr -->|"deposit/withdraw"| DineroConnector
    ExtReqMgr -->|"deposit/withdraw"| LidoConnector

    %% External Protocols
    subgraph "External Protocols" 
        direction TB
        Aave["Aave Protocol"]:::external
        Dinero["Dinero Protocol"]:::external
        Lido["Lido Protocol"]:::external
        ChainlinkOracle["Chainlink/Other Oracles"]:::external
    end
    AaveConnector -->|"interface"| Aave
    DineroConnector -->|"interface"| Dinero
    LidoConnector -->|"interface"| Lido
    ChainlinkOracle -->|"feeds"| PriceStorage

    %% Oracles & Price Storage
    subgraph "Oracle Layer"
        direction TB
        PriceStorage["UsrPriceStorage, RlpPriceStorage"]:::storage
    end
    ChainlinkOracle --> PriceStorage
    PriceStorage --> RewardDist

    %% Reward Distributor
    RewardDist["RewardDistributor"]:::reward
    RewardDist -->|"distribute rewards"| Tokens

    %% Click Events
    click AaveConnector "https://github.com/resolv-im/resolv-contracts-public/tree/main/contracts/interfaces/external/aave"
    click DineroConnector "https://github.com/resolv-im/resolv-contracts-public/tree/main/contracts/interfaces/external/dinero"
    click LidoConnector "https://github.com/resolv-im/resolv-contracts-public/tree/main/contracts/interfaces/external/lido"
    click ChainlinkOracle "https://github.com/resolv-im/resolv-contracts-public/tree/main/contracts/interfaces/external/oracles"
    click PriceStorage "https://github.com/resolv-im/resolv-contracts-public/tree/main/contracts/oracles"

    %% Styles
    classDef contract fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef connector fill:#FFA500,stroke:#000,stroke-width:1px
    classDef storage fill:#90EE90,stroke:#000,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#000,stroke-width:1px
    classDef control fill:#DDA0DD,stroke:#000,stroke-width:1px
    classDef reward fill:#FFD700,stroke:#000,stroke-width:1px
```
