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 and remappings.txt:

Alias	Path
@crane/	Crane framework contracts
@solady/	Solady library
@openzeppelin/	OpenZeppelin contracts
forge-std/	Foundry test utilities

Function Organization

Order functions by visibility:

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

Naming Conventions

Pattern	Usage	Example
_layoutStruct()	Storage access	_layoutStruct(), _layoutStruct(bytes32 slot_)
_initialize()	Storage setup	_initialize(address owner_)
_functionName()	Internal Repo functions	_isOperator(), _setOperator()
_onlyXxx()	Guard functions in Repos	_onlyOwner(), _onlyOperator()
onlyXxx	Modifiers	onlyOwner, onlyOperator
layoutStruct	Storage parameter name	Storage storage layoutStruct
param_	Function parameters	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:

Category	Pattern	Example
Crane core	crane.{domain}.{feature}	"crane.access.operable"
Protocol integrations	protocols.{category}.{protocol}.{version}.{feature}	"protocols.dexes.balancer.v3.vault.aware"
EIP implementations	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 or viaIR in foundry.toml.

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