diamond-pattern

# EIP-2535 Diamond Pattern ## Overview The Diamond pattern splits a contract into multiple "facets" (logic modules) that share a single storage and address. Bypasses the 24KB contract size limit and enables surgical upgrades of individual functions. ## Architecture ``` User → Diamond Proxy ├── FacetA (functions a1, a2) ├── FacetB (functions b1, b2, b3) ├── DiamondCutFacet (add/replace/remove functions) └── DiamondLoupeFacet (introspection) ``` All facets share the Diamond's storage context via `delegatecall`. ## Diamond Contract ```solidity // SPDX-License-Identifier: MIT pragma solidity ^0.8.20; import {LibDiamond} from "./libraries/LibDiamond.sol"; contract Diamond { constructor(address contractOwner, address diamondCutFacet) payable { LibDiamond.setContractOwner(contractOwner); LibDiamond.FacetCut[] memory cut = new LibDiamond.FacetCut[](1); bytes4[] memory selectors = new bytes4[](1); selectors[0] = IDiamondCut.diamondCut.selector; cut[0] = LibDiamond.FacetCut({ facetAddress: diamondCutFacet, action: LibDiamond.FacetCutAction.Add, functionSelectors: selectors }); LibDiamond.diamondCut(cut, address(0), ""); } fallback() external payable { LibDiamond.DiamondStorage storage ds = LibDiamond.diamondStorage(); address facet = ds.selectorToFacetAndPosition[msg.sig].facetAddress; require(facet != address(0), "Diamond: Function does not exist"); assembly { calldatacopy(0, 0, calldatasize()) let result := delegatecall(gas(), facet, 0, calldatasize(), 0, 0) returndatacopy(0, 0, returndatasize()) switch result case 0 { revert(0, returndatasize()) } default { return(0, returndatasize()) } } } receive() external payable {} } ``` ## DiamondCut Interface ```solidity interface IDiamondCut { enum FacetCutAction { Add, Replace, Remove } struct FacetCut { address facetAddress; FacetCutAction action; bytes4[] functionSelectors; } event DiamondCut(FacetCut[] diamondCut, address init, bytes calldata); function diamondCut( FacetCut[] calldata diamondCut_, address init_, bytes calldata calldata_ ) external; } ``` ## Storage Patterns ### AppStorage (Recommended for Single Diamond) All state in one struct at a fixed position: ```solidity struct AppStorage { // Token state mapping(address => uint256) balances; mapping(address => mapping(address => uint256)) allowances; uint256 totalSupply; string name; string symbol; // Protocol state address treasury; uint256 feeRate; mapping(address => bool) operators; } library LibAppStorage { bytes32 constant APP_STORAGE_POSITION = keccak256("myprotocol.app.storage"); function appStorage() internal pure returns (AppStorage storage s) { bytes32 position = APP_STORAGE_POSITION; assembly { s.slot := position } } } // Usage in any facet: contract TokenFacet { function balanceOf(address account) external view returns (uint256) { return LibAppStorage.appStorage().balances[account]; } } ``` ### DiamondStorage (Per-Facet Namespaced Storage) Each facet gets its own storage namespace. Better for composable/reusable facets: ```solidity library LibTokenStorage { bytes32 constant STORAGE_POSITION = keccak256("myprotocol.token.storage"); struct TokenStorage { mapping(address => uint256) balances; uint256 totalSupply; } function tokenStorage() internal pure returns (TokenStorage storage s) { bytes32 position = STORAGE_POSITION; assembly { s.slot := position } } } library LibGovernanceStorage { bytes32 constant STORAGE_POSITION = keccak256("myprotocol.governance.storage"); struct GovernanceStorage { mapping(uint256 => Proposal) proposals; uint256 proposalCount; } function governanceStorage() internal pure returns (GovernanceStorage storage s) { bytes32 position = STORAGE_POSITION; assembly { s.slot := position } } } ``` ## Example Facet ```solidity contract ERC20Facet { using LibAppStorage for *; event Transfer(address indexed from, address indexed to, uint256 value); function transfer(address to, uint256 amount) external returns (bool) { AppStorage storage s = LibAppStorage.appStorage(); require(s.balances[msg.sender] >= amount, "Insufficient balance"); s.balances[msg.sender] -= amount; s.balances[to] += amount; emit Transfer(msg.sender, to, amount); return true; } function balanceOf(address account) external view returns (uint256) { return LibAppStorage.appStorage().balances[account]; } } ``` ## Diamond Loupe (Introspection) ```solidity interface IDiamondLoupe { struct Facet { address facetAddress; bytes4[] functionSelectors; } function facets() external view returns (Facet[] memory); function facetFunctionSelectors(address facet) external view returns (bytes4[] memory); function facetAddresses() external view returns (address[] memory); function facetAddress(bytes4 selector) external view returns (address); } ``` ## Upgrade Process ```solidity // Add new functions IDiamondCut.FacetCut[] memory cuts = new IDiamondCut.FacetCut[](1); bytes4[] memory selectors = new bytes4[](2); selectors[0] = NewFacet.newFunction1.selector; selectors[1] = NewFacet.newFunction2.selector; cuts[0] = IDiamondCut.FacetCut({ facetAddress: address(newFacet), action: IDiamondCut.FacetCutAction.Add, functionSelectors: selectors }); // With initialization callback diamond.diamondCut(cuts, address(initContract), abi.encodeCall(DiamondInit.init, ())); // Replace existing functions cuts[0].action = IDiamondCut.FacetCutAction.Replace; // Remove functions (set facetAddress to address(0)) cuts[0].facetAddress = address(0); cuts[0].action = IDiamondCut.FacetCutAction.Remove; ``` ## Diamond vs Other Patterns | Aspect | UUPS | Diamond | |--------|------|---------| | Max contract size | 24KB | Unlimited (split across facets) | | Upgrade granularity | Whole implementation | Per-function | | Shared storage | N/A | All facets share | | Complexity | Low | High | | Audit cost | Lower | Higher | | Introspection | No | DiamondLoupe | ## When to Use Diamond - Contract exceeds 24KB limit - Protocol needs modular upgrades (change one function without redeploying all) - Multiple teams work on different facets independently - Need EIP-165 introspection of all supported interfaces ## Security Checklist - [ ] Only owner/governance can call `diamondCut` - [ ] Storage layout is consistent across all facets (use AppStorage or DiamondStorage) - [ ] No storage collisions between facets (test with `forge inspect`) - [ ] Selector clashes are detected before `diamondCut` (no two facets share a selector) - [ ] DiamondLoupe is implemented for transparency - [ ] Initialization contract runs exactly once during upgrades - [ ] Test full upgrade cycle: add facet → verify → replace → verify → remove