# balancednetwork/balanced-java-contracts architecture

> Architecture diagram of the GitHub repository balancednetwork/balanced-java-contracts, 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/balancednetwork/balanced-java-contracts
- Repository: https://github.com/balancednetwork/balanced-java-contracts

## Overview

This project is a collection of smart contracts written in Java for the Balanced network. The project is modular and organized into multiple submodules and directories representing different smart contract components, client libraries, and utilities. Essentially, it serves as a backend (smart contract) system for managing decentralized finance (DeFi) functionalities such as asset management, oracle services, governance, loans, decentralized exchange (Dex), rewards, staking, and additional token functionality.

##### Main components
- Smart Contract Modules: The “core-contracts” directory includes various modules such as AssetManager, BalancedOracle, BatchDisbursement, DAOfund, Dex, Dividends, FeeHandler, Governance, Loans, Multicall, Rebalancing, Reserve, Rewards, Router, Savings, StakedLP, Staking, etc. Each module implements its own functionalities and sometimes has integration tests, main implementations, and helper utilities.
- Token Contracts: The “token-contracts” directory includes modules for different token implementations (AssetToken, BalancedDollar, BalancedToken, Sicx, WorkerToken, bBaln, etc.) which defines the token logic used within the Balanced network.
- Client Libraries: The “score-client” and “score-lib” directories provide Java-based utilities and interfaces for communicating with the deployed smart contracts. They include functionality for JSON-RPC communications and contract interactions.
- Utility and Helper Contracts: The “util-contracts” directory contains additional components such as burners, dummy oracles, OTC components, stability modules, and cross-chain call managers.
- Build and Deployment Infrastructure: The root of the project includes Gradle build files, GitHub Actions workflows, Docker configuration (docker-compose.yml), and deployment scripts that help build, test (unit and integration), and deploy the contracts on a local blockchain (using Docker).

##### Relationships and interactions
- Smart Contract Communication: Although each module stands on its own, many of them interact indirectly. For example, governance contracts, fee handlers, oracles, and loans likely interact through standardized interfaces defined in “score-lib”. These interfaces are also implemented by the corresponding smart contracts.
- Client–Contract Interaction: The “score-client” module is used to interact with the smart contracts deployed on the blockchain. This shows a clear separation between the on-chain code (the smart contracts) and the off-chain client which interacts with them.
- Module Coupling: Many modules depend on shared utilities like common constants, database wrappers, and token standards (IRC2 interfaces, for instance). Also note that the Gradle build system integrates all these modules, and Continuous Integration (CI) workflows validate changes every time.

##### Architectural patterns and design principles
- Contract Interface Standardization: The “score-lib” package defines many interfaces which are implemented by corresponding smart contract modules and token contracts, ensuring consistent interaction protocols.
- Build and Testing Pipelines: The repository includes extensive Gradle build scripts and GitHub Actions workflows for testing and deployment, showing a strong emphasis on CI/CD practices.
- Separation of Concerns: Core business logic is separated into core contracts, token contracts, utility modules, and client libraries.

##### Relevant technologies and frameworks
- Gradle: Used as the build automation tool (see build.gradle, settings.gradle, and buildSrc).
- GitHub Actions: For automated testing and code quality (workflows in .github/workflows).
- Docker & Docker-compose: For local blockchain deployment and integration testing.

##### Elements
- Client applications (score-client) and smart contracts.
- Smart contracts and external or on-chain interaction (e.g., governance proposals, tokens transfers).
- Integration flows between different contract components (some contracts may delegate or call functions in others).
- Notes or annotations to capture key responsibilities (for example, “Governance manages proposals via standardized interfaces defined in score-lib” or “Loans module interacts with collateral databases”).

– At the core, multiple smart contract modules (organized by functionality) interact with one another through well-defined interfaces.
– Surrounding this core are supporting client libraries (score-client, score-lib) that enable external interaction.
– Additionally, illustrate the CI/CD and deployment pipeline (Gradle builds, Docker, GitHub workflows) that bring these components together.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% On-Chain Smart Contracts
    subgraph "On-Chain Smart Contracts"
        %% Core Contracts
        subgraph "Core Contracts"
            AssetManager["AssetManager"]:::smartContract
            BalancedOracle["BalancedOracle"]:::smartContract
            BatchDisbursement["BatchDisbursement"]:::smartContract
            DAOfund["DAOfund"]:::smartContract
            Dex["Dex"]:::smartContract
            Dividends["Dividends"]:::smartContract
            FeeHandler["FeeHandler"]:::smartContract
            Governance["Governance"]:::smartContract
            Loans["Loans"]:::smartContract
            Multicall["Multicall"]:::smartContract
            Rebalancing["Rebalancing"]:::smartContract
            Reserve["Reserve"]:::smartContract
            Rewards["Rewards"]:::smartContract
            Router["Router"]:::smartContract
            Savings["Savings"]:::smartContract
            StakedLP["StakedLP"]:::smartContract
            Staking["Staking"]:::smartContract
        end

        %% Token Contracts
        subgraph "Token Contracts"
            AssetToken["AssetToken"]:::token
            BalancedDollar["BalancedDollar"]:::token
            BalancedToken["BalancedToken"]:::token
            Sicx["Sicx"]:::token
            WorkerToken["WorkerToken"]:::token
            bBaln["bBaln"]:::token
        end

        %% Utility and Helper Contracts
        subgraph "Utility Contracts"
            Burner["Burner"]:::utility
            DummyOracle["DummyOracle"]:::utility
            OTCComponents["OTC Components"]:::utility
            StabilityModules["Stability Modules"]:::utility
            Trickler["Trickler"]:::utility
            XCallManager["XCall Manager"]:::utility
            XCallMock["XCall Mock"]:::utility
        end
    end

    %% Off-Chain Components
    subgraph "Off-Chain Components"
        SCOREClient["SCORE Client"]:::client
        SCORELibrary["SCORE Library"]:::client
    end

    %% Build & Deployment
    subgraph "Build & Deployment"
        GradleBuild["Gradle & Build Scripts"]:::deployment
        CICD["CI/CD"]:::deployment
        Docker["Docker"]:::deployment
    end

    %% Connections between components
    SCOREClient -->|"calls"| SCORELibrary
    SCORELibrary -->|"interface"| Governance
    SCORELibrary -->|"interface"| AssetToken

    %% Core contracts intercommunications
    Governance -->|"manages"| FeeHandler
    Loans -->|"interacts_with"| Reserve
    Dex -->|"routes"| Router

    %% Build & Deployment flows
    CICD -->|"triggers"| GradleBuild
    Docker -->|"deploys"| GradleBuild
    GradleBuild -->|"builds"| AssetManager

    %% Class definitions for styling
    classDef smartContract fill:#F9C74F,stroke:#333,stroke-width:2px;
    classDef token fill:#90BE6D,stroke:#333,stroke-width:2px;
    classDef client fill:#577590,stroke:#fff,stroke-width:2px,color:#fff;
    classDef utility fill:#F9844A,stroke:#333,stroke-width:2px;
    classDef deployment fill:#43AA8B,stroke:#333,stroke-width:2px;

    %% Click Events for Smart Contract Modules
    click AssetManager "https://github.com/balancednetwork/balanced-java-contracts/tree/main/core-contracts/AssetManager"
    click BalancedOracle "https://github.com/balancednetwork/balanced-java-contracts/tree/main/core-contracts/BalancedOracle"
    click BatchDisbursement "https://github.com/balancednetwork/balanced-java-contracts/tree/main/core-contracts/BatchDisbursement"
    click DAOfund "https://github.com/balancednetwork/balanced-java-contracts/tree/main/core-contracts/DAOfund"
    click Dex "https://github.com/balancednetwork/balanced-java-contracts/tree/main/core-contracts/Dex"
    click Dividends "https://github.com/balancednetwork/balanced-java-contracts/tree/main/core-contracts/Dividends"
    click FeeHandler "https://github.com/balancednetwork/balanced-java-contracts/tree/main/core-contracts/FeeHandler"
    click Governance "https://github.com/balancednetwork/balanced-java-contracts/tree/main/core-contracts/Governance"
    click Loans "https://github.com/balancednetwork/balanced-java-contracts/tree/main/core-contracts/Loans"
    click Multicall "https://github.com/balancednetwork/balanced-java-contracts/tree/main/core-contracts/Multicall"
    click Rebalancing "https://github.com/balancednetwork/balanced-java-contracts/tree/main/core-contracts/Rebalancing"
    click Reserve "https://github.com/balancednetwork/balanced-java-contracts/tree/main/core-contracts/Reserve"
    click Rewards "https://github.com/balancednetwork/balanced-java-contracts/tree/main/core-contracts/Rewards"
    click Router "https://github.com/balancednetwork/balanced-java-contracts/tree/main/core-contracts/Router"
    click Savings "https://github.com/balancednetwork/balanced-java-contracts/tree/main/core-contracts/Savings"
    click StakedLP "https://github.com/balancednetwork/balanced-java-contracts/tree/main/core-contracts/StakedLP"
    click Staking "https://github.com/balancednetwork/balanced-java-contracts/tree/main/core-contracts/Staking"

    %% Click Events for Token Contracts
    click AssetToken "https://github.com/balancednetwork/balanced-java-contracts/tree/main/token-contracts/AssetToken"
    click BalancedDollar "https://github.com/balancednetwork/balanced-java-contracts/tree/main/token-contracts/BalancedDollar"
    click BalancedToken "https://github.com/balancednetwork/balanced-java-contracts/tree/main/token-contracts/BalancedToken"
    click Sicx "https://github.com/balancednetwork/balanced-java-contracts/tree/main/token-contracts/Sicx"
    click WorkerToken "https://github.com/balancednetwork/balanced-java-contracts/tree/main/token-contracts/WorkerToken"
    click bBaln "https://github.com/balancednetwork/balanced-java-contracts/tree/main/token-contracts/bBaln"

    %% Click Events for Client Libraries
    click SCOREClient "https://github.com/balancednetwork/balanced-java-contracts/tree/main/score-client"
    click SCORELibrary "https://github.com/balancednetwork/balanced-java-contracts/tree/main/score-lib"

    %% Click Events for Utility and Helper Contracts
    click Burner "https://github.com/balancednetwork/balanced-java-contracts/tree/main/util-contracts/Burner"
    click DummyOracle "https://github.com/balancednetwork/balanced-java-contracts/tree/main/util-contracts/DummyOracle"
    click OTCComponents "https://github.com/balancednetwork/balanced-java-contracts/tree/main/util-contracts/OTC"
    click StabilityModules "https://github.com/balancednetwork/balanced-java-contracts/tree/main/util-contracts/Stability"
    click Trickler "https://github.com/balancednetwork/balanced-java-contracts/tree/main/util-contracts/Trickler"
    click XCallManager "https://github.com/balancednetwork/balanced-java-contracts/tree/main/util-contracts/XCallManager"
    click XCallMock "https://github.com/balancednetwork/balanced-java-contracts/tree/main/util-contracts/XCallMock"

    %% Click Events for Build & Deployment Infrastructure
    click GradleBuild "https://github.com/balancednetwork/balanced-java-contracts/blob/main/build.gradle, settings.gradle, buildSrc, gradlew, gradlew.bat"
    click CICD "https://github.com/balancednetwork/balanced-java-contracts/tree/main/.github/workflows"
    click Docker "https://github.com/balancednetwork/balanced-java-contracts/blob/main/docker-compose.yml"
```
