A hybrid smart contract combining the benefits of an ERC-4626 tokenized vault with the flexibility of a smart wallet for fund management.

MetaWallet enables institutional fund managers to operate a vault that accepts user deposits while maintaining full flexibility to deploy capital across DeFi strategies. It features:

• ERC-4626 Vault: Standard deposit/redeem flow with share-based accounting
• Smart Wallet: Arbitrary execution capabilities for strategy management
• Virtual Accounting: totalAssets remains stable during invest/divest operations
• Hook System: Modular, chainable hooks for strategy interactions
• Merkle Proof Settlements: Off-chain attestation of external holdings

┌─────────────────────────────────────────────────────────────────┐
│                         MetaWallet                              │
├─────────────────────────────────────────────────────────────────┤
│  MinimalSmartAccount    │  HookExecution   │  MultiFacetProxy   │
│  (execution + roles)    │  (hook system)   │  (modules)         │
└─────────────────────────────────────────────────────────────────┘
                                 │
                    ┌────────────┴────────────┐
                    ▼                         ▼
              VaultModule                   Hooks
         (ERC4626 + accounting)     (ERC4626, 1inch Swap)

MetaWallet uses a minimalistic virtual accounting model:

totalAssets = virtualTotalAssets (stored value)
totalIdle   = asset.balanceOf(vault)

1. Deposits (deposit/mint): Increase virtualTotalAssets
2. Redemptions (redeem/withdraw): Decrease virtualTotalAssets
3. Invest/Divest: totalAssets remains unchanged
4. Settlements: Manager updates virtualTotalAssets via settleTotalAssets()

This design ensures share price stability during strategy operations, which is critical for cross-chain deployments where assets may be "in flight".

Note: WHITELISTED_ROLE and EXECUTOR_ROLE share the same role slot (_ROLE_1), so granting one automatically grants the other.

// Deposit USDC and receive shares
vault.deposit(1000e6, user);

// Redeem shares for USDC (limited by totalIdle)
vault.redeem(shares, user, user);

Redemptions are limited by totalIdle - users can only withdraw up to the actual USDC balance in the vault.

ERC4626ApproveAndDepositHook.ApproveAndDepositData memory data =
    ERC4626ApproveAndDepositHook.ApproveAndDepositData({
        vault: EXTERNAL_VAULT,
        assets: 5000e6,
        receiver: address(metaWallet),
        minShares: 0
    });

IHookExecution.HookExecution[] memory hooks = new IHookExecution.HookExecution[](1);
hooks[0] = IHookExecution.HookExecution({
    hookId: keccak256("hook.erc4626.deposit"),
    data: abi.encode(data)
});

metaWallet.executeWithHookExecution(hooks);

OneInchSwapHook.SwapData memory swapData = OneInchSwapHook.SwapData({
    router: ONEINCH_ROUTER,
    srcToken: USDC,
    dstToken: WETH,
    amountIn: 1000e6,
    minAmountOut: 0.5 ether,  // Slippage protection
    receiver: address(metaWallet),
    value: 0,  // ETH value for native swaps
    swapCalldata: oneInchCalldata  // Pre-built 1inch API calldata
});

IHookExecution.HookExecution[] memory hooks = new IHookExecution.HookExecution[](1);
hooks[0] = IHookExecution.HookExecution({
    hookId: keccak256("hook.oneinch.swap"),
    data: abi.encode(swapData)
});

metaWallet.executeWithHookExecution(hooks);

The swap hook supports:

• Static amounts: Fixed input amount specified in amountIn
• Dynamic amounts: Use USE_PREVIOUS_HOOK_OUTPUT to chain with previous hooks
• Native ETH swaps: Set srcToken to 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE and value to the ETH amount
• Slippage protection: Set minAmountOut to enforce minimum output

// Update totalAssets to reflect gains/losses
address[] memory strategies = new address[](2);
uint256[] memory values = new uint256[](2);
strategies[0] = VAULT_A;
strategies[1] = VAULT_B;
values[0] = 5000e6;
values[1] = 3000e6;

uint256 newTotalAssets = totalIdle + values[0] + values[1];
bytes32 merkleRoot = metaWallet.computeMerkleRoot(strategies, values);

metaWallet.settleTotalAssets(newTotalAssets, merkleRoot);

// Emergency pause (blocks all user operations)
metaWallet.pause();

// Resume operations
metaWallet.unpause();

External holdings can be validated against the stored merkle root:

address[] memory strategies = new address[](2);
uint256[] memory values = new uint256[](2);
strategies[0] = VAULT_A;
strategies[1] = VAULT_B;
values[0] = 5000e6;
values[1] = 3000e6;

bool valid = metaWallet.validateTotalAssets(strategies, values, merkleRoot);

forge build

forge test

forge fmt

forge doc --serve

MetaWallet uses CREATE2 for deterministic addresses across multiple chains. The deployment process involves:

1. Deploy implementation contracts (once per chain)
2. Deploy proxy via factory (same address on all chains)

Create a .env file:

# Required
PRIVATE_KEY=0x...
FACTORY_ADDRESS=0x...      # MinimalSmartAccountFactory (same on all chains)
REGISTRY_ADDRESS=0x...     # Your registry contract
ASSET_ADDRESS=0x...        # Underlying asset (e.g., USDC)

# Optional
DEPLOY_SALT=0              # Custom salt for deterministic address
OWNER_ADDRESS=0x...        # Defaults to deployer
VAULT_NAME="Meta USDC"
VAULT_SYMBOL="mUSDC"

# RPC URLs
MAINNET_RPC_URL=https://...
ARBITRUM_RPC_URL=https://...
OPTIMISM_RPC_URL=https://...
BASE_RPC_URL=https://...
POLYGON_RPC_URL=https://...
SEPOLIA_RPC_URL=https://...

# Block Explorer API Keys (for verification)
ETHERSCAN_API_KEY=...
ARBISCAN_API_KEY=...

Deploy everything in a single transaction:

# Deploy to testnet first
make deploy-all-sepolia

# Deploy to mainnet
make deploy-all-mainnet

This deploys:

1. MetaWallet implementation
2. VaultModule implementation
3. Proxy via CREATE2 factory
4. ERC4626 deposit/redeem hooks

The proxy address is deterministic - use the same DEPLOY_SALT and deployer on all chains to get the same address.

If you prefer more control, deploy in steps:

Deploy the MetaWallet implementation and VaultModule to each chain:

# Deploy to Sepolia (testnet)
make deploy-impl-sepolia

# Deploy to mainnet
make deploy-impl-mainnet

# Deploy to all mainnets
make deploy-impl-all

Save the deployed addresses:

• IMPLEMENTATION_ADDRESS - MetaWallet implementation
• VAULT_MODULE_ADDRESS - VaultModule implementation

The proxy deployment requires additional environment variables:

# Add to .env
FACTORY_ADDRESS=0x...          # MinimalSmartAccountFactory (same on all chains)
IMPLEMENTATION_ADDRESS=0x...   # From step 1
VAULT_MODULE_ADDRESS=0x...     # From step 1
REGISTRY_ADDRESS=0x...         # Your registry contract
ASSET_ADDRESS=0x...            # Underlying asset (e.g., USDC)

# Optional
DEPLOY_SALT=0                  # Custom salt for deterministic address
OWNER_ADDRESS=0x...            # Defaults to deployer
VAULT_NAME="Meta USDC"
VAULT_SYMBOL="mUSDC"

Predict the proxy address before deploying:

make predict-address

Deploy the proxy (same address on all chains with same salt):

# Deploy proxy only
make deploy-proxy-sepolia

# Deploy proxy with ERC4626 hooks
make deploy-full-sepolia

# Deploy to all mainnets
make deploy-proxy-all

If you deployed without hooks, you can add them later:

# Add to .env
METAWALLET_ADDRESS=0x...  # Deployed proxy address

# Deploy hooks
make deploy-hooks-mainnet

# Install hooks (requires DEPOSIT_HOOK_ADDRESS, REDEEM_HOOK_ADDRESS)
make install-hooks-mainnet

To deploy to the same address on multiple chains:

1. Use the same DEPLOY_SALT on all chains
2. Use the same deployer address (PRIVATE_KEY)
3. Ensure the factory is deployed at the same address on all chains

# Predict address first
FACTORY_ADDRESS=0x... DEPLOYER_ADDRESS=0x... DEPLOY_SALT=0 make predict-address

# Deploy to each chain (will have same address)
make deploy-proxy-mainnet
make deploy-proxy-arbitrum
make deploy-proxy-optimism
make deploy-proxy-base
make deploy-proxy-polygon

Test deployment without broadcasting by adding -dry-run suffix to any deployment command:

# Full deployment dry-run
make deploy-localhost-dry-run
make deploy-sepolia-dry-run
make deploy-mainnet-dry-run

# Step-by-step dry-run
make deploy-impl-localhost-dry-run
make deploy-proxy-sepolia-dry-run
make deploy-hooks-sepolia-dry-run

Deployment addresses are saved to deployments/output/{network}/{accountId}.json:

deployments/
├── config/
│   ├── localhost.json
│   ├── sepolia.json
│   └── mainnet.json
└── output/
    ├── localhost/
    │   └── metawallet.v1.json
    └── sepolia/
        └── metawallet.v1.json

The accountId is configured in the network config file (e.g., vault.accountId: "metawallet.v1"). This allows multiple MetaWallet instances to be deployed on the same chain with different accountIds.

• solady - Gas-optimized libraries
• minimal-smart-account - Smart wallet base
• kam - Multi-facet proxy and modules

MIT