smom-dbis-138/docs/operations/status-reports/DECISION_TREE.md

Decision Tree: OpenZeppelin vs Custom Implementation

Overview

This decision tree helps you choose between OpenZeppelin and custom implementations when creating new contracts.

Decision Tree

Start
  |
  ├─ Do you need token operations?
  |   |
  |   ├─ Yes → Standard ERC20 tokens?
  |   |   |
  |   |   ├─ Yes → Use Minimal IERC20 Interface ✅
  |   |   |   (Reference: CCIPWETH9Bridge.sol)
  |   |   |
  |   |   └─ No → Non-standard tokens?
  |   |       |
  |   |       ├─ Yes → Use SafeERC20 (OpenZeppelin) ⚠️
  |   |       |
  |   |       └─ No → Use Minimal IERC20 Interface ✅
  |   |
  |   └─ No → Continue
  |
  ├─ Do you need access control?
  |   |
  |   ├─ Yes → Simple admin pattern?
  |   |   |
  |   |   ├─ Yes → Use Custom Admin Pattern ✅
  |   |   |   (Reference: CCIPWETH9Bridge.sol)
  |   |   |
  |   |   └─ No → Complex access control?
  |   |       |
  |   |       ├─ Yes → Use OpenZeppelin Access Control ⚠️
  |   |       |
  |   |       └─ No → Use Custom Admin Pattern ✅
  |   |
  |   └─ No → Continue
  |
  ├─ Do you need security features?
  |   |
  |   ├─ Yes → Battle-tested needed?
  |   |   |
  |   |   ├─ Yes → Use OpenZeppelin ⚠️
  |   |   |
  |   |   └─ No → Use Custom Implementation ✅
  |   |
  |   └─ No → Continue
  |
  ├─ Gas optimization critical?
  |   |
  |   ├─ Yes → Use Custom Implementation ✅
  |   |
  |   └─ No → Continue
  |
  ├─ Code size critical?
  |   |
  |   ├─ Yes → Use Custom Implementation ✅
  |   |
  |   └─ No → Continue
  |
  └─ Default: Use Custom Implementation ✅

---

Decision Matrix

Token Operations

Scenario	Recommendation	Reason
Standard ERC20 tokens	✅ Minimal IERC20 Interface	No external dependency, smaller code
Non-standard ERC20 tokens	⚠️ SafeERC20 (OpenZeppelin)	Handles non-standard tokens
Unknown token types	⚠️ SafeERC20 (OpenZeppelin)	Safety first
Known standard tokens	✅ Minimal IERC20 Interface	Optimized for known tokens

Access Control

Scenario	Recommendation	Reason
Simple admin pattern	✅ Custom Admin Pattern	No external dependency, simpler
Complex access control	⚠️ OpenZeppelin Access Control	Battle-tested, complex features
Multi-role access	⚠️ OpenZeppelin Access Control	Complex features needed
Single admin	✅ Custom Admin Pattern	Simple, no dependency

Security Features

Scenario	Recommendation	Reason
Battle-tested needed	⚠️ OpenZeppelin	Proven security
Simple security	✅ Custom Implementation	No external dependency
Complex security	⚠️ OpenZeppelin	Complex features needed
Standard patterns	✅ Custom Implementation	Simple, maintainable

Gas Optimization

Scenario	Recommendation	Reason
Gas optimization critical	✅ Custom Implementation	Lower gas costs
Gas not critical	Either	Choose based on other factors
High-frequency operations	✅ Custom Implementation	Lower gas costs
Low-frequency operations	Either	Choose based on other factors

Code Size

Scenario	Recommendation	Reason
Code size critical	✅ Custom Implementation	Smaller code size
Code size not critical	Either	Choose based on other factors
Contract size limits	✅ Custom Implementation	Smaller code size
No size constraints	Either	Choose based on other factors

---

Use Cases

Use Custom Implementation When:

1. ✅ Standard ERC20 tokens only

   • Use minimal IERC20 interface
   • Reference: CCIPWETH9Bridge.sol

2. ✅ Simple admin pattern

   • Use custom admin pattern
   • Reference: CCIPWETH9Bridge.sol

3. ✅ Gas optimization critical

   • Use custom implementation
   • Lower gas costs

4. ✅ Code size critical

   • Use custom implementation
   • Smaller code size

5. ✅ No external dependencies desired

   • Use custom implementation
   • Better maintainability

Use OpenZeppelin When:

1. ⚠️ Non-standard ERC20 tokens

   • Use SafeERC20
   • Handles non-standard tokens

2. ⚠️ Complex access control

   • Use OpenZeppelin Access Control
   • Complex features needed

3. ⚠️ Battle-tested security needed

   • Use OpenZeppelin
   • Proven security

4. ⚠️ Time constraints

   • Use OpenZeppelin
   • Faster development

5. ⚠️ Standard patterns needed

   • Use OpenZeppelin
   • Industry standard

---

Examples

Example 1: Token Bridge

Scenario: Cross-chain token bridge with standard ERC20 tokens

Decision: ✅ Custom Implementation

• Use minimal IERC20 interface
• Use custom admin pattern
• No external dependencies

Reference: contracts/ccip/CCIPWETH9Bridge.sol

---

Example 2: Multi-Sig Wallet

Scenario: Multi-signature wallet with complex access control

Decision: ⚠️ OpenZeppelin (or Gnosis Safe)

• Complex access control needed
• Battle-tested security required
• Consider Gnosis Safe for production

Reference: contracts/governance/MultiSig.sol

---

Example 3: Token Staking

Scenario: Token staking with standard ERC20 tokens

Decision: ✅ Custom Implementation

• Use minimal IERC20 interface
• Use custom admin pattern
• No external dependencies

---

Example 4: Voting Contract

Scenario: Simple voting contract with admin functions

Decision: ✅ Custom Implementation

• Use custom admin pattern
• No external dependencies
• Simple access control

Reference: contracts/governance/Voting.sol (currently uses Ownable, can be refactored)

---

Checklist

Before Choosing Custom Implementation

• Standard ERC20 tokens only?
• Simple access control sufficient?
• Gas optimization important?
• Code size important?
• No external dependencies desired?
• Time available for custom implementation?

Before Choosing OpenZeppelin

• Non-standard tokens needed?
• Complex access control needed?
• Battle-tested security required?
• Time constraints?
• Standard patterns needed?
• External dependency acceptable?

---

Recommendations

For New Contracts

1. Start with Custom Implementation

   • Use minimal interfaces
   • Use custom admin pattern
   • No external dependencies

2. Use OpenZeppelin Only When Needed

   • Non-standard tokens
   • Complex access control
   • Battle-tested security required

3. Follow Patterns from New WETH Contracts

   • CCIPWETH9Bridge.sol
   • CCIPWETH10Bridge.sol
   • WETH10.sol

For Existing Contracts

1. Refactor When Possible

   • Replace SafeERC20 with standard ERC20 calls
   • Replace Ownable with custom admin pattern
   • Reduce external dependencies

2. Keep OpenZeppelin When Needed

   • Non-standard tokens
   • Complex access control
   • Battle-tested security required

---

References

Contract Examples

• contracts/ccip/CCIPWETH9Bridge.sol - Custom implementation ✅
• contracts/ccip/CCIPWETH10Bridge.sol - Custom implementation ✅
• contracts/tokens/WETH10.sol - Custom implementation ✅
• contracts/ccip/CCIPSender.sol - Uses OpenZeppelin ⚠️
• contracts/governance/MultiSig.sol - Uses OpenZeppelin ⚠️

Documentation

• Migration Guide
• Contract Inventory
• OpenZeppelin Usage Analysis
• Dependencies Guide

---

Summary

Default Recommendation: ✅ Custom Implementation

• Use minimal interfaces
• Use custom admin pattern
• No external dependencies
• Better maintainability
• Lower gas costs
• Smaller code size

Use OpenZeppelin When: ⚠️

• Non-standard tokens needed
• Complex access control needed
• Battle-tested security required
• Time constraints

---

Questions?

For questions about choosing between OpenZeppelin and custom implementations, refer to:

• Migration Guide
• Contract Inventory
• OpenZeppelin Usage Analysis