MetaWallet Hooks Python Library

A Python library for building transaction data for MetaWallet hook executions.

This library only generates calldata - it does NOT execute transactions.

Installation

pip install -e .

Quick Start

from metawallet_hooks import (
    MetaWalletHookBuilder,
    ApproveAndDepositData,
    HookExecution,
)

# Initialize builder
builder = MetaWalletHookBuilder(metawallet_address="0x...")

# Create deposit data
deposit = ApproveAndDepositData(
    vault="0x...",
    assets=1000 * 10**6,  # 1000 USDC
    receiver="0x...",
    min_shares=0
)

# Build transaction data
tx_data = builder.build_execute_hooks([HookExecution.deposit(deposit)])

# Use with your own execution infrastructure
print(f"To: {tx_data.to}")
print(f"Calldata: 0x{tx_data.data.hex()}")
print(f"Value: {tx_data.value}")

# Or export as dictionary
tx_dict = tx_data.to_dict()  # {'to': '0x...', 'data': '0x...', 'value': 0}

Hook Types

ERC4626 Deposit Hook

Deposits assets into ERC-4626 vaults:

deposit = ApproveAndDepositData(
    vault="0x...",           # ERC4626 vault address
    assets=1000 * 10**6,     # Amount to deposit
    receiver="0x...",        # Who receives the shares
    min_shares=900 * 10**18  # Slippage protection
)

ERC4626 Redeem Hook

Redeems shares from ERC-4626 vaults:

redeem = RedeemData(
    vault="0x...",           # ERC4626 vault address
    shares=500 * 10**18,     # Shares to redeem
    receiver="0x...",        # Who receives the assets
    owner="0x...",           # Owner of the shares
    min_assets=450 * 10**6   # Slippage protection
)

1inch Swap Hook

Executes swaps via 1inch Aggregation Router:

swap = SwapData(
    router="0x...",          # 1inch router address
    src_token="0x...",       # Source token
    dst_token="0x...",       # Destination token
    amount_in=1000 * 10**6,  # Amount to swap
    min_amount_out=...,      # Slippage protection
    receiver="0x...",        # Who receives output
    value=0,                 # ETH value (for ETH swaps)
    swap_calldata=b"..."     # Calldata from 1inch API
)

Hook Chaining with Dynamic Amounts

Hooks can be chained, with each hook's output feeding into the next:

from metawallet_hooks import HookChainBuilder, SwapData, ApproveAndDepositData

# Swap USDC -> WETH, then deposit ALL received WETH into vault
chain = (HookChainBuilder()
    .add_swap(SwapData(
        router="0x...",
        src_token=USDC,
        dst_token=WETH,
        amount_in=5000 * 10**6,
        min_amount_out=1.5 * 10**18,
        receiver=METAWALLET,
        value=0,
        swap_calldata=calldata
    ))
    .add_deposit(ApproveAndDepositData.with_dynamic_amount(
        vault=WETH_VAULT,
        receiver=METAWALLET,
        min_shares=0
    ))
    .build())

tx_data = builder.build_execute_hooks(chain)

Constants

• USE_PREVIOUS_HOOK_OUTPUT: Special value (2^256 - 1) indicating the amount should be read from the previous hook's output
• NATIVE_ETH: Sentinel address for native ETH in swaps (0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE)
• DEPOSIT_HOOK_ID: Standard hook ID for deposit operations
• REDEEM_HOOK_ID: Standard hook ID for redeem operations
• SWAP_HOOK_ID: Standard hook ID for swap operations

API Reference

MetaWalletHookBuilder

Method	Description
build_execute_hooks(hooks)	Build calldata for hook execution
build_execute_chain(builder)	Build calldata from HookChainBuilder
build_install_hook(hook_id, address)	Build calldata for installing a hook
build_uninstall_hook(hook_id)	Build calldata for uninstalling a hook
build_get_hook(hook_id)	Build calldata for querying hook address
build_get_installed_hooks()	Build calldata for listing all hooks

HookChainBuilder

Method	Description
add_deposit(data)	Add deposit hook to chain
add_redeem(data)	Add redeem hook to chain
add_swap(data)	Add swap hook to chain
add_custom(name, data)	Add custom hook to chain
build()	Build and return hook list

TransactionData

Property	Description
to	Target contract address
data	Encoded calldata (bytes)
value	ETH value to send (wei)
to_dict()	Export as dictionary for web3.py

Standalone Functions

from metawallet_hooks import (
    encode_hook_execution_calldata,
    encode_install_hook_calldata,
    encode_uninstall_hook_calldata,
)

# Encode without needing the builder
calldata = encode_hook_execution_calldata(hooks)

License

MIT