battlechain-lib: Skill for Claude Code

Solidity Development Standards

Instructions for how to write solidity code, from the Cyfrin security team.

Philosophy

• Everything will be attacked - Assume that any code you write will be attacked and write it defensively.

Code Quality and Style

1. Absolute and named imports only — no relative (..) paths

// good
import {MyContract} from "contracts/MyContract.sol";

// bad
import "../MyContract.sol";

1. Prefer revert over require, with custom errors that are prefix'd with the contract name and 2 underscores.

error ContractName__MyError();

// Good
myBool = true;
if (myBool) {
    revert ContractName__MyError();
}

// bad
require(myBool, "MyError");

1. In tests, prefer stateless fuzz tests over unit tests

// good - using foundry's built in stateless fuzzer
function testMyTest(uint256 randomNumber) { }

// bad
function testMyTest() {
    uint256 randomNumber = 0;
}

Additionally, write invariant (stateful) fuzz tests for core protocol properties. Use invariant-driven development: identify O(1) properties that must always hold and encode them directly into core functions (FREI-PI pattern). Use a multi-fuzzing setup like Chimera to run the same invariant suite across Foundry, Echidna, and Medusa — different fuzzers find different bugs.

1. Functions should be grouped according to their visibility and ordered:

constructor
receive function (if exists)
fallback function (if exists)
user-facing state-changing functions
    (external or public, not view or pure)
user-facing read-only functions
    (external or public, view or pure)
internal state-changing functions
    (internal or private, not view or pure)
internal read-only functions
    (internal or private, view or pure)

1. Headers should look like this:

    /*//////////////////////////////////////////////////////////////
                      INTERNAL STATE-CHANGING FUNCTIONS
    //////////////////////////////////////////////////////////////*/