Recover users wallets

How to recover a wallet using recovery

What is a recovery

Users of Cometh Connect will generate and use a Safe as their wallet, with exclusive ownership and access to the funds it contains. Nonetheless, in the event of a lost key (such as misplacing their device or any other unforeseen circumstance), we aim to facilitate user's recovery of wallet access without compromising their security or self-custody. To achieve this, we have implemented a default feature in any Safe deployed to allow a guardian to initiate a recovery request. Upon the completion of a recovery request, the ownership structure of the Safe will be modified.

Our decentralized recovery model implementation is based on Safe{RecoveryHub}.

Prerequesites

Before initiating a recovery request, the following conditions are assumed to be met:

• The user possesses a Safe created using the connect-api.

• The application using Cometh SDK should have identified their users before starting any recovery procedure.

Recovery flow

A recovery request consists of three phases:

1. Creating a new owner: end user must create a signer that will be the new owner of his lost wallet.

2. User identification and submitting the recovery request: after identification of the user by the application, the recovery request can be created and sent to the guardian for signature.

3. Finalizing the recovery request: after Cometh's verification, provided the cooldown period is over (24h by default), the request can be processed. This action effectively modifies the ownership structure of the user's Safe.

1. User creates a new owner for their wallet

In the case of lost access to the wallet, you can start a recovery procedure by calling the initRecoveryRequest function from the SDK. It will return an object that contains the new signer that will be the new owner of your wallet.

import { ConnectAdaptor, SupportedNetworks} from "@cometh/connect-sdk";

const walletAdaptor = new ConnectAdaptor({
  chainId: SupportedNetworks.POLYGON,
  apiKey,
  passKeyName:YOUR_PASSKEY_NAME
});

const addSignerRequest = await walletAdaptor.initRecoveryRequest(walletAddress)

// with an optional passkeyName
const addSignerRequest = await walletAdaptor.initRecoveryRequest(walletAddress,
 passKeyName)

2. Submit the recovery request

Following the creation of the new owner, they can then initiate a recovery request. This process is similar to a "Forgot password" feature, requiring the user to specify the new addresses they wish to designate as the new owners of their Safe.

From a technical standpoint, after identification of the user at the application level, this is done by calling Cometh Connect API :

Recovery endpoints are protected with an apisecret, indicating that requests should be done from your backend for privacy concerns.

Start a recovery.

Start a recovery process. This will start the recovery period. During this period, the owner can cancel the recovery.

POSThttps://api.connect.cometh.io/recovery/start

Header parameters

Body

application/json

walletAddress*WalletAddress (string)

A wallet address

Example: "0x7Fc751C1725F3B955Aa8781640E1BAf5B75684c2"

Pattern: ^0x[a-fA-F0-9]{40}$

newOwner*string

A signer address.

Example: "0x3D9819210A31b4961b30EF54bE2aeD79B9c9Cd3B"

deviceDataDeviceData (object)

The device system information.

publicKeyIdPublicKeyId (string)

A string representation of the public Key Id.

Example: "0xebd7c0e4e702a4b7310f860901406bd91db6f4c874996b69775ea15f71409b38"

publicKeyXPublicKeyX (string)

A string representation of the public Key X.

Example: "0xebd7c0e4e702a4b7310f860901406bd91db6f4c874996b69775ea15f71409b38"

publicKeyYPublicKeyY (string)

A string representation of the public Key Y.

Example: "0xebd7c0e4e702a4b7310f860901406bd91db6f4c874996b69775ea15f71409b38"

Response

200404500

Success

Body

application/json

success*SuccessRequest (boolean)

Indicates whether the request was successful or not.

Example: true

Request

JavaScriptCurlPython

const response = await fetch('https://api.connect.cometh.io/recovery/start', {
    method: 'POST',
    headers: {
      "apisecret": "78d8e101a-9154-4000-91c5-b02527f4c70e",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "walletAddress": "0x7Fc751C1725F3B955Aa8781640E1BAf5B75684c2",
      "newOwner": "0x3D9819210A31b4961b30EF54bE2aeD79B9c9Cd3B"
    }),
});
const data = await response.json();

Response

200404500

{
  "success": true
}

3. Finalize the recovery request

Once the 24h recovery period is over without the owner of the Safe canceling the recovery, the request can be finalized. This step does not require any signature and can be executed by any party. Either Cometh, the project or the user can finalize the request.

An easy way to finalize the recovery request is by calling Cometh Connect API:

Finalize a recovery.

Finalize a recovery process. This can be done only once the recovery period is over.

POSThttps://api.connect.cometh.io/recovery/finalize

Header parameters

Body

application/json

walletAddress*WalletAddress (string)

A wallet address

Example: "0x7Fc751C1725F3B955Aa8781640E1BAf5B75684c2"

Pattern: ^0x[a-fA-F0-9]{40}$

Response

200409500

Success

Body

application/json

success*SuccessRequest (boolean)

Indicates whether the request was successful or not.

Example: true

Request

JavaScriptCurlPython

const response = await fetch('https://api.connect.cometh.io/recovery/finalize', {
    method: 'POST',
    headers: {
      "apisecret": "78d8e101a-9154-4000-91c5-b02527f4c70e",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "walletAddress": "0x7Fc751C1725F3B955Aa8781640E1BAf5B75684c2"
    }),
});
const data = await response.json();

Response

200409500

{
  "success": true
}

Calling finalize before the end of the recovery period (24 hours) will return an error {"error":"Recovery period not complete"}

This action will do an on-chain transaction finalizing the change.

Get a recovery Request

You can get the current recovery request using the getRecoveryRequest method of the SDK. You'll get the creation date of the request and the hash of the transaction.

Here is the method to call from the SDK:

import { ConnectAdaptor, ComethWallet } from "@cometh/connect-sdk";

const walletAdaptor = new ConnectAdaptor({
  chainId: YOUR_CHAIN_ID,
  apiKey: API_KEY,
});


const wallet = new ComethWallet({
  authAdapter: walletAdaptor,
  apiKey,
});

await wallet.connect(WALLET_ADDRESS);

const recoveryRequest = await wallet.getRecoveryRequest();

Cancel a recovery request

If a recovery request is still in the cooldown period, the user can cancel it if he has access to a device with a valid signer. This is done using the SDK method cancelRecoveryRequest, triggering an onchain transaction that will cancel the recovery request.

Parameters

• delayAddress (optional): The address used to delay the cancellation. If provided, the recovery request will be cancelled through this address.

Here is the method to call from the SDK:

import { ConnectAdaptor, ComethWallet } from "@cometh/connect-sdk";

const walletAdaptor = new ConnectAdaptor({
  chainId: YOUR_CHAIN_ID,
  apiKey: API_KEY,
});

const wallet = new ComethWallet({
  authAdapter: walletAdaptor,
  apiKey,
});

await wallet.connect(WALLET_ADDRESS);

const cancelRecoveryTx = await wallet.cancelRecoveryRequest(
  "0x_your_delay_address" // Optional parameter
);
const txPending = await provider.getTransaction(cancelRecoveryTx.safeTxHash); 
const txReceipt = await txPending.wait();

Additional functions

Setup Delay Module

This function sets up a delay module for the wallet. The setup involves deploying the delay module, enabling it on the wallet, and configuring it with the provided guardian address.

Parameters

• guardianAddress (string): The address of the guardian.

• expiration (number, optional): The expiration time for the delay module, 0 by default.

• cooldown (number, optional): The cooldown period for the delay module, 600 by default.

Here is the method to call from the SDK:

const setupDelayTx = await wallet.setupDelayModule(
  "0x_your_guardian_address", 
  expiration, // Optional parameter
  cooldown // Optional parameter
);
const txPending = await provider.getTransaction(setupDelayModule.safeTxHash); 
const txReceipt = await txPending.wait();

Get delay module address given expiration and cooldown

This function retrieves the delay module address for the wallet based on the specified expiration time and cooldown period.

Parameters

• expiration (number): The expiration time for the delay module.

• cooldown (number): The cooldown period for the delay module.

Here is the method to call from the SDK:

const delayModuleAddress = await wallet.getDelayModuleAddressFor(
    expiration,
    cooldown
);

console.log("Delay Module Address:", delayModuleAddress);

Get Current Recovery Params

This function retrieves the current recovery parameters for the wallet, provided the delay module is already enabled on the wallet.

Parameters

• delayModuleAddress (string, optional): The address of the delay module. By default, the delay module address related to the guardian address of Cometh is used.

Here is the method to call from the SDK:

const recoveryParams = await wallet.getCurrentRecoveryParams(
  delayModuleAddress: "0x_your_delay_module_address" // Optional parameter
);

console.log("Current Recovery Params:", recoveryParams);

Get Guardian Address

This function retrieves the guardian address for the specified delay module address. It ensures that the provided delay module address is enabled on the wallet before fetching the guardian address.

Parameters

• delayModuleAddress (string): The address of the delay module from which the guardian address will be retrieved.

Here is the method to call from the SDK:

const guardianAddress = await wallet.getGuardianAddress(
  "0x_your_delay_module_address"
);

console.log("Guardian Address:", guardianAddress);

Disable Guardian

This function disables a guardian's access to the delay module associated with the wallet by revoking the permissions previously granted to the specified guardian.

Parameters

• guardianAddress (string): The address of the guardian whose access is being disabled.

• expiration (number, optional): The expiration time for the delay module.

• cooldown (number, optional): The cooldown period for the delay module.

It requires the expiration and cooldown parameters only when the delay module has been set up using the setupDelayModule function with specific expiration and cooldown periods.

Here is the method to call from the SDK:

const disableGuardianTx = await wallet.disableGuardian(
  "0x_guardian_address_to_disable",
  expiration, // Optional parameter
  cooldown // Optional parameter
);

const txPending = await provider.getTransaction(disableGuardianTx.safeTxHash);
const txReceipt = await txPending.wait();

Add Guardian

This function allows to reactivate a guardian for the wallet. This function can only be used to reactivate a guardian that has been deactivated. It is important to note that at any given time, only one guardian can be linked to the delay module.

Parameters

• delayModuleAddress (string): The address of the delay module associated with the wallet. This module must already be enabled on the wallet.

• guardianAddress (string): The address of the new guardian to be added.

Here is the method to call from the SDK:

const addGuardianTx = await wallet.addGuardian(
  "0x_your_delay_module_address", 
  "0x_new_guardian_address"
);

const txPending = await provider.getTransaction(addGuardianTx.safeTxHash);
const txReceipt = await txPending.wait();