Skip to main content

Guardian Recovery

The Account Recovery module is designed to work for both a single-owner account and for multi-sig Safe accounts. An account owner can add recovery methods (also known as Guardians) that have the ability to change the ownership of the account, in case the owner key is lost or compromised.

Read more on our on blog post on making Ethereum Accounts Recoverable, the seedless way.

tip

Want to run a simple example? Start by adding your first guardian to protect an account here.

Usage

Install

npm i abstractionkit@0.1.7
note

We're installing v0.1.7 of abstractionkit, an experimental version that includes the Guardian Recovery Module, only on Sepolia Testnet.

Import

import { SocialRecoveryModule } from "abstractionkit";

How to use

Initialize a SocialRecoveryModule instance

const srm = new SocialRecoveryModule();

Then consume the module methods like the following:

const accountAddress = "0x1.."
const guardianAddress= "0x2.."

const metaTransaction1 = srm.createEnableModuleMetaTransaction(accountAddress);

const metaTransaction2 = srm.createAddGuardianWithThresholdMetaTransaction(
accountAddress,
guardianAddress,
1n //threshold
);

Setup Guardians

createEnableModuleMetaTransaction

Active the recovery plugin for the smart account

Param NameParam TypeDescription
accountAddress stringThe target account address.

createAddGuardianWithThresholdMetaTransaction

Creates a MetaTransaction that lets the owner add a guardian for its account.

Param NameParam TypeDescription
accountAddress stringThe target account address.
guardianAddress stringThe guardian to add.
threshold bigintThe new threshold that will be set after addition.

Change Guardians Setup

createRevokeGuardianWithThresholdMetaTransaction

Creates a MetaTransaction that lets the owner revoke a guardian from its account.

Param NameParam TypeDescription
accountAddress stringThe target account address.
prevGuardianAddress stringThe previous guardian linking to the guardian in the linked list.
guardianAddress stringThe guardian to revoke.
threshold bigintThe new threshold that will be set after execution of revokation.

createChangeThresholdMetaTransaction

Creates a MetaTransaction that lets the owner change the guardian threshold required to initiate a recovery.

Param NameParam TypeDescription
accountAddress stringThe target account address.
threshold bigintThe new threshold that will be set after execution of revokation.

Recover

createConfirmRecoveryMetaTransaction

Creates a MetaTransaction that lets a single guardian confirm the execution of the recovery request. It can also trigger the start of the execution by passing true to 'execute' parameter. Once triggered, the recovery will started the recovery period delay, before it can be finalised.

Param NameParam TypeDescription
accountAddress stringThe target account address.
newOwners string[]The new owners' addresses.
newThreshold numberThe new threshold for the safe.
execute booleanWhether to auto-start execution of recovery.

createMultiConfirmRecoveryMetaTransaction

Creates a MetaTransaction that lets multiple guardians confirm the execution of the recovery request. It can also trigger the start of the execution by passing true to 'execute' parameter. Once triggered, the recovery will start the recovery period delay, before it can be finalised.

Param NameParam TypeDescription
accountAddress stringThe target account address.
newOwners string[]The new owners' addresses.
newThreshold numberThe new threshold for the safe.
signatures string[]The guardians' signatures.
execute booleanWhether to auto-start execution of recovery.

createExecuteRecoveryMetaTransaction

Creates a MetaTransaction that lets the guardians start the execution of the recovery request. Once triggered, the recovery will be pending for the recovery period before it can be finalized.

Param NameParam TypeDescription
accountAddress stringThe target account address.
newOwners string[]The new owners' addresses.
newThreshold numberThe new threshold for the safe.

createFinalizeRecoveryMetaTransaction

Creates a MetaTransaction that finalizes an ongoing recovery request if the recovery period is over. The method is public and callable by anyone to enable orchestration.

Param NameParam TypeDescription
accountAddress stringThe target account address.

Cancel a Recovery

createCancelRecoveryMetaTransaction

Creates a MetaTransaction that lets the account cancel an ongoing recovery request.

Param NameParam TypeDescription
accountAddress stringThe target account address.

Helpers

hasGuardianApproved

Retrieves specific guardian approval status for a particular recovery request at the current nonce.

Param NameParam TypeDescription
rpcUrl stringThe URL of the Ethereum RPC endpoint.
accountAddress stringThe target account address.
guardian stringThe guardian.
newOwners string[]The new owners' addresses.
newThreshold numberThe new threshold for the safe.

isGuardian

Checks if an address is a guardian for an account.

Param NameParam TypeDescription
rpcUrl stringThe URL of the Ethereum RPC endpoint.
accountAddress stringThe target account address.
guardian stringThe address to check.

guardiansCount

Counts the number of active guardians for an account.

Param NameParam TypeDescription
rpcUrl stringThe URL of the Ethereum RPC endpoint.
accountAddress stringThe target account address.

threshold

Retrieves the guardians threshold for the account.

Param NameParam TypeDescription
rpcUrl stringThe URL of the Ethereum RPC endpoint.
accountAddress stringThe target account address.

getGuardians

Get the active guardians for an account.

Param NameParam TypeDescription
rpcUrl stringThe URL of the Ethereum RPC endpoint.
accountAddress stringThe target account address.

getRecoveryRequest

Retrieves the account's current ongoing recovery request.

Param NameParam TypeDescription
rpcUrl stringThe URL of the Ethereum RPC endpoint.
accountAddress stringThe target account address.

getRecoveryApprovals

Retrieves the guardian approval count for this particular recovery request at the current nonce.

Param NameParam TypeDescription
rpcUrl stringThe URL of the Ethereum RPC endpoint.
accountAddress stringThe target account address.
newOwners string[]The new owners' addresses.
newThreshold numberThe new threshold for the safe.

nonce

Get the module nonce for an account.

Param NameParam TypeDescription
rpcUrl stringThe URL of the Ethereum RPC endpoint.
accountAddress stringThe target account address.