Wallet Control Strategies

When you develop with Levain, you have the flexibility to choose how you want to manage your users' wallets. This article explores the different wallet control strategies available to you. There are no specific parameters needed to create a wallet with a specific strategy - rather, it is determined by how you manage the keys of the wallet. For example, you may choose to manage the keys yourself or let your users create them through your application.

Developer-controlled wallets

With this strategy, the developer has primary control over the wallet's keys, effectively managing the assets on behalf of the users. This strategy is suitable for applications where the developer is comfortable taking custody of the assets in the users' wallets, or to manage the assets on behalf of the users.

graph BT A[Key 1\nEncrypted user signing key] B[Key 2\nUser backup key] C[Key 3\nLevain key] D[Developer] E[Levain] G[Multi-sig Wallet] D -- encrypted by\ndeveloper's wallet password --> A D --> B E --> C A --> G C --> G subgraph "Levain Cloud" A C end subgraph "Offline storage" B end

In Levain's security model, there are three keys that are generated when a wallet is created:

  • User signing key: Encrypted and sent to Levain using a secret known only to the user, in this case you as the developer.
  • User backup key: A backup key, typically stored offline, and should never be used unless in specific recovery scenarios.
  • Levain key: Controlled by Levain and acts as a signatory of the multi-signature wallet.

For any transaction to be approved, at least two of these keys must be used. The combination of Key 1 (encrypted by the developer's wallet password) and Key 3 (controlled by Levain) enables transaction signing. This ensures that Levain cannot access the developer's private key without explicit permission, and yet the developer can still co-sign transactions on behalf of the user.

User-controlled wallets

In this strategy, the user retains full control over the wallet's user signing key - you as the developer can still offer a Web2-like experience to your users within your application.

This strategy ensures that users have complete autonomy over their wallets, preventing both Levain and the developer from accessing or transferring a user's assets without their explicit permission. To set up a user-controlled wallet, users need to establish their encryption secret and complete a recovery flow during your users' onboarding journey with your application.

graph BT A[Key 1\nEncrypted user signing key] B[Key 2\nUser backup key] C[Key 3\nLevain key] D[Developer] E[Levain] G[Multi-sig Wallet] H[User] I[Developer's app] D --> I D ---> B E --> C H --> I I -- encrypted by\nuser's wallet password --> A A --> G C --> G subgraph "Levain Cloud" A C end subgraph "Offline storage" B end

The three keys are generated in the same way as the developer-controlled wallet, except with a slight difference in the User signing key:

  • User signing key: Encrypted and sent to Levain using a wallet password known only to the user, through your application.
  • User backup key: A backup key, typically stored offline, and should never be used unless in specific recovery scenarios.
  • Levain key: Controlled by Levain and acts as a signatory of the multi-signature wallet.

The combination of the User signing key (encrypted by the user's wallet password) and Levain key (controlled by Levain) enables transaction signing. This ensures that:

  • Levain cannot access the user's private key at all
  • You as the developer can build a co-signing experience on your application, for example by abstracting the private key decryption process away from the user through Web2 logins (e.g. Google, Facebook, etc.) or PINs
  • The user can still co-sign transactions on their own through your application

This ensures that the user has full control over the wallet's signing key, and the developer cannot access the user's assets without their explicit permission.

Having multiple recovery flows in your application can ensure that you have multiple fail-safes when it comes to wallet recovery.

In this case, you are expected to have recovery flows in your application that allows users:

  • to recover their wallet using a recovery mechanism defined by your application (e.g. recovery questions), and
  • to recover their wallet using the backup key held by you.