Contract API Reference

Complete API reference for BattleChain contracts

Deployed Addresses

ℹ️

Every address on this page comes from a single source of truth and is served as JSON at /deployments.json. Fetch that file from scripts or AI agents instead of scraping these tables.

The proxy is the address you interact with. Implementation and Sepolia L1 addresses follow below.

Contract	Testnet	Mainnet
AttackRegistry (proxy)	`0x22134e878c409a0Eab7259d873b38e26Ca966d3C`	`0x24876e481eC7198CAC95af739Df2a852CE65A415`
SafeHarborRegistry (proxy)	`0x07E09f67B272aec60eebBfB3D592eC649BDCFEFc`	`0xd229f4EE1bAE432010b72a9d1bD682570F4C6eBe`
AgreementFactory (proxy)	`0xf52CEA27b9E20D03Ec48CDe4fafF8F27565646f2`	`0xCdB7F5C0F708baBaabE82afE1DbA8362023AcFdd`
BattleChainDeployer	`0x0f75289c6b883b885A1fDF9BCCABE1bbFB094077`	`0xD12765D21dDba418B8Fc0583c4716763e03Aa078`
CreateX	`0xf1Ebfaa992854ECcB01Ac1F60e5b5279095cca7F`	`0xa397f06F07251A3AEd53f6d3019A2a6cbd83E53e`

Testnet only — MockRegistryModerator at 0x3DdA228A38b4d7438bBF5D5137c8D1090DcaF6bF. This permissionless contract lets you approve your own attack request instantly on testnet; mainnet uses the DAO multisig below.

For mock Chainlink price feeds and test tokens (testnet only), see Mock Contracts.

Implementation addresses

The current UUPS implementations behind the proxies above:

Contract	Testnet	Mainnet
AttackRegistry	`0x4496b7e04b4Dd94153AA0d614708d5f06fc65a13`	`0x2d226C9f76748C3759F640Ee527Ad0D1A312fbB2`
SafeHarborRegistry	`0x7d6fC65eA6436f1621973BcfeaAD8951853D8E35`	`0x96d9cCEf1C2eBD19Cc4D3293Bd726c335F9523d7`
AgreementFactory	`0x8E940c4FE62ea1696751faA99F45F30459c6c978`	`0xF52b4B00E6c33ED327886fc64c205a9F2DEc3623`

Mainnet governance

Role	Address
Owner (Safe)	`0xfA26440c6DDc56C93A9248078e13a5eB050ADb1E`
Registry moderator (Safe)	`0x445d5685c4Ae71550Da0716b82B434AEA140E0c7`
Treasury (Safe)	`0x2B1731F5EedBa4141a66C6F81C5290BF61d3325c`

Sepolia (Testnet L1)

Settlement layer (L1) for BattleChain Testnet (chain 627)

Contract	Address
Bridgehub	`0xcea5c0ade89389dd5fc461f69ccbd812cfb7fbd8`
ZK Chain (627)	`0x564ca3000EfF59D9a647A1B8c871f27236201D1D`
Chain Type Manager	`0x3F9A46ec287C93b74D4f144712bDb4EEdEEEEC74`
Validator Timelock	`0x8C2a0b3C86CaA986f5dCd71f053c63Ac8324EA6f`

Ethereum (Mainnet L1)

Settlement layer (L1) for BattleChain (chain 626)

Contract	Address
Bridgehub	`0x6f85C08e2DabB6b0B8B3587D3628FCfb5b10BE19`
ZK Chain (626)	`0xB44d26D227e0bD028d893BEc16DC1C7B168eCdE3`
Chain Type Manager	`0x4Ee4EA87b909ea3E1C36d9fcbf6C0e535165f96D`
Validator Timelock	`0x313E1E05b967aB18cCb6aAaAE19E616b7b99a01a`

AttackRegistry

Tracks attack/production status of contracts.

State-Changing Functions

// Protocol functions
function requestUnderAttack(address agreementAddress) external;
function requestUnderAttackByNonAuthorized(address agreementAddress) external;
function goToProduction(address agreementAddress) external;

// Attack moderator functions
function promote(address agreementAddress) external;
function cancelPromotion(address agreementAddress) external;
function markCorrupted(address agreementAddress) external;
function transferAttackModerator(address agreementAddress, address newModerator) external;

// Deployer functions
function authorizeAgreementOwner(address contractAddress, address newOwner) external;

// DAO functions
function approveAttack(address agreementAddress) external;
function rejectAttackRequest(address agreementAddress) external;
function instantPromote(address agreementAddress) external;

View Functions

function isTopLevelContractUnderAttack(address contractAddress) external view returns (bool);
function getAgreementState(address agreementAddress) external view returns (ContractState);
function getAgreementInfo(address agreementAddress) external view returns (AgreementInfo memory);
function getAgreementForContract(address contractAddress) external view returns (address);
function getAttackModerator(address agreementAddress) external view returns (address);
function getContractDeployer(address contractAddress) external view returns (address);
function getAuthorizedOwner(address contractAddress) external view returns (address);
function getRegistryModerator() external view returns (address);

Events

event AgreementStateChanged(address indexed agreementAddress, ContractState newState);
event AttackModeratorTransferred(address indexed agreementAddress, address indexed newModerator);
event ContractRegistered(address indexed contractAddress, address indexed agreementAddress);
event AgreementOwnerAuthorized(address indexed contractAddress, address indexed authorizedOwner);

Agreement

Per-protocol Safe Harbor terms.

Owner Functions

function setProtocolName(string calldata protocolName) external;
function setContactDetails(Contact[] memory contactDetails) external;
function addOrSetChains(Chain[] memory chains) external;
function removeChains(string[] memory caip2ChainIds) external;
function addAccounts(string memory caip2ChainId, Account[] memory newAccounts) external;
function removeAccounts(string memory caip2ChainId, string[] memory accountAddresses) external;
function setBountyTerms(BountyTerms memory bountyTerms) external;
function setAgreementURI(string calldata agreementURI) external;
function extendCommitmentWindow(uint256 newCantChangeUntil) external;

View Functions

function getDetails() external view returns (AgreementDetails memory);
function getProtocolName() external view returns (string memory);
function getBountyTerms() external view returns (BountyTerms memory);
function getAgreementURI() external view returns (string memory);
function getChainIds() external view returns (string[] memory);
function getChainAccounts(string memory caip2ChainId) external view returns (Account[] memory);
function getAssetRecoveryAddress(string memory caip2ChainId) external view returns (string memory);
function getCantChangeUntil() external view returns (uint256);
function getBattleChainScopeAddresses() external view returns (address[] memory);
function isContractInScope(address contractAddress) external view returns (bool);

AgreementFactory

Creates Agreement contracts.

function create(
    AgreementDetails memory details,
    address owner,
    bytes32 salt
) external returns (address agreementAddress);

function isAgreementContract(address agreementAddress) external view returns (bool);
function getRegistry() external view returns (address);
function getBattleChainCaip2ChainId() external view returns (string memory);

BattleChainSafeHarborRegistry

Maps protocols to agreements.

function adoptSafeHarbor(address agreementAddress) external;
function getAgreement(address adopter) external view returns (address);
function isChainValid(string calldata caip2ChainId) external view returns (bool);
function isAgreementValid(address agreementAddress) external view returns (bool);

BattleChainDeployer

Deploys contracts with automatic registration.

Supports all CreateX methods:

deployCreate(), deployCreateAndInit(), deployCreateClone()
deployCreate2(), deployCreate2AndInit(), deployCreate2Clone()
deployCreate3(), deployCreate3AndInit()

All deployments automatically call AttackRegistry.registerDeployment().

Contract ABIs

Typed ABIs for all BattleChain contracts are available in battlechain-lib as TypeScript constants compatible with viem:

Export	Contract
`attackRegistryAbi`	AttackRegistry
`registryAbi`	BattleChainSafeHarborRegistry
`agreementFactoryAbi`	AgreementFactory
`agreementAbi`	Agreement
`deployerAbi`	BattleChainDeployer

import { attackRegistryAbi, registryAbi } from 'battlechain-lib/ts/abi'