How It Works

Mesh Wallet-as-a-Service simplifies the integration of blockchain wallets into your application while maintaining a high standard of security and user control. This guide explains the key principles behind its design, including its non-custodial architecture, secure key management, and recovery mechanisms. By leveraging Mesh, developers can provide users with a seamless and secure wallet experience without compromising on privacy or self-custody.

Non-custodial design

Mesh wallet-as-a-service are designed to be strictly non-custodial, meaning neither the developer nor Mesh can access the user’s private key.

By design, the private key only exists in-memory within an isolated iframe on the user’s device and does not persist past the iframe’s lifetime. The iframe runs on a separate domain from the developer’s application, and modern browser security ensures that storage is partitioned across domains.

Key management

This section describes how the private key for the user’s wallet is generated, secured, and used for signing transactions.

Create and secure the private key

When a user creates a wallet, the iframe generates a secure private key and converts to a mnemonic. From this private key, the wallet derives all public information, including the wallet address. During the creation process, the user sets a signing password and a recovery question and answer which are used to secure each key shard.

To enhance security and enable self-custody, the private key is split into three shards using Shamir’s Secret Sharing:

Device Share: Encrypted with the user’s signing password and stored locally on their device within the iframe. This prevents unauthorized access and remains separate from the developer’s application.
Auth Share: Encrypted and secured by Mesh with row-level security. A valid JSON Web Token (JWT) is required to retrieve this shard.
Recovery Share: Encrypted with the user’s recovery answer when creating the wallet.

The private key requires any two out of the three key shards to be reconstructed for signing. It is assembled only in-memory on the user’s device and is never persisted or accessible by Mesh. If a user forgets their recovery answer, Mesh cannot recover the key.

The device share is encrypted with the user’s spending password and stored locally on the user’s device. The device share is used to sign transactions and is only accessible when the user is logged in and provides their spending password. The device share is never sent to Mesh or the developer’s application.

The auth share is encrypted and stored by Mesh. The auth share is used to sign transactions and is only accessible when the user is logged in and provides a valid JWT.

Users can set a memorable recovery question and answer to secure the recovery share for their wallet. Mesh has no knowledge of the user’s recovery answer and cannot decrypt the recovery share. Mesh implements a key management system to secure the encrypted recovery share on behalf of the user.

This allows the user to recover their wallet on a new device as needed, by providing the correct recovery answer. Mesh’s key management infrastructure enforces that only the user can decrypt their recovery share on their device and is set up to prevent any unauthorized access.

Using the private key for signing

When the wallet is needed to produce a signature, the process works as follows:

The developer’s application build the transaction and the CBOR is sent to the iframe via the @meshsdk/web3-sdk package.
The user must be logged in with a valid JWT to retrieve the auth share.
If the device share is available, user’s spending password is required to decrypt it.
The iframe reconstructs the private key in-memory using the device share and auth share.
The private key is used to sign the transaction.
The signature is returned to the developer’s application, and the memory is immediately cleared when the iframe closes.

If the device share is not available (at step 3) or the user forgets their signing password, they must go through the recovery process to regain access to their wallet.

Recovering the wallet

If a user access their wallet from a new device or forgets their signing password, they can initiate the recovery process:

The iframe retrieves the auth share and encrypted recovery share using a valid JWT.
User can provide the recovery answer to decrypt the recovery share.
Once both the auth share and recovery share are obtained, reconstructs the private key and generates new key shares:
- The user sets a new signing password to encrypt the device share.
- A new recovery answer encrypt the recovery share.

After recovery process is completed, the wallet remains the same (same key and address), and the new device share allows the user to continue using the wallet on their new device without needing repeated recovery. User can proceed to sign transactions as usual.

By following this approach, wallets provide strong security while ensuring users can recover their wallet if needed.

Exporting keys to any CIP-30 compatible wallet

When the user wants to export their keys, they can do so at any time. User are prompted to start the recovery process, and the wallet provides a mnemonic phrase that can be used to import the key into any CIP-30 compatible wallet. This feature ensures that users always have full control over their assets and can move them to other wallets if needed.

Users can also choose to delete their data at any time.

Overview User Interface