System architecture

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/cowprotocol/flash-loan-router/llms.txt

Use this file to discover all available pages before exploring further.

​

Architecture overview

​

Component interactions

​

Core contracts

​

FlashLoanRouter

• Authenticate solver calls through CoW Protocol’s authentication contract
• Process flash loan requests sequentially in the specified order
• Coordinate with borrower adapters to obtain loans
• Execute the CoW Protocol settlement once all loans are received
• Maintain execution state to prevent reentrancy and unauthorized calls

function flashLoanAndSettle(
    Loan.Data[] calldata loans,
    bytes calldata settlement
) external onlySolver;

​

Borrower adapters

abstract contract Borrower is IBorrower {
    IFlashLoanRouter public immutable router;
    ICowSettlement public immutable settlementContract;

    function flashLoanAndCallBack(
        address lender,
        IERC20 token,
        uint256 amount,
        bytes calldata callBackData
    ) external onlyRouter {
        triggerFlashLoan(lender, token, amount, callBackData);
    }

    function approve(
        IERC20 token,
        address target,
        uint256 amount
    ) external onlySettlementContract {
        token.forceApprove(target, amount);
    }

    function triggerFlashLoan(...) internal virtual;
}

contract AaveBorrower is Borrower, IAaveFlashLoanReceiver {
    function triggerFlashLoan(...) internal override {
        IAavePool(lender).flashLoan(
            address(this),
            assets,
            amounts,
            interestRateModes,
            onBehalfOf,
            params,
            referralCode
        );
    }

    function executeOperation(...) external returns (bool) {
        flashLoanCallBack(callBackData);
        return true;
    }
}

contract ERC3156Borrower is Borrower, IERC3156FlashBorrower {
    function triggerFlashLoan(...) internal override {
        bool success = IERC3156FlashLender(lender).flashLoan(
            this,
            address(token),
            amount,
            callBackData
        );
        require(success, "Flash loan was unsuccessful");
    }

    function onFlashLoan(...) external returns (bytes32) {
        flashLoanCallBack(callBackData);
        return ERC3156_ONFLASHLOAN_SUCCESS;
    }
}

1. Settlement calls borrower.approve(token, spender, amount)
2. Spender (e.g., settlement contract) calls token.transferFrom(borrower, destination, amount)

​

Loan data structure

struct Data {
    uint256 amount;      // Amount of tokens to borrow
    IBorrower borrower;  // Adapter contract for this lender
    address lender;      // Flash loan provider address
    IERC20 token;        // Token to borrow
}

Content: |--  amount  --||-- borrower --||--  lender  --||--  token   --|
Length:  |<--32 bytes-->||<--20 bytes-->||<--20 bytes-->||<--20 bytes-->|

​

Execution flow

​

Phase 1: Solver initiates settlement

flashLoanRouter.flashLoanAndSettle(
    [
        Loan(1000e6, aaveBorrower, aavePool, USDC),
        Loan(500e18, erc3156Borrower, makerFlash, DAI)
    ],
    abi.encodeCall(ICowSettlement.settle, (...))
)

• Verify caller is a registered solver
• Emit Settlement(solver) event
• Store loan and settlement data
• Begin loan acquisition process

​

Phase 2: Sequential loan acquisition

1. Router calls borrower.flashLoanAndCallBack(lender, token, amount, data)
2. Borrower calls lender-specific flash loan function
3. Lender transfers assets to borrower
4. Lender calls borrower’s callback function
5. Borrower calls router.borrowerCallBack(data)
6. Router validates callback came from expected borrower
7. Router proceeds to next loan or settlement

IBorrower internal transient pendingBorrower;
bytes32 internal transient pendingDataHash;

​

Phase 3: Settlement execution

1. Router sets internal state to SETTLING to prevent reentrancy
2. Router calls settlementContract.settle(settlementData)
3. Settlement transfers borrowed funds where needed
4. Settlement executes trades and user interactions
5. Settlement repays borrowers and sets lender approvals
6. Lenders pull repayment from borrowers

​

Phase 4: Loan repayment

• Settlement transfers borrowed amount + fee to borrower
• Settlement calls borrower.approve(token, aavePool, repaymentAmount)
• Aave pool calls token.transferFrom(borrower, pool, repaymentAmount)

• Settlement transfers borrowed amount + fee to borrower
• Settlement calls borrower.approve(token, lender, repaymentAmount)
• Lender calls token.transferFrom(borrower, lender, repaymentAmount)

​

Security model

​

Router security guarantees

• Settlement data cannot be modified
• Additional settlements cannot be triggered
• Execution order cannot be changed

• Cause transaction revert
• Modify chain state before settlement
• Exploit slippage tolerance

​

Borrower security

• Cannot call CoW Protocol functions directly
• Cannot access router functions outside of callback flow
• Only respond to authenticated router requests

• Impair borrower’s adapter functionality
• Modify expected borrower behavior
• Extract funds (only approvals can authorize transfers)

​

Supported lenders

​

Adding new lenders

1. Create new borrower contract inheriting from Borrower
2. Implement triggerFlashLoan() for lender-specific request format
3. Implement lender’s callback interface
4. Call flashLoanCallBack() from the lender’s callback
5. Deploy borrower contract with router address
6. Solvers can now use the new lender

contract CustomBorrower is Borrower {
    constructor(IFlashLoanRouter _router) Borrower(_router) {}

    function triggerFlashLoan(...) internal override {
        // Call lender-specific flash loan function
    }

    function lenderCallback(...) external {
        // Lender's callback signature
        flashLoanCallBack(callBackData);
    }
}

​

Gas optimization

​

Design principles