Wallet lifecycle

A Portal Wallet keeps track of the status of its signing shares and backup shares.

There are 4 core MPC operations that can take place with your wallet:

• Generate

• Backup

• Recover

• Sign

The first 3 (Generate, Backup, Recover) are all state changing operations that affect either the set of signing shares or backup shares.

Generate

Generates new signing shares from randomly generated values.

The generate function only modifies signing shares.

Steps

When you call portal.createWallet() two steps happen under the hood.

1. MPC WebSocket Operation - After this completes the custodian signing share will have been successfully stored in Portal's database and client signing share is available on the client device. This updates the signing share status to STORED_DATABASE.

2. Client Signing Share Stored to Keychain - After the WebSocket successfully closes the client signing share is written to the device keychain and the SDK notifies the server that it succeeded. This updates the signing shares status to STORED_CLIENT.

Backup

Generates new backup shares using the signing shares.

This only modifies backup shares.

Steps

When you call portal.backupWallet() the first 2 steps happen under the hood. After the function returns you are required to implement the third step.

1. MPC WebSocket Operation - After this completes the custodian backup shares are saved to the customer backend via the configured webhook. This updates the backup share status to STORED_CUSTODIAN_BACKUP_SHARE.

2. Client Backup Share is Encrypted - The client backup share is encrypted on the client side, the encryption key is uploaded to the user's cloud storage, and the cipher text is returned from the function. The function returns.

3. Client Backup Share Cipher Text Stored to Customer Backend - After the function returns, you are required to call portal.api.storedClientBackupShare() to notify our backend that the client backup share was successfully stored. This updates the backup shares status to STORED_CLIENT_BACKUP_SHARE.

If backup fails you are expected to handle the error (see the Error Reference) and re-run backup after handling it. Recover cannot be run until Backup succeeds.

Recover

Generates new signing shares using the backup shares.

This only affects signing shares.

Steps

When you call portal.recoverWallet() the first 4 steps happen under the hood. After the function returns you are required to implement the third step.

1. MPC WebSocket Operation (Signing Shares) - After this completes the custodian signing share will have been successfully updated in Portal's database and the client signing share is available on the client device.

2. Client Signing Share Stored to Keychain (Signing Shares) - After the WebSocket successfully closes the client signing share is written to the device keychain and the SDK notifies the server that it succeeded. This updates the signing shares status to STORED_CLIENT.

If recovery fails you are expected to handle the error (see the Error Reference) and re-run recovery after handling it. Signing functionality may not work until a successful recover on a new device.