Crane Architecture

---
name: Crane Architecture
description: This skill should be used when the user asks about "facet", "target", "repo", "diamond pattern", "storage slot", "guard function", "DFPkg", "AwareRepo", "Service pattern", "Modifiers", "ERC2535", or needs guidance on Crane's core architectural patterns for building modular, upgradeable smart contracts.
version: 0.1.0
---

# Crane Architecture Patterns

Crane is a Diamond-first (ERC2535) Solidity development framework for building modular, upgradeable smart contracts. This skill provides guidance on the core architectural patterns.

## Core Pattern: Facet-Target-Repo

Every feature in Crane follows a three-tier architecture:

| Layer | File Pattern | Purpose |
|-------|--------------|---------|
| **Repo** | `*Repo.sol` | Storage library with assembly-based slot binding. Defines `Storage` struct and dual `_layout()` functions. No state variables. |
| **Target** | `*Target.sol` | Implementation contract with business logic. Uses Repo for storage access. Inherits interfaces. |
| **Facet** | `*Facet.sol` | Diamond facet. Extends Target and implements `IFacet` for metadata (name, interfaces, selectors). |

### When to Create Each Layer

- **Repo**: Always create first. Contains all storage and internal helper functions.
- **Target**: Create when business logic needs to be shared or tested independently.
- **Facet**: Create when exposing functionality through the Diamond proxy.

## Storage Slot Pattern

All Repos use the Diamond storage pattern with dual function overloads:

```solidity
library ExampleRepo {
    bytes32 internal constant STORAGE_SLOT = keccak256(abi.encode("crane.feature.name"));

    struct Storage {
        mapping(address => bool) isOperator;
    }

    // Parameterized version - allows custom slot
    function _layout(bytes32 slot) internal pure returns (Storage storage layout) {
        assembly { layout.slot := slot }
    }

    // Default version - uses STORAGE_SLOT
    function _layout() internal pure returns (Storage storage) {
        return _layout(STORAGE_SLOT);
    }
}
```

### Dual Function Overload Pattern

Every Repo function has TWO overloads:

```solidity
// 1. Parameterized: takes Storage as first param
function _isOperator(Storage storage layout, address query) internal view returns (bool) {
    return layout.isOperator[query];
}

// 2. Default: calls parameterized with _layout()
function _isOperator(address query) internal view returns (bool) {
    return _isOperator(_layout(), query);
}
```

This enables:
- Default usage with standard storage slot
- Custom slot usage for multi-instance patterns
- Composability between Repos

## Guard Functions Pattern

Repos contain `_onlyXxx()` guard functions with access control logic. Modifiers are thin wrappers:

```solidity
// In Repo - contains the actual check logic
function _onlyOperator(Storage storage layout) internal view {
    if (!_isOperator(layout, msg.sender) && !_isFunctionOperator(layout, msg.sig, msg.sender)) {
        revert IOperable.NotOperator(msg.sender);
    }
}

function _onlyOperator() internal view {
    _onlyOperator(_layout());
}

// In Modifiers contract - thin delegation wrapper
modifier onlyOperator() {
    OperableRepo._onlyOperator();
    _;
}
```

## Additional Patterns

### Modifiers Contract (`*Modifiers.sol`)

Abstract contracts with reusable modifiers delegating to Repo guards:

```solidity
abstract contract OperableModifiers {
    modifier onlyOperator() {
        OperableRepo._onlyOperator();
        _;
    }
}
```

### Service Library (`*Service.sol`)

Stateless libraries for complex business logic. Use structs to avoid stack-too-deep:

```solidity
library CamelotV2Service {
    struct SwapParams {
        ICamelotV2Router router;
        uint256 amountIn;
        IERC20 tokenIn;
    }

    function _swap(SwapParams memory params) internal { ... }
}
```

### AwareRepo (`*AwareRepo.sol`)

Dependency injection for external contract references:

```solidity
library BalancerV3VaultAwareRepo {
    bytes32 internal constant STORAGE_SLOT = keccak256("protocols.dexes.balancer.v3.vault.aware");

    struct Storage {
        IVault balancerV3Vault;
    }

    function _initialize(IVault vault) internal { _layout().balancerV3Vault = vault; }
    function _balancerV3Vault() internal view returns (IVault) { return _layout().balancerV3Vault; }
}
```

### Diamond Factory Package (`*DFPkg.sol`)

Bundles facets into deployable packages. See `references/dfpkg-pattern.md` for complete details.

## IFacet Interface

All facets implement `IFacet`:

```solidity
function facetName() external view returns (string memory name);
function facetInterfaces() external view returns (bytes4[] memory interfaces);
function facetFuncs() external view returns (bytes4[] memory funcs);
function facetMetadata() external view returns (string memory name, bytes4[] memory interfaces, bytes4[] memory functions);
```

## Storage Slot Naming Convention

Use hierarchical dot-notation:

| Pattern | Example |
|---------|---------|
| Crane core | `"crane.access.operable"` |
| Protocol integrations | `"protocols.dexes.balancer.v3.vault.aware"` |
| EIP implementations | `"eip.erc.8023"` |

## Key Reference Files

For complete implementations, examine these files in the Crane codebase:

- `contracts/access/operable/` - Complete Facet-Target-Repo example
- `contracts/introspection/ERC2535/ERC2535Repo.sol` - Diamond storage management
- `contracts/access/ERC8023/` - Two-step ownership (EIP-8023)
- `contracts/protocols/dexes/camelot/v2/services/CamelotV2Service.sol` - Service pattern

## Additional Resources

### Reference Files

For detailed patterns and complete examples:
- **`references/dfpkg-pattern.md`** - Diamond Factory Package pattern in depth
- **`references/factory-service.md`** - FactoryService pattern for deployment

### Quick Decision Guide

| Need | Pattern |
|------|---------|
| Storage for a feature | Create `*Repo.sol` |
| Business logic | Create `*Target.sol` or `*Service.sol` |
| Diamond-exposed functions | Create `*Facet.sol` |
| External contract reference | Create `*AwareRepo.sol` |
| Reusable access control | Create `*Modifiers.sol` |
| Deployable package | Create `*DFPkg.sol` |