Smart Contract Documentation
This document contains documentation for the latest Velvet smart contracts, please don't hesitate to reach out for integration support.
Introduction
Velvet v4 protocol is a DeFi protocol enabling creation, management, and interaction with onchain portfolios. It allows portfolio managers to construct & manage bespoke portfolios across a diverse range of tokens & protocols and facilitate deposit/withdrawal process.
Key Features:
Portfolio Creation: Portfolio managers can deploy both custodial and non-custodial portfolios setting up parameters like management fees, performance fees, entry and exit fees, token whitelists, initial token supply, and transferability options. Safe (fka Gnosis Safe) standard is used for portfolio creation.
Deposit and Withdrawal: Depositors can supply multiple tokens into portfolios via single or batched transactions, with support for gasless approvals through Permit2. Withdrawals are flexible, allowing depositors to receive specific underlying assets or to repay associated debts, offering granular control over their portfolio positions.
Rebalancing: Managers have the tools to update the portfolio's asset composition and adjust token weights dynamically. This enables them to rebalance portfolios in response to market movements, maintain desired asset allocations, and optimize for performance or risk management. Rebalancing includes trading and allocation into DeFi pools generating additional yield (routed using Velvet solver network).
External Position Management: The protocol is also directly integrated with DeFi primitives such as Uniswap V3, Thena or similar. Portfolio managers can create and manage liquidity positions, adjust price ranges, and reinvest earned fees, enabling portfolios to participate in yield farming, liquidity provision, and other advanced DeFi strategies.
Debt Management: Portfolio managers can engage in borrowing and lending activities, utilizing tokens as collateral to borrow assets from lending protocols. They can manage collateralization ratios, perform flash loans for efficient debt repayment, and adjust portfolio leverage, allowing for sophisticated debt strategies within the portfolio.
Portfolio Management Configuration: Managers can propose and adjust various fees associated with the portfolio, including management, performance, entry, and exit fees. The protocol incorporates governance mechanisms such as time-locked proposals and the ability to cancel proposals, ensuring transparent and fair fee management.
Treasury and Whitelist Management: The platform allows updating of treasury addresses for fee accrual and supports robust user management via whitelisting. Portfolio managers can control depositor access to their portfolios, manage permissions, and tailor depositor communities.
Token Exclusion Handling: In scenarios where certain tokens need to be removed from a portfolio—such as due to liquidity issues or protocol changes—the protocol provides mechanisms for portfolio managers to exclude tokens and for depositors to claim their proportionate share of them.
Velvet v4 supports advanced portfolio management, diverse DeFi strategies, and seamless interactions with other DeFi protocols. See detailed developer documentation below.
Velvet Core
The Velvet Core contracts facilitate the creation of new portfolios and provide core functionalities for portfolio management.
Create New Portfolio
createPortfolioNonCustodial
Creates a new non-custodial portfolio with specified parameters. This type of portfolio is managed directly by the asset manager without the use of a custodial wallet.
Copy
Parameters:
initData
: A struct containing initialization data for the portfolio.
createPortfolioCustodial
Creates a new custodial portfolio managed by a Gnosis Safe, allowing for multi-signature control and enhanced security.
Copy
Parameters:
initData
: Initialization data for the portfolio._owners
: Array of addresses that will own the Gnosis Safe._threshold
: The minimum number of owner signatures required for transactions.
PortfolioCreationInitData Struct
Defines the initial configuration parameters for creating a new portfolio.
Copy
Fields:
_assetManagerTreasury
: Address for fee accumulation._whitelistedTokens
: Tokens allowed in the portfolio._managementFee
: Annual management fee in basis points._performanceFee
: Fee on profits in basis points._entryFee
: One-time entry fee in basis points._exitFee
: Exit fee in basis points._initialPortfolioAmount
: Initial supply of portfolio tokens (>= 1e14)._minPortfolioTokenHoldingAmount
: Minimum holding amount (>= 1e14)._public
: Indicates if the fund is open to the public._transferable
: If tokens are transferable._transferableToPublic
: If tokens can be transferred to non-whitelisted addresses._whitelistTokens
: Restricts the fund to whitelisted tokens._externalPositionManagementWhitelisted
: Allows external position management._name
: Name of the portfolio token._symbol
: Symbol of the portfolio token.
Event Emission on Portfolio Creation
An event is emitted when a new portfolio is created, providing details about the portfolio.
Copy
Event Parameters:
portfolioData
: Struct with portfolio-related addresses.portfolioId
: Unique identifier for the portfolio._name
: Name of the portfolio token._symbol
: Symbol of the portfolio token._owner
: Address of the portfolio owner._accessController
: Access controller address.isPublicPortfolio
: Indicates if the portfolio is public.
PortfoliolInfo Struct
Contains addresses of various contracts associated with the portfolio.
Copy
Fields:
portfolio
: Portfolio contract address.tokenExclusionManager
: Manages token exclusions.rebalancing
: Rebalancing contract address.owner
: Owner's address.borrowManager
: Manages borrowing operations.assetManagementConfig
: Asset management configuration.feeModule
: Fee module address.vaultAddress
: Vault contract address.gnosisModule
: Gnosis Safe module address.
Initialize Tokens
initTokens
Initializes the vault with a set of tokens, setting up the initial assets managed by the portfolio.
Copy
Parameters:
_tokens
: An array of token addresses to include in the vault.
Deposit
Users can deposit tokens into the portfolio, either directly or on behalf of another user, using multi-token deposit functions.
multiTokenDeposit
Allows users to deposit multiple tokens into the portfolio in a single transaction. Supports gasless approvals through Permit2.
Copy
Parameters:
depositAmounts
: Amounts for each token being deposited._minMintAmount
: Minimum portfolio tokens expected to receive._permit
: Batch permit data for token allowance._signature
: Signature for the permit batch.
PermitBatch Struct
Used for gasless token approvals.
Copy
Fields:
details
: Array ofPermitDetails
structs.spender
: Address authorized to spend tokens.sigDeadline
: Signature validity deadline.
multiTokenDepositFor
Allows depositing tokens on behalf of another user.
Copy
Parameters:
_depositFor
: Address of the user for whom the deposit is made.depositAmounts
: Amounts for each token being deposited._minMintAmount
: Minimum portfolio tokens expected to receive.
DepositBatch
The DepositBatch
contract enables users to batch multiple token swaps and deposit operations, facilitating complex deposit scenarios.
deposit
Allows depositing tokens after performing necessary swaps and transfers, especially when dealing with tokens not directly accepted by the portfolio.
Copy
BatchHandler Struct
Copy
Fields:
_minMintAmount
: Minimum portfolio tokens expected._depositAmount
: Amount of tokens to swap._target
: Portfolio contract address._depositToken
: Initial token address to swap from._callData
: Encoded data for swap operations.
multiTokenSwapETHAndTransfer
Performs swaps for ETH deposits and transfers tokens to the portfolio.
Copy
DepositBatchExternalPositions
Extends DepositBatch
functionalities to handle deposits into portfolios with external positions like Uniswap V3 or Thena.
deposit
Facilitates deposits involving external positions, handling swaps and liquidity operations.
Copy
ExternalPositionDepositParams Struct
Copy
Fields:
_positionWrappers
: External position wrapper addresses._swapTokens
: Tokens involved in swaps or liquidity._positionWrapperIndex
: Indices linking wrappers to portfolio tokens._portfolioTokenIndex
: Indices for tokens in the portfolio._index0
,_index1
: Indices for liquidity pairs._amount0Min
,_amount1Min
: Minimum amounts to prevent slippage._isExternalPosition
: Flags indicating external positions._tokenIn
,_tokenOut
: Tokens for swap operations._amountIn
: Amounts for swaps.
Withdrawal
Users can withdraw portfolio tokens, receiving underlying assets or swapping them into desired tokens.
multiTokenWithdrawal
Allows withdrawing portfolio tokens and optionally repaying debts.
Copy
Parameters:
_portfolioTokenAmount
: Amount of portfolio tokens to withdraw.repayData
: Parameters for debt repayment during withdrawal.
withdrawRepayParams Struct
Copy
Fields:
_factory
: Thena factory contract address._token0
,_token1
: Tokens involved in swaps._flashLoanToken
: Token for flash loan._solverHandler
: Contract handling swaps._bufferUnit
: Buffer for safety margins._flashLoanAmount
: Amounts for flash loans.firstSwapData
,secondSwapData
: Encoded swap data.
multiTokenWithdrawalFor
Allows approved users to withdraw on behalf of others.
Copy
Parameters:
_withdrawFor
: Address of the user whose tokens are withdrawn._tokenReceiver
: Recipient of withdrawn tokens._portfolioTokenAmount
: Amount to withdraw.repayData
: Debt repayment parameters.
WithdrawalBatch
Facilitates batch withdrawals involving swaps and complex operations.
withdraw
Withdraws portfolio tokens and executes swaps to obtain desired output tokens.
Copy
Parameters:
_target
: Portfolio contract address._tokenToWithdraw
: Token to receive after withdrawal._portfolioTokenAmount
: Amount to withdraw._expectedOutputAmount
: Minimum expected output.repayData
: Debt repayment parameters._callData
: Encoded swap operations.
WithdrawalBatchExternalPositions
Handles withdrawals from portfolios with external positions.
withdraw
Manages withdrawals involving external positions and swaps.
Copy
Parameters:
_swapTokens
: Tokens involved in swaps._target
: Portfolio contract address._tokenToWithdraw
: Token to receive._portfolioTokenAmount
: Amount to withdraw._callData
: Encoded swap data.repayData
: Debt repayment parameters._params
: External position withdrawal parameters.
ExternalPositionWithdrawParams Struct
Copy
Fields:
_positionWrappers
: External position wrappers._amountsMin0
,_amountsMin1
: Minimum amounts to prevent slippage._tokenIn
,_tokenOut
: Tokens for swaps._amountIn
: Amounts for swaps.
Rebalancing
Note: Functions in this section can only be called by asset managers.
Asset managers can rebalance the portfolio by updating the token list and adjusting token weights.
updateTokens
Updates the portfolio's token list and adjusts weights based on provided rebalance data.
Copy
RebalanceIntent Struct
Copy
Fields:
_newTokens
: Tokens to add to the portfolio._sellTokens
: Tokens to sell during rebalancing._sellAmounts
: Amounts of tokens to sell._handler
: Address of the handler executing swaps._callData
: Encoded data for rebalancing operations.
updateWeights
Adjusts the weights of existing tokens without changing the token list.
Copy
Parameters:
_sellTokens
: Tokens to sell._sellAmounts
: Amounts to sell._handler
: Swap handler address._callData
: Encoded swap data.
enableCollateralTokens
Enables specified tokens as collateral in a lending protocol.
Copy
Parameters:
_tokens
: Tokens to enable as collateral._controller
: Lending protocol controller address.
disableCollateralTokens
Disables specified tokens as collateral.
Copy
borrow
Executes a borrow operation using designated collateral.
Copy
Parameters:
_pool
: Lending pool address._tokens
: Collateral tokens._tokenToBorrow
: Token to borrow._controller
: Lending protocol controller._amountToBorrow
: Amount to borrow.
repay
Repays debt using a flash loan and rebalances the portfolio.
Copy
Parameters:
_controller
: Controller managing the repayment.repayData
: Parameters for the repayment process.
RepayParams Struct
Refer to the repayData
struct in the Withdrawal section for details.
directDebtRepayment
Repays debt directly by transferring debt tokens.
Copy
removePortfolioToken
Removes a token from the portfolio.
Copy
removePortfolioTokenPartially
Removes a portion of a token from the portfolio.
Copy
removeNonPortfolioToken
Removes a non-portfolio token.
Copy
removeNonPortfolioTokenPartially
Removes a portion of a non-portfolio token.
Copy
Token Exclusion Manager
Manages the exclusion and removal of tokens from the portfolio due to reasons like lack of liquidity.
claimRemovedTokens
Allows users to claim their share of tokens that have been removed from the portfolio.
Copy
claimTokenAtId
Claims a specific removed token by its ID.
Copy
Position Manager
Provides functionalities to manage liquidity positions in Uniswap V3 or Thena.
Setup: Enable the Uniswap V3 Manager in AssetManagementConfig
.
Copy
createNewWrapperPositionAndDeposit
Creates a new liquidity position and makes an initial deposit.
Copy
Parameters:
_dustReceiver
: Address for leftover tokens._token0
,_token1
: Tokens in the liquidity pair._name
,_symbol
: Name and symbol for the wrapper token.params
: Parameters for minting the position.
PositionMintParamsThena Struct
Copy
Fields:
_amount0Desired
,_amount1Desired
: Desired token amounts._amount0Min
,_amount1Min
: Minimum amounts to prevent slippage._tickLower
,_tickUpper
: Price range ticks.
initializePositionAndDeposit
Initializes an existing position and makes a deposit.
Copy
createNewWrapperPosition
Creates a new wrapper position without an initial deposit.
Copy
increaseLiquidity
Increases liquidity in an existing position.
Copy
WrapperDepositParams Struct
Copy
decreaseLiquidity
Decreases liquidity and burns wrapper tokens.
Copy
updateRange
Updates the price range and fee tier of an existing position.
Copy
Note: Asset managers need to calculate swap parameters to maintain optimal ratios during liquidity adjustments. This involves determining collected fees, desired ratios, and required swaps to align with the new price range.
Portfolio Data
The portfolio contracts provide functions to access and manage the tokens within the vault, as well as information about the portfolio tokens themselves.
getTokens
Copy
Retrieves the current list of token addresses held in the vault.
Returns:
address[] memory
: An array containing the addresses of the tokens in the vault.
totalSupply
Copy
Returns the total supply of the portfolio tokens in circulation.
Returns:
uint256
: The total number of portfolio tokens minted.
balanceOf
Copy
Provides the balance of portfolio tokens held by a specific user.
Parameters:
account
: The address of the user whose balance is being queried.
Returns:
uint256
: The number of portfolio tokens owned by the specified user.
Asset Management Configuration
Note: All functions in AssetManagementConfig
can only be called by asset managers.
The AssetManagementConfig
contract allows asset managers to configure various aspects of the portfolio, including external positions, fees, portfolio settings, treasury management, and user whitelist management.
External Position Management
enableUniSwapV3Manager
Enables the Uniswap V3 wrapper, allowing the portfolio to interact with Uniswap V3 positions. This is essential for portfolios that include external liquidity positions.
Copy
Fee Management
The following functions allow asset managers to propose and update management, performance, entry, and exit fees. Each fee change involves a proposal followed by a waiting period before the update can be finalized.
proposeNewManagementFee
Starts the process of updating the management fee by proposing a new fee. A waiting period begins during which the proposed fee can be reviewed.
Copy
Parameters:
_newManagementFee
: The proposed new management fee, expressed in basis points (e.g., 100 = 1%).
Note: The updateManagementFee
function can be called 28 days after the proposal. The management fee cannot exceed the maxManagementFee
set in the protocol configuration.
deleteProposedManagementFee
Cancels the proposed management fee, resetting the proposal and stopping the update process.
Copy
updateManagementFee
Finalizes the management fee update after the waiting period has elapsed, applying the previously proposed fee.
Copy
proposeNewPerformanceFee
Proposes a new performance fee, initiating a waiting period before the fee can be updated.
Copy
Parameters:
_newPerformanceFee
: The proposed new performance fee, expressed in basis points.
deleteProposedPerformanceFee
Cancels the proposed performance fee, resetting the proposal.
Copy
updatePerformanceFee
Updates the performance fee to the previously proposed value after the waiting period has passed.
Copy
proposeNewEntryAndExitFee
Proposes new entry and exit fees, starting a timer before the changes can be finalized.
Copy
Parameters:
_newEntryFee
: The proposed new entry fee, in basis points._newExitFee
: The proposed new exit fee, in basis points.
deleteProposedEntryAndExitFee
Cancels the proposed entry and exit fees, resetting the proposal.
Copy
updateEntryAndExitFee
Finalizes the entry and exit fee updates after the waiting period.
Copy
Portfolio Settings
updateTransferability
Updates the transferability settings of the portfolio token, determining whether tokens can be transferred and whether transfers to the public are allowed.
Copy
Parameters:
_transferable
: Enables or disables the ability to transfer portfolio tokens._publicTransfer
: Allows or disallows transferring portfolio tokens to the public (non-whitelisted addresses).
convertPrivateFundToPublic
Converts a private portfolio to a public one, allowing broader access to investors.
Copy
updateMinPortfolioTokenHoldingAmount
Sets the minimum amount of portfolio tokens that must be held or transacted, enforcing investment thresholds.
Copy
Parameters:
_minPortfolioTokenHoldingAmount
: The new minimum portfolio token amount required for transactions.
updateInitialPortfolioAmount
Updates the initial amount of the portfolio, setting a new starting value for the portfolio tokens.
Copy
Parameters:
_newAmount
: The new initial portfolio amount.
Treasury Management
updateAssetManagerTreasury
Changes the address where asset management fees are accumulated.
Copy
Parameters:
_newAssetManagerTreasury
: The new treasury address for asset management fees.
User Whitelist Management
whitelistUser
Adds users to the whitelist, allowing them to deposit into the portfolio.
Copy
Parameters:
users
: An array of user addresses to be whitelisted.
removeWhitelistedUser
Removes users from the whitelist, revoking their ability to deposit.
Copy
Parameters:
users
: An array of user addresses to be removed from the whitelist.
Last updated