smom-dbis-138/docs/guides/DEPENDENCIES.md

# Project Dependencies Guide

## Overview

This document provides a comprehensive guide for managing project dependencies, particularly OpenZeppelin contracts.

## Current Dependency Status

### ✅ Independent Contracts (No External Dependencies)
- WETH.sol
- WETH10.sol
- CCIPWETH9Bridge.sol
- CCIPWETH10Bridge.sol
- Multicall.sol
- CREATE2Factory.sol
- Aggregator.sol
- Proxy.sol
- IRouterClient.sol
- CCIPMessageValidator.sol
- CCIPReceiver.sol

### ⚠️ Contracts Requiring OpenZeppelin
- CCIPSender.sol
- CCIPRouter.sol
- CCIPRouterOptimized.sol
- MultiSig.sol
- Voting.sol

---

## OpenZeppelin Installation

### Prerequisites
- Git repository initialized
- Foundry installed
- `foundry.toml` configured with `libs = ["lib"]`

### Installation Steps

#### Option 1: Install via Foundry (Recommended)
```bash
# Initialize git repository (if not already)
git init

# Install OpenZeppelin
forge install OpenZeppelin/openzeppelin-contracts

# Verify installation
ls -la lib/openzeppelin-contracts

# Test compilation
forge build
```

#### Option 2: Install via Git Submodule
```bash
# Initialize git repository
git init

# Add OpenZeppelin as submodule
git submodule add https://github.com/OpenZeppelin/openzeppelin-contracts lib/openzeppelin-contracts

# Initialize submodules
git submodule update --init --recursive

# Test compilation
forge build
```

### Verification
```bash
# Check if OpenZeppelin is installed
ls lib/openzeppelin-contracts

# Verify compilation
forge build

# Run tests
forge test
```

---

## Dependency Management

### Adding New Dependencies

#### Foundry Dependencies
```bash
# Install dependency
forge install <username>/<repository>

# Update foundry.toml if needed
# libs = ["lib"]
```

#### Git Submodules
```bash
# Add submodule
git submodule add <repository-url> lib/<dependency-name>

# Initialize submodules
git submodule update --init --recursive
```

### Updating Dependencies

#### Foundry Dependencies
```bash
# Update all dependencies
forge update

# Update specific dependency
forge update lib/<dependency-name>
```

#### Git Submodules
```bash
# Update submodule
cd lib/<dependency-name>
git pull origin main
cd ../..
git add lib/<dependency-name>
git commit -m "Update dependency"
```

### Removing Dependencies

#### Foundry Dependencies
```bash
# Remove dependency
rm -rf lib/<dependency-name>

# Update .gitmodules if needed
git rm lib/<dependency-name>
```

#### Git Submodules
```bash
# Remove submodule
git submodule deinit lib/<dependency-name>
git rm lib/<dependency-name>
rm -rf .git/modules/lib/<dependency-name>
```

---

## Dependency Guidelines

### When to Use OpenZeppelin

#### Use OpenZeppelin When:
- ✅ Battle-tested functionality is needed
- ✅ Complex security features are required
- ✅ Standard patterns are needed
- ✅ Time is limited and security is critical

#### Don't Use OpenZeppelin When:
- ❌ Simple functionality can be implemented easily
- ❌ External dependencies should be minimized
- ❌ Gas optimization is critical
- ❌ Code size reduction is important

### When to Use Custom Implementation

#### Use Custom Implementation When:
- ✅ Simple functionality (like admin pattern)
- ✅ Gas optimization is critical
- ✅ Code size reduction is important
- ✅ No external dependencies desired

#### Don't Use Custom Implementation When:
- ❌ Complex security features are needed
- ❌ Battle-tested implementation is required
- ❌ Time is limited

---

## Migration Strategy

### Phase 1: Install OpenZeppelin (Quick Fix)
1. Initialize git repository
2. Install OpenZeppelin
3. Verify compilation
4. Run tests
5. Deploy contracts

### Phase 2: Refactor Contracts (Long-term)
1. Refactor CCIP contracts (Low effort)
2. Refactor governance contracts (Medium effort)
3. Update tests
4. Verify security
5. Update documentation

### Phase 3: Remove OpenZeppelin (Final)
1. Remove OpenZeppelin dependency
2. Update documentation
3. Update CI/CD pipelines
4. Verify all tests pass

---

## CI/CD Integration

### GitHub Actions

#### Install Dependencies in CI
```yaml
- name: Install dependencies
  run: |
    forge install --no-commit
```

#### Update Dependencies in CI
```yaml
- name: Update dependencies
  run: |
    forge update
```

### Git Submodules in CI
```yaml
- name: Checkout with submodules
  uses: actions/checkout@v4
  with:
    submodules: recursive
```

---

## Best Practices

### Dependency Management
1. **Minimize Dependencies**: Only use when necessary
2. **Version Pinning**: Pin dependency versions
3. **Regular Updates**: Update dependencies regularly
4. **Security Audits**: Audit dependencies for security issues
5. **Documentation**: Document all dependencies

### Code Organization
1. **Independent Contracts**: Keep contracts independent when possible
2. **Minimal Interfaces**: Use minimal interfaces instead of full libraries
3. **Custom Patterns**: Use custom patterns for simple functionality
4. **Gas Optimization**: Consider gas costs when choosing dependencies

### Testing
1. **Test Dependencies**: Test all dependencies
2. **Mock Dependencies**: Mock dependencies in tests
3. **Integration Tests**: Test integration with dependencies
4. **Security Tests**: Test security of dependencies

---

## Troubleshooting

### Common Issues

#### Issue: OpenZeppelin Not Found
```bash
# Solution: Install OpenZeppelin
forge install OpenZeppelin/openzeppelin-contracts
```

#### Issue: Compilation Errors
```bash
# Solution: Check foundry.toml
# Ensure libs = ["lib"] is set
```

#### Issue: Git Submodule Issues
```bash
# Solution: Initialize submodules
git submodule update --init --recursive
```

#### Issue: Dependency Version Conflicts
```bash
# Solution: Update dependencies
forge update
```

---

## References

- [Foundry Documentation](https://book.getfoundry.sh/)
- [OpenZeppelin Documentation](https://docs.openzeppelin.com/)
- [Contract Inventory](./CONTRACT_INVENTORY.md)
- [OpenZeppelin Usage Analysis](./OPENZEPPELIN_USAGE_ANALYSIS.md)
- [OpenZeppelin Dependency Assessment](./OPENZEPPELIN_DEPENDENCY_ASSESSMENT.md)

---

## Summary

- **Independent Contracts**: 14 (74%)
- **Contracts Requiring OpenZeppelin**: 5 (26%)
- **Installation**: Simple (forge install)
- **Refactoring**: Possible (11-22 hours)
- **Recommendation**: Install OpenZeppelin short-term, refactor long-term