🆕Wallet Pregeneration

Easily provision wallets for your users in the background, then control when you'd like users to claim and take ownership of their wallet

Overview

Wallet Pregeneration makes it easy to create a wallet for a user before they have set up a wallet with capsule, then transfer ownership to them once they’re ready to authenticate, set up a passkey, and continue to hold on to the wallet.

This guide is oriented towards building with pregenerated wallets, for more on how this (or any) feature works, please get in touch!

Capsule Core Concepts

Because of the application’s additional role in MPC with pregeneration, it requires a bit more knowledge of Capsule’s internals. Capsule has the following core concepts relevant to pregeneration:

User Share: This is the share of Capsule’s 2/2 MPC that is typically managed by a users and protected by their auth+passkey

Recovery Secret: This is a client encryption string that permits the user to restore the user share to a new device in the event of device/passkey loss

NOTE: Pregenerated wallets are app-specific until claimed by the user

Creating a Pregen Wallet

First, follow setup instructions here to create the capsule object with your API KEY

Now, create a pregen wallet on behalf of a user using an email the user controls

const pregenWallet = await capsule.createWalletPreGen(userEmail);
const walletId = pregenWallet.id;

Capsule will create a wallet using your partnerId (based on your API KEY) and associate to userEmail - and return the two secrets above

NOTE: the above can be done from either web-sdk or server-sdk. In the latter case, you won’t need to do the session import/export mentioned

Once you’ve done this, you can always update the email as follows

await updateWalletEmailPreGen(newEmail, walletId)

You’ll need to get/set the user share on each session to sign transactions as described in the next section

const userShare = await capsule.getUserShare();
await capsule.setUserShare(userShare)

Signing with a Pregen Wallet

You can also sign messages and transactions as usual, Capsule will know if it is for a pregen wallet or a regular user wallet:

You can also sign with Ethers, Viem, or Wagmi — check out the guide here on how to do this: Signing Transactions

await capsule.signMessage(walletId, messageBase64);
await capsule.signTransaction(walletId, rlpEncodedTxBase64, chainId);

Claiming a Pregen Wallet

The easiest way to claim a pregen wallet is by signing up with a user whose email has an associated pregen wallet

We’re also adding this out to the Capsule Modal.

const verifyEmailandClaim = async (): Promise<void> => {
  if (!capsule) {
    throw new Error('Capsule not instantiated');
  }
  const url = await capsule.verifyEmail(verificationCode);
  setPasskeyCreationUrl(url);
  window.open(url, 'popup', 'popup=true,width=400,height=500');

  // capsule.waitForPasskeyAndCreateWallet checks to see if there is a
  // pregenerated wallet for the current email.
  // if there is one, the wallet is claimed; otherwise a new wallet is created.
  const newRecoverySecret = await capsule.waitForPasskeyAndCreateWallet();
  setWalletAddress(Object.values(capsule.getWallets())[0].address);
  setRecoverySecret(newRecoverySecret);
}

That’s all! The Capsule Modal can also be used to automatically claim pregen wallets.

Examples

Check out a no-ui Example App of pregeneration in action!