Key Management

Responsibility

A single user is responsible for managing the private key (secp256r1passkey in this case).

Storage

The passkey is generated by the device’s Secure Enclave (in case of iOS devices) or similar modules (in case of Android devices). The passkey is locally stored on the device’s Secure Enclave (in case of iOS devices) or similar modules (in case of Android devices).

Access

The user can access Secure Enclave (in case of iOS devices) or similar modules (in case of Android devices) in order to perform different operations without the passkey ever leaving the Secure Enclave.

Account Management

Clave does not support Externally Owned Accounts (EOAs) but it does support Smart Contract Accounts (SCAs).

Clave’s SCA Implementation

Clave maintains their own SCA implementation.

Registry

Clave maintains their own and ModuleManager and HookManager.

Modules

Clave also has 2 module implementations: SocialRecoveryModule and CloudRecoveryModule.

• SocialRecoveryModule: The Social recovery module allows clave users to assign guardians to their account who can help recovery your wallet.

  1
  struct RecoveryConfig {
  2
    uint128 timelock; // Recovery timelock duration
  3
    uint128 threshold; // Recovery threshold
  4
    address[] guardians; // Guardian addresses
  5
  }

  Copy code

  Each account has a RecoveryConfig which defines:

  1. timelock defines the duration of the recovery period (see recovery section for more context).
  2. threshold defines the minimum number of guardians that need to approve the recovery of an account. Note that the threshold will always be less than or equal to the number of guardians associated with the account.
  3. guardians is an array of guardian addresses associated with an account.

  We’ll discuss how this module is used for recovery in this section.

• CloudRecoveryModule: The cloud recovery module recovers an account using a key stored in iCloud or other similar clouds. This module is no longer used in the current Clave app because passkeys can sync with different user devices.

Processes

Clave has the following processes in place:

Key Generation

1. User (mobile wallet) receives a challenge string the Clave server. This challenge string is then used as an input (bytes32 salt) to generate the (counterfactual) account address (using the getAddressForSalt function). A counterfactual account address means that the actual smart contract account is not deployed on the address yet, but if we use the same salt (challenge string) to deploy a smart contract account (using the deployAccount function), it’ll be deployed to the same address that was generated by the getAddressForSalt function.

2. Once the user has the counterfactual account address, we’ll generate a key pair. In order to do so, we’ll first need to create a publicKeyCredentialCreationOptions object.

   Here is an example (actual implementation might differ) of how the publicKeyCredentialCreationOptions object looks like:

   • challenge parameter is generated using the challenge string that we got from the Clave server (which is randomStringFromServer in the code snippet). This is used to prevent “replay attacks” (more info here).
   • rp which is also known as the relaying party basically defines the describing the organization responsible for registering and authenticating the user. In this case, it’s Clave! (more info here).
   • user defines the user currently registering. The counterfactual account address is used as the id parameter. It is suggested to not use personally identifying information as the id, as it may be stored in an authenticator.  Read the spec (more info here).
   • pubKeyCredParams describes what public key types (in this case, secp256r1) are acceptable to a server (Clave).

   Rest of the params are optionally filled and are same for every user.

   1
   const publicKeyCredentialCreationOptions = {
   2
     challenge: Uint8Array.from(
   3
         randomStringFromServer, c => c.charCodeAt(0)),
   4
     rp: {
   5
         name: "Clave wallet",
   6
         id: "getclave.io",
   7
     },
   8
     user: {
   9
         id: Uint8Array.from(
   10
             "UZSL85T9AFC", c => c.charCodeAt(0)),
   11
         name: "vasa.develop@gmail.com",
   12
         displayName: "vasa",
   13
     },
   14
     pubKeyCredParams: [{alg: -7, type: "public-key"}],
   15
     authenticatorSelection: {
   16
         authenticatorAttachment: "cross-platform",
   17
     },
   18
     timeout: 60000,
   19
     attestation: "direct"
   20
   };

   Copy code

3. Once we have the publicKeyCredentialCreationOptions, we use the register function to get a PasskeyRegistrationResult object. ThisPasskeyRegistrationResult object is then sent to the clave server to be parsed and validated. Note that under the hood, the register function generates a key pair; the private key is stored in the secure enclave and never leaves the enclave, whereas the public key can be shared publicly.

   1
   import { Passkey, PasskeyRegistrationResult } from 'react-native-passkey';
   2
   
   3
   // Retrieve a valid FIDO2 attestation request from your server
   4
   // The challenge inside the request needs to be a base64 encoded string
   5
   // There are plenty of libraries which can be used for this (e.g. fido2-lib)
   6
   
   7
   try {
   8
     // Call the `register` method with the retrieved request in JSON format
   9
     // A native overlay will be displayed
   10
     const result: PasskeyRegistrationResult = await Passkey.register(requestJson);
   11
   
   12
     // The `register` method returns a FIDO2 attestation result
   13
     // Pass it to your server for verification
   14
     
   15
     console.log(result);
   16
     
   17
     // PasskeyRegistrationResult {
   18
     //   id: 'ADSUllKQmbqdGtpu4sjseh4cg2TxSvrbcHDTBsv4NSSX9...',
   19
     //   rawId: ArrayBuffer(59),
   20
     //   response: AuthenticatorAttestationResponse {
   21
     //       clientDataJSON: ArrayBuffer(121),
   22
     //       attestationObject: ArrayBuffer(306),
   23
     //   },
   24
     //   type: 'public-key'
   25
     // }
   26
   } catch (error) {
   27
     // Handle Error...
   28
   }

   Copy code

Account Generation/Activation

4. If everything goes well in step 3, Clave will deploy the smart contract wallet (using the deployAccount function) whenever the user performs their 1st trx from the clave wallet (here is an example transaction ). As we discussed in step 1, the smart contract wallet will be deployed at the counterfactual account address as we will use the same salt to deploy the account that was used to pre generate the address.

   

   The public key (hex encoded version of id fromPasskeyRegistrationResult) will also be passed (within theinitializer parameter) which will set it as the owner of the SCA.

Transaction Process

• Key signing : The app takes a transaction message and forwards a signing request to the Secure Enclave. The user can then use biometric authentication to approve signing after which the Secure Enclave signs the message with the key.

• Transaction verification : The signed message from the Secure Enclave is then relayed to the bundler (which is also the sequencer in case of zksync due to native AA support) which sends the transaction to the SCA which uses a verifier contract to validate the secp256r1 signature. Note that in April of 2024, zksync will add native support for EIP-7212, and Clave can then use the native circuit implementation to verify secp256r1 signatures in a much cheaper way.

• Gas abstraction/sponsership : Clave wallet sponsors first few (~5) transactions using a paymaster.

  

Account Recovery Process

Clave wallet supports social recovery mechanism where the user can assign their family or friend’s clave address as backup guardians. Users can decide the number of guardians that have to give confirmation for recovery (M our of N guardians where N ≥ M).

The recovery process is conducted by Clave’s smart contract on zkSync. Once the user initiates the recovery flow:

1. The user is asked to share the address (or nick name that Clave uses as a temporary solution before ENS is added to zksync) that needs to be recovered.
2. Next, the user is asked the address (or nick name) of their guardian. Note that while Clave’s social recovery module does support recovery using M out of N guardians, but the app currently only works for recovery using a single guardian (i.e. for all users, the threshold is set to 1).
3. Next, a new passkey is generated (using the process discussed here ). Your device might ask for a biometric authentication to save the newly generated passkey to the cloud (for eg. in case of iOS, it will be stored on the iCloud keychain).
4. The app will then share a link that the user can share with your guardian. This link contains the details needed by the guardian to generate a signature to initiate the recovery process for the user.
5. Once the guardian uses the link, they will be prompted to sign a message that signifies their consent to recover the user’s account.
6. Next, the guardian will sign a transaction that calls the startRecovery function which which will validate the signature from the previous step and start a 48-hour time lock.
7. Once the 48-hour duration is complete, anyone can call theexecuteRecoveryfunction that will update the owner of the SCA with the new public key that we created in step 3.

Note that the user can chose to cancel the recovery process (using the startRecovery function) anytime within the 48 hours time lock period. This feature is useful in case the user initiated the recovery process by mistake or to prevent any unauthorized and malicious activities.

Migrating from another wallet (assuming migration on a single network; zksync)

• Case 1: If you are migrating from an EOA account: You would need to transfer all your assets from your EOA to the Clave account contract. In future this can be made easier with (EIP-7377 migration transaction).

• Case 2: If you are migrating from a smart contract account: You would need to transfer all your assets from your smart contract account to the Clave account contract. Ideally, this could be done in a single transaction given we can batch transactions with a smart contract account.

Migrating to another wallet (assuming migration on a single network)

You should be able to transfer all your assets to any other address in a single transaction.

What happens to the wallet if clave servers/platform is down?

TODO