Velvet Capital: strategy deposit flow

[kenkunz]

Goal

As a web visitor seeking to deposit funds into a strategy that uses a Velvet Capital vault, I want a usable and secure deposit flow that enables me to deposit funds in a denomination currency (e.g., USDC, USDT) and receive, in exchange, an appropriate amount of tokens representing shares of the strategy.

Example deposit

Here's an example deposit flow for ETH-BTC long swing using an Enzyme vault:

ETH-BTC.long.swing.deposit.mp4

Acceptance criteria

Given

• a strategy with metadata property on_chain_data.asset_management_mode set to "velvet_capital"
• and on_chain_data.smart_contracts includes the following properties with valid blockchain addresses:
  • denomination_token
  • vault
  • portfolio
  • deposit_manager
• and configured API endpoints and API keys for:
  • Enso Intents API
  • Velvet Intents API
• and a user with a connected wallet, with sufficient gas and denomination token quantities to deposit into the strategy

1. When: a user clicks the "Deposit" button on the strategy
   • then: deposit wizard is initiated
   • and: based on the vault information provided in the strategy's metadata, the denomination token is identified and displayed to the user on the introduction screen (e.g., USDT, USDC)
2. When: the user advances through other wizard steps and arrives on the Payment step
   • then: payment state is initialized
   • and: the share value of the vault token (in terms of the denomination token) is retrieved so that "Estimated shares" may be calculated based on the user's input
3. When: the user enters a deposit amount
   • then: "Estimated shares" are calculated and displayed to the user (based on the share value retrieved in criterion 2)
4. When: the user clicks "Approve [token]"
   • then: a spending cap approve request is initiated in the user's wallet on the denomination token, approving transfer to an appropriate spender contract address associated with the vault, for the amount that the user specified for their deposit
5. When: the user has successfully approved the spending cap and the user clicks "Buy shares"
   • then: a request to purchase vault shares is initiated, displaying an approval request in the user's wallet
   • and: approving the request in-wallet results in successful purchase of vault assets

Additional code quality acceptance criterion

6. The code is restructured with an adapter layer for vault providers:
   • current Enzyme-specific code is moved into an Enzyme-specific module
   • new Velvet-specific code is added to a Velvet-specific module
   • the vault provider is determined at runtime during the deposit flow and the appropriate vault-specific data, functions and ABIs are loaded and used
   • consider using dynamic import to prevent bloat

Questions

1. How do we identify the denomination token?

Per @miohtama:

Velvet Capital vaults don't require a specific denomination token. They just hold a set of assets. When a user makes a deposit, the deposited asset is immediately traded for the vaults current asset holdings.

To keep our UI simple and consistent across vaults, we will treat USDC as a denomination token for all strategies using Velvet Capital vaults and Base blockchain.

This address should be included in the smart_contracts of the strategy's metadata.

2. How is the share value (relative to USDC) determined?

See AC 2 above, second bullet.

Examining the estimation process in the purchase flow on Velvet Capital's own site, this is done through an Enso API.

Sample API call:

curl 'https://api.enso.finance/api/v1/shortcuts/route?chainId=56&fromAddress=0x110f8d66f84649F3cBb76778C53EdaB7f086f3E8&receiver=0x110f8d66f84649F3cBb76778C53EdaB7f086f3E8&spender=0x110f8d66f84649F3cBb76778C53EdaB7f086f3E8&amountIn=2767000000000000&slippage=100&tokenIn=0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee&tokenOut=0x78F5d389F5CDCcFc41594aBaB4B0Ed02F31398b3&routingStrategy=delegate&fee=20&feeReceiver=0x3B3060823Fd0b26211CA3C2e3090Eac14cf526Cc&ignoreAggregators%5B0%5D=barter&ignoreAggregators%5B1%5D=openocean' \
  -H 'Accept: application/json, text/plain, */*' \
  -H 'Authorization: Bearer XXX-YYY-ZZZZ'

{"gas":"206905","amountOut":"13363160579977810914","priceImpact":9,"feeAmount":["5534000000000"],"createdAt":44963743,"tx":{"data":"...","to":"0x38147794FF247e5Fc179eDbAE6C37fff88f68C52","from":"0x110f8d66f84649F3cBb76778C53EdaB7f086f3E8","value":"2767000000000000"},"route":[{"action":"swap","protocol":"enso","tokenIn":["0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee"],"tokenOut":["0x78f5d389f5cdccfc41594abab4b0ed02f31398b3"]}]}

Velvet UI appears to make above request for every single token asset held in the vault.

Q: where does the UI get the list of tokens held by the vault?

NOTE: may be able to use simpler quote API instead of route

3. How do we identify the spender contract address?

See AC 4 above.

See code referenced in question 4 below.

The spender for an approve or allowance ERC-20 call should be the Velvet deposit_manager address for a given chain.

On Base this is: 0xe4e23120a38c4348D7e22Ab23976Fa0c4Bf6e2ED

This address should be included in the smart_contracts of the strategy's metadata.

4. How do we initiate vault deposit transaction?

See AC 5 above.

Per @miohtama:

You make an API call which returns a payload with a prepared transaction. You then submit the tx on-chain. See example python code here:
https://github.com/tradingstrategy-ai/web3-ethereum-defi/blob/434d7d3776ac111378866d49860f7981eb80d3aa/tests/velvet/test_velvet_api.py#L333

See Velvet Deposit Portfolio API documentation