Getting Started

Crane is a Diamond-first (ERC-2535) framework for building modular, upgradeable Solidity contracts with deterministic deployment, reusable logic, and first-class support for AI agents.

Why reuse matters

Security. Prefer attaching already deployed and verified facets (via DFPkgs) instead of redeploying large surfaces of new bytecode—especially when an AI agent writes the change.

Cost. Facets and packages deployed once can be reused by many proxies and projects, so you do not pay full deployment cost for the same logic every time.

Cross-chain reproducibility. CREATE3 salts yield the same addresses when configuration matches.

Documentation map

Install

git clone --recurse-submodules https://github.com/cyotee/crane.git
cd crane
forge build

# Core path (matches CI)
FOUNDRY_PROFILE=ci forge build
FOUNDRY_PROFILE=ci forge test

As a Foundry dependency:

forge install cyotee/crane

Update your remappings.txt and foundry.toml (see this repo for aliases such as @crane/).

Bootstrap factories in tests:

import {InitDevService} from "@crane/contracts/InitDevService.sol";

(ICreate3FactoryProxy create3Factory, IDiamondPackageCallBackFactory diamondFactory) =
    InitDevService.initEnv(address(this));

For AI agents

1. Load skills — Prefer in-repo .claude/skills/ and/or install marketplaces:
   • Developer: cyotee/cyotee-claude-plugins → crane@cyotee
   • Ops: cyotee/defi-agent-skills (on-chain runbooks; not architecture dumps)
2. Start with crane-architecture, crane-deployment, and crane-testing.
3. Use Facet-Target-Repo + DFPkg for new features — Repo for storage, Target for logic, Facet for Diamond exposure.
4. Bootstrap via Init*Service or Crane test bases — avoid ad-hoc new for production deployment paths.
5. Follow NatSpec conventions in AGENTS.md and NatSpec docs.
6. Optional BattleChain gate — significant factories/packages may be exercised on BattleChain before mainnet promotion; see BattleChain.

Next steps

• Read Building with Crane
• Skim Facet-Target-Repo
• Try CREATE3 setup and DFPkg