Skip to main content

ERC-7579 Modular Accounts

ERC-7579 defines a standard interface for modular smart accounts. Instead of a monolithic wallet contract, you compose behavior from interchangeable modules — validators that control who can sign, executors that define what actions are allowed, and hooks that intercept calls. This gives you multi-sig, social recovery, session keys, and spending limits as plug-and-play modules.

The Simple Way
// Install a 2-of-3 multisig validator
var config = OwnableValidatorConfig.Create(validatorAddress, threshold: 2, owner1, owner2, owner3);
await accountService.InstallModuleAndWaitForReceiptAsync(config);

One call to install any module. Nethereum handles the ABI encoding.

Prerequisites​

Install the Account Abstraction package:

dotnet add package Nethereum.AccountAbstraction
dotnet add package Nethereum.Web3

You need:

  • A deployed ERC-7579 compatible smart account (such as a modular account from Rhinestone, Biconomy, or your own implementation).
  • A signer key authorized to manage the account.
  • A bundler endpoint for submitting UserOperations.
  • The module contract addresses you want to install (validators, executors, etc.).

Add these namespaces to your code:

using Nethereum.AccountAbstraction.ERC7579;
using Nethereum.AccountAbstraction.ERC7579.Modules;
using Nethereum.AccountAbstraction.ERC7579.Modules.SocialRecovery;
using Nethereum.AccountAbstraction.ERC7579.Modules.SmartSession;
using Nethereum.AccountAbstraction.Contracts.Modules.SmartSessions.SmartSession.ContractDefinition;
using Nethereum.Web3;
using Nethereum.Web3.Accounts;

Module Types​

ERC-7579 defines four module types. Each serves a distinct role in the account lifecycle:

TypeConstantValuePurposeExample
ValidatorERC7579ModuleTypes.TYPE_VALIDATOR1Controls who can authorize operationsECDSA signer, multisig, passkey
ExecutorERC7579ModuleTypes.TYPE_EXECUTOR2Defines what actions the account can performAutomated DCA, scheduled transfers
FallbackERC7579ModuleTypes.TYPE_FALLBACK3Handles calls to functions not on the accountToken callbacks, custom interfaces
HookERC7579ModuleTypes.TYPE_HOOK4Intercepts calls before or after executionSpending limits, rate limiting

Every module config in Nethereum implements IModuleConfig, which exposes ModuleTypeId, ModuleAddress, GetInitData(), and GetDeInitData(). You never need to encode these yourself — the config classes handle it.

Install a Validator​

Validators are the most common module type. They determine how the account verifies signatures on UserOperations.

ECDSA Validator​

The simplest validator: a single EOA address controls the account. Use ECDSAValidatorConfig when you want one private key to authorize all operations.

var validatorAddress = "0x2222222222222222222222222222222222222222";
var ownerAddress = "0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B";

var config = ECDSAValidatorConfig.Create(validatorAddress, ownerAddress);
var receipt = await accountService.InstallModuleAndWaitForReceiptAsync(config);

The init data is the owner address encoded as bytes. After installation, only signatures from that owner will pass validation.

There is also a shortcut that skips the config object entirely:

var receipt = await accountService.InstallECDSAValidatorAndWaitForReceiptAsync(
validatorAddress, ownerAddress);

Both approaches produce the same on-chain result.

Ownable Validator (Multisig)​

For multi-signature control, use OwnableValidatorConfig. You set a threshold (minimum signers required) and a list of owner addresses.

A 2-of-3 multisig:

var validatorAddress = "0x3333333333333333333333333333333333333333";
var owner1 = "0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B";
var owner2 = "0x4B20993Bc481177ec7E8f571ceCaE8A9e22C02db";
var owner3 = "0x78731D3Ca6b7E34aC0F824c42a7cC18A495cabaB";

var config = OwnableValidatorConfig.Create(validatorAddress, threshold: 2, owner1, owner2, owner3);
var receipt = await accountService.InstallModuleAndWaitForReceiptAsync(config);

You can also build the config with fluent methods:

var config = new OwnableValidatorConfig { ModuleAddress = validatorAddress }
.WithOwner(owner1)
.WithOwner(owner2)
.WithOwner(owner3)
.WithThreshold(2);

The shortcut method works here too:

var receipt = await accountService.InstallOwnableValidatorAndWaitForReceiptAsync(
validatorAddress, threshold: 2, new[] { owner1, owner2, owner3 });

After installation, any UserOperation must include valid signatures from at least 2 of the 3 owners.

Social Recovery​

Social recovery lets designated guardians restore access to the account if the primary key is lost. Guardians are trusted addresses (friends, family, hardware wallets) that can collectively authorize a recovery operation.

var moduleAddress = "0x4444444444444444444444444444444444444444";
var guardian1 = "0x5B38Da6a701c568545dCfcB03FcB875f56beddC4";
var guardian2 = "0x617F2E2fD72FD9D5503197092aC168c91465E7f2";
var guardian3 = "0x17F6AD8Ef982297579C203069C1DbfFE4348c372";

var config = SocialRecoveryConfig.Create(moduleAddress, threshold: 2, guardian1, guardian2, guardian3);
var receipt = await accountService.InstallModuleAndWaitForReceiptAsync(config);

The fluent builder works the same way:

var config = new SocialRecoveryConfig { ModuleAddress = moduleAddress }
.WithGuardian(guardian1)
.WithGuardian(guardian2)
.WithGuardian(guardian3)
.WithThreshold(2);

Or use the shortcut:

var receipt = await accountService.InstallSocialRecoveryAndWaitForReceiptAsync(
moduleAddress, threshold: 2, new[] { guardian1, guardian2, guardian3 });

With a threshold of 2, any two guardians can trigger recovery. The third guardian is a safety net in case one guardian becomes unavailable.

Passkeys (WebAuthn)​

A passkey is an ERC-7579 validator too. WebAuthnValidatorModule (package Nethereum.AccountAbstraction.WebAuthn) plugs into the account exactly like the validators above — install it with a WebAuthnValidatorConfig through the same InstallModuleAndWaitForReceiptAsync call:

using Nethereum.AccountAbstraction.WebAuthn.ERC7579.Modules;

// credential is a WebAuthnCredential (the on-chain DTO) - obtain it from a platform
// authenticator's created credential via credential.ToCredential().
var moduleConfig = new WebAuthnValidatorConfig(webAuthnValidatorAddress, threshold: 1, credential);
var receipt = await accountService.InstallModuleAndWaitForReceiptAsync(moduleConfig);

See the WebAuthn Passkeys guide for credential creation and signing UserOperations with a passkey, and the Nethereum.AccountAbstraction.WebAuthn package for WebAuthnValidatorModule, WebAuthnValidatorConfig, and the IAAClient extensions that attach an account signed by a passkey.

Install an Executor​

Executors define what the account can do on behalf of an authorized caller. An OwnableExecutorConfig delegates execution rights to a specific address — useful for automation bots, portfolio managers, or scheduled operations.

var executorAddress = "0x5555555555555555555555555555555555555555";
var delegateAddress = "0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B";

var config = OwnableExecutorConfig.Create(executorAddress, delegateAddress);
var receipt = await accountService.InstallModuleAndWaitForReceiptAsync(config);

The shortcut:

var receipt = await accountService.InstallOwnableExecutorAndWaitForReceiptAsync(
executorAddress, delegateAddress);

Once installed, the delegate address can submit execution calls through the executor module without needing the account owner's signature for each operation. The executor contract enforces its own access control.

Smart Sessions​

Session keys let you grant temporary, scoped permissions to a key without giving it full control of the account. A session defines what a key can do (specific contract calls, token transfers up to a limit) and for how long. This is the foundation for gasless UX, embedded wallets, and dApp-specific permissions.

Create a Basic Session​

Start with SmartSessionConfig to define a session tied to a session validator. The salt is a 32-byte value; Create takes a byte[], and WithSalt also accepts a BigInteger:

var sessionModuleAddress = "0x6666666666666666666666666666666666666666";
var sessionValidatorAddress = "0x7777777777777777777777777777777777777777";
var salt = new byte[32];
salt[31] = 1;

var config = SmartSessionConfig.Create(sessionModuleAddress, sessionValidatorAddress, salt);
var receipt = await accountService.InstallModuleAndWaitForReceiptAsync(config);

If the session validator needs to know the owner address (for ECDSA verification of session signatures), use CreateWithOwner with the same salt shape:

var ownerAddress = "0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B";
var config = SmartSessionConfig.CreateWithOwner(
sessionModuleAddress, sessionValidatorAddress, ownerAddress, salt);

Scope Permissions with ERC20SpendingLimitBuilder​

The real power of sessions is scoping. Use ERC20SpendingLimitBuilder to encode spending limit policy data for one or more tokens:

using Nethereum.AccountAbstraction.ERC7579.Modules.SmartSession;

var usdcToken = "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48";
var spendingLimitPolicy = "0x8888888888888888888888888888888888888888";
var dailyLimit = BigInteger.Parse("100000000"); // 100 USDC (6 decimals)

// Single token — use the static helper
var spendingLimitInitData = ERC20SpendingLimitBuilder.SingleToken(usdcToken, dailyLimit);

var config = new SmartSessionConfig()
.WithSessionValidator(sessionValidatorAddress)
.WithSalt(salt)
.WithERC20TransferAction(usdcToken, spendingLimitPolicy, spendingLimitInitData)
.WithPaymasterPermission(true);

For multiple tokens, use the fluent builder:

var initData = new ERC20SpendingLimitBuilder()
.AddTokenLimit("0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", BigInteger.Parse("100000000")) // 100 USDC
.AddTokenLimit("0xdAC17F958D2ee523a2206206994597C13D831ec7", BigInteger.Parse("200000000")) // 200 USDT
.Build();

The builder validates inputs — BigInteger.Zero as a limit throws ArgumentException, and calling Build() with no tokens throws InvalidOperationException.

Define Custom Actions with ActionDataBuilder​

When you need both transfer and approve permissions (common in DeFi), use ActionDataBuilder to construct the action configuration:

var transferAction = ActionDataBuilder.ERC20Transfer(usdcToken, spendingLimitPolicy, limit);
var approveAction = ActionDataBuilder.ERC20Approve(usdcToken, spendingLimitPolicy, limit);

var config = new SmartSessionConfig()
.WithSessionValidator(sessionKeyValidator)
.WithSalt(salt)
.WithAction(transferAction)
.WithAction(approveAction);

Each action targets a specific function selector — 0xa9059cbb for transfer(address,uint256) and 0x095ea7b3 for approve(address,uint256). The policy contract enforces the spending limit independently per action.

Convert to a Session Object​

When you need the session data structure for off-chain use or to pass to other services:

Session session = config.ToSession();

This produces the Session object that the smart session module expects.

Manage Session Keys​

SessionKeyManager handles the lifecycle of session keys — generation, storage, retrieval, and cleanup. Use InMemorySessionKeyStore for development or implement ISessionKeyStore for persistent storage:

using Nethereum.AccountAbstraction.SessionKeys;

var sessionKeyStore = new InMemorySessionKeyStore();
var sessionKeyManager = new SessionKeyManager(sessionKeyStore);

// Generate a session key valid for 7 days
var generatedSession = await sessionKeyManager.GenerateSessionKeyAsync(accountAddress, validDays: 7);

// Mark it as registered after on-chain installation
await sessionKeyManager.MarkRegisteredAsync(generatedSession.Key);

// Retrieve the best session key for an account: the active one currently inside its ValidAfter/ValidUntil window with the latest ValidUntil
var bestKey = await sessionKeyManager.GetBestSessionKeyAsync(accountAddress);

// Remove a session key when it's no longer needed
await sessionKeyManager.RemoveSessionKeyAsync(generatedSession.Key);

The manager stores each generated key as inactive until MarkRegisteredAsync flips IsActive, and GetBestSessionKeyAsync returns the active key currently inside its ValidAfter/ValidUntil window with the latest ValidUntil. Use this to build session key rotation or expiry workflows in your application.

Attaching Modules: At Creation vs. After Deployment​

Every module above needs an account to attach to. There are two different points in an account's life where that happens, and they use different APIs.

The Initial Validator, Baked In at Creation​

NethereumAccountFactory deploys accounts via CREATE2, encoding exactly one validator into the account's init data — the validator installed the moment the account deploys. IAAClient.CreateAccountAsync builds that init data and derives the counterfactual address for you:

using Nethereum.AccountAbstraction.Client;
using Nethereum.Signer;

var owner = EthECKey.GenerateKey();
var account = await aaClient.CreateAccountAsync(owner); // NethereumSmartAccount, ECDSAValidator baked in

This is the ECDSA-owned shortcut. CreateAccountAsync also has a generic overload that takes any IAccountSigningService paired with the IErc7579ValidatorModule that authenticates it — an external signer, WebAuthn, or your own module — for the same one-validator-at-creation deploy. See Smart Account Deployment for the full mechanics: counterfactual addresses, funding, and deploy-on-first-op.

Every other module — a second validator, an executor, a hook, or a smart session — attaches after deployment, as its own UserOperation.

Installing a Module After Deployment: The Self-Call Pattern​

Installing or uninstalling a module on an already-deployed account is a UserOperation the account sends to itself. That means NethereumAccountService needs to be routed through Account Abstraction exactly like any other typed contract service — via UseAccountAbstraction — before the install/uninstall/query calls used throughout this guide will work:

using Nethereum.AccountAbstraction; // AATransactionReceipt
using Nethereum.AccountAbstraction.Client;
using Nethereum.AccountAbstraction.Contracts.Core.NethereumAccount;
using Nethereum.AccountAbstraction.ERC7579.Modules;

var accountService = new NethereumAccountService(web3, account.Address);
accountService.UseAccountAbstraction(account, aaClient);

var config = OwnableExecutorConfig.Create(executorAddress, delegateAddress);
var receipt = (AATransactionReceipt)await accountService.InstallModuleAndWaitForReceiptAsync(config);

Console.WriteLine(receipt.UserOpSuccess
? $"Installed - isModuleInstalled: {await accountService.IsModuleInstalledAsync(config)}"
: receipt.FailureDiagnostic);

This accountService — bound to the account's own address and routed through UseAccountAbstraction — is what every InstallModuleAndWaitForReceiptAsync/IsModuleInstalledAsync/UninstallModuleAndWaitForReceiptAsync call earlier in this guide runs against.

Check and Remove Modules​

Before installing a module, check whether it is already present:

var config = ECDSAValidatorConfig.Create(validatorAddress, ownerAddress);
bool installed = await accountService.IsModuleInstalledAsync(config);

if (!installed)
{
await accountService.InstallModuleAndWaitForReceiptAsync(config);
}

To remove a module, call uninstall with the same config:

var config = OwnableValidatorConfig.Create(validatorAddress, threshold: 2, owner1, owner2, owner3);
var receipt = await accountService.UninstallModuleAndWaitForReceiptAsync(config);

The config's GetDeInitData() method provides the cleanup data the module needs to remove its state.

If you need the raw generated methods instead of a config's IModuleConfig encoding — NethereumAccountService (the generated contract service itself, not a separate class) exposes them directly, taking the type ID and byte arrays yourself:

bool installed = await accountService.IsModuleInstalledQueryAsync(
ERC7579ModuleTypes.TYPE_VALIDATOR, validatorAddress, additionalContext: Array.Empty<byte>());

await accountService.UninstallModuleRequestAsync(
ERC7579ModuleTypes.TYPE_VALIDATOR, validatorAddress, deInitData);

These are exactly what the IModuleConfig-based helpers above call into — reach for them only if you are building initData/deInitData yourself instead of using a config class.

Common Mistakes​

Installing a module with the wrong type. An executor contract installed as a validator will not work. Each module is designed for one type. Check the module documentation or source to confirm its type before installing.

Setting threshold higher than the owner count. If you create an OwnableValidatorConfig with threshold 3 but only provide 2 owners, the account becomes unusable — you can never gather enough signatures. Always ensure threshold <= owners.Count.

Not checking if a module is already installed. Installing the same module twice may revert or produce unexpected state. Always call IsModuleInstalledAsync before InstallModuleAsync unless you are certain the module is not present.

Removing the last validator. If you uninstall every validator, the account has no way to authorize operations. Always ensure at least one validator remains active.

Forgetting to permit the paymaster in sessions. If your dApp uses a paymaster for gas sponsorship but the session does not call .WithPaymasterPermission(permit: true), the bundler will reject the UserOperation.

Next Steps​