Overview
Wallet Pregeneration allows you to create wallets for users before they set up a wallet with Para. 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 Para’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 Para 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.
Creating a Pregenerated Wallet
Before creating a wallet for a user, it’s a good practice to check if one already exists.Check if a pregenerated wallet exists
Create a pregenerated wallet if needed
Method Parameters
PregenAuth Type Definition
The identifier can be an email or phone number, a third-party user ID (for Farcaster, Telegram, Discord, or X), or a custom ID relevant to your application. Choose an identifier that works best for your application architecture.
Storing and Managing User Share
After creating a pregenerated wallet, it’s crucial to securely store the user share. This share is part of Para’s 2/2 MPC protocol and remains the application’s responsibility until the wallet is claimed. To retrieve the user share for a pregenerated wallet, use thegetUserShare
method:
You must securely store this user share in your backend, associated with the user’s identifier. If this share is lost,
the wallet becomes permanently inaccessible.
Best Practices for Storing the UserShare
While temporarily managing theUserShare
, it’s important that you take extra care with how you store this information.
If you ever face a situation where data becomes compromised across your systems, reach out to the Para team so we can
work on possible key rotation. However, keep in mind that Para 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
UserShares
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
Para is happy to offer pre-launch security reviews for teams in the Growth tier or above. Let us know if you need
help!
Using a Pregenerated Wallet
Before using a pregenerated wallet for signing operations, you must first load the user share into your Para client instance. Retrieve theUserShare
from your secure storage and load it into Para using the setUserShare
method:
You can perform this operation using either
@getpara/server-sdk
@alpha or @getpara/react-sdk/@alpha@getpara/web-sdk
@alpha depending
on your application architecture. The Para client that has the user share loaded is the one that can perform signing
operations.Using with Ecosystem Libraries
Once theuserShare
is set, your Para client functions like any standard wallet. You can now easily integrate with
popular blockchain libraries to perform transactions and other operations.
For detailed integration guides with blockchain ecosystems, see:
Claiming a Pregenerated Wallet
Claiming pregenerated wallets must be done client-side with the Para Client SDK. The Server SDK does not support the
key rotation operations required for wallet claiming.
- The user must be fully authenticated with Para
- The wallet’s user share must be loaded into the Para client
- The wallet’s identifier must match the authenticated user’s identifier
Prerequisites for Claiming
Claiming with the modal
Define the function fetchPregenWalletsOverride
This function retrieves the userShare
associated with the passed pregenId
from your backend.
Pass fetchPregenWalletsOverride
as a field in opts
to the paraClientConfig
This step allows our frontend logic to automatically fetch the correct userShare
for claiming when the user is first creating an account through the modal flow.
Claiming manually
Authenticate the user
Ensure the user has completed Para’s authentication flow and has an active session.Load the wallet’s user share
Since this is a client side only operation, you need to securely send theUserShare
from your server to the client. Once received, load it into the Para client:
Update wallet identifier if needed
Ensure the pregenerated wallet’s identifier matches the authenticated user’s identifier:Claiming the Wallet
Once prerequisites are met, you can claim the wallet:If the userShare is already loaded into the Para client before authentication occurs, and if the pregenerated wallet’s
identifier matches the authenticating user, the wallet will be automatically claimed during authentication.
Controlling When Wallets are Claimed
You have control over when users claim their pregenerated wallets:- Delayed Claiming: Only load the userShare and update the identifier when you’re ready for the user to claim the wallet. This allows your application to continue using the wallet on behalf of the user.
- Immediate Claiming: If you want immediate claiming upon user authentication, load the userShare before authentication and ensure the identifiers match.
- No Claiming: Keep using different identifiers for the wallet than the user’s actual identifier to prevent automatic claiming.
Core Pregeneration Methods
Best Practices and Considerations
App-specific vs. Cross-app Usage
App-specific vs. Cross-app Usage
Pregenerated wallets are app-specific until claimed. Before claiming, they can only be used within your application through the
UserShare
. After a user claims the wallet, it becomes part of their Para account, allowing them to use it across different Para-integrated applications. This transition from app-managed to user-managed is a key consideration in your implementation strategy.Identifier Management
Identifier Management
Choose identifiers that align with your application architecture: - Email/Phone: Most common for user-facing
applications - OAuth Identifiers: Useful for social login integrations (Discord, Twitter) - Custom IDs: Ideal
for internal user management systems Consider your user onboarding flow when choosing identifiers. If you use custom
IDs initially, you’ll need to update them to match the user’s actual identifier (email/phone) before claiming can
occur.
Secure Storage Practices
Secure Storage Practices
The user share is critical security information that must be protected: - Encryption: Always encrypt user shares
both in transit and at rest - Database Security: Implement proper access controls for your share database -
Backups: Maintain regular database backups to prevent data loss - Disaster Recovery: Create processes for
handling compromise scenarios - Key Rotation: Have a plan for working with Para if key rotation becomes necessary
Consider implementing a fire drill before launching to test scenarios like database loss, access issues, or credential
compromise. Para offers security reviews for teams on Growth tier and above.
User Experience Design
User Experience Design
Plan your user experience around wallet claiming: - Delayed Claiming: Keep control of wallets until users are
ready for full ownership - Automatic Claiming: Configure for immediate claiming during authentication -
Progressive Onboarding: Start users with app-managed wallets, then transition to self-custody - Educational
Elements: Help users understand the transition from app-managed to self-custody The claiming process should feel
seamless and intuitive to users while giving you flexibility in your application architecture.
Wallet Type Considerations
Wallet Type Considerations
Be deliberate about the wallet types you create:
- Match Blockchain Needs: Select wallet types (EVM, Solana, Cosmos) based on your application’s blockchain requirements
- Multiple Types: Consider creating multiple wallet types if your application spans multiple blockchains
- Default Selection: If your app supports multiple chains, create wallets for all required types during pregeneration
- User Guidance: Provide clear information about which blockchain networks are supported by each wallet
Server vs. Client Operations
Server vs. Client Operations
Understand the operational boundaries:
- Server-side: Create pregen wallets, store user shares, sign transactions (with loaded shares)
- Client-side only: Create and claim wallets, load user shares, sign transactions