How It Works

UTXOS Wallet-as-a-Service makes it easy to add secure, self-custodial wallets to your app. This page explains how it works—its non-custodial architecture, key management, signing, and recovery. With UTXOS, you can offer a seamless wallet experience without sacrificing privacy or user control.

Non-custodial Design

UTXOS Wallet-as-a-Service is strictly non-custodial: neither your app nor UTXOS can access a user’s private key.

By design, the private key exists only in memory inside an isolated iframe on the user’s device and is discarded when the iframe closes. The iframe runs in a separate process and on a separate domain from your application. Modern browser security also partitions storage across domains, keeping data isolated.

Key Management

This section describes how the private key is created, protected, and used for signing transactions.

Create and Secure the Private Key

When a user creates a wallet, the iframe generates a cryptographically secure private key and derives a mnemonic phrase from it. All public information (addresses, public keys) is derived from this key. During setup, the user creates a passkey or a spending password and a recovery question/answer to protect the key shards.

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

1. Device share: Encrypted with a passkey (preferred) or the user’s spending password and stored locally inside the iframe. It never leaves the device or the iframe’s origin.
2. Auth share: Encrypted and stored by UTXOS with row-level security. A valid JSON Web Token (JWT) is required to retrieve this shard.
3. Recovery share: Encrypted with a passkey (preferred) or the user’s recovery answer at creation time.

Any two of the three shares are required to reconstruct the private key. Reconstruction happens only in memory on the user’s device and is never persisted or accessible by UTXOS. If a user forgets their recovery answer and does not have a passkey, the key cannot be recovered.

Passkeys and WebAuthn (optional, recommended)

For devices, browsers, and password managers that support WebAuthn (with the PRF Extension), UTXOS uses passkeys to strengthen security and improve the user experience.

• On supported systems, passkeys (WebAuthn credentials) use the PRF extension to build a crypto key to encrypt the device share and recovery share instead of (or in addition to) a password. This leverages platform authentication (Touch ID, Face ID, built-in OS passkeys) to protect key material.
• This means:
  1. The passkey is the ownership credential for the wallet and its assets.
  2. Losing the passkey may result in permanent loss of access; UTXOS cannot recover passkeys or decrypt passkey-protected shares.
  3. Only the user should have access to their passkey on their device.

If a device does not support passkeys, the password + recovery question/answer flows remain available as a fallback (see next sections).

Securing the Device Share

The device share is stored locally and protected in one of two ways, depending on device capabilities:

• Passkeys (WebAuthn): On supported devices, the device share is encrypted with the user’s passkey and unlocked with platform authentication (Touch ID, Face ID, or passcode). It is never sent to UTXOS or your application.
• Passwords: On devices without passkey support, the device share is encrypted with the user’s spending password and stored locally within the iframe. It is only accessible when the user is logged in and provides their password.

Securing the Auth Share

The auth share is encrypted and stored by UTXOS. It is required for signing and is only accessible when the user is logged in with a valid JWT.

Securing the Recovery Share

Users can secure the recovery share in one of two ways, depending on device capabilities:

• Passkeys (WebAuthn): When available and set up by the user, the recovery share is encrypted with the user’s passkey. This lets the user recover their wallet on a new device by proving possession of the passkey and completing platform authentication.
• Secret question & answer: On devices without passkey support, the recovery share is encrypted with the user’s recovery answer. UTXOS has no knowledge of the user’s recovery answer and cannot decrypt the recovery share.

Today, recovery is designed to be automatic and seamless: UTXOS securely stores the encrypted recovery share, and the user’s authentication token (JWT) is the root of access. Users don’t need to manage backup files or recovery artifacts.

In the future, we will introduce user-managed recovery so users can store their recovery share in a secure location of their choice (e.g., password managers or cloud backup).

Using the Private Key for Signing

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

1. Your application builds the transaction and sends its CBOR to the iframe via the @meshsdk/web3-sdk package.

2. The user must be logged in; a valid JWT is used to retrieve the auth share.

3. If the device share is available, the user authenticates to decrypt it. On passkey-enabled devices, platform authentication (Touch ID, Face ID, or passcode) unlocks it; otherwise, the user’s spending password is used.

4. The iframe reconstructs the private key in memory using the device share and auth share.

5. The private key signs the transaction.

6. The signature is returned to your application. When the iframe closes, memory is immediately cleared.

   

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

When a passkey is present, users are prompted to complete platform authentication. The passkey both proves ownership and unlocks the encrypted share used to reconstruct the private key.

Recovering the Wallet

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

1. The iframe retrieves the auth share and encrypted recovery share using a valid JWT.

2. The user proves ownership to decrypt the recovery share. If a passkey is set up, it is used to decrypt the recovery share and complete recovery. Otherwise, the user provides the recovery answer (secret question/answer) to decrypt the recovery share.

3. With both the auth share and recovery share, the iframe reconstructs the private key and generates fresh shares:

   • The user sets a new spending password to encrypt the device share.
   • A new recovery answer (or passkey) encrypts the recovery share.

   

After recovery, the wallet remains the same (same key and address). The new device share lets the user continue using the wallet on the new device without repeated recovery. Users can sign transactions as usual.

Important: If a user encrypted their shares with a passkey and loses access to that passkey (for example, loses the device and has no passkey backup), they may permanently lose access to the wallet and its assets. UTXOS cannot recover passkeys or decrypt shares for the user.

This approach delivers strong security while ensuring users can recover their wallet if needed.

Exporting Keys to Compatible Wallet

Users can export their keys at any time. They are prompted to start the recovery process, after which the wallet provides a mnemonic phrase that can be imported into any compatible wallet. This preserves full user control and portability.

Users can also delete their data at any time.