battlechain-lib-py

Python library for deploying on BattleChain and adopting Safe Harbor agreements. Mirrors cyfrin/battlechain-lib (Solidity).

Boa-first, designed for Moccasin scripts.

• battlechain-lib-py
  • Installation
  • Quick start
  • What's included
  • Supported networks
    • Mainnet (626) addresses
  • Reference
    • is_attackable(contract_address: str) -> bool
    • bc_deploy_create(init_code: bytes) -> str
    • bc_deploy(deployer, *args) and build_init_code(deployer, *args)
    • default_agreement_details(...) and friends
    • Network overrides
  • Contributing
  • License

Installation

uv add battlechain-lib-py
# or
pip install battlechain-lib-py

Requires Python ≥ 3.11.

Quick start

A minimal Moccasin script that deploys a contract, creates a Safe Harbor agreement, adopts it, and requests attack mode:

import boa
from eth_utils import keccak

import battlechain as bc
from src import MyVault  # your Vyper contract


def moccasin_main() -> None:
    # 1. Deploy through BattleChainDeployer (auto-registers with AttackRegistry)
    vault = MyVault.deploy()
    bc.track_deployment(vault.address)

    # 2. Build agreement defaults — chain ID, CAIP-2 scope, and Safe Harbor URI
    #    are all picked automatically based on the active boa env.
    details = bc.default_agreement_details(
        protocol_name="MyProtocol",
        contacts=[bc.Contact(name="Security Team", contact="sec@example.xyz")],
        contracts=bc.deployed_contracts(),
        recovery_address=boa.env.eoa,
        chain_id=bc.TESTNET_CHAIN_ID,
    )

    # 3. Create + 14-day commitment + adopt, all in one call
    agreement = bc.create_and_adopt_agreement(
        details, owner=boa.env.eoa, salt=keccak(b"v1")
    )

    # 4. Enter attack mode — only valid on BattleChain
    bc.request_attack_mode(agreement)

    # 5. Verify source on the block explorer
    bc.verify_contract(vault.address, "src/MyVault.vy:MyVault", "0.4.0")

Run with mox run script/deploy.py --network battlechain.

What's included

Supported networks

Both networks have a block explorer, so the explorer-backed helpers (is_attackable, verify_contract) work on mainnet and testnet:

• Mainnet: https://explorer.mainnet.battlechain.com/
• Testnet: https://explorer.testnet.battlechain.com/

Mainnet (626) addresses

Note: on BattleChain mainnet, CreateX is not at the well-known 0xba5Ed0… address — create_x_address(626) resolves the BattleChain deployment above.

For local Anvil or unsupported chains, register addresses with config.set_overrides:

import battlechain.config as cfg

cfg.set_overrides(
    chain_id=31337,
    registry="0x…",
    factory="0x…",
    attack_registry="0x…",
    deployer="0x…",
)

Reference

is_attackable(contract_address: str) -> bool

Mirrors BCQuery.isAttackable. Returns True if any Safe Harbor agreement covering the contract is in UNDER_ATTACK or PROMOTION_REQUESTED. Resolves coverage via the BattleChain block explorer (works for top-level and child contracts).

import battlechain as bc

if bc.is_attackable("0x…"):
    print("fair game under Safe Harbor")

For top-level-only on-chain checks (no HTTP), use is_top_level_contract_under_attack.

bc_deploy_create(init_code: bytes) -> str

Routes through BattleChainDeployer on BattleChain (auto-registers with the AttackRegistry) and through CreateX on any of the 190+ supported chains. bc_deploy_create2(salt, init_code) and bc_deploy_create3(salt, init_code) work the same way.

Every deploy is tracked — call deployed_contracts() to get them all and pass straight into default_agreement_details.

bc_deploy(deployer, *args) and build_init_code(deployer, *args)

Higher-level wrappers for boa-compiled contracts. build_init_code takes a boa VyperDeployer (e.g. the symbol from from src import MyContract) plus constructor args and returns the assembled init code — handy when paired with bc_deploy_create2 for deterministic addresses:

salt = keccak(b"my-vault-v1")
init_code = bc.build_init_code(MyVault, token.address)
address = bc.bc_deploy_create2(salt, init_code)

bc_deploy does the full job in one call: builds init code, deploys via BattleChainDeployer (CREATE), wraps the result back into a VyperContract, and persists the address to a per-chain JSON file (.bc_deployments.json by default):

vault = bc.bc_deploy(MyVault, token.address)
vault.deposit(amount)  # use it like any boa contract

Subsequent script runs can resolve the address with get_tracked_address("MyVault") or fetch a wrapped contract instance with get_tracked_contract(MyVault). The JSON file exists because deployer-routed contracts perform their CREATE inside BattleChainDeployer's call context, so moccasin's deployments.db can't see them.

default_agreement_details(...) and friends

Build AgreementDetails with sensible defaults. On BattleChain it sets the BattleChain CAIP-2 scope and BATTLECHAIN_SAFE_HARBOR_URI; on other chains it falls back to the chain's eip155: scope and the generic Safe Harbor V3 URI.

The default bounty terms match BCSafeHarbor.defaultBountyTerms: 10%, $1M cap, retainable, anonymous, no aggregate cap.

Network overrides

Same pattern as BCBase._setBcAddresses: register override addresses for any chain and they take precedence over the canonical registry.

Contributing

See CONTRIBUTING.md for dev environment setup, the codegen flow, and the test suite.

License

Dual-licensed under MIT and Apache-2.0 at your option.