SocialRecoveryModule SDK Reference

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";

Initialize

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. This async version auto-detects the previous guardian by querying the node.

Param Types

key	type	description
nodeRpcUrl	string	The JSON-RPC API url for the target chain (to get the prevGuardian parameter).
accountAddress	string	The target account.
guardianAddress	string	The guardian to revoke.
threshold	bigint	The new threshold that will be set after execution of revocation.
overrides	object	Optional overrides object with prevGuardianAddress.

Return Types

Param Name	Param Type	Description
Promise<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.

createStandardRevokeGuardianWithThresholdMetaTransaction

Creates a MetaTransaction that lets the owner revoke a guardian from its account. This synchronous version requires the previous guardian address to be provided manually.

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 revocation.

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.
signaturePairList	RecoverySignaturePair[]	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

getRecoveryHash

Generates the recovery hash that should be signed by the guardian to authorize a recovery.

Param Types

key	type	description
nodeRpcUrl	string	The JSON-RPC API url for the target chain.
accountAddress	string	The target account address.
newOwners	string[]	The new owners' addresses.
newThreshold	number	The new threshold for the safe.
nonce	bigint	Recovery nonce.

Return Types

Promise<string>

getRecoveryRequestEip712Data

Creates recovery request EIP-712 data for signing by guardians.

Param Types

key	type	description
rpcNode	string	Node to fetch the recovery nonce.
chainId	bigint	Chain ID of the target network.
accountAddress	string	Address of account to recover.
newOwners	string[]	New owners to recover to.
newThreshold	bigint	New threshold.
overrides	object	Optional overrides with recoveryNonce.

Return Types

Promise<object>

Object containing domain, types, and messageValue for EIP-712 signing.

Types

RecoverySignaturePair

A guardian address paired with its EIP-712 signature authorizing a recovery.

key	type	description
signer	string	Guardian address that produced the signature.
signature	string	Hex-encoded signature bytes.