# scallop-io/sui-lending-protocol architecture

> Architecture diagram of the GitHub repository scallop-io/sui-lending-protocol, 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/scallop-io/sui-lending-protocol
- Repository: https://github.com/scallop-io/sui-lending-protocol

## Overview

##### Project Type and Purpose
- This project is a blockchain-based lending protocol implemented using the SUI network. It leverages Move smart contracts for on-chain logic and TypeScript for deployment and interaction.
- The README clearly shows the use of the Scallop SDK to interact with the contracts. The protocol is designed to be simple, efficient, secure, and composable so that other protocols can integrate with it.

##### Key Components (as seen in the file tree)
- Move Contracts:
- The “contracts” directory is central and includes many subfolders:
- Libraries (“contracts/libs”): Contains reusable Move modules for specific functions (e.g., coin_decimals_registry, math, whitelist, and x). These provide fundamental operations and abstractions.
- Protocol (“contracts/protocol”): Contains the core lending protocol logic, covering elements such as market, evaluator, user operations, obligation management, and error handling.
- Protocol Whitelist: Likely offering access control or additional security checks.
- Query: Contains smart-contract code to retrieve on-chain state (e.g., market and obligation queries).
- Oracle Integrations (under “contracts/sui_x_oracle”): Multiple folders (pyth_rule, supra_rule, switchboard_rule, x_oracle) support different oracle integrations for price feeds and other external data.
- Test and Test Coin packages: (found in “contracts/test” and “contracts/test_coin”) for simulating transactions and validating contract behavior.
- TypeScript Interactions:
- Under many directories (e.g., protocol/typescript, libs’ typescript subfolders, test_coin/typescript) there are modules for building, deploying, and interacting with smart contracts. They include tx-builder scripts and publish-result parsers.
- Setup Scripts:
- “mainnet-data-setup” and “testnet-data-setup” directories include scripts (in TypeScript) for tasks such as initializing markets, setting up fees, managing protocol upgrades, and deploying configuration on various networks.
- Environment & Configuration:
- The .env.example, Move.toml files (by network type), and publish-result JSON files provide configuration details needed during deployment and interaction.
- Auxiliary Components:
- The project includes other items (e.g., sui-elements) likely to provide additional SDK or utility functions.

- Blockchain and its deployed Move contracts:
- Together the core Move modules under the “protocol” package.
- Libraries used by the protocol and how they support core functions (data types, math operations, access control).
- TypeScript Integration Layer:
- Data Flow & Interactions:
- Flows like “deployment phase” (using publish-result JSON and Move.toml) and “runtime on-chain interactions” (transactions invoked via tx-builder).

##### Architectural Patterns and Design Principles
- Modularity and Composability:
- Separation of Concerns:
- Clearly delineate smart contract code (Move sources) from deployment and interaction code (TypeScript scripts).
- Environment-based Configuration:
- How network-specific configuration is achieved via Move.toml files (e.g., mainnet, testnet, devnet) ensuring that deployment behavior adapts per environment.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Off-chain Components
    subgraph "Off-chain Layer"
        ClientSDK["Scallop SDK/Clients"]:::offchain
        TSProtocol["TypeScript Integration (Protocol)"]:::offchain
        TSLibs["TypeScript Integration (Library Modules)"]:::offchain
        SetupMainnet["Setup Scripts (Mainnet)"]:::offchain
        SetupTestnet["Setup Scripts (Testnet)"]:::offchain
        EnvConfig["Env & Config Files"]:::utility
        AuxSDK["Auxiliary SDK/Utilities"]:::utility
    end

    %% On-chain Components
    subgraph "On-chain Move Contracts"
        CoreProtocol["Move Contracts – Core Protocol"]:::onchain
        Libraries["Move Contracts – Libraries"]:::onchain
        ProtocolWhitelist["Move Contracts – Protocol Whitelist"]:::onchain
        QueryModule["Move Contracts – Query Module"]:::onchain
        subgraph "Oracle Integrations"
            PythOracle["Move Contracts – Oracle Integration (Pyth)"]:::onchain
            SupraOracle["Move Contracts – Oracle Integration (Supra)"]:::onchain
            SwitchboardOracle["Move Contracts – Oracle Integration (Switchboard)"]:::onchain
            XOracle["Move Contracts – Oracle Integration (X Oracle)"]:::onchain
        end
    end

    %% Data Flow - Off-chain to On-chain
    ClientSDK -->|"initiates"| TSProtocol
    ClientSDK -->|"can use"| AuxSDK
    TSProtocol -->|"deploys/interacts"| CoreProtocol
    TSLibs -->|"supports"| Libraries
    SetupMainnet -->|"configures"| CoreProtocol
    SetupTestnet -->|"configures"| CoreProtocol
    EnvConfig --- TSProtocol
    EnvConfig --- SetupMainnet
    EnvConfig --- SetupTestnet

    %% Internal On-chain Interactions
    CoreProtocol -->|"uses"| Libraries
    CoreProtocol -->|"calls"| ProtocolWhitelist
    CoreProtocol -->|"queries"| QueryModule
    CoreProtocol -->|"integrates"| PythOracle
    CoreProtocol -->|"integrates"| SupraOracle
    CoreProtocol -->|"integrates"| SwitchboardOracle
    CoreProtocol -->|"integrates"| XOracle

    %% Class definitions for styling
    classDef onchain fill:#ADD8E6,stroke:#00008B,stroke-width:2px;
    classDef offchain fill:#90EE90,stroke:#006400,stroke-width:2px;
    classDef utility fill:#FFD700,stroke:#B8860B,stroke-width:2px;

    %% Click Events for Component Mapping
    click CoreProtocol "https://github.com/scallop-io/sui-lending-protocol/tree/main/contracts/protocol"
    click Libraries "https://github.com/scallop-io/sui-lending-protocol/tree/main/contracts/libs"
    click ProtocolWhitelist "https://github.com/scallop-io/sui-lending-protocol/tree/main/contracts/protocol_whitelist"
    click QueryModule "https://github.com/scallop-io/sui-lending-protocol/tree/main/contracts/query"
    click PythOracle "https://github.com/scallop-io/sui-lending-protocol/tree/main/contracts/sui_x_oracle/pyth_rule"
    click SupraOracle "https://github.com/scallop-io/sui-lending-protocol/tree/main/contracts/sui_x_oracle/supra_rule"
    click SwitchboardOracle "https://github.com/scallop-io/sui-lending-protocol/tree/main/contracts/sui_x_oracle/switchboard_rule"
    click XOracle "https://github.com/scallop-io/sui-lending-protocol/tree/main/contracts/sui_x_oracle/x_oracle"
    click TSProtocol "https://github.com/scallop-io/sui-lending-protocol/tree/main/contracts/protocol/typescript"
    click TSLibs "https://github.com/scallop-io/sui-lending-protocol/tree/main/contracts/libs/coin_decimals_registry/typescript"
    click SetupMainnet "https://github.com/scallop-io/sui-lending-protocol/tree/main/mainnet-data-setup"
    click SetupTestnet "https://github.com/scallop-io/sui-lending-protocol/tree/main/testnet-data-setup"
    click EnvConfig "https://github.com/scallop-io/sui-lending-protocol/blob/main/.env.example"
    click AuxSDK "https://github.com/scallop-io/sui-lending-protocol/tree/main/sui-elements"
```
