API Reference

Version: 1.0
Last Updated: December 2025
Status: Production

ArbiterRegistry

Purpose: Store swarm configurations with gas-optimized Merkle root membership

Public State Variables

swarms(bytes32 swarmId) → SwarmConfig

Returns the swarm configuration for a given swarm ID.

owner → address

Contract owner address (can pause and register swarms).

paused → bool

Pause status (when true, all operations are paused).

Functions

registerSwarm(SwarmConfig memory config)

Access: Owner only, when not paused

Parameters:

• config (SwarmConfig): Swarm configuration

Gas Cost: ~50K gas

Events: SwarmRegistered(bytes32 indexed swarmId, bytes32 membersMerkleRoot, uint16 quorumBps)

verifyMembership(bytes32 swarmId, address member, bytes32[] calldata merkleProof) → bool

Access: Public view, when not paused

Returns: isValid (bool): true if member is in swarm

Gas Cost: ~5K gas (view function)

getSwarmConfig(bytes32 swarmId) → SwarmConfig

Access: Public view

Returns: SwarmConfig struct

Gas Cost: ~3K gas (view function)

ArbiterFinality

Purpose: Authoritative source for leadership proofs and fencing tokens

Functions

commitLeadership(bytes32 swarmId, address newLeader, uint64 newTerm, AggregatedVoteProof calldata voteProof)

Access: Public

Requirements:

• Swarm must exist in registry
• Term must be sequential
• Must meet quorum threshold

Gas Cost: ~80K gas

Events: LeadershipCommitted(bytes32 indexed swarmId, address indexed leader, uint64 termNumber, bytes32 votesHash, uint256 voteCount)

issueFence(bytes32 resourceId) → uint256

Access: Authorized fence issuers only

Returns: fenceToken (uint256): Monotonically increasing fence token

Gas Cost: ~45K gas

Events: FenceIssued(bytes32 indexed resourceId, uint256 fenceToken, address holder)

ArbiterStaking

Purpose: Verification-only staking for Sybil resistance (NO FUND CUSTODY)

Functions

verifyStakeProof(address agent, uint256 stakeAmount, uint256 timestamp, bytes32 swarmId, bytes calldata signature) → uint256

Access: Public view

Returns: verifiedStake (uint256): Verified stake amount (0 if invalid)

Gas Cost: ~5K gas (view function)

getVoteWeight(address agent, uint256 stakeAmount, uint256 timestamp, bytes32 swarmId, bytes calldata signature) → uint256

Access: Public view

Returns: weight (uint256): Voting weight (square root of stake, 0 if invalid)

Gas Cost: ~3K gas (view function)

ArbiterPricing

Purpose: Dynamic pricing engine for x402 payment protocol

Functions

calculateVoteCollectionPrice(uint256 numVotes, uint256 swarmSize, bool isBFT, bool isUrgent) → uint256

Access: Public view

Returns: price (uint256): Price in USDC atomic units (6 decimals)

Gas Cost: ~3K gas (view function)

calculateLeadershipCommitPrice(uint256 swarmSize, uint256 numVoteProofs, uint256 estimatedGas, uint256 gasPrice) → (uint256 price, uint256 serviceFee, uint256 gasCost)

Access: Public view

Returns: Total price (service fee + gas cost), service fee component, and gas cost component

Gas Cost: ~5K gas (view function)

ArbiterSubscription

Purpose: Prepaid subscription service for high-volume users

Functions

subscribe(uint8 tier)

Access: Public

Parameters:

• tier (uint8): Subscription tier (1=Starter, 2=Pro, 3=Enterprise)

Gas Cost: ~80K gas

Events: SubscriptionPurchased(address indexed subscriber, uint8 tier, uint256 price, uint128 credits)

canAccess(address user, uint256 requiredCredits) → (bool hasAccess, uint256 creditsRemaining)

Access: Public view

Returns: Whether user has valid subscription with sufficient credits, and remaining credits

Gas Cost: ~3K gas (view function)

Data Structures

SwarmConfig

struct SwarmConfig {
    bytes32 swarmId;
    bytes32 membersMerkleRoot;
    uint16 quorumBps;            // Basis points (5000 = 50%)
    uint16 maxByzantineFaults;   // f in 3f+1
    uint32 heartbeatBlocks;
    uint32 electionTimeoutBlocks;
    bool requireBFT;
    uint256 minStakeOverride;    // 0 = use global
    uint16 memberCount;
}

LeadershipProof

struct LeadershipProof {
    address leader;
    uint64 termNumber;
    uint64 electedAtBlock;
    uint64 lastCheckpointBlock;
    bytes32 votesHash;
}

Events

ArbiterRegistry

SwarmRegistered(bytes32 indexed swarmId, bytes32 membersMerkleRoot, uint16 quorumBps)

Emitted when a new swarm is registered.

ArbiterFinality

LeadershipCommitted(bytes32 indexed swarmId, address indexed leader, uint64 termNumber, bytes32 votesHash, uint256 voteCount)

Emitted when leadership is committed.

ArbiterStaking

StakeProofVerified(address indexed agent, bytes32 indexed swarmId, uint256 stakeAmount, bytes32 proofHash)

Emitted when a stake proof is verified and consumed.

Error Codes

• "Swarm already exists" - Swarm ID already registered
• "Swarm not found" - Swarm ID does not exist
• "Invalid quorum" - Quorum must be between 1 and 10000 basis points
• "Term must be sequential" - Term numbers must be sequential
• "Insufficient votes for quorum" - Not enough votes for quorum
• "Not authorized" - Caller not authorized
• "Contract paused" - Contract is paused
• "Invalid signature" - Signature verification failed
• "Below minimum stake" - Stake amount below minimum
• "Subscription expired" - Subscription has expired
• "Insufficient credits" - Not enough credits for operation

For complete documentation with detailed examples and usage patterns, see the Documentation page.