@coti-io/coti-contracts 1.1.0 → 1.2.0

package/contracts/mocks/utils/mpc/Shift128TestsContract.sol

@@ -0,0 +1,36 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.19;
+
+import "../../../utils/mpc/MpcCore.sol";
+
+contract Shift128TestsContract {
+    uint128 shlResult;
+    uint128 shrResult;
+
+    function getShlResult() public view returns (uint128) {
+        return shlResult;
+    }
+
+    function getShrResult() public view returns (uint128) {
+        return shrResult;
+    }
+
+    function shlTest(uint128 a, uint8 shift) public returns (uint128) {
+        gtUint128 a128 = MpcCore.setPublic128(a);
+        
+        uint128 result = uint128(MpcCore.decrypt(MpcCore.shl(a128, shift)));
+        shlResult = result;
+        
+        return result;
+    }
+
+    function shrTest(uint128 a, uint8 shift) public returns (uint128) {
+        gtUint128 a128 = MpcCore.setPublic128(a);
+        
+        uint128 result = uint128(MpcCore.decrypt(MpcCore.shr(a128, shift)));
+        shrResult = result;
+        
+        return result;
+    }
+}
+

package/contracts/mocks/utils/mpc/Shift256TestsContract.sol

@@ -0,0 +1,36 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.19;
+
+import "../../../utils/mpc/MpcCore.sol";
+
+contract Shift256TestsContract {
+    uint256 shlResult;
+    uint256 shrResult;
+
+    function getShlResult() public view returns (uint256) {
+        return shlResult;
+    }
+
+    function getShrResult() public view returns (uint256) {
+        return shrResult;
+    }
+
+    function shlTest(uint256 a, uint8 shift) public returns (uint256) {
+        gtUint256 a256 = MpcCore.setPublic256(a);
+        
+        uint256 result = MpcCore.decrypt(MpcCore.shl(a256, shift));
+        shlResult = result;
+        
+        return result;
+    }
+
+    function shrTest(uint256 a, uint8 shift) public returns (uint256) {
+        gtUint256 a256 = MpcCore.setPublic256(a);
+        
+        uint256 result = MpcCore.decrypt(MpcCore.shr(a256, shift));
+        shrResult = result;
+        
+        return result;
+    }
+}
+

package/contracts/mocks/utils/mpc/Transfer128TestsContract.sol

@@ -0,0 +1,29 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.19;
+
+import "../../../utils/mpc/MpcCore.sol";
+
+contract Transfer128TestsContract {
+    uint128 newA;
+    uint128 newB;
+    bool result;
+
+    function getResults() public view returns (uint128, uint128, bool) {
+        return (newA, newB, result);
+    }
+
+    function transferTest(uint128 a, uint128 b, uint128 amount) public returns (uint128, uint128, bool) {
+        gtUint128 a128 = MpcCore.setPublic128(a);
+        gtUint128 b128 = MpcCore.setPublic128(b);
+        gtUint128 amount128 = MpcCore.setPublic128(amount);
+        
+        (gtUint128 newA128, gtUint128 newB128, gtBool res) = MpcCore.transfer(a128, b128, amount128);
+        
+        newA = uint128(MpcCore.decrypt(newA128));
+        newB = uint128(MpcCore.decrypt(newB128));
+        result = MpcCore.decrypt(res);
+        
+        return (newA, newB, result);
+    }
+}
+

package/contracts/mocks/utils/mpc/Transfer256TestsContract.sol

@@ -0,0 +1,29 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.19;
+
+import "../../../utils/mpc/MpcCore.sol";
+
+contract Transfer256TestsContract {
+    uint256 newA;
+    uint256 newB;
+    bool result;
+
+    function getResults() public view returns (uint256, uint256, bool) {
+        return (newA, newB, result);
+    }
+
+    function transferTest(uint256 a, uint256 b, uint256 amount) public returns (uint256, uint256, bool) {
+        gtUint256 a256 = MpcCore.setPublic256(a);
+        gtUint256 b256 = MpcCore.setPublic256(b);
+        gtUint256 amount256 = MpcCore.setPublic256(amount);
+        
+        (gtUint256 newA256, gtUint256 newB256, gtBool res) = MpcCore.transfer(a256, b256, amount256);
+        
+        newA = MpcCore.decrypt(newA256);
+        newB = MpcCore.decrypt(newB256);
+        result = MpcCore.decrypt(res);
+        
+        return (newA, newB, result);
+    }
+}
+

package/contracts/mocks/utils/mpc/TransferWithAllowance128TestsContract.sol

@@ -0,0 +1,32 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.19;
+
+import "../../../utils/mpc/MpcCore.sol";
+
+contract TransferWithAllowance128TestsContract {
+    uint128 newA;
+    uint128 newB;
+    bool result;
+    uint128 newAllowance;
+
+    function getResults() public view returns (uint128, uint128, bool, uint128) {
+        return (newA, newB, result, newAllowance);
+    }
+
+    function transferWithAllowanceTest(uint128 a, uint128 b, uint128 amount, uint128 allowance) public returns (uint128, uint128, bool, uint128) {
+        gtUint128 a128 = MpcCore.setPublic128(a);
+        gtUint128 b128 = MpcCore.setPublic128(b);
+        gtUint128 amount128 = MpcCore.setPublic128(amount);
+        gtUint128 allowance128 = MpcCore.setPublic128(allowance);
+        
+        (gtUint128 newA128, gtUint128 newB128, gtBool res, gtUint128 newAllowance128) = MpcCore.transferWithAllowance(a128, b128, amount128, allowance128);
+        
+        newA = uint128(MpcCore.decrypt(newA128));
+        newB = uint128(MpcCore.decrypt(newB128));
+        result = MpcCore.decrypt(res);
+        newAllowance = uint128(MpcCore.decrypt(newAllowance128));
+        
+        return (newA, newB, result, newAllowance);
+    }
+}
+

package/contracts/mocks/utils/mpc/TransferWithAllowance256TestsContract.sol

@@ -0,0 +1,32 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.19;
+
+import "../../../utils/mpc/MpcCore.sol";
+
+contract TransferWithAllowance256TestsContract {
+    uint256 newA;
+    uint256 newB;
+    bool result;
+    uint256 newAllowance;
+
+    function getResults() public view returns (uint256, uint256, bool, uint256) {
+        return (newA, newB, result, newAllowance);
+    }
+
+    function transferWithAllowanceTest(uint256 a, uint256 b, uint256 amount, uint256 allowance) public returns (uint256, uint256, bool, uint256) {
+        gtUint256 a256 = MpcCore.setPublic256(a);
+        gtUint256 b256 = MpcCore.setPublic256(b);
+        gtUint256 amount256 = MpcCore.setPublic256(amount);
+        gtUint256 allowance256 = MpcCore.setPublic256(allowance);
+        
+        (gtUint256 newA256, gtUint256 newB256, gtBool res, gtUint256 newAllowance256) = MpcCore.transferWithAllowance(a256, b256, amount256, allowance256);
+        
+        newA = MpcCore.decrypt(newA256);
+        newB = MpcCore.decrypt(newB256);
+        result = MpcCore.decrypt(res);
+        newAllowance = MpcCore.decrypt(newAllowance256);
+        
+        return (newA, newB, result, newAllowance);
+    }
+}
+

package/contracts/mocks/utils/mpc/ValidateCiphertext128TestsContract.sol

@@ -0,0 +1,59 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.19;
+
+import "../../../utils/mpc/MpcCore.sol";
+
+/**
+ * @title ValidateCiphertext128TestsContract
+ * @notice Simple contract to test buildInputText with 128-bit values via Wallet.encryptValue
+ * @dev Validates itUint128 and returns ctUint128 via offBoardToUser
+ */
+contract ValidateCiphertext128TestsContract {
+    
+    // Events
+    event ValueValidated(address indexed user, string operation);
+    event ValueOffBoarded128(address indexed user, ctUint128 result);
+    
+    /**
+     * @dev Validates an encrypted uint128 input and returns it encrypted for user
+     * @param input The encrypted uint128 input (itUint128)
+     * @return The encrypted value for the user (ctUint128)
+     */
+    function validateAndReturn(itUint128 calldata input) external returns (ctUint128) {
+        // Validate the ciphertext and convert to gtUint128
+        gtUint128 validatedValue = MpcCore.validateCiphertext(input);
+        
+        emit ValueValidated(msg.sender, "validateAndReturn");
+        
+        // OffBoard to user (GT → CT for user to decrypt)
+        ctUint128 ctResult = MpcCore.offBoardToUser(validatedValue, msg.sender);
+        
+        emit ValueOffBoarded128(msg.sender, ctResult);
+        
+        return ctResult;
+    }
+    
+    /**
+     * @dev Validates and adds two encrypted uint128 values
+     * @param a First encrypted value (itUint128)
+     * @param b Second encrypted value (itUint128)
+     * @return The result encrypted for the user (ctUint128)
+     */
+    function validateAndAdd(itUint128 calldata a, itUint128 calldata b) external returns (ctUint128) {
+        // Validate both inputs
+        gtUint128 gtA = MpcCore.validateCiphertext(a);
+        gtUint128 gtB = MpcCore.validateCiphertext(b);
+        
+        emit ValueValidated(msg.sender, "validateAndAdd");
+        
+        // Perform addition
+        gtUint128 result = MpcCore.add(gtA, gtB);
+        
+        // OffBoard to user
+        ctUint128 ctResult = MpcCore.offBoardToUser(result, msg.sender);
+        
+        emit ValueOffBoarded128(msg.sender, ctResult);
+        
+        return ctResult;
+    }
+}

package/contracts/mocks/utils/mpc/ValidateCiphertext256TestsContract.sol

@@ -0,0 +1,63 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.19;
+
+import "../../../utils/mpc/MpcCore.sol";
+
+contract ValidateCiphertext256TestsContract {
+    uint256 storedValue;
+    bool validationResult;
+    ctUint256 storedEncryptedValue;
+
+    function getStoredValue() public view returns (uint256) {
+        return storedValue;
+    }
+
+    function getValidationResult() public view returns (bool) {
+        return validationResult;
+    }
+
+    function getStoredEncryptedValue() public view returns (ctUint256 memory) {
+        return storedEncryptedValue;
+    }
+
+    /**
+     * @dev Validates an encrypted uint256 input and stores the decrypted value
+     * @param input The encrypted uint256 input (itUint256)
+     * @return The decrypted uint256 value
+     */
+    function validateAndStore(itUint256 memory input) public returns (uint256) {
+        // Validate the ciphertext and convert to gtUint256
+        gtUint256 validatedValue = MpcCore.validateCiphertext(input);
+        
+        // Store the encrypted value as ctUint256 (offBoard from gtUint256)
+        storedEncryptedValue = MpcCore.offBoard(validatedValue);
+        
+        // Decrypt the value to store it
+        uint256 decryptedValue = MpcCore.decrypt(validatedValue);
+        
+        storedValue = decryptedValue;
+        validationResult = true;
+        
+        return decryptedValue;
+    }
+
+    /**
+     * @dev Validates an encrypted uint256 input and performs a simple operation (add 1)
+     * @param input The encrypted uint256 input (itUint256)
+     * @return The result after adding 1
+     */
+    function validateAndIncrement(itUint256 memory input) public returns (uint256) {
+        // Validate the ciphertext and convert to gtUint256
+        gtUint256 validatedValue = MpcCore.validateCiphertext(input);
+        
+        // Add 1 to the value
+        gtUint256 one = MpcCore.setPublic256(1);
+        gtUint256 result = MpcCore.add(validatedValue, one);
+        
+        // Decrypt and return
+        uint256 decryptedResult = MpcCore.decrypt(result);
+        
+        return decryptedResult;
+    }
+}
+

package/contracts/mocks/utils/mpc/ValidateCiphertextTestsContract.sol

@@ -0,0 +1,99 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.19;
+
+import "../../../utils/mpc/MpcCore.sol";
+
+/**
+ * @title ValidateCiphertextTestsContract
+ * @notice Contract to test validateCiphertext for 8/16/32/64-bit values
+ * @dev Validates itUint (8/16/32/64-bit) and returns ctUint via offBoardToUser
+ */
+contract ValidateCiphertextTestsContract {
+    
+    // Events
+    event ValueValidated(address indexed user, string operation);
+    event ValueOffBoarded(address indexed user, ctUint8 result);
+    
+    uint8 storedValue;
+    bool validationResult;
+    ctUint8 storedEncryptedValue;
+    
+    function getStoredValue() public view returns (uint8) {
+        return storedValue;
+    }
+    
+    function getValidationResult() public view returns (bool) {
+        return validationResult;
+    }
+    
+    function getStoredEncryptedValue() public view returns (ctUint8) {
+        return storedEncryptedValue;
+    }
+    
+    /**
+     * @dev Validates an encrypted uint8 input and returns it encrypted for user
+     * @param input The encrypted input (itUint8)
+     * @return The encrypted value for the user (ctUint8)
+     */
+    function validateAndReturn(itUint8 calldata input) external returns (ctUint8) {
+        // Validate the ciphertext and convert to gtUint8
+        gtUint8 validatedValue = MpcCore.validateCiphertext(input);
+        
+        emit ValueValidated(msg.sender, "validateAndReturn");
+        
+        // OffBoard to user (GT → CT for user to decrypt)
+        ctUint8 ctResult = MpcCore.offBoardToUser(validatedValue, msg.sender);
+        
+        emit ValueOffBoarded(msg.sender, ctResult);
+        
+        return ctResult;
+    }
+    
+    /**
+     * @dev Validates an encrypted input and stores the decrypted value
+     * @param input The encrypted input (itUint8)
+     * @return The decrypted uint8 value
+     */
+    function validateAndStore(itUint8 calldata input) external returns (uint8) {
+        // Validate the ciphertext and convert to gtUint8
+        gtUint8 validatedValue = MpcCore.validateCiphertext(input);
+        
+        // Store the encrypted value as ctUint8 (offBoard from gtUint8)
+        storedEncryptedValue = MpcCore.offBoard(validatedValue);
+        
+        // Decrypt the value to store it
+        uint8 decryptedValue = MpcCore.decrypt(validatedValue);
+        
+        storedValue = decryptedValue;
+        validationResult = true;
+        
+        emit ValueValidated(msg.sender, "validateAndStore");
+        
+        return decryptedValue;
+    }
+    
+    /**
+     * @dev Validates and adds two encrypted values
+     * @param a First encrypted value (itUint8)
+     * @param b Second encrypted value (itUint8)
+     * @return The result encrypted for the user (ctUint8)
+     */
+    function validateAndAdd(itUint8 calldata a, itUint8 calldata b) external returns (ctUint8) {
+        // Validate both inputs
+        gtUint8 gtA = MpcCore.validateCiphertext(a);
+        gtUint8 gtB = MpcCore.validateCiphertext(b);
+        
+        emit ValueValidated(msg.sender, "validateAndAdd");
+        
+        // Perform addition
+        gtUint8 result = MpcCore.add(gtA, gtB);
+        
+        // OffBoard to user
+        ctUint8 ctResult = MpcCore.offBoardToUser(result, msg.sender);
+        
+        emit ValueOffBoarded(msg.sender, ctResult);
+        
+        return ctResult;
+    }
+}
+

package/contracts/mocks/wallet/PrivateERC20Wallet/PrivateERC20WalletMock.sol

@@ -3,6 +3,7 @@
 pragma solidity ^0.8.19;
 
 import "../../../token/PrivateERC20/IPrivateERC20.sol";
+import "../../../utils/mpc/MpcCore.sol";
 
 contract PrivateERC20WalletMock {
     constructor() {}
@@ -11,15 +12,15 @@ contract PrivateERC20WalletMock {
         return IPrivateERC20(token).setAccountEncryptionAddress(accountEncryptionAddress);
     }
 
-    function transfer(address token, address to, uint64 value) public returns (gtBool) {
-        return IPrivateERC20(token).transfer(to, MpcCore.setPublic64(value));
+    function transfer(address token, address to, uint256 value) public {
+        IPrivateERC20(token).transfer(to, value);
     }
 
-    function approve(address token, address spender, uint64 value) public returns (bool) {
-        return IPrivateERC20(token).approve(spender, MpcCore.setPublic64(value));
+    function approve(address token, address spender, uint256 value) public {
+        IPrivateERC20(token).approve(spender, value);
     }
 
-    function transferFrom(address token, address from, address to, uint64 value) public returns (gtBool) {
-        return IPrivateERC20(token).transferFrom(from, to, MpcCore.setPublic64(value));
+    function transferFrom(address token, address from, address to, uint256 value) public {
+        IPrivateERC20(token).transferFrom(from, to, value);
     }
 }

package/contracts/node/CotiNodeRewards.sol

@@ -0,0 +1,199 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.19;
+
+import {Ownable} from "@openzeppelin/contracts/access/Ownable.sol";
+import {ReentrancyGuard} from "@openzeppelin/contracts/security/ReentrancyGuard.sol";
+
+/**
+ * @title CotiNodeRewards
+ * @notice Manages eligibility rules and native COTI rewards for the COTI node ecosystem.
+ * @dev COTI is the chain's native token (like ETH). Owner funds the contract by sending native COTI,
+ *      sets eligibility rules, allocates claimable rewards; users claim and receive native COTI.
+ * @dev Decimals: USDC = 6 ({DECIMALS_USDC}), native COTI = 18 ({DECIMALS_COTI}). Reward amounts are in COTI wei.
+ */
+contract CotiNodeRewards is Ownable, ReentrancyGuard {
+
+    // ============ Decimals ============
+    /// @notice USDC uses 6 decimals (amounts in eligibility rules for USDC are in 10^6 units)
+    uint8 public constant DECIMALS_USDC = 6;
+    /// @notice Native COTI uses 18 decimals (reward amounts and contract balance are in wei, 10^18 units)
+    uint8 public constant DECIMALS_COTI = 18;
+
+    // ============ Eligibility rules: rule name (bytes32) => value ============
+    /// @dev Use getEligibilityRule(string) or predefined keys (e.g. PLATFORM_USDC_AMOUNT)
+    mapping(bytes32 => uint256) public eligibilityRules;
+
+    /// @notice Predefined rule key: Platform USDC amount (value in USDC smallest unit, 6 decimals; e.g. 10 * 10^6 = 10 USDC)
+    bytes32 public constant RULE_PLATFORM_USDC_AMOUNT = keccak256("RULE_PLATFORM_USDC_AMOUNT");
+    /// @notice Predefined rule key: Platform COTI amount (value in COTI smallest unit, 18 decimals; e.g. 5e18 = 5 COTI)
+    bytes32 public constant RULE_PLATFORM_COTI_AMOUNT = keccak256("RULE_PLATFORM_COTI_AMOUNT");
+    /// @notice Predefined rule key: Full node uptime percentage threshold (e.g. 98 for 98%)
+    bytes32 public constant RULE_FULL_NODE_UPTIME_PERCENTAGE_THRESHOLD = keccak256("RULE_FULL_NODE_UPTIME_PERCENTAGE_THRESHOLD");
+
+    // ============ Reward state ============
+    /// @notice Per address: total COTI ever claimed by this address
+    mapping(address => uint256) public totalPerAddressClaimedCotiToken;
+    /// @notice Per address: COTI currently claimable (not yet claimed)
+    mapping(address => uint256) public totalPerAddressClaimableCotiToken;
+    /// @notice Per address: last epoch in which this wallet was rewarded (used to prevent double rewards per epoch)
+    mapping(address => uint256) public lastRewardEpoch;
+
+    /// @notice Total COTI ever allocated as claimable (sum of all rewards ever added)
+    uint256 public totalRewardedCoti;
+    /// @notice Total COTI ever claimed by all users
+    uint256 public totalClaimedCoti;
+    /// @notice Sum of all current claimable amounts (invariant: contract native balance must be >= this)
+    uint256 public totalClaimableCoti;
+
+    // ============ Events ============
+    event EligibilityRuleSet(bytes32 indexed ruleKey, uint256 value);
+    event RewardAdded(address indexed wallet, uint256 amount);
+    event Claimed(address indexed wallet, uint256 amount);
+
+    error ZeroAddress();
+    error ZeroAmount();
+    error InsufficientContractBalance();
+    error NothingToClaim();
+    error ArrayLengthMismatch();
+    error TransferFailed();
+    error AlreadyRewardedInEpoch(address wallet, uint256 epoch);
+    error InvalidEpoch(uint256 epoch);
+
+    constructor() Ownable() {
+        eligibilityRules[RULE_PLATFORM_COTI_AMOUNT] = 100_000 * 10**DECIMALS_COTI;   // 100k COTI
+        eligibilityRules[RULE_PLATFORM_USDC_AMOUNT] = 50_000 * 10**DECIMALS_USDC;    // 50k USDC
+        eligibilityRules[RULE_FULL_NODE_UPTIME_PERCENTAGE_THRESHOLD] = 98;          // 98%
+    }
+
+    /// @notice Accept native COTI so the contract can be funded for rewards.
+    receive() external payable {}
+
+    // ============ Eligibility rules (owner) ============
+
+    /**
+     * @notice Set an eligibility rule by key and value.
+     * @param ruleKey Rule identifier (use constants or keccak256("name"))
+     * @param value Rule value (e.g. threshold, amount in smallest units)
+     */
+    function setEligibilityRule(bytes32 ruleKey, uint256 value) external onlyOwner {
+        eligibilityRules[ruleKey] = value;
+        emit EligibilityRuleSet(ruleKey, value);
+    }
+
+    /**
+     * @notice Get eligibility rule value by string name (e.g. "Platform_USDC_amount").
+     */
+    function getEligibilityRule(string calldata ruleName) external view returns (uint256) {
+        return eligibilityRules[keccak256(bytes(ruleName))];
+    }
+
+    // ============ Reward allocation (owner) ============
+
+    /**
+     * @dev Increases the claimable native COTI amount for a wallet for a specific epoch. Owner only.
+     *      Each wallet can only be rewarded once per epoch, and epochs must be strictly increasing per wallet.
+     *      Contract must have sufficient native balance to cover existing claimable + new amount.
+     * @param wallet Address to reward
+     * @param amount Native COTI amount in wei (18 decimals, {DECIMALS_COTI}) to add to claimable
+     * @param epoch  Logical epoch identifier for this reward (must be greater than the wallet's lastRewardEpoch)
+     */
+    function rewardWallet(address wallet, uint256 amount, uint256 epoch) external onlyOwner {
+        if (wallet == address(0)) revert ZeroAddress();
+        if (amount == 0) revert ZeroAmount();
+        if (epoch == 0) revert InvalidEpoch(epoch);
+        if (epoch <= lastRewardEpoch[wallet]) revert AlreadyRewardedInEpoch(wallet, epoch);
+
+        uint256 newTotalClaimable = totalClaimableCoti + amount;
+        if (address(this).balance < newTotalClaimable) revert InsufficientContractBalance();
+
+        totalPerAddressClaimableCotiToken[wallet] += amount;
+        totalClaimableCoti = newTotalClaimable;
+        totalRewardedCoti += amount;
+        lastRewardEpoch[wallet] = epoch;
+
+        emit RewardAdded(wallet, amount);
+    }
+
+    /**
+     * @notice Add claimable rewards for multiple wallets in one call, for a specific epoch. Owner only.
+     *         Each wallet can only be rewarded once per epoch, and epochs must be strictly increasing per wallet.
+     * @param wallets Addresses to reward
+     * @param amounts Native COTI amounts in wei to add to claimable for each wallet
+     * @param epoch   Logical epoch identifier for this reward batch
+     */
+    function rewardWallets(address[] calldata wallets, uint256[] calldata amounts, uint256 epoch) external onlyOwner {
+        uint256 len = wallets.length;
+        if (len != amounts.length) revert ArrayLengthMismatch();
+        if (epoch == 0) revert InvalidEpoch(epoch);
+
+        uint256 added;
+        for (uint256 i; i < len; ) {
+            address wallet = wallets[i];
+            uint256 amount = amounts[i];
+            if (wallet == address(0)) revert ZeroAddress();
+            if (amount != 0) {
+                if (epoch <= lastRewardEpoch[wallet]) revert AlreadyRewardedInEpoch(wallet, epoch);
+                totalPerAddressClaimableCotiToken[wallet] += amount;
+                added += amount;
+                lastRewardEpoch[wallet] = epoch;
+                emit RewardAdded(wallet, amount);
+            }
+            unchecked { ++i; }
+        }
+        if (added != 0) {
+            uint256 newTotalClaimable = totalClaimableCoti + added;
+            if (address(this).balance < newTotalClaimable) revert InsufficientContractBalance();
+            totalClaimableCoti = newTotalClaimable;
+            totalRewardedCoti += added;
+        }
+    }
+
+    // ============ Claim (user) ============
+
+    /**
+     * @dev Lets msg.sender claim their claimable native COTI. Reduces total_per_address_claimable_Coti_token
+     *      and adds the claimed amount to total_per_address_claimed_coti_token; sends native COTI (18 decimals) to the user.
+     */
+    function claimReward() external nonReentrant {
+        uint256 amount = totalPerAddressClaimableCotiToken[msg.sender];
+        if (amount == 0) revert NothingToClaim();
+
+        totalPerAddressClaimableCotiToken[msg.sender] = 0;
+        totalPerAddressClaimedCotiToken[msg.sender] += amount;
+        totalClaimableCoti -= amount;
+        totalClaimedCoti += amount;
+
+        (bool success, ) = payable(msg.sender).call{value: amount}("");
+        if (!success) revert TransferFailed();
+        emit Claimed(msg.sender, amount);
+    }
+
+    /**
+     * @notice Returns the claimable COTI amount for the caller.
+     */
+    function claimableOf(address account) external view returns (uint256) {
+        return totalPerAddressClaimableCotiToken[account];
+    }
+
+    // ============ Admin withdrawal ============
+
+    /**
+     * @notice Withdraw excess native COTI that is not reserved for current rewards.
+     * @dev Ensures that after withdrawal, the contract still holds at least `totalClaimableCoti`.
+     * @param to Recipient address for the withdrawn native COTI.
+     * @param amount Native COTI amount in wei to withdraw.
+     */
+    function withdrawExcess(address payable to, uint256 amount) external onlyOwner {
+        if (to == address(0)) revert ZeroAddress();
+        if (amount == 0) revert ZeroAmount();
+
+        uint256 balance = address(this).balance;
+        if (balance < totalClaimableCoti) revert InsufficientContractBalance();
+
+        uint256 available = balance - totalClaimableCoti;
+        if (amount > available) revert InsufficientContractBalance();
+
+        (bool success, ) = to.call{value: amount}("");
+        if (!success) revert TransferFailed();
+    }
+}