battlechain-lib

Foundry library for deploying on BattleChain and adopting Safe Harbor agreements.

Installation

Foundry

forge install cyfrin/battlechain-lib

Add the remapping to your foundry.toml:

remappings = ["battlechain-lib/=lib/battlechain-lib/src/"]

npm / Hardhat (in development)

Note: Hardhat support is still in development. The TypeScript exports and Solidity imports work, but the integration is not yet fully tested. Expect rough edges.

npm install @cyfrin/battlechain-lib

Add the remapping to your hardhat.config or remappings.txt:

battlechain-lib/=node_modules/@cyfrin/battlechain-lib/src/

Quick Start

Inherit BCScript and implement the required hooks:

import { BCScript } from "battlechain-lib/BCScript.sol";
import { Contact } from "battlechain-lib/types/AgreementTypes.sol";

contract Deploy is BCScript {
    function _protocolName() internal pure override returns (string memory) {
        return "MyProtocol";
    }

    function _contacts() internal pure override returns (Contact[] memory) {
        Contact[] memory c = new Contact[](1);
        c[0] = Contact({ name: "Security Team", contact: "security@example.xyz" });
        return c;
    }

    function _recoveryAddress() internal view override returns (address) {
        return msg.sender;
    }

    function run() external {
        vm.startBroadcast();

        // Deploy via BattleChainDeployer
        address token = bcDeployCreate(type(MyToken).creationCode);

        // Create agreement with defaults, adopt it, and enter attack mode
        address agreement = createAndAdoptAgreement(
            defaultAgreementDetails(
                _protocolName(), _contacts(), getDeployedContracts(), _recoveryAddress()
            ),
            msg.sender,
            keccak256("v1")
        );
        requestAttackMode(agreement);

        vm.stopBroadcast();
    }
}

See script/Example.s.sol for full examples including generic EVM deployment.

What's Included

Contract	Purpose
BCScript	Single import combining deploy + Safe Harbor helpers
BCDeploy	Deploy via BattleChainDeployer (CREATE, CREATE2, CREATE3)
BCSafeHarbor	Build and adopt Safe Harbor agreements
BCConfig	On-chain address registry for BattleChain networks
BCBase	Shared base with address resolution and overrides

Supported Networks

Network	Chain ID	RPC URL
Mainnet	626	https://mainnet.battlechain.com
Testnet	627	https://testnet.battlechain.com

The core BattleChain contracts (registry, agreement factory, attack registry, deployer) and CreateX are deployed on both networks — BCConfig resolves them by chain ID. Block explorers: explorer.mainnet.battlechain.com and explorer.testnet.battlechain.com.

For unsupported chains or local Anvil testing, use _setBcAddresses() to provide contract addresses manually.

Documentation

Full BattleChain documentation: docs.battlechain.com

Teach Your AI About BattleChain

Claude Code: Install the BattleChain skill:

npx skills add cyfrin/solskill --skill battlechain

Other AI tools (Cursor, Copilot, etc.): Add this to your .cursorrules or equivalent AI instructions file:

This project deploys on BattleChain.

AI docs: https://docs.battlechain.com/llms-full.txt

BattleChain docs follow the llms.txt convention:

URL	Contents
llms.txt	Table of contents with page titles and links
llms-full.txt	Complete docs as clean markdown

Development

forge build       # Build
forge test        # Run tests
forge fmt         # Format