Docscontracts

Smart Contract Architecture Reference

Learn about the BotPay protocol core smart contracts, transaction structures, storage slots, registry interfaces, and gas properties.

Core Contracts Structure

The BotPay protocol is built as a set of modular smart contracts on the Arc Network. Because **USDC is the native gas token on Arc**, payments are transacted natively using `msg.value` (measured in 18 decimals, directly corresponding to native USDC tokens) without calling the ERC-20 `transferFrom` approval patterns.

BotPay.sol

The core processor registry and escrow streaming ledger. Handles identity lookup, intent validation, and automated linear settlement.

IdentityRegistry.sol

Official **ERC-8004** compliant directory. Maps bot identifiers to verified metadata, owner hashes, and developer endpoint signatures.

Data Structs & State Variables

The contract stores Bot registries and Payment escrow logs inside clean mappings:

struct Bot {
    uint256 id;             // Unique sequential identifier
    string name;            // Human-readable bot name
    address owner;          // Wallet address that owns the bot
    string endpoint;        // Webhook URL destination
    uint256 totalRevenue;   // Total USDC (18-decimal) settled
    uint256 totalPayments;  // Total completed payments count
    uint256 registeredAt;   // Genesis block timestamp
    bool active;            // Registry activation state
}

struct PaymentIntent {
    uint256 id;             // Unique payment intent identifier
    uint256 botId;          // Link to registered Bot struct
    address payer;          // Address of customer locking funds
    uint256 amount;         // Total USDC amount requested
    uint256 streamedAmount; // Current accrued USDC amount
    uint256 claimedAmount;  // Already withdrawn USDC amount
    uint256 createdAt;      // Intent creation timestamp
    uint256 authorizedAt;  // Payer authorization lockup timestamp
    uint256 duration;       // Total stream window size in seconds
    bytes32 memo;           // 32-byte reference parameter
    IntentStatus status;    // State enum
}

Core Functions Reference

registerBot(string name, string endpoint)approx. 85,000 gas units

Registers a new bot under the caller's wallet. Initializes totalRevenue to 0, sets active to true, and triggers the BotRegistered event.

createIntent(uint256 botId, uint256 amount, uint256 duration, bytes32 memo)approx. 62,000 gas units

Called by the bot server to generate a pending payment. The amount must be specified in native 18-decimal gas USDC.

authorizeIntent(uint256 intentId) payableapprox. 45,000 gas units

Called by the client to lock USDC funds in escrow. If excess native USDC is provided, the contract automatically refunds the difference to the sender.

claimStream(uint256 intentId)approx. 38,000 gas units

Called by the bot owner to withdraw accrued USDC. Accrual is calculated linearly: (Amount * elapsedSeconds) / duration.

refundExpired(uint256 intentId)approx. 30,000 gas units

Allows either the payer or bot owner to unlock and claim remaining unstreamed funds once the stream duration expires or if the intent was never authorized.

Contract Events Log

Indexer nodes poll the following event signatures to update database webhooks:

event BotRegistered(uint256 indexed botId, string name, address indexed owner, string endpoint, uint256 timestamp);
event BotDeactivated(uint256 indexed botId, uint256 timestamp);
event PaymentIntentCreated(uint256 indexed intentId, uint256 indexed botId, uint256 amount, uint256 duration, bytes32 memo, uint256 timestamp);
event PaymentAuthorized(uint256 indexed intentId, address indexed payer, uint256 amount, uint256 timestamp);
event StreamClaimed(uint256 indexed intentId, uint256 indexed botId, address indexed botOwner, uint256 claimedAmount, uint256 totalClaimed, uint256 timestamp);
event PaymentCompleted(uint256 indexed intentId, uint256 indexed botId, uint256 totalAmount, uint256 timestamp);
event PaymentRefunded(uint256 indexed intentId, address indexed payer, uint256 refundAmount, uint256 timestamp);

Suggested Actions