Trusted Filler Integration

Using CoW Swap and other trusted fillers for advanced auction execution

Overview

Trusted fillers enable asynchronous order execution during Folio rebalancing auctions. Instead of executing swaps directly on-chain through the bid() function, trusted fillers can route orders to external protocols like CoW Swap for potentially better execution.

How Trusted Fillers Work

When trusted fillers are enabled, an AUCTION_LAUNCHER or any authorized party can create a trusted fill during an active auction:

function createTrustedFill(
    uint256 auctionId,
    IERC20 sellToken,
    IERC20 buyToken,
    address targetFiller,
    bytes32 deploymentSalt
) external returns (IBaseTrustedFiller filler);

This function:

1. Validates the auction is ongoing
2. Calculates the sell and buy amounts based on current auction prices
3. Creates a new trusted filler contract via the TrustedFillerRegistry
4. Approves the sell token to the filler
5. Initializes the filler with swap parameters

CoW Swap Integration

CoW Swap is currently the only supported trusted filler. It enables:

• MEV protection through batch auctions
• Better execution via solver competition
• Gas optimization through order batching
• Price improvement beyond standard dutch auction curves

Example: Creating a CoW Swap Fill

// During an active auction
IBaseTrustedFiller filler = folio.createTrustedFill(
    auctionId,
    USDC,           // sell token
    WETH,           // buy token
    cowSwapFiller,  // CoW Swap filler address
    bytes32(0)      // deployment salt
);

State Management

The Folio tracks an active trusted fill at activeTrustedFill. While a trusted fill is active:

• Token balances include balances held by the filler
• The stateChangeActive() function returns (false, true) if the swap is ongoing
• The _poke() function automatically closes completed fills

Checking Async State

(bool syncActive, bool asyncActive) = folio.stateChangeActive();
if (!syncActive && !asyncActive) {
    // Safe to rely on Folio state
}

When asyncActive is true, view functions like totalAssets(), toAssets(), and getBid() may return unreliable data mid-swap. Always check stateChangeActive() before trusting view data in consuming protocols.

Configuration

Trusted fillers are configured through the FolioRegistryIndex during deployment or via governance:

function setTrustedFillerRegistry(
    address _newFillerRegistry,
    bool _enabled
) external onlyRole(DEFAULT_ADMIN_ROLE);

Enabling Trusted Fillers

// Set registry and enable
folio.setTrustedFillerRegistry(trustedFillerRegistryAddress, true);

// Disable without changing registry
folio.setTrustedFillerRegistry(trustedFillerRegistryAddress, false);

The trusted filler registry can only be set once. After initial configuration, you can only enable/disable the existing registry, not replace it.

Token Compatibility

When trusted fillers are enabled, tokens must be supported by both:

1. The Folio contract (see Security Considerations)
2. The external trusted fillers whitelisted in the registry

For CoW Swap specifically, tokens must:

• Be listed on CoW Protocol
• Have sufficient liquidity for solver routing
• Not be pausable, fee-on-transfer, or have callbacks

Auction Lifecycle with Trusted Fills

The complete rebalancing flow with trusted fillers:

1. Start Rebalance - REBALANCE_MANAGER initiates
2. Open Auction - AUCTION_LAUNCHER opens with price ranges
3. Create Trusted Fill - Optional async execution via CoW Swap
4. Order Settlement - CoW solvers compete to fill the order
5. Close Fill - Folio automatically claims tokens when complete
6. Close Auction - Optional early closure or natural expiration

Best Practices

For AUCTION_LAUNCHER

• Use trusted fillers for large trades where MEV is a concern
• Monitor fill status and close auctions if fills fail
• Combine with PriceControl.ATOMIC_SWAP for maximum control

For Consuming Protocols

// Always check state before relying on view functions
function getSafeBalance() external view returns (uint256) {
    (bool syncActive, bool asyncActive) = folio.stateChangeActive();
    require(!syncActive && !asyncActive, "State change active");
    
    (address[] memory assets, uint256[] memory amounts) = folio.totalAssets();
    // ... safe to use amounts
}

Events

event AuctionTrustedFillCreated(uint256 indexed auctionId, address filler);
event TrustedFillerRegistrySet(address trustedFillerRegistry, bool isEnabled);

Security Considerations

• Trusted fillers execute within the same auction price bounds as regular bids
• The AUCTION_LAUNCHER must still act within ranges set by REBALANCE_MANAGER
• Failed fills do not revert; the Folio reclaims tokens automatically
• Only one trusted fill can be active at a time per Folio

Related

• Price Control Modes
• Security Considerations
• Rebalancing Guide