> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/reserve-protocol/reserve-index-dtf/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```solidity theme={null}
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

```solidity theme={null}
// 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

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

<Warning>
  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.
</Warning>

## Configuration

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

```solidity theme={null}
function setTrustedFillerRegistry(
    address _newFillerRegistry,
    bool _enabled
) external onlyRole(DEFAULT_ADMIN_ROLE);
```

### Enabling Trusted Fillers

```solidity theme={null}
// Set registry and enable
folio.setTrustedFillerRegistry(trustedFillerRegistryAddress, true);

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

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

## Token Compatibility

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

1. The Folio contract (see [Security Considerations](/advanced/security#weird-erc20-support))
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

```solidity theme={null}
// 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

```solidity theme={null}
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](/advanced/price-control)
* [Security Considerations](/advanced/security)
* [Rebalancing Guide](/concepts/rebalancing)