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)

# 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

# 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

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

# Verify compilation
forge build

# Run tests
forge test

---

Dependency Management

Adding New Dependencies

Foundry Dependencies

# Install dependency
forge install <username>/<repository>

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

Git Submodules

# Add submodule
git submodule add <repository-url> lib/<dependency-name>

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

Updating Dependencies

Foundry Dependencies

# Update all dependencies
forge update

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

Git Submodules

# 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

# Remove dependency
rm -rf lib/<dependency-name>

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

Git Submodules

# 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

- name: Install dependencies
  run: |
    forge install --no-commit

Update Dependencies in CI

- name: Update dependencies
  run: |
    forge update

Git Submodules in CI

- 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

# Solution: Install OpenZeppelin
forge install OpenZeppelin/openzeppelin-contracts

Issue: Compilation Errors

# Solution: Check foundry.toml
# Ensure libs = ["lib"] is set

Issue: Git Submodule Issues

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

Issue: Dependency Version Conflicts

# Solution: Update dependencies
forge update

---

References

• Foundry Documentation
• OpenZeppelin Documentation
• Contract Inventory
• OpenZeppelin Usage Analysis
• OpenZeppelin Dependency Assessment

---

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