ozExecutorFacet

Main execution implementation of the L2 subsystem. It does the final swap from the user's ETH to the Account stablecoin, and updates key system components that maintain the rebasing mechanism of the OZL token, like the Ozel Index.

Github repo here.

System methods

executeFinalTrade

function executeFinalTrade( 
        struct TradeOps calldata swap_, 
        uint accountSlippage_,
        address user_,
        uint lockNum_
) external payable isAuthorized(lockNum_) noReentrancy(3);

When the Account's chosen stablecoin is not a base token (USDT or WBTC), this function makes the final swap from the correspondent base token to the Account's stablecoin.

It uses the try/catch technique where if the Account's slippage is not enough and the original swap fails, it doubles the slippage, divides the swapped amount between two, and tries again two times (since the swapped amount is divided between two).

There are three scenarios that could happen here:

1. The user receives the full amount of funds in the Account's chosen stablecoin. This is the most likely scenario if a decent slippage is chosen and there's enough liquidity in the Curve pool of the swap in comparison to the amount being swapped (aka the amount of ETH sent to the Account).

2. The user receives 50% of funds in the Account's stablecoin and 50% in the base token. This scenario occurs when the first swap fails, the second re-try succeeds, but the third one fails (2nd and 3rd are for the divided -between two- swapped amount after the original swap fails).

3. The user receives 100% of funds in the base token of the Account's stablecoin. This happens when the first and second swap fails, so the third one is never executed.

Parameters:

Struct:

struct TradeOps {
    int128 tokenIn;
    int128 tokenOut;
    address baseToken;
    address token;  
    address pool;
}

Name	Type	Description
tokenIn	int128	Index at Curve pool of the Account's stablecoin's base token
tokenOut	int128	Index at Curve pool of the Account's token
baseToken	address	Base token of the Account's token
token	address	Account's stablecoin
pool	address	Curve pool where token is found

Function:

Name	Type	Description
swap_	struct TradeOps	token configuration for final swap
accountSlippage_	uint256	Account's chosen slippage
user_	address	Owner of the Account
lockNum_	uint256	Index of bit that authorizes the call

modifyPaymentsAndVolumeExternally

function modifyPaymentsAndVolumeExternally(
        address user_, 
        uint newAmount_,
        uint lockNum_
) external isAuthorized(lockNum_) noReentrancy(5);

Function used -from outside the regular flow when an ETH transfer is received- to update the Ozel Index and the main external variables that help in the calculation of an user's OZL balance, such as total volume and an user's payments.

It's currently used when redeeming an OZL balance for the protocol's revenue.

Parameters:

Name	Type	Description
user_	address	Owner calling the redemption
newAmount_	uint256	Amount to reduce in proportion to user_'s OZL redemption
lockNum_	uint256	Index of bit that authorizes the call

transferUserAllocation

function transferUserAllocation( 
        address sender_, 
        address receiver_, 
        uint amount_, 
        uint senderBalance_,
        uint lockNum_
) external isAuthorized(lockNum_) noReentrancy(7);

Function used internally (even though it's marked as external) by the oz20Facet to transfer OZL tokens between users.

Parameters:

Name	Type	Description
sender_	address	Owner of the OZL tokens to send
receiver	address	Recipient of sender_'s transfer
amount_	uint256	OZL tokens to send
senderBalance_	uint256	sender_'s total OZL balance
lockNum_	uint256	Index of bit that authorizes the call

updateExecutorState

function updateExecutorState(
        uint amount_, 
        address user_,
        uint lockNum_
) external payable isAuthorized(lockNum_) noReentrancy(2);

Updates the total volume the protocol has handled so far, and the user's contribution to that volume.

Parameters:

Name	Type	Description
amount_	uint256	Amount of ETH sent to the Account
user_	address	Owner of the Account for the current transaction
lockNum_	uint256	Index of bit that authorizes the call

_updateIndex

function _updateIndex() private;

Updates the Ozel Index, which is in charge, among other variables, of keeping the rebase mechanism of the OZL token pegged to 100 (its total supply).

This is designed having in mind a series of iterations, where each iteration would balance out the index by returning it to its median value.

Each iteration is controlled by a series of invariants and their regulators that keep the index in equilibrium, and in a continuous pattern in regards to the past iteration and the one that follows.

For keeping the equilibrium of the Ozel Index as a whole, there has to be a release mechanism for the energy of each balancing iteration, which could allow -almost- "infinite" iterations. This is the variable regulatorCounter (an unsigned integer that could hold up to 256 bits) which gets updated by 1 on each balancing iteration.

So technically speaking, there can be a maximum of 115792089237316195423570985008687907853269984665640564039457584007913129639935 iterations before the protocol brakes, which is highly unlikely to occur.