AGENTS.md Guidelines: DeCleanup Network Contracts-EVM Repository

Aug 8, 2025 by Pedro Alvarez 65 views

<general_rules> When contributing to this repository, keep the following general rules in mind to ensure code quality and maintainability.

Custom Error Handling: This repository uses a specific custom error handling pattern: CONTRACT__ErrorType(parameters). Before introducing new error types, familiarize yourself with the existing pattern by reviewing the contract code, especially in /contracts/, and ensure consistency across the codebase. For example, examine DCUStorage.sol lines 17-26 for a clear illustration of this pattern. Using this format makes error messages consistent and easily identifiable.
Code Reusability: Before implementing new functions, always conduct a thorough search within the /contracts/ directory to ascertain if a similar function already exists. This practice fosters code reusability, reduces redundancy, and maintains a streamlined codebase. The aim is to build upon existing functionalities whenever feasible, enhancing both efficiency and clarity.
Gas Optimization: Given that these contracts will be deployed on the blockchain, gas optimization is paramount. Strive to write code that minimizes gas consumption. Techniques include: using efficient data structures, minimizing on-chain storage, and optimizing loop operations. Consider the gas costs associated with each operation, striving for the most efficient solutions. Gas optimization is not just about saving resources; it's about making the contracts more accessible and affordable to use.
Testing and Coverage: Comprehensive testing is crucial for the reliability of smart contracts. The repository enforces specific code coverage requirements. Before submitting code, ensure that it meets the coverage thresholds specified in the GitHub Actions workflow. Refer to the .github/workflows/test-coverage.yml file for the precise coverage metrics. Meeting these benchmarks ensures that your code has been rigorously tested, reducing the risk of bugs and vulnerabilities in production. This includes statement, branch, function, and line coverage.
Linting and Formatting: Before submitting a pull request, make sure your code adheres to the repository's linting and formatting rules. Use the provided scripts (e.g., linter and formatter scripts) to automatically check and fix any style issues. This helps maintain a consistent code style across the project, making it easier for everyone to read and understand. </general_rules> <repository_structure> The repository structure is designed to promote modularity and clarity. Understanding the high-level organization is key to navigating the codebase effectively.
Core Contracts: The foundation of the system lies in four main contracts: DCUStorage, DCURewardManager, DipNft, and DCUToken. Each contract serves a distinct purpose within the system's architecture. Understanding the role of each contract is vital before making any modifications. These contracts interact with each other, forming the core logic of the decentralized application. DCUStorage might manage data storage, DCURewardManager handles rewards distribution, DipNft represents Non-Fungible Tokens, and DCUToken likely deals with fungible tokens. Familiarize yourself with their individual responsibilities and interdependencies.
/contracts/interfaces/: This directory houses the interfaces for the contracts. Interfaces define the functions that a contract must implement, providing a clear contract for interaction. When interacting with contracts, understanding their interfaces is essential. These interfaces provide a high-level overview of the contracts' capabilities and how they can be used.
/contracts/tokens/: This directory contains the implementations for the tokens used within the system. This separation helps organize the codebase, especially when dealing with different token standards or custom token logic. By keeping token-related code in a dedicated directory, it becomes easier to manage and maintain the token-related functionalities of the project.
/test/helpers/: This directory contains utility functions and helper scripts used in the testing suite. These helpers abstract common testing logic, making tests more readable and maintainable. Before writing new tests, explore the existing helpers to see if they can be leveraged. These helpers can significantly simplify the testing process and ensure consistency across tests. One notable file is /test/helpers/errorMessages.ts, which provides custom error matching functionality, which is essential for verifying that contracts throw the correct errors under specific conditions.
/docs/: This directory is intended for comprehensive documentation related to the project. Clear and up-to-date documentation is essential for any project, particularly in the blockchain space. Refer to the documentation for high-level overviews, architectural diagrams, and detailed explanations of the system's components.
/scripts/: This directory contains scripts for various tasks, including deployment and other utility operations. These scripts are essential for automating repetitive tasks and streamlining the development workflow. Before performing any deployment or maintenance tasks, review the scripts available in this directory. </repository_structure> <dependencies_and_installation> Setting up the development environment correctly is crucial for contributing effectively. This section provides a high-level overview of the dependencies and installation process.
Package Manager: This repository uses npm as its primary package manager. Ensure that you have Node.js and npm installed on your system. npm is used to manage project dependencies, run scripts, and build the project. Before installing dependencies, make sure you have the latest version of npm installed.
Dependency Installation: When installing dependencies, use the --legacy-peer-deps flag. This flag helps resolve peer dependency conflicts that can arise due to the complex dependency tree in blockchain projects. You can find an example of this flag being used in the .github/workflows/test-coverage.yml file, specifically on line 29. Using this flag ensures compatibility between different packages and avoids potential runtime issues.
Hardhat: This project leverages Hardhat as its development framework. Hardhat provides a suite of tools for compiling, deploying, testing, and debugging smart contracts. Familiarize yourself with Hardhat's configuration and command-line interface. Hardhat simplifies the development process by providing a local development network, testing environment, and deployment tools.
OpenZeppelin Contracts: The repository utilizes OpenZeppelin Contracts as its base library. OpenZeppelin Contracts provides secure and well-tested implementations of common smart contract patterns and standards, such as ERC20 and ERC721. Before implementing custom contract logic, check if OpenZeppelin Contracts offers a suitable implementation. Leveraging OpenZeppelin Contracts reduces the risk of vulnerabilities and promotes code reusability. </dependencies_and_installation> <testing_instructions> Robust testing is essential for smart contract development. This section outlines the testing guidelines for this repository.
Testing Framework: The primary testing framework used in this repository is Hardhat. Hardhat provides a flexible and efficient environment for writing and running tests. Familiarize yourself with Hardhat's testing APIs and best practices. Hardhat's testing environment allows for rapid iteration and provides detailed feedback on test failures.
Test Coverage: The repository enforces specific code coverage requirements, as detailed in the GitHub Actions workflow file (.github/workflows/test-coverage.yml). Aim for high test coverage to ensure that all critical parts of the code are thoroughly tested. The current coverage requirements are 85% for statements, 60% for branches, 80% for functions, and 85% for lines. High coverage indicates that a large portion of the codebase is exercised by the tests, reducing the likelihood of undiscovered bugs.
Custom Error Matching: The /test/helpers/errorMessages.ts file provides custom error matching helpers. These helpers are used to verify that contracts throw the correct errors under specific conditions, especially those following the custom error pattern CONTRACT__ErrorType(parameters). Use these helpers to ensure that your tests accurately check for expected error conditions. Properly matching errors is crucial for ensuring the contracts behave as intended under various scenarios.
What to Test: Focus on testing the core logic of your smart contracts, including state transitions, access controls, and error conditions. Write unit tests for individual functions and integration tests for interactions between contracts. Consider edge cases and potential vulnerabilities in your tests. Thorough testing helps to identify and prevent bugs that could lead to security issues or unexpected behavior in production.
Running Tests: Refer to the package.json file for the commands to run tests. Typically, you will find scripts for running unit tests, integration tests, and coverage reports. Use these scripts to streamline the testing process. For example, you might find commands like npm run test, npm run test:integration, and npm run coverage. Running these scripts will execute the tests and generate reports, helping you verify the correctness of your code. </testing_instructions> <pull_request_formatting> </pull_request_formatting>