Social Recovery Module SDK Reference

abstractionkit ships one class per Social Recovery Module version. Use SocialRecoveryModuleV2 (module v0.2.0) for new integrations, and SocialRecoveryModuleV1 (module v0.1.0) for accounts that already enabled v0.1.0.

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 { SocialRecoveryModuleV2 } from "abstractionkit";

Choose a Module Version

Social Recovery Module v0.2.0 fixes the findings of Certora's audit and is a new deployment with new addresses. v0.1.0 stays deployed. Each version has its own class and grace period selector:

Module version	Class	Grace period selector	Recovery request type
v0.2.0 (recommended)	SocialRecoveryModuleV2	SocialRecoveryModuleGracePeriodSelectorV2	RecoveryRequestV2
v0.1.0	SocialRecoveryModuleV1	SocialRecoveryModuleGracePeriodSelectorV1	RecoveryRequestV1

Accounts on v0.1.0 must stay on V1

Pick the class that matches the module your accounts enabled. If your users enabled the v0.1.0 module, use SocialRecoveryModuleV1 and SocialRecoveryModuleGracePeriodSelectorV1. Pointed at a v0.2.0 address, an account that enabled v0.1.0 has no guardians, and its recovery calls fail.

SocialRecoveryModuleV1 and SocialRecoveryModuleGracePeriodSelectorV1 are what SocialRecoveryModule and SocialRecoveryModuleGracePeriodSelector were before abstractionkit v1.0.0, with the same addresses.

V1 vs V2 Differences

	V1 (module v0.1.0)	V2 (module v0.2.0)
createConfirmRecoveryMetaTransaction	(accountAddress, newOwners, newThreshold, execute)	(accountAddress, newOwners, newThreshold, nonce, execute)
createMultiConfirmRecoveryMetaTransaction	(accountAddress, newOwners, newThreshold, signaturePairList, execute)	(accountAddress, newOwners, newThreshold, nonce, signaturePairList, execute)
Guardian signature EIP-712 domain version	"0.0.1"	"0.2.0". Signatures made for v0.1.0 are not valid on v0.2.0.
getRecoveryRequest returns	RecoveryRequestV1 with executeAfter	RecoveryRequestV2 with nonce and executableAt
Adding or revoking a guardian, changing the threshold	Leaves a recovery in progress untouched	Cancels the recovery in progress and invalidates the guardian confirmations collected so far
cancelRecovery	Reverts when no recovery is in progress	Also invalidates collected confirmations, and works when no recovery is in progress
New owners	Validated at finalization	Also validated at confirmation and execution. For example, confirming a recovery that names a guardian as a new owner reverts.
hasGuardianApproved	Can report an approval from an address that is no longer a guardian	Reports approvals from current guardians only

On V2, pass the recovery nonce the guardians signed to the confirm methods. Read it from messageValue.nonce returned by getRecoveryRequestEip712Data, or call nonce for a single guardian confirming on-chain. The module reverts with SM: invalid nonce if the nonce changed before the transaction is included.

SocialRecoveryModuleBase

SocialRecoveryModuleBase is the abstract class both versions extend. It holds every method the two versions share: guardian management, execute, finalize, cancel, the read helpers, and getRecoveryRequestEip712Data. Use it as a type for code that accepts either version. The confirm methods and getRecoveryRequest differ between versions, so they live on SocialRecoveryModuleV1 and SocialRecoveryModuleV2.

import { SocialRecoveryModuleBase } from "abstractionkit";

async function listGuardians(srm: SocialRecoveryModuleBase, nodeUrl: string, accountAddress: string) {
  return srm.getGuardians(nodeUrl, accountAddress);
}

Initialize

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

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

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

import { SocialRecoveryModuleV2, SocialRecoveryModuleGracePeriodSelectorV2 } from "abstractionkit";

const gracePeriod = SocialRecoveryModuleGracePeriodSelectorV2.After7Days;
const srm = new SocialRecoveryModuleV2(gracePeriod); // 7 days

SocialRecoveryModuleGracePeriodSelectorV2 offers After3Minutes, After3Days, After7Days, and After14Days. The 3-minute deployment is on testnets only.

For accounts that enabled module v0.1.0, use the V1 class with the V1 selector:

import { SocialRecoveryModuleV1, SocialRecoveryModuleGracePeriodSelectorV1 } from "abstractionkit";

const srm = new SocialRecoveryModuleV1(SocialRecoveryModuleGracePeriodSelectorV1.After3Days);

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 object MetaTransaction is the type of transaction to construct a Safe operation. MetaTransaction.to string To address, or the the target contract address for the transaction MetaTransaction.value BigNumberish Value transfered if making a native token transfer. (usually 0n for contract interaction with non-native tokens like erc-20 tokens) MetaTransaction.data BytesLike The call data for the transaction MetaTransaction.operation Operation: enum Default to 0 for a Call. 1 for a Delegate Call. (Optional)	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. On V2 this also cancels any recovery in progress and invalidates collected guardian confirmations.

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 object MetaTransaction is the type of transaction to construct a Safe operation. MetaTransaction.to string To address, or the the target contract address for the transaction MetaTransaction.value BigNumberish Value transfered if making a native token transfer. (usually 0n for contract interaction with non-native tokens like erc-20 tokens) MetaTransaction.data BytesLike The call data for the transaction MetaTransaction.operation Operation: enum Default to 0 for a Call. 1 for a Delegate Call. (Optional)	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 | Transport | JsonRpcNode	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 object MetaTransaction is the type of transaction to construct a Safe operation. MetaTransaction.to string To address, or the the target contract address for the transaction MetaTransaction.value BigNumberish Value transfered if making a native token transfer. (usually 0n for contract interaction with non-native tokens like erc-20 tokens) MetaTransaction.data BytesLike The call data for the transaction MetaTransaction.operation Operation: enum Default to 0 for a Call. 1 for a Delegate Call. (Optional)	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 object MetaTransaction is the type of transaction to construct a Safe operation. MetaTransaction.to string To address, or the the target contract address for the transaction MetaTransaction.value BigNumberish Value transfered if making a native token transfer. (usually 0n for contract interaction with non-native tokens like erc-20 tokens) MetaTransaction.data BytesLike The call data for the transaction MetaTransaction.operation Operation: enum Default to 0 for a Call. 1 for a Delegate Call. (Optional)	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 guardian threshold.

Return Types

Param Name	Param Type	Description
MetaTransaction	MetaTransaction key type description MetaTransaction object MetaTransaction is the type of transaction to construct a Safe operation. MetaTransaction.to string To address, or the the target contract address for the transaction MetaTransaction.value BigNumberish Value transfered if making a native token transfer. (usually 0n for contract interaction with non-native tokens like erc-20 tokens) MetaTransaction.data BytesLike The call data for the transaction MetaTransaction.operation Operation: enum Default to 0 for a Call. 1 for a Delegate Call. (Optional)	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 starts the grace period, before it can be finalized.

On V2 it takes the account's current recovery nonce before execute. Get it with nonce.

// SocialRecoveryModuleV2
const nonce = await srm.nonce(nodeUrl, accountAddress);
const confirmTx = srm.createConfirmRecoveryMetaTransaction(
    accountAddress,
    [newOwnerAddress],
    1, // new threshold
    nonce,
    true, // execute
);

Param Types (V2)

key	type	description
accountAddress	string	The target account address.
newOwners	string[]	The new owners' addresses.
newThreshold	number	The new threshold for the safe.
nonce	bigint	The account's current recovery nonce (see nonce). The module reverts if it changed before the transaction is included.
execute	boolean	Whether to auto-start execution of recovery.

Param Types (V1)

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 object MetaTransaction is the type of transaction to construct a Safe operation. MetaTransaction.to string To address, or the the target contract address for the transaction MetaTransaction.value BigNumberish Value transfered if making a native token transfer. (usually 0n for contract interaction with non-native tokens like erc-20 tokens) MetaTransaction.data BytesLike The call data for the transaction MetaTransaction.operation Operation: enum Default to 0 for a Call. 1 for a Delegate Call. (Optional)	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 starts the grace period, before it can be finalized. Signature pairs are sorted by signer address for you.

On V2 it takes the recovery nonce the guardians signed, before the signatures. Use messageValue.nonce from getRecoveryRequestEip712Data. A signature may be empty when its signer is the transaction sender, or when the signer is a Safe guardian that pre-approved the recovery hash (EIP-1271).

// SocialRecoveryModuleV2
const { domain, types, messageValue } = await srm.getRecoveryRequestEip712Data(
    nodeUrl,
    chainId,
    accountAddress,
    [newOwnerAddress],
    1n, // new threshold
);

// each guardian signs { domain, types, messageValue } and returns { signer, signature }

const multiConfirmTx = srm.createMultiConfirmRecoveryMetaTransaction(
    accountAddress,
    [newOwnerAddress],
    1, // new threshold
    messageValue.nonce,
    signaturePairList,
    true, // execute
);

Param Types (V2)

key	type	description
accountAddress	string	The target account address.
newOwners	string[]	The new owners' addresses.
newThreshold	number	The new threshold for the safe.
nonce	bigint	The recovery nonce the guardians signed (messageValue.nonce from getRecoveryRequestEip712Data). It must still be the account's current nonce when the transaction is included.
signaturePairList	RecoverySignaturePair[]	The guardians signers and signatures pair list.
execute	boolean	Whether to auto-start execution of recovery.

Param Types (V1)

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 object MetaTransaction is the type of transaction to construct a Safe operation. MetaTransaction.to string To address, or the the target contract address for the transaction MetaTransaction.value BigNumberish Value transfered if making a native token transfer. (usually 0n for contract interaction with non-native tokens like erc-20 tokens) MetaTransaction.data BytesLike The call data for the transaction MetaTransaction.operation Operation: enum Default to 0 for a Call. 1 for a Delegate Call. (Optional)	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 object MetaTransaction is the type of transaction to construct a Safe operation. MetaTransaction.to string To address, or the the target contract address for the transaction MetaTransaction.value BigNumberish Value transfered if making a native token transfer. (usually 0n for contract interaction with non-native tokens like erc-20 tokens) MetaTransaction.data BytesLike The call data for the transaction MetaTransaction.operation Operation: enum Default to 0 for a Call. 1 for a Delegate Call. (Optional)	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 object MetaTransaction is the type of transaction to construct a Safe operation. MetaTransaction.to string To address, or the the target contract address for the transaction MetaTransaction.value BigNumberish Value transfered if making a native token transfer. (usually 0n for contract interaction with non-native tokens like erc-20 tokens) MetaTransaction.data BytesLike The call data for the transaction MetaTransaction.operation Operation: enum Default to 0 for a Call. 1 for a Delegate Call. (Optional)	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.

On V2 it also invalidates the guardian confirmations collected for the current nonce, and can be sent when no recovery is in progress. On V1 it reverts when no recovery is in progress.

Param Types

Return Types

Param Name	Param Type	Description
MetaTransaction	MetaTransaction key type description MetaTransaction object MetaTransaction is the type of transaction to construct a Safe operation. MetaTransaction.to string To address, or the the target contract address for the transaction MetaTransaction.value BigNumberish Value transfered if making a native token transfer. (usually 0n for contract interaction with non-native tokens like erc-20 tokens) MetaTransaction.data BytesLike The call data for the transaction MetaTransaction.operation Operation: enum Default to 0 for a Call. 1 for a Delegate Call. (Optional)	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. On V2, only current guardians are reported as having approved.

Param Types

key	type	description
nodeRpcUrl	string | Transport | JsonRpcNode	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 | Transport | JsonRpcNode	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 | Transport | JsonRpcNode	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
nodeRpcUrl	string | Transport | JsonRpcNode	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 | Transport | JsonRpcNode	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. V2 returns a RecoveryRequestV2, which adds the request nonce and renames executeAfter to executableAt. V1 returns a RecoveryRequestV1.

Param Types

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

Return Types (V2)

Promise<RecoveryRequestV2>

key	type	description
guardiansApprovalCount	bigint	The number of guardian approvals.
newThreshold	bigint	The new threshold for the safe.
nonce	bigint	The recovery nonce the request was approved under.
executableAt	bigint	Unix timestamp (seconds) from which the recovery can be finalized. 0 if no recovery is in progress.
newOwners	string[]	Array of new owners' addresses.

Return Types (V1)

Promise<RecoveryRequestV1>

key	type	description
guardiansApprovalCount	bigint	The number of guardian approvals.
newThreshold	bigint	The new threshold for the safe.
executeAfter	bigint	Unix timestamp (seconds) from which the recovery can be finalized. 0 if not yet executed.
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
nodeRpcUrl	string | Transport | JsonRpcNode	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's recovery nonce for an account. On V2, pass it to createConfirmRecoveryMetaTransaction.

Param Types

key	type	description
nodeRpcUrl	string | Transport | JsonRpcNode	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 | Transport | JsonRpcNode	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. It reads the current recovery nonce from the node unless overrides.recoveryNonce is set. The domain version matches the class: "0.2.0" for V2 and "0.0.1" for V1.

Param Types

key	type	description
rpcNode	string | Transport | JsonRpcNode	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. recoveryNonce sets the recovery nonce instead of reading it from the node.

Return Types

Promise<object>

key	type	description
domain	RecoveryRequestTypedDataDomain	EIP-712 domain: name "Social Recovery Module", version ("0.2.0" for V2, "0.0.1" for V1), chainId, and the module address as verifyingContract.
types	Record<string, { name: string; type: string }[]>	EIP-712 type definitions for the ExecuteRecovery primary type.
messageValue	RecoveryRequestTypedMessageValue	The message to sign: wallet, newOwners, newThreshold, and nonce. On V2, pass messageValue.nonce to the confirm methods.

Types

RecoveryRequestV2

Returned by SocialRecoveryModuleV2.getRecoveryRequest.

key	type	description
guardiansApprovalCount	bigint	The number of guardian approvals.
newThreshold	bigint	The new threshold for the safe.
nonce	bigint	The recovery nonce the request was approved under.
executableAt	bigint	Unix timestamp (seconds) from which the recovery can be finalized. 0 if no recovery is in progress.
newOwners	string[]	Array of new owners' addresses.

RecoveryRequestV1

Returned by SocialRecoveryModuleV1.getRecoveryRequest.

key	type	description
guardiansApprovalCount	bigint	The number of guardian approvals.
newThreshold	bigint	The new threshold for the safe.
executeAfter	bigint	Unix timestamp (seconds) from which the recovery can be finalized. 0 if not yet executed.
newOwners	string[]	Array of new owners' addresses.

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.