🆕Wallet Pregeneration

Overview

Wallet Pregeneration allows you to create wallets for users before they set up a wallet with Capsule. You can then control when users claim and take ownership of their wallet. This guide will walk you through the process of creating, managing, and claiming pregenerated wallets using Capsule's SDK.

Core Pregeneration Methods

Capsule provides several methods for handling pregenerated wallets:

• getPregenWallets: Retrieve pregenerated wallets for a given identifier.

• hasPregenWallet: Check if a pregenerated wallet exists for an identifier.

• claimPregenWallets: Claim pregenerated wallets associated with an identifier.

• createWalletPreGen: Create a new pregenerated wallet.

• updateWalletIdentifierPreGen: Update the identifier of a pregenerated wallet.

Let's explore each of these methods in detail.

Creating a Pregenerated Wallet

To create a pregenerated wallet, use the createWalletPreGen method:

const pregenWallet = await capsule.createWalletPreGen(pregenIdentifier, useSolana, pregenIdentifierType);

• pregenIdentifier: A string that identifies the user (e.g., email, user ID).

• useSolana: Optional boolean to create a Solana wallet (default is false for EVM wallet).

• pregenIdentifierType: Optional enum (EMAIL or PHONE) to specify the identifier type.

Example:

const userEmail = "[e-mail]";
const pregenWallet = await capsule.createWalletPreGen(userEmail);
console.log("Pregenerated Wallet ID:", pregenWallet.id);

It's important to check if a pregenerated wallet already exists before creating a new one:

const hasWallet = await capsule.hasPregenWallet(userEmail);
if (!hasWallet) {
  const pregenWallet = await capsule.createWalletPreGen(userEmail);
  console.log("New pregenerated wallet created:", pregenWallet.id);
} else {
  console.log("Pregenerated wallet already exists for this user");
}

Note: The identifier doesn't have to be an email. It can be any string specific to your application, such as a user ID.

Managing User Share

After creating a pregenerated wallet, it's crucial to manage the user share. The user share is part of Capsule's 2/2 MPC that is typically managed by users and protected by their auth+passkey. For pregenerated wallets, you need to handle this share until the wallet is claimed.

To get the user share:

const userShare = await capsule.getUserShare();

To set the user share (important before using the wallet for signing):

await capsule.setUserShare(userShare);

It's important to safeguard this user share as it's specific to your application until the wallet is claimed. Store it securely and associate it with the user's identifier in your backend.

Using a Pregenerated Wallet

To use a pregenerated wallet for signing, first set the user share, then you can sign messages or transactions:

await capsule.setUserShare(userShare);

const messageBase64 = btoa("Hello, World!");
const signature = await capsule.signMessage(walletId, messageBase64);

const rlpEncodedTxBase64 = "..."; // Your RLP encoded transaction
const chainId = "1"; // Ethereum mainnet
const txSignature = await capsule.signTransaction(walletId, rlpEncodedTxBase64, chainId);

You can also sign using popular Ethereum libraries like Ethers or Viem. These libraries provide a more familiar interface for developers working with Ethereum transactions and messages.

For more detailed information on signing transactions and messages, including examples with Ethers and Viem, please refer to our Signing Transactions guide.

Claiming a Pregenerated Wallet (Optional)

When you want to allow a user to claim their pregenerated wallet, you can use the claimPregenWallets method. This process typically involves user authentication and transfers ownership of the wallet to the user's Capsule account.

const recoverySecret = await capsule.claimPregenWallets(userEmail);

Before claiming, you might need to update the wallet's identifier, especially if you used a non-email identifier initially:

await capsule.updateWalletIdentifierPreGen(userEmail, walletId);

The claiming process usually involves these steps:

1. Authenticate the user (e.g., email verification, OAuth)

2. Update the wallet identifier if necessary

3. Claim the wallet

Example flow:

// Assume user is authenticated and we have their email
const userEmail = "[e-mail]";

// Update identifier if necessary
await capsule.updateWalletIdentifierPreGen(userEmail, walletId);

// Claim the wallet
const recoverySecret = await capsule.claimPregenWallets(userEmail);

console.log("Wallet claimed successfully. Recovery secret:", recoverySecret);

Best Practices and Considerations

1. App-specific vs. Cross-app Usage: Pregenerated wallets are app-specific until claimed. After claiming, users can use them across different Capsule-integrated apps.

2. Identifier Management: Choose identifiers that make sense for your application. While emails are common, you can use any unique identifier.

3. Security: Safeguard the user share of pregenerated wallets. Treat it as sensitive information and store it securely.

4. User Experience: Consider when and how you'll prompt users to claim their wallets. This could be part of a broader onboarding or upgrade process in your app.

5. Wallet Types: Be aware of the wallet types you're creating (EVM or Solana) and ensure they align with your application's needs.

Full Example Reference

For a complete example demonstrating the usage of pregeneration methods, refer to: Wallet Pregeneration Example

This example provides a comprehensive flow of pregeneration method usage in a React application context.