diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..be803b65 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,201 @@ +# Contributing to Moolah + +Thank you for your interest in contributing to Moolah! This document provides guidelines and instructions for contributing. + +## Table of Contents + +- [Code of Conduct](#code-of-conduct) +- [Getting Started](#getting-started) +- [Development Workflow](#development-workflow) +- [Submitting Changes](#submitting-changes) +- [Style Guidelines](#style-guidelines) +- [Testing](#testing) +- [Security](#security) + +## Code of Conduct + +Please be respectful and constructive in all interactions. We are committed to providing a welcoming and inclusive environment for all contributors. + +## Getting Started + +### Prerequisites + +- [Foundry](https://book.getfoundry.sh/getting-started/installation) - Solidity development framework +- [Node.js](https://nodejs.org/) v18 or higher +- [Yarn](https://yarnpkg.com/) - Package manager +- [Git](https://git-scm.com/) + +### Setup + +1. Fork the repository on GitHub +2. Clone your fork: + ```bash + git clone --recursive git@github.com:YOUR_USERNAME/moolah.git + cd moolah + ``` +3. Add the upstream repository: + ```bash + git remote add upstream git@github.com:lista-dao/moolah.git + ``` +4. Install dependencies: + ```bash + yarn install + ``` +5. Build the project: + ```bash + forge build + ``` + +## Development Workflow + +### Creating a Branch + +Create a descriptive branch name for your changes: + +```bash +git checkout -b feature/your-feature-name +# or +git checkout -b fix/issue-description +``` + +### Making Changes + +1. Make your changes in the appropriate files +2. Write or update tests as needed +3. Ensure all tests pass +4. Format your code + +### Running Tests + +```bash +# Run all tests +forge test + +# Run with verbosity +forge test -vvv + +# Run specific test +forge test --match-contract ContractName --match-test testFunctionName -vvv + +# Run with gas reporting +forge test --gas-report +``` + +### Formatting + +Before committing, ensure your code is properly formatted: + +```bash +forge fmt +``` + +## Submitting Changes + +### Commit Messages + +We follow the [Conventional Commits](https://www.conventionalcommits.org/) specification: + +- `feat:` - New features +- `fix:` - Bug fixes +- `docs:` - Documentation changes +- `style:` - Code style changes (formatting, etc.) +- `refactor:` - Code refactoring without feature changes +- `test:` - Adding or updating tests +- `chore:` - Maintenance tasks + +Examples: +``` +feat: add new liquidation callback +fix: correct interest rate calculation +docs: update README with deployment instructions +test: add unit tests for MoolahVault +``` + +### Pull Request Process + +1. Update your branch with the latest upstream changes: + ```bash + git fetch upstream + git rebase upstream/master + ``` + +2. Push your changes to your fork: + ```bash + git push origin your-branch-name + ``` + +3. Open a Pull Request on GitHub against the `master` branch + +4. In your PR description: + - Describe what changes you made and why + - Reference any related issues (e.g., "Fixes #123") + - Include any relevant testing information + - Add screenshots if applicable (for UI changes) + +5. Wait for review and address any feedback + +### PR Requirements + +- All tests must pass +- Code must be formatted with `forge fmt` +- New features should include tests +- Documentation should be updated if needed + +## Style Guidelines + +### Solidity + +- Use Solidity version `0.8.28` +- Follow the project's existing code style +- Use meaningful variable and function names +- Add NatSpec comments for public/external functions +- Keep functions focused and concise + +### Documentation + +- Use clear, concise language +- Update relevant documentation when making changes +- Include code examples where helpful + +## Testing + +### Writing Tests + +- Place test files in the `test/` directory +- Name test files with `.t.sol` suffix +- Use descriptive test function names starting with `test` +- Test both success and failure cases +- Use fuzzing for numerical inputs where appropriate + +### Test Coverage + +Aim for comprehensive test coverage, especially for: +- Core protocol functions +- Edge cases +- Error conditions +- Access control + +## Security + +### Reporting Security Issues + +**Do not report security vulnerabilities through public GitHub issues.** + +Please report security issues directly to the Lista DAO team through responsible disclosure. See the security policy for details. + +### Security Considerations + +When contributing: +- Be mindful of reentrancy vulnerabilities +- Check for integer overflow/underflow +- Validate all inputs +- Follow the checks-effects-interactions pattern +- Consider gas optimization without sacrificing security + +## Questions? + +If you have questions about contributing, feel free to: +- Open a GitHub issue for discussion +- Reach out to the Lista DAO team + +Thank you for contributing to Moolah! 🎉 diff --git a/README.md b/README.md index 315b0301..6250c9b6 100644 --- a/README.md +++ b/README.md @@ -1,98 +1,147 @@ -## Foundry +# Moolah -**Foundry is a blazing fast, portable and modular toolkit for Ethereum application development written in Rust.** +[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) +[![Solidity](https://img.shields.io/badge/Solidity-0.8.28-blue)](https://soliditylang.org/) +[![Foundry](https://img.shields.io/badge/Built%20with-Foundry-FFDB1C)](https://book.getfoundry.sh/) -Foundry consists of: +**Moolah** is a decentralized lending protocol developed by [Lista DAO](https://lista.org). Built on top of [Morpho Blue](https://morpho.org), it enables permissionless lending and borrowing with isolated markets, customizable risk parameters, and efficient capital utilization. -- **Forge**: Ethereum testing framework (like Truffle, Hardhat and DappTools). -- **Cast**: Swiss army knife for interacting with EVM smart contracts, sending transactions and getting chain data. -- **Anvil**: Local Ethereum node, akin to Ganache, Hardhat Network. -- **Chisel**: Fast, utilitarian, and verbose solidity REPL. +## Features + +- **Isolated Lending Markets** - Each market has its own collateral and loan asset pair with independent risk parameters +- **Customizable LLTVs** - Flexible Loan-to-Value ratios for different asset pairs +- **Vault System** - ERC4626-compliant vaults for passive lending strategies +- **Multi-chain Support** - Deployed on BNB Chain and Ethereum +- **Interest Rate Models** - Configurable interest rate strategies including fixed-rate options +- **Smart Collateral** - Advanced collateral management with provider integrations +- **Liquidation System** - Efficient liquidation mechanism with customizable parameters + +## Architecture + +``` +src/ +├── moolah/ # Core lending protocol +├── moolah-vault/ # ERC4626 vault implementations +├── interest-rate-model/ # Interest rate strategies +├── liquidator/ # Liquidation logic +├── oracle/ # Price oracle integrations +├── provider/ # Collateral provider integrations +├── vault-allocator/ # Vault allocation strategies +├── broker/ # Broker integrations +├── revenue/ # Fee distribution +└── timelock/ # Governance timelock +``` + +## Security + +Moolah has been audited by multiple security firms. All audit reports are available in the [`docs/audits/`](docs/audits/) directory: + +- **Blocksec** - Core lending protocol audit +- **Bailsec** - Multiple audits covering core protocol, providers, and smart collateral +- **OpenZeppelin** - Smart collateral audit +- **Cantina** - Fixed term and rate audit ## Documentation -https://book.getfoundry.sh/ +- [Foundry Book](https://book.getfoundry.sh/) - Development framework documentation +- [Lista DAO](https://lista.org) - Protocol documentation + +## Getting Started -## Usage +### Prerequisites + +- [Foundry](https://book.getfoundry.sh/getting-started/installation) +- [Node.js](https://nodejs.org/) (v18+) +- [Yarn](https://yarnpkg.com/) ### Clone + ```shell -# clone the repository +# Clone the repository with submodules git clone --recursive git@github.com:lista-dao/moolah.git -# update submodules if cloned without --recursive +# If cloned without --recursive, update submodules git submodule update --init --recursive ``` -### Install +### Install Dependencies + ```shell yarn install ``` - ### Build ```shell -$ forge build +forge build ``` ### Test ```shell -$ forge test -``` -#### test a specific contract -```shell +# Run all tests +forge test + +# Run specific test contract forge test --match-contract SafeGuardTest -vvv + +# Run specific test function forge test --match-contract BuybackTest --match-test "testExecutorOfNoneOwner" -vvv ``` ### Format ```shell -$ forge fmt +forge fmt ``` ### Gas Snapshots ```shell -$ forge snapshot +forge snapshot ``` -### Anvil - -```shell -$ anvil -``` +## Deployment ### Deploy ```shell -$ forge script --rpc-url --private-key --etherscan-api-key --broadcast --verify -vvv --via-ir -# deploy SafeGuard Contract -$ forge script script/safe/SafeGuard.s.sol:SafeGuardScript --rpc-url --private-key --etherscan-api-key --broadcast --verify -vvv +forge script --rpc-url --private-key --etherscan-api-key --broadcast --verify -vvv --via-ir ``` -### Verify +### Verify Contract ```shell -$ forge verify-contract --rpc-url --chain-id
--api-key +forge verify-contract --rpc-url --chain-id
--api-key ``` -### Cast +## Local Development + +### Start Local Node ```shell -$ cast -$ cast call -$ cast send --private-key -# demo -$ cast send "addExecutor(address)" <...parameters> --rpc-url $RPC --private-key $PRIVATE_KEY +anvil ``` -### Help +### Interact with Contracts ```shell -$ forge --help -$ anvil --help -$ cast --help +# Call a view function +cast call + +# Send a transaction +cast send --private-key --rpc-url ``` + +## Contributing + +Contributions are welcome! Please see our [Contributing Guidelines](CONTRIBUTING.md) for details. + +## License + +This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. + +## Acknowledgements + +- [Morpho Labs](https://morpho.org) - Core lending protocol design inspiration +- [OpenZeppelin](https://openzeppelin.com) - Secure smart contract libraries