Skip to main content

​
Overview

You can create custom conditions for specialized logic beyond what the built-in conditions provide. Build against the ICondition interface and follow the security rules below.

​
ICondition Rules

From the ICondition.sol NatSpec:
  1. MUST NOT revert: return false to deny, never revert
  2. Return true to allow, false to deny
The operator converts a false return into a PreActionConditionNotMet revert. Prefer view or pure implementations to keep call sites cheap and gas predictable.

​
Example: TimeOfDayCondition

A condition that only allows actions during specific hours (UTC): 
contract TimeOfDayCondition is ICondition {
    uint256 public immutable startHour;  // e.g., 9 (9 AM)
    uint256 public immutable endHour;    // e.g., 17 (5 PM)

    constructor(uint256 _startHour, uint256 _endHour) {
        startHour = _startHour;
        endHour = _endHour;
    }

    function check(
        PaymentInfo calldata payment,
        uint256,
        address caller,
        bytes calldata
    ) external view returns (bool) {
        uint256 hour = (block.timestamp / 3600) % 24;
        return hour >= startHour && hour < endHour;
    }
}
Usage, deploy via a factory and use in operator config: 
// Deploy via your custom factory
const businessHours = await timeOfDayConditionFactory.write.deploy([9, 17]);

// Use in operator config
config.capturePreActionCondition = businessHours;

​
Security Checklist

Before deploying a custom condition:
  • Returns false instead of reverting on denial
  • Declared as view or pure
  • No external calls to untrusted contracts
  • No state modifications
  • Handles edge cases (zero address, zero amount, uninitialized payments)
  • Full test coverage with Forge tests
Custom conditions with bugs can lead to permanently locked funds (if check() always returns false) or unauthorized access (if check() always returns true). Test on Base Sepolia before mainnet deployment.

​
Testing

Test custom conditions with Forge: 
contract TimeOfDayConditionTest is Test {
    TimeOfDayCondition condition;

    function setUp() public {
        condition = new TimeOfDayCondition(9, 17);
    }

    function test_allowsDuringBusinessHours() public {
        // Set block.timestamp to 10 AM UTC
        vm.warp(10 * 3600);
        assertTrue(condition.check(paymentInfo, 0, caller, ""));
    }

    function test_deniesOutsideBusinessHours() public {
        // Set block.timestamp to 8 PM UTC
        vm.warp(20 * 3600);
        assertFalse(condition.check(paymentInfo, 0, caller, ""));
    }
}

​
Next Steps

Conditions Overview

Review the condition system architecture.

Custom Hooks

Build custom state hooks.