lista-dao · phessophissy · Jan 20, 2026 · Jan 20, 2026
diff --git a/CONTRIBUTING.md 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
@@ -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 <path_to_script> --rpc-url <your_rpc_url> --private-key <your_private_key> --etherscan-api-key <bscscan-api-key> --broadcast --verify -vvv --via-ir
-# deploy SafeGuard Contract
-$ forge script script/safe/SafeGuard.s.sol:SafeGuardScript --rpc-url <your_rpc_url> --private-key <your_private_key> --etherscan-api-key <bscscan-api-key> --broadcast --verify -vvv
+forge script <path_to_script> --rpc-url <your_rpc_url> --private-key <your_private_key> --etherscan-api-key <api-key> --broadcast --verify -vvv --via-ir
 ```
 
-### Verify
+### Verify Contract
 
 ```shell
-$ forge verify-contract --rpc-url <your_rpc_url> --chain-id <chain-id> <address> <contract-name> --api-key <bscscan-api-key>
+forge verify-contract --rpc-url <your_rpc_url> --chain-id <chain-id> <address> <contract-name> --api-key <api-key>
 ```
 
-### Cast
+## Local Development
+
+### Start Local Node
 
 ```shell
-$ cast <subcommand>
-$ cast call <contract_address> <method_name> <method_args>
-$ cast send <contract_address> <method_name> <method_args> --private-key <private_key>
-# demo
-$ cast send <contract_address> "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 <contract_address> <method_name> <method_args>
+
+# Send a transaction
+cast send <contract_address> <method_name> <method_args> --private-key <private_key> --rpc-url <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