PaymentOperator

​

Overview

• Type: Operator instance (one per fee recipient + configuration)
• Deployment: Via PaymentOperatorFactory
• Immutability: No pause switch, no upgrade path
• Configuration: 10 slots for conditions and hooks
• Use Cases: Marketplace, subscriptions, streaming, grants, custom flows

​

Immutable Fields

address public immutable ESCROW;              // AuthCaptureEscrow address
address public immutable FEE_RECEIVER;       // Operator fee recipient
ProtocolFeeConfig public immutable PROTOCOL_FEE_CONFIG; // Shared protocol fee config
IFeeCalculator public immutable FEE_CALCULATOR; // Operator fee calculator

​

State

// Fee tracking for accurate distribution
mapping(address token => uint256) public accumulatedProtocolFees;

// Fees locked at authorization time
mapping(bytes32 paymentInfoHash => AuthorizedFees) public authorizedFees;

​

10-Slot Configuration

​

Key Methods

​

authorize()

function authorize(
    AuthCaptureEscrow.PaymentInfo calldata paymentInfo,
    uint256 amount,
    address tokenCollector,
    bytes calldata collectorData
) external nonReentrant

• paymentInfo - Payment info struct (must have operator == address(this), feeReceiver == address(this))
• amount - Amount to authorize
• tokenCollector - Address of the token collector contract
• collectorData - Data to pass to the token collector

1. Check AUTHORIZE_PRE_ACTION_CONDITION (if set)
2. Check fee bounds compatibility
3. Store fees at authorization time (prevents protocol fee changes from breaking capture)
4. Call escrow.authorize()
5. Call AUTHORIZE_POST_ACTION_HOOK (if set)
6. Emit AuthorizeExecuted

​

charge()

function charge(
    AuthCaptureEscrow.PaymentInfo calldata paymentInfo,
    uint256 amount,
    address tokenCollector,
    bytes calldata collectorData
) external nonReentrant

• paymentInfo - Payment info struct (must have operator == address(this), feeReceiver == address(this))
• amount - Amount to charge
• tokenCollector - Address of the token collector contract
• collectorData - Data to pass to the token collector

1. Check CHARGE_PRE_ACTION_CONDITION (if set)
2. Check fee bounds compatibility
3. Call escrow.charge() - funds go directly to receiver
4. Accumulate protocol fees for later distribution
5. Call CHARGE_POST_ACTION_HOOK (if set)
6. Emit ChargeExecuted

​

capture()

function capture(
    AuthCaptureEscrow.PaymentInfo calldata paymentInfo,
    uint256 amount,
    bytes calldata data
) external nonReentrant

• paymentInfo - Payment info struct
• amount - Amount to capture
• data - Optional pass-through data for the pre/post action plugins

1. Check CAPTURE_PRE_ACTION_CONDITION (if set)
2. Use fees stored at authorization time
3. Call escrow.capture()
4. Accumulate protocol fees for later distribution
5. Call CAPTURE_POST_ACTION_HOOK (if set)
6. Emit CaptureExecuted

​

void()

function void(
    AuthCaptureEscrow.PaymentInfo calldata paymentInfo,
    bytes calldata data
) external nonReentrant

• paymentInfo - Payment info struct
• data - Optional pass-through data for the pre/post action plugins

1. Check VOID_PRE_ACTION_CONDITION (if set)
2. Call escrow.void() to return escrowed funds to payer
3. Call VOID_POST_ACTION_HOOK (if set)
4. Emit VoidExecuted

​

refund()

function refund(
    AuthCaptureEscrow.PaymentInfo calldata paymentInfo,
    uint256 amount,
    address tokenCollector,
    bytes calldata collectorData
) external nonReentrant

• paymentInfo - Payment info struct
• amount - Amount to refund to payer
• tokenCollector - Address of the token collector that will source the refund
• collectorData - Data to pass to the token collector (for example, signatures)

1. Check REFUND_PRE_ACTION_CONDITION (if set)
2. Call escrow.refund() - token collector enforces permission
3. Call REFUND_POST_ACTION_HOOK (if set)
4. Emit RefundExecuted

​

Fee System (Modular, Additive)

​

Fee Architecture

// Shared protocol fee config (timelocked, swappable calculator)
ProtocolFeeConfig public immutable PROTOCOL_FEE_CONFIG;

// Per-operator fee calculator (immutable, set at deploy)
IFeeCalculator public immutable FEE_CALCULATOR;

// Fee recipients
address public immutable FEE_RECEIVER;  // Operator fee recipient
// Protocol fee recipient is on ProtocolFeeConfig

// Fee tracking for accurate distribution
mapping(address token => uint256) public accumulatedProtocolFees;

struct AuthorizedFees {
    uint16 totalFeeBps;
    uint16 protocolFeeBps;
}
mapping(bytes32 paymentInfoHash => AuthorizedFees) public authorizedFees;

• Arbiter (marketplace with disputes)
• Service Provider (subscriptions)
• Platform Treasury (platform-controlled)
• DAO Multisig (governance-controlled)

​

Fee Distribution

// Anyone can call to distribute fees for a token
operator.distributeFees(usdcAddress);
// Protocol share -> protocolFeeRecipient
// Operator share -> FEE_RECEIVER

​

Protocol Fee Changes (7-day Timelock)

​

Security Features

• ReentrancyGuardTransient - EIP-1153 transient storage for gas-efficient reentrancy protection
• Ownership - Solady’s Ownable with 2-step transfer
• Timelock - 7-day delay on protocol fee changes (operator fees are immutable)
• Immutable Core - Escrow, conditions, and fee configuration stay fixed after deployment

​

Next Steps