How aarna-ai/atv-ethereum works
Project type and purpose
• This is an Ethereum smart‐contract project using Hardhat (and Truffle for coverage) focused on testing a modular DeFi protocol (“AFi”) and its integration with on‐chain services (like 1inch, oracles).
• Purpose: define, compile, deploy, and test a set of core contracts + mocks, run them against a mainnet fork, measure coverage, and validate behaviors.
File structure
• Top‐level:
• contracts/ – main Solidity source
• contracts/mockcontracts/ – supporting mock contracts for isolated/unit tests
• test/ – JS/TS test suites organized by module (Migration, OneInch, core AFi modules)
• hardhat.config.js & truffle-config.js – compilation/deployment settings
• utils/ – helper scripts/constants for tests
• coverage/ – generated HTML/JSON reports
• Inside contracts/:
• /Interfaces – external protocol & internal interface definitions (e.g., IFactory, IRouter)
• /Libraries – shared on‐chain libraries (e.g., SafeMath, Address)
• /mockcontracts – mirror of structure under contracts/, containing mock implementations of Interfaces & Libraries for testing
• Configuration files indicate use of Hardhat (forking mainnet) and solidity‐coverage.
Key README insights
• Mainnet fork via Infura/Blast endpoint
• Hardhat commands to compile, test, and generate coverage
• Emphasis on keeping the node running while coverage commands execute
Main components
a. On-Chain Contracts Layer
• Core AFi Contracts
• AFiFactory
• AFiManager
• AFiBase
• AFiExchangeMock / AFiOracle
• AFiPassiveRebal / time-delay modules
• Utility contracts (Vaults, Token interfaces)
• Interfaces & Libraries
• External (IERC20, IOneInchRouter)
• Internal (IManager, ILibrary functions)
• MockContracts (under contracts/mockcontracts)
• Mocks for oracles, exchange, ERC20 tokens
b. Off-Chain Tooling Layer
• Hardhat Node (mainnet fork)
• Test runner (Mocha/Chai scripts in test/)
• Coverage tools (solidity-coverage, Truffle coverage plugin)
• Utils (constants, payload builders, USDT mainnet address)
c. External Services
• Ethereum Mainnet (via Infura/Blast RPC)
• 1Inch API/Router (for swap integration tests)
• Oracle price feeds
Relationships & Interactions
• Deployment flow: Hardhat → deploy core contracts → link libraries → instantiate factory/manager
• Core contracts interact: Factory creates Base vaults; Manager triggers rebalances via Exchange/Oracle
• Off-chain tests invoke contract functions through Hardhat, simulate time (ForwardTimeScript), measure outcomes
• Mock contracts emulate oracles/ERC20 to isolate unit tests
• Coverage plugin instruments contracts under test, collects execution data
Architectural patterns & design principles
• Modular design: Factory/Manager/Base separation
• Pluggable modules: Oracle, Exchange, Rebalance logic loaded at runtime
• Use of Interfaces and Libraries to decouple implementation
• Mocks to achieve test isolation
• Forked environment to blend unit tests with mainnet data
Hierarchy inside contracts/
1. Interfaces (Interfaces/)
2. Libraries (Libraries/)
3. Core contracts & modules
• Next to it, a mirrored “contracts/mockcontracts/” container with its own Interfaces/ and Libraries/ subfolders and mock modules
• Mock Interface/Library to its real counterpart to show one-to-one substitution in tests
Detail but avoid over-fragmentation
• Related contracts where logical (e.g., all Rebalance modules in one cluster)
• Still show each contract’s name for traceability back to the file tree
• Essential flows: deployment, function calls, test invocation, coverage instrumentation