Back up a wallet
This guide will walk you through how backups of a user's wallet are set up with Portal.
If you're set up to use Portal-managed backups, your application will not require the backend implementation described in this guide. Instead, you can jump straight to Backup methods.
MPC backups allow your users to recover their MPC wallets in the event that their device is lost, stolen, or bricked.
Backups are handled in two pieces: user backup shares and custodian backup shares. Your infrastructure will store both of them.
At the time of recovery, a user and a custodian backup share are used together to generate new signing shares, which are then stored on the user's device. This allows the user to migrate their wallet to a new device seamlessly.
Additionally, a user can back up their wallet once per backup method. That means they can potentially have "GDRIVE"
, "ICLOUD"
, "PASSWORD"
, and "PASSKEY"
backups simultaneously, which would allow them to easily recover their wallet using any of those backup methods.
![](https://docs.portalhq.io/~gitbook/image?url=https%3A%2F%2F1744168258-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F8fkrdVt5Nxou2X995uAB%252Fuploads%252FIbj56q0NBpsZ8pFRpR00%252F2.%2520MPC%2520Backup%2520Mechanism%2520Setup%2520-%2520dark.png%3Falt%3Dmedia%26token%3Da89db315-39d6-41ec-9780-08af5c978501&width=768&dpr=4&quality=100&sign=ccfef386&sv=1)
Your Database
Before we dive into the backup shares' implementations, we should go over your database schema. Multi-backup requires storing both custodian and user backup shares by their respective backup method in your own database. We recommend the following database model structure:
We won't go into depth just yet, but it's worth calling out that you can see a couple associations:
A user has many raw custodian backup shares unique by backup method.
A user has many encrypted user backup shares unique by backup method.
The encryption key is stored differently depending on the backup method used.
Perfect, let's dive right into user backup shares.
User Backup Shares
There's a few steps to store your user's backup shares. First, our SDK creates the raw user backup share and then encrypts it. Next, the encryption key is stored using the backup method you specify (e.g. "GDRIVE"
, "ICLOUD"
, "PASSWORD"
, "PASSKEY"
, etc.). Finally, the encrypted user backup share must then be saved in your infrastructure. Be sure to store it for the user by backup method, as a user can only have 1 backup per backup method.
In order to support user backup shares, three main dependencies must be met:
You must configure 1 or many backup methods when initializing
Portal
.You must be able to store the encrypted user backup share by backup method.
You must be able to retrieve the encrypted user backup share by backup method.
Using Google Drive or iCloud Backups
In order to enable Google Drive or iCloud backups, you must first configure one or more cloud storage adapters with your Portal instance.
You can use @portal-hq/gdrive-storage or @portal-hq/icloud-storage (iOS only).
Storing User Backup Shares
After running portal.backupWallet()
, you will receive a cipherText
as a return value (we will get to that part in a moment). This is the encrypted user backup share. On your own API server, we recommend creating an endpoint to accept the encrypted user backup share and store it.
Sending shares to your server
In order to add support for user backup shares to your mobile app, you must perform three steps:
Generate an encrypted user backup share using
portal.backupWallet()
.Send the encrypted user backup share to your API and store it.
Call
portal.api.storedClientBackupShare()
to notify Portal that the encrypted user backup share was saved successfully. (Alternatively you can make an HTTP request to our API directly.)
Custodian Backup Shares
Storing a custodian backup share is done by Portal generating a custodian backup share and sending the share – via webhook – to be stored within your infrastructure.
In order to support custodian backup shares, two main dependencies must be met:
Register a webhook on the Portal Admin Dashboard for your environment (development or production).
Implement the
/backup
webhook endpoint on your server to store the custodian backup shares.
Registering Your Webhook
You can register your webhook for both /backup
and /backup/fetch
endpoints in the Portal Admin Dashboard. Reach out to us if you still need to be invited to your organization's dashboard and we can help.
Implementing the /backup
Webhook
/backup
WebhookPortal will send the raw custodian backup share to POST
[webhookBaseURL]/backup
. The request will include a X-Webhook-Secret
header (you can set this in the Portal Admin Dashboard). The body of this POST
request will contain three fields:
backupMethod
- The backup method and curve used to create the backup share.clientId
- The Portal ID of the user. We recommend keeping track of this.share
- A JSON stringified version of the custodian backup share.
When Portal makes a request to your /backup
webhook, another immediate request is made to /backup/fetch
right after in order to validate the custodian backup share was stored successfully. The /backup/fetch
webhook is explained in the "Handling recovery" doc.
Next steps
Great! You have now set up backups for your users. Before we talk about how to put those backups to use, let's cover all the backup methods your users can make use of.
Last updated