Vault

The GeniusVault is the core contract of the Genius bridge protocol, serving as a cross-chain stablecoin bridge with sophisticated price-based deposit protection mechanisms. It enables users to bridge stablecoins across different blockchain networks while maintaining liquidity and protecting against stablecoin depegs through Chainlink price feed integration.

The vault acts as a liquidity pool that accepts stablecoin deposits from users and manages cross-chain order fulfillment. It implements a sophisticated fee system, price verification mechanisms, and liquidity management to ensure the protocol's stability and security.

The GeniusVault contract - overview

The GeniusVault contract is built on top of the GeniusVaultCore abstract contract, inheriting all the core functionality while adding specific vault-related features. It serves as the main entry point for users to create cross-chain orders and manages the protocol's liquidity pool.

The contract implements a dual-layer architecture where GeniusVaultCore handles the core logic (staking, order management, rebalancing) while GeniusVault adds vault-specific functionality like fee collection and insurance fee management.

The GeniusVault contract - key features

Cross-chain order creation

Users can create orders to bridge stablecoins across different blockchain networks. Each order specifies the source chain, destination chain, amounts, and recipient addresses. The vault validates all order parameters and ensures sufficient liquidity before accepting the order.

Price-based deposit protection

The vault integrates with Chainlink price feeds to monitor stablecoin prices in real-time. Before accepting any deposit, it verifies that the stablecoin price is within acceptable bounds (between stablePriceLowerBound and stablePriceUpperBound). This protects against stablecoin depegs and market volatility.

Sophisticated fee system

The contract implements a multi-tier fee structure:

• Insurance fees: Retained in the vault as additional liquidity to protect against reorgs and rebalancing fees

• Rest of fees: Transferred to the FeeCollector contract for distribution to protocol, LPs, and operators

Liquidity management

The vault maintains a minimum liquidity threshold based on the total staked assets and rebalance threshold. This ensures that sufficient liquidity is always available for order fulfillment while allowing excess liquidity to be used for cross-chain operations.

Order lifecycle management

Orders go through a complete lifecycle:

1. Created: Order is accepted and fees are collected

2. Filled: Order is executed on the destination chain

3. Reverted: Order is cancelled and funds are returned (if applicable)

Role-based access control

The contract implements comprehensive role management:

• Admin: Can configure all vault parameters and manage roles

• Pauser: Can pause/unpause the contract in emergencies

• Orchestrator: Can execute cross-chain operations and fill orders

Emergency controls

The contract includes pause functionality that can be activated by authorized pausers to halt all operations in emergency situations.

Understanding the workflow of GeniusVault

1. Initialization: The vault is initialized with stablecoin address, admin, multicall contract, price feed, and various thresholds.

2. Staking: Users can stake stablecoins to provide liquidity to the vault and receive gUSD tokens in return.

3. Order Creation: Users create cross-chain orders by calling createOrder() with the required parameters. The vault verifies the stablecoin price and validates all order parameters.

4. Fee Collection: When an order is created, fees are automatically collected and distributed:

   • Insurance fees are retained in the vault

   • Rest of the fees are transferred to the FeeCollector

5. Order Fulfillment: Orchestrators execute orders on destination chains by calling fillOrder() or fillOrderBatch().

6. Liquidity Rebalancing: Orchestrators can rebalance liquidity across chains using rebalanceLiquidity().

7. Unstaking: Users can withdraw their staked assets by burning their gUSD tokens.

Core functions and their purposes

Order Management

GeniusVault.sol

function createOrder(Order memory order) external payable virtual override whenNotPaused {
    // Check stablecoin price before accepting the order
    _verifyStablecoinPrice();

    // Validate order parameters
    if (order.trader == bytes32(0) || order.receiver == bytes32(0))
        revert GeniusErrors.NonAddress0();
    if (order.amountIn == 0 || order.amountIn <= order.fee || order.amountIn > maxOrderAmount)
        revert GeniusErrors.InvalidAmount();
    
    // Process fees and transfer stablecoins
    uint256 amountToTransfer = feeCollector.collectFromVault(
        orderHash_,
        order.amountIn,
        order.destChainId,
        order.fee
    );

    insuranceFeesAccumulated += order.fee - amountToTransfer;
    STABLECOIN.safeTransferFrom(msg.sender, address(this), order.amountIn);
    STABLECOIN.safeTransfer(address(feeCollector), amountToTransfer);

    orderStatus[orderHash_] = OrderStatus.Created;
}

Price Verification

GeniusVaultCore.sol

function _verifyStablecoinPrice() internal view returns (bool) {
    try stablecoinPriceFeed.latestRoundData() returns (
        uint80 roundId,
        int256 price,
        uint256 startedAt,
        uint256 updatedAt,
        uint80 answeredInRound
    ) {
        // Check for stale data
        if (block.timestamp - updatedAt > priceFeedHeartbeat)
            revert GeniusErrors.StalePrice(updatedAt);

        // Verify price is within bounds
        uint256 priceUint = uint256(price);
        if (priceUint < stablePriceLowerBound || priceUint > stablePriceUpperBound) {
            revert GeniusErrors.PriceOutOfBounds(priceUint);
        }

        return true;
    } catch {
        revert GeniusErrors.PriceFeedError();
    }
}

Liquidity Management

GeniusVault.sol

function minLiquidity() public view override returns (uint256) {
    uint256 _totalStaked = totalStakedAssets;
    uint256 reduction = (_totalStaked * rebalanceThreshold) / BASE_PERCENTAGE;
    uint256 minBalance = _totalStaked - reduction;
    return minBalance;
}

Staking Operations

GeniusVaultCore.sol

function stakeDeposit(uint256 amount, address receiver) external override whenNotPaused {
    if (amount == 0) revert GeniusErrors.InvalidAmount();
    if (receiver == address(0)) revert GeniusErrors.NonAddress0();

    totalStakedAssets += amount;
    STABLECOIN.safeTransferFrom(msg.sender, address(this), amount);
    _mint(receiver, amount);

    emit StakeDeposit(msg.sender, receiver, amount);
}

Security features

Price Feed Protection

The vault continuously monitors stablecoin prices through Chainlink feeds and rejects deposits when prices are outside acceptable bounds or when price data is stale.

Reentrancy Protection

All critical functions are protected against reentrancy attacks using OpenZeppelin's ReentrancyGuard.

Access Control

Comprehensive role-based access control ensures that only authorized addresses can perform sensitive operations.

Pause Mechanism

The contract can be paused in emergency situations to halt all operations and protect user funds.

Input Validation

Extensive input validation ensures that all parameters are within acceptable ranges and that addresses are valid.

Integration with other contracts

The GeniusVault interacts with several other contracts in the Genius ecosystem:

• FeeCollector: Manages protocol fee collection and distribution

• GeniusMulticall: Executes cross-chain operations and swaps

• Chainlink Price Feeds: Provides real-time stablecoin price data

• Stablecoin Contracts: The underlying stablecoin being bridged

Key state variables

• STABLECOIN: The stablecoin token being bridged

• totalStakedAssets: Total amount of stablecoins staked in the vault

• insuranceFeesAccumulated: Accumulated insurance fees retained in the vault

• stablePriceLowerBound / stablePriceUpperBound: Price bounds for stablecoin validation

• rebalanceThreshold: Threshold for liquidity rebalancing

• maxOrderAmount: Maximum amount allowed per order

Events

The contract emits various events to track important state changes:

• OrderCreated: When a new cross-chain order is created

• OrderFilled: When an order is successfully executed

• OrderReverted: When an order is cancelled and funds are returned

• StakeDeposit: When users stake stablecoins

• StakeWithdraw: When users withdraw their staked assets

• RebalancedLiquidity: When liquidity is rebalanced across chains

The GeniusVault is the cornerstone of the Genius bridge protocol, providing secure, efficient, and protected cross-chain stablecoin transfers while maintaining protocol stability through sophisticated liquidity and risk management mechanisms.