LTV protocol

LTV: Curatorless Leveraged Tokenized Vault with a Constant Target Loan-To-Value Ratio

Abstract:

The proposed system is a Curatorless Leveraged Tokenized Vault (LTV) with a Constant Target Loan-To-Value (LTV) ratio. This vault operates without a central curator and allows users to deposit and withdraw funds while receiving tokenized shares representing their holdings. The architec- ture is based on two interconnected EIP4626 vaults. To ensure alignment with the target LTV, an auction-based stimulus system is employed, which incentivizes users to participate in rebalancing actions through rewards or fees. This approach also integrates basic level of MEV protection to guard against frontrunning and maintain system integrity.

Ghost testnet

The LTV Vault is an implementation of an EIP-4626 vault designed for leveraging WETH (Wrapped ETH) deposits to generate yield over time. Users can deposit WETH, hold for a few months, and earn more WETH through a leveraged strategy utilizing the Magic ETH (MAE) token.

The vault borrows WETH and use MagicETH as collateral in the HodlMyBeer Lending protocol and follows the design principles outlined in the research paper: LTV: Curatorless Leveraged Tokenized Vault with a Constant Target Loan-To-Value Ratio

Components

LTV Vault

The LTV Vault is a smart contract that accepts WETH and MagicETH deposits. The vault borrows WETH and keeps MagicETH tokens as collateral in target LTV ratio in HodlMyBeer Lending Protocol. Users can deposit WETH and MagicETH into the vault and receive more WETH and MagicETH after a certain period.

Source code: LTV Vault

Ghost Testnet branch: ghost-testnet

Actual (v0.1.1) tag: ghost_v0.1.1

WETH (Wrapped Testnet ETH)

WETH is the wrapped version of ETH available on the Sepolia Testnet. Users can obtain testnet ETH from various faucets, such as:

User can tranform Sepolia ETH to WETH using the WETH contract

Magic ETH (MAE)

Magic ETH (MAE) is a testnet asset that mimics real-world Liquid Staking Tokens (LSTs) such as Rocket Pool ETH (rETH) or Lido Staked ETH (stETH). MAE accrues value over time, making it an effective asset for yield strategies.

Source code: Magic ETH

Spooky Oracle

The Spooky Oracle provides the real-time redemption price of Magic ETH (MAE) and feeds this data into the LTV Vault. It is maintained by the LTV Protocol Team to ensure accurate pricing for yield calculations and leverage adjustments.

Source code: Spooky Oracle

HodlMyBeer Lending Protocol

The HodlMyBeer Lending Protocol is a dummy lending system that supports an isolated WETH-to-MAE pool. The LTV Vault interacts with this protocol to borrow WETH and provide MagicETH as collateral and execute leveraged yield strategies.

Source code: HodlMyBeer Lending Protocol

How to Use

Obtain ETH from the Sepolia Testnet faucets.
Transform ETH to WETH using the WETH contract.
Deposit WETH into the LTV Vault.
Wait for the yield generation period to end.
Withdraw your WETH or MagicETH from the LTV Vault.

Pico UI

A minimal and lightweight frontend for interacting with the ghost testnet vaults.

Source code: https://github.com/ltvprotocol/pico_ui Detailed documentation: Pico UI Docs

Contract Addresses

Name	Source Code	Address
LTV Vault	Source code	0xe2a7f267124ac3e4131f27b9159c78c521a44f3c
Magic ETH	Source code	0x8f7b2044f9aa6fbf495c1cc3bde120df9032ae43
Spooky Oracle	Source code	0x6074d1d4022521147db1fad7bacc486b35a64df3
HodlMyBeer Lending Protocol	Source code	0x1dcd756db287354c4607d5d57621cdfb4456e2d4

Versions

v0.1.1

Actual (v0.1.1) tag: ghost_v0.1.1

Deployed contract implementation: 0x95fe6151ad668984b1c7b193866302b41b90887a

v0.1.0

Previous (v0.1.0) tag: ghost_v0.1.0

Deployed contract implementation: 0xeb81c4fe3d8e3c146a25bf9ea2309977071b6490

Pico UI

A minimal and lightweight frontend for interacting with the LTV Protocol testnet vaults.

Pico UI is a simple user interface designed to interact with vaults. It gives access to all main actions: deposit, mint, withdraw, redeem for borrow and collateral tokens. Also it shows balances and main vault information, creates possibility to convenient and simple interact with vaults.

Capabilities

Connect with any EIP-6963 compatible browser wallet (e.g., MetaMask, Trust Wallet, Rainbow, and others)
Deposit assets or mint shares with borrow/collateral tokens
Withdraw assets or redeem shares with borrow/collateral tokens
View real-time vault and transaction statuses

Deployed Testnet Version

https://testnet.ltv.finance

Release Versions

v0.0.3 - Fixes wallet duplication/loading & Sepolia switching issues View Release
v0.0.2 — Early testnet release with basic vault actions and initial UI improvements.
View Release
v0.0.1 — Initial stable release with basic vault interaction and wallet connection support.
View Release

Prerequisites

Node.js (v20 or later)

Setup

Clone the repository:

 git clone https://github.com/ltvprotocol/pico_ui.git

Go to directory:

 cd pico_ui

Install dependencies:

 npm install

Development

Start the development server:

npm run dev

The application will be available at http://localhost:5173

Building for Production

Build the application:

npm run build

The built files will be in the dist directory. You can deploy it to any static hosting provider (e.g., Vercel, Netlify, Cloudflare Pages).

Public ABI Description

EIP-4626 Standard (Borrow Vault)

EIP-4626 read methods/view function

totalAssets() → uint256
- Type: view
- Outputs: uint256 - The total amount of borrowed assets in the vault
- Description: This function returns the total borrowed assets in the vault, including real and future auction assets.
totalAssets(bool isDeposit) → uint256
- Type: view
- Inputs: isDeposit (bool) - Whether this is for deposit operations (true) or withdrawal operations (false)
- Outputs: uint256 - Returns the total amount of borrow assets managed by the vault
- Description: This function returns the total borrow assets with context-aware pricing. When isDeposit = true, uses optimistic pricing (rounds up collateral, rounds down borrow). When isDeposit = false, uses conservative pricing (rounds down collateral, rounds up borrow).
convertToShares(uint256 assets) → uint256
- Type: view
- Inputs: assets (uint256) - The amount of borrowed assets to convert
- Outputs: uint256 - The number of shares based on the assets
- Description: This function returns how many vault shares are obtained for a certain amount of borrowed assets.
convertToAssets(uint256 shares) → uint256
- Type: view
- Inputs: shares (uint256) - The number of shares to convert
- Outputs: uint256 - The amount of borrowed assets based on the shares
- Description: This function returns how many borrowed assets are obtained for a certain number of vault shares.
maxDeposit(address receiver) → uint256
- Type: view
- Inputs: receiver (address) - The address to check deposit limits
- Outputs: uint256 - The maximum amount of borrowed assets that can be deposited
- Description: The function returns the maximum borrowed assets that the receiver can deposit.
maxMint(address receiver) → uint256
- Type: view
- Inputs: receiver (address) - The address to check mint limits
- Outputs: uint256 - The maximum number of shares that can be minted for the receiver
- Description: This function shows the maximum vault shares that can be minted for the receiver.
maxWithdraw(address owner) → uint256
- Type: view
- Inputs: owner (address) - The address to check withdrawal limits
- Outputs: uint256 - The maximum amount of borrowed assets that can be withdrawn
- Description: This function returns the maximum borrowed assets the owner can withdraw.
maxRedeem(address owner) → uint256
- Type: view
- Inputs: owner (address) - The address to check redemption limits
- Outputs: uint256 - The maximum number of shares that can be redeemed
- Description: This function returns the maximum shares the owner can redeem.
previewDeposit(uint256 assets) → uint256
- Type: view
- Inputs: assets (uint256) - The amount of borrowed assets to deposit
- Outputs: uint256 - The estimated number of shares received
- Description: This function returns the estimates of how many vault shares you get for depositing a specified amount of borrowed assets.
previewMint(uint256 shares) → (uint256 assets)

Type: view
Inputs: shares (uint256) - The number of shares to mint
Outputs: uint256 - The estimated amount of borrowed assets needed
Description: This function returns the estimates of how many borrowed assets are needed to mint a specified number of shares.

previewWithdraw(uint256 assets) → (uint256 shares)
- Type: view
- Inputs: assets (uint256) - The amount of borrowed assets to withdraw
- Outputs: uint256 shares - The estimated number of shares to be burned
- Description: This function returns the estimates of how many shares must be burned to withdraw the specified amount of borrowed assets.
previewRedeem(uint256 shares) → (uint256 assets)
- Type: view
- Inputs: shares (uint256) - The number of shares to redeem
- Outputs: uint256 assets - The estimated amount of borrowed assets to be received
- Description: This function returns the estimates of how many borrowed assets to get for redeeming the specified number of shares.

EIP-4626 write methods

deposit(uint256 assets, address receiver) → uint256
- Type: impure
- Inputs:
  - assets (uint256) - The amount of borrowed assets to deposit
  - receiver (address) - The address to receive the minted shares
- Outputs: uint256 - The number of shares minted for the receiver
- Description: The function deposits borrowed assets and mints vault shares to the receiver. This may trigger rebalancing to maintain the target loan-to-value (LTV) ratio.
mint(uint256 shares, address receiver) → (uint256 assets)
- Type: impure
- Inputs:
  - shares (uint256) - The number of shares to mint
  - receiver (address) - The address to receive the minted shares
- Outputs: uint256 - The amount of borrowed assets used to mint the shares
- Description: This function mints vault shares in exchange for borrowed assets. The required asset amount is calculated based on current exchange rates.
withdraw(uint256 assets, address receiver, address owner) → uint256

Type: impure
Inputs:
- assets (uint256) - The amount of borrowed assets to withdraw
- receiver (address) - The address to receive the withdrawn assets
- owner (address) - The address whose shares will be burned
Outputs: uint256 - The number of shares burned from the owner
- Description: This function withdraws borrowed assets by burning shares from the owner and transferring the assets to the receiver.

redeem(uint256 shares, address receiver, address owner) → (uint256 assets)

Type: impure
Inputs:
- shares (uint256) - The number of shares to redeem
- receiver (address) - The address to receive the withdrawn assets
- owner (address) - The address whose shares will be burned
Outputs: uint256 assets - The amount of borrowed assets transferred to the receiver
Description: This function redeems shares and transfers the corresponding borrowed assets.

EIP-4626 Collateral Extension

EIP-4626 read methods/view function

maxDepositCollateral(address receiver) → uint256
- Type: view
- Inputs: receiver (address) - The address to check for how much collateral can be deposited.
- Outputs: uint256 - The maximum amount of collateral that can be deposited.
- Description: This function returns the maximum collateral assets the receiver can deposit.
maxMintCollateral(address receiver) → uint256
- Type: view
- Inputs: receiver (address) - The address to check for how much collateral can be minted.
- Outputs: uint256 - The maximum number of collateral shares that can be minted.
- Description: This function returns how many collateral shares can be minted for the receiver.
maxRedeemCollateral(address owner) → uint256
- Type: view
- Inputs: owner (address) - The address to check for how much collateral can be redeemed.
- Outputs: uint256 - The maximum number of collateral shares that can be redeemed.
- Description: This function returns how many collateral shares the owner can redeem.
maxWithdrawCollateral(address owner) → uint256
- Type: view
- Inputs: owner (address) - The address to check for how much collateral can be withdrawn.
- Outputs: uint256 - The maximum amount of collateral assets that can be withdrawn.
- Description: This function returns the maximum collateral assets the owner can withdraw.
previewDepositCollateral(uint256 collateralAssets) → uint256
- Type: view
- Inputs: collateralAssets (uint256) - The amount of collateral assets to deposit.
- Outputs: uint256 - The estimated number of collateral shares to receive.
- Description: This function estimates how many collateral shares to get for depositing a specific amount of collateral assets.
previewMintCollateral(uint256 shares) → (uint256 collateralAssets)
- Type: view
- Inputs: shares (uint256) - The number of collateral shares to mint.
- Outputs: uint256 - The estimated amount of collateral assets needed.
- Description: This function estimates how much collateral is required to mint a specific number of shares.
previewRedeemCollateral(uint256 shares) → (uint256 assets)
- Type: view
- Inputs: shares (uint256) - The number of collateral shares to redeem.
- Outputs: uint256 assets - The estimated amount of collateral assets to receive.
- Description: This function returns an estimate of how much collateral to get for redeeming a specific number of shares.
previewWithdrawCollateral(uint256 assets) → (uint256 shares)
- Type: view
- Inputs: assets (uint256) - The amount of collateral assets to withdraw.
- Outputs: uint256 shares - The estimated number of collateral shares that will be burned.
- Description: This function returns the estimated number of collateral shares that need to be burned to withdraw a specific amount of collateral assets.
totalAssetsCollateral() → uint256
- Type: view
- Outputs: uint256 - The total amount of collateral assets managed by the vault.
- Description: This function returns the total collateral assets in the vault using conservative pricing (isDeposit = false).
totalAssetsCollateral(bool isDeposit) → uint256
- Type: view
- Inputs: isDeposit (bool) - Whether this is for a deposit operation (true) or withdrawal operation (false).
- Outputs: uint256 - The total amount of collateral assets managed by the vault.
- Description: This function returns the total collateral assets with context-aware pricing. Use isDeposit = true for deposit operations (optimistic pricing) and isDeposit = false for withdrawal operations (conservative pricing).

EIP-4626 write methods

depositCollateral(uint256 collateralAssets, address receiver) → uint256
- Type: impure
- Inputs:
  - collateralAssets (uint256) - The amount of collateral assets to deposit.
  - receiver (address) - The address to receive the minted collateral shares.
- Outputs: uint256 - The number of collateral shares minted to the receiver.
- Description: This function deposits collateral assets and mints collateral shares to the receiver.
mintCollateral(uint256 shares, address receiver) → (uint256 collateralAssets)
- Type: impure
- Inputs:
  - shares (uint256) - The number of collateral shares to mint.
  - receiver (address) - The address to receive the minted shares.
- Outputs: uint256 collateralAssets - The amount of collateral assets used to mint the shares.
- Description: This function mints collateral shares in exchange for collateral assets.
withdrawCollateral(uint256 collateralAssets, address receiver, address owner) → uint256
- Type: impure
- Inputs:
  - collateralAssets (uint256) - The amount of collateral assets to withdraw.
  - receiver (address) - The address to receive the withdrawn collateral assets.
  - owner (address) - The address whose collateral shares will be burned.
- Outputs: uint256 - The number of collateral shares burned from the owner.
- Description: This function withdraws collateral assets by burning collateral shares from the owner.
redeemCollateral(uint256 shares, address receiver, address owner) → (uint256 collateralAssets)
- Type: impure
- Inputs:
  - shares (uint256) - The number of collateral shares to redeem.
  - receiver (address) - The address to receive the withdrawn collateral assets.
  - owner (address) - The address whose collateral shares will be burned.
- Outputs: uint256 collateralAssets - The amount of collateral assets transferred to the receiver.
- Description: This function redeems collateral shares and transfers the corresponding collateral assets to the receiver.

ERC-20 Standard

ERC-20 read methods/view function

balanceOf(address owner) → uint256
- Type: view
- Inputs: owner (address) - The address to check the balance for.
- Outputs: uint256 - The token balance of the owner.
- Description: This function returns the vault share token balance of the specified address.
totalSupply() → uint256
- Type: view
- Outputs: uint256 - The total supply of vault share tokens.
- Description: This function returns the total supply of vault share tokens.
decimals() → uint8
- Type: view
- Outputs: uint8 - The number of decimal places for the token.
- Description: This function returns the number of decimal places for the vault share token.
name() → string
- Type: view
- Outputs: string - The token name.
- Description: This function returns the name of the vault share token.
symbol() → string
- Type: view
- Outputs: string - The token symbol.
- Description: This function returns the symbol of the vault share token.
allowance(address owner, address spender) → uint256
- Type: view
- Inputs:
  - owner (address) - The token owner address.
  - spender (address) - The spender address.
- Outputs: uint256 - The remaining allowance amount.
- Description: This function returns the remaining number of tokens that spender can use on behalf of the owner.

ERC-20 write methods

approve(address spender, uint256 amount) → bool
- Type: impure
- Inputs:
  - spender (address) - The address to approve for spending.
  - amount (uint256) - The amount of tokens to approve.
- Outputs: bool - The success status.
- Description: This function approves the spender to use an amount of tokens on behalf of the caller.
transfer(address recipient, uint256 amount) → bool
- Type: impure
- Inputs:
  - recipient (address) - The address to transfer tokens to.
  - amount (uint256) - The amount of tokens to transfer.
- Outputs: bool - The success status.
- Description: This function transfers amount tokens to the recipient.
transferFrom(address sender, address recipient, uint256 amount) → bool
- Type: impure
- Inputs:
  - sender (address) - The address to transfer tokens from.
  - recipient (address) - The address to transfer tokens to.
  - amount (uint256) - The amount of tokens to transfer.
- Outputs: bool - The success status.
- Description: This function transfers amount tokens from sender to recipient using allowance.

Auction System

Auction read methods/view function

startAuction() → uint256
- Type: view
- Outputs: uint256 - The timestamp when the auction started.
- Description: This function returns the timestamp when the current auction started, or 0 if no auction is active.
previewExecuteAuctionBorrow(int256 deltaUserBorrowAssets) → int256
- Type: view
- Inputs: deltaUserBorrowAssets (int256) - The change in user borrow assets (positive to receive, negative to provide).
- Outputs: int256 - The estimated amount of borrow assets user needs to give/receive.
- Description: This function estimates the amount of borrow assets a user needs to give or receive to execute the auction with the specified delta.
previewExecuteAuctionCollateral(int256 deltaUserCollateralAssets) → int256
- Type: view
- Inputs: deltaUserCollateralAssets (int256) - The change in user collateral assets (positive to receive, negative to provide).
- Outputs: int256 - The estimated amount of collateral assets user needs to give/receive.
- Description: This function estimates the amount of collateral assets a user needs to give or receive to execute the auction with the specified delta.

Auction write methods

executeAuctionBorrow(int256 deltaUserBorrowAssets) → int256
- Type: impure
- Inputs: deltaUserBorrowAssets (int256) - The change in user borrow assets (positive to receive, negative to provide).
- Outputs: int256 - The actual amount of borrow assets transferred.
- Description: This function executes an auction for borrow assets, allowing users to participate in rebalancing for rewards.
executeAuctionCollateral(int256 deltaUserCollateralAssets) → int256
- Type: impure
- Inputs: deltaUserCollateralAssets (int256) - The change in user collateral assets (positive to receive, negative to provide).
- Outputs: int256 - The actual amount of collateral assets transferred.
- Description: This function executes an auction for collateral assets, allowing users to participate in rebalancing for rewards.

Low level rebalance

Low level rebalance read methods/view function

previewLowLevelRebalanceShares(int256 deltaShares) → (int256 deltaCollateral, int256 deltaBorrow)
- Type: view
- Inputs: deltaShares (int256) - The amount of shares to mint or burn (positive for mint).
- Outputs:
  - deltaCollateral (int256) - The amount of collateral assets user will receive or provide.
  - deltaBorrow (int256) - The amount of borrow assets user will receive or provide.
- Description: This function previews low level rebalance execution with input in shares. Positive deltaShares mints shares, negative burns shares.
previewLowLevelRebalanceBorrow(int256 deltaBorrowAssets) → (int256 deltaCollateral, int256 deltaShares)
- Type: view
- Inputs: deltaBorrowAssets (int256) - The amount of borrow assets to withdraw or deposit (negative to send borrow assets).
- Outputs:
  - deltaCollateral (int256) - The amount of collateral assets user will receive or provide.
  - deltaShares (int256) - The amount of shares user will receive or burn.
- Description: This function previews low level rebalance execution with input in borrow assets. Negative deltaCollateral means protocol sends collateral to user, positive means user provides collateral. Positive deltaShares means user receives shares, negative means shares are burned.
previewLowLevelRebalanceCollateral(int256 deltaCollateralAssets) → (int256 deltaBorrow, int256 deltaShares)
- Type: view
- Inputs: deltaCollateralAssets (int256) - The amount of collateral assets to withdraw or deposit (positive to send collateral assets).
- Outputs:
  - deltaBorrow (int256) - The amount of borrow assets user will receive or provide.
  - deltaShares (int256) - The amount of shares user will receive or burn.
- Description: This function previews low level rebalance execution with input in collateral assets. Positive deltaBorrow means protocol sends borrow assets to user, negative means user provides borrow assets.
previewLowLevelRebalanceBorrowHint(int256 deltaBorrowAssets, bool isSharesPositiveHint) → (int256 deltaCollateral, int256 deltaShares)
- Type: view
- Inputs:
  - deltaBorrowAssets (int256) - The amount of borrow assets to withdraw or deposit (negative to send borrow assets).
  - isSharesPositiveHint (bool) - The hint indicating if user expects to mint shares (saves gas).
- Outputs:
  - deltaCollateral (int256) - The amount of collateral assets user will receive or provide.
  - deltaShares (int256) - The amount of shares user will receive or burn.
- Description: This function is the same as previewLowLevelRebalanceBorrow but with a hint to optimize gas usage.
previewLowLevelRebalanceCollateralHint(int256 deltaCollateralAssets, bool isSharesPositiveHint) → (int256 deltaBorrow, int256 deltaShares)
- Type: view
- Inputs:
  - deltaCollateralAssets (int256) - The amount of collateral assets to withdraw or deposit (positive to send collateral assets).
  - isSharesPositiveHint (bool) - The hint indicating if user expects to mint shares (saves gas).
- Outputs:
  - deltaBorrow (int256)- The amount of borrow assets user will receive or provide.
  - deltaShares (int256) - The amount of shares user will receive or burn.
- Description: This function is the same as previewLowLevelRebalanceCollateral but with a hint to optimize gas usage.
maxLowLevelRebalanceShares() → int256
- Type: view
- Outputs: int256 - The maximum amount of shares that can be minted or burned in low level rebalance.
- Description: This function returns the maximum amount of shares that can be minted (positive) or burned (negative) in a low level rebalance operation.
maxLowLevelRebalanceBorrow() → int256
- Type: view
- Outputs: int256 - The maximum amount of borrow assets that can be used in low level rebalance.
- Description: This function returns the maximum amount of borrow assets that can be withdrawn (positive) or deposited (negative) in a low level rebalance operation.
maxLowLevelRebalanceCollateral() → int256
- Type: view
- Outputs: int256 - The maximum amount of collateral assets that can be used in low level rebalance.
- Description: This function returns the maximum amount of collateral assets that can be withdrawn (positive) or deposited (negative) in a low level rebalance operation.

Low level rebalance write methods

executeLowLevelRebalanceBorrow(int256 deltaBorrowAssets) → (int256, int256)
- Type: impure
- Inputs: deltaBorrow (int256) - The amount of borrow assets to withdraw or deposit (negative to send borrow assets).
- Outputs:
  - int256 - The amount of collateral assets transferred.
  - int256 - The amount of shares minted or burned.
- Description: This function executes low level rebalance with input in borrow assets. This is a core rebalancing function that maintains the target LTV ratio.
executeLowLevelRebalanceCollateral()(int256 deltaCollateralAssets) → (int256, int256)
- Type: impure
- Inputs: deltaCollateral (int256) - The amount of collateral assets to withdraw or deposit (positive to send collateral assets).
- Outputs:
  - int256 - The amount of borrow assets transferred.
  - int256 - The amount of shares minted or burned.
- Description: This function executes low level rebalance with input in collateral assets.
executeLowLevelRebalanceShares(int256 deltaShares) → (int256, int256)
- Type: impure
- Inputs: deltaShares (int256) - The amount of shares to mint or burn (positive for mint).
- Outputs:
  - int256 - The amount of collateral assets transferred.
  - int256 - The amount of borrow assets transferred.
- Description: This function executes low level rebalance with input in shares.
executeLowLevelRebalanceBorrowHint(int256 deltaBorrow, bool isSharesPositiveHint) → (int256, int256)
- Type: impure
- Inputs:
  - deltaBorrow (int256) - The amount of borrow assets to withdraw or deposit (negative to send borrow assets).
  - isSharesPositiveHint (bool) - The hint indicating if user expects to mint shares.
- Outputs:
  - int256 - The amount of collateral assets transferred.
  - int256 - The amount of shares minted or burned.
- Description: This function is the same as executeLowLevelBorrow, but with a hint to optimize gas usage.
executeLowLevelRebalanceCollateralHint(int256 deltaCollateral, bool isSharesPositiveHint) → (int256, int256)
- Type: impure
- Inputs:
  - deltaCollateral (int256) - The amount of collateral assets to withdraw or deposit (positive to send collateral assets).
  - isSharesPositiveHint (bool) - The hint indicating if user expects to mint shares.
- Outputs:
  - int256 - The amount of borrow assets transferred.
  - int256 - The amount of shares minted or burned.
- Description: This function is the same as executeLowLevelCollateral but with a hint to optimize gas usage.

State Representation

State read methods/view function

borrowToken() → address
- Type: view
- Outputs: address - The borrow token contract address.
- Description: This function returns the address of the borrow token (e.g., USDC, DAI).
collateralToken() → address
- Type: view
- Outputs: address - The collateral token contract address.
- Description: This function returns the address of the collateral token (e.g., ETH, WBTC).
futureBorrowAssets() → int256
- Type: view
- Outputs: int256 - The current auction borrow assets.
- Description: This function returns the current amount of borrow assets in the auction system.
futureCollateralAssets() → int256
- Type: view
- Outputs: int256 - The current auction collateral assets.
- Description: This function returns the current amount of collateral assets in the auction system.
futureRewardBorrowAssets() → int256
- Type: view
- Outputs: int256 - The current auction reward in borrow assets.
- Description: This function returns the current auction reward denominated in borrow assets.
futureRewardCollateralAssets() → int256
- Type: view
- Outputs: int256 - The current auction reward in collateral assets.
- Description: This function returns the current auction reward denominated in collateral assets.
getRealBorrowAssets(bool isDeposit) → uint256
- Type: view
- Inputs: isDeposit (bool) - Whether this is for deposit operations (true) or withdrawal operations (false).
- Outputs: uint256 - The protocol's current debt in lending protocol.
- Description: This function returns the protocol's current debt position in the underlying lending protocol in borrow assets with context-aware pricing.
getRealCollateralAssets(bool isDeposit) → uint256
- Type: view
- Inputs: isDeposit (bool) - Whether this is for deposit operations (true) or withdrawal operations (false).
- Outputs: uint256 - The protocol's current collateral in lending protocol.
- Description: This function returns the protocol's current collateral position in the underlying lending protocol in collateral assets with context-aware pricing.
maxSafeLTV() → uint128
- Type: view
- Outputs: uint128 - The maximum safe loan-to-value ratio.
- Description: This function returns the maximum safe LTV ratio that the protocol will maintain.
maxTotalAssetsInUnderlying() → uint256
- Type: view
- Outputs: uint256 - The protocol top border in underlying oracle assets.
- Description: This function returns the maximum total assets the protocol can manage in underlying oracle assets.
minProfitLTV() → uint128
- Type: view
- Outputs: uint128 - The minimum profitable LTV.
- Description: This function returns the minimum profitable LTV ratio for the protocol.
targetLTV() → uint128
- Type: view
- Outputs: uint128 - The target loan-to-value ratio.
- Description: This function returns the target LTV ratio that the protocol aims to maintain.
oracleConnector() → address
- Type: view
- Outputs: address - The oracle connector address.
- Description: This function returns the address of the oracle connector that provides price feeds.
lendingConnector() → address
- Type: view
- Outputs: address - The lending protocol connector address.
- Description: This function returns the address of the lending protocol connector (e.g., Aave V3, Morpho Blue).
feeCollector() → address
- Type: view
- Outputs: address - The fee collector address.
- Description: This function returns the address that receives protocol fees.
baseTotalSupply() → uint256
- Type: view
- Outputs: uint256 - The base total supply of vault shares.
- Description: This function returns the base total supply of vault shares, excluding any growth fees.
maxGrowthFee() → uint256
- Type: view
- Outputs: uint256 - The maximum growth fee percentage.
- Description: This function returns the maximum growth fee that can be charged by the protocol.
lastSeenTokenPrice() → uint256
- Type: view
- Outputs: uint256 - The last seen token price from the oracle.
- Description: This function returns the most recent token price observed from the oracle connector.
isDepositDisabled() → bool
- Type: view
- Outputs: bool - Whether deposits are currently disabled.
- Description: This function returns true if deposit functionality is currently disabled by the guardian.
isWithdrawDisabled() → bool
- Type: view
- Outputs: bool - Whether withdrawals are currently disabled.
- Description: This function returns true if withdrawal functionality is currently disabled by the guardian.
isWhitelistActivated() → bool
- Type: view
- Outputs: bool - Whether the whitelist is currently activated.
- Description: This function returns true if the whitelist functionality is currently active.
getLendingConnector() → address
- Type: view
- Outputs: address - The lending protocol connector contract address.
- Description: This function returns the address of the lending protocol connector that handles lending operations.
maxDeleverageFee() → uint256
- Type: view
- Outputs: uint256 - The maximum deleverage fee percentage.
- Description: This function returns the maximum fee charged when users deleverage their positions.

Ownership

Ownership read methods/view function

owner() → address
- Type: view
- Outputs: address - The current owner address.
- Description: This function returns the address of the current contract owner.
governor() → address
- Type: view
- Outputs: address - The current governor address.
- Description: This function returns the address of the current governor who can modify protocol parameters.
guardian() → address
- Type: view
- Outputs: address - The current guardian address.
- Description: This function returns the address of the current guardian who can disable functions and perform emergency actions.
emergencyDeleverager() → address
- Type: view
- Outputs: address - The current emergency deleverager address.
- Description: This function returns the address of the emergency deleverager who can perform emergency deleveraging operations.

Ownership write methods

transferOwnership(address newOwner)
- Type: impure
- Inputs: newOwner (address) - The new owner address.
- Description: This function transfers contract ownership to the new owner.
renounceOwnership()
- Type: impure
- Description: This function renounces ownership of the contract, making it ownerless.
initialize(StateInitData memory stateInitData, IModules modules)
- Type: impure
- Inputs:
  - stateInitData (StateInitData) - Initial state configuration data including target LTV, max safe LTV, min profit LTV, and other parameters.
  - modules (IModules) - The modules interface containing vault modules and connectors.
- Description: This function initializes the LTV vault with the provided state data and modules. Can only be called once during deployment.

Administration

Administration write methods

setTargetLTV(uint128 value)
- Type: impure
- Inputs: value (uint128) - The new target LTV value.
- Description: This function sets the protocol's new target LTV ratio (governor only).
setMaxSafeLTV(uint128 value)
- Type: impure
- Inputs: value (uint128) - The new max safe LTV value.
- Description: This function sets the protocol's new maximum safe LTV ratio (governor only).
setMinProfitLTV(uint128 value)
- Type: impure
- Inputs: value (uint128) - The new min profit LTV value.
- Description: This function sets the protocol's new minimum profitable LTV ratio (governor only).
setFeeCollector(address _feeCollector)
- Type: impure
- Inputs: _feeCollector (address) - The new fee collector address.
- Description: This function sets the protocol's new fee collector address (governor only).
setMaxTotalAssetsInUnderlying(uint256 _maxTotalAssetsInUnderlying)
- Type: impure
- Inputs: _maxTotalAssetsInUnderlying (uint256) - The new maximum total assets value.
- Description: This function sets the protocol's maximum total assets in underlying oracle assets (governor only).
setMaxDeleverageFee(uint256 value)
- Type: impure
- Inputs: value (uint256) - The new max deleverage fee value.
- Description: This function sets the protocol's maximum deleverage fee (governor only).
setIsWhitelistActivated(bool activate)
- Type: impure
- Inputs: activate (bool) - Whether to activate the whitelist.
- Description: This function activates or deactivates the whitelist functionality (governor only).
setWhitelistRegistry(address value)
- Type: impure
- Inputs: value (IWhitelistRegistry) - The new whitelist registry address.
- Description: This function sets the protocol's whitelist registry address (governor only).
setSlippageProvider(ISlippageProvider _slippageProvider)
- Type: impure
- Inputs: _slippageProvider (ISlippageProvider) - The new slippage provider address.
- Description: This function sets the protocol's slippage provider address (governor only).
allowDisableFunctions(bytes4[] memory signatures, bool isDisabled)
- Type: impure
- Inputs:
  - signatures (bytes4[]) - Array of function signatures to enable/disable.
  - isDisabled (bool) - Whether to disable the functions.
- Description: This function allows the guardian to disable or enable specific functions (guardian only).
setMaxGrowthFee(uint256 _maxGrowthFee)
- Type: impure
- Inputs: _maxGrowthFee (uint256) - The new max growth fee value.
- Description: This function sets the protocol's maximum growth fee (governor only).
setModules(IModules _modules)
- Type: impure
- Inputs: _modules (IModules) - The new modules provider address.
- Description: This function sets the modules provider address (owner only).
setIsDepositDisabled(bool value)
- Type: impure
- Inputs: value (bool) - Whether to disable deposits.
- Description: This function disables or enables deposit functionality (guardian only).
setIsWithdrawDisabled(bool value)
- Type: impure
- Inputs: value (bool) - Whether to disable withdrawals.
- Description: This function disables or enables withdrawal functionality (guardian only).
setLendingConnector(address _lendingConnector)
- Type: impure
- Inputs: _lendingConnector (address) - The new lending connector address.
- Description: This function sets the lending protocol connector address (owner only).
setOracleConnector(address _oracleConnector)
- Type: impure
- Inputs: _oracleConnector (address) - The new oracle connector address.
- Description: This function sets the oracle connector address (owner only).
deleverageAndWithdraw(uint256 closeAmountBorrow, uint256 deleverageFee)
- Type: impure
- Inputs:
  - closeAmountBorrow (uint256) - The amount of borrow assets to close.
  - deleverageFee (uint256) - The deleverage fee to charge.
- Description: This function performs emergency deleveraging and withdrawal of all assets (emergency deleverager only).
updateEmergencyDeleverager(address newEmergencyDeleverager)
- Type: impure
- Inputs: newEmergencyDeleverager (address) - The new emergency deleverager address.
- Description: This function updates the emergency deleverager address (owner only).
updateGovernor(address newGovernor)
- Type: impure
- Inputs: newGovernor (address) - The new governor address.
- Description: This function updates the governor address (owner only).
updateGuardian(address newGuardian)
- Type: impure
- Inputs: newGuardian (address) - The new guardian address.
- Description: This function updates the guardian address (owner only).

Function control

_isFunctionDisabled(bytes4 signature) → bool
- Type: view
- Inputs: signature (bytes4) - The function signature to check.
- Outputs: bool - Whether the function is disabled.
- Description: This function returns true if the specified function signature is currently disabled.
allowDisableFunctions(bytes4[] memory signatures, bool isDisabled)
- Type: impure
- Inputs:
  - signatures (bytes4[]) - Array of function signatures to enable/disable.
  - isDisabled (bool) - Whether to disable the functions.
- Description: This function allows the guardian to disable or enable specific functions (guardian only).

Events

EIP-4626 Events

Deposit(address indexed sender, address indexed owner, uint256 assets, uint256 shares)
- Description: This event is emitted when borrow assets are deposited and shares are minted.
- Parameters:
  - sender (address) - The address that initiated the deposit.
  - owner (address) - The address that receives the minted shares.
  - assets (uint256) - The amount of borrow assets deposited.
  - shares (uint256) - The number of shares minted.
Withdraw(address indexed sender, address indexed receiver, address indexed owner, uint256 assets, uint256 shares)
- Description: This event is emitted when borrow assets are withdrawn and shares are burned.
- Parameters:
  - sender (address) - The address that initiated the withdrawal.
  - receiver (address) - The address that receives the withdrawn assets.
  - owner (address) - The address whose shares are burned.
  - assets (uint256) - The amount of borrow assets withdrawn.
  - shares (uint256) - The number of shares burned.
DepositCollateral(address indexed sender, address indexed owner, uint256 collateralAssets, uint256 shares)
- Description: This event is emitted when collateral assets are deposited and shares are minted.
- Parameters:
  - sender (address) - The address that initiated the deposit.
  - owner (address) - The address that receives the minted shares.
  - collateralAssets (uint256) - The amount of collateral assets deposited.
  - shares (uint256) - The number of shares minted.
WithdrawCollateral(address indexed sender, address indexed receiver, address indexed owner, uint256 collateralAssets, uint256 shares)
- Description: This event is emitted when collateral assets are withdrawn and shares are burned.
- Parameters:
  - sender (address) - The address that initiated the withdrawal.
  - receiver (address) - The address that receives the withdrawn assets.
  - owner (address) - The address whose shares are burned.
  - collateralAssets (uint256) - The amount of collateral assets withdrawn.
  - shares (uint256) - The number of shares burned.

ERC-20 Events

Approval(address indexed owner, address indexed spender, uint256 value)
- Description: This event is emitted when an approval is granted.
- Parameters:
  - owner (address) - The token owner.
  - spender (address) - The approved spender.
  - value (uint256) - The approved amount.
Transfer(address indexed from, address indexed to, uint256 value)
- Description: This event is emitted when tokens are transferred.
- Parameters:
  - from (address) - The sender address.
  - to (address) - The recipient address.
  - value (uint256) - The transfer amount.

Auction Events

AuctionExecuted(address executor, int256 deltaRealCollateralAssets, int256 deltaRealBorrowAssets)
- Description: This event is emitted when an auction is executed.
- Parameters:
  - executor (address) - The address that executed the auction.
  - deltaRealCollateralAssets (int256) - The change in real collateral assets.
  - deltaRealBorrowAssets (int256) - The change in real borrow assets.

State Update Events

StateUpdated(int256 oldFutureBorrowAssets, int256 oldFutureCollateralAssets, int256 oldFutureRewardBorrowAssets, int256 oldFutureRewardCollateralAssets, uint256 oldStartAuction, int256 newFutureBorrowAssets, int256 newFutureCollateralAssets, int256 newFutureRewardBorrowAssets, int256 newFutureRewardCollateralAssets, uint256 newStartAuction)
- Description: This event is emitted when the protocol state is updated.
- Parameters:
  - oldFutureBorrowAssets (int256) - The previous future borrow assets.
  - oldFutureCollateralAssets (int256) - The previous future collateral assets.
  - oldFutureRewardBorrowAssets (int256) - The previous future reward borrow assets.
  - oldFutureRewardCollateralAssets (int256) - The previous future reward collateral assets.
  - oldStartAuction (uint256) - The previous auction start timestamp.
  - newFutureBorrowAssets (int256) - The new future borrow assets.
  - newFutureCollateralAssets (int256) - The new future collateral assets.
  - newFutureRewardBorrowAssets (int256) - The new future reward borrow assets.
  - newFutureRewardCollateralAssets (int256) - The new future reward collateral assets.
  - newStartAuction (uint256) - The new auction start timestamp.
Initialized(uint64 version)
- Description: This event is emitted when the contract is initialized.
- Parameters:
  - version (uint64) - The initialization version.

Administration Events

TargetLTVChanged(uint128 oldValue, uint128 newValue)
- Description: This event is emitted when the target LTV is changed.
- Parameters:
  - oldValue (uint128) - The previous target LTV value.
  - newValue (uint128) - The new target LTV value.
MaxSafeLTVChanged(uint128 oldValue, uint128 newValue)
- Description: This event is emitted when the maximum safe LTV is changed.
- Parameters:
  - oldValue (uint128) - The previous maximum safe LTV value.
  - newValue (uint128) - The new maximum safe LTV value.
MinProfitLTVChanged(uint128 oldValue, uint128 newValue)
- Description: This event is emitted when the minimum profitable LTV is changed.
- Parameters:
  - oldValue (uint128) - The previous minimum profitable LTV value.
  - newValue (uint128) - The new minimum profitable LTV value.
FeeCollectorUpdated(address oldValue, address newValue)
- Description: This event is emitted when the fee collector address is updated.
- Parameters:
  - oldValue (address) - The previous fee collector address.
  - newValue (address) - The new fee collector address.
MaxTotalAssetsInUnderlyingChanged(uint256 oldValue, uint256 newValue)
- Description: This event is emitted when the maximum total assets in underlying is changed.
- Parameters:
  - oldValue (uint256) - The previous maximum total assets value.
  - newValue (uint256) - The new maximum total assets value.
MaxDeleverageFeeChanged(uint256 oldValue, uint256 newValue)
- Description: This event is emitted when the maximum deleverage fee is changed.
- Parameters:
  - oldValue (uint256) - The previous maximum deleverage fee value.
  - newValue (uint256) - The new maximum deleverage fee value.
MaxGrowthFeeChanged(uint256 oldValue, uint256 newValue)
- Description: This event is emitted when the maximum growth fee is changed.
- Parameters:
  - oldValue (uint256) - The previous maximum growth fee value.
  - newValue (uint256) - The new maximum growth fee value.
IsWhitelistActivatedChanged(bool oldValue, bool newValue)
- Description: This event is emitted when the whitelist activation status is changed.
- Parameters:
  - oldValue (bool) - The previous whitelist activation status.
  - newValue (bool) - The new whitelist activation status.
IsDepositDisabledChanged(bool oldValue, bool newValue)
- Description: This event is emitted when the deposit disabled status is changed.
- Parameters:
  - oldValue (bool) - The previous deposit disabled status.
  - newValue (bool) - The new deposit disabled status.
IsWithdrawDisabledChanged(bool oldValue, bool newValue)
- Description: This event is emitted when the withdraw disabled status is changed.
- Parameters:
  - oldValue (bool) - The previous withdraw disabled status.
  - newValue (bool) - The new withdraw disabled status.
LendingConnectorUpdated(address oldValue, address newValue)
- Description: This event is emitted when the lending connector address is updated.
- Parameters:
  - oldValue (address) - The previous lending connector address.
  - newValue (address) - The new lending connector address.
OracleConnectorUpdated(address oldValue, address newValue)
- Description: This event is emitted when the oracle connector address is updated.
- Parameters:
  - oldValue (address) - The previous oracle connector address.
  - newValue (address) - The new oracle connector address.
SlippageProviderUpdated(address oldValue, address newValue)
- Description: This event is emitted when the slippage provider address is updated.
- Parameters:
  - oldValue (address) - The previous slippage provider address.
  - newValue (address) - The new slippage provider address.
WhitelistRegistryUpdated(address oldValue, address newValue)
- Description: This event is emitted when the whitelist registry address is updated.
- Parameters:
  - oldValue (address) - The previous whitelist registry address.
  - newValue (address) - The new whitelist registry address.
VaultBalanceAsLendingConnectorUpdated(address oldValue, address newValue)
- Description: This event is emitted when the vault balance as lending connector address is updated.
- Parameters:
  - oldValue (address) - The previous vault balance as lending connector address.
  - newValue (address) - The new vault balance as lending connector address.
GovernorUpdated(address oldValue, address newValue)
- Description: This event is emitted when the governor address is updated.
- Parameters:
  - oldValue (address) - The previous governor address.
  - newValue (address) - The new governor address.
GuardianUpdated(address oldValue, address newValue)
- Description: This event is emitted when the guardian address is updated.
- Parameters:
  - oldValue (address) - The previous guardian address.
  - newValue (address) - The new guardian address.
EmergencyDeleveragerUpdated(address oldValue, address newValue)
- Description: This event is emitted when the emergency deleverager address is updated.
- Parameters:
  - oldValue (address) - The previous emergency deleverager address.
  - newValue (address) - The new emergency deleverager address.

Ownership Events

OwnershipTransferred(address indexed previousOwner, address indexed newOwner)
- Description: This event is emitted when ownership is transferred.
- Parameters:
  - previousOwner (address) - The previous owner address.
  - newOwner (address) - The new owner address.

Errors

InvalidInitialization()
- Description: This error is thrown when the contract is initialized incorrectly.
NotInitializing()
- Description: This error is thrown when a function is called during initialization but the contract is not being initialized.
OwnableInvalidOwner(address owner)
- Description: This error is thrown when an invalid owner address is provided.
- Parameters:
  - owner (address) - The invalid owner address.
OwnableUnauthorizedAccount(address account)
- Description: This error is thrown when an unauthorized account tries to perform an owner-only operation.
- Parameters:
  - account (address) - The unauthorized account address.
ReentrancyGuardReentrantCall()
- Description: This error is thrown when a reentrant call is detected.

Connectors

Read Connector Address

oracleConnector() → address
- Type: view
- Outputs: address - The oracle connector contract address.
- Description: This function returns the address of the oracle connector that provides price feeds for collateral and borrow tokens.
lendingConnector() → address
- Type: view
- Outputs: address - The lending protocol connector contract address.
- Description: This function returns the address of the lending protocol connector that handles lending operations.
slippageProvider() → address
- Type: view
- Outputs: address - The slippage provider address.
- Description: This function returns the address of the slippage provider that manages slippage parameters.
vaultBalanceAsLendingConnector() → address
- Type: view
- Outputs: address - The vault balance as lending connector address.
- Description: This function returns the address of the vault balance as lending connector.
whitelistRegistry() → address
- Type: view
- Outputs: address - The whitelist registry address.
- Description: This function returns the address of the whitelist registry that manages access control.

EIP links

EIP-4626 Vault Functions

12 Main functions

	preview	max	execute
deposit	`previewDeposit()`	`maxDeposit()`	`deposit()`
mint	`previewMint()`	`maxMint()`	`mint()`
withdraw	`previewWithdraw()`	`maxWithdraw()`	`withdraw()`
redeem	`previewRedeem()`	`maxRedeem()`	`redeem()`

All 4626 functions

Category	Function	Description
Preview	`previewDeposit(uint256)`	Simulates shares received for a given asset deposit
Preview	`previewMint(uint256)`	Simulates assets required to mint a given amount of shares
Preview	`previewWithdraw(uint256)`	Simulates shares needed to withdraw a given amount of assets
Preview	`previewRedeem(uint256)`	Simulates assets received for redeeming a given amount of shares
Max	`maxDeposit(address)`	Max assets that `address` can deposit
Max	`maxMint(address)`	Max shares that `address` can mint
Max	`maxWithdraw(address)`	Max assets that `address` can withdraw
Max	`maxRedeem(address)`	Max shares that `address` can redeem
Execute	`deposit(uint256 assets, address receiver)`	Deposit assets and receive shares
Execute	`mint(uint256 shares, address receiver)`	Mint shares by depositing equivalent assets
Execute	`withdraw(uint256 assets, address receiver, address owner)`	Withdraw assets by burning shares
Execute	`redeem(uint256 shares, address receiver, address owner)`	Redeem shares for assets
Other	`asset()`	Returns the underlying asset address (ERC-20)
Other	`totalAssets()`	Total amount of underlying assets managed by the vault
Other	`convertToShares(uint256 assets)`	Converts assets to shares
Other	`convertToAssets(uint256 shares)`	Converts shares to assets
ERC-20	`balanceOf(address)`	Returns share balance of an account
ERC-20	`totalSupply()`	Total supply of shares
ERC-20	`transfer(address, uint256)`	Transfers shares to another address
ERC-20	`transferFrom(address, address, uint256)`	Transfers shares on behalf of another
ERC-20	`approve(address, uint256)`	Approves a spender
ERC-20	`allowance(address, address)`	Returns remaining allowance for a spender
ERC-20	`name()`	Share token name
ERC-20	`symbol()`	Share token symbol
ERC-20	`decimals()`	Share token decimals (commonly 18)

Connectors - Interfaces for Integration.

The LTV protocol uses connectors to stay modular and adaptable, allowing seamless integration with various external systems like lending protocols and price oracles. This design ensures that the vault logic remains unchanged even as the ecosystem evolves or new protocols emerge. By abstracting these components, the protocol can support permissionless deployments across different chains and asset pairs. It also enables governance flexibility.

Lending Protocol Connector

The Lending Protocol Connector determines how the vault interacts with external lending platforms to deposit collateral and borrow assets. It gives the LTV system flexibility to integrate with various protocols such as Aave, Compound, or custom-built solutions like the HodlMyBeer protocol used on testnet. Since the connector acts as a modular layer, the core vault logic remains unchanged even if the underlying lending protocol is swapped out.

Oracle Connector

The Oracle Connector handles how the vault obtains and interprets price data for assets like LSTs or borrow tokens. This data can come from sources like Chainlink, a specialized oracle such as Spooky Oracle, or even DEX-based price feeds. With accurate and modular oracle integration, the vault can continuously evaluate its leverage position and make informed rebalancing decisions.

Slippage Connector

The Slippage Connector in the LTV protocol framework is a mechanism that governs how price slippage is accounted for during operations like rebalancing and auctions. It influences how assets are valued and incentivizes participation in auctions by adjusting for market impact.

LTV protocol documentation