PaymentOperator

​

Overview

• Type: Operator instance (one per fee recipient + configuration)
• Deployment: Via PaymentOperatorFactory
• Immutability: Cannot be paused or upgraded
• Configuration: 10 slots for conditions and recorders
• Use Cases: Marketplace, subscriptions, streaming, grants, custom flows

​

Immutable Fields

address public immutable ESCROW;              // AuthCaptureEscrow address
address public immutable FEE_RECIPIENT;       // 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_CONDITION (if set)
2. Validate fee bounds compatibility
3. Store fees at authorization time (prevents protocol fee changes from breaking capture)
4. Call escrow.authorize()
5. Call AUTHORIZE_RECORDER (if set)
6. Emit AuthorizationCreated

​

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_CONDITION (if set)
2. Validate fee bounds compatibility
3. Call escrow.charge() - funds go directly to receiver
4. Accumulate protocol fees for later distribution
5. Call CHARGE_RECORDER (if set)
6. Emit ChargeExecuted

​

release()

function release(
    AuthCaptureEscrow.PaymentInfo calldata paymentInfo,
    uint256 amount
) external nonReentrant

• paymentInfo - Payment info struct
• amount - Amount to release

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

​

refundInEscrow()

function refundInEscrow(
    AuthCaptureEscrow.PaymentInfo calldata paymentInfo,
    uint120 amount
) external nonReentrant

• paymentInfo - Payment info struct
• amount - Amount to return to payer

1. Check REFUND_IN_ESCROW_CONDITION (if set)
2. Call escrow.partialVoid() to return funds to payer
3. Call REFUND_IN_ESCROW_RECORDER (if set)
4. Emit RefundInEscrowExecuted

​

refundPostEscrow()

function refundPostEscrow(
    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 (e.g., signatures)

1. Check REFUND_POST_ESCROW_CONDITION (if set)
2. Call escrow.refund() - token collector enforces permission
3. Call REFUND_POST_ESCROW_RECORDER (if set)
4. Emit RefundPostEscrowExecuted

​

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_RECIPIENT;  // Operator fee recipient
// Protocol fee recipient is on ProtocolFeeConfig

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

• Protocol Fee: 3 bps (0.03%) = 0.30 USDC -> goes to protocolFeeRecipient
• Operator Fee: 2 bps (0.02%) = 0.20 USDC -> goes to FEE_RECIPIENT
• Total Fee: 5 bps (0.05%) = 0.50 USDC
• Receiver Gets: 999.50 USDC

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_RECIPIENT

​

Protocol Fee Changes (7-day Timelock)

// Step 1: Queue new calculator
protocolFeeConfig.queueCalculator(newCalculatorAddress);

// Step 2: Wait 7 days

// Step 3: Execute
protocolFeeConfig.executeCalculator();

​

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 cannot be changed

​

Next Steps