Social Recovery

Social Recovery: N-of-M Guardian Quorum Account Recovery

Every other signer (an ECDSA key, a passkey, a session key) assumes there is some working credential to authenticate with. Social recovery answers the question those cannot: what happens when the owner key itself is gone? A phone is lost, a seed phrase is destroyed, a hardware wallet dies — no key remains to sign anything, so no session key, second validator, or policy can help, because all of them still need to be invoked by an existing authorized signer.

Social recovery must be set up before that happens: a set of guardians (friends, family, hardware wallets you control, other trusted parties) is installed on the account in advance, so that later, if the owner key is lost, a quorum of guardians — not any single one — can co-sign a UserOperation that rotates the account to a new owner key. No individual guardian can act alone, and guardians have no day-to-day authority over the account — only the collective quorum, exercised once, to recover it.

When to Use This

• User wants a way to recover a smart account after losing the owner key
• User mentions guardians, N-of-M quorum, or break-glass recovery for a wallet
• User is designing an account-recovery UX that shouldn't depend on any single device or person surviving
• User wants to know who can act during recovery and what happens with too few guardians

Packages

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

You need an IAAClient, a deployed ERC-7579-compatible NethereumAccount with at least one validator installed (typically ECDSAValidator — see the modular-accounts skill), plus a deployed SocialRecovery module contract (SocialRecoveryService.DeployContractAndGetServiceAsync, a generated Nethereum contract service — no hand-written ABI).

using System.Linq;
using Nethereum.AccountAbstraction; // AATransactionReceipt
using Nethereum.AccountAbstraction.Client;
using Nethereum.AccountAbstraction.Contracts.Core.NethereumAccount;
using Nethereum.AccountAbstraction.Contracts.Modules.Native.ECDSAValidator;
using Nethereum.AccountAbstraction.ERC7579.Modules;
using Nethereum.AccountAbstraction.ERC7579.Modules.MultiGuardian;
using Nethereum.AccountAbstraction.ERC7579.Modules.SocialRecovery;
using Nethereum.AccountAbstraction.Validation; // Erc7769ErrorCodes
using Nethereum.JsonRpc.Client; // RpcResponseException
using Nethereum.Signer; // EthECKey

The Simple Way

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

// Install SocialRecovery with a 2-of-3 guardian quorum, signed by the account's CURRENT owner.
var receipt = (AATransactionReceipt)await accountService.InstallSocialRecoveryAndWaitForReceiptAsync(
    socialRecoveryAddress, threshold: 2, new[] { guardian1, guardian2, guardian3 });

That's it — any 2 of those 3 guardians can now recover the account if its owner key is ever lost. ABI-encoding the guardian list, the module type id, fees, gas, and nonce are all automatic.

Mental Model: Guardians, Threshold, Recovery-as-Owner-Rotation

SocialRecovery is an ERC-7579 TYPE_VALIDATOR module, installed exactly like ECDSAValidator or SmartSession, with two pieces of on-chain configuration per account: a guardian list and a threshold (SocialRecoveryConfig). Guardians never get day-to-day control. The only thing a guardian quorum can do is co-sign a UserOperation, and that UserOperation is itself restricted on-chain to a single execute() call whose target is a currently-installed TYPE_VALIDATOR module — in practice, calling transferOwnership on the account's ECDSAValidator to rotate the owner to a new key.

Recovery is a single co-signed UserOperation, not a two-phase propose/approve flow: each guardian signs the same userOp hash with their own key, MultiGuardianSignatureBlobBuilder concatenates the threshold signatures (ascending by guardian address) into one CheckNSignatures-compatible blob, and SocialRecoveryValidatorModule prefixes that blob with the module's own address.

Configure an N-of-M Guardian Quorum

Guardians must be sorted ascending by address and free of duplicates at install time — SocialRecovery.sol's onInstall reverts NotSortedAndUnique() otherwise. MultiGuardianSignatureBlobBuilder.SortAddressesAscending gives you that ordering:

var guardianKeys = Enumerable.Range(0, guardianCount)
    .Select(_ => EthECKey.GenerateKey())
    .ToArray();

var sortedGuardians = MultiGuardianSignatureBlobBuilder.SortAddressesAscending(
    guardianKeys.Select(k => k.GetPublicAddress()));

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

var receipt = (AATransactionReceipt)await accountService.InstallSocialRecoveryAndWaitForReceiptAsync(
    socialRecoveryAddress, threshold, sortedGuardians);

This is signed by the account's current owner — the guardians are not involved in their own installation. It composes with counterfactual deploy-on-first-op exactly like any other first UserOperation: if the account isn't deployed yet, the same op both deploys it and installs SocialRecovery.

SocialRecoveryConfig also validates itself before ever reaching the chain: GetInitData() throws InvalidOperationException if Guardians is empty, or if Threshold is not between 1 and the guardian count — the same rule SocialRecovery.sol's own onInstall enforces on-chain.

A Guardian Quorum Recovers the Account

The owner key is now lost. A quorum of threshold guardians (any threshold of the installed set — order doesn't matter, only which ones sign) co-signs a UserOperation that calls transferOwnership on the account's ECDSAValidator, through a second, independent NethereumSmartAccount attached to the same address:

var newOwner = EthECKey.GenerateKey();

// A guardian quorum co-signs the recovery userOp - the account's owner is never involved.
var guardianSigningService = new MultiGuardianSigningService(guardianKeys, threshold);
var socialRecoveryValidator = new SocialRecoveryValidatorModule(socialRecoveryAddress, threshold);
var recoveryAccount = aaClient.GetAccount(account.Address, guardianSigningService, socialRecoveryValidator);

// Driven through the RECOVERY TARGET's own typed service (ECDSAValidatorService), not
// NethereumAccountService.ExecuteAsync - see Common Mistakes below for why that distinction matters.
var ecdsaValidatorService = new ECDSAValidatorService(web3, ecdsaValidatorAddress);
ecdsaValidatorService.UseAccountAbstraction(recoveryAccount, aaClient);

var receipt = (AATransactionReceipt)await ecdsaValidatorService.TransferOwnershipRequestAndWaitForReceiptAsync(
    newOwner.GetPublicAddress());

var rotatedOwner = await ecdsaValidatorService.GetOwnerQueryAsync(account.Address);
// rotatedOwner == newOwner.GetPublicAddress() - the owner has genuinely rotated.

Neither the old owner key nor the new owner key ever signs anything — the rotation is authorized entirely by the guardian quorum through SocialRecoveryValidatorModule.