What is Venus Protocol?

Venus Protocol is a trusted decentralized finance lending and borrowing protocol that's deployed on the BNB Chain. Initially launched in 2020, it combines the stablecoin minting facility of Maker and the algorithmic money markets developed by Compound, providing a simplified user experience and core capabilities in a single application.

How do I interact with Venus Protocol?

Interacting with Venus V4 is straightforward. Supply your chosen asset and the amount to start earning interest. Additionally, once you supply assets, you can also borrow against them. Any interest earned from supplying assets can help offset the interest you accrue when borrowing.

Where are my supplied funds stored?

Your supplied funds are stored in a smart contract on the BNB Chain. The contract's code is public, open-source, and has been formally verified and audited by external auditors. You can withdraw your funds on demand or receive Venus Tokens (vTokens) representing your stake. vTokens are as freely tradable as any other cryptographic asset on BNB Chain.

What is the cost of interacting with Venus Protocol?

Transactions on the Venus V4 protocol require BNB Chain fees, which depend on network congestion and the complexity of the transaction.

Is there any risk?

No platform can be considered entirely risk-free. Risks associated with Venus V4 include smart contract risk and liquidation risk. However, every possible step has been taken to minimize these risks, including making the protocol code public and conducting thorough audits.

What are the key areas Venus Protocol V4 aims to improve?

Venus Protocol focuses on improving three main areas:

• Risk Management: Prioritizing the risk management , Venus introduces new features like Isolated Pools and more sophisticated risk parameters.

• Decentralization: The governance model has been enhanced by introducing fast-track VIPs, role-based access control, and a fine-grained pause mechanism.

• User Experience: The latest version offers an enhanced user interface, a more effective reward system, and isolated lending. Future releases for V4 will feature stable rate borrowing and the Venus Prime Soulbound Token, all aimed at providing a smooth user experience.

What is the Resilient Price Oracle?

The Resilient Price Oracle introduced in Venus V4 fetches prices from multiple sources and validates them, providing a more reliable price indicator and protecting against price manipulations. It supports the integration of new price oracles and allows enabling and disabling price oracles per token.

What are Isolated Pools?

Isolated Pools are a new feature in Venus V4, designed to overcome the limitations of a single core pool. Each Isolated Pool is an independent collection of assets with custom risk management configurations. This setup allows users to better manage their risk and earn yield, while also preventing failures in one market from impacting others.

What is the Risk Fund?

In Venus V4, a risk fund is maintained for each pool. A percentage of the protocol's revenue is deposited into this fund, aiming to counterbalance bad debt and prevent potential market insolvencies.

What changes were made to the governance model in Venus V4?

Venus V4 features a new governance model that introduces fast-track Venus Improvement Proposals (VIPs), role-based access control, and a fine-grained pause mechanism. This new model allows for more agile and accurate decision-making, ensuring the protocol remains competitive and secure.

Overview

Isolated Pools are made up of separate collections of assets with tailored risk management configurations. This design offers users broader opportunities to manage risk and allocate assets to earn yield. Moreover, it prevents hypothetical failures from affecting the liquidity of the entire protocol as they are confined to isolated markets.

Isolated Pools also offer custom rewards for each market in the pool, incentivizing users accordingly.

Isolated Pools Architecture

The Isolated Pools system is based on the PoolRegistry contract. It maintains a directory of isolated lending pools, allows the creation and registration of new pools, and offers getter methods to fetch pool details.

To add a new market to an existing lending pool, the PoolRegistry deploys a JumpRateModelV2 or a WhitePaperInterestRateModel contract, deploying the upgradable VToken for the market before gaining the approval of the market's Comptroller.

User Actions

Users can perform the following actions on any market in a pool:

1. Deposit: Users can deposit an asset, receiving vTokens that correspond to the liquidity deposited. These vTokens accrue interest until they are burned on redeem or liquidated.

2. Borrow: Users can borrow assets, in exchange for locked collateral.

3. Redeem: Users can redeem vTokens for the underlying asset based on the exchange rate.

4. Repay Borrow: Users can repay the borrowed asset and accrued interest.

Overview:

Stable Rate Borrowing is a distinctive feature of the Venus Protocol that provides an alternative to variable interest rate loans. Stable-rate loans set their interest rates at issuance until a rebalancing event occurs. This approach shields users who borrow at a stable rate from being affected by individual actions of other users and large fluctuations in the market.

Rate Determination:

The interest rates for stable and variable rate borrowing are determined based on several calculations involving parameters such as utilization rate, stable loan adoption rate, and total supply. For instance, the stable interest rate will include a base premium plus an additional premium that depends on the stable loan adoption rate.

Model Parameters:

The model parameters involved in the calculations include slopes for the variable interest rate, a base rate per block, the optimal utilization rate (kink), a reserve factor, base premium, and other parameters related to stable loan borrowing.

Rebalancing Conditions:

The fixed rate of a stable loan persists until certain rebalancing conditions are met. These conditions involve the utilization rate and the comparison between the market average borrow rate and the variable borrow rate. The stable rate provides predictability for the borrower but may come at a cost of higher interest rates compared to the variable rate.

Launched in 2020, Venus Protocol (a.k.a. “Venus”) pushed the edges of decentralized finance through its composition of two pre-existing solutions and deployment on BNB chain, lowering the barrier to entry for millions of new users around the globe. By combining the stablecoin minting facility introduced by Maker and algorithmic money markets developed by Compound, Venus simplified the user experience and provided core capabilities that enabled decentralized finance to flourish in a single application. As a result, Venus found remarkable success and quickly rose to be one of the most widely used decentralized applications in web3.

The latest iteration of Venus Protocol, the most trusted and battle-tested lending and borrowing protocol on the BNB Chain, builds on prior successes and lessons learned to improve in 3 key areas:

1. Risk management

2. Decentralization

3. User experience

In doing so, Venus continues to push the boundaries of what's possible within the realm of decentralized finance.

Overview

Key Aspects of the Token Converter

The Token Converter works on four key principles:

1. Distributed and Autonomous: No centralized management or human interactions needed, ensuring a secure and seamless conversion process.

2. Efficient: The system is designed to maximize the amount of specific tokens we receive while protecting against potential risks like sandwich attacks.

3. Streaming: The conversions occur continually, without waiting for scheduled intervals.

4. Transparent: All conversions are publicly recorded in the blockchain, reinforcing our commitment to transparency.

Venus Protocol will offer discounts to incentivize these conversions. This incentive will create arbitrage opportunities in the market, and external agents can potentially gain from these opportunities.

Rational

Before the Token Converter, token conversions were not as seamless and efficient. Venus Protocol needed a system that could constantly convert the received income into specific tokens, with no room for errors or delays.

The Token Converter streamlines the conversion process by allowing key elements in the Venus Protocol, such as the XVSVaultConverter and RiskFundConverter, to autonomously offer token conversions. This solution follows the rules of distributed and autonomous systems, removing the need for human intervention.

Moreover, the introduction of incentives through discounts encourages external agents to take part in the conversion process, thus creating a win-win situation for all. This is in line with the vision of decentralization, where processes are not only transparent but also rewarding for participants.

Architecture

The dashed lines represent transactions initiated by external agents (VIP’s, scripts, arbitrage bots, etc.), and the solid lines represent transfers of funds.

Overview

The Peg Stability Module (PSM) is a crucial component of the Venus Protocol designed to maintain the value of the VAI stablecoin at $1. It functions similarly to the system provided by MakerDAO for DAI. The PSM contract utilizes two stablecoins: VAI (the target stablecoin) and USDT (used to help maintain the peg).

Features

Convert Functionality:

• Users can exchange VAI and USDT with a "fixed" conversion rate of 1 VAI = $1.

• Users can send VAI to the PSM and receive USDT if enough USDT is available in the PSM.

• Users can send USDT to the PSM and receive VAI, provided that the PSM hasn't reached its maximum allowed minted VAI limit.

No Stability Fee

The VAI minted through the PSM does not accrue any interest or stability fee.

Configurable Parameters:

The PSM contract has three configurable variables set via the Venus Improvement Proposal (VIP):

• feeIn: Fee charged when users send USDT to the PSM.

• feeOut: Fee charged when users send VAI to the PSM.

• maxMintedVAI: The maximum amount of VAI that the PSM can distribute. Conversions that exceed this limit will be reverted.

Fees Sent to Treasury: The collected fees are sent to the Venus Treasury contract in each operation.

Integration with Oracle Price: The PSM considers the USD value of the stablecoin to peg VAI to its value accurately.

Convert Functions

Function swapStableForVAI

This function allows users to exchange the paired stablecoin (USDT) for VAI.

Expected Parameters:

• receiver: Address of the user who will receive the VAI.

• amount: The amount of stablecoin (USDT) the sender wants to convert.

The received stablecoins will be held by the PSM, and the fee specified by feeIn will be sent to the Treasury contract.

This function returns the amount of VAI transferred to the receiver.

Function swapVAIForStable

This function enables users to exchange VAI for the paired stablecoin (USDT).

Expected Parameters:

• receiver: Address of the user who will receive the stablecoin.

• amount: The expected amount of stablecoin (USDT) the user should receive.

The received VAI will be burnt, and the fee specified by feeOut will be sent to the Treasury contract.

This function returns the amount of VAI transferred from the sender (burnt + fee).

Preview Functions

The PSM also offers preview functions that help users estimate the outcome of convert operations:

previewSwapVAIForStable(uint256 stableTknAmount)

Returns the amount of VAI that the sender would transfer (burnt + fee) to receive the specified stablecoin amount.

previewSwapStableForVAI(uint256 stableTknAmount)

Returns the amount of VAI that the receiver would receive after executing the swapVAIForStable function with the specified stablecoin amount.

Integration of the Oracle Price

To protect the value of VAI and consider the USD value of the paired stablecoin, the PSM integrates with the Resilient Oracle. The following rules are applied:

swapVAIForStable (the user sends VAI and receives USDT)

• If the oracle price of the paired stablecoin is below $1, the conversion rate is 1 stablecoin = $1.

• If the oracle price of the paired stablecoin is above $1, the conversion rate is 1 stablecoin = oracle price.

swapStableForVAI (the user sends USDT and receives VAI)

• If the oracle price of the paired stablecoin is below $1, the conversion rate is 1 stablecoin = oracle price.

• If the oracle price of the paired stablecoin is above $1, the conversion rate is 1 stablecoin = $1.

Overview

Venus Protocol's governance relies on participants locking XVS tokens into a vault to acquire voting power for Venus Improvement Proposals (VIPs). A 48-hour timelock period after voting ensures transparency and protection against malicious proposals. However, the initial model's rigidity prompted the introduction of a new governance structure in Venus V4. This upgraded model incorporates fast-track VIPs, role-based access control, and a fine-grained pause mechanism for enhanced flexibility and timely adjustments.

Governance Upgrade

Venus V4 introduces an improved governance structure with the following components:

• Fast-track and Critical VIPs

• Role-based access control

• Fine-grained pause

Fast-track and Critical Improvement Proposals

Venus Governance has now categorized VIPs into three types: Normal, Fast-track, and Critical.

• Normal VIPs encompass significant updates like contract upgrades or changes in access controls.

• Fast-track VIPs deal with risk parameter adjustments such as interest rates or collateral factors.

• Critical VIPs are utilized during emergencies demanding an immediate reaction.

Each VIP type has its unique proposal threshold, timelock, and voting periods, reflecting the potential risk and impact of the proposed changes.

The initial voting and delay periods for these types are as follows:

• Normal VIP: 24 hour voting period + 48 hour delay (+ 48 hour delay to execute commands on networks other than BNB Chain)

• Fast-track VIP: 24 hour voting period + 6 hour delay (+ 6 hour delay to execute commands on networks other than BNB Chain)

• Critical VIP: 6 hour voting period + 1 hour delay (+ 1 hour delay to execute commands on networks other than BNB Chain)

Role-based Access Control

Venus V4 employs a separate Access Control Manager contract that validates access permissions rather than merely verifying the caller as an "admin". This allows certain actions to bypass voting, enabling them to take the fast-track or critical route, or even to be executed directly through a multisig by guardians. It can be particularly useful for implementing borrowing and supply caps, pausing specific market actions, or responding to rapid market fluctuations.

Fine-grained Pause

A fine-grained pause mechanism allows the pause guardian to individually halt any action on any market. Unlike previous versions, where the entire protocol was paused for damage control or protection against attacks, the updated model enables guardians to pause individual market actions like supply, borrow, and enabling collateral, offering greater control and flexibility.

Overview

XVS Vault Base Rewards

The XVS Staking Vault is an integral component of the Venus ecosystem. It enables governance voting participation and is a prerequisite for Venus Prime eligibility. To incentivize XVS staking, additional rewards will be offered in the form of Base Rewards (previously referred to as Legacy Rewards).

Revenue Distribution from Protocol Reserves

Protocol reserves are mainly composed of accumulated borrow fees. The model for revenue allocation from these reserves divides income into three main segments:

• Treasury Reserve (60%): The treasury reserve is used to fund community-driven initiatives and essential protocol expenses for its ongoing operations.

• XVS Vault Rewards (20%): This allocation is designated for the buyback of XVS, which is then distributed via vault rewards.

• Venus Prime Token Program (20%): Used to boost select market APYs with organic rewards for users that qualify.

Allocation for Additional Revenue Streams

Other revenue streams include liquidation penalties and potential income generated from future product releases. The revenue distribution for these streams is as follows:

• Treasury Reserves (80%)

• XVS Vault Rewards (20%)

The methodology behind these adjustments includes an assessment of the existing tokenomics, past changes, their impact on the ecosystem, and analysis of market dynamics and trends.

This dual allocation model accounts for the diverse revenue sources within the Venus Protocol ecosystem, ensuring robust and responsive financial management. As the protocol evolves and introduces new products, these models may further be adjusted to optimally serve the Venus community.

Some assets, such as Liquid Staking Tokens (LSTs), are closely tied to an underlying asset, often featuring an added growth component.

The exchange rate between an asset and its underlying is typically sourced from an onchain smart contract, which can be susceptible to manipulation. A capped oracle is a design mechanism that mitigates potential losses from such manipulation by limiting the rate at which the exchange rate is allowed to grow.

The capped oracle mechanism should be used for any asset whose price is derived through an intermediary token, where the exchange rate between the source asset and the intermediary is fetched onchain and includes a growth component.

At a high level, the capped oracle determines the maximum allowable exchange rate at the queried block based on a predefined growth rate. It then compares this with the current onchain exchange rate, and if the current rate exceeds the calculated maximum, it caps it to that maximum value.

Typically, the current maximum exchange rate at a given block is calculated by taking a historical exchange rate from a past block and applying a predefined per-second growth rate up to the current block timestamp. However, since the exchange rate may not grow consistently over time, the historical reference rate is periodically updated to ensure a more accurate and reliable maximum exchange rate.

The historical reference rate is periodically refreshed through a process called snapshotting. During this process, the new reference rate is set to the lower of the current onchain exchange rate or the maximum rate derived from the previous reference rate, helping maintain a more accurate and robust cap. Before querying an asset’s price from the capped oracle, the consumer should trigger the snapshotting process. If the configured interval has elapsed, a new snapshot will be taken.

The capped exchange rate between intervals is constrained by a per-second growth limit. However, since the actual exchange rate may exceed this cap, we inflate the snapshotted exchange rate by a predefined buffer to avoid imposing a hard limit.

Configuration

The following configuration needs to be defined when configuring the capped oracle for a token:

• Annual Growth Rate: This defines the maximum growth in exchange rate per year. Internally this is converted to growth rate per second.

• Snapshot Interval: After the number of seconds window at which the reference exchange rate is recalculated,

• Initial Snapshot Exchange Rate and Timestamp: Defines the initial reference exchange rate and the timestamp at which the exchange rate is taken from.

• Snapshot Gap: Used to define the inflation of the exchange rate at each snapshot.

Note that all the above variables values can be updated using the governance process after the deployment with the initial values.

Example

Let’s walk through an example to understand how the capped oracle functions. Suppose we want to retrieve the exchange rate between wstETH and stETH.

• Annual Growth Rate: Assume an annual growth rate of 2.9%, based on Lido’s estimated APY. Taking into account Lido compounding period is daily, the estimated APY would be 2.9423% (compounding should be considered when the caps are defined). So, the associated capped oracle could be configured with a maximum annual growth rate of 5%. Internally, this will be converted into a per-second growth rate.

• Snapshot Interval: The snapshot can be updated once per month to refresh the reference exchange rate.

• Initial Snapshot: We fetch the current exchange rate and timestamp from the onchain wstETH contract. For instance, the current exchange rate is 1.200101369591475639 and the timestamp is 1744895950. We apply a buffer on top of the current exchange rate: for example 1% of the maximum annual growth rate, that is 1% * 5% = 0.05%. So, the initial snapshot value would be 1.200101369591475639 * 1.0005 = 1.20070142027627137681. This way, the capped oracle won't cap spikes on the wstETH exchange rate just after the initialization.

• Snapshot Gap: The same concept of the buffer applied to calculate the initial snapshot in the previous step, but to be considered every time the snapshot is automatically updated. This cap could be set to 1.200101369591475639 * 0.0005 = 0.0006, and reviewed periodically.

Given this initial setup:

• after 15 days, the maximum exchange rate allowed will be 1.20070142027627137681 * (1 + (0.05 * 15 / 365)) = 1.20316860954764085647

• after 1 month, the snapshot will be automatically updated. Assuming the exchange rate at that time is 1.20300161856832627043, after applying the snapshot gap, the new maximum exchange rate will be 1.20360161856832627043 (1.20300161856832627043 + 0.0006)

• after 15 days, the maximum exchange rate allowed will be 1.20360161856832627043 * (1 + (0.05 * 15 / 365)) = 1.20607476713814428156

Overview

XVS is the native token of Venus Protocol and serves as its governance token. By staking XVS tokens in the vault, users gain voting power proportionate to the amount staked. This voting power enables them to participate in the voting process for Venus Improvement Proposals (VIPs), thereby playing a critical role in the development and evolution of the Venus Protocol.

Furthermore, users who stake their XVS tokens in the vault have the potential to earn yield, creating an incentive for participation in the Venus governance process. This aligns the interests of XVS holders with the overall health and success of the Venus Protocol.

Next Steps and Future of XVS

The upcoming Venus Prime program adds a new dimension to the utility of XVS tokens. As Venus Protocol continues to innovate:

• The launch of Venus Prime will provide opportunities for additional yield to committed users, using protocol's revenue instead of just relying on the token supply.

• The program will introduce unique, non-transferable tokens for eligible participants, adding a new layer of user interaction.

These developments further emphasize the importance of the XVS token in the ecosystem, providing holders with more ways to earn and participate in the protocol's future.

Overview

Venus Protocol offers variable interest rates for markets using two different models: the Jump Rate Model and the Whitepaper Rate Model. Each market operates under one of these models with specifically set risk parameters at the market's inception. Notably, the community can update these parameters through the Governance process. Moreover, some markets feature a stable rate, introduced in Venus V4.

Jump Rate Model

The Jump Rate Model uses the following formulas to calculate the interest:

For Borrow rate:

And, for Supply rate:

Where,

The borrow rate employs different formulas when the utilization rate falls into two distinct ranges:

If u < kink:

If u > kink:

Model Parameters

• a1: Variable interest rate slope1.

• a2: Variable interest rate slope2.

• b: Base rate per block (baseRatePerYear / blocksPerYear).

• kink: Optimal utilization rate, at which the variable interest rate slope shifts from slope1 to slope2.

• reserve_factor: Part of interest income withdrawn from the protocol, i.e., not distributed to suppliers.

The utilization rate (u) is defined as:

Where:

• borrows: Amount of borrows in the market, in terms of the underlying asset, excluding bad debt.

• cash: Total amount of the underlying asset owned by the market at a specific time.

• reserves: Amount of the underlying asset owned by the market but unavailable for borrowers or suppliers, reserved for various uses defined by the protocol's tokenomics.

• bad_debt: After liquidators repay as much debt as possible, reducing collateral to a minimal amount, the remaining debt is tagged as bad debt. Bad debt doesn’t accrue interest.

Whitepaper Rate Model

The Whitepaper Rate Model is simpler, where the borrow rate depends linearly on the utilization:

For Borrow rate:

For Supply rate:

Where,

Introduction

Venus Protocol is deeply committed to ensuring the highest level of security and risk management for our users. This section of the documentation outlines our comprehensive approach to risk management, emphasizing our continuous monitoring practices, partnerships for enhanced security, real-time alert systems, and ongoing risk assessments.

Multiple Audits Before Deployment

• Prior to deployment, Venus Protocol undergoes extensive audits conducted by industry-leading security firms. The results of these audits are publicly accessible and have been fully implemented, ensuring a robust and secure framework.

Continuous On-Chain Monitoring

• Venus Protocol has partnered with Chaos Labs, a leader in blockchain security and monitoring. This partnership equips us with sophisticated tools for continuous on-chain monitoring, significantly enhancing our risk control and mitigation strategies.

Real-Time Alert System

• To further enhance our risk management, we have implemented a real-time alert system via Telegram. This system provides immediate notifications for critical events such as market high utilization, significant whale movements, and borrow/supply cap utilization.

Dynamic Risk Management

• In collaboration with Chaos Labs, we continuously analyze market conditions and adjust risk parameters across all pools regularly or anytime there is need for adjustment to mitigate risks due to market conditions. These adjustments are based on comprehensive data analysis and are integral to maintaining the stability and security of the protocol.

Frontend

• The Venus Protocol UI is deployed on AWS infrastructure. Additionally, Cloudflare is employed to distribute the web app. The relevant security services in both AWS and Cloudflare are properly configured to detect and mitigate security risks.

• SPF and DKIM are configured to protect every email sent from a @venus.io account.

• Web certificates, generated by AWS, are set to auto-renew.

• Venus nameservers are hosted on Cloudflare, serving as our DNS provider.

• Only privileged users have the authority to deploy the open-source code, accessible on Github (https://github.com/VenusProtocol/venus-protocol-interface), to the domain app.venus.io. Additionally, only privileged users are authorized to merge pull requests in the Github repository.

Conclusion

The risk management practices at Venus Protocol are designed to provide a secure and stable environment for our users. Our commitment to continuous monitoring, real-time alerts, and dynamic risk adjustments ensure that we are always at the forefront of blockchain security. We encourage our community to explore the provided resources for a deeper understanding of our risk management protocols.

Overview

VAI is the primary stablecoin of the Venus Protocol. It is carefully designed and integrated with a series of stability mechanisms to maintain its peg to 1 USD.

Stability Fee and Optimised Minting

VAI sustains its value via a stability fee system. This fee is a charge that users incur when they repay their minted VAI. Calculated on a block-by-block basis, this fee gets added to the user's minted VAI balance. This fee system encourages users to either mint or burn VAI in response to its price fluctuations, thereby contributing to its stability.

The stability fee is determined through the following formula:

The baseRate is a fixed rate that users must always pay, while max(0, (1 - currentPriceOfVAI)) * floatingRate is a variable rate that users pay based on outstanding VAI. This incentivizes users to burn or mint VAI according to its price. The variable rate will always be greater or equal to zero, meaning the minimum stability fee will be the base rate.

Revenue generated from the stability fee serves as a financial cushion during extreme market conditions, such as bad debt scenarios.

VAI Comptroller

This is the implementation contract for the VAIUnitroller proxy

Solidity API

mintVAI

The mintVAI function mints and transfers VAI from the protocol to the user, and adds a borrow balance. The amount minted must be less than the user's Account Liquidity and the mint vai limit.

function mintVAI(uint256 mintVAIAmount) external returns (uint256)

Parameters

Return Values

repayVAI

The repay function transfers VAI interest into the protocol and burns the rest, reducing the borrower's borrow balance. Before repaying VAI, users must first approve VAIController to access their VAI balance.

function repayVAI(uint256 amount) external returns (uint256, uint256)

Parameters

Return Values

repayVAIBehalf

The repay on behalf function transfers VAI interest into the protocol and burns the rest, reducing the borrower's borrow balance. Borrowed VAIs are repaid by another user (possibly the borrower). Before repaying VAI, the payer must first approve VAIController to access their VAI balance.

function repayVAIBehalf(address borrower, uint256 amount) external returns (uint256, uint256)

Parameters

Return Values

liquidateVAI

The sender liquidates the vai minters collateral. The collateral seized is transferred to the liquidator.

function liquidateVAI(address borrower, uint256 repayAmount, contract VTokenInterface vTokenCollateral) external returns (uint256, uint256)

Parameters

Return Values

_setComptroller

Sets a new comptroller

function _setComptroller(contract ComptrollerInterface comptroller_) external returns (uint256)

Return Values

setPrimeToken

Set the prime token contract address

function setPrimeToken(address prime_) external

Parameters

setVAIToken

Set the VAI token contract address

function setVAIToken(address vai_) external

Parameters

toggleOnlyPrimeHolderMint

Toggle mint only for prime holder

function toggleOnlyPrimeHolderMint() external returns (uint256)

Return Values

struct AccountAmountLocalVars {
  uint256 oErr;
  enum CarefulMath.MathError mErr;
  uint256 sumSupply;
  uint256 marketSupply;
  uint256 sumBorrowPlusEffects;
  uint256 vTokenBalance;
  uint256 borrowBalance;
  uint256 exchangeRateMantissa;
  uint256 oraclePriceMantissa;
  struct ExponentialNoError.Exp exchangeRate;
  struct ExponentialNoError.Exp oraclePrice;
  struct ExponentialNoError.Exp tokensToDenom;
}

getMintableVAI

Function that returns the amount of VAI a user can mint based on their account liquidy and the VAI mint rate If mintEnabledOnlyForPrimeHolder is true, only Prime holders are able to mint VAI

function getMintableVAI(address minter) public view returns (uint256, uint256)

Parameters

Return Values

_setTreasuryData

Update treasury data

function _setTreasuryData(address newTreasuryGuardian, address newTreasuryAddress, uint256 newTreasuryPercent) external returns (uint256)

Parameters

getVAIRepayRate

Gets yearly VAI interest rate based on the VAI price

function getVAIRepayRate() public view returns (uint256)

Return Values

getVAIRepayRatePerBlock

Get interest rate per block

function getVAIRepayRatePerBlock() public view returns (uint256)

Return Values

getVAIMinterInterestIndex

Get the last updated interest index for a VAI Minter

function getVAIMinterInterestIndex(address minter) public view returns (uint256)

Parameters

Return Values

getVAIRepayAmount

Get the current total VAI a user needs to repay

function getVAIRepayAmount(address account) public view returns (uint256)

Parameters

Return Values

getVAICalculateRepayAmount

Calculate how much VAI the user needs to repay

function getVAICalculateRepayAmount(address borrower, uint256 repayAmount) public view returns (uint256, uint256, uint256)

Parameters

Return Values

accrueVAIInterest

Accrue interest on outstanding minted VAI

function accrueVAIInterest() public

setAccessControl

Sets the address of the access control of this contract

function setAccessControl(address newAccessControlAddress) external

Parameters

setBaseRate

Set VAI borrow base rate

function setBaseRate(uint256 newBaseRateMantissa) external

Parameters

setFloatRate

Set VAI borrow float rate

function setFloatRate(uint256 newFloatRateMantissa) external

Parameters

setReceiver

Set VAI stability fee receiver address

function setReceiver(address newReceiver) external

Parameters

setMintCap

Set VAI mint cap

function setMintCap(uint256 _mintCap) external

Parameters

getVAIAddress

Return the address of the VAI token

function getVAIAddress() public view returns (address)

Return Values

VAI Unitroller

This is the proxy contract for the VAIComptroller

Solidity API

_setPendingImplementation

• Admin Functions **

function _setPendingImplementation(address newPendingImplementation) public returns (uint256)

_acceptImplementation

Accepts new implementation of comptroller. msg.sender must be pendingImplementation

function _acceptImplementation() public returns (uint256)

Return Values

_setPendingAdmin

Begins transfer of admin rights. The newPendingAdmin must call _acceptAdmin to finalize the transfer.

function _setPendingAdmin(address newPendingAdmin) public returns (uint256)

Parameters

Return Values

_acceptAdmin

Accepts transfer of admin rights. msg.sender must be pendingAdmin

function _acceptAdmin() public returns (uint256)

Return Values

Vaults within Venus Protocol provide a secure and efficient mechanism for users to stake their tokens, whether XVS or VAI, and earn passive income. This staking process allows users to actively participate in and contribute to the stability and security of the Venus ecosystem, while maximizing returns on their holdings.

Staking in XVS Vault

1. Navigate to the Venus app (app.venus.io) and connect your BNB Chain Wallet or other supported wallet apps.

2. On the left side of the screen, click on the 'Vault' tab.

3. A new screen will display two options: XVS and VAI vaults. Select the 'XVS' vault.

4. Once you select the XVS vault, a new interface will show. Click the 'Stake' button.

5. A pop-up will appear asking for the amount of XVS you want to stake. Input the desired amount and confirm.

6. After entering the amount, a prompt will ask for the transaction's confirmation in your wallet. Confirm this.

7. Once you've staked your XVS tokens, the interface will show the staked amount, your potential rewards, and other vault statistics.

Staking in VAI Vault

1. Follow the same steps as above to access the 'Vault' tab in the Venus app.

2. This time, select the 'VAI' vault.

3. Upon clicking on the 'VAI' vault, you'll see the option to 'Stake'.

4. Enter the amount of VAI you'd like to stake and confirm the staking action.

5. Just like with the XVS vault, you'll need to confirm the transaction in your wallet.

6. After staking, the interface will show the staked amount, potential rewards, and other relevant statistics related to the VAI vault.

After successfully connecting your wallet, you will gain access to all the features of the Venus Protocol interface. In the Dashboard menu you will find all the markets. Clicking one of the markets a new modal will pop out, enabling you to interact with the selected market. Just make sure you are under the "Supply" or "Borrow" tab, depending on the desired action.

Supply Assets to Earn Interest

2. Navigate to the "Dashboard" menu and choose the asset you want to supply. For example, if you want to supply TRX, click on the TRX market.

3. Enable the asset. This will prompt a transaction confirmation in your wallet. Remember that a small gas fee applies, so ensure some native tokens (BNB for BNB chain, or ETH for Ethereum, for example) are available in your wallet.

4. Specify the amount you want to supply. The selected assets are transferred directly from your wallet to Venus Protocol, earning interest immediately. This interest will be automatically added to your Supply Balance.

Manage your Borrowing Limit

Your borrowing limit on Venus Protocol is a function of the assets you have supplied. The following steps guide you to manage it:

1. Navigate to the "Account" section.

2. Here, you'll find your Borrow Limit on each pool, represented as a percentage of the total value of your supplied assets.

3. To adjust this limit, you can either supply more assets or repay some of your outstanding loans.

Borrow Assets on Venus Protocol

After supplying assets, you can borrow other assets within your borrowing limit:

1. From the "Dashboard" menu, select the asset you want to borrow.

2. Input the amount you wish to borrow and confirm the transaction.

Farm $XVS tokens

In addition to earning interest on supplied assets, you can also farm $XVS tokens:

1. In the "Vaults" section, you can stake your XVS or VAI tokens to earn XVS tokens.

2. Click on 'Stake'. You will be prompted to confirm the transaction in your wallet.

Lending and Borrowing Example

Let's assume you supply 1000 TRX to Venus, and the vTRX/TRX rate is 0.0204. You'd receive approximately 49,019 vTRX in return (1000 / 0.0204). If the vTRX/TRX rate increases to 0.0215 after a year, your 49,019 vTRX would be worth 1021.5 TRX (49019 * 0.0215), an increase of 21.5 TRX.

Remember that these vTokens represent your collateral in Venus Protocol. It's crucial not to trade or transfer them if you have an active loan, as they're required to maintain your borrowing limit.

WETH

The conversion of ETH -> WETH and WETH -> ETH is always available in the WETH token itself, and the exchange rate is always 1:1:

• If you wrap 1 ETH, you'll receive 1 WETH.

• If you unwrap 1 WETH, you'll receive 1 ETH.

An easy way to get WETH from ETH is by using Uniswap. For example, on the Ethereum mainnet, the process would be:

2. Connect your wallet.

3. Type the amount of ETH you want to wrap.

4. Click on Wrap.

5. Review and accept the transaction in your Web3 wallet.

6. Remember to add the WETH token to your Web3 wallet to see your WETH balance.

Overview

Venus Protocol is excited to announce Venus Prime, a revolutionary incentive program aimed to bolster user engagement and growth within the protocol. An integral part of Venus Tokenomics v3.1, Venus Prime aims to enhance rewards and promote $XVS staking, focusing on markets including USDT, USDC, BTC and ETH.

Venus Prime Essentials

Venus Prime's uniqueness lies in its self-sustaining rewards system, instead of external sources, rewards are derived from the protocol's revenue, fostering a sustainable and ever-growing program.

Eligible $XVS holders will receive a unique, non-transferable Soulbound Token, which boosts rewards across selected markets.

Prime Tokens:

Venus Prime encourages user commitment through two unique Prime Tokens:

1. Revocable Prime Token:

   • Users need to stake at least 1,000 XVS for 90 days in a row.

   • After these 90 days, users can mint their Prime Token.

   • If a user decides to withdraw XVS and their balance falls below 1000, their Prime Token will be automatically revoked.
2. Irrevocable "OG" Prime Token (Phase 2):

   • To be defined

Expected Impact and Launch

Venus Prime aims to incentivize larger stake sizes and diverse user participation. This is expected to significantly increase the staking of XVS, the Total Value Locked (TVL), and market growth.

Venus Prime intends to promote user loyalty and the overall growth of the protocol. By endorsing long-term staking, discouraging premature withdrawals, and incentivizing larger stakes, Venus Prime sets a new course in user engagement and liquidity, contributing to Venus Protocol's success.

Stake your $XVS tokens today to be eligible for Venus Prime, an exciting new venture in the DeFi landscape.

Technical Reward Details

Reward Formula: Cobb-Douglas function

Where:

• $Rewards_{i,m}$ = Rewards for user $i$ in market $m$

• $\Gamma_m$ = Protocol Reserve Revenue for market $m$

• $μ$ = Proportion to be distributed as rewards

• $α$ = Protocol stake and supply & borrow amplification weight

• $τ_{i}​$ = XVS staked amount for user $i$

• $\sigma_i$ = Sum of qualified supply and borrow balance for user $i$

• $∑_{j,m}​$ = Sum for all users $j$ in markets $m$

Qualifiable XVS Staked:

Qualifiable supply and borrow:

Note: There will be a limit for the qualifiable supply and borrow amounts, set by the staked XVS limit and the market multiplier.

User Reward Example:

Model Parameters

• $α$ = 0.5

• ${\sum_{j,BTC} \tau_{j}^\alpha \times \sigma_{j,BTC}^{1-\alpha}}$ = 744,164

• $\Gamma_{BTC}$ = 8 BTC

• $\mu$ = 0.2

• BTC Supply Multiplier = 2

• XVS Price = $4.0

User Parameters

Qualifiable Staked XVS

$\tau_i=min(100000,\text{ } 1200)$

Qualifiable Supply and Borrow

$\sigma_{i,\text{BTC}} = \textit{min}(\text{\$9600}, \text{\$2500})$

User Rewards

$Rewards_{i, BTC} = 8\times 0.2\times \dfrac{1,200^{0.5}\times 2,500^{0.5}}{744,164}$

$Rewards_{i, BTC} = \ 0.00372$

$\text{User APY Increase} = \dfrac{0.00372}{0.097} = 3.88\%$

Expected Rewards Function

Rewards in the Venus Prime program will automatically increase as a user increases its XVS Stake, so long as the amount staked and market participation fall within the limits outlined in the "Technical Reward Details" section below.

The graph above demonstrates the relationship between an increased XVS staked amount and its effect on market rewards, assuming a constant participation of $2.5K USD in the BTC supply market. This helps visualize how an increase in the staked amount influences the APY.

Overview

Venus Protocol's governance model allows XVS token holders to propose and vote on Venus Improvement Proposals (VIPs). Here's a step-by-step guide to help you create and submit a proposal.

Step 1: Visit the Venus Governance Portal

Step 2: Connect Your Wallet

To submit a proposal, you need to connect your wallet by clicking on the "Connect Wallet" button at the top right corner of the screen. A menu will appear listing various wallets that the Venus Governance Portal supports. Select your wallet from the menu and follow the instructions to connect your wallet to the portal.

Step 3: Create a Proposal

Now that your wallet is connected, you can create a proposal. Look for the "Create Proposal" button at the top right corner of the screen and click on it.

This action will open a modal presenting two options - "Upload file" and "Create Manually":

Step 4: Upload a proposal file

The fastest way to create a proposal is by importing a VIP file. The import uses a JSON file containing all the information needed to create a VIP, such as the proposal's title, type, actions and parameters.

Step 4.1: Choose a VIP file

Clicking "Upload file" will lead you to choose the proposal file you want to upload. After uploading the desired file, it will be parsed and validated and any possible errors found will be reported by the interface.

Step 4.2: Confirm the Proposal

Once the import is successfully validated, the interface will present all the VIP data for your review:

If everything looks good, click "Create" at the bottom of the modal to confirm the creation of your VIP.

Step 5: Create a Proposal Manually

Proposals can also be created manually by clicking on "Create manually".

Step 5.1: Choose the Proposal Type

After clicking the "Create manually" button, a new interface will pop up prompting you to select the proposal type. Select the relevant proposal type for the change you want to propose.

Step 5.2: Enter Proposal Information

The next step is to provide detailed information about your proposal. This includes the proposal's title, a brief description, and a link to an off-chain discussion related to your proposal. Ensure the information you provide is clear and concise to facilitate understanding by other community members.

Step 5.3: Set the Voting Options

The third screen is where you can specify descriptions for the voting options (for, against, abstain).

Step 5.4: Specify the Actions

Next add the actions that will take place if the proposal is approved. An action requires an contract address, function signature and arguments so that the operation can be created correctly.

Step 5.5: Confirm the Proposal Submission

Finally, just like after the VIP import, you will be able to review your proposal to ensure all details are accurate. After confirming everything is correct, click the "Submit" button to submit your proposal. You'll see a confirmation prompt on your connected wallet. Confirm the transaction to complete the proposal submission process.

Congratulations! You've successfully submitted a Venus Improvement Proposal. The Venus community will now review your proposal and vote on it. Remember, your active involvement in Venus Protocol's governance process is crucial for its continued development and success.

Overview

Venus DAO is an autonomous and decentralized organization that functions via smart contracts on a blockchain, meaning it operates without any central authority or control. The purpose of DAOs is to facilitate trustless collaboration and decision-making among members, who can be individuals or entities involved in the organization. Governance within Venus DAO encompasses making decisions, establishing rules, and managing resources.

It includes the following components:

1/ Token Holders: DAOs typically have a native token, representing membership and voting rights within the organization. For Venus Protocol, this native token is XVS. Token holders partake in the decision-making process by voting on proposals.

2/ Proposals: Venus DAO members who stake XVS in the Vault can create proposals, which suggest changes, initiatives, or organizational actions. Proposals can span a variety of topics such as protocol upgrades, funding requests, or changes to the DAO's rules. To propose, one requires "Voting power" of 300,000 XVS. To vote on a proposal, one needs "Voting power" of 600,000 XVS, either individually owned or delegated by other members.

3/ Voting: Following a proposal's creation, token holders can vote on it. Venus DAO manages the voting process, queuing and voting on protocol updates within 48-hour timelocks. The voting method could entail a simple majority vote, a supermajority, or weighted voting based on each participant's token count, as is the case with Venus Protocol.

4/ Voting Period: Venus DAO recognizes three Venus Improvement Proposals (VIP) roles: Normal, Fast Track, and Critical. Each VIP role has a unique proposal threshold, timelock, and voting period, which can be configured by Governance. This duration allows token holders ample time to review, discuss, and cast their votes. The votes are tallied once the voting period concludes.

5/ Execution: After a proposal garners support and votes, all Venus DAO members can execute the VIP directly in the Venus dapp through smart contracts.

6/ Transparency and Auditability: All Venus DAO transactions and governance activities take place on a public blockchain, enabling transparency and auditability for anyone interested. This level of transparency helps maintain accountability and minimizes potential fraud or manipulation risks.

It's crucial to understand that DAO governance is an evolving field, with different DAOs adopting unique governance structures and processes. The specific rules and mechanisms are continually refined and adapted to best meet the needs of all Venus DAO members.\

Delegate Voting Power

Step 1: Visit the Venus Governance Portal

Step 2: Connect Your Wallet

On the top right corner of the screen, click on the "Connect Wallet" button. Choose your wallet from the dropdown menu and follow the prompts to connect.

Step 3: Delegate Your Voting Power

Once your wallet is connected, click on the "Delegate" button in the Governance section. This will open up a new dialogue box.

Step 4: Enter Your Address

In the new dialogue box, click on the "Paste your address" field. Your connected wallet address should automatically populate.

Step 5: Redelegate Your Votes

Click on the "Redelegate" button. This will submit the address for vote delegation.

Step 6: Confirm the Transaction

A confirmation prompt will appear in your connected wallet (for example, MetaMask). Confirm the transaction to complete the voting power delegation process.

Congratulations, you've now enabled your XVS in the vault to participate in Venus Protocol's governance. Your tokens are now ready to vote on upcoming VIP proposals. Remember, your engagement in the protocol’s decision-making process is vital for its future development and success.

Vote for a VIP

Step 7: Select the VIP Proposal

To vote on a Venus Improvement Proposal (VIP), navigate to the list of active proposals on the Venus Governance Portal. Click on the title of the VIP you wish to vote on. Remember, your voting eligibility requires your address to be delegated.

Step 8: Cast Your Vote

After selecting the VIP, you'll see voting options for the proposal. You can choose 'For' to vote in favor of the proposal, 'Against' to vote against it, or 'Abstain' to remain neutral.

Step 9: Add a Comment

Before you submit your vote, you have an option to provide a comment explaining the reasoning behind your decision. This step is not mandatory, but it contributes to a more transparent and inclusive voting process.

Step 10: Submit Your Vote

Once you've made your decision and optionally left a comment, click the 'Submit Vote' button to cast your vote.

Congratulations, you've successfully voted on a VIP proposal! Your participation is integral to the development and success of the Venus Protocol. Thank you for your contribution to our community's decision-making process. Remember, every vote counts in shaping the future of Venus Protocol.

This is a step-by-step guide on how to perform liquidations on the Venus Protocol. Liquidations involve seizing collateral from under-collateralized accounts to repay outstanding debts. The instructions are targeted towards developers or bots that aim to automate the liquidation process.

Account Liquidity Calculations

Venus Protocol uses two calculations to determine account liquidity: Collateral Factor (CF) and Liquidation Threshold (LT).

Collateral Factor (CF)

Collateral Factor is the percentage of the supplied funds that can be used to cover a loan. Comptroller.getAccountLiquidity in the Core Pool and Comptroller.getBorrowingPower in Isolated Pools return the liquidity or an account. They use the Resilient Oracle to retrieve the value of the asset and the collateral factor for the market to determine the percentage of supply can be used as collateral. Relying on getBorrowingPower is not sufficient for identifying accounts in need of liquidation on Isolated Pools.

Liquidation Threshold (LT)

The Liquidation Threshold represents the point at which an account becomes under-collateralized, triggering the possibility of liquidation. In the Core Pool this is the same as the collateral factor. In Isolated Pools, the LT can be retrieved with Comptroller.getAccountLiquidity.

Liquidators often use external monitoring systems or other strategies to accurately identify under-collateralized accounts.

By combining the information obtained from these functions, one can accurately identify under-collateralized accounts that are suitable for liquidation.

Minimum Liquidatable Collateral

The Comptroller.minLiquidatableCollateral variable represents the minimal collateral in USD required for regular (non-batch) liquidations. Accounts with collateral below this threshold may not be eligible for non-batch liquidations. It's defined in USD value (18 decimals scale).

Finding Under-Collateralized Accounts

The first step to performing a liquidation is to identify under-collateralized accounts. Here's a suggested approach to finding under-collateralized accounts:

1. Create a record of account balances: To identify under-collateralized accounts efficiently, liquidators can maintain an off-chain mapping of accounts and balances by indexing market events to detect new positions and update existing ones:

   • Mint: Event emitted when tokens are minted.

   • Redeem: Event emitted when tokens are redeemed.

   • Borrow: Event emitted when underlying is borrowed.

   • RepayBorrow: Event emitted when a borrow is repaid. By listening to these events, liquidators can track changes in positions and update the balances of users accordingly.

Consider using a subgraph to index these events.

1. Get account balances: Use the vTokenBalancesAll function provided by PoolLens (VenusLens on the Core Pool) to retrieve supply and borrow balances for multiple vTokens associated with an account. This function takes an array of vTokens and the account address as parameters.

2. Get underlying asset prices: Use the vTokenUnderlyingPriceAll function provided by the PoolLens (VenusLens on the Core Pool) to retrieve the underlying asset prices for multiple vTokens. This function takes an array of vTokens as a parameter.

3. Calculate liquidity shortfall: With the supply and borrow balances obtained from step 2 and the underlying asset prices from step 3, calculate the liquidity shortfall for each account. This can be done by taking the scalar product of the balances and prices and comparing them against the LT values.

By following this approach, you can efficiently identify under-collateralized accounts based on the CF and LT calculations.

Performing the Liquidation

Once an under-collateralized account has been identified, the liquidation process can be initiated using either liquidateBorrow , liquidateAccount or healAccount function. liquidateBorrow is provided by the relevant vToken contract (Liquidator contract on the Core Pool) whereas liquidateAccount and healAccount are provided in Comptroller. Here's an overview of the steps involved:

1. Calculate the liquidation amount: Determine the amount of debt to be repaid and the collateral to be seized. This is typically calculated by examining the borrower's debt balance, the market's collateral factor, and any discounts or liquidation incentives offered.

2. When performing the liquidation, there are 3 different types of liquidations that can be called, taking in mind the collateral, minimum liquidatable collateral and solvency of the account:

• Collateral > minLiquidatableCollateral --> liquidateBorrow(): Call the liquidateBorrow function on the relevant vToken contract. This function requires several parameters, including the borrower's address, the liquidator's address, the amount of debt to be repaid, and the collateral to be seized. Refer to the vToken contract documentation for specific details on the function's required parameters.

• Collateral < minLiquidatableCollateral && account is solvent --> liquidateAccount(): this function liquidates all borrows of the borrower.

• Collateral < minLiquidatableCollateral && account is insolvent --> healAccount(): this function seizes all the remaining collateral from the borrower, requires the person initiating the liquidation (msg.sender) to repay the borrower's existing debt, and treats any remaining debt as bad debt. The sender has to repay a certain percentage of the debt, computed as collateral / (borrows * liquidationIncentive)

1. Handle liquidation results: After invoking liquidateBorrow, monitor the transaction's success and handle any resulting events or errors. Successful liquidations will transfer the seized collateral to the liquidator's address and repay the debt from the borrower's account.

Forced liquidations

Usually, accounts are only eligible to be liquidated if they are under-collateralized, as described in the previous sections. An exception is if "forced liquidations" are enabled for a market or an individual account in a market. In this case, borrow positions can be liquidated in that market even when the health rate of the account is greater than 1 (i.e. when the account is sufficiently collateralized). Additionally, the close factor check is ignored, allowing the liquidation of 100% of the debt in one transaction.

On Venus, forced liquidations can be enabled either for an entire market (all borrow positions in the market can be forcefully liquidated), or for individual accounts in a market (only the borrows of a particular account can be forcefully liquidated in the market).

To check if forced liquidations are enabled for an entire market, the function Comptroller.isForcedLiquidationEnabled(address vToken) can be called on the Comptroller contract of the pool with the address of the market. To check if forced liquidations are enabled for an individual account in the market, the function Comptroller.isForcedLiquidationEnabledForUser(address borrower, address vToken) can be used, providing the account and market address as arguments.

Force VAI Debt First

In the previous section, liquidations are carried out on all accounts without taking into consideration specific amounts of VAI debt. The forceVAILiquidate feature enhances the liquidation process by forcing liquidations of borrowers with VAI debt greater than minLiquidatableVAI. Forcing VAI liquidations allows the protocol to better manage risk and prevent potential losses due to excessive VAI debt accumulation.

For borrowers with outstanding VAI debt, the force VAI liquidation first includes checks to ensure that only eligible accounts are liquidated before starting the liquidation process.

Checks

1. Check that VAI liquidations are not paused in Comptroller.

2. The forceVAILiquidate flag is set to true.

3. Verify whether the borrower's VAI debt is greater than the minimum amount of liquidatable VAI (initially 1,000 VAI).

Automatic Income Allocation

In the Core Pool, liquidation income is transferred to the Liquidator contract in the form of vTokens. During a liquidation transaction, the Liquidator contract will try to redeem the protocol's portion of the liquidation incentive in vTokens for the underlying tokens. If the redemption process is successful, the underlying tokens will be sent to the ProtocolShareReserve contract. However, if the redemption fails the underlying tokens will be added to a list of pending redemptions and the Liquidator contract will try to redeem the pending redemptions again in subsequent liquidation transactions.

Distributing Seized Amount

The seized collateral is distributed between the Liquidator and the ProtocolShareReserve contract:

1. Liquidator's Share:

   • The Liquidator receives a designated portion of the collateral as an incentive.

2. ProtocolShareReserve contract's Share:

   • The remaining portion of the collateral is sent to the ProtocolShareReserve contract.

3. Conversion (if applicable):

   • BNB:

     • If the seized collateral is BNB, it is converted to Wrapped BNB (wBNB) before sending it to the ProtocolShareReserve contract.

   • Other VTokens:

     • For other VTokens, the underlying tokens are redeemed and transferred to the ProtocolShareReserve contract.

Redemption Handling

The Liquidator contract attempts to redeem the protocol's portion of the liquidation incentive in underlying tokens for the VTokens:

1. Successful Redemption:

   • If the redemption is successful, the underlying tokens are sent to the ProtocolShareReserve contract.

2. Failed Redemption:

   • If the redemption fails due to insufficient liquidity or other reasons, the VTokens representing the pending redemption are added to a list for later processing.

Pending Redemption Management

Subsequent liquidation transactions leverage the list of pending redemptions: during each liquidation, the Liquidator contract attempts to redeem pending VTokens for their underlying tokens, and send these underlying tokens to the ProtocolShareReserve contract.

Overview

The contracts under the Venus Protocol employ a system called Exponential.sol. This system uses exponential mathematics to represent fractional quantities with high precision.

Most numbers in this system are represented by a mantissa, an unsigned integer scaled by a factor of 1 * 10^18. This scaling ensures basic mathematical operations can be performed with a high degree of accuracy.

vToken and Underlying Decimals

Prices and exchange rates are adjusted according to the unique decimal scaling of each asset. vTokens, which are BEP-20 tokens, are scaled with 8 decimal places. However, their underlying tokens may have different decimal scaling, which is indicated by a public member called 'decimals'.

For further details, please refer to the respective token contract addresses.

Interpreting Exchange Rates

The exchange rate of vTokens is adjusted based on the decimal difference between the vToken and its underlying asset.

Here is an example illustrating how to determine the value of one vBUSD in BUSD using the Web3.js JavaScript library.

As BNB lacks an underlying contract, you must set the 'underlyingDecimals' to 18 when dealing with vBNB.

To calculate the number of underlying tokens that can be redeemed using vTokens, you should multiply the total amount of vTokens by the previously computed 'oneVTokenInUnderlying' value.

Calculating Accrued Interest

Interest rates for each market are updated in any block where there is a change in the ratio of borrowed assets to supplied assets. The magnitude of this change in interest rates depends on the interest rate model smart contract in place for the market, and the degree of change in the aforementioned ratio.

The accrual of interest to suppliers and borrowers in a market occurs when any wallet interacts with the market's vToken contract. This interaction could be any of the following functions: mint, redeem, borrow, or repay. A successful execution of any of these functions triggers the accrueInterest method, leading to the addition of interest to the underlying balance of every supplier and borrower in the market. Interest accrues for the current block, as well as any previous blocks where the accrueInterest method was not triggered due to lack of interaction with the vToken contract. Interest only accumulates during blocks where one of the aforementioned methods is invoked on the vToken contract.

Let's consider an example of supply interest accrual: Alice supplies 1 BNB to the Venus Protocol. At the time of her supply, the supplyRatePerBlock is 37893605 Wei, which equates to 0.000000000037893605 BNB per block. For 3 blocks, no interactions occur with the vBNB contract. On the subsequent 4th block, Bob borrows some BNB. As a result, Alice’s underlying balance is updated to 1.000000000151574420 BNB (calculated by multiplying 37893605 Wei by 4 blocks and adding the original 1 BNB). From this point onwards, the accrued interest on Alice’s underlying BNB balance will be based on the updated value of 1.000000000151574420 BNB, rather than the initial 1 BNB. It is important to note that the supplyRatePerBlock value may alter at any given time.

Calculating the APY Using Rate Per Block

The Annual Percentage Yield (APY) for either supplying or borrowing in each market can be computed using the supplyRatePerBlock (for Supply APY) or borrowRatePerBlock (for Borrow APY) values. These rates can be used in the following formula (assuming a daily compound):

Here is an example of calculating the supply and borrow APY with Web3.js JavaScript:

The NativeTokenGateway contract serves the purpose of facilitating seamless interaction with Wrapped Native Token markets, even for users who do not possess any Wrapped Native Tokens. It achieves this by allowing users to utilize the native currency in their wallets directly.

Overview

The Venus contracts deployed on the new networks do not directly support native currencies. For example on Ethereum instead of a native ether market there is a market for WETH. Wrapped Native Token markets address this limitation by facilitating the conversion of native currency into a format compatible with the ERC-20 standard.

To streamline user experience and eliminate the need for an additional transaction to convert native tokens into wrapped tokens, wrapping an unwrapping of native tokens is done behind the scenes when users interact with the market.

User Journey

The introduction of the NativeTokenGateway contract significantly enhances the user experience when interacting with wrapped native token markets. Unlike before, where users were required to have the wrapped native token to engage with markets, they now have the flexibility to choose between native currency or wrapped version for market interaction.

If the user opts for native currency, the following functions are executed to facilitate interaction with the protocol:

Approve Delegate

The updateDelegate function facilitates the granting or revocation of borrowing and redeeming delegate rights to or from an account. By invoking this function, borrowing delegate rights or redeeming delegate rights can be assigned to a specific address (delegate), enabling them to borrow or redeeming funds on behalf of the User.

This mechanism provides flexibility and control over borrowing and redeeming activities within the protocol, enhancing the overall efficiency and functionality of the system.

Interaction with the NativeTokenGateway contract

Supply (wrapAndSupply)

• The wrapAndSupply function is invoked sending the native currency, and the execution proceeds as follows:

  • Native currency is wrapped, providing the wrapped token.

  • VWrappedNative tokens are minted on behalf of the user.

  • VWrappedNative tokens are transferred to the user.

Redeem

1. redeemUnderlyingAndUnwrap

   • The user approves the NativeTokenGateway contract as the delegate.

   • The redeemUnderlyingAndUnwrap function is called with the amount of underlying tokens to redeem, and the execution proceeds as follows:

     • VWrappedNative tokens are redeemed by the NativeTokenGateway contract on behalf of the user.

     • Received wrapped native tokens are unwrapped to obtain native currency.

     • Native currency is transferred to the user.

2. redeemAndUnwrap

   • The user approves the NativeTokenGateway contract as the delegate.

   • The redeemAndUnwrap function is called with the amount of VWrappedNative tokens to redeem, and the execution proceeds as follows:

     • VWrappedNative tokens are redeemed by the NativeTokenGateway contract on behalf of the user.

     • Received wrapped native tokens are unwrapped to obtain native currency.

     • Native currency is transferred to the user.

Borrow (borrowAndUnwrap)

• The user approves the NativeTokenGateway contract as the delegate.

• The borrowAndUnwrap function is invoked, and the execution proceeds as follows:

  • Wrapped native tokens are borrowed on behalf of the user.

  • The borrowed wrapped native tokens are unwrapped to obtain native currency.

  • Native currency is transferred to the user.

Repay (wrapAndRepay)

• The wrapAndRepay function is invoked sending the native currency, and the execution proceeds as follows:

  • The native currency sent is wrapped, providing the wrapped native.

  • The NativeTokenGateway repays the debt on behalf of the user.

  • Any unused native currency for repayment is returned to the user.

DiamondConsolidated

This contract contains the functions defined in the different facets of the Diamond, plus the getters to the public variables. This contract cannot be deployed, due to its size. Its main purpose is to allow the easy generation of an ABI and the typechain to interact with the Unitroller contract in a simple way

Solidity API

Introduction

This guide provides step-by-step instructions on how to bridge XVS tokens from the BNB Chain to the Ethereum network.

Steps for Bridging XVS from BNB Chain to Ethereum

Step 1: Access the Venus Bridge

Step 2: Connect Your Wallet

• Click on the "Connect wallet" button in the top right corner of the Venus Bridge interface to connect your wallet.

Step 3: Configure the Bridge Transaction

• From: Ensure "BNB mainnet" is selected in the "From" dropdown menu.

• To: Select "Ethereum" in the "To" dropdown menu to set the destination network.

Step 4: Enter the Amount to Bridge

• Enter the amount of XVS you wish to transfer in the "Amount" field. You can also use the "MAX" button to transfer the total available balance.

• Check your "Wallet balance" to confirm you have sufficient XVS and BNB for gas fees.

Step 5: Approve XVS Token

• Before initiating the transfer, you must give the bridge contract permission to access your XVS tokens. Click on the "Approve XVS" button to do this.

• A wallet pop-up will request your confirmation for the approval. Confirm to proceed.

Step 6: Initiate the Transfer

• After approving XVS token usage, the interface will update to reflect the next step. Click the "Transfer" button (which replaces the "Approve XVS" button after approval) to initiate the bridging process.

• A confirmation pop-up will appear in your wallet for you to approve the transaction.

Step 7: Confirm and Wait

• Confirm the transaction in your wallet. The Venus Bridge interface will show the transaction as pending, indicating that it is being processed. This may take a few minutes.

Step 8: Transaction Completion

• Once the transaction is complete, the XVS tokens will be available in your Ethereum wallet.

Conclusion

Bridging XVS tokens from BNB Chain to Ethereum is made simple with the Venus Protocol. Remember to approve your tokens for use by the bridge and to check transaction details carefully before confirming to ensure a smooth bridging experience.

Overview

Risk fund

The risk fund concerns three main contracts:

• ProtocolShareReserve

• RiskFund

• ReserveHelpers

These three contracts are designed to hold funds that have been accumulated from interest reserves and liquidation incentives, send a portion to the protocol treasury, and send the remainder to the RiskFund contract. When reduceReserves() is called in a vToken contract, all accumulated liquidation fees and interests reserves are sent to the ProtocolShareReserve contract. Once funds are transferred to the ProtocolShareReserve, anyone can call releaseFunds() to transfer 50% to the protocolIncome address and the other 50% to the riskFund contract. Once in the riskFund contract, the tokens can be swapped via PancakeSwap pairs to the convertible base asset, which can be updated by the authorized accounts. When tokens are converted to the convertibleBaseAsset, they can be used in the Shortfall contract to auction off the pool's bad debt. Note that just as each pool is isolated, the risk funds for each pool are also isolated: only the associated risk fund for a pool can be used when auctioning off the bad debt of the pool.

Shortfall

When a borrower's shortfall (total borrowed amount converted to USD is greater than the total supplied amount converted to USD) is detected in a market in the Isolated Pools, Venus halts the interest accrual, writes off the borrower's balance, and tracks the bad debt.

Shortfall is an auction contract designed to auction off the convertibleBaseAsset accumulated in RiskFund. The convertibleBaseAsset is auctioned in exchange for users paying off the pool's bad debt. An auction can be started by anyone once a pool's bad debt has reached a minimum value (see Shortfall.minimumPoolBadDebt()). This value is set and can be changed by the authorized accounts. If the pool’s bad debt exceeds the risk fund plus a 10% incentive, then the auction winner is determined by who will pay off the largest percentage of the pool's bad debt. The auction winner repays the bid percentage of the bad debt in exchange for the entire risk fund. Otherwise, if the risk fund covers the pool's bad debt plus the 10% incentive, then the auction winner is determined by who will take the smallest percentage of the risk fund in exchange for paying off all the pool's bad debt.

The main configurable (via VIP) parameters in the Shortfall contract , and their initial values, are:

• minimumPoolBadDebt - Minimum USD bad debt in the pool to allow the initiation of an auction. Initial value set to 1,000 USD

• waitForFirstBidder - Blocks to wait for first bidder. Initial value sets to 100 blocks

• nextBidderBlockLimit - Time to wait for next bidder. Initial value set to 100 blocks

• incentiveBps - Incentive to auction participants. Initial value set to 1000 bps or 10%

Step-by-Step Guide

Step 1: Connect to ZKsync on Venus

2. Make sure you are connected to the ZKsync network. If you are not, switch your wallet’s network to ZKsync.

Step 2: Interact with the Venus Protocol

In this example, we will approve the use of the ZK market as collateral.

1. Navigate to the ZK market on Venus.

2. Click on "Collateral" to enable the use of this market as collateral.

Step 3: Sign the Transaction

1. Instead of sending a typical transaction, you will be prompted to sign a message. This step authorizes Zyfi to pay for the gas fee of the transaction on your behalf.

2. Sign the message in your wallet. The gas for the transaction will be covered by Zyfi Paymaster, so you don’t need ETH in your wallet.

3. Once signed, Zyfi processes the transaction, and it is sent to the ZKsync blockchain with gas paid through their vault.

Viewing the Transaction

The purpose of this document is to explain the technical details for distributing incomes generated by the Venus Protocol. The distributed incomes are generated from the spread of lending rates (borrow minus supply rates) and liquidations (part of the liquidation incentives). The distribution process for both the Core Pool and Isolated Pools as well as how the different amounts are allocated to different destinations based on specific rules and the approach for near-streaming income distribution are covered.

Income Distribution Schema

The Venus Protocol generates income from two main sources:

• Spread between the borrowing rate and the supply rate

• Part of the liquidation incentives

The initial distribution excludes VAI funds, which are kept in the VTreasury.

Streaming Income Distribution

The Venus Protocol aims to distribute accumulated reserves in the markets automatically and in near-real-time, leveraging transactions executed by users. This approach eliminates the need for external tools to manage the distribution process. The ProtocolShareReserve contract serves as the designated destination for liquidation incomes, allowing for tracking and distribution within the Venus Protocol.

Core Pool - Spread Income

Accumulated reserves in the Core Pool markets will be distributed after reaching a specified threshold. The threshold is based on the number of blocks since the last transfer of reserves. This strategy helps socialize part of the cost associated with distribution.

Core Pook - Liquidation Income

In the Core Pool, liquidation income is transferred to the Liquidator contract in the form of vTokens. During a liquidation transaction, the Liquidator contract will try to redeem the protocol's portion of the liquidation incentive in vTokens for the underlying tokens. If the redemption process is successful, the underlying tokens will be sent to the ProtocolShareReserve contract. However, if the redemption fails the underlying tokens will be added to a list of pending redemptions and the Liquidator contract will try to redeem the pending redemptions again in subsequent liquidation transactions.

Isolated Pool - Spread Income

Distribution of income generated by the interest rate spread in Isolated Pools is socialized and distributed periodically just like in the Core Pool

Isolated Pool - Liquidation Income

The Isolated Pools liquidations are managed by the VToken contracts. During a liquidation transaction, the protocol's percentage of the seized amount is transferred directly to the ProtocolShareReserve contract. No other action is required.

Distribution of Collected Incomes

The distribution of collected incomes is facilitated by the ProtocolShareReserve contract. It supports WBNB transfers but not BNB transfers. Therefore, BNB needs to be wrapped into WBNB before transferring to the ProtocolShareReserve contract.

updateAssetsState Function

The updateAssetsState function enables the transfer of funds to the ProtocolShareReserve contract. After transferring funds to the ProtocolShareReserve contract, the updateAssetsState function is invoked with the following parameters:

• address comptroller: The Comptroller where the market generated the income.

• address asset: The asset transferred to the ProtocolShareReserve.

• IncomeOrigin origin: The origin type, either "spread" or "liquidation."

Within the updateAssetsState function, the following steps are performed:

• Calculate the transferred balance, taking into account the previous balance of the asset.

• Assign the received amount to the appropriate entry (comptroller - asset - schema).

• Track the total balance of the received asset for future distribution.

releaseFunds Function

The releaseFunds function is responsible for distributing the accumulated funds to the different destinations. This function can be invoked by anyone and follows a two-step process:

1. Transfer the tokens to the destination addresses.

2. Invoke the updateAssetsState function in the receiver contract.

VBNBAdmin

VBNBAdmin contract is the admin of the vBNB vToken. All the other vToken contracts send revenue to PSR directly whereas vBNB sends the reserves to the admin i.e., the vBNBAdmin contract. This pattern is different for vBNB because it's not a upgradable contract.

Whenever the VBNBAdmin receives BNB from the vBNB contract it converts it to WBNB and then sends it to the Protocol share reserve contract.

To release the reserves of vBNB contract you need to call the reduceReserves() function of the VBNBAdmin contract.

Venus Protocol contracts are divided in these repositories:

Isolated Pools Contracts

There are 2 categories of isolated pools contracts:

• Pool

• Risk Management

Pool

Pool contracts can be divided into 4 categories:

• Configuration

• Logic

• Miscellaneous

Configuration

Configuration contracts are used to deploy, configure, and manage pools.

Logic contracts

Miscellaneous contracts

Isolated Pools use additional contracts such as lenses, rewards, ect.

Risk Management

Oracle Contracts

Oracles

Venus Protocol

Venus Protocol contracts can be grouped as follows:

• Lending

• Tokens

• Vault

• Lens

Lending Contracts

Token Contracts

Vault Contracts

XVS Vault

VAI Vault

Misc Contracts

ComptrollerLens

SnapshotLens

VenusLens

Governance Contracts

There are three main Governance contracts:

• GovernorBravoDelegate

• AccessControlManager

• Timelock

GovernorBravoDelegate

AccessControlManager

System Overview

Key features

1. VIP Types and Delays:

   • Provides three VIP options: Normal, Fast-track, and Critical.

   • Delays can be configured prior to remote execution on destination networks.

   • Normal VIPs have the greatest delays, whereas Critical VIPs have the smallest delays, indicating their urgency and importance.

2. Inter-chain communication:

   • LayerZero provides secure and reliable cross-chain messaging for remote execution commands.

3. Bridging:

   • Works with a bridge solution to deliver messages to destination networks.

   • Enables smooth interoperability between the BNB Chain and other supported networks.

   • Bridge configurations are flexible to accommodate various networks.

4. Guardian account:

   • Authorized by the ACM to revoke orders before they are executed on the target network.

   • Serves as a fail-safe mechanism, preventing unauthorized or incorrect commands from being performed.

5. Command limits and pausing:

   • Allows you to establish daily command restrictions for destination networks.

   • Adds pause/resume functionality for execution to temporarily halt operations in case of an emergency.

Detailed breakdown

1. Proposing and Voting:

   • Proposers send VIPs with BNB Chain commands and remote commands.

   • Voting takes place on the BNB Chain utilizing existing governance contracts.

   • Proposals are validated and approved according to predetermined criteria and threshold.

2. Remote Execution Flow:

   • Commands for destination networks generate a "Remote VIPs payload”

   • The payload is routed to the destination network using the bridge solution.

3. Delay Mechanism:

   • Remote execution has two delays: bridge delay and executor delay.

   • Bridge delay is the time it takes for the bridge to propagate a message to the target network, which is commonly measured in minutes.

   • Executor delay is the duration between the message's arrival on the target network and its execution, which is customizable dependent on VIP type (Normal, Fast-track, or Critical)

4. Execution and Expiry:

   • User-triggered execution occurs once both delays have passed, signaling the destination network's readiness to perform the orders via Timelock.

   • The Guardian account can cancel orders before they are executed, offering a safeguard against malicious or erroneous acts.

   • "Remote VIPs" become "Expired" if no execution happens within a set grace period, avoiding stale or outdated commands from being executed.

5. Command Restrictions:

   • VIPs can only include one set of commands per destination network to prevent duplication and conflicts.

   • Duplicate commands for the same network within a VIP are not permitted, ensuring consistent and reliable execution.

6. Executor-Side Features:

   • Sets a daily limit on the number of commands received per network.

   • Implements pause/resume functionality for the execute function in the target governance contract, enabling administrators to manage the system's operational state effectively.

Detailed overview of remote proposal execution (step-by-step)

1. Proposing a remote VIP on BNB Chain

• A proposer submits a VIP through the existing governance mechanism on the BNB Chain.

• The must VIP include a command invoking the OmnichainProposalSender::execute function which will send the remote VIP payload.

• The execute function takes four arguments:

  • payload: Encoded data (off-chain) containing the specific commands to be executed on the target network.

  • adapterParams: The params used to specify the custom amount of gas required for the execution on the destination encoded as (ethers.utils.solidityPack(['uint16','uint256'],[1, gasValue])).

  • zroPaymentAddress_: The address of the ZRO token holder who would pay for the transaction.

1. Eligibility checks and limits

Before sending the remote execution message, the system verifies eligibility based on predefined thresholds and limits. These restrictions ensure responsible resource allocation and prevent potential misuse.

1. Remote proposal ID generation

It's crucial to understand that the proposal ID for the remote execution on the destination network differs from the initial VIP ID proposed on the BNB Chain. This remote proposal ID starts from 1.

1. Message relay based on outcome

• Success: If the eligibility checks and limits are met, the encoded message (payload) is relayed across chains using the LayerZero bridge.

• Failure: If the checks fail, the system handles the situation differently based on the cause:

  • Insufficient Gas: The retryExecute function is used to attempt redelivering the message with potentially adjusted gas fees.

  • Logical Error or Check Failure: The fallbackWithdraw function removes the message from the queue, preventing further retries if the failure stems from inherent logic errors or failed eligibility checks.

1. Receiving and Queuing on the Destination Network

• Upon successful reception by the destination network's executor contract (OmnichainGovernanceExecutor), the remote proposal enters a "Queued" state.

• This queuing process applies additional eligibility checks specific to the receiving network, ensuring compliance with its governance rules and thresholds of commands limits.

1. Delay mechanism and execution

• Once the configured delay for the remote proposal type (Normal, Fast-track, Critical) elapses, the proposal becomes eligible for execution.

• Any user can then trigger the execution of the queued commands on the destination network.

1. Ownership and Access Control

• OmnichainProposalSender (BNB Chain):

  • Owned by: NormalTimelock contract on the BNB Chain.

  • Authorized callers: Timelocks (Normal, Critical, Fast-track) are authorized to call the execute function on this contract.

• OmnichainGovernanceExecutor (destination network):

  • Owned by: OmnichainExecutorOwner contract. This owner performs Access Control Manager (ACM) checks before allowing any function calls on this contract.

• TimelockV8:

  • Owned by: OmnichainGovernanceExecutor contract. This ownership grants TimelockV8 the authority to perform specific actions like queuing, canceling, and executing remote proposals.

Potential Failures and Retry Options

• If a VIP fails to send the proposal from source chain (BNB Chain) to destination network, the message will be saved and can be retried with the retryExecute function. This mechanism allows for the redelivery of the message with potentially adjusted gas fees to ensure successful execution.

• In case where the VIP fails to send the proposal from source chain (BNB Chain) to destination network due to non-retryable conditions and funds are stuck in the OmnichainProposalSender contract, funds can be withdrawn by invoking the fallbackWithdraw function. This ensures that funds are not permanently locked in the contract due to failed execution attempts.

• If a proposal's queueing fails on the destination network due to insufficient gas, the message will be saved and can be retried with the retryMessage function.

• If a proposal's queueing fails on the destination network due to reasons such as reaching caps or other constraints, the message will be saved and can be retried with the retryMessage function. This provides flexibility in addressing various failure scenarios and ensures that execution attempts are made until successful.

• If a proposal's queueing fails on the destination network because the contract has been paused, the message will be saved and can be retried with the retryMessage function after the contract has been unpaused.

Contracts overview

Contract 1: BaseOmnichainControllerSrc

Functionality

This contract serves as the framework for secure omnichain (cross-chain) communication. Its primary responsibilities include managing daily command limits and enabling pausing of controlled message transmission across chains.

Key features

1. Access Control Integration: Integrates an AccessControlManager contract to enforce access control for critical functions. This ensures that only authorised entities can execute commands, enhancing security.

2. Daily Command Limits: Establishes a per-chain limit on the number of commands that can be sent within a 24-hour window. This feature prevents potential abuse and maintains system stability.

3. Pausable: Implements a pausing mechanism, inherited from the OpenZeppelin Pausable contract. This functionality allows the contract owner to temporarily halt omnichain communication if necessary.

Architecture

• Inheritance: Extends the functionalities of the Ownable and Pausable contracts from OpenZeppelin, inheriting ownership management and pausing capabilities.

State variables

• accessControlManager (address): Stores the address of the AccessControlManager contract.

• chainIdToMaxDailyLimit (mapping): Maps chain IDs to their corresponding daily command limits.

• chainIdToLast24HourCommandsSent (mapping): Tracks the number of commands sent within the last 24 hours for each chain.

• chainIdToLast24HourWindowStart (mapping): Records the timestamp when the last 24-hour window for a chain began.

• chainIdToLastProposalSentTimestamp (mapping): maintains the timestamp of the last proposal sent to a specific chain to prevent sending multiple proposals within the same block.

Events

• SetMaxDailyLimit (event): Emitted when the daily command limit for a chain is modified.

• NewAccessControlManager (event): Triggered when the address of the AccessControlManager is updated.

Functions

• constructor(address accessControlManager_): Initializes the contract with the address of the AccessControlManager.

• setMaxDailyLimit(uint16 chainId_, uint256 limit_): Sets the maximum daily command limit for a specific chain ID. Requires permission from the AccessControlManager.

• pause(): Triggers the paused state, halting omnichain communication. Requires AccessControlManager permission.

• unpause(): Resumes omnichain communication from the paused state. Requires AccessControlManager permission.

• setAccessControlManager(address accessControlManager_): Updates the address of the AccessControlManager contract. Only callable by the contract owner.

• isEligibleToSend(uint16 dstChainId, uint256 noOfCommands_): Checks if sending the specified number of commands to the given chain is permissible based on daily limits and time windows.

• ensureAllowed(string memory functionSig): Ensures the caller has permission to execute a specific function, leveraging the AccessControlManager.

Contract 2: OmnichainProposalSender

Functionality

This contract facilitates cross-chain message transmission triggered by governor proposals on the main (BNB) chain. It sends proposal execution data to designated remote chains for processing.

Key features

• LayerZero Integration: Utilises the LayerZero communication protocol for efficient and reliable cross-chain message delivery.

• Remote Chain Management: Allows defining trusted remote contracts (receivers) on other chains using setTrustedRemoteAddress.

• Failed Message Handling: Stores the execution hashes of failed messages to facilitate resending or clearing them in case of insufficient fees or other issues.

• Security Measures: Enforces access control using the AccessControlManager for critical functions.

Architecture

• Inheritance: Inherits functionalities from both the ReentrancyGuard and BaseOmnichainControllerSrc contracts, providing reentrancy protection and foundational omnichain communication capabilities.

State variables

• proposalCount (uint256): Tracks the total number of remote proposals.

• storedExecutionHashes (mapping): Stores the execution hashes of failed messages for retry or clearing purposes.

• LZ_ENDPOINT (ILayerZeroEndpoint): Interface for interacting with the LayerZero communication protocol.

• trustedRemoteLookup (mapping): Maps remote chain IDs to trusted remote contract addresses for message transmission.

Events

• SetTrustedRemoteAddress (event): Triggered when a trusted remote address is set for a remote chain.

• TrustedRemoteRemoved (event): Emitted when a trusted remote address is removed from storage.

• ExecuteRemoteProposal (event): Indicates the execution of a proposal on a remote chain.

• ClearPayload (event): Signals the successful clearing of a previously failed message.

• StorePayload (event): Records the storage of an execution hash for a failed message, along with relevant details.

• FallbackWithdraw (event): Indicates a fallback withdrawal of funds in case of failed messages.

Functions

• constructor(ILayerZeroEndpoint lzEndpoint_, address accessControlManager_): Initializes the contract with the LayerZero endpoint and the address of the AccessControlManager.

• estimateFees(uint16 remoteChainId_, bytes calldata payload_, bytes calldata adapterParams_) : Estimates LayerZero fees for cross-chain message delivery based on payload and adapter parameters.

• execute(uint16 remoteChainId_, bytes calldata payload_, bytes calldata adapterParams_): Sends a message to execute a remote proposal, storing execution hashes if the message fails.

• retryExecute(...): Resends a previously failed message with potentially additional fees, ensuring reentrancy protection.

• fallbackWithdraw(...): Allows the owner to withdraw funds in case of failed messages.

• setTrustedRemoteAddress(uint16 remoteChainId_, bytes calldata newRemoteAddress_): Sets the remote message receiver address for a specified remote chain, requiring AccessControlManager permission.

• setConfig(uint16 version_, uint16 chainId_, uint256 configType_, bytes calldata config_): Sets the configuration of the LayerZero messaging library, controlled by the AccessControlManager.

• setSendVersion(uint16 version_): Sets the messaging library version, with permission from the AccessControlManager.

• getConfig(uint16 version_, uint16 chainId_, uint256 configType_): Retrieves the configuration of the LayerZero messaging library.

Contract 3: BaseOmnichainControllerDest

Functionality

This contract serves as the base for the Omnichain controller destination contract. It provides functionality related to daily command limits and pausing.

State variables

• maxDailyReceiveLimit (uint256): Maximum daily limit for receiving commands from BNB Chain.

• last24HourCommandsReceived (uint256): Total received commands within the last 24-hour window from BNB Chain.

• last24HourReceiveWindowStart (uint256): Timestamp when the last 24-hour window started from BNB Chain.

Events

• SetMaxDailyReceiveLimit (event): Emitted when the maximum daily limit for receiving commands from BNB Chain is modified.

Functions

• constructor(address endpoint_): Initializes the contract with the LayerZero endpoint address.

• setMaxDailyReceiveLimit(uint256 limit_): Sets the maximum daily limit for receiving commands. Only callable by the contract owner.

• pause(): Triggers the paused state of the controller. Only callable by the contract owner.

• unpause(): Triggers the resume state of the controller. Only callable by the contract owner.

• renounceOwnership(): Overrides the renounceOwnership function to prevent accidental renouncement of ownership.

• _isEligibleToReceive(uint256 noOfCommands_): Checks the eligibility to receive commands based on the daily limit and updates the state accordingly.

Contract 4: OmnichainGovernanceExecutor

Functionality

This contract executes proposal transactions sent from the main chain. It controls LayerZero configuration and implements a non-blocking behavior.

State variables

• GUARDIAN (address): A privileged role that can cancel any proposal.

• srcChainId (uint16): Stores the layerzero endpoint ID.

• lastProposalReceived (uint256): Last proposal count received.

• proposals (mapping): Official record of all proposals ever proposed.

• proposalTimelocks (mapping): Mapping containing Timelock addresses for each proposal type.

• queued (mapping): Represents the queue state of a proposal.

Events

• ProposalReceived (event): Emitted when a proposal is received.

• ProposalQueued (event): Emitted when a proposal is queued.

• ProposalExecuted (event): Emitted when a proposal is executed.

• ReceivePayloadFailed (event): Emitted when a payload receive fails.

• ProposalCanceled (event): Emitted when a proposal is canceled.

• TimelockAdded (event): Emitted when a Timelock is added.

• SetSrcChainId (event): Emitted when the source layer zero endpoint ID is updated.

• SetTimelockPendingAdmin (event): Emitted when pending admin of Timelock is updated.

• NewGuardian (event): Emitted when guardian of OmnichainGovernanceExecutor is updated.

Functions

• constructor(address endpoint_, address guardian_, uint16 srcChainId_): Initialises the contract with the LayerZero endpoint address, guardian address, and source chain ID.

• setSrcChainId(uint16 srcChainId_): Updates the source layerzero endpoint ID. Only callable by the contract owner.

• addTimelocks(ITimelock[] memory timelocks_): Adds Timelocks to the ProposalTimelocks mapping. Only callable by the contract owner.

• execute(uint256 proposalId_) : Executes a queued proposal if the ETA has passed.

• cancel(uint256 proposalId_): Cancels a proposal if the sender is the guardian and the proposal is not executed.

• state(uint256 proposalId_): Gets the state of a proposal.

• _blockingLzReceive(...) and _nonblockingLzReceive(...): Process LayerZero receive requests, with blocking and non-blocking behaviour respectively.

• _queue(uint256 proposalId_): Queues a proposal for execution.

• _queueOrRevertInternal(...): Checks for a unique proposal and queues it or reverts if already queued.

• setTimelockPendingAdmin(address pendingAdmin_, uint8 proposalType_): Sets the new pending admin of the Timelock.

• setGuardian(address newGuardian): Sets the new guardian of the OmnichainGovernanceExecutor.