Kernel v4 Modular Smart Account Framework

The certora/ directory is organized as follows:

• conf/: Contains certoraRun configuration files in JSON format.
• specs/: Contains CVL (Certora Verification Language) rules and invariants.
• harnesses/: Contains Solidity wrappers used when storage or inheritance tricks are required for verification.

Hooks allow for pre/post execution checks and bind to different components independently:

• Validator hook: Runs around executeUserOp when a non-root validator with a hook is used.
• Executor hook: Runs around executeFromExecutor for any installed executor.
• Fallback hook: Runs around fallback selector dispatch.

Sentinel values for hook addresses:

• address(0): Not installed.
• address(1): Installed with no hook.

The library provides several core contracts and utilities for ERC-4337 development:

• EntryPoint Contract (contracts/core/EntryPoint.sol): The central contract that processes UserOperations. It validates operations, handles account creation, executes operations, and manages gas.
• BaseAccount (contracts/core/BaseAccount.sol): Base implementation for smart contract accounts.
• BasePaymaster (contracts/core/BasePaymaster.sol): Helper class for creating a paymaster.
• StakeManager (contracts/core/StakeManager.sol): Manages deposits and stakes for accounts and paymasters.
• NonceManager (contracts/core/NonceManager.sol): Handles nonce management for accounts.
• UserOperationLib (contracts/core/UserOperationLib.sol): Utilities for working with UserOperations.
• Helpers (contracts/core/Helpers.sol): Common constants and helper functions.

Beyond standard validator modules, Kernel v4 uses a Permission System to enable granular session keys. A permission is a composition of:

1. One Signer
2. One or more Policies

This allows a dapp to be granted a signer that is restricted by specific policies (e.g., spending caps, time windows, or target restrictions) without requiring access to the account's root validator.

Kernel v4 is a modular smart account implementing ERC-7579. It uses six pluggable module types that can be installed or uninstalled at runtime to extend account functionality:

• Validator: Validates UserOps and signatures; owns a specific nonce key namespace.
• Executor: Performs actions on behalf of the account via executeFromExecutor.
• Fallback: Extends the account with new function selectors using call or delegatecall.
• Hook: Performs pre/post execution checks on validators, executors, and fallback selectors.
• Policy: Part of a permission; enforces rules like spending limits or target allowlists.
• Signer: Part of a permission; provides signature verification (e.g., passkey, multisig).

Kernel v4 provides three distinct account deployment patterns depending on your use case:

• KernelUUPS: A UUPS upgradeable proxy. Deployed via KernelFactory.deploy(). Supports the full module lifecycle and proxy upgrades via UserOp.
• KernelImmutableECDSA: An ERC-1967 clone with a fixed ECDSA fallback signer set at deployment. Users can call setRoot to change the validator, and the proxy remains UUPS-upgradeable. Deployed via KernelFactory.deployECDSA().
• Kernel7702: An EIP-7702 variant for EOA delegation. The EOA itself acts as the fallback signer (ECDSA.recover == address(this)). No initialization is required, and it supports raw ERC-1271 signatures.

To install the library using Foundry, run the following command.

Warning: Avoid using the master branch as it is a development branch and does not guarantee the same security measures as tagged releases. Additionally, subsequent forge update commands may default to the master branch.

After installation, you must add the following line to your remappings.txt file to ensure correct imports:

```bash
$ forge install OpenZeppelin/openzeppelin-contracts

Add @openzeppelin/contracts/=lib/openzeppelin-contracts/contracts/ in remappings.txt.

To generate and view coverage reports, use forge coverage with specific exclusions to focus on core logic, then use genhtml to create a visual report.

forge coverage \ 
  --no-match-coverage "(script|test|Foo|Bar|validator|sdk|signer)" \ 
  --report lcov

genhtml lcov.info \ 
  --output-directory coverage \ 
  --ignore-errors inconsistent \ 
  --ignore-errors corrupt

open coverage/index.html

Install the Forge Standard Library using the Forge CLI to use its helper contracts and libraries in your Foundry tests.

forge install foundry-rs/forge-std

The EntryPoint contract is the central hub for processing UserOperations. It is deployed using Hardhat:

hardhat deploy --network {net}

Note: EntryPoint v0.8 is always deployed at address 0x4337084d9e255ff0702461cf8895ce9e3b5ff108.