Smart contracts

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.24;

/// @title Agent Swarm agent registry (draft)
/// @notice Identity, manifest, keys, bond and reputation counters for every agent.
interface IAgentRegistry {
    struct Agent {
        address operator;      // cold key: configuration and withdrawals
        address agentKey;      // hot key: signs quotes and deliveries
        address payout;        // receives settled payouts and released bond
        bytes32 manifestHash;  // keccak256 of the canonical manifest JSON
        string manifestURI;    // ipfs://...
        uint256 bond;          // USDC base units
        uint64 registeredAt;
        uint64 bondReleaseAt;  // 0 while active
        bool active;
    }

    struct Stats {
        uint64 jobsCompleted;  // funded jobs that reached a final state
        uint64 jobsOnTime;     // delivered before deliverBy and not lost in a dispute
        uint64 disputesLost;   // resolutions with any refund or slash
        uint256 volume;        // gross USDC settled to this agent as seller
    }

    event AgentRegistered(uint256 indexed agentId, address indexed operator, address agentKey, string manifestURI, bytes32 manifestHash);
    event ManifestUpdated(uint256 indexed agentId, string manifestURI, bytes32 manifestHash);
    event AgentKeyRotated(uint256 indexed agentId, address indexed oldKey, address indexed newKey);
    event PayoutChanged(uint256 indexed agentId, address payout);
    event OperatorTransferStarted(uint256 indexed agentId, address indexed pendingOperator);
    event OperatorTransferred(uint256 indexed agentId, address indexed newOperator);
    event BondChanged(uint256 indexed agentId, uint256 bond);
    event BondSlashed(uint256 indexed agentId, bytes32 indexed jobId, uint256 amount, address to);
    event AgentDeactivated(uint256 indexed agentId, uint64 bondReleaseAt);
    event AgentReactivated(uint256 indexed agentId);
    event StatsUpdated(uint256 indexed agentId, Stats stats);

    error NotOperator(uint256 agentId);
    error NotEscrow();
    error AgentInactive(uint256 agentId);
    error BondInsufficient(uint256 required, uint256 provided);
    error BondLocked(uint64 releaseAt);
    error OpenDisputes(uint256 agentId);
    error KeyInUse(address agentKey);
    error InvalidManifest();

    /// @notice Register a new service agent. Pulls `bond` USDC from msg.sender, who becomes the operator.
    /// @dev Reverts with BondInsufficient if bond < minBond(). Reverts with KeyInUse if agentKey is registered.
    function register(address agentKey, address payout, string calldata manifestURI, bytes32 manifestHash, uint256 bond)
        external
        returns (uint256 agentId);

    function updateManifest(uint256 agentId, string calldata manifestURI, bytes32 manifestHash) external;
    function rotateAgentKey(uint256 agentId, address newKey) external;
    function setPayout(uint256 agentId, address payout) external;

    /// @notice Two-step operator transfer. The pending operator must call acceptOperator.
    function transferOperator(uint256 agentId, address newOperator) external;
    function acceptOperator(uint256 agentId) external;

    function topUpBond(uint256 agentId, uint256 amount) external;

    /// @notice Stop taking jobs. Starts the bond release timer (draft: 7 days).
    function deactivate(uint256 agentId) external;
    function reactivate(uint256 agentId) external;

    /// @notice Withdraw the bond after bondReleaseAt. Reverts with OpenDisputes while any dispute is open.
    function withdrawBond(uint256 agentId) external;

    /// @notice Escrow only: update counters when a job reaches a final state.
    function recordOutcome(uint256 agentId, bool onTime, bool disputeLost, uint256 grossToSeller) external;

    /// @notice Escrow only: move up to `amount` of the bond to `to` as part of a dispute resolution.
    function slash(uint256 agentId, bytes32 jobId, uint256 amount, address to) external returns (uint256 slashed);

    function agent(uint256 agentId) external view returns (Agent memory);
    function stats(uint256 agentId) external view returns (Stats memory);
    function agentIdOf(address agentKey) external view returns (uint256);
    function minBond() external view returns (uint256);
    function isRoster(uint256 agentId) external view returns (bool);
}

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.24;

/// @title Agent Swarm job escrow (draft)
/// @notice Holds USDC for every job from funding to settlement, refund or resolution.
interface IJobEscrow {
    enum Status { None, Funded, Delivered, Settled, Disputed, Resolved, Refunded }

    struct Quote {
        bytes32 jobId;
        uint256 buyer;
        uint256 seller;
        bytes32 capability;   // keccak256 of the capability ID string
        bytes32 inputHash;    // keccak256 of the canonical JSON input
        uint256 price;        // USDC base units
        uint64 deliverBy;
        uint64 expiresAt;
    }

    struct Delivery {
        bytes32 jobId;
        bytes32 outputHash;
        string outputURI;
    }

    struct Job {
        uint256 buyer;
        uint256 seller;
        bytes32 capability;
        uint256 price;
        uint64 fundedAt;
        uint64 deliverBy;
        uint64 deliveredAt;
        bytes32 outputHash;
        Status status;
    }

    event JobFunded(bytes32 indexed jobId, uint256 indexed buyer, uint256 indexed seller, bytes32 capability, uint256 price, uint64 deliverBy);
    event JobDelivered(bytes32 indexed jobId, bytes32 outputHash, string outputURI, bool onTime);
    event JobVerified(bytes32 indexed jobId, address indexed verifier, bool automatic);
    event JobSettled(bytes32 indexed jobId, uint256 sellerPayout, uint256 fee);
    event JobDisputed(bytes32 indexed jobId, string reasonURI);
    event JobResolved(bytes32 indexed jobId, uint256 toSeller, uint256 toBuyer, uint256 slashed, string reasonURI);
    event JobRefunded(bytes32 indexed jobId, uint256 amount);
    event BuyerDeposited(uint256 indexed agentId, uint256 amount);
    event BuyerWithdrawn(uint256 indexed agentId, uint256 amount, address to);
    event SpendLimitSet(uint256 indexed agentId, uint256 perEpoch);

    error QuoteExpired();
    error SignatureInvalid();
    error JobExists(bytes32 jobId);
    error WrongStatus(bytes32 jobId, Status status);
    error DeadlineMissed(bytes32 jobId);
    error DeadlineNotReached(bytes32 jobId);
    error ChallengeWindowOpen(bytes32 jobId);
    error NotBuyer();
    error NotSeller();
    error NotVerifier();
    error NotResolver();
    error NotOperator();
    error InsufficientBalance(uint256 available, uint256 required);
    error SpendLimitExceeded(uint256 remaining, uint256 required);
    error AgentInactive(uint256 agentId);
    error InvalidSplit();

    /// @notice Fund a job from the buyer balance. Callable by the buyer agent key or the buyer's MandateModule.
    /// @dev Checks: seller signature by the seller's current agent key, block.timestamp <= expiresAt,
    ///      jobId unused, seller active, buyer balance and spend limit.
    function open(Quote calldata quote, bytes calldata sellerSig) external;

    /// @notice Record a delivery. Reverts with DeadlineMissed after deliverBy.
    /// @dev Anyone may relay; the signature must come from the seller's current agent key.
    function deliver(Delivery calldata delivery, bytes calldata sellerSig) external;

    /// @notice Verify and settle. Buyer agent key, or swarm:audit when the buyer is a roster agent.
    function verify(bytes32 jobId) external;

    /// @notice Settle a job up to autoVerifyMax() once challengeWindow() has passed without a dispute. Anyone may call.
    function settleAuto(bytes32 jobId) external;

    /// @notice Buyer disputes a delivered, unverified job.
    function dispute(bytes32 jobId, string calldata reasonURI) external;

    /// @notice Resolver splits the escrow. toSeller <= price; the rest goes back to the buyer balance.
    ///         slashAmount is taken from the seller bond and paid to the buyer.
    function resolve(bytes32 jobId, uint256 toSeller, uint256 slashAmount, string calldata reasonURI) external;

    /// @notice Buyer reclaims a funded job after deliverBy with no delivery. No fee.
    function refund(bytes32 jobId) external;

    function deposit(uint256 agentId, uint256 amount) external;
    function withdraw(uint256 agentId, uint256 amount, address to) external;
    function setSpendLimit(uint256 agentId, uint256 perEpoch) external;

    function job(bytes32 jobId) external view returns (Job memory);
    function buyerBalance(uint256 agentId) external view returns (uint256);
    function hashQuote(Quote calldata quote) external view returns (bytes32);
    function hashDelivery(Delivery calldata delivery) external view returns (bytes32);
    function feeBps() external view returns (uint16);          // draft: 100 (1%)
    function autoVerifyMax() external view returns (uint256);  // draft: 25 USDC
    function challengeWindow() external view returns (uint64); // draft: 15 minutes
}

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.24;

/// @title Agent Swarm ledger (draft)
/// @notice Append-only accounting entries for every settlement that touches the company, closed in daily epochs.
interface ILedger {
    enum Category { REVENUE, COST, INTERNAL, FEE }

    struct EpochReport {
        uint256 revenue;
        uint256 costs;
        uint256 internalVolume;
        uint256 fees;
        uint256 treasuryBalance;
        bytes32 entriesRoot;   // Merkle root of the epoch's entries, in index order
        uint64 closedAt;
    }

    event EntryRecorded(uint256 indexed index, bytes32 indexed jobId, Category indexed category, uint256 buyer, uint256 seller, uint256 amount, uint64 epoch);
    event EpochClosed(uint64 indexed epoch, uint256 revenue, uint256 costs, uint256 internalVolume, uint256 treasuryBalance, bytes32 entriesRoot);

    error NotEscrow();
    error NotAuditor();
    error EpochNotOver(uint64 epoch);
    error EpochAlreadyClosed(uint64 epoch);
    error EpochsOutOfOrder(uint64 expected);
    error TotalsMismatch();

    /// @notice Escrow only. Derives the category from the roster status of buyer and seller and writes
    ///         one job entry when a roster agent is involved, plus one FEE entry for every settled job.
    function record(bytes32 jobId, uint256 buyer, uint256 seller, uint256 amount, uint256 fee) external;

    /// @notice swarm:audit only. Reverts with TotalsMismatch unless revenue, costs and internalVolume equal
    ///         the running totals the ledger accumulated for that epoch, and treasuryBalance equals the
    ///         company's USDC holdings read on-chain at close.
    function closeEpoch(
        uint64 epoch,
        uint256 revenue,
        uint256 costs,
        uint256 internalVolume,
        uint256 treasuryBalance,
        bytes32 entriesRoot
    ) external;

    function epochOf(uint64 timestamp) external pure returns (uint64);  // timestamp / 1 days
    function currentEpoch() external view returns (uint64);
    function lastClosedEpoch() external view returns (uint64);
    function report(uint64 epoch) external view returns (EpochReport memory);
    function entryCount() external view returns (uint256);
}

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.24;

import {IJobEscrow} from "./IJobEscrow.sol";

/// @title Agent Swarm mandate module (draft)
/// @notice Spending rules for roster agents. Every roster purchase goes through openJob.
interface IMandateModule {
    struct Mandate {
        uint256 perEpochBudget;       // ceiling for the budget treasury may assign
        uint256 maxPerJob;
        bytes32[] allowedNamespaces;  // keccak256("compute"), keccak256("data"), ...
        uint16 minScore;              // applied by the agent runtime, see invariants
    }

    event MandateProposed(uint256 indexed agentId, Mandate mandate, uint64 effectiveAt);
    event MandateActivated(uint256 indexed agentId);
    event BudgetSet(uint256 indexed agentId, uint64 indexed epoch, uint256 amount);
    event Spent(uint256 indexed agentId, uint64 indexed epoch, bytes32 indexed jobId, uint256 amount);

    error MandateLimit(uint256 agentId, bytes32 reason);  // "BUDGET", "MAX_PER_JOB"
    error NamespaceNotAllowed(bytes32 namespaceHash);
    error CapabilityMismatch();
    error TimelockActive(uint64 effectiveAt);
    error NotGovernor();
    error NotTreasury();
    error NotRosterKey(uint256 agentId);

    /// @notice Governor proposes a new mandate. It takes effect after timelock() (draft: 48 hours).
    function proposeMandate(uint256 agentId, Mandate calldata mandate) external;

    /// @notice Anyone activates a proposed mandate once the timelock has passed.
    function activateMandate(uint256 agentId) external;

    /// @notice swarm:treasury sets an agent's budget for the current epoch, at most perEpochBudget.
    function setBudget(uint256 agentId, uint256 amount) external;

    /// @notice Roster agent key opens a job. Checks namespace, maxPerJob and remaining budget, then calls JobEscrow.open.
    /// @param capabilityId The plain capability ID; its keccak256 must equal quote.capability.
    function openJob(IJobEscrow.Quote calldata quote, bytes calldata sellerSig, string calldata capabilityId) external;

    function mandate(uint256 agentId) external view returns (Mandate memory);
    function budget(uint256 agentId, uint64 epoch) external view returns (uint256);
    function spent(uint256 agentId, uint64 epoch) external view returns (uint256);
    function timelock() external view returns (uint64);
}