add-vault-protocol

Add vault protocol

This skill guides you through adding support for a new ERC-4626 vault protocol to the eth_defi library.

Tokenised fund protocols

Tokenised fund protocols belong under eth_defi/tokenised_fund/{protocol_slug}/, rather than eth_defi/erc_4626/vault_protocol/. Use eth_defi/tokenised_fund/asseto/ and eth_defi/tokenised_fund/securitize/ as the reference integrations. These protocols commonly expose permissioned ERC-20 token shares and bespoke subscription and redemption flows instead of ERC-4626 vault contracts.

Required inputs

Before starting, gather the following information from the user:

1. Vault smart contract address - The address of an example vault contract on a blockchain
2. Protocol name - Human-readable name (e.g., "Plutus", "IPOR", "Morpho")
3. Protocol slug - Snake_case identifier for code (e.g., "plutus", "ipor", "morpho")
4. Chain - Which blockchain (Ethereum, Arbitrum, Base, etc.)
5. Block explorer URL - To fetch the ABI (e.g., Etherscan, Arbiscan, Basescan)
6. Single vault protocol: Some protocols, especially ones issuing out their own stablecoin, are know to have only a single vault for the stablecoin staking. Example protocols are like like Spark, Ethena, Cap. In this case use HARDCODED_PROTOCOLS classification later, as there is no point to create complex vault smart contract detection patterns if the protocol does not need it.
7. Risk level: Optional. If not given, set to None

Completion requirements

A new vault protocol integration is not complete unless it includes:

• Protocol detection or hardcoded address classification
• Vault class and create_vault_instance() wiring
• Deposit manager and public deposit/redemption flow capability, backed by a guarded fork transaction test
• Risk and fee matrix entries
• Protocol metadata YAML under eth_defi/data/vaults/metadata/
• Original and post-processed protocol logos
• A post-processed light.png: a light-coloured logo that remains legible on the frontend's dark backgrounds
• Vault documentation and API documentation entries
• Focused tests for the new protocol
• A generated protocol-specific historical lead migration script that preserves unrelated vault database, reader-state and Parquet entries

Step-by-step implementation

Step 1: Download and store the ABI

1. Fetch the vault smart contract ABI from the blockchain explorer
2. Important: If the contract is a proxy, you need the implementation ABI, not the proxy ABI
   • Check if the contract has a implementation() function or similar
   • Use the explorer's "Read as Proxy" feature to get the implementation address
   • Download the implementation contract's ABI
3. Create the ABI directory and file:

   eth_defi/abi/{protocol_slug}/
   eth_defi/abi/{protocol_slug}/{ContractName}.json
   

4. Use eth_defi/abi/lagoon/ as a reference for structure

For a narrowly scoped adapter that only needs stable, no-argument view methods, using their canonical four-byte selectors is acceptable instead of storing a generated ABI. Link the authoritative ABI in the module docstring and add a fork regression test for every decoded value and scale.

Step 2: Create the vault class

Create eth_defi/erc_4626/vault_protocol/{protocol_slug}/vault.py following the patterns in:

• eth_defi/erc_4626/vault_protocol/plutus/vault.py - Simple vault with hardcoded fees
• eth_defi/erc_4626/vault_protocol/ipor/vault.py - Complex vault with custom fee reading and multicall support

The vault class should:

"""Module docstring describing the protocol."""

import datetime
import logging

from eth_typing import BlockIdentifier

from eth_defi.erc_4626.vault import ERC4626Vault

logger = logging.getLogger(__name__)


class {ProtocolName}Vault(ERC4626Vault):
    """Protocol vault support.

    One line description of the protocol.

    - Add links to protocol documentation
    - Add links to example contracts on block explorers
    - Add links to github
    - If fee information is documented or available as Github source code, link into it
    """

    def get_management_fee(self, block_identifier: BlockIdentifier) -> float:
        return None

    def get_performance_fee(self, block_identifier: BlockIdentifier) -> float | None:
        return None

    def get_estimated_lock_up(self) -> datetime.timedelta | None:
        return None

    def get_link(self, referral: str | None = None) -> str:
        return f"https://protocol-url.com/vault/{self.vault_address}"

For get_link() check the protocol website to find a direct link URL pattern to its vault. Usual formats:

• By address
• By chain id and address - for example Ethereum chain id is 1
• By chain name and address - use get_chain_name(chain_id).lower() or simiar
• Can be special for protocols just with one vault, it can be a single link with no pattern
• If you fail to figure this out, just link to the protocol homepage

Step 3: Add protocol feature enum

Edit eth_defi/erc_4626/core.py and add a new enum member to ERC4626Feature:

#: {Protocol Name}
#:
#: {Protocol URL}
{protocol_slug}_like = "{protocol_slug}_like"

Also update get_vault_protocol_name() to return the protocol name:

elif ERC4626Feature.{protocol_slug}_like in features:
    return "{Protocol Name}"

Step 4: Add protocol identification probes

Edit eth_defi/erc_4626/classification.py:

Probe budget: Classification runs every probe against every candidate vault. Prefer one no-argument, protocol-specific view accessor per protocol. Use a second probe only when independently necessary contract variants cannot be safely identified by the first one, and document why both are required. Do not add fee, version, or other adapter data accessors merely to corroborate a classification; read those only after the adapter has been selected. Never add more than two protocol probes without explicit maintainer approval.

1. In create_probe_calls(), add a probe call that uniquely identifies this protocol:
   • Analyse the ABI and the vault implementation smart contract source code to find a function unique to this protocol
   • Look for functions like getProtocolSpecificData(), custom role constants, etc. and compare them to what is already implemented in create_probe_calls()
   • Make sure this call does not conflict with already configured protocols
   • You can also use blockchain explorer's Contract > Read contract or Contract Read contract as proxy to figure out good ABI calls to detect this particular type of smart contracts
   • If the protocol is a single vault protocol, use HARDCODED_PROTOCOLS in classification.py instead

If you cannot find a such accessor function in the ABI or vault smart contract source, interrupt the skill and ask for user intervention.

# {Protocol Name}
# {Block explorer link}
{protocol_slug}_call = EncodedCall.from_keccak_signature(
    address=address,
    signature=Web3.keccak(text="uniqueFunction()")[0:4],
    function="uniqueFunction",
    data=b"",
    extra_data=None,
)
yield {protocol_slug}_call

2. In identify_vault_features(), add detection logic:

if calls["uniqueFunction"].success:
    features.add(ERC4626Feature.{protocol_slug}_like)

Step 5: Update create_vault_instance()

In eth_defi/erc_4626/classification.py, add a case for the new protocol in create_vault_instance():

elif ERC4626Feature.{protocol_slug}_like in features:
    from eth_defi.erc_4626.vault_protocol.{protocol_slug}.vault import {ProtocolName}Vault

    return {ProtocolName}Vault(web3, spec, token_cache=token_cache, features=features)

Step 6: Certify deposit and redemption flows

Every vault adapter must explicitly declare whether it supports deposits and redemptions. Do not treat ERC-4626 interface detection alone as permission to advertise deposit-manager support: public support requires a complete tested lifecycle.

1. Determine the flow from the vault contract and protocol documentation:

   • Synchronous: the user approves the denomination token and directly calls ERC-4626 deposit() / mint() and withdraw() / redeem().
   • Asynchronous: the vault uses a request, queue, epoch, settlement, claim, cooldown, or redemption-delay flow. Implement a protocol-specific deposit manager instead of certifying the generic manager.
   • Unsupported: do not expose a partial manager. Leave the public capability as None until both directions are implemented and tested.

2. For a standard synchronous ERC-4626 adapter, certify the inherited ERC4626DepositManager by adding the exact fully-qualified class name to CERTIFIED_SYNCHRONOUS_DEPOSIT_MANAGER_CLASSES in eth_defi/erc_4626/vault.py:

   "eth_defi.erc_4626.vault_protocol.{protocol_slug}.vault.{ProtocolName}Vault",
   

   The inherited get_deposit_manager() then returns ERC4626DepositManager, and get_deposit_manager_capability() exports the public fields:

   {
       "can_deposit": True,
       "can_redeem": True,
       "deposit_flow": "synchronous",
       "redemption_flow": "synchronous",
   }
   

3. Add a guarded Anvil fork test that uses an unlocked token holder to transfer the denomination token to an Anvil account, approves the vault, deposits through vault.get_deposit_manager(), and redeems the exact minted share balance. Assert that the manager is ERC4626DepositManager, both flow methods are synchronous, the public capability fields match the schema above, and the final share balance is zero.

4. Add or update a no-RPC unit test for the exact-class allowlist. This prevents a future refactor from silently removing the advertised capability when RPC-backed tests are skipped.

Reference implementations:

• Generic manager and capability implementation: eth_defi/erc_4626/deposit_redeem.py and `eth_defi/erc_4626

Content truncated.