Crane Code Style Guide

Crane follows strict code conventions for consistency and maintainability. This skill covers section headers, imports, naming, and critical compilation rules.

Section Headers

Use 78-character wide comment blocks for major sections:

/* -------------------------------------------------------------------------- */
/*                             Section Name                                   */
/* -------------------------------------------------------------------------- */

Shorter form for subsections:

/* ------ Feature Name ------ */

Import Organization

Group imports by source, with import aliases:

// External libraries
import {IERC20} from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
import {SafeERC20} from "@solady/utils/SafeERC20.sol";

// Crane interfaces
import {IFacet} from "@crane/contracts/interfaces/IFacet.sol";
import {IOperable} from "@crane/contracts/access/operable/interfaces/IOperable.sol";

// Crane contracts
import {OperableRepo} from "@crane/contracts/access/operable/OperableRepo.sol";
import {OperableTarget} from "@crane/contracts/access/operable/OperableTarget.sol";

// Test utilities (in test files)
import {Test} from "forge-std/Test.sol";
import {Vm, VM_ADDRESS} from "forge-std/Vm.sol";

Import Aliases

Defined in

foundry.toml

remappings.txt

@crane/

@solady/

@openzeppelin/

forge-std/

Function Organization

Order functions by visibility:

1. Constructor
2. Receive
3. Fallback
4. External
5. Public
6. Internal
7. Private

Naming Conventions

_layout()

_layout()

_layout(bytes32 slot_)

_initialize()

_initialize(address owner_)

_functionName()

_isOperator()

_setOperator()

_onlyXxx()

_onlyOwner()

_onlyOperator()

onlyXxx

onlyOwner

onlyOperator

layout

Storage storage layout

param_

owner_

slot_

name_

Parameter Trailing Underscore

All function parameters end with underscore to avoid shadowing:

function transfer(address to_, uint256 amount_) external {
    // to_ and amount_ don't shadow state variables
}

Storage Slot Naming

Use hierarchical dot-notation for storage slot names:

crane.{domain}.{feature}

"crane.access.operable"

protocols.{category}.{protocol}.{version}.{feature}

"protocols.dexes.balancer.v3.vault.aware"

eip.erc.{number}

"eip.erc.8023"

bytes32 internal constant STORAGE_SLOT = keccak256(abi.encode("crane.access.operable"));

Critical: No viaIR Compilation

NEVER enable

via_ir

viaIR

IR compilation is forbidden because:

• Dramatically slower compilation (10-100x slower)
• Excessive memory usage
• Breaks parallel agent workflows
• Not necessary when code is properly structured

Resolving Stack Too Deep Errors

When encountering "stack too deep" errors, refactor using structs:

// WRONG - too many local variables
function badFunction(
    address tokenA,
    address tokenB,
    uint256 amountA,
    uint256 amountB,
    address recipient,
    uint256 deadline
) external {
    uint256 reserveA = pair.reserveA();
    uint256 reserveB = pair.reserveB();
    uint256 totalSupply = pair.totalSupply();
    // ... stack too deep!
}

// CORRECT - group into structs
struct DepositParams {
    address tokenA;
    address tokenB;
    uint256 amountA;
    uint256 amountB;
    address recipient;
    uint256 deadline;
}

struct PoolState {
    uint256 reserveA;
    uint256 reserveB;
    uint256 totalSupply;
}

function goodFunction(DepositParams memory params) external {
    PoolState memory state = PoolState({
        reserveA: pair.reserveA(),
        reserveB: pair.reserveB(),
        totalSupply: pair.totalSupply()
    });
    // Struct members don't consume stack slots
}

Stack Too Deep Solutions

1. Group parameters into structs: Bundle related function parameters
2. Group intermediate state: Use

   State

   or

   Context

   structs
3. Use

   memory

   for computation: Struct fields don't consume stack
4. Extract helper functions: Split complex functions
5. Use block scoping: Limit variable lifetimes with

   { ... }

Configuration

Standard Crane configuration:

• Solidity: 0.8.30
• Optimizer runs: 1 (for contract size limits)
• EVM version: Prague
• via_ir: false (ALWAYS)

Additional Resources

Reference Files

• references/complete-style-guide.md

  - Full style guide with more examples

Key Files

• /contracts/StyleGuide.sol

  - Reference template

• /foundry.toml

  - Build configuration

• /remappings.txt

  - Import aliases