@querais/contracts 0.2.0

package/contracts/ProtocolTreasury.sol

@@ -0,0 +1,157 @@
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.28;
+
+import {IERC20} from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
+import {SafeERC20} from "@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol";
+import {ERC20Burnable} from "@openzeppelin/contracts/token/ERC20/extensions/ERC20Burnable.sol";
+import {AccessControl} from "@openzeppelin/contracts/access/AccessControl.sol";
+import {Pausable} from "@openzeppelin/contracts/utils/Pausable.sol";
+import {ReentrancyGuard} from "@openzeppelin/contracts/utils/ReentrancyGuard.sol";
+
+/**
+ * @title ProtocolTreasury
+ * @notice Slice 6A: protocol fees accumulate here as plain ERC-20 transfers (this
+ *         contract simply replaces the treasury EOA as the fee recipient — settlement
+ *         code is untouched), and a keeper-called `distribute()` executes the
+ *         tokenomics' 60/20/20 ops/staker/burn split in ONE tx per epoch.
+ *
+ * @dev Accumulate-and-sweep, NOT the spec's per-settlement `receiveFee`: splitting +
+ *      burning on every settlement would put token ops on the hot `batchSettle` path
+ *      for identical economics at far more gas. Until the staking pool exists (6B:
+ *      node-operator stakes — Option 1), the staker share parks here under
+ *      `stakerEarmarkWei`, which `allocate()` can never touch. Pausing blocks
+ *      `distribute()`/`allocate()`; the treasury holds protocol funds ONLY, so there
+ *      is deliberately no user exit path to keep open while paused.
+ */
+contract ProtocolTreasury is AccessControl, Pausable, ReentrancyGuard {
+    using SafeERC20 for IERC20;
+
+    // ─── Roles ────────────────────────────────────────────────────────────────
+    /// @notice May call distribute() — the gateway's hot key (the daily epoch keeper).
+    bytes32 public constant KEEPER_ROLE = keccak256("KEEPER_ROLE");
+    bytes32 public constant PAUSER_ROLE = keccak256("PAUSER_ROLE");
+
+    // ─── Split rates (tokenomics: 20% burn / 20% stakers / 60% ops) ───────────
+    uint16 public burnRateBps = 2000;
+    uint16 public stakerRateBps = 2000;
+
+    ERC20Burnable public immutable token;
+
+    /// @notice The 6B staking pool; address(0) until it exists (share parks here).
+    address public stakerPool;
+    /// @notice Staker share accrued while no pool is set. Never spendable via allocate().
+    uint256 public stakerEarmarkWei;
+    /// @notice The retained ops share (the 60%) — the only funds allocate() may spend.
+    ///         Tracked explicitly so a sweep never re-splits what an earlier sweep kept.
+    uint256 public opsRetainedWei;
+
+    // Audit counters (monotonic).
+    uint256 public totalDistributed;
+    uint256 public totalBurned;
+    uint256 public totalToStakers;
+    uint256 public totalAllocated;
+
+    // ─── Events ───────────────────────────────────────────────────────────────
+    event Distributed(uint256 pending, uint256 burned, uint256 toStakers, uint256 opsRetained);
+    event Allocated(address indexed recipient, uint256 amount, string purpose);
+    event RatesUpdated(uint16 burnRateBps, uint16 stakerRateBps);
+    event StakerPoolSet(address indexed pool, uint256 earmarkFlushed);
+
+    // ─── Errors ───────────────────────────────────────────────────────────────
+    error ZeroAddress();
+    error ZeroAmount();
+    error NothingToDistribute();
+    error RatesExceedTotal(uint16 burnBps, uint16 stakerBps);
+    error ExceedsSpendable(uint256 requested, uint256 spendable);
+
+    constructor(ERC20Burnable token_, address admin) {
+        if (address(token_) == address(0) || admin == address(0)) revert ZeroAddress();
+        token = token_;
+        _grantRole(DEFAULT_ADMIN_ROLE, admin);
+        _grantRole(PAUSER_ROLE, admin);
+    }
+
+    // ─── Views ────────────────────────────────────────────────────────────────
+
+    /// @notice Fees that arrived since the last sweep (earmark + retained ops are the
+    ///         already-swept remainder of the balance).
+    function pendingDistribution() public view returns (uint256) {
+        return token.balanceOf(address(this)) - stakerEarmarkWei - opsRetainedWei;
+    }
+
+    // ─── The epoch sweep ──────────────────────────────────────────────────────
+
+    /// @notice Execute the burn/staker/ops split over everything accrued since the
+    ///         last sweep. Ops = remainder (absorbs rounding — conservation is exact).
+    function distribute() external onlyRole(KEEPER_ROLE) nonReentrant whenNotPaused {
+        uint256 pending = pendingDistribution();
+        if (pending == 0) revert NothingToDistribute();
+
+        uint256 burnAmount = (pending * burnRateBps) / 10000;
+        uint256 stakerAmount = (pending * stakerRateBps) / 10000;
+        uint256 opsRetained = pending - burnAmount - stakerAmount;
+        bool payPool = stakerPool != address(0) && stakerAmount > 0;
+
+        // Effects — ALL state before any external call (CEI, the pinned design rule).
+        totalDistributed += pending;
+        totalBurned += burnAmount;
+        totalToStakers += stakerAmount;
+        opsRetainedWei += opsRetained;
+        if (!payPool && stakerAmount > 0) stakerEarmarkWei += stakerAmount; // parks until 6B
+
+        // Interactions. opsRetained simply stays in the balance, spendable via allocate().
+        if (burnAmount > 0) token.burn(burnAmount);
+        if (payPool) IERC20(address(token)).safeTransfer(stakerPool, stakerAmount);
+
+        emit Distributed(pending, burnAmount, stakerAmount, opsRetained);
+    }
+
+    // ─── Ops spending ─────────────────────────────────────────────────────────
+
+    /// @notice Spend from the retained ops share (grants, incentives, marketing).
+    ///         Can never dip into the staker earmark.
+    function allocate(address recipient, uint256 amount, string calldata purpose)
+        external
+        onlyRole(DEFAULT_ADMIN_ROLE)
+        nonReentrant
+        whenNotPaused
+    {
+        if (recipient == address(0)) revert ZeroAddress();
+        if (amount == 0) revert ZeroAmount();
+        if (amount > opsRetainedWei) revert ExceedsSpendable(amount, opsRetainedWei);
+
+        opsRetainedWei -= amount;
+        totalAllocated += amount;
+        IERC20(address(token)).safeTransfer(recipient, amount);
+        emit Allocated(recipient, amount, purpose);
+    }
+
+    // ─── Admin ────────────────────────────────────────────────────────────────
+
+    function setRates(uint16 burnBps, uint16 stakerBps) external onlyRole(DEFAULT_ADMIN_ROLE) {
+        if (uint32(burnBps) + uint32(stakerBps) > 10000) revert RatesExceedTotal(burnBps, stakerBps);
+        burnRateBps = burnBps;
+        stakerRateBps = stakerBps;
+        emit RatesUpdated(burnBps, stakerBps);
+    }
+
+    /// @notice Wire the 6B staking pool; any parked earmark flushes to it immediately.
+    function setStakerPool(address pool) external onlyRole(DEFAULT_ADMIN_ROLE) nonReentrant {
+        if (pool == address(0)) revert ZeroAddress();
+        stakerPool = pool;
+        uint256 flushed = stakerEarmarkWei;
+        if (flushed > 0) {
+            stakerEarmarkWei = 0;
+            IERC20(address(token)).safeTransfer(pool, flushed);
+        }
+        emit StakerPoolSet(pool, flushed);
+    }
+
+    function pause() external onlyRole(PAUSER_ROLE) {
+        _pause();
+    }
+
+    function unpause() external onlyRole(PAUSER_ROLE) {
+        _unpause();
+    }
+}

package/contracts/QUAISToken.sol

@@ -0,0 +1,27 @@
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.28;
+
+import {ERC20} from "@openzeppelin/contracts/token/ERC20/ERC20.sol";
+import {ERC20Burnable} from "@openzeppelin/contracts/token/ERC20/extensions/ERC20Burnable.sol";
+
+/**
+ * @title QUAISToken
+ * @notice The $QAIS utility token: fixed supply, no mint function after deployment.
+ *         Used as the payment medium (escrow) and node stake/collateral.
+ * @dev Burnable (holders and the protocol can permanently reduce supply). The full
+ *      60/20/20 treasury split is deferred; for the MVP the burn primitive exists and
+ *      protocol fees accrue to a treasury address handled by JobEscrow.
+ *
+ *      Total supply (1,000,000,000 QAIS) is minted once to `initialHolder` at
+ *      construction. There is intentionally no `mint` — supply can only ever decrease.
+ */
+contract QUAISToken is ERC20Burnable {
+    /// @notice Fixed total supply minted at construction: 1,000,000,000 * 1e18.
+    uint256 public constant INITIAL_SUPPLY = 1_000_000_000 ether;
+
+    /// @param initialHolder Receives the entire initial supply (the deployer/treasury bootstrap).
+    constructor(address initialHolder) ERC20("QueraIS Token", "QAIS") {
+        require(initialHolder != address(0), "QAIS: zero holder");
+        _mint(initialHolder, INITIAL_SUPPLY);
+    }
+}

package/contracts/StakingRewards.sol

@@ -0,0 +1,136 @@
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.28;
+
+import {IERC20} from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
+import {SafeERC20} from "@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol";
+import {AccessControl} from "@openzeppelin/contracts/access/AccessControl.sol";
+import {Pausable} from "@openzeppelin/contracts/utils/Pausable.sol";
+import {ReentrancyGuard} from "@openzeppelin/contracts/utils/ReentrancyGuard.sol";
+import {NodeRegistry} from "./NodeRegistry.sol";
+
+/**
+ * @title StakingRewards
+ * @notice Slice 6B (Option 1: node-operator stakes ARE the stakers). The treasury's
+ *         20% staker share flows here (`ProtocolTreasury.setStakerPool`); a keeper
+ *         epoch call credits it pro-rata to the ACTIVE staked nodes in `NodeRegistry`;
+ *         operators pull their earnings with `claim()`.
+ *
+ * @dev Discrete epoch crediting, computed fully on-chain: stakes change in the registry
+ *      without notifying anyone (register/addStake/slash/unbond), so continuous
+ *      Synthetix-style accrual would need registry hooks. Instead the active node set —
+ *      small and enumerable on-chain — is walked in one keeper tx. Known trade-off:
+ *      whoever is staked at sweep time gets that epoch's full pro-rata share (no
+ *      intra-epoch time-weighting); acceptable at daily epochs, revisit with Phase-4
+ *      trustlessness. Known scale limit: O(n) registry reads per epoch; the scale-out
+ *      path is a Merkle-epoch distributor, deferred with horizontal scale.
+ *      Pausing blocks crediting; `claim()` is deliberately NOT pausable — earned
+ *      rewards are a user exit and a pause can never trap funds.
+ */
+contract StakingRewards is AccessControl, Pausable, ReentrancyGuard {
+    using SafeERC20 for IERC20;
+
+    // ─── Roles ────────────────────────────────────────────────────────────────
+    /// @notice May call distributeEpoch() — the gateway's hot key (the epoch keeper).
+    bytes32 public constant KEEPER_ROLE = keccak256("KEEPER_ROLE");
+    bytes32 public constant PAUSER_ROLE = keccak256("PAUSER_ROLE");
+
+    IERC20 public immutable token;
+    NodeRegistry public immutable registry;
+
+    /// @notice Earned, unclaimed rewards per node-operator wallet. A token debt —
+    ///         it survives later slashes/unbonding (earned while staked).
+    mapping(address => uint256) public claimable;
+
+    // Audit counters (monotonic). balance − (credited − claimed) = pending rewards.
+    uint256 public totalCredited;
+    uint256 public totalClaimed;
+
+    // ─── Events ───────────────────────────────────────────────────────────────
+    event EpochDistributed(uint256 credited, uint256 activeNodes, uint256 totalActiveStake);
+    event Claimed(address indexed operator, uint256 amount);
+
+    // ─── Errors ───────────────────────────────────────────────────────────────
+    error ZeroAddress();
+    error NothingToCredit();
+    error NoActiveNodes();
+    error NothingToClaim();
+
+    constructor(IERC20 token_, NodeRegistry registry_, address admin) {
+        if (address(token_) == address(0) || address(registry_) == address(0) || admin == address(0))
+        {
+            revert ZeroAddress();
+        }
+        token = token_;
+        registry = registry_;
+        _grantRole(DEFAULT_ADMIN_ROLE, admin);
+        _grantRole(PAUSER_ROLE, admin);
+    }
+
+    // ─── Views ────────────────────────────────────────────────────────────────
+
+    /// @notice Staker-share funds that arrived but are not yet credited to operators.
+    function pendingRewards() public view returns (uint256) {
+        return token.balanceOf(address(this)) - (totalCredited - totalClaimed);
+    }
+
+    // ─── Epoch crediting ──────────────────────────────────────────────────────
+
+    /// @notice Credit everything pending pro-rata to the currently ACTIVE staked nodes.
+    ///         Division dust stays pending and rolls into the next epoch — the credited
+    ///         amounts always conserve exactly against what was swept in.
+    function distributeEpoch() external onlyRole(KEEPER_ROLE) nonReentrant whenNotPaused {
+        uint256 pending = pendingRewards();
+        if (pending == 0) revert NothingToCredit();
+        uint256 n = registry.activeNodeCount();
+        if (n == 0) revert NoActiveNodes(); // funds simply wait for the next epoch
+
+        // Read phase: collect the active set + stakes (registry views), THEN write —
+        // strict CEI even though the only external calls are reads of our own registry.
+        address[] memory wallets = new address[](n);
+        uint256[] memory stakes = new uint256[](n);
+        uint256 totalActiveStake = 0;
+        for (uint256 i; i < n; ++i) {
+            address wallet = registry.activeNodeAt(i);
+            uint256 stake = registry.getNode(wallet).stakeAmount;
+            wallets[i] = wallet;
+            stakes[i] = stake;
+            totalActiveStake += stake;
+        }
+        if (totalActiveStake == 0) revert NoActiveNodes();
+
+        uint256 credited = 0;
+        for (uint256 i; i < n; ++i) {
+            uint256 share = (pending * stakes[i]) / totalActiveStake;
+            if (share > 0) {
+                claimable[wallets[i]] += share;
+                credited += share;
+            }
+        }
+        totalCredited += credited;
+
+        emit EpochDistributed(credited, n, totalActiveStake);
+    }
+
+    // ─── Operator claims ──────────────────────────────────────────────────────
+
+    /// @notice Pull all earned rewards. Deliberately NOT pausable (user exit).
+    function claim() external nonReentrant {
+        uint256 amount = claimable[msg.sender];
+        if (amount == 0) revert NothingToClaim();
+
+        claimable[msg.sender] = 0;
+        totalClaimed += amount;
+        token.safeTransfer(msg.sender, amount);
+        emit Claimed(msg.sender, amount);
+    }
+
+    // ─── Admin ────────────────────────────────────────────────────────────────
+
+    function pause() external onlyRole(PAUSER_ROLE) {
+        _pause();
+    }
+
+    function unpause() external onlyRole(PAUSER_ROLE) {
+        _unpause();
+    }
+}

package/contracts/mocks/ReentrantBatchToken.sol

@@ -0,0 +1,47 @@
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.28;
+
+import {ERC20} from "@openzeppelin/contracts/token/ERC20/ERC20.sol";
+
+/**
+ * @title ReentrantBatchToken
+ * @notice Test-only malicious ERC-20: on its first outbound `transfer` it re-enters a target
+ *         with pre-armed calldata (e.g. CreditAccount.batchSettle) and bubbles up the nested
+ *         revert. Used to prove CreditAccount's nonReentrant guard + CEI ordering stop a
+ *         re-entrant settlement from double-spending a deposit.
+ * @dev NOT part of the deployed system — lives under contracts/mocks for tests only.
+ */
+contract ReentrantBatchToken is ERC20 {
+    address public target;
+    bytes public reentryData;
+    bool public armed;
+
+    constructor() ERC20("ReentrantBatch", "RB") {
+        _mint(msg.sender, 1_000_000_000 ether);
+    }
+
+    function mintTo(address to, uint256 amount) external {
+        _mint(to, amount);
+    }
+
+    /// @notice Arm the attack: the next `transfer` re-enters `target_` with `data_` once.
+    function arm(address target_, bytes calldata data_) external {
+        target = target_;
+        reentryData = data_;
+        armed = true;
+    }
+
+    function transfer(address to, uint256 amount) public override returns (bool) {
+        if (armed) {
+            armed = false; // single shot
+            (bool ok, bytes memory ret) = target.call(reentryData);
+            if (!ok) {
+                // Bubble the nested revert so the outer settlement reverts too.
+                assembly {
+                    revert(add(ret, 0x20), mload(ret))
+                }
+            }
+        }
+        return super.transfer(to, amount);
+    }
+}

package/contracts/mocks/ReentrantToken.sol

@@ -0,0 +1,45 @@
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.28;
+
+import {ERC20} from "@openzeppelin/contracts/token/ERC20/ERC20.sol";
+
+interface IReentryTarget {
+    function verifyAndRelease(bytes32 jobId) external;
+}
+
+/**
+ * @title ReentrantToken
+ * @notice Test-only malicious ERC-20: on its first outbound `transfer` it attempts to
+ *         re-enter JobEscrow.verifyAndRelease for the same job. Used to prove the
+ *         nonReentrant guard + CEI ordering prevent double settlement / draining.
+ * @dev NOT part of the deployed system — lives under contracts/mocks for tests only.
+ */
+contract ReentrantToken is ERC20 {
+    IReentryTarget public target;
+    bytes32 public jobId;
+    bool public armed;
+
+    constructor() ERC20("Reentrant", "RENT") {
+        _mint(msg.sender, 1_000_000_000 ether);
+    }
+
+    /// @notice Mint helper so tests can fund arbitrary accounts.
+    function mintTo(address to, uint256 amount) external {
+        _mint(to, amount);
+    }
+
+    /// @notice Arm the attack: the next `transfer` will re-enter `target` once.
+    function arm(address target_, bytes32 jobId_) external {
+        target = IReentryTarget(target_);
+        jobId = jobId_;
+        armed = true;
+    }
+
+    function transfer(address to, uint256 amount) public override returns (bool) {
+        if (armed) {
+            armed = false; // single shot
+            target.verifyAndRelease(jobId); // expected to revert via ReentrancyGuard
+        }
+        return super.transfer(to, amount);
+    }
+}

package/deployments/addresses.arbitrumSepolia.json

@@ -0,0 +1,20 @@
+{
+  "chainId": 421614,
+  "rpcUrl": "https://sepolia-rollup.arbitrum.io/rpc",
+  "contracts": {
+    "token": "0x5532663d4d4560d9923e30fb7230b82edcb25531",
+    "nodeRegistry": "0xe9674474f7450b8fdc88895f7646d0d5fc34e99a",
+    "jobEscrow": "0x9a8be9ad9f980e828757163780aea1ca46303267",
+    "creditAccount": "0xc148e3d305a35876d9df211dbc9ef944ab4c8191",
+    "disputeResolution": "0x546b548bf5401aad0a21e85ce750aad5e58d8013",
+    "protocolTreasury": "0x83acf7b9a8182a6398c1fd80d0e237011e903fa2",
+    "stakingRewards": "0x8fa6ec119ae18f0793d1ec0eb0525e9f6f6b648f"
+  },
+  "treasury": "0x83acf7b9a8182a6398c1fd80d0e237011e903fa2",
+  "accounts": {
+    "deployer": "0xc80a8137e57d494b195eda12f74d7df324f5b9d6",
+    "gateway": "0xc80a8137e57d494b195eda12f74d7df324f5b9d6",
+    "node": "0xc80a8137e57d494b195eda12f74d7df324f5b9d6",
+    "requester": "0xc80a8137e57d494b195eda12f74d7df324f5b9d6"
+  }
+}

package/deployments/addresses.localhost.json

@@ -0,0 +1,20 @@
+{
+  "chainId": 31337,
+  "rpcUrl": "http://127.0.0.1:8545",
+  "contracts": {
+    "token": "0x5fbdb2315678afecb367f032d93f642f64180aa3",
+    "nodeRegistry": "0x9fe46736679d2d9a65f0992f2272de9f3c7fa6e0",
+    "jobEscrow": "0xcf7ed3acca5a467e9e704c703e8d87f634fb0fc9",
+    "creditAccount": "0xdc64a140aa3e981100a9beca4e685f962f0cf6c9",
+    "disputeResolution": "0x5fc8d32690cc91d4c39d9d3abcbd16989f875707",
+    "protocolTreasury": "0xe7f1725e7734ce288f8367e1bb143e90bb3f0512",
+    "stakingRewards": "0x0165878a594ca255338adfa4d48449f69242eb8f"
+  },
+  "treasury": "0xe7f1725e7734ce288f8367e1bb143e90bb3f0512",
+  "accounts": {
+    "deployer": "0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266",
+    "gateway": "0x70997970c51812dc3a010c7d01b50e0d17dc79c8",
+    "node": "0x3c44cdddb6a900fa2b585dd299e03d12fa4293bc",
+    "requester": "0x90f79bf6eb2c4f870365e785982e1f101e93b906"
+  }
+}