Contract Patterns

Contract Patterns Skill

This skill provides battle-tested patterns and examples for common smart contract functionality.

When to Use

Use this skill when:

• Implementing access control mechanisms
• Creating upgradeable contracts
• Building token contracts (ERC20, ERC721, ERC1155)
• Adding pausability to contracts
• Protecting against reentrancy attacks
• Following established security patterns

Pattern Categories

1. Access Control Patterns

See ./patterns/access-control.md for detailed documentation.

Common patterns:

• Ownable - Single owner with privileged access
• AccessControl - Role-based access control (RBAC)
• Multisig - Multiple signatures required for actions
• Timelock - Delayed execution for critical functions

When to use:

• Ownable: Simple contracts with single admin
• AccessControl: Complex permissions with multiple roles
• Multisig: High-value contracts requiring consensus
• Timelock: Governance and critical upgrades

2. Upgradeable Contract Patterns

See ./patterns/upgradeable-contracts.md for detailed documentation.

Common patterns:

• Transparent Proxy - Separate admin and user logic
• UUPS (Universal Upgradeable Proxy Standard) - Upgrade logic in implementation
• Beacon Proxy - Multiple proxies sharing same implementation
• Diamond Pattern (EIP-2535) - Multi-facet proxy for large contracts

When to use:

• Transparent: When admin and user separation is critical
• UUPS: Gas-efficient upgrades, upgrade logic in implementation
• Beacon: Deploying many instances of same logic
• Diamond: Large contracts exceeding size limits

3. Pausable Pattern

See ./patterns/pausable.md for detailed documentation.

Purpose: Emergency stop mechanism to pause contract functionality

When to use:

• Contracts handling user funds
• Contracts that may need emergency stops
• Contracts under active development/monitoring

Key features:

• Pause/unpause functionality
• Restricted to authorized roles
• Graceful degradation of functionality

4. Reentrancy Guard

See ./patterns/reentrancy-guard.md for detailed documentation.

Purpose: Prevent reentrancy attacks in functions that make external calls

When to use:

• Functions that transfer ETH
• Functions that call external contracts
• Functions that modify state after external calls

Implementation:

• Checks-Effects-Interactions pattern
• ReentrancyGuard modifier
• Mutex locks

5. Token Standards

See ./patterns/token-standards.md for detailed documentation.

ERC20 - Fungible tokens

• Standard interface for tokens like USDC, DAI
• Transfer, approve, transferFrom functionality
• See ./examples/ERC20-example.sol

ERC721 - Non-fungible tokens (NFTs)

• Unique tokens with individual ownership
• Metadata support
• See ./examples/ERC721-example.sol

ERC1155 - Multi-token standard

• Batch operations for fungible and non-fungible tokens
• Gas-efficient for multiple token types
• See ./examples/ERC1155-example.sol

Integration with Code Principles

These patterns follow the code-principles from the foundation plugin:

• DRY: Inherit from OpenZeppelin contracts instead of reimplementing
• SOLID: Single responsibility for each pattern/module
• KISS: Use simplest pattern that meets requirements
• Security First: Battle-tested implementations over custom code

Note: Solidity-specific security concerns take precedence over general software principles.

OpenZeppelin Contracts

Most patterns are best implemented using OpenZeppelin contracts:

# Install OpenZeppelin
forge install OpenZeppelin/openzeppelin-contracts
# or
npm install @openzeppelin/contracts

Available contracts:

• @openzeppelin/contracts/access/Ownable.sol
• @openzeppelin/contracts/access/AccessControl.sol
• @openzeppelin/contracts/security/Pausable.sol
• @openzeppelin/contracts/security/ReentrancyGuard.sol
• @openzeppelin/contracts/token/ERC20/ERC20.sol
• @openzeppelin/contracts/token/ERC721/ERC721.sol
• @openzeppelin/contracts/token/ERC1155/ERC1155.sol
• @openzeppelin/contracts/proxy/transparent/TransparentUpgradeableProxy.sol
• @openzeppelin/contracts/proxy/ERC1967/ERC1967Proxy.sol

Pattern Selection Guide

Best Practices

1. Prefer OpenZeppelin - Use audited implementations over custom code
2. Combine patterns carefully - Test interactions between patterns
3. Follow initialization patterns - Use proper constructor/initializer for upgradeable contracts
4. Test thoroughly - Each pattern has unique security considerations
5. Document deviations - If customizing standard patterns, document why
6. Keep it simple - Use simplest pattern that meets requirements
7. Security over gas optimization - Prioritize security when patterns conflict

Common Combinations

Pausable + AccessControl

contract MyContract is Pausable, AccessControl {
    bytes32 public constant PAUSER_ROLE = keccak256("PAUSER_ROLE");

    function pause() public onlyRole(PAUSER_ROLE) {
        _pause();
    }

    function unpause() public onlyRole(PAUSER_ROLE) {
        _unpause();
    }

    function criticalFunction() public whenNotPaused {
        // Function logic
    }
}

ERC20 + Ownable + Pausable

contract MyToken is ERC20, Ownable, Pausable {
    constructor() ERC20("MyToken", "MTK") Ownable(msg.sender) {}

    function pause() public onlyOwner {
        _pause();
    }

    function _update(address from, address to, uint256 value)
        internal
        override
        whenNotPaused
    {
        super._update(from, to, value);
    }
}

UUPS + AccessControl + ReentrancyGuard

contract MyUpgradeableContract is
    UUPSUpgradeable,
    AccessControlUpgradeable,
    ReentrancyGuardUpgradeable
{
    bytes32 public constant UPGRADER_ROLE = keccak256("UPGRADER_ROLE");

    function _authorizeUpgrade(address newImplementation)
        internal
        override
        onlyRole(UPGRADER_ROLE)
    {}
}

Anti-Patterns to Avoid

1. Custom access control - Use OpenZeppelin instead
2. Manual reentrancy protection - Use ReentrancyGuard
3. Incorrect upgrade patterns - Follow OpenZeppelin upgrade guides
4. Mixing storage layouts - Be careful with inheritance order
5. Skipping initialization - Always initialize upgradeable contracts
6. Ignoring token standards - Follow ERC specifications exactly

Pattern Files

This skill provides the following pattern documentation:

• ./patterns/upgradeable-contracts.md - Proxy patterns
• ./patterns/access-control.md - Permission patterns
• ./patterns/pausable.md - Emergency stop pattern
• ./patterns/reentrancy-guard.md - Reentrancy protection
• ./patterns/token-standards.md - ERC20/721/1155 standards

Example Contracts

This skill provides the following examples:

• ./examples/ERC20-example.sol - Fungible token implementation
• ./examples/ERC721-example.sol - NFT implementation
• ./examples/ERC1155-example.sol - Multi-token implementation
• ./examples/upgradeable-example.sol - UUPS upgradeable contract

Quick Reference

// Access Control
import "@openzeppelin/contracts/access/Ownable.sol";
import "@openzeppelin/contracts/access/AccessControl.sol";

// Security
import "@openzeppelin/contracts/security/Pausable.sol";
import "@openzeppelin/contracts/security/ReentrancyGuard.sol";

// Tokens
import "@openzeppelin/contracts/token/ERC20/ERC20.sol";
import "@openzeppelin/contracts/token/ERC721/ERC721.sol";
import "@openzeppelin/contracts/token/ERC1155/ERC1155.sol";

// Upgradeability
import "@openzeppelin/contracts/proxy/utils/UUPSUpgradeable.sol";
import "@openzeppelin/contracts/proxy/transparent/TransparentUpgradeableProxy.sol";

Remember: Always prefer battle-tested OpenZeppelin implementations over custom patterns. Security > Gas optimization > Code elegance.