Let's start by deleveraging our position. In the event that wS price rises, while our position's USD equity will remain neutral, our collateralization ratio will approach liquidation. Thus we need a way to reduce our overall size in the position to make sure our starting capital remains large enough relative to the position size to collateralize the position.

Do do these we simply need to execute a swap of some portion of our HEDGED_TOKEN for the LIABILITY_TOKEN and use it to pay down our debt. Our exposure will remain neutral but our overall loan to value ratio will be reduced.

We can see that our previously written utility for this pattern batchSwapAndRepay will make implementing this a breeze. We just need to input the proper parameters in the context of reducing our leverage.

First setup our script to define the proper vaults associated with this trade, the same as the previous posts

// delverage.s.sol

// SPDX-License-Identifier: UNLICENSED
pragma solidity ^0.8.28;

import "./common/EScript.s.sol";
import {SonicLib} from "./common/SonicLib.sol";

contract DeleverageScript is EScript {
    function run() public {
        borrower = msg.sender;
        e_account = getSubaccount(borrower, 2);
        evc = IEVC(SonicLib.EVC);

        address LIABILITY_VAULT = SonicLib.EULER_WS_VAULT;
        address HEDGED_VAULT = SonicLib.EULER_PT_STS_VAULT;
        address COLLATERAL_VAULT = SonicLib.EULER_USDC_VAULT;
        address LIABILITY_TOKEN = SonicLib.WS;
        address HEDGED_TOKEN = SonicLib.PT_STS;
        address COLLATERAL_TOKEN = SonicLib.USDC;

        uint256 deleverage_amount = assetsBalance(HEDGED_VAULT) / 4;

        (string memory swapJson, string memory verifyJson) = getRoutingData(
            HEDGED_VAULT, LIABILITY_VAULT, HEDGED_TOKEN, LIABILITY_TOKEN, deleverage_amount
        );

        broadcastBatch(batchSwapAndRepay(
            HEDGED_VAULT, LIABILITY_VAULT, deleverage_amount, swapJson, verifyJson)
        );

        logPositionInfo(COLLATERAL_VAULT, HEDGED_VAULT, LIABILITY_VAULT);

    }
}

Now we calculate our deleverage_amount as the fraction of our HEDGED_TOKEN that we want to liquidate. In this example we will reduce our size by 1/4th (25%)

Now, we just need to fetch our routing payload, noting that we are swapping the HEDGED_TOKEN PT-stS into the LIABILITY_TOKEN wS, with the LIABILITY_VAULT as the ultimate destination for the output tokens.

Once, we have that payload our batchSwapAndRepay batch array will organize the operations to withdraw the PT-stS, execute the swap and repay the debt in the LIABILITY_VAULT.

Finally, we can see our balances show that our USD collateral remain the same and our HEDGED_TOKEN balance and LIABILITY_TOKEN debt are reduced by 1/4.

Unhedge

Just as easily as we deleveraged the position, we can unhedge it. We can gain exposure to the price movements of the underlying wS by simply swapping the COLLATERALTOKEN which we used as our hedge into the HEDGED_TOKEN giving us excess exposure to the HEDGE_TOKEN relative to our LIABILITY_TOKEN debt amount.

Again, we setup our script the same a before with all of the appropriate vaults labeled exactly the same.

// undehge.s.sol
// SPDX-License-Identifier: UNLICENSED
pragma solidity ^0.8.28;

import "./common/EScript.s.sol";
import {SonicLib} from "./common/SonicLib.sol";
import { IERC20 } from "openzeppelin-contracts/contracts/token/ERC20/IERC20.sol";

contract UnhedgeScript is EScript {
    function run() public {
        borrower = msg.sender;
        e_account = getSubaccount(borrower, 2);
        evc = IEVC(SonicLib.EVC);

        address LIABILITY_VAULT = SonicLib.EULER_WS_VAULT;
        address HEDGED_VAULT = SonicLib.EULER_PT_STS_VAULT;
        address COLLATERAL_VAULT = SonicLib.EULER_USDC_VAULT;
        address LIABILITY_TOKEN = SonicLib.WS;
        address HEDGED_TOKEN = SonicLib.PT_STS;
        address COLLATERAL_TOKEN = SonicLib.USDC;

        uint256 collateral_unhedge_amount = assetsBalance(COLLATERAL_VAULT);

        (string memory swapJson, string memory verifyJson) = getRoutingData(
            COLLATERAL_VAULT, HEDGED_VAULT, COLLATERAL_TOKEN, HEDGED_TOKEN, collateral_unhedge_amount
        );

        broadcastBatch(batchWithdrawAndSwap(
            COLLATERAL_VAULT, collateral_unhedge_amount, swapJson, verifyJson)
        );

        logPositionInfo(COLLATERAL_VAULT, HEDGED_VAULT, LIABILITY_VAULT);
    }
}

In this example, we set the collateral_unhedge_amount to the total amount of our COLLATERAL_VAULT balance thus completely unhedging our position and gaining wS exposure equivalent to our starting capital.

We can also easily fetch the payload data, with the COLLATERAL_TOKEN (USDC) as the input and the HEDGED_TOKEN as the output with HEDGED_VAULT as the destination.

Once, we have the swap data, we can broadcast a batch constructed with the batchWithdrawAndSwap pattern using the COLLATERAL_VAULT as the _input_vault.

Just like that, we have converted the position to maximize our exposure to the underlying wS price movements. Here we can see how our script framework makes constructing new position's and managing existing one's a breeze, giving us almost infinite flexibility.

High yield defi engineering is available on demand at YieldDev Studio

Feel free to reach out on —> x for anything, technical or otherwise

Full code described above can be found on github

First, fully close out the position into USDC by selling our hedged asset PT-stS for wS, paying off the entire outstanding debt and then swapping the remaining wS for USDC.

Second, deleverage the position by selling off a portion of our PT-stS hedged asset to pay off our wS liability thus increasing our collateralization ratio.

Lastly, We will create a script to unhedge our position, swapping our USDC collateral for more of the PT-stS hedged asset thus increasing our net exposure to the wS price.

To start out, we create a new file close.s.sol and create our CloseScript contract. We being by setting up our trade parameters exactly the same as in our open script.

// SPDX-License-Identifier: UNLICENSED
pragma solidity ^0.8.28;

import "./common/EScript.s.sol";
import {SonicLib} from "./common/SonicLib.sol";

contract CloseScript is EScript {
    function run() public {
        borrower = msg.sender;
        e_account = getSubaccount(borrower, 0);
        evc = IEVC(SonicLib.EVC);

        address LIABILITY_VAULT = SonicLib.EULER_WS_VAULT;
        address HEDGED_VAULT = SonicLib.EULER_PT_STS_VAULT;
        address COLLATERAL_VAULT = SonicLib.EULER_USDC_VAULT;
        address LIABILITY_TOKEN = SonicLib.WS;
        address HEDGED_TOKEN = SonicLib.PT_STS;
        address COLLATERAL_TOKEN = SonicLib.USDC;
    }
}

Next, we are going to continue simplifying our script framework by generalizing some functions that will be reusable across all of our scripts.

The first instance of this is getting out euler-orderflow-router swap data. Since we will constantly be getting payloads to execute an exactIn swap for our various assets and write them to json payloads for use in our script, we can create a utility function for reuse and readability.

For this reason, let's jump back to our EScript.s.sol file and implement a generalize getter function.

// Escript.s.sol

    function getRoutingData(
        address _inputVault,
        address _outputVault,
        address _inputToken,
        address _outputToken,
        uint256 _amount
    ) public returns (string memory _swapJson, string memory _verifyJson) {
        requestPayload(_inputVault, _outputVault, _inputToken, _outputToken, _amount);
        _swapJson = getJsonFile("./script/payloads/swapData.json");
        _verifyJson = getJsonFile("./script/payloads/verifyData.json");
    }

Here, we define our parameters for the swap and request a payload using our previously defined requestPayload function. Since this function writes the payload data to a json file, we can just read these two files to memory and return them.

This allows us to simplify retrieving router data in our script.

// close.s.sol
        uint256 hedged_balance = assetsBalance(HEDGED_VAULT);
        (string memory swapJson, string memory verifyJson) = getRoutingData(
            HEDGED_VAULT, LIABILITY_VAULT, HEDGED_TOKEN, LIABILITY_TOKEN, hedged_balance
        );

Since, our goal is to close the position. We have first retrieved our hedged_balance the amount of the HEDGE_TOKEN PT-stS which we have deposited as collateral. We will be swapping this entire amount for the LIABILITY_TOKEN wS. Thus we pass these parameters to the getRoutingData function. We have passed the LIABILITY_VAULT as the _outputVault parameter since this will be the destination of our swap's output assets which we will claim as a deposit via the verifyJson payload execution. We will then be able to execute repayWithShares on the LIABILITY_VAULT to pay down our debt.

Now that we have our swap data taken care of, we can construct the batch to execute. We will need to make two additional operation along with our two swap operations. First, we will need to define a batch item to withdraw the HEDGED_TOKEN to the swapper address. Secondly, we will need an operation at the end of the batch to repay the debt with our new purchased LIABILITY_TOKEN.

Since these are, once again, common operations in position management, we can create some utility functions for returning these IEVC.BatchItem structs in our EScript.s.sol file.

// Escript.s.sol

    function batchWithdrawTo(address _vault, uint256 _amount, address _to) public view returns (IEVC.BatchItem memory) {
        return IEVC.BatchItem({
            onBehalfOfAccount: e_account,
            targetContract: _vault,
            value: 0,
            data: abi.encodeWithSelector(EVault.withdraw.selector, _amount, _to, e_account)
        });
    }

    function batchRepayWithShares(address _vault, uint256 _amount) public view returns (IEVC.BatchItem memory) {
        return IEVC.BatchItem({
            onBehalfOfAccount: e_account,
            targetContract: _vault,
            value: 0,
            data: abi.encodeWithSelector(EVault.repayWithShares.selector, _amount, e_account)
        });
    }

Here we define batchWithdrawTo which returns a batch item for withdrawing assets from a given vault in a given amount to a given recipient (the swapperAddress in this use case). We also define batchRepayWithShares which repays the debt of our e_account in a given vault with the e_accounts own deposit shares.

We can now construct a batch to execute this withdraw, swap and repay. Once again, this is a common pattern for on chain position management. Thus we can create another general function for returning this entire batch of BatchItems as we may want to use this pattern in many scenarios where it makes sense to repay debt by swapping a collateral, whether we are deleveraging or closing out a position.

// EScript.s.sol

    function batchSwapAndRepay(
        address _inputVault,
        address _repayVault,
        uint256 _amountIn,
        string memory _swapJson,
        string memory _verifyJson
    ) public view returns (IEVC.BatchItem[] memory items) {
        items = new IEVC.BatchItem[](4);
        items[0] = batchWithdrawTo(_inputVault, _amountIn, vm.parseJsonAddress(_swapJson, ".swapperAddress"));
        items[1] = batchPayload(vm.parseJsonAddress(_swapJson, ".swapperAddress"), vm.parseJsonBytes(_swapJson, ".swapperData"));
        items[2] = batchPayload(vm.parseJsonAddress(_verifyJson, ".verifierAddress"), vm.parseJsonBytes(_verifyJson, ".verifierData"));
        items[3] = batchRepayWithShares(_repayVault, type(uint256).max);
    }

Here, we have generalized this pattern with batchSwapAndRepay. We can easily construct a batch which withdraws the amount of assets from the _inputVault swaps and skims them according to the json payloads provided and then repays the maximum amount of debt repayable by the amount of deposit shares available or the amount of debt outstanding. This function then returns the entire batch as an array of batch items, ready for execution.

Once again, we encounter a functionality we will constantly be calling with out scripts, that of actually executing the batch.

// EScript.s.sol

    function broadcastBatch(IEVC.BatchItem[] memory _items) public {
        vm.startBroadcast();
        evc.batch(_items);
        vm.stopBroadcast();
    }

Here we simplify our function call for executing an array of BatchItems via the EVC inside of the vm's broadcast context. All we need to do is pass it our batch array.

Finally displaying the balances of our vaults will be useful for ensuring that the output of the scripts execution matches our expectations when we run the script in a fork. So, we add a logging function for our vault balances.

// EScript.s.sol

    function logPositionInfo(
        address _collateralVault,
        address _hedgedVault,
        address _liabilityVault
    ) public view {
        console.log("--------------------------------");
        console.log("COLLATERAL VAULT: ", assetsBalance(_collateralVault));
        console.log("HEDGED VAULT: ",assetsBalance(_hedgedVault));
        uint256 debt = debtBalance(_liabilityVault);
        if (debt > 0) {
            console.log("LIABILITY VAULT DEBT: ", debt);
        } else {
            console.log("LIABILITY VAULT ASSET BALANCE: ", assetsBalance(_liabilityVault));
        }
        console.log("--------------------------------");
    }

We are finally ready to jump back to our close.s.sol file and execute the batch in the context of our trade.

// close.s.sol

        broadcastBatch(
            batchSwapAndRepay(
                HEDGED_VAULT, LIABILITY_VAULT, hedged_balance,
                swapJson, verifyJson
            )
        );

        logPositionInfo(COLLATERAL_VAULT, HEDGED_VAULT, LIABILITY_VAULT);

We pass our HEDGED_VAULT, since PT-stS is the input token for our swap and repay, along with the LIABILITY_VAULT as our _repayVault and our hedged_balance as the amount. We also pass through our previously retrieved swap data. batchSwapAndRepay will return the EVC.BatchItem array that we need to execute this operation thus we can pass the entire function call as an argument directly to broadcastBatch which will handle the execution.

After that, we can call logPositionInfo() and see our balance status after the execution is completed.

Now, after running this we may notice that our position has a profit in the form of a log showing LIABILITY VAULT ASSET BALANCE: xxxxx indicating that after repaying the debt, we had excess LIABILITY_TOKENs aka profit.

So, we will now be wanting to swap these profits to cash. In order to do so, we simply call getRoutingData for our new transaction.

// close.s.sol

        uint256 collateral_balance = assetsBalance(COLLATERAL_VAULT);
        uint256 liability_balance = assetsBalance(LIABILITY_VAULT);

        (swapJson, verifyJson) = getRoutingData(
            LIABILITY_VAULT, COLLATERAL_VAULT, LIABILITY_TOKEN, COLLATERAL_TOKEN, liability_balance
        );

Here we retrieve routing data for the LIABILTY_TOKEN's liability_balance of wS and swapped for our desired output the COLLATERAL_TOKEN (USDC). we have also taken note of the COLLATERAL_VAULT collateral_balance which we will use later to calculate our net USDC profit.

Since we have the swap data, we need to construct a batch similar to our previous one except that we do not need to execute a repay function after the swapVerify payload has deposited our output token shares in the vault. So we will create another utility function to return a batch for this pattern of BatchWithdrawAndSwap

// EScript.s.sol

    /// @notice Withdraw from the inputVault, swap and deposit to the outputVault
    /// @param _swapJson The json file for the swap router data
    /// @param _verifyJson The json file for the verify router data
    function batchWithdrawAndSwap(
        address _inputVault,
        uint256 _amountIn,
        string memory _swapJson,
        string memory _verifyJson
    ) public view returns (IEVC.BatchItem[] memory items) {
        items = new IEVC.BatchItem[](3);
        items[0] = batchWithdrawTo(_inputVault, _amountIn, vm.parseJsonAddress(_swapJson, ".swapperAddress"));
        items[1] = batchPayload(vm.parseJsonAddress(_swapJson, ".swapperAddress"), vm.parseJsonBytes(_swapJson, ".swapperData"));
        items[2] = batchPayload(vm.parseJsonAddress(_verifyJson, ".verifierAddress"), vm.parseJsonBytes(_verifyJson, ".verifierData"));
    }

Exactly the same as before, except without a repay operation. Note, also, that the batchWithdrawAndSwap function only needs to "know" about the _inputVault so that it can withdraw the assets to the swapperAddress. Otherwise, the swap payload already has the context of which token to swap to and which vault will receive it. The verifierData that executes within the batch takes care of ensuring that the tokens were delivered to destination vault and were skimmed converting them to deposits on behalf of our e_account.

Now we can easily execute this batch as we did before.

// close.s.sol
        broadcastBatch(batchWithdrawAndSwap(
            LIABILITY_VAULT, liability_balance,
            swapJson, verifyJson)
        );
        logPositionInfo(COLLATERAL_VAULT, HEDGED_VAULT, LIABILITY_VAULT);
        console.log("COLLATERAL PROFIT: ", assetsBalance(COLLATERAL_VAULT) - collateral_balance);

Here, we use the LIABILITY_VAULT as the _inputVault from which to withdraw and the balance of funds to withdraw.

Once this batch is broadcast we can display our vault info. we can also get the difference in our COLLATERAL_VAULT balance to display our profit in USDC.

forge script --fork-url https://rpc.soniclabs.com --sender $SENDER script/close.s.sol --ffi

With this framework of script utilities, we can exert very fine control over the leverage and exposure of our position in addition to allowing us to move quickly and flexibly across trades with maximum capital efficiency.

From here, implementing scripts which allow us to unhedge our exposure or deleverage our position will be a breeze.

High yield defi engineering is available on demand at YieldDev Studio

Feel free to reach out on —> x for anything, technical or otherwise

Full code described above can be found on github

Full code of close.s.sol

// SPDX-License-Identifier: UNLICENSED
pragma solidity ^0.8.28;

import "./common/EScript.s.sol";
import {SonicLib} from "./common/SonicLib.sol";

contract CloseScript is EScript {
    function run() public {
        borrower = msg.sender;
        e_account = getSubaccount(borrower, 2);
        evc = IEVC(SonicLib.EVC);

        address LIABILITY_VAULT = SonicLib.EULER_WS_VAULT;
        address HEDGED_VAULT = SonicLib.EULER_PT_STS_VAULT;
        address COLLATERAL_VAULT = SonicLib.EULER_USDC_VAULT;
        address LIABILITY_TOKEN = SonicLib.WS;
        address HEDGED_TOKEN = SonicLib.PT_STS;
        address COLLATERAL_TOKEN = SonicLib.USDC;

        uint256 hedged_balance = assetsBalance(HEDGED_VAULT);
        (string memory swapJson, string memory verifyJson) = getRoutingData(
            HEDGED_VAULT, LIABILITY_VAULT, HEDGED_TOKEN, LIABILITY_TOKEN, hedged_balance
        );

        broadcastBatch(batchSwapAndRepay(
            HEDGED_VAULT, LIABILITY_VAULT, hedged_balance,
            swapJson, verifyJson
        ));
        logPositionInfo(COLLATERAL_VAULT, HEDGED_VAULT, LIABILITY_VAULT);

        uint256 collateral_balance = assetsBalance(COLLATERAL_VAULT);
        uint256 liability_balance = assetsBalance(LIABILITY_VAULT);

        (swapJson, verifyJson) = getRoutingData(
            LIABILITY_VAULT, COLLATERAL_VAULT, LIABILITY_TOKEN, COLLATERAL_TOKEN, liability_balance
        );

        broadcastBatch(batchWithdrawAndSwap(
            LIABILITY_VAULT, liability_balance,
            swapJson, verifyJson)
        );
        logPositionInfo(COLLATERAL_VAULT, HEDGED_VAULT, LIABILITY_VAULT);
        console.log("COLLATERAL PROFIT: ", assetsBalance(COLLATERAL_VAULT) - collateral_balance);
    }
}

We will simplify and generalize our scripts, in order that they may be used to create delta neutral yield positions across any PT asset on Euler.

To begin Let's create a new directory called AdvancedYieldFarming and initialize a foundry project inside of it.

 forge init

We are also going to install ethereum-vault-connector and evk/periphery libraries from Euler in order to build our scripts

forge install euler-xyz/ethereum-vault-connector
forge install euler-xyz/evk-periphery

To start out, we will create a subdirectory in our script folder called common. Inside of which, we will create a new script file called EScript.s.sol this file will act as the base for any scripts we write and will hold utility logic, so that our main scripts can be focused strictly on building the transaction logic.

// SPDX-License-Identifier: UNLICENSED
pragma solidity ^0.8.28;

// EScript.s.sol
import {Script, console} from "forge-std/Script.sol";
import "evc/interfaces/IEthereumVaultConnector.sol";
import { EVault } from "evk/EVault/EVault.sol";

contract EScript is Script {
    IEVC evc;
    address borrower; // eoa
    address e_account; // subaccount
}

Here, we have imported the basics and setup our contract as a Script with a couple of global variables that will be universal to any transaction we build. Namely, the EVC, the borrower which will be our msg.sender and the e_account, which we can set to our Euler compliant sub account. This sub account will be the global account that holds our position.

From here, we can implement two utility functions that will be necessary for our script. First, we need a way of deriving our sub account based on our index. We also need a way to read in json file data, this will be necessary to utilize the swap routing payloads which we are going to fetch from the euler-orderflow-router. We can define these functions in our EScript contract.

    function getSubaccount(address _account, uint256 _index) public returns (address) {
        return address(uint160(uint160(_account)^_index));
    }

    function getJsonFile(string memory _filePath) internal view returns (string memory) {
        return vm.readFile(_filePath);
    }

In the context of the evc, one general operation we will often need to execute will be the enabling/disabling of the vaults as collateral or controllers. The operations indicate to the evc which vaults to use as collateral and allow us to take loans from the controllers. Thus, we can create two utility functions which return the BatchItem payload necessary for a given vault.

    function enableCollateral(address _vault) public view returns (IEVC.BatchItem memory) {
        return IEVC.BatchItem({
            onBehalfOfAccount: address(0),
            targetContract: address(evc),
            value: 0,
            data: abi.encodeWithSelector(
                IEVC.enableCollateral.selector,
                e_account,
                _vault
            )
        });
    }

    function enableController(address _vault) public view returns (IEVC.BatchItem memory) {
        return IEVC.BatchItem({
            onBehalfOfAccount: address(0),
            targetContract: address(evc),
            value: 0,
            data: abi.encodeWithSelector(
                IEVC.enableController.selector,
                e_account,
                _vault
            )
        });
    }

These functions will deliver the batch data for enabling a specific vault for the Euler sub account which we globally set in our main scripts run logic.

Another frequent operation we will need to make use of is executing a swap's routing payload. The swap data we retrieve will give us a target contract along with all the data needed, this makes executing it within a batch simple enough to allow us to create a general function to batch this operation and execute it on behalf of our current sub account.

    function batchPayload(address _target, bytes memory _data) public view returns (IEVC.BatchItem memory) {
        return IEVC.BatchItem({
            onBehalfOfAccount: e_account,
            targetContract: _target,
            value: 0,
            data: _data
        });
    }

In order that we may open a leveraged long position, we are going to need an operation to borrow funds and have them delivered to the swapper for trading. So we can create a general borrow function to retrieve the BatchItem which accomplishes this transaction on a given vault to a given address in a specified amount.

    function batchBorrowTo(address _vault, uint256 _amount, address _to) public view returns (IEVC.BatchItem memory) {
        return IEVC.BatchItem({
            onBehalfOfAccount: e_account,
            targetContract: _vault,
            value: 0,
            data: abi.encodeWithSelector(EVault.borrow.selector, _amount, _to)
        });
    }

Now that we have implemented all of the necessary batch operations to open our position, we will add a few general getters to check our balances on the vaults.

    function sharesBalance(address _vault) public view returns (uint256) {
        return EVault(_vault).balanceOf(e_account);
    }
    function assetsBalance(address _vault) public view returns (uint256) {
        return EVault(_vault).convertToAssets(EVault(_vault).balanceOf(e_account));
    }
    function debtBalance(address _vault) public view returns (uint256) {
        return EVault(_vault).debtOf(e_account);
    }

Now since we will be opening this trade on Sonic. We will create a library to hold all of the relevant constant sonic contract addresses. This will be in our common directory.

// SPDX-License-Identifier: UNLICENSED
pragma solidity ^0.8.28;

library SonicLib {
    address public constant EVC = 0x4860C903f6Ad709c3eDA46D3D502943f184D4315;

    address public constant EULER_USDC_VAULT = 0x196F3C7443E940911EE2Bb88e019Fd71400349D9;
    address public constant EULER_PT_STS_VAULT = 0xdBc46ff39Cae7f37c39363B0CA474497dAD1d3cf;
    address public constant EULER_WS_VAULT = 0x9144C0F0614dD0acE859C61CC37e5386d2Ada43A;

    address public constant USDC = 0x29219dd400f2Bf60E5a23d13Be72B486D4038894;
    address public constant PT_STS = 0x420df605D062F8611EFb3F203BF258159b8FfFdE;
    address public constant WS = 0x039e2fB66102314Ce7b64Ce5Ce3E5183bc94aD38;
}

Since we have all of our utilities completed, we can move on to writing the scripts run logic. We can create a file called script/open.s.sol and import our EScript base contract and the SonicLib. We also set our global variables to be used in the script. This is where we will define which of our Euler subaccounts will hold our position.

// SPDX-License-Identifier: UNLICENSED
pragma solidity ^0.8.28;

// script/open.s.sol
import "./common/EScript.s.sol";
import {SonicLib} from "./common/SonicLib.sol";
contract OpenScript is EScript {
    function run() public {
        borrower = msg.sender;
        e_account = getSubaccount(borrower, 0);
        evc = IEVC(SonicLib.EVC);
    }
}

Note, we have also imported a library called SonicLib from the common directory. This file will hold specific, constant addresses for our trade.

First, let's define each asset we will use in our trade.

For this trade, we are going to have a hedged asset earning fixed yield in the form of a PT, specifically PT-stS. The purchase of this asset will be funded by borrowing wS, our liability asset. Since The PT resolves to $S staked in beets at maturity, this liability neutralizes our exposure from the PT. We will collateralize this wS loan with our initial capital in USDC.e in it's vault, this will be our collateral.

So we need to set these variables in the code, defining both the token and vault for each asset.

// script/open.s.sol

        address LIABILITY_VAULT = SonicLib.EULER_WS_VAULT;
        address HEDGED_VAULT = SonicLib.EULER_PT_STS_VAULT;
        address COLLATERAL_VAULT = SonicLib.EULER_USDC_VAULT;

        address LIABILITY_TOKEN = SonicLib.WS;
        address HEDGED_TOKEN = SonicLib.PT_STS;
        address COLLATERAL_TOKEN = SonicLib.USDC;

Now that we understand each asset's purpose in our trade, we can set the specific addresses in our SonicLib corresponding to the Sonic address of the asset.

// SPDX-License-Identifier: UNLICENSED
pragma solidity ^0.8.28;

library SonicLib {
    address public constant EVC = 0x4860C903f6Ad709c3eDA46D3D502943f184D4315;

    address public constant EULER_USDC_VAULT = 0x196F3C7443E940911EE2Bb88e019Fd71400349D9;
    address public constant EULER_PT_STS_VAULT = 0xdBc46ff39Cae7f37c39363B0CA474497dAD1d3cf;
    address public constant EULER_WS_VAULT = 0x9144C0F0614dD0acE859C61CC37e5386d2Ada43A;

    address public constant USDC = 0x29219dd400f2Bf60E5a23d13Be72B486D4038894;
    address public constant PT_STS = 0x420df605D062F8611EFb3F203BF258159b8FfFdE;
    address public constant WS = 0x039e2fB66102314Ce7b64Ce5Ce3E5183bc94aD38;
}

Fetching The Swap Routing Payload

To fetch the euler-orderflow-router we will need to setup a typescript script to call the api and write the data to a json file for use in our script. This was covered in our previous post on using euler-orderflow-router . Here we will modify the implementation to be more generalizable.

first we init a typescript project. Install our dependencies and create a new directory called api

npm init -y
npm install --save-dev typescript ts-node @types/node && npm install ethers@^6.0.0 dotenv
npm install yargs @types/yargs
mkdir -p api

Now we create a new file called common.ts to hold our api get logic. We define a function for structuring a query to get a payload for an exactIn swap data, where all of our inputToken amountIn will be consumed and swapped for the outputToken

import axios from "axios";
import * as fs from "fs";

const SWAP_API_URL = "https://swap.euler.finance";
// Get params for an exact in swap to close a position
// funds are delivered to the liability Vault
export function getParamsExactIn(
    account: string,
    inputVaultAddress: string,
    outputVaultAddress: string,
    inputToken: string,
    outputToken: string,
    amountIn: string,
) {
    const queryParams = {
        chainId: "146", // sonic chain
        tokenIn: inputToken,
        tokenOut: outputToken,
        amount: amountIn, // the amount to swap 
        targetDebt: "0", // irrelevant in this exactIn flow
        currentDebt: amountIn, // irrelevant in this exactIn flow
        receiver: outputVaultAddress,
        vaultIn: inputVaultAddress, // left over tokenIn goes here, irrelevent for exactIn flow
        origin: account, // account executing the tx
        accountIn: account, // account holding the collateral
        accountOut: account, // account to swap to, the account that skim will deliver to 
        slippage: "0.15", // 0.15% slippage
        deadline: String(Math.floor(Date.now() / 1000) + 10 * 60), // 10 minutes from now
        swapperMode: "0", // exact input mode = 0 
        isRepay: "false", // we will manually add a call to repay the debt
    };
    return queryParams;
}

// Get payload for an exact in swap to close a position
export async function getPayload(queryParams: any) {

    const { data: response } = await axios.get(
        `${SWAP_API_URL}/swap`,
        {
            params: queryParams
        }
    );

    return response.data
}

export async function writeToJsonFile(data: any, filename: string) {
    fs.writeFileSync(filename, JSON.stringify(data, null, 2));
}

We have also defined a function to send the query request to the API in a get request. As well as a function to write payload data to a json file.

We can, at this point, write the driver script to execute on our payload. We will create a file called ExactInputSwap.ts for this purpose

import { getParamsExactIn, getPayload, writeToJsonFile } from "./common";
import yargs from 'yargs';
import { hideBin } from 'yargs/helpers';

async function main() {
    // Parse command line arguments
    const argv = await yargs(hideBin(process.argv))
        .options({
            'address': {
                type: 'string',
                description: 'The wallet address',
                demandOption: true
            },
            'amount': {
                type: 'string',
                description: 'Amount to swap in ether',
                demandOption: true
            },
            'input-vault': {
                type: 'string',
                description: 'Input vault address',
                demandOption: true
            },
            'output-vault': {
                type: 'string',
                description: 'Output vault address',
                demandOption: true
            },
            'input-token': {
                type: 'string',
                description: 'Input token address',
                demandOption: true
            },
            'output-token': {
                type: 'string',
                description: 'Output token address',
                demandOption: true
            },
            // 'output-dir': {
            //     type: 'string',
            //     description: 'Output directory for payload files',
            //     default: "./script/payloads"
            // }
        })
        .help()
        .argv;

    const swapParams = getParamsExactIn(
        argv.address,
        argv["input-vault"],
        argv["output-vault"],
        argv["input-token"],
        argv["output-token"],
        BigInt(argv.amount).toString()
    );

    const swapPayload = await getPayload(swapParams);

    const outputDir = argv["output-dir"];
    await writeToJsonFile(swapPayload.swap, `script/payloads/swapData.json`);
    await writeToJsonFile(swapPayload.verify, `script/payloads/verifyData.json`);

    console.log("Payloads written to files in:", `script/payloads`);
}

main().catch((error) => {
    console.error(error);
    process.exitCode = 1;
});

Here, we have outlined the command line args necessary for our swap, we than construct our query based on these args and make the request.

Once we have received the payload, they will be written to two separate json files in our script/payload directory. The euler-orderflow-router pattern was previously discussed in this post

Back To Solidity

Now that we have our API call script complete, we can jump back to our EScript.s.sol file and add a utility function which will allow us to call this script and write fresh payload data from inside our solidity execution script.

For this function, we will make use of the vm.ffi() cheatcode. Allowing us to execute arbitrary code on our machine.

// Escript.s.sol

    function requestPayload(
        address _inputVault,
        address _outputVault,
        address _inputToken,
        address _outputToken,
        uint256 _amount
    ) public {
        string[] memory inputs = new string[](14);
        inputs[0] = "ts-node";
        inputs[1] = "api/ExactInputSwap.ts";
        inputs[2] = "--address";
        inputs[3] = vm.toString(e_account);
        inputs[4] = "--input-vault";
        inputs[5] = vm.toString(_inputVault);
        inputs[6] = "--output-vault";
        inputs[7] = vm.toString(_outputVault);
        inputs[8] = "--input-token";
        inputs[9] = vm.toString(_inputToken);
        inputs[10] = "--output-token";
        inputs[11] = vm.toString(_outputToken);
        inputs[12] = "--amount";
        inputs[13] = vm.toString(_amount);

        vm.ffi(inputs);
    }

Here we can pass through all of our trade's parameters to the scripts arguments and execute the request for a swap payload in the context of our current trades execution.

In order that we are able to read the payload file, we must update our foundry configs in foundry.toml

fs_permissions = [{ access = "read", path = "./script/payloads"}]

Now that our utilities are updated, we can jump back to the execution script and finish implementing this trades logic.

After defining all of our assets and vaults, we are going to get the balance of our COLLATERAL_TOKEN (USDC) for deposit. We are also going to get our maximum borrow amount of LIABILITY_TOKEN based on our USDC balance.

Since, at the time of writing, wS is worth 0.5 USDC and we have determined to go 7x long our initial capital, as outlined in the post describing this trade we can calculate our maxDebt at 2 wS per dollar.

// script/open.s.sol

        uint256 collateral_balance = IERC20(COLLATERAL_TOKEN).balanceOf(borrower);
        uint256 maxDebt = collateral_balance * 2e12 * 7;

Now that we have all of our amounts, we can call the euler-orderflow-router to write our payload via the previously made utility function. We also parse the resulting files in order that we may have the data ready to go.

        requestPayload(
            LIABILITY_VAULT,
            HEDGED_VAULT,
            LIABILITY_TOKEN,
            HEDGED_TOKEN,
            maxDebt
        );

        string memory swapJson = getJsonFile("./script/payloads/swapData.json");
        string memory verifyJson = getJsonFile("./script/payloads/verifyData.json");

Next, we can construct our EVC Batch of operations, we will need 7 items, starting with enabling all of the necessary vaults.

        IEVC.BatchItem[] memory batchItems = new IEVC.BatchItem[](7);

        batchItems[0] = enableCollateral(COLLATERAL_VAULT);
        batchItems[1] = enableCollateral(HEDGED_VAULT);
        batchItems[2] = enableController(LIABILITY_VAULT);

We can, then, deposit our initial capital as collateral and borrow our full amount of leverage from the liability vault into the swapper contract.

        batchItems[3] = batchDeposit(COLLATERAL_VAULT, collateral_balance);
        batchItems[4] = batchBorrowTo(LIABILITY_VAULT, maxDebt, vm.parseJsonAddress(swapJson, ".swapperAddress"));

Once that is batched, we batch the payloads for swapping and verifying(which also deposits our outputToken into it's collateral vault).

        batchItems[5] = batchPayload(vm.parseJsonAddress(swapJson, ".swapperAddress"), vm.parseJsonBytes(swapJson, ".swapperData"));
        batchItems[6] = batchPayload(vm.parseJsonAddress(verifyJson, ".verifierAddress"), vm.parseJsonBytes(verifyJson, ".verifierData"));

And with that, our batch is ready to cook! The only other execution we need, inside of our broadcast section, is the approve the COLLATERAL_VAULT an allowance to transfer our COLLATERAL_TOKEN since our batch does contain a deposit transaction.

        vm.startBroadcast();

        IERC20(COLLATERAL_TOKEN).approve(COLLATERAL_VAULT, collateral_balance);
        evc.batch(batchItems);

        vm.stopBroadcast();

Once our broadcast is complete, we can fetch our vault balances to make sure the result is as expected.

        console.log("LIABILITY TOKEN DEBT: ", debtBalance(LIABILITY_VAULT));
        console.log("HEDGED TOKEN BALANCE: ", assetsBalance(HEDGED_VAULT));
        console.log("COLLATERAL TOKEN BALANCE: ", assetsBalance(COLLATERAL_VAULT));

This is script can be run with

forge script --fork-url https://rpc.soniclabs.com --sender $SENDER script/Hedged/close.s.sol --ffi

Here, we can see how utilizing programmatic, scripted execution allows capital allocators and yield farmers to easily create more complex positions available with the EVC's modular design. Integrating multiple assets and protocols. Further scripts written in this series, for managing positions like this, will demonstrate the speed and flexibility in positioning that are available to traders who take advantage of expert defi development.

High yield defi engineering is available on demand at YieldDev Studio

Feel free to reach out on —> x for anything, technical or otherwise

Full code described above can be found on github

Full script code:

// SPDX-License-Identifier: UNLICENSED
pragma solidity ^0.8.28;

import "./common/EScript.s.sol";
import {SonicLib} from "./common/SonicLib.sol";
import { IERC20 } from "openzeppelin-contracts/contracts/token/ERC20/IERC20.sol";
contract OpenScript is EScript {
    function run() public {
        borrower = msg.sender;
        e_account = getSubaccount(borrower, 0);
        evc = IEVC(SonicLib.EVC);

        address LIABILITY_VAULT = SonicLib.EULER_WS_VAULT;
        address HEDGED_VAULT = SonicLib.EULER_PT_STS_VAULT;
        address COLLATERAL_VAULT = SonicLib.EULER_USDC_VAULT;

        address LIABILITY_TOKEN = SonicLib.WS;
        address HEDGED_TOKEN = SonicLib.PT_STS;
        address COLLATERAL_TOKEN = SonicLib.USDC;

        uint256 collateral_balance = IERC20(COLLATERAL_TOKEN).balanceOf(borrower);

        uint256 maxDebt = collateral_balance * 2e12 * 7;

        requestPayload(
            LIABILITY_VAULT,
            HEDGED_VAULT,
            LIABILITY_TOKEN,
            HEDGED_TOKEN,
            maxDebt
        );

        string memory swapJson = getJsonFile("./script/payloads/swapData.json");
        string memory verifyJson = getJsonFile("./script/payloads/verifyData.json");

        vm.label(vm.parseJsonAddress(swapJson, ".swapperAddress"), "swapperAddress");
        vm.label(vm.parseJsonAddress(verifyJson, ".verifierAddress"), "verifierAddress");

        IEVC.BatchItem[] memory batchItems = new IEVC.BatchItem[](7);

        batchItems[0] = enableCollateral(COLLATERAL_VAULT);
        batchItems[1] = enableCollateral(HEDGED_VAULT);
        batchItems[2] = enableController(LIABILITY_VAULT);

        batchItems[3] = batchDeposit(COLLATERAL_VAULT, collateral_balance);
        batchItems[4] = batchBorrowTo(LIABILITY_VAULT, maxDebt, vm.parseJsonAddress(swapJson, ".swapperAddress"));

        batchItems[5] = batchPayload(vm.parseJsonAddress(swapJson, ".swapperAddress"), vm.parseJsonBytes(swapJson, ".swapperData"));
        batchItems[6] = batchPayload(vm.parseJsonAddress(verifyJson, ".verifierAddress"), vm.parseJsonBytes(verifyJson, ".verifierData"));

        vm.startBroadcast();

        IERC20(COLLATERAL_TOKEN).approve(COLLATERAL_VAULT, collateral_balance);
        evc.batch(batchItems);

        vm.stopBroadcast();

        console.log("LIABILITY TOKEN DEBT: ", debtBalance(LIABILITY_VAULT));
        console.log("HEDGED TOKEN BALANCE: ", assetsBalance(HEDGED_VAULT));
        console.log("COLLATERAL TOKEN BALANCE: ", assetsBalance(COLLATERAL_VAULT));

    }
}

Accessing leverage in the form of of the PT's underlying token allows for massive leverage on the fixed rate, providing huge positive carry to be short the PT rate.

For example there are two markets for PT tokens on $S staked tokens which earn a fixed yield by selling the variable yield and points exposure of the underlying staked S.

One is the the PT-stS token and the other is the PT-wOS token which earn fixed yield on $S from the beets and origin protocol respectively.

The Euler MEV vault enables these PT tokens to be used as collateral to borrow the PT's underlying $S token in the form of wS (wrapped Sonic). Providing an 8.31x max multiplier on your capital to execute this trade. The PT-stS trade is particularly interesting as it trades at a APY of 11.07% and expires in 57 days.

With wS borrowing at a rate of 6.17%, the maximum return on equity for this position sits at 46.89% assuming the the actual rate of borrowed wS is realized at its current rate.

A nice extra return if you already have an allocation to $S exposure in your portfolio.

However, what if you don't want exposure to the price of $S but still want to participate in this trade?

Due to the unique design of the Euler lending market and the configuration of the MEV cluster, capital allocators can easily participate in this yield while remaining delta neutral.

Since the wS lending vault allows both USDC and PT-stS to be used as collateral, the positions equity can be entirely allocated to USDC thus funding the the entire purchase of PT-stS with a wS loan. This neutralizes all price exposure since the PT-stS will settle to S at maturity and the liability amount is denominated in wS, with the over collateraliztion requirement of the loan being satisfied by our USDC equity.

In this way, we participate in the carry trade without the currency exposure risk. The LTV settings of the wS vault allow us to borrow wS at a 77% max LTV against USDC and 88% max LTV against the PT-stS portion of our position.

We can calculate our max capital multiplier for a multi collateral position like this in this way. (Assuming 100% of our equity is in cash):

$$(M - 1) = 0.77 + 0.88(M - 1)$$

Our liquidation LTV is also a function of our multiple, as we must weight the LLTV of USDC (78%) and the LLTV of PT-stS (91.5%)

$$\text{LiquidationLTV}_{weighted} = \frac{0.78 + 0.915(M - 1)}{1 + (M - 1)}$$

The max weighted LTV allows us to run this trade at a multiple of 7.42x our starting capital. Since it's delta neutral, it won't lose USD value based on price moves from the underlying wS token. However, we still need to manage our collateralization ratio to that we do not violate the over collateralization requirements as the price of wS rises.

Note that as the price of wS rises, the LTV of the position will rise much more quickly than the weighted LLTV. This position requires tight risk management.

To allow for some headroom, assume we run this trade at 7x our starting capital. We simply need our capital in the USDC.e vault earning it's variable yield, 5.76% at the moment. We can then borrow 7x our starting capital worth of wS, paying 6.17 currently and immediately swap it for PT-stS for a fixed yield of 11%. These PT-stS are immediately deposited as collateral.

our returns, in APY, are then.

$$(11 - 6.17) \times 7 + 5.76 = 39.57$$

Using the EVC batch we can easily construct this trade to execute in a single transaction and remain in compliance with our collateral requirements. We simply batch all the transaction data for the individual trade operations outline above, including the swap, into a single evc.batch() call. This process is illustrated, in depth, in this blog post

The flexibility of EVC for batching transactions allows an on chain trader to easily and quickly use a single transaction to open, close and manage a position such as this one.

An advanced capital allocator, could farm this delta neutral yield while waiting to go long $S by having a script ready to swap some or all of the USDC collateral for more PT-stS in an instant.

A wise risk manager would have a script and a keeper bot ready to deleverage the position by swapping some of the PT-stS for wS and paying back some or all of the loan, reducing the liquidation risk if the price rises.

A technical degen might have a script to increase the leverage as the price of wS falls to maintain a capital multiplier of 7x.

All of this position management can be scripted out and executed via evc batch in a single transaction execution while maintaining the capital compliance of the position.

This delta neutral fixed rate trade can be executed across any PT asset whose underlying is borrowable against both USDC and the PT, for example WETH based PT's are also suitable for this trade.

For technical help, visit https://Yielddev Studio

For example, paying down a specific amount of debt, where the swaps output is meant to deleverage an active borrow position, is achieved by requesting a payload in target debt mode which will return swap data for purchasing a specific amount of the liability asset to pay the debt on a given account down to a specified amount. Additionally, it provides the transaction data for calling the peripheral contract to repay the debt and verify the swapped amount, called the swapVerifier. By fetching this routing data off chain and structuring them in an EVC batch transaction (which defers liquidity checks) we can efficiently and easily payoff a debt using an accounts collateral.

This is a potent tool for risk management, as it allows for deleveraging a position position with no additional collateral. It also allows on chain traders to ratchet up leveraged positions in a controlled manner without looping.

For leveraged traders, it can also be used for unwinding and closing out a leveraged long position entirely by swapping the entirety of the collateral assets and then, using an EVC batch, repaying the debt and leaving us with the net equity of our long position in cash.

In this post we are going to be looking at how this is implemented. Using typescript to fetch the swap routing data from the api and then using solidity (via forge scripts) to write our evc batch execution.

Let us take, for example, our previously discussed long PT-wstkscUSD position which is leveraged against USDC.e liability vault. Since, we are short the rate and the USDC.e borrow spread is compressed perhaps we would like to have a script ready to close out the entire position in one shot and claim our USDC profit.

First, We will need to route our order through the Euler swapper contract by providing specific function call data. Euler Swap works in two parts, first the swap executes the asset swap via whichever DEX route is provided in the data, after that we must call the swap verifier, which acts to reconcile the actual result of the swap with the output amount expected according to the slippage parameter and to execute follow up actions such as claiming the resulting tokens as a vault deposit or repaying debt.

To obtain the transaction data that routes our swap efficiently and accurately and needs to be provided to these two function we call the euler-orderflow-router API, an off chain service which retrieves and formats this data, conveniently delivering it to us for use in our transaction.

So we must write a typescript script which fetches this info for us. let us create a file called: closeToLiability.ts

We will import the required libraries and set the swap api endpoint provided by Euler.

import { ethers } from "ethers";
import axios from "axios";
import dotenv from "dotenv";
import * as fs from "fs";

dotenv.config();

const SWAP_API_URL = "https://swap.euler.finance";

now we will want to also setup an interface for interacting with the EVault contract to gather some basic information.

interface EVault {
    convertToAssets(amount: bigint): Promise<bigint>;
    balanceOf(account: string): Promise<bigint>;
    previewRedeem(amount: bigint): Promise<bigint>;
}
async function getEVaultContract(address: string, provider: ethers.JsonRpcProvider): Promise<EVault> {
    return new ethers.Contract(
        address,
        [
            "function convertToAssets(uint256) view returns (uint256)",
            "function balanceOf(address) view returns (uint256)",
            "function previewRedeem(uint256) view returns (uint256)",
            "function debtOf(address) view returns (uint256)"
        ],
        provider
    ) as unknown as EVault;
}

From here we can create the function to query the data that we are going to need for our swap. This query outlines all the info we will need to provide. In swapper mode, we are using 0 exact input mode, this means that the swap is going to consume all of the amountIn that we give it and purchase as much tokenOut as possible.

Since we are cashing out our entire position, all of the output token will be delivered to the liabilityVaultAddress which we have set in the receiver field. Once the funds are in the vault we will repay the debt and keep the rest of our balance as a deposit earning interest in the vault.

Note, also, that there is an isRepay field which we have set to false. This field is useful if the resulting output tokens from the swap are meant to pay a specified portion of the debt. This allows the swapper to calculate an input amount that results in purchasing up to the total amount of the debt when paired with swapper mode 2 target debt mode. however, since we want to swap all of our collateral via exactInput mode, setting is repay to true results in triggering an error on the vault EVault__RepayTooMuch. For this reason we will manually repay the debt and deposit the remainder as an interest bearing asset.

async function getSwapPayload(
    account: string,
    collateralVaultAddress: string,
    liabilityVaultAddress: string,
    collateralToken: string,
    liabilityToken: string,
    amountIn: string,
) {

    const queryParams = {
        chainId: "146", // sonic chain
        tokenIn: collateralToken,
        tokenOut: liabilityToken,
        amount: amountIn, // the amount to swap 
        targetDebt: "0", // irrelevant in this exactIn flow
        currentDebt: amountIn, // irrelevant in this exactIn flow
        receiver: liabilityVaultAddress,
        vaultIn: collateralVaultAddress, // left over tokenIn goes here, irrelevent for exactIn flow
        origin: account, // account executing the tx
        accountIn: account, // account holding the collateral
        accountOut: account, // account to swap to, the account that skim will deliver to 
        slippage: "0.15", // 0.15% slippage
        deadline: String(Math.floor(Date.now() / 1000) + 10 * 60), // 10 minutes from now
        swapperMode: "0", // exact input mode = 0 
        isRepay: "false", // we will manually add a call to repay the debt
    };

    const { data: response } = await axios.get(
        `${SWAP_API_URL}/swap`,
        {
            params: queryParams
        }
    );

    return response.data
}

Now we can set up all the info we need to retrieve our payload in the main function. Here we will need to set address to the actual Euler subaccount which holds our position. we will also fetch the total collateral balance to use as the amountIn in our request.

Once we have received the payload we will write the json data to two separate files, one for each of the required transactions. The first is the swapper data for actually routing the swap, the second is the verifier data which will make sure we got equal to or more output tokens than the minimum amount expected according to the slippage parameter. The verifier will also be responsible for executing the skim function on the liability vault which claims the tokens as a deposit for our account since they will be sent directly to vault after the swap.

async function main() {
    const provider = new ethers.JsonRpcProvider(process.env.SONIC_RPC_URL);
    const address = $EULER_SUBACCOUNT_ADDRESS; // the address of the euler subaccount holding the position
    const COLLATERAL_VAULT = "0xF6E2ddf7a149C171E591C8d58449e371E6dc7570"; // PTUSDC Vault
    const LIABILITY_VAULT = "0x196F3C7443E940911EE2Bb88e019Fd71400349D9" // USDC Vault

    const COLLATERAL_TOKEN = "0xBe27993204Ec64238F71A527B4c4D5F4949034C3"; // PTUSDC
    const LIABILITY_TOKEN = "0x29219dd400f2Bf60E5a23d13Be72B486D4038894"; // USDC

    const evaultContract = await getEVaultContract(COLLATERAL_VAULT, provider);
    const collateralBalance = await evaultContract.balanceOf(address);
    const withdrawAmount = await evaultContract.previewRedeem(collateralBalance);

    const swapPayload = await getSwapPayload(
        address,
        COLLATERAL_VAULT,
        LIABILITY_VAULT,
        COLLATERAL_TOKEN,
        LIABILITY_TOKEN,
        withdrawAmount.toString()
    );

    await writeToJsonFile(swapPayload.swap, "./script/closeSwapPayload.json");
    await writeToJsonFile(swapPayload.verify, "./script/closeSwapVerify.json");
    console.log("Payloads written to files")
}
main().catch((error) => {
    console.error(error);
    process.exitCode = 1;
});

Now that we have the payload written to a json file, we can write a solidity script to execute on that data.

// SPDX-License-Identifier: UNLICENSED
pragma solidity ^0.8.28;

import {Script, console} from "forge-std/Script.sol";
import {SonicLib} from "../test/common/SonicLib.sol";
import "evc/interfaces/IEthereumVaultConnector.sol";
import { EVault } from "evk/EVault/EVault.sol";

Setup our script contract

contract ClosePositionScript is Script {
    address _e_account1;
}

With two utility functions, One to get the json file data, the other to derive our Euler subaccount.

    function getSubaccount(address _account, uint256 _index) public returns (address) {
        return address(uint160(uint160(_account)^_index));
    }
    function getJsonFile(string memory _filePath) internal view returns (string memory) {
        return vm.readFile(_filePath);
    }

Next our run function holds the main logic

    function run() public {
        borrower = msg.sender;
        _e_account1 = getSubaccount(borrower, 1);
}

Now we need to setup our vault addresses and gather the payload info:

    function run() public {
        borrower = msg.sender;
        _e_account1 = getSubaccount(borrower, 1);

        address PT_USDC_VAULT = SonicLib.EULER_PT_USDC_VAULT;
        address USDC_VAULT = SonicLib.EULER_USDC_VAULT;

        address PT_USDC = SonicLib.PT_USDC;
        address USDC = SonicLib.USDC;

        address evc = SonicLib.Euler_Vault_Connector;

        string memory swapJson = getJsonFile("./script/closeSwapPayload.json");
        string memory verifyJson = getJsonFile("./script/closeSwapVerify.json");
    }

Note that, in order to open a json file via vm.readFile we need to add permissions in our foundry.toml configuration. To do this, simply add the following line:

# foundry.toml
fs_permissions = [{ access = "read", path = "./script"}]

Now we fetch the balance of our collateral shares, which we will be redeeming in order to swap and then construct the EVC Batch transaction, consisting of 4 transaction items. Let's go over each item in the batch to illustrate the process.

First, we construct a BatchItem which executes the redemption of our total collateral shares balance from our subaccount, in order to execute the swap; we set the receiver of the assets from this redemption to the swapperAddress in our swapJson file.

Next, our second BatchItem will call the swapper contract at swapperAddress with the routing data we have saved in our swapJson file. This execution will swap our collateral assets for the liability asset.

Third, we construct a call to the verifierAddress this contract holds logic that verifies our swap output was executed with acceptable slippage. Further, since it is aware of the context of our swap, it also executes the logic to call skim() on the vault address we have set as the receiver, in this case the USDC.e vault. The skim() call converts the assets which were swapped into the vault into deposits on behalf of our accountOut which we set to our Euler subaccount when requesting the payload. After this is called we will have shares representing our deposit.

Finally, we call the liability vault (USDC.e vault) to repay our outstanding debt with the newly minted shares we received from our asset deposit. Here we pass in type(uint256).max to use our entire balance to payoff our owed amount in the vault. Any remaining shares after the debt is paid off will be our remaining equity in the position in cash in the vault.

        uint256 shares = EVault(PT_USDC_VAULT).balanceOf(_e_account1);

        IEVC.BatchItem[] memory items = new IEVC.BatchItem[](4);
        items[0] = IEVC.BatchItem({
            onBehalfOfAccount: _e_account1,
            targetContract: PT_USDC_VAULT,
            value: 0,
            data: abi.encodeWithSelector(
                EVault.redeem.selector,
                shares,
                vm.parseJsonAddress(swapJson, ".swapperAddress"),
                _e_account1
            )
        });
        items[1] = IEVC.BatchItem({
            onBehalfOfAccount: _e_account1,
            targetContract: vm.parseJsonAddress(swapJson, ".swapperAddress"),
            value: 0,
            data: vm.parseJsonBytes(swapJson, ".swapperData")
        });
        items[2] = IEVC.BatchItem({
            onBehalfOfAccount: _e_account1,
            targetContract: vm.parseJsonAddress(verifyJson, ".verifierAddress"),
            value: 0,
            data: vm.parseJsonBytes(verifyJson, ".verifierData")
        });
        items[3] = IEVC.BatchItem({
            onBehalfOfAccount: _e_account1,
            targetContract: USDC_VAULT,
            value: 0,
            data: abi.encodeWithSelector(EVault.repayWithShares.selector, type(uint256).max, _e_account1)
        });

        vm.startBroadcast();
        IEVC(evc).batch(items);
        vm.stopBroadcast();

        console.log("PT BALANCE: ", EVault(PT_USDC_VAULT).balanceOf(_e_account1));
        console.log("USDC DEBT: ", EVault(USDC_VAULT).debtOf(_e_account1));
        console.log("USDC BALANCE: ", EVault(USDC_VAULT).convertToAssets(EVault(USDC_VAULT).balanceOf(_e_account1)));

We also add a few log statements to print out our position info ensuring that our collateral balance and debt are both zero. Additionally, we print our USDC.e vault asset balance after the entire transaction is complete to see our remaining assets after the position had been closed.

we can run this script in a fork to see how it all shakes out:

forge script --fork-url https://rpc.soniclabs.com script/closePosition.s.sol --sender $SENDER

Our logs should match expectations.

  PT BALANCE:  0
  ETH DEBT:  0
  USDC BALANCE:  10666666666

With this example we illustrate the utility of the euler-orderflow-router tool for managing highly leveraged on chain position. By using EVC batch we can defer all account solvency checks until the end of position closing process, allowing us to swap our entire position, close out our margin and end up with our positions equity in cash. All of this can be done in a single transaction with no additional capital or liquidity.

Knowledge of EVC and its peripheral tools provide a massive advantage to on chain traders and yield farmers, allowing them to construct flexible, use case specific scripts for quickly managing and maintaining high yield positions while also taking advantage of capital efficiency inherent in the protocol.

At YieldDev Studio we specialize in developing cutting edge, bespoke Defi applications and tools.

Feel free to contact me on X -> @yielddev

Full Code:

import { ethers } from "ethers";
import axios from "axios";
import dotenv from "dotenv";

import * as fs from "fs";

dotenv.config();

const SWAP_API_URL = "https://swap.euler.finance";
interface EVault {
    convertToAssets(amount: bigint): Promise<bigint>;
    balanceOf(account: string): Promise<bigint>;
    previewRedeem(amount: bigint): Promise<bigint>;
}
async function getEVaultContract(address: string, provider: ethers.JsonRpcProvider): Promise<EVault> {
    return new ethers.Contract(
        address,
        [
            "function convertToAssets(uint256) view returns (uint256)",
            "function balanceOf(address) view returns (uint256)",
            "function previewRedeem(uint256) view returns (uint256)",
            "function debtOf(address) view returns (uint256)"
        ],
        provider
    ) as unknown as EVault;
}

async function getSwapPayload(
    account: string,
    collateralVaultAddress: string,
    liabilityVaultAddress: string,
    collateralToken: string,
    liabilityToken: string,
    amountIn: string,
) {

    const queryParams = {
        chainId: "146",
        tokenIn: collateralToken,
        tokenOut: liabilityToken,
        amount: amountIn, // the amount to swap 
        targetDebt: "0", // irrelevant in this exactIn flow
        currentDebt: amountIn, // irrelevant in this exactIn flow
        receiver: liabilityVaultAddress,
        vaultIn: collateralVaultAddress, // left over tokenIn goes here, irrelevent for exactIn flow
        origin: account, // account executing the tx
        accountIn: account, // account holding the collateral
        accountOut: account, // account to swap to, the account that skim will deliver to 
        slippage: "0.15", // 0.15% slippage
        deadline: String(Math.floor(Date.now() / 1000) + 10 * 60), // 10 minutes from now
        swapperMode: "0", // exact input mode = 0 
        isRepay: "false", // we will manually add a call to repay the debt
    };

    const { data: response } = await axios.get(
        `${SWAP_API_URL}/swap`,
        {
            params: queryParams
        }
    );

    return response.data
}

async function writeToJsonFile(data: any, filename: string) {
    fs.writeFileSync(filename, JSON.stringify(data, null, 2));
}

async function main() {
    const provider = new ethers.JsonRpcProvider(process.env.SONIC_RPC_URL);
    const address = ""; // acc1
    const COLLATERAL_VAULT = "0xF6E2ddf7a149C171E591C8d58449e371E6dc7570"; // PTUSDC Vault
    const LIABILITY_VAULT = "0x196F3C7443E940911EE2Bb88e019Fd71400349D9" // USDC Vault

    const COLLATERAL_TOKEN = "0xBe27993204Ec64238F71A527B4c4D5F4949034C3"; // PTUSDC
    const LIABILITY_TOKEN = "0x29219dd400f2Bf60E5a23d13Be72B486D4038894"; // USDC

    const evaultContract = await getEVaultContract(COLLATERAL_VAULT, provider);
    const collateralBalance = await evaultContract.balanceOf(address);
    console.log("COLLATERAL BALANCE: ", collateralBalance)
    const withdrawAmount = await evaultContract.previewRedeem(collateralBalance);

    const swapPayload = await getSwapPayload(
        address,
        COLLATERAL_VAULT,
        LIABILITY_VAULT,
        COLLATERAL_TOKEN,
        LIABILITY_TOKEN,
        withdrawAmount.toString()
    );

    await writeToJsonFile(swapPayload.swap, "./script/closeSwapPayload.json");
    await writeToJsonFile(swapPayload.verify, "./script/closeSwapVerify.json");
    console.log("Payloads written to files")
}
main().catch((error) => {
    console.error(error);
    process.exitCode = 1;
});

// SPDX-License-Identifier: UNLICENSED
pragma solidity ^0.8.28;

import {Script, console} from "forge-std/Script.sol";
import {SonicLib} from "../test/common/SonicLib.sol";
import "evc/interfaces/IEthereumVaultConnector.sol";
import { EVault } from "evk/EVault/EVault.sol";

contract ClosePositionScript is Script {
    address borrower;
    address _e_account1;
    address _e_account2;
    function getSubaccount(address _account, uint256 _index) public returns (address) {
        return address(uint160(uint160(_account)^_index));
    }
    function getJsonFile(string memory _filePath) internal view returns (string memory) {
        return vm.readFile(_filePath);
    } 

    function run() public {
        borrower = msg.sender;
        _e_account1 = getSubaccount(borrower, 1);

        address PT_USDC_VAULT = SonicLib.EULER_PT_USDC_VAULT;
        address USDC_VAULT = SonicLib.EULER_USDC_VAULT;

        address PT_USDC = SonicLib.PT_USDC;
        address USDC = SonicLib.USDC;

        address evc = SonicLib.Euler_Vault_Connector;

        string memory swapJson = getJsonFile("./script/closeSwapPayload.json");
        string memory verifyJson = getJsonFile("./script/closeSwapVerify.json");

        uint256 shares = EVault(PT_USDC_VAULT).balanceOf(_e_account1);

        IEVC.BatchItem[] memory items = new IEVC.BatchItem[](4);
        items[0] = IEVC.BatchItem({
            onBehalfOfAccount: _e_account1,
            targetContract: PT_USDC_VAULT,
            value: 0,
            data: abi.encodeWithSelector(
                EVault.redeem.selector,
                shares,
                vm.parseJsonAddress(swapJson, ".swapperAddress"),
                _e_account1
            )
        });
        items[1] = IEVC.BatchItem({
            onBehalfOfAccount: _e_account1,
            targetContract: vm.parseJsonAddress(swapJson, ".swapperAddress"),
            value: 0,
            data: vm.parseJsonBytes(swapJson, ".swapperData")
        });
        items[2] = IEVC.BatchItem({
            onBehalfOfAccount: _e_account1,
            targetContract: vm.parseJsonAddress(verifyJson, ".verifierAddress"),
            value: 0,
            data: vm.parseJsonBytes(verifyJson, ".verifierData")
        });
        items[3] = IEVC.BatchItem({
            onBehalfOfAccount: _e_account1,
            targetContract: USDC_VAULT,
            value: 0,
            data: abi.encodeWithSelector(EVault.repayWithShares.selector, type(uint256).max, _e_account1)
        });

        vm.startBroadcast();
        IEVC(evc).batch(items);
        vm.stopBroadcast();

        console.log("PT BALANCE: ", EVault(PT_USDC_VAULT).balanceOf(_e_account1));
        console.log("USDC DEBT: ", EVault(USDC_VAULT).debtOf(_e_account1));
        console.log("USDC BALANCE: ", EVault(USDC_VAULT).convertToAssets(EVault(USDC_VAULT).balanceOf(_e_account1)));
        // forge script --fork-url https://rpc.soniclabs.com script/closePosition.s.sol --sender $SENDER

    }
}

The EVC offers several benefits for on chain trading including; standardized authentication for operator contracts to act on behalf of user accounts and built in sub accounts for segregating a user's EOA into multiple liability positions.

One of its most powerful features for scripting on chain trades is it's batch mechanism which allows several operations to be combined into a single batch call that will execute atomically. Making it much easier to create a more streamlined and gas efficient execution script and guaranteeing consistency when structuring complex positions. For lending vaults that are EVC aware and are implemented via the EVCs standardized liquidity constraints, it also provides a checks deferred execution context for batched operations.

This means that a trader can perform any number of complex operations on an account and as long the account is eventually solvent, the transaction will be valid. This eliminates the common necessity of calling a standardized flashloan and instead provides flash liquidity access out of the box.

The common, manual procedure of "looping" a defi lending position can be scripted away using an EVC batch by simply taking the maximum loan upfront, swapping into the collateral asset, and depositing into a vault thus satisfying the solvency checks at the end of the batch.

Below I describe how EVC batching can be used to migrate a position from one lending protocol (one which is not EVC aware ) onto an Euler vault based lending market in a streamlined, all solidity script, without using a flashloan.

Let's say we have an open leveraged position of PT-wstkscusd on silo with a liability of USDC.e and we would like to transfer this open position to the equivalent lending market on Euler without unwinding the position and reopening it and without access to extra capital.

We simply need to pay off our silo USDC.e debt, withdraw the PT-wstkscusd collateral from silo and deposit it into Euler. Thanks to the EVC deferred checks mechanism we can source the liquidity for this migration by taking our Euler loan upfront, satisfying our silo liabilities and eventually becoming solvent when we move the collateral over.

Let's Jump into the code and go over some of the finer points of integrating with these protocols.

First we will need to import the contract interfaces that we will be interacting with

// EvcShift.sol
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.28;
import { ISilo } from "silo-core/contracts/interfaces/ISilo.sol";
import { IERC20 } from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
import "evc/interfaces/IEthereumVaultConnector.sol";
import { EVault } from "evk/EVault/EVault.sol";
import { EVCUtil } from "evc/utils/EVCUtil.sol";

Than to setup our special purpose contract for executing the migration we will inherit EVCUtil, here we only need to define the canonical EVC contract address deployed by Euler and effective for the lending market we are operating on:

contract EvcShift {
    constructor(address _evc) EVCUtil(_evc) {}
}

Next we need to define three utility functions for our operation. A view function to read our repayment and withdrawal amounts from silo, an approval function to provide an allowance to the Euler deposit vault for our collateral, and a function that executes our silo repayment on behalf of the borrower. The repaySiloAndWithdraw will be called from inside our batch, since an external call from the evc to a contract that is not EVC aware, sees the EVC address as msg.sender in order that we may pay the debt from funds held in this contract, we write a special purpose function so that silo's transferFrom call see's our contract as msg.sender

    function repaySiloAndWithdraw(
        address _silo,
        address _collateralSilo,
        address _borrower,
        uint256 _amount,
        uint256 _maxWithdraw
    ) external {
        IERC20(ISilo(_silo).asset()).approve(address(_silo), _amount);
        ISilo(_silo).repay(_amount, _borrower);
        ISilo(_collateralSilo).withdraw(_maxWithdraw, address(this), _borrower, ISilo.CollateralType.Protected);
    }
    function getMigrationAmounts(
        address _repaySilo,
        address _collateralSilo,
        address _collateralShare,
        address _borrower
    ) internal view returns (uint256, uint256) {
        uint256 _amount = ISilo(_repaySilo).maxRepay(_borrower);
        uint256 _maxWithdraw = ISilo(_collateralSilo).convertToAssets(
            IERC20(_collateralShare).balanceOf(address(_borrower)),
            ISilo.AssetType.Protected
        );
        return (_amount, _maxWithdraw);
    }
    function approveDepositVault(
        address _collateralAsset,
        address _depositVault,
        uint256 _amount
    ) internal {
        IERC20(_collateralAsset).approve(address(_depositVault), _amount);
    }

Now, we can implement a function that executes our entire batch. First we provide as arguments all of the variables we will need for the entire operation. Note, we provide _collateralShare address as the protected collateral share token from the silo collateral vault since, protected (non-borrowable) assets on silo have a special status and share token address. The share token is held by our _borrower EOA and are used to secure the solvency of our account with regard to our debt. In order to allow withdrawal of the assets these protected shares represent by our contract, our EOA simply needs to execute and ERC20 approval on the protected share contract providing an allowance to our special purpose EvcShift contract prior to executing our migrateLoan function.

Since our contract will be able to execute a withdraw for the silo assets, we will want to ensure that only the borrower can call this function. We will also enforce that the _e_account Euler sub account is in fact a sub account of the borrower to prevent any mistakes.

Also, note that we provide _e_account argument, this is the address of our Euler subaccount of our EOA to which we want to migrate the position. We will also derive this prior to executing the migrateLoan function.

We will execute both of these actions in the script we write to deploy and execute this transaction. Additionally, we will approve our evcShift contract as an operator in the evc context to act on behalf of our _e_account. This will all be done in solidity using Forge's scripting.

Further, in our migrateLoan function we have used our utility functions to get the borrowers max repayment and withdraw amounts from the Silo vaults and have preemptively issued an allowance for the Euler _depositVault to eventually transfer our collateral assets allowing for deposit.

    function migrateLoan(
        address _repaySilo,
        address _collateralSilo,
        address _borrowToken,
        address _collateralShare,
        address _borrower,
        address _e_account,
        address _depositVault,
        address _borrowVault
    ) public {
        require(msg.sender == _borrower, "Only borrower can call this function");
        require(_haveCommonOwner(_borrower, _e_account), "_e_account must be subaccount");
        (uint256 _amount, uint256 _maxWithdraw) = getMigrationAmounts(_repaySilo, _collateralSilo, _collateralShare, _borrower);
        approveDepositVault(ISilo(_collateralSilo).asset(), _depositVault, _maxWithdraw);
    }

Now we are ready to define our batch of operations to securely migrate this position. This is also in our migrateLoan function. First we declare a list of our BatchItems, we will use 7 operations in this batch.

        IEVC.BatchItem[] memory items = new IEVC.BatchItem[](6);

Now in order to take a loan or deposit into Euler we need to set both vaults as collateral and our borrowing vault as a controller. This allows the EVC to seize our assets in the event of a solvency violation. We can see that we encode the transaction data according to the ABI. However, for these operations we are calling the EVC directly and thus must set the onBehalfOfAccount as address(0) this is because the will use a delegate call, preserving the msg.sender and authenticating the caller (our evcShift contract) as an operator for the _e_account for which we are enabling.

        items[0] = IEVC.BatchItem({
            onBehalfOfAccount: address(0),
            targetContract: address(evc),
            value: 0,
            data: abi.encodeWithSelector(IEVC.enableCollateral.selector, _e_account, _borrowVault)
        });
        items[1] = IEVC.BatchItem({
            onBehalfOfAccount: address(0),
            targetContract: address(evc),
            value: 0,
            data: abi.encodeWithSelector(IEVC.enableCollateral.selector, _e_account, _depositVault)
        });
        items[2] = IEVC.BatchItem({
            onBehalfOfAccount: address(0),
            targetContract: address(evc),
            value: 0,
            data: abi.encodeWithSelector(IEVC.enableController.selector, _e_account, _borrowVault)
        });

Once the vaults are enabled, we can take a borrow out of the _borrowVault on behalf of our _e_account. We have taken this loan against the _e_account with the receiver of the funds being our EvcShift contract. Since the _borrowVault is EVC aware it authenticates that EvcShift contract we are calling from is authorized to act on behalf of our _e_account.

        items[3] = IEVC.BatchItem({
            onBehalfOfAccount: _e_account,
            targetContract: _borrowVault,
            value: 0,
            data: abi.encodeWithSelector(EVault.borrow.selector, _amount, address(this))
        });

Once we have the USDC.e to pay off our loan we can now call our repaySiloAndWithdraw function, paying off the debt of _borrower since anyone can repay anyone else's debt in silo, no special permissions are needed here. The repaySilAndWithdraw function will also call withdraw on the collateral silo. Now, there should be no liability in the silo vault and we can now withdraw the collateral asset's into our EvcShift contract. Recall that we would need to have already granted this authority to our EvcShift contract by having our _borrower EOA approve an allowance.

        items[4] = IEVC.BatchItem({
            onBehalfOfAccount: address(this),
            targetContract: address(this),
            value: 0,
            data: abi.encodeWithSelector(this.repaySiloAndWithdraw.selector, _repaySilo, _collateralSilo, _borrower, _amount, _maxWithdraw)

Finally, to prevent all the previous operations from reverting, we deposit our collateral into the Euler _depositVault to satisfy our solvency requirements created by the loan. Since the collateral assets were withdrawn into our EvcShift contract we call this function on behalf of the EvcShift itself with the _e_account as the receiver.

        items[5] = IEVC.BatchItem({
            onBehalfOfAccount: address(this),
            targetContract: _depositVault,
            value: 0,
            data: abi.encodeWithSelector(
                EVault.deposit.selector,
                _maxWithdraw,
                _e_account
            )
        });

Now that we have structured all the operations in our batch we can execute it through the evc contract and have the EvcShift contract release its operational authority over our _e_account for safety

        evc.batch(items);
        evc.setAccountOperator(_e_account, address(this), false);

Now we can write our deploy and execution script. Start by importing the necessary contracts

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.28;

import {Script, console} from "forge-std/Script.sol";

import {EvcShift} from "../src/EvcShift.sol";
import {ISiloConfig} from "silo-core/contracts/interfaces/ISiloConfig.sol";
import {ISilo} from "silo-core/contracts/interfaces/ISilo.sol";
import {SonicLib} from "../test/common/SonicLib.sol";
import "evc/interfaces/IEthereumVaultConnector.sol";
import { EVault } from "evk/EVault/EVault.sol";
import {IERC20} from "@openzeppelin/contracts/token/ERC20/IERC20.sol";

Next, we set up the script, we will also add a utility function to derive our subaccount according to the EVC context:

contract EvcShiftScript is Script {
    EvcShift public evcShift;
    address borrower;
    ISiloConfig siloConfig;
    address ptUSDCSilo;
    address usdcSilo;

    function getSubaccount(address _account, uint256 _index) public returns (address) {
        return address(uint160(uint160(_account)^_index));
    }
}

Next we define our run function, start by getting our silo config data:

    function run() public {
        borrower = msg.sender;
        address subaccount = getSubaccount(borrower, 1);
        siloConfig = ISiloConfig(SonicLib.Silo_Config_Address_wstkscUSDC);
        (ptUSDCSilo, usdcSilo) = siloConfig.getSilos();
}

We are now ready to start the broadcasting portion of our script. First we deploy our migration contract, than we approve the contract to withdraw our silo collateral and set it as an operator on our sub account:

        vm.startBroadcast();
        evcShift = new EvcShift(SonicLib.Euler_Vault_Connector);
        ISilo(SonicLib.Silo_Address_ProtectedSHare_PT).approve(address(evcShift), UINT256_MAX);
        IEVC(SonicLib.Euler_Vault_Connector).setAccountOperator(subaccount, address(evcShift), true);
        bool isAuthorized = IEVC(SonicLib.Euler_Vault_Connector).isAccountOperatorAuthorized(subaccount, address(evcShift));
        console.log("isAuthorized: ", isAuthorized);

At this point, we can execute the migrations function.

        evcShift.migrateLoan(
            usdcSilo,
            ptUSDCSilo,
            address(ISilo(usdcSilo).asset()),
            SonicLib.Silo_Address_ProtectedSHare_PT,
            borrower,
            subaccount, // EVC subaccount
            address(SonicLib.Euler_Deposit_Vault),
            address(SonicLib.Euler_Borrow_Vault)
        );

Once that is complete. We will want to revoke all approval on silo just in case and ensure the operator released authorization.

        ISilo(SonicLib.Silo_Address_ProtectedSHare_PT).approve(address(evcShift), 0);
        console.log("Silo Allowance: ", ISilo(SonicLib.Silo_Address_ProtectedSHare_PT).allowance(address(evcShift), address(SonicLib.Silo_Address_ProtectedSHare_PT)));

        isAuthorized = IEVC(SonicLib.Euler_Vault_Connector).isAccountOperatorAuthorized(subaccount, address(evcShift));
        console.log("isAuthorized: ", isAuthorized);
        if (isAuthorized) revert();
        vm.stopBroadcast();

We can than print everything out to ensure consistency.

        console.log("maxRepayment USDC Silo: ", ISilo(usdcSilo).maxRepay(borrower));
        console.log("maxWithdraw PTUSDC Silo: ", ISilo(ptUSDCSilo).maxWithdraw(borrower, ISilo.CollateralType.Protected));

        console.log("Assets Stuck in Shift: ", IERC20(address(ISilo(ptUSDCSilo).asset())).balanceOf(address(evcShift)));
        console.log("Debt of subaccount: ", EVault(SonicLib.Euler_Borrow_Vault).debtOf(subaccount));
        console.log("Collateral of subaccount: ", EVault(SonicLib.Euler_Deposit_Vault).balanceOf(subaccount));

We can than run our script with fork to test it is working. forge script script/EvcShift.s.sol --fork-url $RPC_URL --sender $BORROWER_EOA

Full Code:

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.28;
import { ISilo } from "silo-core/contracts/interfaces/ISilo.sol";
import { IERC20 } from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
import "evc/interfaces/IEthereumVaultConnector.sol";
import { EVault } from "evk/EVault/EVault.sol";
import { EVCUtil } from "evc/utils/EVCUtil.sol";

contract EvcShift is EVCUtil {
    constructor(address _evc) EVCUtil(_evc) {}

    function repaySiloAndWithdraw(
        address _silo,
        address _collateralSilo,
        address _borrower,
        uint256 _amount,
        uint256 _maxWithdraw
    ) external {
        IERC20(ISilo(_silo).asset()).approve(address(_silo), _amount);
        ISilo(_silo).repay(_amount, _borrower);
        ISilo(_collateralSilo).withdraw(_maxWithdraw, address(this), _borrower, ISilo.CollateralType.Protected);
    }
    function getMigrationAmounts(
        address _repaySilo,
        address _collateralSilo,
        address _collateralShare,
        address _borrower
    ) internal view returns (uint256, uint256) {
        uint256 _amount = ISilo(_repaySilo).maxRepay(_borrower);
        uint256 _maxWithdraw = ISilo(_collateralSilo).convertToAssets(
            IERC20(_collateralShare).balanceOf(address(_borrower)),
            ISilo.AssetType.Protected
        );
        return (_amount, _maxWithdraw);
    }
    function approveDepositVault(
        address _collateralAsset,
        address _depositVault,
        uint256 _amount
    ) internal {
        IERC20(_collateralAsset).approve(address(_depositVault), _amount);
    }
    function migrateLoan(
        address _repaySilo,
        address _collateralSilo,
        address _borrowToken,
        address _collateralShare,
        address _borrower,
        address _e_account,
        address _depositVault,
        address _borrowVault
    ) public {
        require(msg.sender == _borrower, "Only borrower can call this function");   
        require(_haveCommonOwner(_borrower, _e_account), "Borrower and EVC account must have a common owner");

        (uint256 _amount, uint256 _maxWithdraw) = getMigrationAmounts(_repaySilo, _collateralSilo, _collateralShare, _borrower);
        approveDepositVault(ISilo(_collateralSilo).asset(), _depositVault, _maxWithdraw);

        IEVC.BatchItem[] memory items = new IEVC.BatchItem[](6);
        items[0] = IEVC.BatchItem({
            onBehalfOfAccount: address(0),
            targetContract: address(evc),
            value: 0,
            data: abi.encodeWithSelector(IEVC.enableCollateral.selector, _e_account, _borrowVault)
        });
        items[1] = IEVC.BatchItem({
            onBehalfOfAccount: address(0),
            targetContract: address(evc),
            value: 0,
            data: abi.encodeWithSelector(IEVC.enableCollateral.selector, _e_account, _depositVault)
        });
        items[2] = IEVC.BatchItem({
            onBehalfOfAccount: address(0),
            targetContract: address(evc),
            value: 0,
            data: abi.encodeWithSelector(IEVC.enableController.selector, _e_account, _borrowVault)
        });
        items[3] = IEVC.BatchItem({
            onBehalfOfAccount: _e_account,
            targetContract: _borrowVault,
            value: 0,
            data: abi.encodeWithSelector(EVault.borrow.selector, _amount, address(this))
        });
        items[4] = IEVC.BatchItem({
            onBehalfOfAccount: address(this),
            targetContract: address(this),
            value: 0,
            data: abi.encodeWithSelector(this.repaySiloAndWithdraw.selector, _repaySilo, _collateralSilo, _borrower, _amount, _maxWithdraw)
        });
        items[5] = IEVC.BatchItem({
            onBehalfOfAccount: address(this),
            targetContract: _depositVault,
            value: 0,
            data: abi.encodeWithSelector(
                EVault.deposit.selector,
                _maxWithdraw,
                _e_account
            )
        });
        evc.batch(items);
        evc.setAccountOperator(_e_account, address(this), false);
    }
}

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.28;

import {Script, console} from "forge-std/Script.sol";

import {EvcShift} from "../src/EvcShift.sol";
import {ISiloConfig} from "silo-core/contracts/interfaces/ISiloConfig.sol";
import {ISilo} from "silo-core/contracts/interfaces/ISilo.sol";
import {SonicLib} from "../test/common/SonicLib.sol";
import "evc/interfaces/IEthereumVaultConnector.sol";
import { EVault } from "evk/EVault/EVault.sol";
import {IERC20} from "@openzeppelin/contracts/token/ERC20/IERC20.sol";

contract EvcShiftScript is Script {
    EvcShift public evcShift;
    address borrower;
    ISiloConfig siloConfig;
    address ptUSDCSilo;
    address usdcSilo;
    // function setUp() public {}
    function getSubaccount(address _account, uint256 _index) public returns (address) {
        return address(uint160(uint160(_account)^_index));
    }
    function run() public {
        borrower = msg.sender;
        console.log("Borrower: ", borrower);
        address subaccount = getSubaccount(borrower, 1);
        siloConfig = ISiloConfig(SonicLib.Silo_Config_Address_wstkscUSDC);
        (ptUSDCSilo, usdcSilo) = siloConfig.getSilos();
        uint256 maxRepayment = ISilo(usdcSilo).maxRepay(borrower);

        vm.startBroadcast();
        evcShift = new EvcShift(SonicLib.Euler_Vault_Connector);
        ISilo(SonicLib.Silo_Address_ProtectedSHare_PT).approve(address(evcShift), UINT256_MAX);
        IEVC(SonicLib.Euler_Vault_Connector).setAccountOperator(subaccount, address(evcShift), true);
        bool isAuthorized = IEVC(SonicLib.Euler_Vault_Connector).isAccountOperatorAuthorized(subaccount, address(evcShift));
        console.log("isAuthorized: ", isAuthorized);

        evcShift.migrateLoan(
            usdcSilo,
            ptUSDCSilo,
            address(ISilo(usdcSilo).asset()),
            SonicLib.Silo_Address_ProtectedSHare_PT,
            borrower,
            subaccount, // EVC subaccount
            address(SonicLib.Euler_Deposit_Vault),
            address(SonicLib.Euler_Borrow_Vault)
        );

        ISilo(SonicLib.Silo_Address_ProtectedSHare_PT).approve(address(evcShift), 0);
        console.log("Silo Allowance: ", ISilo(SonicLib.Silo_Address_ProtectedSHare_PT).allowance(address(evcShift), address(SonicLib.Silo_Address_ProtectedSHare_PT)));
        isAuthorized = IEVC(SonicLib.Euler_Vault_Connector).isAccountOperatorAuthorized(subaccount, address(evcShift));
        console.log("isAuthorized: ", isAuthorized);
        if (isAuthorized) revert();
        vm.stopBroadcast();

        console.log("maxRepayment USDC Silo: ", ISilo(usdcSilo).maxRepay(borrower));
        console.log("maxWithdraw PTUSDC Silo: ", ISilo(ptUSDCSilo).maxWithdraw(borrower, ISilo.CollateralType.Protected));

        console.log("Assets Stuck in Shift: ", IERC20(address(ISilo(ptUSDCSilo).asset())).balanceOf(address(evcShift)));
        console.log("Debt of subaccount: ", EVault(SonicLib.Euler_Borrow_Vault).debtOf(subaccount));
        console.log("Collateral of subaccount: ", EVault(SonicLib.Euler_Deposit_Vault).balanceOf(subaccount));

    }
}

During the recent Sonic yield farming frenzy, Silo launched a PT-wstkscUSD-29MAY2025 vs. USDC.e lending market, allowing traders to unlock leveraged fixed yields on stablecoins.

For those prioritizing predictable returns over speculative points/gems farming, this strategy presents a lucrative opportunity.

Here’s how it works:

• Users can deposit PT assets (fixed-yielding) at approximately 12% APY.

• They can borrow USDC.e at a variable rate to increase leverage on the trade.

• The profit stems from the spread between the fixed PT yield and the variable USDC.e rate, which is currently subsidized by both Silo and Sonic points.

• If the realized variable borrowing rate at PT maturity is lower than the fixed yield at which the PT was purchased, the trader secures this spread as profit.

This also functions as a leveraged short yield trade—if the variable rate matches the fixed rate, the return is zero unless the PT fixed rate drops, causing the collateral to appreciate relative to the debt, leading to trader profit.

Currently, wstkscUSD’s yield is artificially high due to Sonic and Ring point incentives, making it an attractive negative carry trade for those betting on lower future yields.

Silo Arbitrage and the Market Response

At launch, the Silo trade was quickly arbitraged:

• PT assets were initially selling at ~15% fixed yield.

• Leverage was rapidly introduced, pulling the Silo USDC.e borrowing rate to ~10%.

• This, in turn, compressed the PT yield down to similar levels.

The best entry was early on, when PT yields were higher, allowing traders to lock in profits as borrowing costs rose gradually.

Euler Vault Emerges: A More Capital-Efficient Alternative

A few days later, MEV Capital introduced an Euler lending vault with a similar PT strategy:

• Depositing PT fixed-yielding collateral

• Borrowing USDC.e at a variable rate

However, Euler’s Interest Rate Model (IRM) proved far superior to Silo’s:

• Despite the larger supply of USDC.e being borrowable against multiple markets, Euler’s IRM offers better funding for the short-yield trade.

• Comparison at 50% utilization:

  • Silo USDC.e borrow rate: 11.74% APY

  • Euler USDC.e borrow rate: 5.44% APY

This significant cost difference is especially crucial for highly leveraged traders, making Euler a far more attractive funding environment.

However, early traders who locked into Silo when it was the only leveraged PT vault needed a seamless way to migrate their positions to Euler.

The Migration Plan: Seamlessly Shifting from Silo to Euler

Rather than manually unwinding the position—an inefficient and capital-intensive process—a secure, capital-efficient migration solution was developed.

With deep knowledge of both codebases, we quickly built and deployed a bespoke contract to execute the transfer within hours of the Euler MEV vault’s activation.

Migration Steps:

1. Authorize the contract to claim the Silo collateral assets.

2. Enable contract permissions as an operator on the Euler Vault Connector (EVC).

3. Take a flash loan in USDC.e for the total Silo debt balance.

4. Use the flash loan to repay the Silo vault debt.

5. Withdraw the full PT collateral, as no debt remains.

6. Enable PT collateral in Euler and set USDC.e borrowing vault as a controller.

7. Deposit PT collateral into the Euler vault.

8. Borrow USDC.e from the Euler vault against the deposited PT collateral.

9. Repay the flash loan in full.

10. Revoke contract permissions over the user’s account.

11. Reset Silo collateral approval to prevent future risks.

All of this executed from forge script and hardware wallet with steps 3 through 10 being a single contract call.

Conclusion: Efficient Yield Optimization

This migration strategy enabled seamless position transfer between lending platforms without requiring manual unwinding, additional capital, or unnecessary trading exposure.

By capitalizing on Euler’s superior IRM and lower borrowing rates, traders can significantly improve their leveraged yield strategies while maintaining capital efficiency.

This approach highlights the importance of early entry, market inefficiencies, and technical execution in DeFi yield arbitrage.

Full write up with more technical details to come. Feel free to contact me on X → @yielddev

YieldDev Studio

This consideration is separate from designing aspects like collateral ratio (LTV) and pertains specifically to gathering and utilizing asset price information which will eventually be included in the LTV calculation.

While the oracle problem is largely solved by many industry provider like chainlink, pyth or redbrick; understanding the what the prices delivered by these providers are actually based off of and how to best integrate them into the specific use case of your DeFi application are of critical importance.

For the most part, this issue comes down to risk management particularly as it pertains to liquidations on any platform that allows users access to leveraged products and loans.

Defi application offering leverage, generally serve two parties the liquidity provider and the trader and thus, must balance offering the highest possible leverage for the trader and the most collateral safety for the LP. When a trader's collateral is liquidated at a price that results in proceeds less than the amount of the loan owed to the LP this balance is violated and the difference in value is marked as bad debt resulting in an impairment of the liquidity provider pools funds.

For this reason, a safety ratio is often built into the lending markets design resulting in two critical numbers attached to any loan that is opened. The initial margin requirement and the maintenance margin requirement.

There Is No Price

Thinking of the price as single, definitive number is a misconception. Allow us to briefly re-conceptualize price. Price is, of course, what someone is willing to pay. However, if we invert this statement, price is what someone is willing to receive. From this stand point, it is easy to imagine that these numbers are different depending on whether we are looking to buy something or looking to sell it. We need only imagine a limit order book for any asset to understand that, at any given moment, the only definitive is that there is one price at which we know a party is willing to buy and another price at which we know a party is willing to sell. These must be different prices, or else the two parties would have already bought and sold from each other leaving us to have to find a different party to buy or sell from at an even different price point.

True market pricing, involves a bid / ask price. a price for buying and a price for selling.

Mark To Market, Mark To Model

So, When our DeFi application calls an oracle and gets a single number, we think of it as a price but is it a market price? No. In this case we are working with some model of a price. A useful approximation used to evaluate the our assets in an application specific way.

For example, if we have a DeFi application with two pools, one of ETH and one of WBTC. We might fetch some general price, like the last trade price, for both BTC and ETH in terms of USD. We then multiply the amount of ETH by the USD price of eth and the amount of WBTC by the USD price of BTC, add the two numbers together, call it our TVL and display it on our front end. "$xxx,xxx,xxx Total Value Locked"

Pretty harmless assumption to make that the last trade price is a good price to use in this scenario because the result of this calculation is merely cosmetic and not mission critical to the application. But, can we really expect the receive $xxx,xxx,xxx in exchange for liquidating both pools for USD at this moment. Absolutely not, we have just naively marked marked all the assets locked in out pools at the last trade price.

However, in the case of a loan or leveraged position, we are fetching a price and marking an asset value because we expect we might actually have to liquidate the assets immediately, into the market in the case of a collateral ratio violation (loan liquidation). In this situation, we actually we want to be very confident of the value we can actually get for selling these assets at this moment. The last trade price is not a good model to mark by for several reasons. How long ago was this trade made at this price? In what size was the this trade executed at for this price? Was this trade executed as a buy or sell?

We can see, though this example is absurd, that there are many considerations about how a price was arrived at (the model) when marking collateral to certain price. In order to manage the risk of a lending market, we need to have strong confidence in what value can we actually receive if we liquidated a certain amount of a collateral asset at this moment.

The Models

Considering that we know understand why we need different models of pricing for different situations, let us review a few basic price types. First, we can think about a perps exchange allowing counterparties to trade futures against each other on a perpetual basis. Exchanges like Bitmex or even DEXs rely on an index price to mark the value of futures contracts P/L against the associated margin of a trader. Combining prices from several liquid exchanges, using a formula that weights each price based on the volume, they create a Volume weighted average price across all the exchanges and mark position based off of this model of pricing.

If we had some simple graphic displaying the ticker of a given asset, meant for nothing more than to give the user a general idea of what price that asset might be trading around. A website will often call an exchanges api, which provides the current bid/ask price and then take the mid-point, a price directly in between the spread and display it as the price.

On chain applications, typically using the popular UniswapV3 price as an oracle, are calling a price from a highly liquid uniswapV3 pool which represents the time weighted average price of an asset, TWP. A the TWAP calculates the geometric mean of relative prices of the two assets in a pool over a certain rolling window. The rationale for using this model on chain, versus the VWAP (volume weighted price) used in traditional markets, is primarily on of security. This is because one popular vectors of attack against lending markets is to temporarily manipulate the price of an asset inside of the pool used as a reference price and earn a greater profit than the cost of the manipulation on the lending market as a consequence of this mis-pricing. However, since this price is calculated over a certain window of time, an attacker must manipulate the price over a longer period in order to affect the mark price used in lending markets thus making such an attack infeasible.

Liquidity and Size

An additional consideration when pricing collateral assets, especially with regards to liquidation is the size of the potential liquidation and the depth of the liquidity in the market you might liquidate into.

This is particularly important for exotic markets, even less exotic markets such as options, where the market liquidity may be thinner than a standard blue-chip asset like ETH. Fragmentations of market liquidity pools is also an important factor to take note of when designing a lending market.

Especially in ultra high leverage markets, where the margin of safety with regards to a user's collateral ration is razor thin, the price slippage of liquidating a large position into a thin market can cause serious insolvency issues and create bad debt. Practically speaking, the higher the leverage and the thinner the market liquidity, the more pessimistic your implementation should be when assigning a value collateral assets.

One design consideration that could be made is adjusting the pricing model in addition to the collateral ratio to manage risk on a size aware basis. It may be appropriate for a smaller loan (relative to the market liquidity) to have a lower collateral ratio requirement than a larger one on the basis that liquidations on a smaller loan will execute at a better effective price. Further, the oracle mechanism that fetches the price and assigns a value to the collateral of a given position can take into account the size of the position when marking a price given the available liquidity providing a more pessimistic (less risky) model to mark the collateral. Though, in practice, fetching the depth of market liquidity is a difficult task and is currently an emergent research topic.

Implementation

So, now let us outline the actionable take aways from these considerations.

First, when fetching oraclized price data on-chain, we must implement EIP-7726. Since, oracles typically return a fixed price ticker, it is essential to wrap them in a standard interface that shifts our conception (as well as our interactions) with this price data from one of fetching a definitive price to fetching a quote

The getQuote interface, implemented by EIP-7726, allows contract calls to request a quote for a certain amount of a certain asset in terms of another asset.

In this way, we get to the heart of our actual requirement in a lending market. The price of 1 ether is not actually relevant to us when we are trying to manage the risk of a USDC loan collateralized by ETH. Instead, we care about how much USDC we can receive were we to liquidate a specific amount of collateral. Thus, getting a quote for a position's collateral assets more closely aligns our conceptualization of the oracles function to the requirements of our application.

We can also implement bid/ask awareness when fetching the price of an asset. In the event of a liquidation are we buying or selling into this market? Specifying the direction of a liquidation helps us fetch a more pessimistic price assumption.

Further our design needs to carefully consider the purpose of quoting these asset's value. Do we need an index price? weighting across several markets based on volume in order to enforce some contract between counterparties? or do we need a price that is resistant to manipulation such as TWAP?

Lastly, we need to consider the amount leverage that is offered to traders (borrowers) on our platform and how can we best model a quote that effectively manages the risk to our liquidity provider (lenders). How will the platform manager open interest vs market depth to create a platform large liquidations don't encounter price slippage that effects the solvency of the LPs.

Here must make careful considerations when designing a DeFi application that balances risk management, high leverage and usability to carefully engineer an efficient and valuable platform.

At Yield Dev Studio we specialize in DeFi design and development. Reach out if you before you undertake your next project.

Following along with the previous two tutorials, we should have a forge project with the following src/ directory.

-src/
    -EVCClient.sol
    -VaultBase.sol
    -VaultSimple.sol
    -VaultSimpleBorrowable

We will start off by testing the deposit only VaultSimple.sol The initial setup will involve importing the EVC contract and a MockERC20 for testing as well as our VaultSimple contract. In the testy setUp() we will deploy everything and then run a simple test to ensure its metadata is properly defined.

Additionally we define a test user, Alice, which will hold 1000 units of our mock token for depositing

// test_vault_simple.t.sol

// SPDX-License-Identifier: UNLICENSED
pragma solidity ^0.8.13;
import { Test, console } from "forge-std/Test.sol";
import "evc/EthereumVaultConnector.sol";
import { MockERC20 } from "solmate/test/utils/mocks/MockERC20.sol";
import { VaultSimple } from "../src/VaultSimple.sol";

contract VaultSimpleTest is Test {
    IEVC evc;
    MockERC20 collateralAsset;
    VaultSimple vault;
    address alice = address(0x69);
    uint256 aliceDeposit = 1000;

    function setUp() public {
        evc = new EthereumVaultConnector();
        collateralAsset = new MockERC20("Collateral Asset", "CA", 18);
        vault = new VaultSimple(address(evc), collateralAsset, "Simple Collateral Vault", "SCV");

        collateralAsset.mint(alice, aliceDeposit);
        vm.prank(alice);
        collateralAsset.approve(address(vault), aliceDeposit);
    }

    // Test vault deployed with metadata
    function test_deployed_vault() public {
        assertEq(vault.name(), "Simple Collateral Vault");
        assertEq(vault.symbol(), "SCV");
    }

}

Next, we will test out a simple deposit which, according to ERC4626, should simply wrap alice's tokens in our vault's shares at a 1:1 ratio.

    // Test Deposit 
    function test_deposit() public {
        vm.prank(alice);
        vault.deposit(aliceDeposit, alice); // direct call to deposit is rerouted through the EVC via it's modifier logic

        assertEq(vault.balanceOf(alice), aliceDeposit); // 1:1 share to asset caclulation in this case
        assertEq(collateralAsset.balanceOf(alice), 0);
        assertEq(vault.totalAssets(), aliceDeposit);
    }

Further, we will test the withdraw functionality,

    // Test Withdraw
    function test_withdraw() public {
        vm.prank(alice);
        vault.deposit(aliceDeposit, alice);

        vm.prank(alice);
        vault.withdraw(shares, alice, alice); // withdraw a certain amount of assets for the vaults shares
        assertEq(vault.balanceOf(alice), 0);
        assertEq(collateralAsset.balanceOf(alice), shares);
    }

mint() and redeem() are similar operations to deposit withdraw and are also defined in ERC4626. Where deposit/withdraw take the amount of tokens to put into, or remove from the vault as arguments, the mint/ redeem functions take the amount of shares worth of tokens to be removed or added to the vault. We test these functions as well.

    // Test mint and redeem 
    function test_mint_redeem() public {
        vm.prank(alice);
        vault.mint(aliceDeposit, alice); // here put the amount of shares we want to mint as an argument

        assertEq(vault.balanceOf(alice), aliceDeposit); // 1:1 share to asset caclulation in this case
        assertEq(collateralAsset.balanceOf(alice), 0);
        assertEq(vault.totalAssets(), aliceDeposit); 

        uint256 shares = vault.balanceOf(alice);

        vm.prank(alice);
        vault.redeem(shares, alice, alice); // redeem a certain amount of shares for the underlying asset
    }

Thus far, we have only tested the basic functionality inherited from ERC4626 vaults. In this next example we will see how the EVC facilitates lending interactions in our VaultSimpleBorrowable.

Setting up our tests, similarly to our VaultSimple test, We deploy an EVC contract along with our borrowable vault.

contract VaultSimpleBorrowableTest is Test {
    IEVC evc;
    MockERC20 borrowableAsset;
    VaultSimpleBorrowable vault;
    address alice = address(0x69);
    uint256 aliceDeposit = 1000;
    function setUp() public {
        evc = new EthereumVaultConnector();
        borrowableAsset = new MockERC20("Borrowable Asset", "CA", 18);
        vault = new VaultSimpleBorrowable(address(evc), borrowableAsset, "Simple Borrowable Vault", "SBV");

        borrowableAsset.mint(alice, aliceDeposit);
        vm.prank(alice);
        borrowableAsset.approve(address(vault), type(uint256).max);
    }
}

First thing to note is that we constructed this vault as a simple borrowable vault using its own deposits as collateral for its own assets at 90% of its value. We did this for simplicity to demonstrate borrowing functionality. In a later post we will extend this contract to a more real world scenario where we can borrow from this vault with our initial VaultSimple deposits as collateral.

First, our test will have Alice deposit into the vault and than borrow 90% of those tokens and subsequently repay those same tokens. Doing this we will see how the EVC comes into play in these interaction.

After Alice has deposited, in order that she may borrow from the vault she must take two actions via the EVC. First, calling the evc.enableController(alice, vault) which enables the vault to control Alice's account through the EVC according the terms of the vaults collateral requirements. This effectively gives the vault a lien on Alice's available collaterals. Second, Alice must opt-in to allowing the EVC to use certain deposits as collateral for various actions, this is done by calling evc.enableCollateral(alice, vault). In summary, Alice must authorize the EVC to, both use specific vaults as collateral and allow a specific vault to control that collateral.

    function test_borrow_repay() public {
        vm.prank(alice);
        uint256 shares = vault.deposit(aliceDeposit, alice);

        assertEq(vault.balanceOf(alice), aliceDeposit);
        assertEq(borrowableAsset.balanceOf(alice), 0);
        assertEq(vault.totalAssets(), aliceDeposit);

        vm.prank(alice);
        evc.enableController(alice, address(vault));

        vm.prank(alice);
        evc.enableCollateral(alice, address(vault));

        vm.prank(alice);
        vault.borrow((aliceDeposit * 9) / 10, alice);

        vm.prank(alice);
        vault.repay((aliceDeposit * 9) / 10, alice);

        assertEq(borrowableAsset.balanceOf(alice), 0);
        assertEq(vault.balanceOf(alice), shares);
        assertEq(vault.debtOf(alice), 0);

    }

Recall that the callThroughEVC function modifiers on the repay/borrow function reroute these direct function calls to be made through the EVC. However, the EVC itself exposes some powerful functionality which we can use directly to call this contract with better UX. One such feature is the EVC batch allowing us to use the EVC as a multicall combining all these calls into a single transaction.

To do this we create a list of IEVC.BatchItem structs containing the encoded transaction execution data which the EVC with authenticate and execute in a single transaction.

    function test_borrow_with_evc_batch() public {

        IEVC.BatchItem[] memory items = new IEVC.BatchItem[](4);
        items[0] = IEVC.BatchItem({
            targetContract: address(vault),
            onBehalfOfAccount: alice,
            value: 0, 
            data: abi.encodeWithSelector(VaultSimple.deposit.selector, aliceDeposit, alice)
        });
        items[1] = IEVC.BatchItem({
            targetContract: address(evc),
            onBehalfOfAccount: address(0),
            value: 0, 
            data: abi.encodeWithSelector(IEVC.enableController.selector, alice, address(vault))
        });
        items[2] = IEVC.BatchItem({
            targetContract: address(evc),
            onBehalfOfAccount: address(0),
            value: 0, 
            data: abi.encodeWithSelector(IEVC.enableCollateral.selector, alice, address(vault))
        });
        items[3] = IEVC.BatchItem({
            targetContract: address(vault),
            onBehalfOfAccount: alice,
            value: 0, 
            data: abi.encodeWithSelector(VaultSimpleBorrowable.borrow.selector, (aliceDeposit * 9) / 10, alice)
        });

        vm.prank(alice);
        evc.batchSimulation(items);
        vm.prank(alice);
        evc.batch(items);

        assertEq(borrowableAsset.balanceOf(alice), (aliceDeposit * 9) / 10);
        assertEq(vault.maxWithdraw(alice), aliceDeposit - (aliceDeposit * 9) / 10);
        assertEq(vault.debtOf(alice), (aliceDeposit * 9) / 10);
    }

By implementing these tests, we have seen how the EVC is used to authenticate and mediate interactions between a user's account and our vaults.

In the next post we will further extend our VaultSimpleBorrowable to illustrate how the EVC is used to mediate interactions between vaults. Thus, completing our simple lending market.

Full code can, once again, be found in the EVC Playground Repo

To get started, we will import the VaultSimple we will be extending and define some borrow specific events.

// SPDX-License-Identifier: GPL-2.0-or-later

pragma solidity ^0.8.19;

import "./VaultSimple.sol";

/// @title VaultSimpleBorrowable
/// @notice This contract extends VaultSimple to add borrowing functionality.
/// @notice In this contract, the EVC is authenticated before any action that may affect the state of the vault or an
/// account. This is done to ensure that if it's EVC calling, the account is correctly authorized and the vault is
/// enabled as a controller if needed. This contract does not take the account health into account when calculating max
/// withdraw and max redeem values. This contract does not implement the interest accrual hence it returns raw values of
/// total borrows and 0 for the interest accumulator in the interest accrual-related functions.
contract VaultSimpleBorrowable is VaultSimple {
    using SafeTransferLib for ERC20;
    using FixedPointMathLib for uint256;

    event BorrowCapSet(uint256 newBorrowCap);
    event Borrow(address indexed caller, address indexed owner, uint256 assets);
    event Repay(address indexed caller, address indexed receiver, uint256 assets);

    error BorrowCapExceeded();
    error AccountUnhealthy();
    error OutstandingDebt();

    uint256 public borrowCap;
    uint256 internal _totalBorrowed;
    mapping(address account => uint256 assets) internal owed;

    constructor(
        address _evc,
        ERC20 _asset,
        string memory _name,
        string memory _symbol
    ) VaultSimple(_evc, _asset, _name, _symbol) {}
}

The borrowable vault will also need a setter function to allow the vault governor (owner) to set the borrow cap of the vault

    /// @notice Sets the borrow cap.
    /// @param newBorrowCap The new borrow cap.
    function setBorrowCap(uint256 newBorrowCap) external onlyOwner {
        borrowCap = newBorrowCap;
        emit BorrowCapSet(newBorrowCap);
    }

Next, the vault will implement two view function to get information about the debt. The first being the totalBorrowed amount for the entire vault. This implementation will call the _accrueInterestCalculation, which is an internal function that will be implemented later on, to return the total borrowed including outstanding interest. For now, we simply assume 0 interest rate as we will define an interest rate model later on.

    /// @notice Returns the total borrowed assets from the vault.
    /// @return The total borrowed assets from the vault.
    function totalBorrowed() public view virtual returns (uint256) {
        (uint256 currentTotalBorrowed,,) = _accrueInterestCalculate();
        return currentTotalBorrowed;
    }

    /// @notice Calculates the accrued interest.
    /// @dev Because this contract does not implement the interest accrual, this function does not need to calculate the
    /// interest, but only returns the current value of total borrows, 0 for the interest accumulator and false for the
    /// update flag. This function is needed so that it can be overriden by child contracts without a need to override
    /// other functions which use it.
    /// @return The total borrowed amount, the interest accumulator and a boolean value that indicates whether the data
    /// should be updated.
    function _accrueInterestCalculate() internal view virtual returns (uint256, uint256, bool) {
        return (_totalBorrowed, 0, false);
    }

Additionally, the borrowable vault will expose a view function for the users account debt, implemented by calling an internal function to return the accounts mapping of its outstanding debt.

    /// @notice Returns the debt of an account.
    /// @param account The account to check.
    /// @return The debt of the account.
    function debtOf(address account) public view virtual returns (uint256) {
        return _debtOf(account);
    }

    /// @notice Returns the debt of an account.
    /// @param account The account to check.
    /// @return The debt of the account.
    function _debtOf(address account) internal view virtual returns (uint256) {
        return owed[account];
    }

Next, we implement function overrides for maxWithdraw and maxRedeem since, in the context of our borrowable vault, the maximum amount withdraw-able must be adjusted to account for the fact that some funds from the vault might be lent out at the time of withdrawal. Thus the maximum amount that can be withdrawn from the vault is either the user's deposited balance or the total amount in the vault if some of the user's balance happens to be lent out.

    /// @notice Returns the maximum amount that can be withdrawn by an owner.
    /// @dev This function is overridden to take into account the fact that some of the assets may be borrowed.
    /// @param owner The owner of the assets.
    /// @return The maximum amount that can be withdrawn.
    function maxWithdraw(address owner) public view virtual override returns (uint256) {
        uint256 totAssets = _totalAssets;
        uint256 ownerAssets = _convertToAssets(balanceOf[owner], false);

        return ownerAssets > totAssets ? totAssets : ownerAssets;
    }

    /// @notice Returns the maximum amount that can be redeemed by an owner.
    /// @dev This function is overridden to take into account the fact that some of the assets may be borrowed.
    /// @param owner The owner of the assets.
    /// @return The maximum amount that can be redeemed.
    function maxRedeem(address owner) public view virtual override returns (uint256) {
        uint256 totAssets = _totalAssets;
        uint256 ownerShares = balanceOf[owner];

        return _convertToAssets(ownerShares, false) > totAssets ? _convertToShares(totAssets, false) : ownerShares;
    }

Now since our borrowable vault has a different application requirements than our deposit only vault, we need to override the vault snapshot function to return the vault's state values that are relevant to the calculations required by our application. In the case of a borrowable vault, this would be the total assets and the currentTotalBorrowed. Further, since this function is called to cache the state of the vault prior to any actions that effect the vault's state (i.e before a borrow, repayment etc) we use this opportunity to update the _accrueInterest calculation ensuring the totalBorrowed value remains consistent and up to date.

    /// @notice Creates a snapshot of the vault.
    /// @dev This function is called before any action that may affect the vault's state. Considering that and the fact
    /// that this function is only called once per the EVC checks deferred context, it can be also used to accrue
    /// interest.
    /// @return A snapshot of the vault's state.
    function doCreateVaultSnapshot() internal virtual override returns (bytes memory) {
        (uint256 currentTotalBorrowed,) = _accrueInterest();

        // make total assets and total borrows snapshot:
        return abi.encode(_totalAssets, currentTotalBorrowed);
    }

    /// @notice Accrues interest.
    /// @dev Because this contract does not implement the interest accrual, this function does not need to update the
    /// state, but only returns the current value of total borrows and 0 for the interest accumulator. This function is
    /// needed so that it can be overriden by child contracts without a need to override other functions which use it.
    /// @return The current values of total borrowed and interest accumulator.
    function _accrueInterest() internal virtual returns (uint256, uint256) {
        return (_totalBorrowed, 0);
    }

Additionally, we will need to update the vault status check logic, doCheckVaultStatus is a check that is called after an action that may change a vault's state. Thus, this function takes the previous vault snapshot as an argument and implements logic the validate that the new state of the vault, after an action has been called, remains consistent and conforms to the constraints of our vaults requirements. In this case, that means we check that the supplyCap and the borrowCap have not been violated. Further, since the interest rate of a lending market is a function of the amount borrowed and the total assets in the vault, both of which may have been updated in the action preceding this check, we use this opportunity to call the internal _updateInteres() function. For now, we will leave this unimplemented as we are not charging interest in this example

    /// @notice Checks the vault's status.
    /// @dev This function is called after any action that may affect the vault's state. Considering that and the fact
    /// that this function is only called once per the EVC checks deferred context, it can be also used to update the
    /// interest rate. `IVault.checkVaultStatus` can only be called from the EVC and only while checks are in progress
    /// because of the `onlyEVCWithChecksInProgress` modifier. So it can't be called at any other time to reset the
    /// snapshot mid-batch.
    /// @param oldSnapshot The snapshot of the vault's state before the action.
    function doCheckVaultStatus(bytes memory oldSnapshot) internal virtual override {
        // sanity check in case the snapshot hasn't been taken
        if (oldSnapshot.length == 0) revert SnapshotNotTaken();

        // use the vault status hook to update the interest rate (it should happen only once per transaction).
        // EVC.forgiveVaultStatus check should never be used for this vault, otherwise the interest rate will not be
        // updated.
        // this contract doesn't implement the interest accrual, so this function does nothing. needed for the sake of
        // inheritance
        _updateInterest();

        // validate the vault state here:
        (uint256 initialAssets, uint256 initialBorrowed) = abi.decode(oldSnapshot, (uint256, uint256));
        uint256 finalAssets = _totalAssets;
        (uint256 finalBorrowed,,) = _accrueInterestCalculate();

        // the supply cap can be implemented like this:
        if (
            supplyCap != 0 && finalAssets + finalBorrowed > supplyCap
                && finalAssets + finalBorrowed > initialAssets + initialBorrowed
        ) {
            revert SupplyCapExceeded();
        }

        // or the borrow cap can be implemented like this:
        if (borrowCap != 0 && finalBorrowed > borrowCap && finalBorrowed > initialBorrowed) {
            revert BorrowCapExceeded();
        }
    }

    /// @notice Updates the interest rate.
    function _updateInterest() internal virtual {}

Along with requiring vault checks after an action updates the vault's state, our borrowable vault will also require checks after an account's state is updated. For the purposes of our lending market, these checks will be centered around ensuring that any action does not result in our account ending up in an unhealthy state. To do this we will first call the internal _calculateLiabilityAndCollateral call and then check that the liability value is not greater than the value of our collateral. Since our EVC lending market is modular and extendable to any arbitrary collateral vault we use the account and a list of collaterals for the account as arguments.

In this example we will simply create a placeholder collateralValue calculation, implementing a check that requires the only collateral value returned be the same asset deposited into this (the borrowable vault) at 90% of it's value. Later on will modify this function to integrate with our initial deposit only vault. We will also save gas by offering a flag bypassing the collateral check if the account has no liabilities (debt)

    /// @notice Checks the status of an account.
    /// @dev This function is called after any action that may affect the account's state.
    /// @param account The account to check.
    /// @param collaterals The collaterals of the account.
    function doCheckAccountStatus(address account, address[] calldata collaterals) internal view virtual override {
        (, uint256 liabilityValue, uint256 collateralValue) =
            _calculateLiabilityAndCollateral(account, collaterals, true);

        if (liabilityValue > collateralValue) {
            revert AccountUnhealthy();
        }
    }

    /// @notice Calculates the liability and collateral of an account.
    /// @param account The account.
    /// @param collaterals The collaterals of the account.
    /// @param skipCollateralIfNoLiability A flag indicating whether to skip collateral calculation if the account has
    /// no liability.
    /// @return liabilityAssets The liability assets.
    /// @return liabilityValue The liability value.
    /// @return collateralValue The risk-adjusted collateral value.
    function _calculateLiabilityAndCollateral(
        address account,
        address[] memory collaterals,
        bool skipCollateralIfNoLiability
    ) internal view virtual returns (uint256 liabilityAssets, uint256 liabilityValue, uint256 collateralValue) {
        liabilityAssets = _debtOf(account);

        if (liabilityAssets == 0 && skipCollateralIfNoLiability) {
            return (0, 0, 0);
        } else if (liabilityAssets > 0) {
            // pricing doesn't matter
            liabilityValue = liabilityAssets;
        }

        // in this simple example, let's say that it's only possible to borrow against
        // the same asset up to 90% of its value
        for (uint256 i = 0; i < collaterals.length; ++i) {
            if (collaterals[i] == address(this)) {
                collateralValue = _convertToAssets(balanceOf[account], false) * 9 / 10;
                break;
            }
        }
    }

Now, two of our view function from our SimpleVault will need to be overridden. The _convertToAssets and _convertToShares use the totalAssets to determine the share to asset conversion, however in the context of our lending vault we need to account for the totalBorrowed amount in this calculation.

    /// @dev This function is overridden to take into account the fact that some of the assets may be borrowed.
    function _convertToShares(uint256 assets, bool roundUp) internal view virtual override returns (uint256) {
        (uint256 currentTotalBorrowed,,) = _accrueInterestCalculate();

        return roundUp
            ? assets.mulDivUp(totalSupply + 1, _totalAssets + currentTotalBorrowed + 1)
            : assets.mulDivDown(totalSupply + 1, _totalAssets + currentTotalBorrowed + 1);
    }

    /// @dev This function is overridden to take into account the fact that some of the assets may be borrowed.
    function _convertToAssets(uint256 shares, bool roundUp) internal view virtual override returns (uint256) {
        (uint256 currentTotalBorrowed,,) = _accrueInterestCalculate();

        return roundUp
            ? shares.mulDivUp(_totalAssets + currentTotalBorrowed + 1, totalSupply + 1)
            : shares.mulDivDown(_totalAssets + currentTotalBorrowed + 1, totalSupply + 1);
    }

Our vault will also need to implement methods to increase and decrease the amount owed by any account taking a loan from the vault.

    /// @notice Increases the owed amount of an account.
    /// @param account The account.
    /// @param assets The assets.
    function _increaseOwed(address account, uint256 assets) internal virtual {
        owed[account] += assets;
        _totalBorrowed += assets;
    }

    /// @notice Decreases the owed amount of an account.
    /// @param account The account.
    /// @param assets The assets.
    function _decreaseOwed(address account, uint256 assets) internal virtual {
        owed[account] -= assets;

        uint256 __totalBorrowed = _totalBorrowed;
        _totalBorrowed = __totalBorrowed >= assets ? __totalBorrowed - assets : 0;
    }

Finally, we need to implement the lending functionality for our vault. First, we provide a view function to get the liability status of an account. We also need to provide the functionality for a users account to disassociate with the vault as a controller if it has no debt.

    /// @notice Disables the controller.
    /// @dev The controller is only disabled if the account has no debt. If the account has outstanding debt, the
    /// function reverts.
    function disableController() external virtual override nonReentrant {
        // ensure that the account does not have any liabilities before disabling controller
        address msgSender = _msgSender();
        if (_debtOf(msgSender) == 0) {
            EVCClient.disableController(msgSender);
        } else {
            revert OutstandingDebt();
        }
    }

    /// @notice Retrieves the liability and collateral value of a given account.
    /// @dev Account status is considered healthy if the collateral value is greater than or equal to the liability.
    /// @param account The address of the account to retrieve the liability and collateral value for.
    /// @return liabilityValue The total liability value of the account.
    /// @return collateralValue The total collateral value of the account.
    function getAccountLiabilityStatus(address account)
        external
        view
        virtual
        returns (uint256 liabilityValue, uint256 collateralValue)
    {
        (, liabilityValue, collateralValue) = _calculateLiabilityAndCollateral(account, getCollaterals(account), false);
    }

We now have all the functionality necessary to write our borrow logic. To do this we must first add a modifier to the function requiring that it be called through the EVC to ensure that borrow conforms to the constraints of our vault by requiring it to be called via the EVC.

By setting the msgSender to _msgSenderForBorrow() we ensure that, since the function can only be called via the EVC, the EVC caller is calling the operation on behalf of an account which it is authorized to do so. This means it checks whether the caller an the authenticated EVC caller or an enabled controller vault.

Next, the function creates a vault snapshot to make sure the state variables remain consistent throughout the operation. We can than increase the amount owed by the account, emit a borrow event and transfer the borrowed assets to the receiver.

Finally, the accounting is finalized by reducing the global _totalAssets counter by the amount borrowed. Note that, the global _totalBorrowed amount is already updated via the _increseOwed() function's logic. This operation requires that we call the checks function for the vault and account after all state updating operations, ensuring the maximum borrow amount for the vault is respected and that the account health requirement for the borrower is also respected.

    /// @notice Borrows assets.
    /// @param assets The amount of assets to borrow.
    /// @param receiver The receiver of the assets.
    function borrow(uint256 assets, address receiver) external callThroughEVC nonReentrant {
        address msgSender = _msgSenderForBorrow();

        createVaultSnapshot();

        require(assets != 0, "ZERO_ASSETS");

        _increaseOwed(msgSender, assets);

        emit Borrow(msgSender, receiver, assets);

        asset.safeTransfer(receiver, assets);

        _totalAssets -= assets;

        requireAccountAndVaultStatusCheck(msgSender);
    }

The next function our lending market is going to need to implement is the ability for a debt to be repaid. Again, this function will be modified to require calling it through the EVC. However, the _msgSender() for this function will set to the result of the evc.getCurrentOnBehalfOfAccount() call. This is the account which has authenticated the call with the EVC. Since anyone can payoff the debt of an account, we don't need to call messageSenderForBorrow() which ensures the caller is controllerEnabled.

Once the call is authenticated and before any state is updated, we again need to create a vault snapshot. We are then free to transfer the repayment assets from the msgSender to the vault contract. update the _totalAssets global variable and call the _decreaseOwed function on the account being paid off. Once again, since we are updating an account and vault's state, we need to call requireAccountAndVaultStatusCheck after all operation have been completed to ensure consistency. However, keeping in mind our application specific requirements (a lending market) we can reason that we may want to allow an account to be unhealthy after repaying debt.

For example, if an account begins this operation in an unhealthy state and is paying back an amount that does not fully restore the accounts solvency we may still want to allow the operation to complete since it benefits the stability of our lending market. So, instead of passing the account being operated on as the status check argument, we can pass address(0) which tells the logic of the requireAccountAndVaultStatusCheck to simply call the evc.requireVaultStatusCheck() along.

    /// @notice Repays a debt.
    /// @dev This function transfers the specified amount of assets from the caller to the vault.
    /// @param assets The amount of assets to repay.
    /// @param receiver The receiver of the repayment.
    function repay(uint256 assets, address receiver) external callThroughEVC nonReentrant {
        address msgSender = _msgSender();

        // sanity check: the receiver must be under control of the EVC. otherwise, we allowed to disable this vault as
        // the controller for an account with debt
        if (!isControllerEnabled(receiver, address(this))) {
            revert ControllerDisabled();
        }

        createVaultSnapshot();

        require(assets != 0, "ZERO_ASSETS");

        asset.safeTransferFrom(msgSender, address(this), assets);

        _totalAssets += assets;

        _decreaseOwed(receiver, assets);

        emit Repay(msgSender, receiver, assets);

        requireAccountAndVaultStatusCheck(address(0));
    }

The final functionality we may want to implement for our lending pool vault is pullDebt. This will allow a caller to rebalance the debt from a given account onto their own account. No funds will actually be transferred in this process, the accounting of the debt will simply be moved from one account to another. This is still equivalent to the caller creating a borrow, so we must authenticate the msgSender with _msgSenderForBorrow in the same way we did in the borrow function. After creating a snapshot of the vault and checking the arguments are valid, we can update the state of both accounts; decreasing the debt of the from parameter and increasing the debt of the caller.

We finally require a vault check and an account status check on the function caller (msgSender)

    /// @notice Pulls debt from an account.
    /// @dev This function decreases the debt of one account and increases the debt of another.
    /// @dev Despite the lack of asset transfers, this function emits Repay and Borrow events.
    /// @param from The account to pull the debt from.
    /// @param assets The amount of debt to pull.
    /// @return A boolean indicating whether the operation was successful.
    function pullDebt(address from, uint256 assets) external callThroughEVC nonReentrant returns (bool) {
        address msgSender = _msgSenderForBorrow();

        // sanity check: the account from which the debt is pulled must be under control of the EVC.
        // _msgSenderForBorrow() checks that `msgSender` is controlled by this vault
        if (!isControllerEnabled(from, address(this))) {
            revert ControllerDisabled();
        }

        createVaultSnapshot();

        require(assets != 0, "ZERO_AMOUNT");
        require(msgSender != from, "SELF_DEBT_PULL");

        _decreaseOwed(from, assets);
        _increaseOwed(msgSender, assets);

        emit Repay(msgSender, from, assets);
        emit Borrow(msgSender, msgSender, assets);

        requireAccountAndVaultStatusCheck(msgSender);

        return true;
    }

With that we have implemented all of the initial functionality to create a borrowable vault in our lending market.

A Modular Financial Engineering Platform

An EVC contract is deployed to act as the mediator for our modular financial system. Acting as the authentication mechanism, the EVC mediates interactions between users and the various vaults in our system. The EVC is implemented as a robustly featured multi-call contract, authenticating user operations and ensuring the resulting state of these operations conform to the constraints defined by our vaults.

Composable nodes in the EVC framework are implemented as EVCClient vaults extending the ERC4626 standard with a set of utilities required to allow the EVC to act as an authentication mechanism for operation between vaults in on our platform. These client vaults, are extended further to define the bespoke financial logic pertaining to a specific assets on the platform and allowing for a highly composable set of custom financial transaction to be implemented without fragmenting liquidity or siloing capital within a monolithic DeFi protocol.

These vaults are meant to act as an entry point to a modular financial system, wrapping user assets in a highly flexible financial primitive which can be used to create complex agreements between vaults on the platform or extended, in an open and permission-less way, by other platforms and developers.

Basics

The most basic EVC setup involves two initial vaults; a deposit only vault specifically for accepting a collateral asset and a borrowable vault which accepts deposits for an asset meant to be lent out against the collateral asset. These vaults, along with the EVC, create the basis for a simple lending market.

This example illustrates the simplicity of the EVC's design, as a simple lending market can be implemented utilizing two vaults. Borrowers would deposit their collateral into the deposit vault and liquidity providers can deposit into the borrowable vault, while the EVC mediates interactions between these two vaults ensuring that they conform to the rules of our lending market.

Walkthrough

In this guide we will be walking through reimplementing the VaultSimple contract from the EVC Playground repository. The full code can be found in the EVC playground repository. Further reading on the design and concepts around the EVC can be found in the whitepaper

While the deposit only vault wraps an asset to be utilized as collateral by the EVC infrastructure, the borrowable vault can be extended to implement the specific terms of the lending market's loans. Including the interest rate, price oracle, collateral ratio requirements and, in the case of multiple collaterals, the allowable collateral assets.

First we will break down the implementation of the simplest borrow-only collateral vault.

EVCClient

All vaults interacting with the EVC must implement an EVCClient interface exposing a set of utilities for authenticating the contract callers in the context of the EVC which includes scheduling status check and implementing the ability to unilaterally liquidate collateral shares when appropriate.

These utilities include a getter for determining which collaterals are enabled for an account as well as getters for determining which controllers(Vaults) are enabled for executing on account. It also exposes functionality for disabling a controller.

The client also implements a set of checks, which vault contracts that inherit the EVCClient can schedule when appropriate to ensure conformity to the requirements of the EVC. Including:

requireAccountStatusCheck requireVaultStatusCheck requireAccountAndVaultStatusCheck forgiveAccountStatusCheck isAccountStatusCheckDeferred isVaultStatusCheckDeferred

These checks are used to ensure the solvency of an account or vault after any action that may result in transfer of funds.

Finally, the client implements a liquidateCollateralShares function, allowing the controller to unilaterally seize shares of collateral in the event of a liquidation.

This is the collateral vault of our lending market, and in order to conform to the requirements of the vault controller must implement a couple of basic functions and checks. These requirements can be inherited from the VaultBase contract which itself is a EVCClient contract. Here we have reentrancy locks, vault and account status checks and snapshots.

    /// @notice Creates a snapshot of the vault state
    function createVaultSnapshot() internal {
        // We delete snapshots on `checkVaultStatus`, which can only happen at the end of the EVC batch. Snapshots are
        // taken before any action is taken on the vault that affects the cault asset records and deleted at the end, so
        // that asset calculations are always based on the state before the current batch of actions.
        if (snapshot.length == 0) {
            snapshot = doCreateVaultSnapshot();
        }
    }

    /// @notice Checks the vault status
    /// @dev Executed as a result of requiring vault status check on the EVC.
    function checkVaultStatus() external onlyEVCWithChecksInProgress returns (bytes4 magicValue) {
        doCheckVaultStatus(snapshot);
        delete snapshot;

        return IVault.checkVaultStatus.selector;
    }

    /// @notice Checks the account status
    /// @dev Executed on a controller as a result of requiring account status check on the EVC.
    function checkAccountStatus(
        address account,
        address[] calldata collaterals
    ) external view onlyEVCWithChecksInProgress returns (bytes4 magicValue) {
        doCheckAccountStatus(account, collaterals);

        return IVault.checkAccountStatus.selector;
    }

Here we see the creatVaultSnapshot implementation which saves the state of the vault so that any action taken on the vault that might effect asset calculation are calculated based on the state of the vault before the functions execution started. Preventing many exploits.

We also see the implementation of checkVaultStatus, this calls the doCheckVaultStatus function and deletes the the current snapshot

Finally, checkAccountStatus calls the doCheckAccountStatus function when the EVC requires a check of the accounts health.

In addition to implementing certain basic functionality required by the vault controller, the VaultBase also defines several functions which must be implemented in our borrowable vault contract to configure the lending market.

    /// @notice Creates a snapshot of the vault state
    /// @dev Must be overridden by child contracts
    function doCreateVaultSnapshot() internal virtual returns (bytes memory snapshot);

    /// @notice Checks the vault status
    /// @dev Must be overridden by child contracts
    function doCheckVaultStatus(bytes memory snapshot) internal virtual;

    /// @notice Checks the account status
    /// @dev Must be overridden by child contracts
    function doCheckAccountStatus(address, address[] calldata) internal view virtual;

    /// @notice Disables a controller for an account
    /// @dev Must be overridden by child contracts. Must call the EVC.disableController() only if it's safe to do so
    /// (i.e. the account has repaid their debt in full)
    function disableController() external virtual;

In order that we may build out our VaultSimple contract, we will be importing and inheriting the VaultBase.sol so that our resulting vault is a compliant EVCClient vault. The code for these abstract base contracts can be found here:

VaultBase.sol EVCClient.sol

Implementing VaultSimple.sol: A Deposit Only, Collateral Vault

Now that we understand the Base Vault and the EVCClient implementation, we can begin building our simple vault by inheriting the BaseVault contract.

// SPDX-License-Identifier: GPL-2.0-or-later

pragma solidity ^0.8.19;

import "solmate/auth/Owned.sol";
import "solmate/tokens/ERC4626.sol";
import "solmate/utils/SafeTransferLib.sol";
import "solmate/utils/FixedPointMathLib.sol";
import "../VaultBase.sol";

/// @title VaultSimple
/// @dev It provides basic functionality for vaults.
/// @notice In this contract, the EVC is authenticated before any action that may affect the state of the vault or an
/// account. This is done to ensure that if it's EVC calling, the account is correctly authorized. Unlike solmate,
/// VaultSimple implementation prevents from share inflation attack by using virtual assets and shares. Look into
/// Open-Zeppelin documentation for more details. This vault implements internal balance tracking. This contract does
/// not take the supply cap into account when calculating max deposit and max mint values.
contract VaultSimple is VaultBase, Owned, ERC4626 {
    using SafeTransferLib for ERC20;
    using FixedPointMathLib for uint256;

    event SupplyCapSet(uint256 newSupplyCap);

    error SnapshotNotTaken();
    error SupplyCapExceeded();

    uint256 internal _totalAssets;
    uint256 public supplyCap;

    constructor(
        address _evc,
        ERC20 _asset,
        string memory _name,
        string memory _symbol
    ) VaultBase(_evc) Owned(msg.sender) ERC4626(_asset, _name, _symbol) {}
}

We also inherit from ERC4626, as our Simple Vault will wrap an ERC4626 standard interface for use in the EVC context.

Now we can implement a Simple, Deposit only vault meant to wrap collateral assets for use by the EVC.

Firstly, our vault must implement the vault snapshot function, in the case of a deposit only vault we simply return the _totalAssets managed by the vault. This snapshot is meant to ensure that any calculation involving the vaults state are based off of the state of the vault before any operations occur, this is important for maintaining consistency in vaults with more complex logic.

    /// @notice Creates a snapshot of the vault.
    /// @dev This function is called before any action that may affect the vault's state.
    /// @return A snapshot of the vault's state.
    function doCreateVaultSnapshot() internal virtual override returns (bytes memory) {
        // make total assets snapshot here and return it:
        return abi.encode(_totalAssets);
    }

Next, we define the doCheckVaultStatus function required by the BaseVault interface. here we ensure the vault snapshot was taken before validating the vault state and implementing the vault specific check required by our application. In the case of our deposit only collateral vault this is simply implementing a check to enforce the supply cap.

    /// @notice Checks the vault's status.
    /// @dev This function is called after any action that may affect the vault's state.
    /// @param oldSnapshot The snapshot of the vault's state before the action.
    function doCheckVaultStatus(bytes memory oldSnapshot) internal virtual override {
        // sanity check in case the snapshot hasn't been taken
        if (oldSnapshot.length == 0) revert SnapshotNotTaken();

        // validate the vault state here:
        uint256 initialSupply = abi.decode(oldSnapshot, (uint256));
        uint256 finalSupply = _convertToAssets(totalSupply, false);

        // the supply cap can be implemented like this:
        if (supplyCap != 0 && finalSupply > supplyCap && finalSupply > initialSupply) {
            revert SupplyCapExceeded();
        }
    }

The next function required by our BaseVault parent contract's interface is the doCheckAccountStatus check. This function is actually not required to implement our deposit only functionality so we can leave it blank. However, typically any transaction that may effect the solvency of a user's account will require this check to be called at the end of any set of operations to ensure that the preceding operation did not result in a state that violates the rules of our lending market (i.e insolvency, bad debt etc)

    /// @notice Checks the status of an account.
    /// @dev This function is called after any action that may affect the account's state.
    function doCheckAccountStatus(address, address[] calldata) internal view virtual override {
        // no need to do anything here because the vault does not allow borrowing
    }

Now we are also required to implement a disableController function to allow an account to disassociate with a vault. However our deposit only vault, since it does not allow borrowing, should not ever be a controller.

    /// @notice Disables the controller.
    /// @dev The controller is only disabled if the account has no debt.
    function disableController() external virtual override nonReentrant {
        // this vault doesn't allow borrowing, so we can't check that the account has no debt.
        // this vault should never be a controller, but user errors can happen
        EVCClient.disableController(_msgSender());
    }

Now that we've implemented the VaultBase interface, we move on to typical view functions required to implement a ERC4626 vault. These getter/view functions return an internal calculation for converting between assets(deposited into the vault) and shares (the wrapped representation of these assets).

    /// @notice Returns the total assets of the vault.
    /// @return The total assets.
    function totalAssets() public view virtual override returns (uint256) {
        return _totalAssets;
    }

    /// @notice Converts assets to shares.
    /// @dev That function is manipulable in its current form as it uses exact values. Considering that other vaults may
    /// rely on it, for a production vault, a manipulation resistant mechanism should be implemented.
    /// @dev Considering that this function may be relied on by controller vaults, it's read-only re-entrancy protected.
    /// @param assets The assets to convert.
    /// @return The converted shares.
    function convertToShares(uint256 assets) public view virtual override nonReentrantRO returns (uint256) {
        return _convertToShares(assets, false);
    }

    /// @notice Converts shares to assets.
    /// @dev That function is manipulable in its current form as it uses exact values. Considering that other vaults may
    /// rely on it, for a production vault, a manipulation resistant mechanism should be implemented.
    /// @dev Considering that this function may be relied on by controller vaults, it's read-only re-entrancy protected.
    /// @param shares The shares to convert.
    /// @return The converted assets.
    function convertToAssets(uint256 shares) public view virtual override nonReentrantRO returns (uint256) {
        return _convertToAssets(shares, false);
    }

    /// @notice Simulates the effects of depositing a certain amount of assets at the current block.
    /// @param assets The amount of assets to simulate depositing.
    /// @return The amount of shares that would be minted.
    function previewDeposit(uint256 assets) public view virtual override returns (uint256) {
        return _convertToShares(assets, false);
    }

    /// @notice Simulates the effects of minting a certain amount of shares at the current block.
    /// @param shares The amount of shares to simulate minting.
    /// @return The amount of assets that would be deposited.
    function previewMint(uint256 shares) public view virtual override returns (uint256) {
        return _convertToAssets(shares, true);
    }

    /// @notice Simulates the effects of withdrawing a certain amount of assets at the current block.
    /// @param assets The amount of assets to simulate withdrawing.
    /// @return The amount of shares that would be burned.
    function previewWithdraw(uint256 assets) public view virtual override returns (uint256) {
        return _convertToShares(assets, true);
    }

    /// @notice Simulates the effects of redeeming a certain amount of shares at the current block.
    /// @param shares The amount of shares to simulate redeeming.
    /// @return The amount of assets that would be redeemed.
    function previewRedeem(uint256 shares) public view virtual override returns (uint256) {
        return _convertToAssets(shares, false);
    }

These views need to further call the conversion calculation of shares to assets and assets to shares as required by ERC4262:

    function _convertToShares(uint256 assets, bool roundUp) internal view virtual returns (uint256) {
        return roundUp
            ? assets.mulDivUp(totalSupply + 1, _totalAssets + 1)
            : assets.mulDivDown(totalSupply + 1, _totalAssets + 1);
    }

    function _convertToAssets(uint256 shares, bool roundUp) internal view virtual returns (uint256) {
        return roundUp
            ? shares.mulDivUp(_totalAssets + 1, totalSupply + 1)
            : shares.mulDivDown(_totalAssets + 1, totalSupply + 1);
    }

Now we need an approval method in order for our vaults shares to conform to the ERC20 standard. We override this function to set msgSender to the result of _msgSender() a function exposed by the EVCUtil contract and inherited from the EVCClient base contract. This allows this function to be called and authenticated via the EVC on behalf of a given account if this call is being made by the EVC, which is not required as it does not implement the callThroughEVC modifier:

    /// @notice Approves a spender to spend a certain amount.
    /// @param spender The spender to approve.
    /// @param amount The amount to approve.
    /// @return A boolean indicating whether the approval was successful.
    function approve(address spender, uint256 amount) public virtual override returns (bool) {
        address msgSender = _msgSender();

        allowance[msgSender][spender] = amount;

        emit Approval(msgSender, spender, amount);

        return true;
    }

In the same vein, our ERC20 compliant shares of this vault will require a transfer mechanism. However, since this vault must be used as a deposit vault for collateral we need to implement a vault snapshot as well as an account and vault status check to ensure that both the user's account and the vault remain solvent and consistent after each transfer.

To do this we simply call the requireAccountAndVaultStatusCheck defined on the EVCClient contract we have inherited. This function further calls the EVC to schedule these checks.

Note that, again, we have set the msgSender to the _msgSender() in the context of the EVC. So even thought the EVC is the canonical caller of this operation, the logic is operating on the account authenticated in the EVC's onBehalfOf context. Since this function's operation always results in the transfer of funds, the callThroughEVC modifier is implemented requiring that the this call is delegated via the evc ensuring the scheduled account and vault checks are triggered at the end of its operations.

    /// @notice Transfers a certain amount of shares to a recipient.
    /// @param to The recipient of the transfer.
    /// @param amount The amount shares to transfer.
    /// @return A boolean indicating whether the transfer was successful.
    function transfer(address to, uint256 amount) public virtual override callThroughEVC nonReentrant returns (bool) {
        address msgSender = _msgSender();

        createVaultSnapshot();

        balanceOf[msgSender] -= amount;

        // Cannot overflow because the sum of all user
        // balances can't exceed the max uint256 value.
        unchecked {
            balanceOf[to] += amount;
        }

        emit Transfer(msgSender, to, amount);

        // despite the fact that the vault status check might not be needed for shares transfer with current logic, it's
        // added here so that if anyone changes the snapshot/vault status check mechanisms in the inheriting contracts,
        // they will not forget to add the vault status check here
        requireAccountAndVaultStatusCheck(msgSender);

        return true;
    }

Similarly to our transfer, our mint function also needs to check the consistency of our vault. Which, if you recall, simply enforces our supply cap.

    /// @notice Mints a certain amount of shares for a receiver.
    /// @param shares The shares to mint.
    /// @param receiver The receiver of the mint.
    /// @return assets The assets equivalent to the minted shares.
    function mint(
        uint256 shares,
        address receiver
    ) public virtual override callThroughEVC nonReentrant returns (uint256 assets) {
        address msgSender = _msgSender();

        createVaultSnapshot();

        assets = _convertToAssets(shares, true); // No need to check for rounding error, previewMint rounds up.

        // Need to transfer before minting or ERC777s could reenter.
        asset.safeTransferFrom(msgSender, address(this), assets);

        _totalAssets += assets;

        _mint(receiver, shares);

        emit Deposit(msgSender, receiver, assets, shares);

        requireVaultStatusCheck();
    }

Similar to the transfer function our withdraw function will need to check the Account and vault status to ensure the solvency of accounts, I.E make sure users with open debts don't withdraw more collateral than the minimum amount required to sustain their loan's margin requirements.

    /// @notice Withdraws a certain amount of assets for a receiver.
    /// @param assets The assets to withdraw.
    /// @param receiver The receiver of the withdrawal.
    /// @param owner The owner of the assets.
    /// @return shares The shares equivalent to the withdrawn assets.
    function withdraw(
        uint256 assets,
        address receiver,
        address owner
    ) public virtual override callThroughEVC nonReentrant returns (uint256 shares) {
        address msgSender = _msgSender();

        createVaultSnapshot();

        shares = _convertToShares(assets, true); // No need to check for rounding error, previewWithdraw rounds up.

        if (msgSender != owner) {
            uint256 allowed = allowance[owner][msgSender]; // Saves gas for limited approvals.

            if (allowed != type(uint256).max) {
                allowance[owner][msgSender] = allowed - shares;
            }
        }

        _burn(owner, shares);

        emit Withdraw(msgSender, receiver, owner, assets, shares);

        asset.safeTransfer(receiver, assets);

        _totalAssets -= assets;

        requireAccountAndVaultStatusCheck(owner);
    }

Redeem, an ERC4626 compliant function allows a user to get the amount of assets out of the vault in return for a given number of shares. This function, as you can probably imagine, also requires checks on the account and vault to ensure solvency.

    /// @notice Redeems a certain amount of shares for a receiver.
    /// @param shares The shares to redeem.
    /// @param receiver The receiver of the redemption.
    /// @param owner The owner of the shares.
    /// @return assets The assets equivalent to the redeemed shares.
    function redeem(
        uint256 shares,
        address receiver,
        address owner
    ) public virtual override callThroughEVC nonReentrant returns (uint256 assets) {
        address msgSender = _msgSender();

        createVaultSnapshot();

        if (msgSender != owner) {
            uint256 allowed = allowance[owner][msgSender]; // Saves gas for limited approvals.

            if (allowed != type(uint256).max) {
                allowance[owner][msgSender] = allowed - shares;
            }
        }

        // Check for rounding error since we round down in previewRedeem.
        require((assets = _convertToAssets(shares, false)) != 0, "ZERO_ASSETS");

        _burn(owner, shares);

        emit Withdraw(msgSender, receiver, owner, assets, shares);

        asset.safeTransfer(receiver, assets);

        _totalAssets -= assets;

        requireAccountAndVaultStatusCheck(owner);
    }

With that, we have implemented an EVC compliant ERC4626 vault for use as a deposit only collateral vault in our lending market.

Next we will need to implement a Borrowable vault. Our Borrowable Vault will extend our SimpleVault with the necessary functionality to allow the creation of loans in our market.

Here's the full code for the SimpleVault deposit only collateral vault.

// SPDX-License-Identifier: GPL-2.0-or-later

pragma solidity ^0.8.19;

import "solmate/auth/Owned.sol";
import "solmate/tokens/ERC4626.sol";
import "solmate/utils/SafeTransferLib.sol";
import "solmate/utils/FixedPointMathLib.sol";
import "../VaultBase.sol";

/// @title VaultSimple
/// @dev It provides basic functionality for vaults.
/// @notice In this contract, the EVC is authenticated before any action that may affect the state of the vault or an
/// account. This is done to ensure that if it's EVC calling, the account is correctly authorized. Unlike solmate,
/// VaultSimple implementation prevents from share inflation attack by using virtual assets and shares. Look into
/// Open-Zeppelin documentation for more details. This vault implements internal balance tracking. This contract does
/// not take the supply cap into account when calculating max deposit and max mint values.
contract VaultSimple is VaultBase, Owned, ERC4626 {
    using SafeTransferLib for ERC20;
    using FixedPointMathLib for uint256;

    event SupplyCapSet(uint256 newSupplyCap);

    error SnapshotNotTaken();
    error SupplyCapExceeded();

    uint256 internal _totalAssets;
    uint256 public supplyCap;

    constructor(
        address _evc,
        ERC20 _asset,
        string memory _name,
        string memory _symbol
    ) VaultBase(_evc) Owned(msg.sender) ERC4626(_asset, _name, _symbol) {}

    /// @notice Sets the supply cap of the vault.
    /// @param newSupplyCap The new supply cap.
    function setSupplyCap(uint256 newSupplyCap) external onlyOwner {
        supplyCap = newSupplyCap;
        emit SupplyCapSet(newSupplyCap);
    }

    /// @notice Creates a snapshot of the vault.
    /// @dev This function is called before any action that may affect the vault's state.
    /// @return A snapshot of the vault's state.
    function doCreateVaultSnapshot() internal virtual override returns (bytes memory) {
        // make total assets snapshot here and return it:
        return abi.encode(_totalAssets);
    }

    /// @notice Checks the vault's status.
    /// @dev This function is called after any action that may affect the vault's state.
    /// @param oldSnapshot The snapshot of the vault's state before the action.
    function doCheckVaultStatus(bytes memory oldSnapshot) internal virtual override {
        // sanity check in case the snapshot hasn't been taken
        if (oldSnapshot.length == 0) revert SnapshotNotTaken();

        // validate the vault state here:
        uint256 initialSupply = abi.decode(oldSnapshot, (uint256));
        uint256 finalSupply = _convertToAssets(totalSupply, false);

        // the supply cap can be implemented like this:
        if (supplyCap != 0 && finalSupply > supplyCap && finalSupply > initialSupply) {
            revert SupplyCapExceeded();
        }
    }

    /// @notice Checks the status of an account.
    /// @dev This function is called after any action that may affect the account's state.
    function doCheckAccountStatus(address, address[] calldata) internal view virtual override {
        // no need to do anything here because the vault does not allow borrowing
    }

    /// @notice Disables the controller.
    /// @dev The controller is only disabled if the account has no debt.
    function disableController() external virtual override nonReentrant {
        // this vault doesn't allow borrowing, so we can't check that the account has no debt.
        // this vault should never be a controller, but user errors can happen
        EVCClient.disableController(_msgSender());
    }

    /// @notice Returns the total assets of the vault.
    /// @return The total assets.
    function totalAssets() public view virtual override returns (uint256) {
        return _totalAssets;
    }

    /// @notice Converts assets to shares.
    /// @dev That function is manipulable in its current form as it uses exact values. Considering that other vaults may
    /// rely on it, for a production vault, a manipulation resistant mechanism should be implemented.
    /// @dev Considering that this function may be relied on by controller vaults, it's read-only re-entrancy protected.
    /// @param assets The assets to convert.
    /// @return The converted shares.
    function convertToShares(uint256 assets) public view virtual override nonReentrantRO returns (uint256) {
        return _convertToShares(assets, false);
    }

    /// @notice Converts shares to assets.
    /// @dev That function is manipulable in its current form as it uses exact values. Considering that other vaults may
    /// rely on it, for a production vault, a manipulation resistant mechanism should be implemented.
    /// @dev Considering that this function may be relied on by controller vaults, it's read-only re-entrancy protected.
    /// @param shares The shares to convert.
    /// @return The converted assets.
    function convertToAssets(uint256 shares) public view virtual override nonReentrantRO returns (uint256) {
        return _convertToAssets(shares, false);
    }

    /// @notice Simulates the effects of depositing a certain amount of assets at the current block.
    /// @param assets The amount of assets to simulate depositing.
    /// @return The amount of shares that would be minted.
    function previewDeposit(uint256 assets) public view virtual override returns (uint256) {
        return _convertToShares(assets, false);
    }

    /// @notice Simulates the effects of minting a certain amount of shares at the current block.
    /// @param shares The amount of shares to simulate minting.
    /// @return The amount of assets that would be deposited.
    function previewMint(uint256 shares) public view virtual override returns (uint256) {
        return _convertToAssets(shares, true);
    }

    /// @notice Simulates the effects of withdrawing a certain amount of assets at the current block.
    /// @param assets The amount of assets to simulate withdrawing.
    /// @return The amount of shares that would be burned.
    function previewWithdraw(uint256 assets) public view virtual override returns (uint256) {
        return _convertToShares(assets, true);
    }

    /// @notice Simulates the effects of redeeming a certain amount of shares at the current block.
    /// @param shares The amount of shares to simulate redeeming.
    /// @return The amount of assets that would be redeemed.
    function previewRedeem(uint256 shares) public view virtual override returns (uint256) {
        return _convertToAssets(shares, false);
    }

    /// @notice Approves a spender to spend a certain amount.
    /// @param spender The spender to approve.
    /// @param amount The amount to approve.
    /// @return A boolean indicating whether the approval was successful.
    function approve(address spender, uint256 amount) public virtual override returns (bool) {
        address msgSender = _msgSender();

        allowance[msgSender][spender] = amount;

        emit Approval(msgSender, spender, amount);

        return true;
    }

    /// @notice Transfers a certain amount of shares to a recipient.
    /// @param to The recipient of the transfer.
    /// @param amount The amount shares to transfer.
    /// @return A boolean indicating whether the transfer was successful.
    function transfer(address to, uint256 amount) public virtual override callThroughEVC nonReentrant returns (bool) {
        address msgSender = _msgSender();

        createVaultSnapshot();

        balanceOf[msgSender] -= amount;

        // Cannot overflow because the sum of all user
        // balances can't exceed the max uint256 value.
        unchecked {
            balanceOf[to] += amount;
        }

        emit Transfer(msgSender, to, amount);

        // despite the fact that the vault status check might not be needed for shares transfer with current logic, it's
        // added here so that if anyone changes the snapshot/vault status check mechanisms in the inheriting contracts,
        // they will not forget to add the vault status check here
        requireAccountAndVaultStatusCheck(msgSender);

        return true;
    }

    /// @notice Transfers a certain amount of shares from a sender to a recipient.
    /// @param from The sender of the transfer.
    /// @param to The recipient of the transfer.
    /// @param amount The amount of shares to transfer.
    /// @return A boolean indicating whether the transfer was successful.
    function transferFrom(
        address from,
        address to,
        uint256 amount
    ) public virtual override callThroughEVC nonReentrant returns (bool) {
        address msgSender = _msgSender();

        createVaultSnapshot();

        uint256 allowed = allowance[from][msgSender]; // Saves gas for limited approvals.

        if (allowed != type(uint256).max) {
            allowance[from][msgSender] = allowed - amount;
        }

        balanceOf[from] -= amount;

        // Cannot overflow because the sum of all user
        // balances can't exceed the max uint256 value.
        unchecked {
            balanceOf[to] += amount;
        }

        emit Transfer(from, to, amount);

        // despite the fact that the vault status check might not be needed for shares transfer with current logic, it's
        // added here so that if anyone changes the snapshot/vault status check mechanisms in the inheriting contracts,
        // they will not forget to add the vault status check here
        requireAccountAndVaultStatusCheck(from);

        return true;
    }

    /// @notice Deposits a certain amount of assets for a receiver.
    /// @param assets The assets to deposit.
    /// @param receiver The receiver of the deposit.
    /// @return shares The shares equivalent to the deposited assets.
    function deposit(
        uint256 assets,
        address receiver
    ) public virtual override callThroughEVC nonReentrant returns (uint256 shares) {
        address msgSender = _msgSender();

        createVaultSnapshot();

        // Check for rounding error since we round down in previewDeposit.
        require((shares = _convertToShares(assets, false)) != 0, "ZERO_SHARES");

        // Need to transfer before minting or ERC777s could reenter.
        asset.safeTransferFrom(msgSender, address(this), assets);

        _totalAssets += assets;

        _mint(receiver, shares);

        emit Deposit(msgSender, receiver, assets, shares);

        requireVaultStatusCheck();
    }

    /// @notice Mints a certain amount of shares for a receiver.
    /// @param shares The shares to mint.
    /// @param receiver The receiver of the mint.
    /// @return assets The assets equivalent to the minted shares.
    function mint(
        uint256 shares,
        address receiver
    ) public virtual override callThroughEVC nonReentrant returns (uint256 assets) {
        address msgSender = _msgSender();

        createVaultSnapshot();

        assets = _convertToAssets(shares, true); // No need to check for rounding error, previewMint rounds up.

        // Need to transfer before minting or ERC777s could reenter.
        asset.safeTransferFrom(msgSender, address(this), assets);

        _totalAssets += assets;

        _mint(receiver, shares);

        emit Deposit(msgSender, receiver, assets, shares);

        requireVaultStatusCheck();
    }

    /// @notice Withdraws a certain amount of assets for a receiver.
    /// @param assets The assets to withdraw.
    /// @param receiver The receiver of the withdrawal.
    /// @param owner The owner of the assets.
    /// @return shares The shares equivalent to the withdrawn assets.
    function withdraw(
        uint256 assets,
        address receiver,
        address owner
    ) public virtual override callThroughEVC nonReentrant returns (uint256 shares) {
        address msgSender = _msgSender();

        createVaultSnapshot();

        shares = _convertToShares(assets, true); // No need to check for rounding error, previewWithdraw rounds up.

        if (msgSender != owner) {
            uint256 allowed = allowance[owner][msgSender]; // Saves gas for limited approvals.

            if (allowed != type(uint256).max) {
                allowance[owner][msgSender] = allowed - shares;
            }
        }

        _burn(owner, shares);

        emit Withdraw(msgSender, receiver, owner, assets, shares);

        asset.safeTransfer(receiver, assets);

        _totalAssets -= assets;

        requireAccountAndVaultStatusCheck(owner);
    }

    /// @notice Redeems a certain amount of shares for a receiver.
    /// @param shares The shares to redeem.
    /// @param receiver The receiver of the redemption.
    /// @param owner The owner of the shares.
    /// @return assets The assets equivalent to the redeemed shares.
    function redeem(
        uint256 shares,
        address receiver,
        address owner
    ) public virtual override callThroughEVC nonReentrant returns (uint256 assets) {
        address msgSender = _msgSender();

        createVaultSnapshot();

        if (msgSender != owner) {
            uint256 allowed = allowance[owner][msgSender]; // Saves gas for limited approvals.

            if (allowed != type(uint256).max) {
                allowance[owner][msgSender] = allowed - shares;
            }
        }

        // Check for rounding error since we round down in previewRedeem.
        require((assets = _convertToAssets(shares, false)) != 0, "ZERO_ASSETS");

        _burn(owner, shares);

        emit Withdraw(msgSender, receiver, owner, assets, shares);

        asset.safeTransfer(receiver, assets);

        _totalAssets -= assets;

        requireAccountAndVaultStatusCheck(owner);
    }

    function _convertToShares(uint256 assets, bool roundUp) internal view virtual returns (uint256) {
        return roundUp
            ? assets.mulDivUp(totalSupply + 1, _totalAssets + 1)
            : assets.mulDivDown(totalSupply + 1, _totalAssets + 1);
    }

    function _convertToAssets(uint256 shares, bool roundUp) internal view virtual returns (uint256) {
        return roundUp
            ? shares.mulDivUp(_totalAssets + 1, totalSupply + 1)
            : shares.mulDivDown(_totalAssets + 1, totalSupply + 1);
    }
}

Building off of our last tutorial, Creating a FlashLoan Vault we will now be able to learn how to develop and deploy Upgradeable contracts from foundry using the openzeppelin-upgrades library.

In our last version we built a Flashloan vault with a fixed fee for loans of any size. However, what happens when we realize that this pricing model makes little sense and decide instead to charge a percentage of the loan size as the fee?

With our previous version we would be forced to deploy an entirely new lending protocol and instruct all of our users, both depositors and borrowers to target a new contract and migrate all of their funds. This is particularly problematic given that our borrowers have developed and deployed specially built IERC3156FlashBorrower contracts that are designed to target our lending facility. This puts a major overhead on our users and customers for such a trivial change.

The solution to this issue is to deploy our flash lending protocol as an upgradeable contract. This way we can make changes to the protocol without having to redeploy the entire contract and migrate all of our users. All previous users can continue to target the same address but they will be interacting with our new V2 logic.

In this post we will show how easily we can reimplement our initial FlashLoan vault design as an upgradeable contract and then make a change to the fee structure and, again easily, deploy the version 2 to our users without the need for a migration or downtime. If you would like to follow along please see the previous post for the initial implementation of the FlashLoanVault.

Installation

The first thing we will need to do is install the necessary tools. One being the openzeppelin-foundry-upgrades library to facilitate our management of the upgradeable contracts via foundry. The second being the openzeppelin-contracts-upgradeable library which contains the upgradeable versions of the OpenZeppelin standard contracts we will be inheriting in our smart contract.

forge install OpenZeppelin/openzeppelin-foundry-upgrades --no-commit
forge install OpenZeppelin/openzeppelin-contracts-upgradeable@v5.0.1 --no-commit

Once we have these installed we can add the following to our remapping configurations in foundry.toml. We will also need to add the extra_output configuration to include the storageLayout output. These configs will help us manage the build artifacts necessary for our upgradeable deployment.

foundry.toml

build_info = true
extra_output = ["storageLayout"]
remappings = [
    '@openzeppelin/contracts/=lib/openzeppelin-contracts-upgradeable/lib/openzeppelin-contracts/contracts/',
    '@openzeppelin/contracts-upgradeable/=lib/openzeppelin-contracts-upgradeable/contracts/',
    '@solady/contracts/=lib/solady/src/',
]

(Re)Implementation

Now our reimplementation of the FlashLoan vault will only require some minor changes. Starting with the imports, we will need to import the upgradeable versions of the OpenZeppelin contracts we will be inheriting. For this example, we only need to import the ERC4626Upgradeable contract to replace our previous ERC4626 import. Then, we can add imports for the UUPSUpgradeable and Ownable2StepUpgradeable contracts which will allow us to manage the upgradeability of our contract as well as require special permissions from the owner to perform the upgrade.

// FlashLoanVault.sol
import { UUPSUpgradeable } from "@openzeppelin/contracts-upgradeable/proxy/utils/UUPSUpgradeable.sol";
import { ERC4626Upgradeable } from "@openzeppelin/contracts-upgradeable/token/ERC20/extensions/ERC4626Upgradeable.sol";
import { Ownable2StepUpgradeable } from "@openzeppelin/contracts-upgradeable/access/Ownable2StepUpgradeable.sol";

Once we have the upgrades imported, we can change the inheritance structure of our contract to match it.

contract FlashLoanVault is ERC4626Upgradeable, IERC3156FlashLender, UUPSUpgradeable, Ownable2StepUpgradeable {}

Now, one thing in particular to note about upgradeable contracts is that they do not have a constructor function, instead we will use an initialize function to set the initial state of our contract as well as it's inherited contracts.

    // constructor(address _depositToken) ERC4626(IERC20(_depositToken)) ERC20("Shares Vault", "SV") {}
    function initialize(
        address _depositToken
    ) external initializer {
        __Ownable2Step_init();
        __Ownable_init(msg.sender);
        __ERC4626_init(IERC20(_depositToken));
        __ERC20_init("Shares Vault", "SV");
    }

After we delete the constructor, we can implement our intialize function to set the initial state of our base contracts. Note the initializer modifier which is used to ensure that the initialize function is only called once.

The final change we need to make to our implementation is adding an _authorizeUpgrade function which will be used to ensure that only the owner of the contract can perform the upgrade. In order that we may achieve this, we simply add the onlyOwner modifier to the function.

    function _authorizeUpgrade(address) internal override onlyOwner {}

Deploying a UUPSUpgradable Contract in Foundry Tests

Now that we have the upgradeable reimplementation of our FlashLoanVault complete we can move on to testing the upgradeability. The first thing we will need to change in our FlashLoanVault.t.sol test file is the deployment setup of our contract.

import {Upgrades} from "openzeppelin-foundry-upgrades/Upgrades.sol";

We import the openzeppelin-foundry-upgrades/Upgrades.sol library which will assist us in deploying our new contracts.

After that we modify our FlashLoan Vault deployment in the setup function to use the deployUUPSProxy helper. Once our proxy is deployed we will declare our vault variable used in testing to be an instance of FlashLoanVault at the proxy address.

        proxy = Upgrades.deployUUPSProxy("FlashLoanVault.sol",
            abi.encodeCall(FlashLoanVault.initialize, (address(usdc)))
        );
        vault = FlashLoanVault(proxy);
        //vault = new FlashLoanVault(address(usdc));

Now, we can run all of our previously written tests and see that they all pass and the expected logic is the same as before.

Note: When we build and run this new implementation we will have to add the --ffi flag to enable the openzeppelin foundry upgrades library to be used in our tests.

forge clean && forge build && forge test -vv --ffi

Making an Upgrade

At this point, we have our upgradeable FlashLoanVault with exactly the same functional logic as before. Including the fixed fee of 0.1 USDC

Now, we can test changing the logic of the fee structure in a V2.

All we need to do to implement the upgrade is make a copy of our FlashLoanVault.sol file and name it FlashLoanVaultV2.sol. After this, we simply change the name of the contract to indicate it's the second version and add a reference tag to the previous implementation so that the openzeppelin upgrades library knows how to manage the upgrade. The reference is simply added as a comment above the contract declaration detailing the contract to be upgraded.

FlashLoanVaultV2.sol

/// @custom:oz-upgrades-from FlashLoanVault
contract FlashLoanVaultV2 is ERC4626Upgradeable, IERC3156FlashLender, UUPSUpgradeable, Ownable2StepUpgradeable {}

With the version 2 now setup, we can upgrade the logic of the flashFee function to change the fee structure of our flash loan protocol.

    function flashFee(address token, uint256 amount) public view override returns (uint256) {
        return (amount * 100) / 10000;
    }

Here, we have simply changed the formula to calculate the fee to be 100 basis points or 1% of the loan amount.

Deploying an Upgrade

Now that we have our V2 implementation complete, we can deploy it in our tests to see the procedure and test that the new functionality is working properly.

All we do is add a new test in our FlashLoanVault.t.sol file called test_upgrade_fee().

Deploying the upgrade is actually rather simple utilizing the Upgrades library we simply call the Upgrade.upgradeProxy function and pass the proxy address and the new implementation file "FlashLoanVaultV2.sol" as arguments.

FlashLoanVault.t.sol

    function test_upgrade_fee() public {
        Upgrades.upgradeProxy(
            proxy,
            "FlashLoanVaultV2.sol",
            ""
        );
        vm.startPrank(user1);
        usdc.transfer(address(borrower), 0.01 ether);
        vault.flashLoan(borrower, address(usdc), 1 ether, "");

        // Check we paid the fee 1% of 1 ether = 0.01 ether
        assertEq(usdc.balanceOf(address(vault)), 10.01 ether); 
        assertEq(usdc.balanceOf(address(user1)), 9.99 ether);
        assertEq(usdc.balanceOf(address(borrower)), 0);

        usdc.transfer(address(borrower), 0.1 ether);
        vault.flashLoan(borrower, address(usdc), 10 ether, "");

        // no we paid the fee 1% of 10 ether = 0.1 ether
        assertEq(usdc.balanceOf(address(vault)), 10.11 ether); 
        assertEq(usdc.balanceOf(address(user1)), 9.89 ether);
        assertEq(usdc.balanceOf(address(borrower)), 0);
    }

Once we have the upgrade deployed, we can execute our tests using user1 to make two flashloans of 1 USDC and 10 USDC, each time checking that the fee was paid correctly and in the amount of 1% of the loan size.

Conclusion

In this post we have seen how to reimplement our FlashLoanVault contract as a UUPSupgradeable contract to allow for future changes to the protocol logic without requiring action from our user or any downtime to the protocol.

We have also seen how to utilize openzeppelin's foundry-upgrades library to deploy and test the contracts as well as how to upgrade a live contract to a version 2 implementation.

Full Code

FlashLoanVault.sol

// SPDX-License-Identifier: UNLICENSED
pragma solidity 0.8.20;
import { UUPSUpgradeable } from "@openzeppelin/contracts-upgradeable/proxy/utils/UUPSUpgradeable.sol";
import { ERC4626Upgradeable } from "@openzeppelin/contracts-upgradeable/token/ERC20/extensions/ERC4626Upgradeable.sol";
import { Ownable2StepUpgradeable } from "@openzeppelin/contracts-upgradeable/access/Ownable2StepUpgradeable.sol";
import {IERC3156FlashBorrower} from "@openzeppelin/contracts/interfaces/IERC3156FlashBorrower.sol";
import {IERC3156FlashLender} from "@openzeppelin/contracts/interfaces/IERC3156FlashLender.sol";
import { SafeTransferLib } from "solady/utils/SafeTransferLib.sol";
import { ERC20, IERC20 } from "@openzeppelin/contracts/token/ERC20/ERC20.sol";
error FlashLoanVault__WrongToken();
error FlashLoanVault__RepayFailed();
error FlashLoanVault__MaxLoanExceeded();
contract FlashLoanVault is ERC4626Upgradeable, IERC3156FlashLender, UUPSUpgradeable, Ownable2StepUpgradeable {
    using SafeTransferLib for IERC20;
    // constructor(address _depositToken) ERC4626(IERC20(_depositToken)) ERC20("Shares Vault", "SV") {
    // }
    function initialize(
        address _depositToken
    ) external initializer {
        __Ownable2Step_init();
        __Ownable_init(msg.sender);
        __ERC4626_init(IERC20(_depositToken));
        __ERC20_init("Shares Vault", "SV");
    }
    function maxFlashLoan(address token) public view override returns (uint256) {
        if (token != address(asset())) revert FlashLoanVault__WrongToken();
        return IERC20(token).balanceOf(address(this));
    }

    function flashFee(address token, uint256 amount) public view override returns (uint256) {
        return 0.1 ether;
    }

    function flashLoan(
        IERC3156FlashBorrower receiver,
        address token,
        uint256 amount,
        bytes calldata data
    ) external override returns (bool)
    {
        if (amount > maxFlashLoan(token)) revert FlashLoanVault__MaxLoanExceeded();

        uint256 fee = flashFee(token, amount);
        uint256 totalDebt = amount + fee;
        SafeTransferLib.safeTransfer(address(asset()), address(receiver), amount);
        if (receiver.onFlashLoan(msg.sender, token, amount, fee, data) != keccak256("IERC3156FlashBorrower.onFlashLoan")) revert FlashLoanVault__RepayFailed();

        SafeTransferLib.safeTransferFrom(address(asset()), address(receiver), address(this), totalDebt);
        return true;
    }

    function _authorizeUpgrade(address) internal override onlyOwner {}

}

FlashLoanVaultV2.sol

// SPDX-License-Identifier: UNLICENSED
pragma solidity 0.8.20;
import { UUPSUpgradeable } from "@openzeppelin/contracts-upgradeable/proxy/utils/UUPSUpgradeable.sol";
import { ERC4626Upgradeable } from "@openzeppelin/contracts-upgradeable/token/ERC20/extensions/ERC4626Upgradeable.sol";
import { Ownable2StepUpgradeable } from "@openzeppelin/contracts-upgradeable/access/Ownable2StepUpgradeable.sol";
import {IERC3156FlashBorrower} from "@openzeppelin/contracts/interfaces/IERC3156FlashBorrower.sol";
import {IERC3156FlashLender} from "@openzeppelin/contracts/interfaces/IERC3156FlashLender.sol";
import { SafeTransferLib } from "solady/utils/SafeTransferLib.sol";
import { ERC20, IERC20 } from "@openzeppelin/contracts/token/ERC20/ERC20.sol";
error FlashLoanVault__WrongToken();
error FlashLoanVault__RepayFailed();
error FlashLoanVault__MaxLoanExceeded();
/// @custom:oz-upgrades-from FlashLoanVault
contract FlashLoanVaultV2 is ERC4626Upgradeable, IERC3156FlashLender, UUPSUpgradeable, Ownable2StepUpgradeable {
    using SafeTransferLib for IERC20;
    // constructor(address _depositToken) ERC4626(IERC20(_depositToken)) ERC20("Shares Vault", "SV") {
    // }
    function initialize(
        address _depositToken
    ) external initializer {
        __Ownable2Step_init();
        __Ownable_init(msg.sender);
        __ERC4626_init(IERC20(_depositToken));
        __ERC20_init("Shares Vault", "SV");
    }
    function maxFlashLoan(address token) public view override returns (uint256) {
        if (token != address(asset())) revert FlashLoanVault__WrongToken();
        return IERC20(token).balanceOf(address(this));
    }

    function flashFee(address token, uint256 amount) public view override returns (uint256) {
        return (amount * 100) / 10000;
    }

    function flashLoan(
        IERC3156FlashBorrower receiver,
        address token,
        uint256 amount,
        bytes calldata data
    ) external override returns (bool)
    {
        if (amount > maxFlashLoan(token)) revert FlashLoanVault__MaxLoanExceeded();

        uint256 fee = flashFee(token, amount);
        uint256 totalDebt = amount + fee;
        SafeTransferLib.safeTransfer(address(asset()), address(receiver), amount);
        if (receiver.onFlashLoan(msg.sender, token, amount, fee, data) != keccak256("IERC3156FlashBorrower.onFlashLoan")) revert FlashLoanVault__RepayFailed();

        SafeTransferLib.safeTransferFrom(address(asset()), address(receiver), address(this), totalDebt);
        return true;
    }

    function _authorizeUpgrade(address) internal override {}

}

FlashLoanVault.t.sol

// SPDX-License-Identifier: UNLICENSED
pragma solidity ^0.8.20;

import {Test, console2} from "forge-std/Test.sol";
import { FlashLoanVault } from "../src/FlashLoanVault.sol";
import { FlashLoanVaultV2 } from "../src/FlashLoanVaultV2.sol";
import { ERC20 } from "@openzeppelin/contracts/token/ERC20/ERC20.sol";
import { IERC20 } from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
import { IERC3156FlashBorrower } from "@openzeppelin/contracts/interfaces/IERC3156FlashBorrower.sol";
import {Upgrades} from "openzeppelin-foundry-upgrades/Upgrades.sol";

contract FlashLoanVaultTest is Test {
    address OwnerWallet;
    address user1;
    address user2;
    address user3;
    address proxy;
    FlashLoanVault vault;
    MockFlashLoanReceiver borrower;
    MockUSDC usdc;

    error FlashLoanVault__WrongToken();
    error FlashLoanVault__RepayFailed();
    error FlashLoanVault__MaxLoanExceeded();

    function setUp() public {
        OwnerWallet = address(69);

        user1 = address(420);
        user2 = address(666);
        user3 = address(777);

        usdc = new MockUSDC();
        usdc.mint(user1, 10 ether);
        usdc.mint(user2, 10 ether);
        usdc.mint(OwnerWallet, 10 ether);
        proxy = Upgrades.deployUUPSProxy("FlashLoanVault.sol",
            abi.encodeCall(FlashLoanVault.initialize, (address(usdc)))
        );
        vault = FlashLoanVault(proxy);
        //vault = new FlashLoanVault(address(usdc));

        vm.startPrank(OwnerWallet);
        usdc.approve(address(vault), 10 ether); 
        vault.deposit(7 ether, OwnerWallet);
        vm.stopPrank();

        vm.startPrank(user2);
        usdc.approve(address(vault), 10 ether);
        vault.deposit(3 ether, user2);
        vm.stopPrank();

        vm.startPrank(user1);
        borrower = new MockFlashLoanReceiver(address(vault));
        vm.stopPrank();
    }

    function test_flashLoan() public {
        vm.startPrank(user1);
        usdc.transfer(address(borrower), 0.1 ether);
        vault.flashLoan(borrower, address(usdc), 10, "");
        assertEq(usdc.balanceOf(address(vault)), 10.1 ether);
        assertEq(usdc.balanceOf(address(borrower)), 0);
    }
    function test_ten_flashloans() public {
        vm.startPrank(user1);
        for (uint i = 0; i < 10; i++) {
            usdc.transfer(address(borrower), 0.1 ether);
            vault.flashLoan(borrower, address(usdc), 1, "");
            assertEq(usdc.balanceOf(address(borrower)), 0);
        }
        vm.stopPrank();
        assertEq(usdc.balanceOf(address(vault)), 11 ether);
        assertApproxEqAbs(vault.previewRedeem(7 ether), 7.7 ether, 1);
        assertApproxEqAbs(vault.previewRedeem(3 ether), 3.3 ether, 1);
    }

    function test_revert_loan_repay_failed() public {
        vm.startPrank(user1);
        FlashLoanAttacker attacker = new FlashLoanAttacker();
        usdc.transfer(address(attacker), 0.1 ether);
        vm.expectRevert();
        vault.flashLoan(attacker, address(usdc), 10, "");
    }
    function test_upgrade_fee() public {
        Upgrades.upgradeProxy(
            proxy,
            "FlashLoanVaultV2.sol",
            ""
        );
        vm.startPrank(user1);
        usdc.transfer(address(borrower), 0.01 ether);
        vault.flashLoan(borrower, address(usdc), 1 ether, "");

        // Check we paid the fee 1% of 1 ether = 0.01 ether
        assertEq(usdc.balanceOf(address(vault)), 10.01 ether); 
        assertEq(usdc.balanceOf(address(user1)), 9.99 ether);
        assertEq(usdc.balanceOf(address(borrower)), 0);

        usdc.transfer(address(borrower), 0.1 ether);
        vault.flashLoan(borrower, address(usdc), 10 ether, "");

        // no we paid the fee 1% of 10 ether = 0.1 ether
        assertEq(usdc.balanceOf(address(vault)), 10.11 ether); 
        assertEq(usdc.balanceOf(address(user1)), 9.89 ether);
        assertEq(usdc.balanceOf(address(borrower)), 0);
    }
}

contract MockFlashLoanReceiver is IERC3156FlashBorrower, Test{
    address public lender;

    constructor(address _lender) {
        lender = _lender;
    }
    //
    function onFlashLoan(address initiator, address token, uint256 amount, uint256 fee, bytes calldata data) external override returns (bytes32) {
        // check we have received the loan
        assertEq(IERC20(token).balanceOf(address(this)), amount+fee);
        // Hypothetically do something with the loan
        // approve the repayment 
        IERC20(token).approve(msg.sender, amount + fee);
        return keccak256("IERC3156FlashBorrower.onFlashLoan");
    }
}

contract FlashLoanAttacker is IERC3156FlashBorrower{
    constructor(){}
    function onFlashLoan(address initiator, address token, uint256 amount, uint256 fee, bytes calldata data) external override returns (bytes32) {
        // try to send the loan to ourselves
        IERC20(token).transfer(initiator, amount + fee); 
        return keccak256("IERC3156FlashBorrower.onFlashLoan");
    }
}

contract MockUSDC is ERC20 {
    constructor() ERC20("USDC", "USDC") {
    }
    function mint(address to, uint256 amount) public {
        _mint(to, amount);
    }
}

If you've followed our previous article on implementing Vault with ERC4626, then you are already aware of how easy it is to implement a token vault with a profit sharing distribution mechanism.

Building on this knowledge we will implement a flashloan lending facility into our vault allowing our shareholding depositors to earn additional yield from the flashloan fees.

Implementing flashloan functionality is standardized by ERC3156 which defines the interface for for both the flashloan lender and the flashloan borrower.

We will again use the OpenZeppelin library as scaffold to implement the flashloan functionality.

Getting Started

FlashLoanVault.sol

import { ERC4626 } from "@openzeppelin/contracts/token/ERC20/extensions/ERC4626.sol";
import { ERC20, IERC20 } from "@openzeppelin/contracts/token/ERC20/ERC20.sol";
import {IERC3156FlashBorrower} from "@openzeppelin/contracts/interfaces/IERC3156FlashBorrower.sol";
import {IERC3156FlashLender} from "@openzeppelin/contracts/interfaces/IERC3156FlashLender.sol";
import { SafeTransferLib } from "solady/utils/SafeTransferLib.sol";
error FlashLoanVault__WrongToken();
error FlashLoanVault__RepayFailed();
error FlashLoanVault__MaxLoanExceeded();

The first thing we need to do is import the necessary libraries and interfaces. We'll need the ERC4626 contract in order to implement the tokenized vault shares. Additionally we need to import both IERC3156FlashBorrower and IERC3156FlashLender interfaces from the OpenZeppelin library.

In addition to inheriting, we are also defining some custom errors that we will be using later on.

We'll also be using the SafeTransferLib from solady in order to confidently handle token transfers. To install solady simply run:

forge install vectorized/solady

and in your foundry.toml add a remapping the import with:

remappings = [
   '@solady/contracts/=lib/solady/src/',
]

save your remappings with:

forge remappings > remappings.txt

Once we have that, we can define our FlashLoanVault contract by inheriting the token vault and the flashlender interface in addition to declaring our usage of the SafeTransferLib.

contract FlashLoanVault is ERC4626, IERC3156FlashLender {
    using SafeTransferLib for IERC20;
    constructor(address _depositToken) ERC4626(IERC20(_depositToken)) ERC20("Shares Vault", "SV") {

    }
}

Now, if you've ready our previous article about implementing a vault with ERC4626, you'll notice that we wont be implementing the shareProfits function in this contract. Our flashlending protocol will be able to receive its fees directly and they will automatically and immediately be available to our shareholder.

In order to implement an ERC3156 compliant flash lender we need to implement three simple functions: maxFlashLoan(address token), flashFee(address token, uint256 amount) and flashLoan(IERC3156FlashBorrower receiver, address token, uint256 amount, bytes calldata data).

Firstly, we are only going to allow flashloans of the deposit token that is being pooled in our vault. So we are going to enforce this in the maxFlashLoan function by reverting if the token requested is not the deposit token. Otherwise, the max flashloan allowed will be the total balance of the deposit tokens in the vault.

    function maxFlashLoan(address token) public view override returns (uint256) {
        if (token != address(asset())) revert FlashLoanVault__WrongToken();
        return IERC20(token).balanceOf(address(this));
    }

Next, we need to implement the flashFee function which will return the fee that will be charged for our flashloan. Here, we will be using a flat rate (rather expensive) fee of 0.1 ether, regardless of the amount of the loan.

    function flashFee(address token, uint256 amount) public view override returns (uint256) {
        return 0.1 ether;
    }

Finally we can implement the flashLoan function which will be called when a flashloan is initiated. The caller must pass a compliant IERC3156FlashBorrower as the loan receiver, note: only a smart contract can receive a flashloan since it must contain the appropriate logic to pay the loan back within the same transaction. Next, our borrower must specify the token and amount of the loan, and any additional data that the borrower may need to process the loan in the receiver contract, this data is simply passed along to the receiver contract after the loan is distributed.

    function flashLoan(
        IERC3156FlashBorrower receiver,
        address token,
        uint256 amount,
        bytes calldata data
    ) external override returns (bool)
    {
        if (amount > maxFlashLoan(token)) revert FlashLoanVault__MaxLoanExceeded();

        uint256 fee = flashFee(token, amount);
        uint256 totalDebt = amount + fee;
        SafeTransferLib.safeTransfer(address(asset()), address(receiver), amount);
        if (receiver.onFlashLoan(msg.sender, token, amount, fee, data) != keccak256("IERC3156FlashBorrower.onFlashLoan")) revert FlashLoanVault__RepayFailed();

        SafeTransferLib.safeTransferFrom(address(asset()), address(receiver), address(this), totalDebt);
        return true;
    }

Here we are simply checking that the flashloan amount requested is within the maximum allowed, then we calculate the fee and cache the amount we expect to be paid back, loan + fee, in the totalDebt variable.

After, that we can transfer the loan to the receiver. Once the receiver has the loan our lender contract will call the receivers onFlashLoan() function this is where the receiver can implement any logic desired utilizing the loan funds as long as it does two things: 1. Results in the funds being transferred back to the lender at the end of the transaction and 2. Returns the keccak256 hash of the IERC3156FlashBorrower.onFlashLoan function signature. If the receiver fails to do either of these things the transaction will revert and the loan will not be completed.

Once, we've called the onFlashLoan function we can call safetTransferFrom on the receiver for the amount of the loan + fee, and the flashloan is repaid.

Note: since we've implemented the repayment using safeTransferFrom any receiver contract wishing to borrow from our vault must execute an approve function granting the vault an allowance to transfer the total debt amount by the end of the transaction.

Secondly, we've used the SafeTransferLib here to handle the token transfers, the solady SafeTransferLib is an optimized gas efficient implementation that allows us to be sure the whole transaction will revert if the loan repayment fails.

Testing

Now that we have implemented our flashloan lender vault, we can write some tests to have a look at how it works and how to interact with it.

We'll start with the basic foundry test contract. We'll also import the FlashLoanVault contract and the IERC3156FlashBorrower interface as well as the ERC20 contracts. All of which we will need for testing. Then, we can setup some test users and declare the custom errors we defined in the FlashLoanVault contract, which we will also want to test.

FlashLoanVaultTest.sol

// SPDX-License-Identifier: UNLICENSED
pragma solidity ^0.8.20;

import {Test, console2} from "forge-std/Test.sol";
import { FlashLoanVault } from "../src/FlashLoanVault.sol";
import { ERC20 } from "@openzeppelin/contracts/token/ERC20/ERC20.sol";
import { IERC20 } from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
import { IERC3156FlashBorrower } from "@openzeppelin/contracts/interfaces/IERC3156FlashBorrower.sol";

contract FlashLoanVaultTest is Test {
    address OwnerWallet;
    address user1;
    address user2;
    address user3;
    FlashLoanVault vault;

    error FlashLoanVault__WrongToken();
    error FlashLoanVault__RepayFailed();
    error FlashLoanVault__MaxLoanExceeded();

    function setUp() public {
        OwnerWallet = address(69);

        user1 = address(420);
        user2 = address(666);
        user3 = address(777);
    }

}

Once we have the basics, we notice that we will need some extra setup in order to test all our functionality. The first thing we'll need is a deposit token to use in our vault. So we will create a MockUSDC token similar to what we did in our ERC4626 vault article. At the bottom of our test file we can just define a simple mock token contract.

FlashLoanVaultTest.t.sol

// FlashLoanVaultTest.t.sol
contract MockUSDC is ERC20 {
    constructor() ERC20("USDC", "USDC") {
    }
    function mint(address to, uint256 amount) public {
        _mint(to, amount);
    }
}
`

Additionally, we will need a Mock Borrower to test our flashloans. The ERC3156FlashBorrower interface only needs to implement the onFlashLoan function in order to be compliant. Our mock borrower will take the lender address as a constructor argument to ensure that it knows to where to repay the loan. Note: a this only for testing purposes, a real flash borrower would need to implement further checks to ensure security.

contract MockFlashLoanReceiver is IERC3156FlashBorrower, Test{
    address public lender;

    constructor(address _lender) {
        lender = _lender;
    }
    //
    function onFlashLoan(address initiator, address token, uint256 amount, uint256 fee, bytes calldata data) external override returns (bytes32) {
        // check we have received the loan
        assertEq(IERC20(token).balanceOf(address(this)), amount+fee);
        // Hypothetically do something with the loan here
        // approve the repayment 
        IERC20(token).approve(msg.sender, amount + fee);
        // return this signature so the lender knows we are a compliant borrower
        return keccak256("IERC3156FlashBorrower.onFlashLoan");
    }
}

Normally, this is where the borrower will implement its own custom logic to make use of the loan funds. In our case we will simply want to test that we have received the appropriate funds and have enough to back the loan with an assertion. For this reason, we have inherited the Test base contract from from foundry in order to use the assertEq function. After that we approved the repayment of funds and returned the appropriate selector hash to signal to the lender that we are a compliant borrower.

Now that we have the appropriate mocks, we can return to our test setup function and create our flash loan protocol.

FlashLoanVaultTest.t.sol

// FlashLoanVaultTest.t.sol
    function setUp() public {
        OwnerWallet = address(69);

        user1 = address(420);
        user2 = address(666);
        user3 = address(777);

        usdc = new MockUSDC();
        usdc.mint(user1, 10 ether);
        usdc.mint(user2, 10 ether);
        usdc.mint(OwnerWallet, 10 ether);
        vault = new FlashLoanVault(address(usdc));

        vm.startPrank(OwnerWallet);
        usdc.approve(address(vault), 10 ether); 
        vault.deposit(7 ether, OwnerWallet);
        vm.stopPrank();

        vm.startPrank(user2);
        usdc.approve(address(vault), 10 ether);
        vault.deposit(3 ether, user2);
        vm.stopPrank();

        vm.startPrank(user1);
        borrower = new MockFlashLoanReceiver(address(vault));
        vm.stopPrank();
    }

All we've done here is setup our user wallets with some USDC and then created a vault and deposited some funds into it. We now have a vault with 10 USDC and two users with shares equivalent to 1 USDC each. We have also deployed a borrower contract targeting our vault as the lender.

We are ready to test the flashloan with the test_flashloan() function.

    function test_flashLoan() public {
        vm.startPrank(user1);
        usdc.transfer(address(borrower), 0.1 ether);
        vault.flashLoan(borrower, address(usdc), 10, "");
        assertEq(usdc.balanceOf(address(vault)), 10.1 ether);
        assertEq(usdc.balanceOf(address(borrower)), 0);
    }

In this test, we've had our test user1 transfer 0.1 USDC to the borrower contract to use as the loan fee. Then we executed a flashloan on the fault. Our borrower contract will test that it has received the loan by calling assertEq mid transaction in the onFlashLoan function. After the flashloan call completes, our test checks that the vault balance has increased by 0.1 USDC and maintained its initial balance of 10 USDC as well as checking that the borrower contract is now empty. All of which are indicative of a successful flashloan.

Testing the Shareholder's Profits

Now that we have a basic flashloan working, we can run a function that executes several flashloans thus accumulating profits to the vault and check that the shareholder profits are being distributed correctly.

    function test_ten_flashloans() public {
        vm.startPrank(user1);
        for (uint i = 0; i < 10; i++) {
            usdc.transfer(address(borrower), 0.1 ether);
            vault.flashLoan(borrower, address(usdc), 1, "");
            assertEq(usdc.balanceOf(address(borrower)), 0);
        }
        vm.stopPrank();
        assertEq(usdc.balanceOf(address(vault)), 11 ether);
        assertApproxEqAbs(vault.previewRedeem(7 ether), 7.7 ether, 1);
        assertApproxEqAbs(vault.previewRedeem(3 ether), 3.3 ether, 1);
    }

In this test, we've use a simple loop to do 10 flashloans which should result in 1 USDC of profit to the vault. We then check that the vault has accumulated 11 USDC and that the shareholder profits are being distributed correctly according to their holding. Since, the vault has profited 10% on its 10 USDC of liquidity, the shareholders should be able to redeem 10% more than their initial deposit for each share.

Note here that we are using assertApproxEqAbs to check the shareholder redeem value are within 1 unit of what we expect. This is due to the rounding precision effects of integer division which was discussed in the shareholder vault article.

Testing Errors

Finally, we can test that our custom errors are being thrown when they should be. Namely, when a flashloan is requested for a token that is not the vault deposit token and when a flashloan is requested that exceeds the amount of liquidity available in the vault.

    function test_flashloan_revert_wrong_token() public {
        vm.startPrank(user1);
        vm.expectRevert(abi.encodeWithSelector(FlashLoanVault__WrongToken.selector));
        vault.flashLoan(borrower, address(vault), 10, "");
    }
    function test_revertMaxLoanExceeded() public {
        vm.startPrank(user1);
        vm.expectRevert(abi.encodeWithSelector(FlashLoanVault__MaxLoanExceeded.selector));
        vault.flashLoan(borrower, address(usdc), 100 ether, "");
    }

To implement these checks, we utilize vm.expectRevert and compare the returned error data to the selector of the custom error we declared earlier.

Testing an Attack

Finally, we can test that our flashloan protocol is secure by attempting to attack it. We can do this by creating a malicious borrower contract that does not repay the loan. We will first need to define an attacker contract that attempts to take the loan and transfer it directly to the attacker. at the bottom of our test file we can define the attacker contract.

contract FlashLoanAttacker is IERC3156FlashBorrower{
    constructor(){}
    function onFlashLoan(address initiator, address token, uint256 amount, uint256 fee, bytes calldata data) external override returns (bytes32) {
        // try to send the loan to ourselves
        IERC20(token).transfer(initiator, amount + fee); 
        return keccak256("IERC3156FlashBorrower.onFlashLoan");
    }
}

Finally, in our test we can have the attacker call for a flashloan and expect it to revert.

    function test_revert_loan_repay_failed() public {
        vm.startPrank(user1);
        FlashLoanAttacker attacker = new FlashLoanAttacker();
        usdc.transfer(address(attacker), 0.1 ether);
        vm.expectRevert();
        vault.flashLoan(attacker, address(usdc), 10, "");
    }

In this test, we've used a general vm.expectRevert() since we are expecting the SafeTransferLib to revert when it fails to safeTrasferFrom the attacker contract in the appropriate amount to pay back the loan and fee.

Conclusion

Here we have seen the relative ease with which a flashloan protocol can be implemented utilizing the ERC3156 interface to provide standardized flashloan functionality and the ERC4626 interface to provide a simple profit distributing vault mechanism for depositors to provide pooled capital and receive a yield.

Full Code

FlashLoanVault.sol

import { ERC4626 } from "@openzeppelin/contracts/token/ERC20/extensions/ERC4626.sol";
import {IERC3156FlashBorrower} from "@openzeppelin/contracts/interfaces/IERC3156FlashBorrower.sol";
import {IERC3156FlashLender} from "@openzeppelin/contracts/interfaces/IERC3156FlashLender.sol";
import { SafeTransferLib } from "solady/utils/SafeTransferLib.sol";
import { ERC20, IERC20 } from "@openzeppelin/contracts/token/ERC20/ERC20.sol";
error FlashLoanVault__WrongToken();
error FlashLoanVault__RepayFailed();
error FlashLoanVault__MaxLoanExceeded();
contract FlashLoanVault is ERC4626, IERC3156FlashLender {
    using SafeTransferLib for IERC20;
    constructor(address _depositToken) ERC4626(IERC20(_depositToken)) ERC20("Shares Vault", "SV") {

    }
    function maxFlashLoan(address token) public view override returns (uint256) {
        if (token != address(asset())) revert FlashLoanVault__WrongToken();
        return IERC20(token).balanceOf(address(this));
    }

    function flashFee(address token, uint256 amount) public view override returns (uint256) {
        return 0.1 ether;
    }

    function flashLoan(
        IERC3156FlashBorrower receiver,
        address token,
        uint256 amount,
        bytes calldata data
    ) external override returns (bool)
    {
        if (amount > maxFlashLoan(token)) revert FlashLoanVault__MaxLoanExceeded();

        uint256 fee = flashFee(token, amount);
        uint256 totalDebt = amount + fee;
        SafeTransferLib.safeTransfer(address(asset()), address(receiver), amount);
        if (receiver.onFlashLoan(msg.sender, token, amount, fee, data) != keccak256("IERC3156FlashBorrower.onFlashLoan")) revert FlashLoanVault__RepayFailed();

        SafeTransferLib.safeTransferFrom(address(asset()), address(receiver), address(this), totalDebt);
        return true;
    }


}

FlashLoanVaultTest.t.sol

// SPDX-License-Identifier: UNLICENSED
pragma solidity ^0.8.20;

import {Test, console2} from "forge-std/Test.sol";
import { FlashLoanVault } from "../src/FlashLoanVault.sol";
import { ERC20 } from "@openzeppelin/contracts/token/ERC20/ERC20.sol";
import { IERC20 } from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
import { IERC3156FlashBorrower } from "@openzeppelin/contracts/interfaces/IERC3156FlashBorrower.sol";

contract FlashLoanVaultTest is Test {
    address OwnerWallet;
    address user1;
    address user2;
    address user3;
    FlashLoanVault vault;
    MockFlashLoanReceiver borrower;
    MockUSDC usdc;

    error FlashLoanVault__WrongToken();
    error FlashLoanVault__RepayFailed();
    error FlashLoanVault__MaxLoanExceeded();

    function setUp() public {
        OwnerWallet = address(69);

        user1 = address(420);
        user2 = address(666);
        user3 = address(777);

        usdc = new MockUSDC();
        usdc.mint(user1, 10 ether);
        usdc.mint(user2, 10 ether);
        usdc.mint(OwnerWallet, 10 ether);
        vault = new FlashLoanVault(address(usdc));

        vm.startPrank(OwnerWallet);
        usdc.approve(address(vault), 10 ether); 
        vault.deposit(7 ether, OwnerWallet);
        vm.stopPrank();

        vm.startPrank(user2);
        usdc.approve(address(vault), 10 ether);
        vault.deposit(3 ether, user2);
        vm.stopPrank();

        vm.startPrank(user1);
        borrower = new MockFlashLoanReceiver(address(vault));
        vm.stopPrank();
    }

    function test_flashLoan() public {
        vm.startPrank(user1);
        usdc.transfer(address(borrower), 0.1 ether);
        vault.flashLoan(borrower, address(usdc), 10, "");
        assertEq(usdc.balanceOf(address(vault)), 10.1 ether);
        assertEq(usdc.balanceOf(address(borrower)), 0);
    }
    function test_ten_flashloans() public {
        vm.startPrank(user1);
        for (uint i = 0; i < 10; i++) {
            usdc.transfer(address(borrower), 0.1 ether);
            vault.flashLoan(borrower, address(usdc), 1, "");
            assertEq(usdc.balanceOf(address(borrower)), 0);
        }
        vm.stopPrank();
        assertEq(usdc.balanceOf(address(vault)), 11 ether);
        assertApproxEqAbs(vault.previewRedeem(7 ether), 7.7 ether, 1);
        assertApproxEqAbs(vault.previewRedeem(3 ether), 3.3 ether, 1);
    }

    function test_revert_loan_repay_failed() public {
        vm.startPrank(user1);
        FlashLoanAttacker attacker = new FlashLoanAttacker();
        usdc.transfer(address(attacker), 0.1 ether);
        vm.expectRevert();
        vault.flashLoan(attacker, address(usdc), 10, "");
    }
}

contract MockFlashLoanReceiver is IERC3156FlashBorrower, Test{
    address public lender;

    constructor(address _lender) {
        lender = _lender;
    }
    //
    function onFlashLoan(address initiator, address token, uint256 amount, uint256 fee, bytes calldata data) external override returns (bytes32) {
        // check we have received the loan
        assertEq(IERC20(token).balanceOf(address(this)), amount+fee);
        // Hypothetically do something with the loan
        // approve the repayment 
        IERC20(token).approve(msg.sender, amount + fee);
        return keccak256("IERC3156FlashBorrower.onFlashLoan");
    }
}

contract FlashLoanAttacker is IERC3156FlashBorrower{
    constructor(){}
    function onFlashLoan(address initiator, address token, uint256 amount, uint256 fee, bytes calldata data) external override returns (bytes32) {
        // try to send the loan to ourselves
        IERC20(token).transfer(initiator, amount + fee); 
        return keccak256("IERC3156FlashBorrower.onFlashLoan");
    }
}

contract MockUSDC is ERC20 {
    constructor() ERC20("USDC", "USDC") {
    }
    function mint(address to, uint256 amount) public {
        _mint(to, amount);
    }
}

A common pattern in Defi is to create a vault that holds assets and distributes profits to the vault's token holders. Users will pool their assets in the vault and receive a corresponding token representing their share of the vault's assets. When the assets in the vault grow from share creation, each share's corresponding value remains the same. When the assets in the vault grow from profit accumulation, each share's corresponding value grows proportionally.

Here we will demonstrate the basic implementation of such a vault, utilizing the ERC4626 standard.

ERC4626 is tokenized vault standard which itself extends an ERC20 token. This means that the vault contract includes an ERC20 token to be used as the vault's shares. Further, the vault will have the deployer define an asset token to be used as a deposit asset exchanged for shares in the vault.

Utilizing the openzeppelin library we can implement a simple version of this contract incredibly easily. Everything we need to get started with the vault comes fully functional, completely out of the box.

once we implement a simple vault, we'll explore some of its functionality through testing.

Setting Up the Vault Contract

First, we can start with an empty foundry project, install the openzeppelin library and implement our basic vault through inheritance.

src/SharesVault.sol

import { ERC4626 } from "@openzeppelin/contracts/token/ERC20/extensions/ERC4626.sol";
import { ERC20, IERC20 } from "@openzeppelin/contracts/token/ERC20/ERC20.sol";

contract SharesVault is ERC4626 {
    constructor(address _depositToken) ERC4626(IERC20(_depositToken)) ERC20("Shares Vault", "SV") {

    }
}

That's it! That's all we need to get started, simply import the ERC4626 and ERC20 contracts from the openzeppelin library and inherit them in our contract. Then in the constructor we pass the address of our asset token which will get passed along to the ERC4626 constructor as an ERC20 token. We now have a fully functional and ERC4626 compliant shares vault. Later on in this post we will see how to add some functionality to this implementation specific to our business logic.

Setting Up the Tests

Now we can set up some tests to see how it works. The standard foundry test setup should do fine for now. but we will also need to generate a Mock token to act as our asset token. So, import ERC20 at the top and at the bottom of the test file we will implement a simple token.

test/SharesVault.t.sol

// SPDX-License-Identifier: UNLICENSED
pragma solidity ^0.8.20;

import {Test, console2} from "forge-std/Test.sol";
import { SharesVault } from "../src/SharesVault.sol";
import { ERC20 } from "@openzeppelin/contracts/token/ERC20/ERC20.sol";

contract TestSharesVault is Test {
    function setUp() public {

    }
}

contract MockERC20 is ERC20 {
    constructor (string memory name_, string memory symbol_) ERC20(name_, symbol_) {}

    function mint(address to, uint256 amount) external {
        _mint(to, amount);
    }  
}

Now that we have the basic scaffolding of our test setup we can implement the setup and deployment of our vault. This is a simple setup which only requires us to deploy an instance of the SharesVault contract with our MockERC20 token passed to the constructor as its deposit token. We can then mint some depositToken to our test users. We have named our vault shares here for better readability when making token transactions. remember our SharesVault instance is also our shares token

contract TestSharesVault is Test {
    address OwnerWallet;
    address user1;
    address user2;
    address user3;
    SharesVault shares;
    MockERC20 depositToken; // assets token

    function setUp() public {
        OwnerWallet = address(69);

        user1 = address(420);
        user2 = address(666);
        user3 = address(777);

        vm.prank(OwnerWallet);
        depositToken = new MockERC20("Deposit Token", "DT");
        depositToken.mint(user1, 10 ether);
        depositToken.mint(user2, 10 ether);
        depositToken.mint(OwnerWallet, 10 ether);
        shares = new SharesVault(address(depositToken));
        vm.stopPrank();
    }
}

Testing the Share Creation Mechanism

Once We have the vault deployed we can start utilizing its functions. The ERC4626 standard includes two function which handle the use case of a user depositing assets and receiving shares in return.

The deposit(uint256 assets, address receiver) function which allows the user to define the amount of asset they want to deposit and receive a corresponding amount of shares.

The mint(uint256 shares, address receiver) function which allows the user to define the amount of shares they want to mint and the vault will pull the corresponding amount of assets from the user in exchange for those minted shares.

We can see these functions in action by first implementing an approval from the user to the vault and then calling the deposit or mint function. After that we can check our balance of shares and the balance of the deposit tokens in the vault.

    function test_deposit() public {
        vm.startPrank(user1);
        depositToken.approve(address(shares), 1 ether);
        shares.deposit(1 ether, user1);
        assertEq(shares.balanceOf(user1), 1 ether);
        assertEq(depositToken.balanceOf(address(shares)), 1 ether);
        vm.stopPrank();
    }

    function test_mint() public {
        vm.startPrank(user1);
        depositToken.approve(address(shares), 1 ether);
        shares.mint(1 ether, user1);
        assertEq(shares.balanceOf(user1), 1 ether);
        assertEq(depositToken.balanceOf(address(shares)), 1 ether);
        vm.stopPrank();
    }

We can see that, since our test user1 is the only depositor to the vault, we have been minted a share in a 1:1 ratio with the deposit token.

Testing the Share Redemption Mechanism

Now, we can have a look at the share redemption mechanism included in our ERC4626 contract. The standard includes two functions for exchanging our shares for the underlying assets of the vault.

The withdraw(uint256 assets, address receiver, address owner) function which allows the user to define the amount of assets they want to withdraw and the vault will pull and burn the corresponding amount of shares from the user in exchange for those assets.

The burn(uint256 shares, address receiver, address owner) function which allows the user to define the amount of shares they want to burn and receive a corresponding amount of assets.

Both of these functions require the msg.sender of the transaction to be the owner of the shares being burned but the withdrawn assets can be sent to any receiver the owner defines via the address receiver parameter.

Our tests will look very similar to the share creation tests, expect that we will first run test_mint() so that our tests start off with a user who has some shares and assets in the vault.

    function test_withdraw() public {
        test_mint();
        vm.startPrank(user1);
        shares.withdraw(1 ether, user1, user1);
        assertEq(shares.balanceOf(user1), 0);
        assertEq(depositToken.balanceOf(address(shares)), 0);
        assertEq(depositToken.balanceOf(user1), 10 ether);
        vm.stopPrank();
    }
    function test_redeem() public {
        test_mint();
        vm.startPrank(user1);
        shares.redeem(1 ether, user1, user1);
        assertEq(shares.balanceOf(user1), 0);
        assertEq(depositToken.balanceOf(address(shares)), 0);
        assertEq(depositToken.balanceOf(user1), 10 ether);
        vm.stopPrank();
    }

We can see here that our user is able to use either of these functions to redeem their shares in exchange for the underlying assets of the vault to which they are entitled. Which function they use is simply determined by which parameter they wish to define. Either, the amount of shares to redeem or the amount of assets to withdraw.

Implementing Profit Sharing.

Now that we have seen the usage of a fully compliant vault, we can implement some custom functionality to support our business logic.

In this case, lets say, we want to implement a profit sharing mechanism so that shareholders in the vault can receive a dividend of the profits generated by the vaults capital. We'll say that these profits are occasionally distributed from the vault owner to the shareholders.

Thus, we simply need a function which the owner can call to transfer profits, in the form of the asset token into the vault.

import { ERC4626 } from "@openzeppelin/contracts/token/ERC20/extensions/ERC4626.sol";
import { ERC20, IERC20 } from "@openzeppelin/contracts/token/ERC20/ERC20.sol";
import { SafeERC20 } from "@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol";

contract SharesVault is ERC4626 {
    constructor(address _depositToken) ERC4626(IERC20(_depositToken)) ERC20("Shares Vault", "SV") {

    }

    function shareProfits(uint256 amount) public {
        SafeERC20.safeTransferFrom(IERC20(asset()), msg.sender, address(this), amount);
    }
}

All we've done here is import the SafeERC20 utility from openzeppelin and implemented a shareProfits function which executes a safeTransferFrom of the asset token from the caller to the vault. Note, however, that this is not strictly necessary. As any asset tokens set directly to the contract without going through the share creation mechanism will result in the vaults total assets being increase while the totalSupply of shares remains the same, thus the existing shareholders receive their portion of these profits regardless if this function is executed or not. We implement it here for convenience and to demonstrate the concept.

Now we can test it out. In order to do so, we will need to setup a test state where the vault has some shareholders and assets. We can achieve this by simply adding a utility function to our test file.

    function setup_shareholders() public {
        vm.startPrank(user1);
        depositToken.approve(address(shares), 10 ether);
        shares.deposit(10 ether, user1);
        vm.stopPrank();
        vm.startPrank(user2);
        depositToken.approve(address(shares), 10 ether);
        shares.deposit(10 ether, user2);
        vm.stopPrank();
        assertEq(shares.balanceOf(user1), 10 ether);
        assertEq(shares.balanceOf(user2), 10 ether);
    }

This will give us two shareholders with equal shares in the vault and 20 ether of assets in the vault. Then we can implement a test were the vault receives some profits from the owner.

    function test_profitSharing() public {
        setup_shareholders();
        vm.startPrank(OwnerWallet);
        depositToken.approve(address(shares), 2 ether);
        shares.shareProfits(2 ether);
        vm.stopPrank();
        assertEq(depositToken.balanceOf(address(shares)), 22 ether);
        uint256 user1_value = shares.previewRedeem(10 ether);
        assertEq(user1_value, 11 ether);
    }

After the owner executes shareProfits and transfers in 2 asset tokens, we can use one of the vaults view functions to get an accounting of our shares new value. In this case, we'll use the previewRedeem function which allows us to see the value of our shares if we were to redeem them for the underlying assets and we'll pass it our user1 balance of 10 shares.

Our hypothetical user1 deposited 10 asset tokens in exchange for 10 shares. The pools total assets was 20 with 20 shares outstanding, since we had a second user do the same. Now, the pool has earned a profit of 2 asset tokens so we would expect the value of our shares to have grown to 11 asset tokens. 1 token being half the profits since we hold half of the shares.

However if we run this test with forge test -vv we see that it fails! and produces the following output.

[FAIL. Reason: assertion failed] test_profitSharing() (gas: 195837)
Logs:
  Error: a == b not satisfied [uint]
        Left: 10999999999999999999
       Right: 11000000000000000000

So, what happened? In fact we are only short 1 wei of what we expected.

If we go to the openzeppelin implementation we can have a look at how this happened. It is fundamentally an issue of precision. we called previewRedeem in our test which itself calls _convertToAssets

    /** @dev See {IERC4626-previewRedeem}. */
    function previewRedeem(uint256 shares) public view virtual returns (uint256) {
        return _convertToAssets(shares, Math.Rounding.Floor);
    }

    /**
     * @dev Internal conversion function (from shares to assets) with support for rounding direction.
     */
    function _convertToAssets(uint256 shares, Math.Rounding rounding) internal view virtual returns (uint256) {
        return shares.mulDiv(totalAssets() + 1, totalSupply() + 10 ** _decimalsOffset(), rounding);
    }