# Kernel V2 Documentation

[TOC]

## Reference

- [ERC4337](https://eips.ethereum.org/EIPS/eip-4337)
- [code](https://github.com/zerodevapp/zerodev-wallet-kernel/tree/kernel_v2)

# Getting started

Deploying the Kernel is done through `KernelFactory` which deploys the EIP1967 Proxy and set the initial implementation contract as predefined `Kernel` code

## How to build the Validator Plugin

building a validator plugin can be creative but still there are things you should be aware of in terms of compatibility.
First, make sure you follow the `IKernelValidator` interface. [#](https://github.com/zerodevapp/zerodev-wallet-kernel/blob/kernel_v2/src/validator/IValidator.sol)

pragma solidity ^0.8.0;

import "account-abstraction/interfaces/UserOperation.sol";

interface IKernelValidator {
    function enable(bytes calldata _data) external;

    function disable(bytes calldata _data) external;

    function validateUserOp(UserOperation calldata userOp, bytes32 userOpHash, uint256 missingFunds)
        external
        returns (uint256);

    function validateSignature(bytes32 hash, bytes calldata signature) external view returns (uint256);
}

- **enable()** setting the data for the validator
- **disable()** disabling the data for validator
- **validateUserOp()** called while erc4337's validation phase, instead of sending the raw data, `userOp` will be plain signature that does not include the "mode" or overhead for the [enable mode](#Enable-mode).
- **validateSignature()** function for validating the off-chain signature, and for using the enable mode. if your plugin is not for defaultValidator, you can ignore this function

Since `Kernel` aims to be the erc4337 wallet, it should be noted that validator plugin should only access to the storage slot that is associated to the wallet's address.

For example, you cannot

bool enabled;
function validateUserOp(UserOperation calldata _op, ...) external {
    require(enabled);
}

but you can

mapping(address => bool) enabled;
function validateUserOp(UserOperation calldata _op, ...) external {
    require(enabled[_op.sender]);
}

Also, be aware that you are not allowed to use some opcodes like NUMBER, GAS, etc [#](https://eips.ethereum.org/EIPS/eip-4337#forbidden-opcodes)

## How to build the Executor Plugin

This is where you can be creative, there aren't any limit for opcodes nor any storage access rule to follow. **BUT** zerodev team strongly advise not to use any storage on executor plugin since executor is called with `DELEGATECALL` unlike the validator plugin being called with `CALL`. Which means, executor plugin can access storage in `Kernel` which may lead to weird behavior.

This does not mean you cannot use any `SLOAD` or `SSTORE`, just avoid using any storage inside the plugin for safety

## Registering the Plugin

If you finished developing the plugin, you have to register the plugin.
You can register in 2 ways
1. setExecution function
2. during validation phase

setExecution function will be straight forward, you'll be calling the `kernel.setExecution()` function with proper parameters and sign the userOp and pass it to bundler.

For example, If you are registering `ERC165SessionKey` to execute `ERC721Actions`, it will be like

`kernel.setExecution(ERC721Executor.transferERC721.selector, address(erc721Executor), erc165SessionKeyValidator)`

Or you can also set the executor and validator on validation phase using [enable mode](https://hackmd.io/joe9mwzPRCCA5Mw0JVWzBw#Enable-mode)

## Examples

### [ERC165SessionKeyValidator](https://github.com/zerodevapp/zerodev-wallet-kernel/blob/kernel_v2/src/validator/ERC165SessionKeyValidator.sol)
This is combination of sessionkey idea and erc165.

Session key is a trusted third party that can be allowed by the kernel which has limited access to certain actions like transferring erc721.

[ERC165](https://eips.ethereum.org/EIPS/eip-165) is used to check if given address is implementing certain interface. Which is a weak claim because given address can still fake if they are implementing the interface even though they are not.

Since session key should be assigned to trusted third party, deploying a fake address that does nothing but spending gas is less likely to happen.

### [KillSwitchValidator](https://github.com/zerodevapp/zerodev-wallet-kernel/blob/kernel_v2/src/validator/KillSwitchValidator.sol)
Instead of using plain ECDSA Validator as default validator, setting KillSwitchValidator is a nice option if you want a recovery option.

In usual cases, KillSwitchValidator will act same as ECDSA Validator which just checks the userOpHash has been signed by the owner.

When owner requests recovery to guardian, guardian will set the new address as owner and set the pausedUntil value,and set the disabled mode flag to make sure no other userOp can pass the validation phase

After `pausedUntil`, new owner can safely use the `Kernel` without any restriction

# Kernel V2 Design Choices

## Validation Modes

There are 3 modes in current Kernel implementation
- Sudo mode(0x00000000)
- Plugin mode(0x00000001)
- Enable mode(0x00000002)

"mode" will be determined by the first 4 bytes of `userOp.signature`, so if you are using the `ECDSAValidator ` as a `defaultValidator`, you should add 4 bytes of 0 to the signature to use the function properly

### Sudo mode
sudo mode is used to execute "any" function that is currently registered in the `Kernel`, this mode can only use the `defaultValidator` which has the most permission on the `Kernel`

This sudo mode should be audited precisely and implemented with care since using compromised code for the sudo might end up risking the `Kernel` itself.

### Plugin mode
Plugin mode is the mode enabled automatically with the function selector of the `userOp.callData`. Which should be set while doing the [Registering the plugin](#Registering-the-Plugin).

Just like the sudo mode, all it needs is the signature that will be used on validator

### Enable mode

Enable mode is for setting the plugin on validation phase to minimize the flow of using the plugin.

Enable mode requires the signature to be packed as following

|name|position|length|
|----|--------|------|
|mode|0 |4 |
|validUntil|4|6|
|validAfter|10|6|
|validatorAddress|16|20|
|executorAddress|36|20|
|enableDataLength|56|32|
|enableData|88|enableDataLength|
|enableSignatureLength|88+enableDataLength|32|
|enableSignature|120+enableDataLength|enableSignatureLength|
|validatorSignature|120 + enableDataLength + enableSignatureLength|

This mode will set the execution data and enble the validator with enableData.

And enableSignature should be the signature used by `defaultValidator` following EIP712 using typeHash of `ValidatorApproved(bytes4 sig,uint256 validatorData,address executor,bytes enableData)`

## Using external storage

Instead of using `DELEGATECALL` for validators, `Kernel` uses `CALL` to all validators. Rationale behind this is preventing the validation phase to be corrupted on validation. But we still use `DELEGATECALL` for executors which can potentially corrupt the storage of the `Kernel`, but this will be quite safe since executors can only be accessed when they were validated.

# Q&A