Blog Article

SEP-30 and User-Friendly Key Management


Leigh McCulloch

Publishing date


Key management

Part III: SEP-30 for User-Friendly Apps

If you’ve followed us this far in the SEP-30 series, you know how important user experience is in driving adoption of blockchain technology, and you have a better understanding of the shortcomings of key management and recovery today.

Now, it’s time for the pay-off: an explanation of how SEP-30 provides a seamless, user-focused solution for key management and key recovery.

For those who aren’t familiar, Stellar Ecosystem Proposals — SEPs for short — are open specifications that define best practices for building products and services on Stellar. There are all kinds of SEPs, and they relate to all kinds of use cases, but generally, they explain how projects building on Stellar set up infrastructure external to the network — including APIs — to maximize interoperability with other network participants.

SEP-30 defines an approach focused on making key management, and specifically loss prevention, as user-friendly as possible. It's designed to:

  1. Work without recovery phrases.
  2. Prevent a third party from controlling a user's account.
  3. Ensure a user doesn't need to remember a password.

SEP-30 is live and operational in one wallet, Vibrant, a non-custodial US dollar savings app that stores value on the Stellar network. Vibrant, which soft launched recently, presents a user experience designed for the general public.

The only thing a user needs to log in to Vibrant is their phone number. That's it. No secret key, no password, just a phone number. That's because a SEP-30 wallet like Vibrant doesn't manage and backup a single master key. Instead, it manages device keys, and uses multi-sig and distributed servers to create new ones when necessary. It still does many of the same things other wallets do — it stores and protects a key; it helps a user sign transactions; it prevents loss — but the loss it prevents is different: it prevents users from losing their accounts, not their keys.

SEP-30 Setup

SEP-30 defines an API that provides two endpoints, one to register an account and one to sign transactions. A third party sets up a recovery server hosting those two endpoints, and the SEP-30 wallet sets up a client to consume them. For the whole thing to work, the wallet needs to interact with two separate, independent recovery servers.

A wallet uses the first endpoint to register an account with a third-party recovery server. In that request, the wallet tells the server what identities are permitted to request signatures for the account. Identities are generally phone numbers or email addresses.

The wallet authenticates using SEP-10, a Stellar Ecosystem Proposal that defines a challenge-response flow. Authentication allows the wallet to prove to the server that it possesses keys that can sign for the user's Stellar account, which means it can define who is permitted to sign transactions for that account. In response, the wallet gets back a signing address for the server, and it makes that address a signer on the user's Stellar account.

The second recovery server endpoint handles transaction signing. When a user loses access to their account, the wallet calls this endpoint with a transaction it wants the server to sign. The wallet authenticates using an identity provided during registration, and if the phone or email matches an identity it has on file for the account, the server signs the transaction for the Stellar account and returns the signature to the wallet.

To better understand how that setup allows for a simple, seamless user experience, let's take a look at the SEP-30 flows for account registration and recovery.

How Registration Works

1. When Alice creates an account using the wallet app on her phone, the app generates a master key, and the wallet server creates the associated account. The master key, which is the red key in the diagram, is one of those big S addresses that we looked at in the previous post. The master key isn't shared with anyone, and it never leaves Alice's device.

Because of the way SEP-30 works, there's no need for this master key to be backed up anywhere.

2. Alice’s wallet also generates a second key, which we’ll call a device key. It’s a key that is only used by the device — in this case Alice's phone — to sign transactions. The device key, like the master key, is not shared with anyone.

3. Alice’s wallet submits a transaction to the Stellar network making that device key a signer on the account and removing the master key as a signer. It then deletes the master key: it’s not useful anymore.

4. The wallet then registers the account with two recovery servers. Each server is hosted and controlled by a separate, independent entity, and each has its own self-generated key. The wallet proves to each server that it has authority over Alice's account by signing a SEP-10 transaction, and tells each recovery server that anyone who can prove possession of Alice's phone number or email should be allowed to request for transactions to be signed.

5. The wallet submits a transaction to the Stellar network adding both recovery servers as signers on the account, but limiting the weight of their signatures so that neither has independent control over the value in the account. Each recovery server can now sign a transaction at the request of the user, but the transaction will only be authorized if it's signed by both independent parties.

The only individual with independent control of the account is Alice.

How Recovery Works

Let’s imagine Alice lost her phone and had to get a new one. Alice’s lost phone still has her device key on it, and her new phone has no key for the account.

1. Alice’s new phone goes through the same process that her previous phone did when it signed up with the wallet server: it generates a device key, and signs in to the wallet.

The new device key is not a signer of her Stellar account, so her device cannot authorize transactions. At least not yet.

2. The wallet pings the first recovery server and asks it to sign a transaction that makes Alice's new device key a signer on the account. This first signature adds a weight of 10 to the transaction.

3. Alice then continues recovery with the second recovery server. The second recovery server is operated by an independent third party, so Alice authenticates with them independently using an SMS code sent to her phone, or a link or code sent to her email address. Once Alice has authenticated, the server signs the transaction and returns the signature to the wallet. This signature adds an additional weight of 10 to the transaction.

4. The transaction now has a weight of 20, which is sufficient to authorize it, so the wallet submits it to the network. The transaction removes the signing key that was lost with Alice’s old phone, and adds the new signing key that lives on Alice’s new phone.

Alice is now back in control of her Stellar account.

The User Experience

In the examples above, Alice registered and recovered access to her account using only her phone number. She never gave a third party full control of her account, and everything happened via API behind the scenes. She didn't have to think about it or understand how key recovery works: she just agreed to terms of service like she would with any other product, and the wallet handled the rest. That's the same user experience Alice — and all of us, really — expect from a consumer application.

Great user experience drives adoption, and supporting account recovery through phone, email, and other forms of authentication means you can actually build a user-friendly non-custodial wallet. Pretty neat.

The thing about SEP-30, however, is that it relies on a certain amount of ecosystem infrastructure: for it to work, there need to be both SEP-30 wallets and independent recovery servers. So if you've come this far, and you're excited about the benefits this key management approach can bring to the crypto-consumer experience, we'd love to hear from you. We can all work together to build the key management infrastructure the ecosystem needs.

If you're interested in building a SEP-30 wallet or running a recovery server — let us know!