battlechain-safe-harbor

name	battlechain-safe-harbor
description	Use this skill when evaluating attack legality, agreement scope, bounty eligibility, or Binding Agreement resolution on BattleChain.

BattleChain Safe Harbor and Binding Agreement

This skill prevents the most dangerous mistake: reading terms from the wrong agreement.

What Safe Harbor Covers

Protected only when both are true:

1. Target is attackable (UNDER_ATTACK or PROMOTION_REQUESTED).
2. Target is in scope under the Binding Agreement.

Safe Harbor does not cover attacks on PRODUCTION, out-of-scope contracts, or violations of bounty and identity terms.

Binding Agreement Resolution (Critical)

Do not trust BattleChainSafeHarborRegistry.getAgreement(adopter) for exploit terms.

Use Binding Agreement resolution:

• For top-level contracts: AttackRegistry.getAgreementForContract(target).
• For child contracts: resolve by deployer lineage and child-scope rules.

Prefer API or BCQuery instead of manual resolution.

Preferred Verification Paths

Option 1: Explorer API (recommended)

GET https://block-explorer-api.testnet.battlechain.com/battlechain/agreement/by-contract/{contractAddress}

Option 2: BCQuery helper

bool attackable = isAttackable(contractAddress); // requires --ffi

Option 3: On-chain only (top-level only)

address binding = attackRegistry.getAgreementForContract(contractAddress);
require(binding != address(0), "not registered top-level");
require(attackRegistry.isTopLevelContractUnderAttack(contractAddress), "not attackable");
BountyTerms memory terms = IAgreement(binding).getBountyTerms();

Commitment Window Rules

During commitment window (getCantChangeUntil()), protocol cannot make whitehat-unfavorable changes:

• cannot reduce bounty/caps
• cannot remove scope
• cannot tighten identity
• cannot switch to return-all unfavorably

Agreement URI Rule

Legal source of truth is agreementURI from the Binding Agreement itself.

string memory uri = IAgreement(bindingAgreement).getAgreementURI();

Pre-Attack Checklist

• Resolve Binding Agreement.
• Confirm attackable state.
• Confirm in-scope contract coverage.
• Read bounty percentage and cap.
• Read retainable behavior.
• Read identity requirements.
• Capture evidence snapshot (state, agreement address, tx context).

Bounty Terms Essentials

struct BountyTerms {
    uint256 bountyPercentage;
    uint256 bountyCapUsd;
    bool retainable;
    IdentityRequirements identity;
    string diligenceRequirements;
    uint256 aggregateBountyCapUsd;
}

Bounty formula:

bounty = min(recoveredValue * bountyPercentage, bountyCapUsd)

Aggregate cap constraints apply when set. aggregateBountyCapUsd is incompatible with retainable = true.

Mainnet Safety Rule

If exploit likely affects mainnet deployments:

• do not publicly disclose exploit details
• notify protocol privately
• use normal bug bounty path for mainnet scope

References

• https://docs.battlechain.com/battlechain/explanation/safe-harbor
• https://docs.battlechain.com/battlechain/how-to/find-attackable-contracts
• https://docs.battlechain.com/battlechain/how-to/claim-bounties
• https://docs.battlechain.com/battlechain/reference/bounty-terms