owl-wallet

The owl-wallet MCP server provides AI agents with direct access to the SmartWallet factory system. It enables agents to compute deterministic wallet addresses, generate deployment initCode, and query factory state — all without requiring direct smart contract interaction knowledge.

This server is designed for agents that need to:

• Deploy new smart wallets deterministically via ERC-4337

• Verify wallet addresses before deployment

• Generate UserOperation initCode for bundler submission

• Understand the wallet creation flow

---

Architecture Overview

The owl-wallet server acts as a read-only interface layer between AI agents and the deployed SmartWalletFactory contract. It translates high-level agent requests into web3 RPC calls, handles CREATE2 address computation, and formats responses in agent-friendly JSON.

Key capabilities:

• Deterministic address computation — Agents can predict wallet addresses before deployment

• initCode generation — Produces the exact calldata needed for ERC-4337 UserOperation deployment

• Factory state queries — Checks EntryPoint configuration, implementation addresses, and pause status

• Educational context — Provides human-readable explanations of the wallet creation process

---

Available Tools

Tool Name	Description
get_factory_state	Returns factory configuration including EntryPoint address, wallet implementation, guardian contract, and pause status
get_wallet_address	Computes the deterministic CREATE2 address for a wallet given owner, guardian, and salt parameters
get_init_code	Generates the complete initCode bytes for UserOperation deployment (factory address + calldata)
explain_create_flow	Returns a detailed explanation of the wallet creation process, CREATE2 mechanics, and deployment requirements

---

Setup and Configuration

Requirements

• Node.js 18+

• RPC URL for the target network (e.g., Base Sepolia, Base mainnet)

• Factory address — deployed SmartWalletFactory contract

• Chain ID — expected network identifier for validation

Installation

cd mcp/owl-wallet
npm install

Environment Variables

# Required
export RPC_URL="https://base-sepolia-rpc.publicnode.com"
export FACTORY_ADDRESS="0x..."  # Deployed SmartWalletFactory address
export EXPECTED_CHAIN_ID="84532"  # 84532 for Base Sepolia, 8453 for Base mainnet

Running the Server

Standard mode (stdio):

npm run dev

SSE/HTTP mode (Express server):

npm run start:sse

Production build:

npm run build
npm start

Development Commands

npm run lint       # Run ESLint
npm run typecheck  # Run TypeScript type checking

---

How AI Agents Use This Server

Typical Agent Workflow

1. Query factory state to verify the factory is operational and retrieve configuration

2. Compute wallet address using the agent's owner key, guardian address, and a unique salt

3. Check if wallet is deployed (via on-chain code check or balance query)

4. Generate initCode if wallet does not exist

5. Submit UserOperation with initCode to bundler for deployment

Example: Agent Deploying a New Wallet

// Step 1: Check factory state
const factoryState = await agent.call_tool("get_factory_state", {});
// Returns: { entryPoint, walletImplementation, guardian, paused: false }

// Step 2: Compute deterministic address
const address = await agent.call_tool("get_wallet_address", {
  owner: "0x1234...",  // Agent's P256 or ECDSA public key
  guardian: "0x5678...",  // Guardian contract address
  salt: "0x00...01"  // 32-byte unique identifier
});
// Returns: { address: "0xABCD..." }

// Step 3: Generate initCode for deployment
const initCode = await agent.call_tool("get_init_code", {
  owner: "0x1234...",
  guardian: "0x5678...",
  salt: "0x00...01"
});
// Returns: { initCode: "0x..." }  // Factory address + createAccount calldata

// Step 4: Agent constructs UserOperation with initCode and submits to bundler

Security Considerations

• Factory pause status — Agents must check paused state before attempting deployment

• Address verification — Always verify computed addresses match expected values

• Salt uniqueness — Using the same owner + guardian + salt will produce the same address; increment salt for multiple wallets

• initCode usage — initCode is only required for first-time deployment; omit for existing wallets

---

Tool Reference

get_factory_state

Returns the current configuration and operational status of the SmartWalletFactory.

Parameters: None

Returns:

{
  entryPoint: string;           // ERC-4337 EntryPoint address
  walletImplementation: string; // SmartWallet implementation address
  guardian: string;             // Guardian contract address
  paused: boolean;              // Whether factory is paused
}

Agent use case: Verify factory is operational before computing addresses or generating initCode.

---

get_wallet_address

Computes the deterministic CREATE2 address for a SmartWallet.

Parameters:

{
  owner: string;     // Owner public key or address (P256 or ECDSA)
  guardian: string;  // Guardian contract address
  salt: string;      // 32-byte hex salt (e.g., "0x00...01")
}

Returns:

{
  address: string;   // Computed wallet address
}

Agent use case: Predict wallet address before deployment, verify address matches expected value, check if wallet already exists.

---

get_init_code

Generates the complete initCode for UserOperation deployment.

Parameters:

{
  owner: string;     // Owner public key or address
  guardian: string;  // Guardian contract address
  salt: string;      // 32-byte hex salt
}

Returns:

{
  initCode: string;  // Factory address + createAccount calldata
}

Agent use case: Populate UserOperation.initCode field for first-time wallet deployment via ERC-4337 bundler.

Note: initCode should only be included in UserOperations when the wallet does not yet exist on-chain. For existing wallets, use empty bytes (0x).

---

explain_create_flow

Returns a human-readable explanation of the wallet creation process.

Parameters: None

Returns:

{
  explanation: string;  // Detailed explanation of CREATE2 deployment flow
}

Agent use case: Understand the wallet creation process, troubleshoot deployment issues, generate educational content for users.

---

Network Configuration

Base Sepolia (Testnet)

export RPC_URL="https://base-sepolia-rpc.publicnode.com"
export EXPECTED_CHAIN_ID="84532"
export FACTORY_ADDRESS="0x..."  # See deployment artifacts

Base Mainnet

export RPC_URL="https://mainnet.base.org"
export EXPECTED_CHAIN_ID="8453"
export FACTORY_ADDRESS="0x..."  # See deployment artifacts

---

Deployment Notes

• Factory must be unpaused for wallet deployment to succeed

• Wallet addresses are deterministic — same owner + guardian + salt = same address

• initCode is deployment-only — only required for first UserOperation; omit for existing wallets

• CREATE2 guarantees — addresses can be computed off-chain and verified on-chain before deployment

---

Related Documentation

• SmartWalletFactory Contract — On-chain factory implementation

• SmartWallet Contract — Core wallet contract

• ERC-4337 Overview — Account abstraction standard

• MCP Protocol — Model Context Protocol specification