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 of PermitDetails 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