skillbase/solidity-diamond-pattern

## Diamond architecture overview

A Diamond consists of:

- **Diamond proxy** — single entry point; holds all state; delegates calls to facets via `fallback()`

- **Facets** — stateless logic contracts; each exposes a set of function selectors

- **DiamondCutFacet** — upgrade mechanism; adds, replaces, or removes function-to-facet mappings

- **DiamondLoupeFacet** — introspection; queries which facets/selectors exist

- **Diamond storage** — each facet uses its own storage struct at a unique, collision-free slot

## Diamond storage pattern

Every facet needing persistent state uses diamond storage. Each storage struct lives at a unique `bytes32` slot derived from a namespace string.

```solidity

library LibVaultStorage {

    // keccak256("diamond.storage.vault")

    bytes32 constant STORAGE_SLOT = 0x...;

    struct VaultStorage {

        mapping(address => uint256) balances;

        uint256 totalDeposits;

        bool paused;

    }

    function layout() internal pure returns (VaultStorage storage s) {

        bytes32 slot = STORAGE_SLOT;

        assembly { s.slot := slot }

    }

}

```

Rules:

1. **One library per storage namespace** — name it `Lib<Feature>Storage`

2. **Precompute the slot hash** — use `keccak256("diamond.storage.<namespace>")` and paste the result as a constant. Include the plain-text string in a comment

3. **Append-only structs** — when upgrading, only add new fields to the END. Reordering or removing fields corrupts storage

4. **Unique namespace per feature domain** — two facets can share the same storage library if they operate on the same domain

## Facet design

```solidity

contract VaultFacet {

    function deposit(uint256 amount) external {

        LibVaultStorage.VaultStorage storage s = LibVaultStorage.layout();

        if (amount == 0) revert ZeroAmount();

        s.balances[msg.sender] += amount;

        s.totalDeposits += amount;

        // ... token transfer

    }

    function balanceOf(address account) external view returns (uint256) {

        return LibVaultStorage.layout().balances[account];

    }

}

```

Rules:

1. **Facets are stateless** — all state through storage libraries; state variables in facet contracts would live at the facet address, not the diamond proxy

2. **Use initializer functions** instead of constructors — constructors execute at the facet address, not the diamond proxy where state lives

3. **Store constants in diamond storage** instead of `immutable` — immutable values live in facet bytecode and change when the facet is replaced

4. **Group by domain** — one facet per logical domain (VaultFacet, StakingFacet, AdminFacet)

5. **Access control via internal library** — use `LibDiamond.enforceIsContractOwner()` or a shared access control library

## DiamondCut — upgrades

```solidity

struct FacetCut {

    address facetAddress;

    FacetCutAction action; // Add, Replace, Remove

    bytes4[] functionSelectors;

}

```

### Performing an upgrade

```solidity

contract UpgradeVaultV2 is Script {

    function run() external {

        IDiamondCut diamond = IDiamondCut(vm.envAddress("DIAMOND_ADDRESS"));

        address newFacet = address(new VaultFacetV2());

        IDiamondCut.FacetCut[] memory cuts = new IDiamondCut.FacetCut[](1);

        cuts[0] = IDiamondCut.FacetCut({

            facetAddress: newFacet,

            action: IDiamondCut.FacetCutAction.Replace,

            functionSelectors: _vaultSelectors()

        });

        bytes memory initData = abi.encodeWithSelector(VaultFacetV2.initializeV2.selector);

        vm.startBroadcast();

        diamond.diamondCut(cuts, newFacet, initData);

        vm.stopBroadcast();

    }

}

```

### Upgrade rules

1. **`Add`** — selector must not already exist

2. **`Replace`** — selector must exist and point to a different facet

3. **`Remove`** — set `facetAddress` to `address(0)`; selector must exist

4. **Initialization** — pass `_init` address and `_calldata` for migration logic. Pass `address(0)` and `""` for none

5. **Batch cuts** — group related changes into a single `diamondCut` for atomicity

## Selector management

1. **Generate selector lists from interfaces** rather than hardcoding

2. **Maintain a selector registry** tracking which selector belongs to which facet. Check for clashes before deploying

3. **Reserve `diamondCut` and loupe selectors** — these should never be replaced or removed

## DiamondLoupe — introspection

Every diamond implements these four loupe functions (per EIP-2535):

```solidity

interface IDiamondLoupe {

    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);

}

```

Use loupe functions in tests to verify selectors point to expected facet addresses after a `diamondCut`.

## Initialization pattern

```solidity

contract VaultFacet {

    function initialize(address asset_, uint256 maxDeposit_) external {

        LibDiamond.enforceIsContractOwner();

        LibVaultStorage.VaultStorage storage s = LibVaultStorage.layout();

        if (s.initialized) revert AlreadyInitialized();

        s.initialized = true;

        s.asset = asset_;

        s.maxDeposit = maxDeposit_;

    }

}

```

For versioned upgrades, track an initialization version:

```solidity

if (s.initVersion >= 2) revert AlreadyInitialized();

s.initVersion = 2;

// ... V2 migration logic

```