Account Recovery

Intro

Social Recovery is widely accepted as an effective method for users to regain control of their accounts by changing the main access control to a new owner through their trusted contacts. Account Recovery modules allow owners to add recovery addresses, known as Guardians, to facilitate this process in case their signer key is lost or compromised.

The Candide Social Recovery Module is flexible to accept various types of Ethereum accounts as Guardians, including:

• Family and friends'
• Hardware wallets
• Institutions
• Email / SMS (through custodial services offering cloud-based wallets)

Learn more on how the Social Recovery Module work on this post.

Audits

• Contracts, Formal Verification and Audits be found on the github repo candide-contracts.

Deployment addresses

• Deployment addresses for different grace periods can be found here.

Usage

Install

tip

Prefer to run a simple example? Fork this repo and add your first guardian here.

npm

npm i abstractionkit

yarn

yarn add abstractionkit

Import

import { SocialRecoveryModule } from "abstractionkit";

How to use

Initialize a SocialRecoveryModule instance. By default, the grace period for recovery is set to 3 days.

const srm = new SocialRecoveryModule(); // 3 days

If you need a different grace period, you can override it by providing a different grace period address during initialization.

import { SocialRecoveryModule, SocialRecoveryModuleGracePeriodSelector } from "abstractionkit";
 
const gracePeriod = SocialRecoveryModuleGracePeriodSelector.After7Days;
const srm = new SocialRecovery(gracePeriod); // 7 days

Then consume the module methods like the following:

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

const metaTransaction1 = srm.createEnableModuleMetaTransaction(accountAddress);

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

Setup Guardians

createEnableModuleMetaTransaction

Active the recovery plugin for the smart account

Param Types

key	type	description
accountAddress	string	The target account address.

Return Types

Param Name	Param Type	Description
MetaTransaction	MetaTransaction key type description MetaTransaction key type description to string To address, or the the target contract address for the transaction value BigNumberish Value transfered if making a native token transfer. (usually 0n for contract interaction with non-native tokens like erc-20 tokens) data BytesLike The call data for the transaction operation Operation: enum Default to 0 for a Call. 1 for a Delegate Call. (Optional) MetaTransaction is the type of transaction to construct a Safe operation.	MetaTransaction is the type of a transaction to construct a Safe operation.

createAddGuardianWithThresholdMetaTransaction

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

Param Types

key	type	description
guardianAddress	string	The guardian to add.
threshold	bigint	The new threshold that will be set after addition.

Return Types

Param Name	Param Type	Description
MetaTransaction	MetaTransaction key type description MetaTransaction key type description to string To address, or the the target contract address for the transaction value BigNumberish Value transfered if making a native token transfer. (usually 0n for contract interaction with non-native tokens like erc-20 tokens) data BytesLike The call data for the transaction operation Operation: enum Default to 0 for a Call. 1 for a Delegate Call. (Optional) MetaTransaction is the type of transaction to construct a Safe operation.	MetaTransaction is the type of a transaction to construct a Safe operation.

Change Guardians Setup

createRevokeGuardianWithThresholdMetaTransaction

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

Param Types

key	type	description
prevGuardianAddress	string	The previous guardian linking to the guardian in the linked list.
guardianAddress	string	The guardian to revoke.
threshold	bigint	The new threshold that will be set after execution of revokation.

Return Types

Param Name	Param Type	Description
MetaTransaction	MetaTransaction key type description MetaTransaction key type description to string To address, or the the target contract address for the transaction value BigNumberish Value transfered if making a native token transfer. (usually 0n for contract interaction with non-native tokens like erc-20 tokens) data BytesLike The call data for the transaction operation Operation: enum Default to 0 for a Call. 1 for a Delegate Call. (Optional) MetaTransaction is the type of transaction to construct a Safe operation.	MetaTransaction is the type of a transaction to construct a Safe operation.

createChangeThresholdMetaTransaction

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

Param Types

key	type	description
threshold	bigint	The new threshold that will be set after execution of revokation.

Return Types

Param Name	Param Type	Description
MetaTransaction	MetaTransaction key type description MetaTransaction key type description to string To address, or the the target contract address for the transaction value BigNumberish Value transfered if making a native token transfer. (usually 0n for contract interaction with non-native tokens like erc-20 tokens) data BytesLike The call data for the transaction operation Operation: enum Default to 0 for a Call. 1 for a Delegate Call. (Optional) MetaTransaction is the type of transaction to construct a Safe operation.	MetaTransaction is the type of a transaction to construct a Safe operation.

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 Types

key	type	description
accountAddress	string	The target account address.
newOwners	string[]	The new owners' addresses.
newThreshold	number	The new threshold for the safe.
execute	boolean	Whether to auto-start execution of recovery.

Return Types

Param Name	Param Type	Description
MetaTransaction	MetaTransaction key type description MetaTransaction key type description to string To address, or the the target contract address for the transaction value BigNumberish Value transfered if making a native token transfer. (usually 0n for contract interaction with non-native tokens like erc-20 tokens) data BytesLike The call data for the transaction operation Operation: enum Default to 0 for a Call. 1 for a Delegate Call. (Optional) MetaTransaction is the type of transaction to construct a Safe operation.	MetaTransaction is the type of a transaction to construct a Safe operation

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 Types

key	type	description
accountAddress	string	The target account address.
newOwners	string[]	The new owners' addresses.
newThreshold	number	The new threshold for the safe.
signatureData	key type description signer bigint signer signature string[] signature	The guardians signers and signatures pair list.
execute	boolean	Whether to auto-start execution of recovery.

Return Types

Param Name	Param Type	Description
MetaTransaction	MetaTransaction key type description MetaTransaction key type description to string To address, or the the target contract address for the transaction value BigNumberish Value transfered if making a native token transfer. (usually 0n for contract interaction with non-native tokens like erc-20 tokens) data BytesLike The call data for the transaction operation Operation: enum Default to 0 for a Call. 1 for a Delegate Call. (Optional) MetaTransaction is the type of transaction to construct a Safe operation.	MetaTransaction is the type of a transaction to construct a Safe operation

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 Types

key	type	description
accountAddress	string	The target account address.
newOwners	string[]	The new owners' addresses.
newThreshold	number	The new threshold for the safe.

Return Types

Param Name	Param Type	Description
MetaTransaction	MetaTransaction key type description MetaTransaction key type description to string To address, or the the target contract address for the transaction value BigNumberish Value transfered if making a native token transfer. (usually 0n for contract interaction with non-native tokens like erc-20 tokens) data BytesLike The call data for the transaction operation Operation: enum Default to 0 for a Call. 1 for a Delegate Call. (Optional) MetaTransaction is the type of transaction to construct a Safe operation.	MetaTransaction is the type of a transaction to construct a Safe operation.

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 Types

key	type	description
accountAddress	string	The target account address.

Return Types

Param Name	Param Type	Description
MetaTransaction	MetaTransaction key type description MetaTransaction key type description to string To address, or the the target contract address for the transaction value BigNumberish Value transfered if making a native token transfer. (usually 0n for contract interaction with non-native tokens like erc-20 tokens) data BytesLike The call data for the transaction operation Operation: enum Default to 0 for a Call. 1 for a Delegate Call. (Optional) MetaTransaction is the type of transaction to construct a Safe operation.	MetaTransaction is the type of a transaction to construct a Safe operation.

Cancel a Recovery

createCancelRecoveryMetaTransaction

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

Param Types

Return Types

Param Name	Param Type	Description
MetaTransaction	MetaTransaction key type description MetaTransaction key type description to string To address, or the the target contract address for the transaction value BigNumberish Value transfered if making a native token transfer. (usually 0n for contract interaction with non-native tokens like erc-20 tokens) data BytesLike The call data for the transaction operation Operation: enum Default to 0 for a Call. 1 for a Delegate Call. (Optional) MetaTransaction is the type of transaction to construct a Safe operation.	MetaTransaction is the type of a transaction to construct a Safe operation.

Helpers

hasGuardianApproved

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

Param Types

key	type	description
nodeURL	string	The Node URL of the Ethereum RPC endpoint.
accountAddress	string	The target account address.
guardian	string	The guardian.
newOwners	string[]	The new owners' addresses.
newThreshold	number	The new threshold for the safe.

Return Types

Boolean

isGuardian

Checks if an address is a guardian for an account.

Param Types

key	type	description
nodeRpcUrl	string	The Node URL of the Ethereum RPC endpoint.
accountAddress	string	The target account address.
guardian	string	The address to check.

Return Types

Boolean

guardiansCount

Counts the number of active guardians for an account.

Param Types

key	type	description
nodeRpcUrl	string	The Node URL of the Ethereum RPC endpoint.
accountAddress	string	The target account address.

Return Types

BigInt

threshold

Retrieves the guardians threshold for the account.

Param Types

key	type	description
nodeURL	string	The Node URL of the Ethereum RPC endpoint.
accountAddress	string	The target account address.

Return Types

BigInt

getGuardians

Get the active guardians for an account.

Param Types

key	type	description
nodeRpcUrl	string	The Node URL of the Ethereum RPC endpoint.
accountAddress	string	The target account address.

Return Types

String[]

getRecoveryRequest

Retrieves the account's current ongoing recovery request.

Param Types

key	type	description
nodeUrl	string	The Node URL of the Ethereum RPC endpoint.
accountAddress	string	The target account address.

Return Types

key	type	description
guardiansApprovalCount	bigint	The number of guardian approvals.
newThreshold	bigint	The new threshold for the safe.
executeAfter	bigint	Timestamp indicating when the execution can happen.
newOwners	string[]	Array of new owners' addresses.

getRecoveryApprovals

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

Param Types

key	type	description
nodeUrl	string	The Node URL of the Ethereum RPC endpoint.
accountAddress	string	The target account address.
newOwners	string[]	The new owners' addresses.
newThreshold	number	The new threshold for the safe.

Return Types

BigInt

nonce

Get the module nonce for an account.

Param Types

key	type	description
nodeRpcUrl	string	The Node URL of the Ethereum RPC endpoint.
accountAddress	string	The target account address.

Return Types

BigInt