Wallet Pregeneration

​

Overview

Wallet Pregeneration allows you to create wallets for users before they set up a wallet with Capsule. This feature gives you control over 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.

Pregenerated wallets can be associated with an email address, a phone number, a Twitter or Discord username, or a custom ID of your choosing (for example, an external database ID). A Capsule user can attempt to claim any current pregenerated wallets in their app storage.

• For email or phone, the user will need to have the same email address or phone number linked to their account.
• For Discord or Twitter, the user will need to have authenticated via those services on your application with the same username.
• For a custom ID, the ID in question cannot have been claimed by another user. After a successful claim, only the first user to claim a custom ID will thereafter be allowed to claim pregenerated wallets with that ID on your application.

​

Core Pregeneration Methods

Capsule provides several methods for handling pregenerated wallets:

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('EVM', pregenIdentifier, pregenIdentifierType);

Example:

const userEmail = "user@example.com";
const pregenWallet = await capsule.createWalletPreGen('EVM', userEmail, 'EMAIL');
console.log("Pregenerated Wallet ID:", pregenWallet.id);

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

​

Storing and Managing User Share

After creating a pregenerated wallet, it’s crucial to manage the user share so it remains accessible to either you or the user until the claim process. 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);

​

Best Practices for Storing the User Share

When temporarily managing the user share, it is critical to have a higher degree of operational excellence around storing this share. In disaster scenarios of widespread data compromise, key rotation is possible in coordination with the Capsule Team. However, Capsule does not store backups of this share in case of data loss.

To mitigate this category of risks, we’ve compiled a few best practices:

• Encrypt User Shares in-transit and at-rest.
• Ensure Your database has backups and periodic replicas to mitigate against data deletion risks.
• Complete a fire drill prior to going live, testing scenarios such as:
  • You are unable to access your DB
  • Your DB is deleted
  • An internal team member’s credentials are compromised

​

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);

​

Claiming a Pregenerated Wallet (Optional)

If a new user of your application registers via the Capsule Modal and has pre-generated wallets for their email address, phone number, or Discord or Twitter username already present in storage, these wallets will be claimed automatically.

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

You may call this method without arguments to attempt to claim all pre-generated wallets present in storage, or pass the identifier for a particular wallet.

const recoverySecret = await capsule.claimPregenWallets();
// or: await capsule.claimPregenWallets('user@email.com', 'EMAIL');

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 = "user@example.com";

// 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

​

Reference Example

For a complete example demonstrating the usage of pregeneration methods, refer to our

.

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