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 24h cooldown period is over, 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

newOwner*string

A signer address.

deviceDataDeviceData (object)

The device system information.

publicKeyIdPublicKeyId (string)

A string representation of the public Key Id.

publicKeyXPublicKeyX (string)

A string representation of the public Key X.

publicKeyYPublicKeyY (string)

A string representation of the public Key Y.

Response

200404500

Success

Body

application/json

success*SuccessRequest (boolean)

Indicates whether the request was successful or not.

Request

JavaScriptCurl

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

Response

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

Response

200409500

Success

Body

application/json

success*SuccessRequest (boolean)

Indicates whether the request was successful or not.

Request

JavaScriptCurl

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

Response

{
  "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.

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();
const txPending = await provider.getTransaction(cancelRecoveryTx.safeTxHash); 
const txReceipt = await txPending.wait();