Wombex architecture

This page contains detailed information regarding Wombex architecture and smart-contracts

The scheme of Wombex contracts containing pathways of interaction between them is presented below:

This page has several sections:

1. Key Wombat contracts used by Wombex

2. Contracts related to WOM accumulation and storage

3. Contracts working with depositing/withdrawing users' liquidity

4. Contracts related to WMX token

Key Wombat contracts used by Wombex

There are two main Wombat contracts Wombex is interacting with:

MasterWombat.sol is the contract storing all Wombat LP tokens and providing WOM rewards according to boost determined by the size of veWOM position of this address in veWOM.sol.

veWOM.sol is the contract storing all veWOM stakes of Wombat users.

Contracts related to WOM accumulation and storage

Wombex operation is build around accumulating and storing WOM tokens, supplied by users and staked into veWOM forever. There are following contracts participating in veWOM accumulation and using it for voting and boosting purposes:

WomDepositor.sol is a contract used for depositing WOM into Wombex and further staking it into veWOM forever through VoterProxy.sol. As a result of the WOM deposit, users receive wmxWOM liquid staking token minted by CvxCrvToken.sol.

• One wmxWOM is minted for a deposit of 1 WOM

• Since the Wombat contract veWOM.sol has only 10k slots for WOM deposits, WOM is deposited there only once per 24 hrs (when the next deposit occurs and 24hrs passed since the previous deposit tx, WOM->veWOM deposit is added to this transaction)

• Every time there is a check out, if there is a WOM that can be unstaked. If yes, unstake it and stake it one more time for 4 years.

• Allows adding users to a special Whitelist. Addresses from the Whitelist can lock a specific amount of WOM for a specified period and withdraw it when the veWOM lock-up period ends. As a result of such a transaction, there will be no wmxWOM minted. The function is developed especially for the Wombat DAO.

CvxCrvToken.sol - ERC20 token contract with mint() and burn() functions. When a user deposits WOM into WomDepositor.sol, the wmxWOM token is minted as a result.

• wmxWOM is a transferable liquid derivative of staked veWOM

• Only WomDepositor.sol has a right to call mint() in case WOM was deposited

VoterProxy.sol is the contract interacting with veWOM.sol and MasterWombat.sol. This contract is the owner of the Wombex veWOM position in veWOM.sol contract and all Wombat LP tokens deposited into MasterWombat.sol. In the future, VoterProxy.sol will call other Wombat contracts, for example, governance ones.

Contracts working with depositing/withdrawing users' liquidit

This section is devoted to contracts receiving users’ liquidity deposits, boosting yield, and distributing liquidity mining rewards.

Liquidity provider interaction scenarios

The user has three ways to deposit funds to the protocol:

1. [ZAP Simplified Deposit] The user has an asset (for example, stablecoin or stBNB). The user deposits this token to PoolDepositor (ZAP contract), PoolDepositor calls Wombat pool and deposits tokens to the pool, receiving Wombat LP tokens afterward. After that, it calls Booster and transfers the Wombat LP token to Booster. Booster deposits Wombat LP via VoterProxy deposits to MasterWombat, mints DepositToken, and deposits to BaseRewardPool.

2. [Direct interaction with BaseRewardPool]. In this case, the user already has a Wombat LP token and calls BaseRewardPool. BaseRewardPool calls Booster and transfers Wombat LP tokens there. Booster stakes Wombat LP token into MasterWombat, mints DepositToken and deposits BaseRewardPool

3. [Manual] The user has Wombat LP tokens and calls Booster. Booster deposits Wombat LP tokens into MasterWombat via VoterProxy and mints DepositToken for the user, and the user needs to stake DepositToken to the BaseRewardPool himself.

Withdraw scenarios:

1. [ZAP Simplified Withdrawal]. The user calls PoolDepositor; it calls BaseRewardPool. In turn, it calls Booster and VoterProxy, sending LP tokens to PoolDepositor. PoolDepositor redeems Wombat LP tokens and returns underlying assets to the user.

2. User calls BaseRewardPool. The BaseRewardPool calls Booster. Booster burns DepositToken withdraws LP tokens from MasterWombat via VoterProxy and sends them to the user. In this case, the user must redeem LP tokens using Wombat UI.

3. The same as “2,” but the user needs to take all actions (including interaction with Booster) himself.

The following contracts are involved into deposit and withdrawal process of users' liquidity:

DepositToken.sol - Wrapper for Wombat LP token with mint and burn functions.

• DepositToken is unique for each Wombat LP token. It means that for every new Wombat pool, we create a new DepositToken contract from the factory. When a user supplies liquidity to Wombat via DepositToken, it’s NOT staked into BaseRewardPool and is not receiving any rewards besides the basic Wombat swap fee.

• DepositToken is further staked into BaseRewardPool for receiving rewards in WOM and other third-party tokens (if there are any additional rewards for this pool)

• Booster.sol has mint() and burn() rights

• Booster.sol can be updated

• 1 DepositToken = 1 Wombat pool LP token.

• An example of Deposit Token: Wombat LP token name: Wombat USD Coin Asset symbol: LP-USDC

  Deposit Token: Name: Wombat USD Coin Asset Wombex Deposit Token Symbol: wmxLP-USDC

BaseRewardPool4626.sol is the primary contract with which the user interacts.

• A token is compliant with the ERC4626 standard.

• Non-transferable.

• Accounts Wombat LP tokens deposited by users to the protocol via DepositToken balances

• 1 BaseRewardPool token = 1 DepositToken token = 1 LP Wombat token

• Calls Booster.sol to deposit Wombat LP tokens into MasterWombat.sol or withdraw LP tokens from MasterWombat.sol.

• The users can call the deposit() function. In this case, the contract will take Wombat LP tokens and initiate (call) the deposit() function in Booster.sol contract for staking tokens into MasterWombat (for reference, please check Booster.sol).

• The user can call stake() or stakeFor() with DepositToken on a balance. In this case, contract will take tokens and will credit the same balance to the user

• The user can call withdraw() and receive DepositToken for further interaction with the Booster.sol contract.

• The user can call withdrawAndUnwrap(), and the contract will call Booster.sol for burning DepositToken and returning Wombat LP tokens to the user.

• It Distributes WOM (and other third-party tokens rewards) to users corresponding with their balances.

• It calls Booster.sol in case of claiming rewards for minting WMX for the user. The user can choose the bool _lock. If _lock == true, the user will receive more WMX tokens(or avoid the penalty, see Booster.sol).

Booster.sol is a contract containing the logic of interaction with Wombat protocol via VoterProxy.sol.

• It stores all information about pools. For each pool there is: `address lptoken` - Wombat LP token, `address token` - technical token `DepositToken.sol`, `address gauge` - `MasterWombat.sol` contract, `address crvRewards` - `BaseRewardPool4626.sol` contract, `bool shutdown` - the pool status.

• The contract has several roles.At the current moment, all roles are appointed to Wombex multi-sig. In the future, governance contracts will handle them.

• It creates new pools via smart contract factories (BaseRewardPool and DepositToken).

• Creates new instances for already existing pools (for pools that have BaseRewardPool and DepositToken).

• In case of calling deposit() from BaseRewardPool contract stakes received Wombat LP tokens Wombat to MasterWombat via VoterProxy, mints DepositToken to BaseRewardPool address and records final balance for a user by using stakeFor().

• In the case of calling deposit() function directly by the user Booster.sol stakes received Wombat LP tokens into MasterWombat via VoterProxy, mints DepositToken to the user’s address.

• In case of calling withdraw() from BaseRewardPool contract, burns DepositToken from BaseRewardPool address and sends Wombat LP tokens to BaseRewardPool contract for returning them to the user.

• In case of calling withdraw() by the user - burnsDepositToken from the user’s address and sends Wombat LP token to the user’s address

• Mints WMX tokens in case of calling rewardClaimed() from BaseRewardPool contract. In the Booster.sol contract the correction coefficient can be specified (increases or decreases mintAmount in a pre-defined range). If bool _lock == true, then the user receives more WMX tokens in accordance with penaltyShare. If bool _lock == false, then additional WMX tokens are distributed between WMX stakers using ExtraRewardsDistributor.sol and WmxLocker.sol contracts.

• Every token distributed as a reward (WOM or other ones) can be defined as the structure: struct TokenDistro { address distro; uint256 share; bool callQueue; }. The structure contains address, share and boolean, that defines if tokens should be sent or any additional method used. This data is used for distributing a share of received tokens as a protocol fee. The MAX_DISTRIBUTION limits the total fee.

• Anyone can call the earmarkRewards(). In this case Booster.sol calls VoterProxy.sol, receives WOM + additional token rewards, and will distribute these rewards between BaseRewardPool contract and addresses defined in TokenDistro. Caller receive reward defined as earmarkIncentiveAmount. The Wombex DAO determines the actual size of the reward with an upper limit.

WomStakingProxy.sol - converts Wom into wmxWom for distribution rewards in BaseRewardPool, wmxWom staking, and WmxLocker.sol. The part of the WOM rewards mined by Wombex protocol LPs is transferred to WmxLocker.sol (set up as 10% currently). In case when someone calls earmarkRewards() in the Booster.sol contract distributes WOM (and extra token rewards) to BaseRewardPool contracts and protocol fee to WmxLocker.sol, BaseRewardPool for wmxWOM, and DAO Treasury if the community will make such a decision. Since we distribute WOM tokens to WmxLocker.sol in wmxWOM, Booster.sol calls WomStakingProxy.sol to convert WOM to wmxWom and calls queueNewRewards in WmxLocker.sol.

PoolDepositor.sol is the contract allowing users to deposit assets (such as stablecoins, BNB, etc) directly to Wombat via Wombex without requiring users to interact with Wombat LP tokens manually.

Contracts related to WMX token

Wmx.sol is the contract of Wombex native governance token (WMX)

• WMX is a ERC20 token

• Total token supply of WMX is 100m

• WMX can be minted by using the mint() function. The rights for minting have Booster.sol and WmxMinter.sol contracts. Booster.sol can be updated by updating Booster.sol in VoterProxy.sol.

• WMX pro-rata emission for WOM mined by supplied liquidity in Wombat is defined by the equation: WMX_minted = (((500 - WMX_supply)/100000)*1.5 + 20)*WOM_earned/500. The emission rate can be corrected via Booster.sol according to the Wombex DAO decisions.

WmxClaimZap.sol is the ZAP contract, bundling transactions and allowing one to claim rewards from several pools in one transaction. Also, it allows to stake WMX and convert WOM into wmxWOM and stake in the same transaction.

WmxLocker.sol is the WMX vote-lock contract. Users can lock WMX for 16 weeks, receive voting rights in Wombex governance, and share the protocol fees.

WmxMerkleDrop.sol is the contract for conducting WMX airdrop.

• It stores unclaimed WMX allocated for the airdrop (1% TTS initially), and the root of the airdrop Merkle tree

• It allows claiming WMX tokens by airdropping recipients' addresses with mandatory lock for 16 weeks in WmxLocker.sol.

• After the airdrop is finished, the Wombex DAO can transfer unclaimed tokens to the multi-sig address

• Airdrop will last 14 days from the moment of deployment

WmxMinter.sol allows Wombex DAO to mint any amount of WMX after the initial cooldown period (inflation protection time) is over.

• Inflation protection time is three years now

• Changing inflation protection time is not possible

WmxPenaltyForwarder.sol is used for distributing penalized WMX using ExtraRewardsDistributor.sol and WmxLocker.sol. It occurs if users claim WMX tokens from WmxRewardPool.sol without locking them into WmxLocker.sol, a share of it is taken as a penalty going to the community of WMX vote-lockers. Also, penalized WMX from the Bootstrap event will be transferred from WmxRewardPool.sol.

ExtraRewardsDistributor.sol is a contract distributing additional rewards (including third-party ERC20 tokens) to WmxLocker.sol.

WmxRewardPool.sol is a contract for carrying out the Wombex Bootstrap Event. It rewards WOM conversion to wmxWOM (WOM is converted to wmxWOM by staking into veWOM.sol via WomDepositor.sol and VoterProxy.sol).

• The rewards period is 14 days.

• The amount of the rewards pool is 2% TTS of WMX or 2,000,000 WMX

• _stakingToken - wmxWOM, _rewardToken - WMX.

• User deposits_stakingToken (wmxWOM) into the contract and receives WMX rewards. The number of rewards is calculated based on the total WMX and wmxWOM on the contract balance.

Suppose the user selects to claim rewards without vote-locking after that (depositing to WmxLocker.sol). In that case, 30% of claimed rewards remains on the contract balance as a sort of penalty and will be used for future distribution via WmxPenaltyForwarder.sol, ExtraRewardsDistributor.sol, and WmxLocker.sol.