Morpho Vault¶

Connector for Morpho Vault protocol.

almanak.framework.connectors.morpho_vault ¶

MetaMorpho Vault Connector.

This module provides adapters and utilities for interacting with MetaMorpho vaults, the ERC-4626 vault layer that aggregates capital across Morpho Blue lending markets.

MetaMorpho Features: - ERC-4626 compliant vault deposits and redemptions - Passive yield optimization with curator-managed allocation - Multi-market capital allocation across Morpho Blue markets - Transparent share pricing via convertToAssets/convertToShares

Supported Chains: - Ethereum - Base

Example

from almanak.framework.connectors.morpho_vault import ( MetaMorphoAdapter, MetaMorphoConfig, MetaMorphoReceiptParser, MetaMorphoSDK, create_test_adapter, ) from decimal import Decimal

Initialize adapter¶

config = MetaMorphoConfig(chain="ethereum", wallet_address="0x...") adapter = MetaMorphoAdapter(config, gateway_client=gateway_client)

Deposit assets¶

result = adapter.deposit( vault_address="0xBEEF01735c132Ada46AA9aA4c54623cAA92A64CB", amount=Decimal("1000"), )

Redeem all shares¶

result = adapter.redeem( vault_address="0xBEEF01735c132Ada46AA9aA4c54623cAA92A64CB", shares="all", )

Parse transaction receipts¶

parser = MetaMorphoReceiptParser() parse_result = parser.parse_receipt(receipt)

MetaMorphoAdapter ¶

MetaMorphoAdapter(
    config: MetaMorphoConfig,
    gateway_client=None,
    token_resolver: TokenResolver | None = None,
)

Adapter for MetaMorpho vault protocol.

Provides high-level methods for depositing into and redeeming from MetaMorpho ERC-4626 vaults, with token resolution and validation.

Example

config = MetaMorphoConfig(chain="ethereum", wallet_address="0x...") adapter = MetaMorphoAdapter(config, gateway_client=client)

Get vault info¶

info = adapter.get_vault_info("0xBEEF...")

Deposit¶

result = adapter.deposit("0xBEEF...", Decimal("1000"))

Initialize the adapter.

Parameters:

Name	Type	Description	Default
`config`	`MetaMorphoConfig`	Adapter configuration	required
`gateway_client`		Gateway client for RPC calls. Required for on-chain operations.	`None`
`token_resolver`	`TokenResolver \| None`	Optional TokenResolver instance. If None, uses singleton.	`None`

sdk `property` ¶

sdk: MetaMorphoSDK

Get the SDK instance (lazy initialization).

get_vault_info ¶

get_vault_info(vault_address: str) -> VaultInfo

Get complete vault information.

Parameters:

Name	Type	Description	Default
`vault_address`	`str`	MetaMorpho vault address	required

Returns:

Type	Description
`VaultInfo`	VaultInfo with vault state

get_position ¶

get_position(
    vault_address: str, user: str | None = None
) -> VaultPosition

Get user's position in the vault.

Parameters:

Name	Type	Description	Default
`vault_address`	`str`	MetaMorpho vault address	required
`user`	`str \| None`	User address (defaults to wallet_address)	`None`

Returns:

Type	Description
`VaultPosition`	VaultPosition with shares and assets

deposit ¶

deposit(
    vault_address: str, amount: Decimal
) -> TransactionResult

Build a deposit transaction for a MetaMorpho vault.

This builds approve + deposit transactions. The approve TX authorizes the vault to pull the exact amount of underlying tokens.

Parameters:

Name	Type	Description	Default
`vault_address`	`str`	MetaMorpho vault address	required
`amount`	`Decimal`	Amount of underlying assets to deposit (in token units, e.g. 1000.0 USDC)	required

Returns:

Type	Description
`TransactionResult`	TransactionResult with transaction data for both approve and deposit

redeem ¶

redeem(
    vault_address: str, shares: Decimal | str
) -> TransactionResult

Build a redeem transaction for a MetaMorpho vault.

Parameters:

Name	Type	Description	Default
`vault_address`	`str`	MetaMorpho vault address	required
`shares`	`Decimal \| str`	Number of shares to redeem, or "all" to redeem all	required

Returns:

Type	Description
`TransactionResult`	TransactionResult with transaction data

build_approve_transaction ¶

build_approve_transaction(
    token: str, amount: Decimal, spender: str
) -> TransactionResult

Build an ERC20 approve transaction.

Parameters:

Name	Type	Description	Default
`token`	`str`	Token symbol or address	required
`amount`	`Decimal`	Amount to approve	required
`spender`	`str`	Address to approve	required

Returns:

Type	Description
`TransactionResult`	TransactionResult with transaction data

MetaMorphoConfig `dataclass` ¶

MetaMorphoConfig(chain: str, wallet_address: str)

Configuration for MetaMorpho adapter.

Attributes:

Name	Type	Description
`chain`	`str`	Blockchain network (ethereum, base)
`wallet_address`	`str`	User wallet address

__post_init__ ¶

__post_init__() -> None

Validate configuration.

TransactionResult `dataclass` ¶

TransactionResult(
    success: bool,
    tx_data: dict[str, Any] | None = None,
    gas_estimate: int = 0,
    description: str = "",
    error: str | None = None,
)

Result of a transaction build operation.

Attributes:

Name	Type	Description
`success`	`bool`	Whether operation succeeded
`tx_data`	`dict[str, Any] \| None`	Transaction data (to, value, data)
`gas_estimate`	`int`	Estimated gas
`description`	`str`	Human-readable description
`error`	`str \| None`	Error message if failed

to_dict ¶

to_dict() -> dict[str, Any]

Convert to dictionary.

MetaMorphoEvent `dataclass` ¶

MetaMorphoEvent(
    event_type: MetaMorphoEventType,
    event_name: str,
    log_index: int,
    transaction_hash: str,
    block_number: int,
    contract_address: str,
    data: dict[str, Any],
    raw_topics: list[str] = list(),
    raw_data: str = "",
)

Parsed MetaMorpho event.

MetaMorphoEventType ¶

Bases: Enum

MetaMorpho event types.

MetaMorphoReceiptParser ¶

MetaMorphoReceiptParser(**kwargs: Any)

Parser for MetaMorpho vault transaction receipts.

Extracts ERC-4626 Deposit/Withdraw events and ERC-20 Transfer/Approval events.

Example

parser = MetaMorphoReceiptParser() result = parser.parse_receipt(receipt) if result.success: for event in result.events: print(f"{event.event_name}: {event.data}")

Initialize the parser.

parse_receipt ¶

parse_receipt(
    receipt: dict[str, Any],
    timestamp: datetime | None = None,
) -> ParseResult

Parse a transaction receipt.

Parameters:

Name	Type	Description	Default
`receipt`	`dict[str, Any]`	Transaction receipt dictionary with 'logs' field	required
`timestamp`	`datetime \| None`	Optional timestamp for events	`None`

Returns:

Type	Description
`ParseResult`	ParseResult with parsed events

extract_deposit_data ¶

extract_deposit_data(
    receipt: dict[str, Any],
) -> dict | None

Extract deposit data from transaction receipt.

Called by ResultEnricher for VAULT_DEPOSIT intents.

Returns:

Type	Description
`dict \| None`	Dict with {assets, shares, share_price_raw} if found, None otherwise.
`dict \| None`	All values are in raw on-chain units (wei). share_price_raw is the
`dict \| None`	ratio of raw assets to raw shares -- to get a human-readable price,
`dict \| None`	normalize by asset and share decimals.

extract_redeem_data ¶

extract_redeem_data(receipt: dict[str, Any]) -> dict | None

Extract redeem data from transaction receipt.

Called by ResultEnricher for VAULT_REDEEM intents.

Returns:

Type	Description
`dict \| None`	Dict with {shares_burned, assets_received} if found, None otherwise

ParseResult `dataclass` ¶

ParseResult(
    success: bool,
    events: list[MetaMorphoEvent] = list(),
    error: str | None = None,
    transaction_hash: str = "",
    block_number: int = 0,
)

Result of parsing a transaction receipt.

TransferEventData `dataclass` ¶

TransferEventData(
    from_address: str, to_address: str, amount: Decimal
)

Parsed data from ERC-20 Transfer event.

VaultDepositEventData `dataclass` ¶

VaultDepositEventData(
    sender: str,
    owner: str,
    assets: Decimal,
    shares: Decimal,
)

Parsed data from ERC-4626 Deposit event.

VaultWithdrawEventData `dataclass` ¶

VaultWithdrawEventData(
    sender: str,
    receiver: str,
    owner: str,
    assets: Decimal,
    shares: Decimal,
)

Parsed data from ERC-4626 Withdraw event.

DepositExceedsCapError ¶

Bases: MetaMorphoSDKError

Raised when deposit amount exceeds vault's maxDeposit.

InsufficientSharesError ¶

Bases: MetaMorphoSDKError

Raised when redeem amount exceeds user's maxRedeem.

MetaMorphoSDK ¶

MetaMorphoSDK(gateway_client, chain: str)

Low-level SDK for reading MetaMorpho vault state via gateway RPC calls.

All RPC calls are routed through the gateway client's RPC service. This SDK handles ABI encoding/decoding and provides typed return values.

Parameters:

Name	Type	Description	Default
`gateway_client`		Connected gateway client with RPC service	required
`chain`	`str`	Chain identifier (e.g., "ethereum", "base")	required

get_vault_asset ¶

get_vault_asset(vault_address: str) -> str

Read the vault's underlying asset address (asset()).

get_total_assets ¶

get_total_assets(vault_address: str) -> int

Read the vault's total assets (totalAssets()).

get_total_supply ¶

get_total_supply(vault_address: str) -> int

Read the vault's total share supply (totalSupply()).

get_share_price ¶

get_share_price(vault_address: str) -> int

Get share price as convertToAssets(one_share) in raw underlying units.

get_decimals ¶

get_decimals(vault_address: str) -> int

Read the vault's share decimals (decimals()). Always 18 for MetaMorpho.

get_balance_of ¶

get_balance_of(vault_address: str, user: str) -> int

Read user's share balance in the vault.

get_max_deposit ¶

get_max_deposit(vault_address: str, receiver: str) -> int

Read maximum deposit amount allowed for a receiver.

get_max_redeem ¶

get_max_redeem(vault_address: str, owner: str) -> int

Read maximum shares that can be redeemed by an owner.

preview_deposit ¶

preview_deposit(vault_address: str, assets: int) -> int

Preview how many shares a deposit of assets would mint.

preview_redeem ¶

preview_redeem(vault_address: str, shares: int) -> int

Preview how many assets a redemption of shares would return.

convert_to_assets ¶

convert_to_assets(vault_address: str, shares: int) -> int

Convert share amount to asset amount.

convert_to_shares ¶

convert_to_shares(vault_address: str, assets: int) -> int

Convert asset amount to share amount.

get_curator ¶

get_curator(vault_address: str) -> str

Read the vault's curator address.

get_fee ¶

get_fee(vault_address: str) -> int

Read the vault's performance fee (WAD scale, 1e18 = 100%).

get_timelock ¶

get_timelock(vault_address: str) -> int

Read the vault's timelock duration in seconds.

is_allocator ¶

is_allocator(vault_address: str, address: str) -> bool

Check if an address is an allocator for the vault.

get_supply_queue ¶

get_supply_queue(vault_address: str) -> list[str]

Read the vault's supply queue (list of market IDs).

get_withdraw_queue ¶

get_withdraw_queue(vault_address: str) -> list[str]

Read the vault's withdraw queue (list of market IDs).

get_vault_info ¶

get_vault_info(vault_address: str) -> VaultInfo

Read complete vault information in multiple RPC calls.

get_position ¶

get_position(
    vault_address: str, user: str
) -> VaultPosition

Read a user's position in the vault.

build_deposit_tx ¶

build_deposit_tx(
    vault_address: str, assets: int, receiver: str
) -> dict

Build an unsigned ERC-4626 deposit(uint256,address) transaction.

Parameters:

Name	Type	Description	Default
`vault_address`	`str`	The MetaMorpho vault address.	required
`assets`	`int`	Amount of underlying assets to deposit (raw units).	required
`receiver`	`str`	Address to receive vault shares.	required

Returns:

Type	Description
`dict`	Unsigned transaction dict with keys: to, from, data, value, gas_estimate.

build_redeem_tx ¶

build_redeem_tx(
    vault_address: str,
    shares: int,
    receiver: str,
    owner: str,
) -> dict

Build an unsigned ERC-4626 redeem(uint256,address,address) transaction.

Parameters:

Name	Type	Description	Default
`vault_address`	`str`	The MetaMorpho vault address.	required
`shares`	`int`	Number of shares to redeem (raw units).	required
`receiver`	`str`	Address to receive underlying assets.	required
`owner`	`str`	Address that owns the shares being redeemed.	required

Returns:

Type	Description
`dict`	Unsigned transaction dict with keys: to, from, data, value, gas_estimate.

build_approve_tx ¶

build_approve_tx(
    token_address: str,
    spender: str,
    amount: int,
    owner: str,
) -> dict

Build an ERC-20 approve transaction.

Parameters:

Name	Type	Description	Default
`token_address`	`str`	The ERC-20 token address.	required
`spender`	`str`	The address to approve.	required
`amount`	`int`	Amount to approve (raw units).	required
`owner`	`str`	The address that owns the tokens (tx sender).	required

Returns:

Type	Description
`dict`	Unsigned transaction dict.

MetaMorphoSDKError ¶

Bases: Exception

Base exception for MetaMorpho SDK errors.

RPCError ¶

Bases: MetaMorphoSDKError

Raised when an RPC call fails.

UnsupportedChainError ¶

Bases: MetaMorphoSDKError

Raised when chain is not supported.

VaultInfo `dataclass` ¶

VaultInfo(
    address: str,
    asset: str,
    total_assets: int,
    total_supply: int,
    share_price: int,
    decimals: int,
    curator: str,
    fee: int,
    timelock: int,
)

Information about a MetaMorpho vault.

VaultMarketConfig `dataclass` ¶

VaultMarketConfig(
    market_id: str,
    cap: int,
    enabled: bool,
    removable_at: int,
)

Market configuration within a MetaMorpho vault (Phase 2).

VaultNotFoundError ¶

Bases: MetaMorphoSDKError

Raised when vault contract does not exist or returns invalid data.

VaultPosition `dataclass` ¶

VaultPosition(
    vault_address: str, user: str, shares: int, assets: int
)

User position in a MetaMorpho vault.

create_test_adapter ¶

create_test_adapter(
    chain: str = "ethereum",
    wallet_address: str = "0x1234567890123456789012345678901234567890",
) -> MetaMorphoAdapter

Create a test adapter without gateway client (for unit tests).

For unit testing only. On-chain operations will raise RuntimeError.

Parameters:

Name	Type	Description	Default
`chain`	`str`	Chain name (default: ethereum)	`'ethereum'`
`wallet_address`	`str`	Wallet address (default: test address)	`'0x1234567890123456789012345678901234567890'`

Returns:

Type	Description
`MetaMorphoAdapter`	MetaMorphoAdapter configured for testing

Morpho Vault¶

almanak.framework.connectors.morpho_vault ¶

Initialize adapter¶

Deposit assets¶

Redeem all shares¶

Parse transaction receipts¶

MetaMorphoAdapter ¶

Get vault info¶

Deposit¶

sdk property ¶

get_vault_info ¶

get_position ¶

deposit ¶

redeem ¶

build_approve_transaction ¶

MetaMorphoConfig dataclass ¶

__post_init__ ¶

TransactionResult dataclass ¶

to_dict ¶

MetaMorphoEvent dataclass ¶

MetaMorphoEventType ¶

MetaMorphoReceiptParser ¶

parse_receipt ¶

extract_deposit_data ¶

extract_redeem_data ¶

ParseResult dataclass ¶

TransferEventData dataclass ¶

VaultDepositEventData dataclass ¶

VaultWithdrawEventData dataclass ¶

DepositExceedsCapError ¶

InsufficientSharesError ¶

MetaMorphoSDK ¶

get_vault_asset ¶

get_total_assets ¶

get_total_supply ¶

get_share_price ¶

get_decimals ¶

get_balance_of ¶

get_max_deposit ¶

get_max_redeem ¶

preview_deposit ¶

preview_redeem ¶

convert_to_assets ¶

convert_to_shares ¶

get_curator ¶

get_fee ¶

get_timelock ¶

is_allocator ¶

get_supply_queue ¶

get_withdraw_queue ¶

get_vault_info ¶

get_position ¶

build_deposit_tx ¶

build_redeem_tx ¶

build_approve_tx ¶

MetaMorphoSDKError ¶

RPCError ¶

UnsupportedChainError ¶

VaultInfo dataclass ¶

VaultMarketConfig dataclass ¶

VaultNotFoundError ¶

VaultPosition dataclass ¶

create_test_adapter ¶

sdk `property` ¶

MetaMorphoConfig `dataclass` ¶

TransactionResult `dataclass` ¶

MetaMorphoEvent `dataclass` ¶

ParseResult `dataclass` ¶

TransferEventData `dataclass` ¶

VaultDepositEventData `dataclass` ¶

VaultWithdrawEventData `dataclass` ¶

VaultInfo `dataclass` ¶

VaultMarketConfig `dataclass` ¶

VaultPosition `dataclass` ¶