> For the complete documentation index, see [llms.txt](https://docs.greenowl.money/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.greenowl.money/interfaces/interfaces/iwalletfactory.md).

# IWalletFactory

**Interface for the SmartWalletFactory contract**

The `IWalletFactory` interface defines the standard for deploying and managing Owl Smart Wallets using ERC-4337's deterministic CREATE2 deployment pattern. It is the primary interface used by AI agents, MCP servers, and integrators to deploy new smart wallets and track wallet ownership.

## Overview

The factory serves as the **single source of truth** for wallet deployments in the Owl ecosystem. It:

* **Deploys wallets deterministically** via CREATE2, enabling counterfactual address computation before deployment
* **Tracks wallet ownership** through mappings updated when ownership transfers occur
* **Manages wallet upgrades** by maintaining a canonical implementation address that wallets can upgrade to
* **Integrates with ERC-4337** EntryPoint for gasless wallet creation via UserOperations
* **Supports guardian recovery** by allowing an optional guardian to be set at deployment time

This interface is used by:

* **MCP servers** (`owl-wallet`) to deploy wallets for AI agents
* **Frontend clients** to compute wallet addresses before deployment
* **Bundlers** to validate `initCode` in UserOperations
* **Wallets** to notify the factory of ownership changes

***

## Key Differences from IWalletFactoryV2

* Single guardian at deploy (not array)
* No timelock on implementation changes
* Simplified `createWallet` signature

***

## State Functions

### ENTRY\_POINT

Returns the immutable EntryPoint contract address used for ERC-4337 operations.

```solidity
function ENTRY_POINT() external view returns (IEntryPoint);
```

**Returns**

| Name     | Type          | Description                      |
| -------- | ------------- | -------------------------------- |
| `<none>` | `IEntryPoint` | The ERC-4337 EntryPoint contract |

***

### SENDER\_CREATOR

Returns the immutable SenderCreator contract address used by EntryPoint for CREATE2 deployments.

```solidity
function SENDER_CREATOR() external view returns (ISenderCreator);
```

**Returns**

| Name     | Type             | Description                |
| -------- | ---------------- | -------------------------- |
| `<none>` | `ISenderCreator` | The SenderCreator contract |

**Usage Note:** This address is authorized to call internal factory functions during wallet deployment via EntryPoint.

***

### WALLET\_IMPLEMENTATION

Returns the initial wallet implementation set at factory deployment (immutable).

```solidity
function WALLET_IMPLEMENTATION() external view returns (address);
```

**Returns**

| Name     | Type      | Description                        |
| -------- | --------- | ---------------------------------- |
| `<none>` | `address` | The initial implementation address |

***

### walletImplementation

Returns the **current** wallet implementation address for upgrades. Wallets call `upgradeToLatest()` to upgrade to this implementation.

```solidity
function walletImplementation() external view returns (address);
```

**Returns**

| Name     | Type      | Description                                    |
| -------- | --------- | ---------------------------------------------- |
| `<none>` | `address` | The current upgradeable implementation address |

**Usage Note:** AI agents should check this before triggering wallet upgrades via MCP tools.

***

### isValidWallet

Returns whether a wallet address was deployed by this factory.

```solidity
function isValidWallet(address wallet) external view returns (bool);
```

**Parameters**

| Name     | Type      | Description                 |
| -------- | --------- | --------------------------- |
| `wallet` | `address` | The wallet address to check |

**Returns**

| Name     | Type   | Description                                       |
| -------- | ------ | ------------------------------------------------- |
| `<none>` | `bool` | `true` if the wallet was deployed by this factory |

**Security Note:** Only wallets returning `true` can call `notifyOwnershipTransfer()`.

***

### totalWallets

Returns the total number of wallets deployed by this factory.

```solidity
function totalWallets() external view returns (uint256);
```

**Returns**

| Name     | Type      | Description                 |
| -------- | --------- | --------------------------- |
| `<none>` | `uint256` | The cumulative wallet count |

***

### version

Returns the factory contract version.

```solidity
function version() external pure returns (uint256);
```

**Returns**

| Name     | Type      | Description        |
| -------- | --------- | ------------------ |
| `<none>` | `uint256` | The version number |

***

## Deployment Functions

### getWalletAddress

Computes the **deterministic** wallet address for given parameters without deploying. Uses CREATE2 for counterfactual address computation.

```solidity
function getWalletAddress(
    address walletOwner,
    address guardian,
    uint256 salt
) external view returns (address);
```

**Parameters**

| Name          | Type      | Description                                      |
| ------------- | --------- | ------------------------------------------------ |
| `walletOwner` | `address` | The ECDSA owner address (EOA or contract)        |
| `guardian`    | `address` | Initial guardian address (`address(0)` for none) |
| `salt`        | `uint256` | Additional entropy for CREATE2                   |

**Returns**

| Name     | Type      | Description                 |
| -------- | --------- | --------------------------- |
| `<none>` | `address` | The computed wallet address |

**Usage:** AI agents use this to compute wallet addresses before deployment, enabling "send funds first, deploy later" patterns.

***

### getInitCode

Returns the ERC-4337 `initCode` bytes for including in a UserOperation.

```solidity
function getInitCode(
    address walletOwner,
    address guardian,
    uint256 salt
) external view returns (bytes memory);
```

**Parameters**

| Name          | Type      | Description                                      |
| ------------- | --------- | ------------------------------------------------ |
| `walletOwner` | `address` | The ECDSA owner address                          |
| `guardian`    | `address` | Initial guardian address (`address(0)` for none) |
| `salt`        | `uint256` | Additional entropy for CREATE2                   |

**Returns**

| Name     | Type    | Description                               |
| -------- | ------- | ----------------------------------------- |
| `<none>` | `bytes` | The `initCode` for ERC-4337 UserOperation |

**Usage:** MCP servers construct UserOperations with this `initCode` for gasless wallet deployment via bundlers.

***

### createWallet

Deploys a new SmartWallet using CREATE2.

```solidity
function createWallet(
    address walletOwner,
    address guardian,
    uint256 salt
) external returns (address wallet);
```

**Parameters**

| Name          | Type      | Description                                      |
| ------------- | --------- | ------------------------------------------------ |
| `walletOwner` | `address` | The ECDSA owner address                          |
| `guardian`    | `address` | Optional initial guardian (`address(0)` to skip) |
| `salt`        | `uint256` | Additional salt for CREATE2                      |

**Returns**

| Name     | Type      | Description                 |
| -------- | --------- | --------------------------- |
| `wallet` | `address` | The deployed wallet address |

**Access Control:** Can be called directly or via EntryPoint's SenderCreator during UserOperation execution.

**Reverts:**

* `WalletExists()` if wallet already exists at computed address
* `ZeroAddress()` if `walletOwner` is zero

**Emits:** `WalletDeployed(wallet, walletOwner, guardian, salt)`

***

## Owner Query Functions

### getWalletsForOwner

Returns all wallet addresses deployed for a specific owner.

```solidity
function getWalletsForOwner(address walletOwner) external view returns (address[] memory);
```

**Parameters**

| Name          | Type      | Description                |
| ------------- | --------- | -------------------------- |
| `walletOwner` | `address` | The owner address to query |

**Returns**

| Name     | Type        | Description               |
| -------- | ----------- | ------------------------- |
| `<none>` | `address[]` | Array of wallet addresses |

**Usage:** AI agents use this to discover all wallets associated with an owner, enabling multi-wallet management strategies.

***

## Admin Functions

### initialize

Initializes the factory with an owner address.

```solidity
function initialize(address owner_) external;
```

**Parameters**

| Name     | Type      | Description           |
| -------- | --------- | --------------------- |
| `owner_` | `address` | Factory owner address |

**Access Control:** Called once during deployment (initializer pattern).

***

### setWalletImplementation

Updates the canonical wallet implementation address used for upgrades.

```solidity
function setWalletImplementation(address newImplementation) external;
```

**Parameters**

| Name                | Type      | Description                       |
| ------------------- | --------- | --------------------------------- |
| `newImplementation` | `address` | New wallet implementation address |

**Access Control:** Only factory owner.

**Validation:**

* New implementation must have code
* New implementation version must be higher than current

**Reverts:**

* `InvalidImplementation()` if implementation has no code
* `VersionNotHigher()` if version is not greater than current

**Emits:** `WalletImplementationUpdated(oldImplementation, newImplementation)`

**Security Note:** No timelock required. Wallets must manually opt-in to upgrades via `upgradeToLatest()`.

***

### pause

Pauses all wallet deployments.

```solidity
function pause() external;
```

**Access Control:** Only factory owner.

***

### unpause

Resumes wallet deployments.

```solidity
function unpause() external;
```

**Access Control:** Only factory owner.

***

## Wallet Callback Functions

### notifyOwnershipTransfer

Called by wallets when ownership changes to update factory mappings.

```solidity
function notifyOwnershipTransfer(
    address previousOwner,
    address newOwner
) external;
```

**Parameters**

| Name            | Type      | Description                |
| --------------- | --------- | -------------------------- |
| `previousOwner` | `address` | The previous owner address |
| `newOwner`      | `address` | The new owner address      |

**Access Control:** Only callable by valid wallets deployed by this factory (checked via `isValidWallet(msg.sender)`).

**Reverts:**

* `InvalidWallet()` if caller is not a factory-deployed wallet

**Emits:** `WalletOwnershipTransferred(wallet, previousOwner, newOwner)`

**Usage:** Automatically called by SmartWallet's `transferOwnership()` function to keep factory mappings synchronized.

***

## Events

### WalletDeployed

Emitted when a new wallet is deployed.

```solidity
event WalletDeployed(
    address indexed wallet,
    address indexed walletOwner,
    address indexed guardian,
    uint256 salt
);
```

**Parameters**

| Name          | Type      | Description                          |
| ------------- | --------- | ------------------------------------ |
| `wallet`      | `address` | The deployed wallet address          |
| `walletOwner` | `address` | The owner address of the wallet      |
| `guardian`    | `address` | Initial guardian (or `address(0)`)   |
| `salt`        | `uint256` | The salt used for CREATE2 deployment |

***

### WalletImplementationUpdated

Emitted when the canonical wallet implementation is updated.

```solidity
event WalletImplementationUpdated(
    address indexed oldImplementation,
    address indexed newImplementation
);
```

**Parameters**

| Name                | Type      | Description                     |
| ------------------- | --------- | ------------------------------- |
| `oldImplementation` | `address` | Previous implementation address |
| `newImplementation` | `address` | New implementation address      |

***

### WalletOwnershipTransferred

Emitted when wallet ownership is transferred and factory mappings are updated.

```solidity
event WalletOwnershipTransferred(
    address indexed wallet,
    address indexed previousOwner,
    address indexed newOwner
);
```

**Parameters**

| Name            | Type      | Description            |
| --------------- | --------- | ---------------------- |
| `wallet`        | `address` | The wallet address     |
| `previousOwner` | `address` | Previous owner address |
| `newOwner`      | `address` | New owner address      |

***

## Errors

### ZeroAddress

Thrown when a zero address is provided where a valid address is required.

```solidity
error ZeroAddress();
```

***

### WalletExists

Thrown when attempting to deploy a wallet at an address that already exists.

```solidity
error WalletExists();
```

***

### InvalidImplementation

Thrown when an implementation address has no bytecode.

```solidity
error InvalidImplementation();
```

***

### MaxWalletsPerOwner

Thrown when an owner attempts to exceed the maximum allowed wallets per owner.

```solidity
error MaxWalletsPerOwer();
```

***

### VersionNotHigher

Thrown when attempting to set an implementation with a version not higher than the current version.

```solidity
error VersionNotHigher(uint256 currentVersion, uint256 newVersion);
```

**Parameters**

| Name             | Type      | Description                    |
| ---------------- | --------- | ------------------------------ |
| `currentVersion` | `uint256` | Current implementation version |
| `newVersion`     | `uint256` | Proposed new version           |

***

### NotSenderCreator

Thrown when the caller is not the authorized EntryPoint SenderCreator contract.

```solidity
error NotSenderCreator(address msgSender, address factory, address senderCreator);
```

**Parameters**

| Name            | Type      | Description                         |
| --------------- | --------- | ----------------------------------- |
| `msgSender`     | `address` | The actual caller address           |
| `factory`       | `address` | The factory contract address        |
| `senderCreator` | `address` | The expected sender creator address |

***

### InvalidWallet

Thrown when a caller is not a valid wallet deployed by this factory.

```solidity
error InvalidWallet();
```

**Context:** Used in `notifyOwnershipTransfer()` to prevent unauthorized mapping updates.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.greenowl.money/interfaces/interfaces/iwalletfactory.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.