How balancednetwork/balanced-java-contracts works
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.