# SocialRecoveryModule SDK Reference ## Install[​](#install "Direct link to Install") tip Prefer to run a simple example? Fork this repo and add your first guardian [here](https://github.com/candidelabs/abstractionkit-examples/blob/main/recovery/recovery.ts). * npm * yarn ``` npm i abstractionkit ``` ``` yarn add abstractionkit ``` ## Import[​](#import "Direct link to Import") ``` import { SocialRecoveryModule } from "abstractionkit"; ``` ## Initialize[​](#initialize "Direct link to 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](https://docs.candide.dev/wallet/technical-reference/deployments/.md#social-recovery-module) 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[​](#setup-guardians "Direct link to Setup Guardians") ### createEnableModuleMetaTransaction[​](#createenablemodulemetatransaction "Direct link to createEnableModuleMetaTransaction") Active the recovery plugin for the smart account * Param Types * Return Types | key | type | description | | :--------------- | :------- | :-------------------------- | | `accountAddress` | `string` | The target account address. | | Param Name | Param Type | Description | | :-------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------- | | MetaTransaction | MetaTransactionkey type descriptionMetaTransaction key type descriptionto 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[​](#createaddguardianwiththresholdmetatransaction "Direct link to createAddGuardianWithThresholdMetaTransaction") Creates a MetaTransaction that lets the owner add a guardian for its account. * Param Types * Return Types | key | type | description | | :---------------- | :------- | :------------------------------------------------- | | `guardianAddress` | `string` | The guardian to add. | | `threshold` | `bigint` | The new threshold that will be set after addition. | | Param Name | Param Type | Description | | :-------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------- | | MetaTransaction | MetaTransactionkey type descriptionMetaTransaction key type descriptionto 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[​](#change-guardians-setup "Direct link to Change Guardians Setup") ### createRevokeGuardianWithThresholdMetaTransaction[​](#createrevokeguardianwiththresholdmetatransaction "Direct link to 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 * Return 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. | | Param Name | Param Type | Description | | :------------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------- | | Promise\ | MetaTransactionkey type descriptionMetaTransaction key type descriptionto 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[​](#createstandardrevokeguardianwiththresholdmetatransaction "Direct link to 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 * Return 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. | | Param Name | Param Type | Description | | :-------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------- | | MetaTransaction | MetaTransactionkey type descriptionMetaTransaction key type descriptionto 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[​](#createchangethresholdmetatransaction "Direct link to createChangeThresholdMetaTransaction") Creates a MetaTransaction that lets the owner change the guardian threshold required to initiate a recovery. * Param Types * Return Types | key | type | description | | :---------- | :------- | :---------------------------------------------------------------- | | `threshold` | `bigint` | The new threshold that will be set after execution of revokation. | | Param Name | Param Type | Description | | :-------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------- | | MetaTransaction | MetaTransactionkey type descriptionMetaTransaction key type descriptionto 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[​](#recover "Direct link to Recover") ### createConfirmRecoveryMetaTransaction[​](#createconfirmrecoverymetatransaction "Direct link to 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 * Return 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. | | Param Name | Param Type | Description | | :-------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------- | | MetaTransaction | MetaTransactionkey type descriptionMetaTransaction key type descriptionto 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[​](#createmulticonfirmrecoverymetatransaction "Direct link to 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 * Return 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. | | Param Name | Param Type | Description | | :-------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------- | | MetaTransaction | MetaTransactionkey type descriptionMetaTransaction key type descriptionto 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[​](#createexecuterecoverymetatransaction "Direct link to 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 * Return Types | key | type | description | | :--------------- | :--------- | :------------------------------ | | `accountAddress` | `string` | The target account address. | | `newOwners` | `string[]` | The new owners' addresses. | | `newThreshold` | `number` | The new threshold for the safe. | | Param Name | Param Type | Description | | :-------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------- | | MetaTransaction | MetaTransactionkey type descriptionMetaTransaction key type descriptionto 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[​](#createfinalizerecoverymetatransaction "Direct link to 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 * Return Types | key | type | description | | :--------------- | :------- | :-------------------------- | | `accountAddress` | `string` | The target account address. | | Param Name | Param Type | Description | | :-------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------- | | MetaTransaction | MetaTransactionkey type descriptionMetaTransaction key type descriptionto 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[​](#cancel-a-recovery "Direct link to Cancel a Recovery") ### createCancelRecoveryMetaTransaction[​](#createcancelrecoverymetatransaction "Direct link to createCancelRecoveryMetaTransaction") Creates a MetaTransaction that lets the account cancel an ongoing recovery request. * Param Types * Return Types | Param Name | Param Type | Description | | :-------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------- | | MetaTransaction | MetaTransactionkey type descriptionMetaTransaction key type descriptionto 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[​](#helpers "Direct link to Helpers") ### hasGuardianApproved[​](#hasguardianapproved "Direct link to hasGuardianApproved") Retrieves specific guardian approval status for a particular recovery request at the current nonce. * Param Types * Return 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. | Boolean ### isGuardian[​](#isguardian "Direct link to isGuardian") Checks if an address is a guardian for an account. * Param Types * Return 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. | Boolean ### guardiansCount[​](#guardianscount "Direct link to guardiansCount") Counts the number of active guardians for an account. * Param Types * Return Types | key | type | description | | :--------------- | :------- | :----------------------------------------- | | `nodeRpcUrl` | `string` | The Node URL of the Ethereum RPC endpoint. | | `accountAddress` | `string` | The target account address. | BigInt ### threshold[​](#threshold "Direct link to threshold") Retrieves the guardians threshold for the account. * Param Types * Return Types | key | type | description | | :--------------- | :------- | :----------------------------------------- | | `nodeURL` | `string` | The Node URL of the Ethereum RPC endpoint. | | `accountAddress` | `string` | The target account address. | BigInt ### getGuardians[​](#getguardians "Direct link to getGuardians") Get the active guardians for an account. * Param Types * Return Types | key | type | description | | :--------------- | :------- | :----------------------------------------- | | `nodeRpcUrl` | `string` | The Node URL of the Ethereum RPC endpoint. | | `accountAddress` | `string` | The target account address. | String\[] ### getRecoveryRequest[​](#getrecoveryrequest "Direct link to getRecoveryRequest") Retrieves the account's current ongoing recovery request. * Param Types * Return Types | key | type | description | | :--------------- | :------- | :----------------------------------------- | | `nodeUrl` | `string` | The Node URL of the Ethereum RPC endpoint. | | `accountAddress` | `string` | The target account address. | | 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[​](#getrecoveryapprovals "Direct link to getRecoveryApprovals") Retrieves the guardian approval count for this particular recovery request at the current nonce. * Param Types * Return 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. | BigInt ### nonce[​](#nonce "Direct link to nonce") Get the module nonce for an account. * Param Types * Return Types | key | type | description | | :--------------- | :------- | :----------------------------------------- | | `nodeRpcUrl` | `string` | The Node URL of the Ethereum RPC endpoint. | | `accountAddress` | `string` | The target account address. | BigInt ### getRecoveryHash[​](#getrecoveryhash "Direct link to getRecoveryHash") Generates the recovery hash that should be signed by the guardian to authorize a recovery. * Param Types * Return 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. | Promise\ ### getRecoveryRequestEip712Data[​](#getrecoveryrequesteip712data "Direct link to getRecoveryRequestEip712Data") Creates recovery request EIP-712 data for signing by guardians. * Param Types * Return 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. | Promise\ Object containing domain, types, and messageValue for EIP-712 signing. ## Types[​](#types "Direct link to Types") ### RecoverySignaturePair[​](#recoverysignaturepair "Direct link to 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. |