Recovery - Stellar Developer Docs

This guide is available on four different programming languages: Typescript, Kotlin, Flutter (Dart) and Swift. You can change the shown version on each page via the buttons above.

The Sep-30 standard defines the standard way for an individual (e.g., a user or wallet) to regain access to their Stellar account after losing its private key without providing any third party control of the account. During this flow the wallet communicates with one or more recovery signer servers to register the wallet for a later recovery if it’s needed.

Create Recoverable Account

First, let’s create an account key, a device key, and a recovery key that will be attached to the account.

TypeScript
Kotlin
Flutter
Swift

const accountKp = wallet.stellar().account().createKeypair();
const deviceKp = wallet.stellar().account().createKeypair();
const recoveryKp = wallet.stellar().account().createKeypair();

  val accountKp = wallet.stellar().account().createKeyPair()
  val deviceKp = wallet.stellar().account().createKeyPair()
  val recoveryKp = wallet.stellar().account().createKeyPair()

var accountKp = wallet.stellar().account().createKeyPair();
var deviceKp = wallet.stellar().account().createKeyPair();
var recoveryKp = wallet.stellar().account().createKeyPair();

let accountKp = wallet.stellar.account.createKeyPair()
let deviceKp = wallet.stellar.account.createKeyPair()
let recoveryKp = wallet.stellar.account.createKeyPair()

The accountKp is the wallet’s main account. The deviceKp we will be adding to the wallet as a signer so a device (eg. a mobile device a wallet is hosted on) can take control of the account. And the recoveryKp will be used to identify the key with the recovery servers. Next, let’s identify the recovery servers and create our recovery object:

TypeScript
Kotlin
Flutter
Swift

const server1Key = "server1";
const server1 = {
  endpoint: "recovery-example.com",
  authEndpoint: "auth-example.com",
  homeDomain: "test-domain",
};

const server2Key = "server2";
const server2 = {
  endpoint: "recovery-example2.com",
  authEndpoint: "auth-example2.com",
  homeDomain: "test-domain2",
};

const recovery = wallet.recovery({
  servers: { [server1Key]: server1, [server2Key]: server2 },
});

val first = RecoveryServerKey("first")
val second = RecoveryServerKey("second")
val firstServer = RecoveryServer("recovery.example.com", "auth.example.com", "example.com")
val secondServer = RecoveryServer("recovery2.example.com", "auth2.example.com", "example.com")
val servers = mapOf(first to firstServer, second to secondServer)
val recovery = wallet.recovery(servers)

var first = RecoveryServerKey("first");
var second = RecoveryServerKey("second");
var firstServer = RecoveryServer("https://recovery.example1.com", "https://auth.example1.com", "recovery.example1.com");
var secondServer = RecoveryServer("https://recovery.example2.com", "https://auth.example2.com", "recovery.example2.com");
var servers = {first:firstServer, second:secondServer};
var recovery = wallet.recovery(servers);

let first = RecoveryServerKey(name: "first")
let second = RecoveryServerKey(name: "second")

let firstServer = RecoveryServer(endpoint:"https://recovery.example1.com",
                                authEndpoint:"https://auth.example1.com",
                                homeDomain:"recovery.example1.com")

let secondServer = RecoveryServer(endpoint:"https://recovery.example2.com",
                                  authEndpoint:"https://auth.example2.com",
                                  homeDomain:"recovery.example2.com")

let servers = [first: firstServer, second:secondServer]

let recovery = wallet.recovery(servers: servers)

Next, we need to define SEP-30 identities. In this example we are going to create an identity for both servers. Registering an identity tells the recovery server what identities are allowed to access the account.

TypeScript
Kotlin
Flutter
Swift

const identity1 = {
  role: RecoveryRole.OWNER,
  authMethods: [
    {
      type: RecoveryType.STELLAR_ADDRESS,
      value: recoveryKp.publicKey,
    },
  ],
};

const identity2 = {
  role: RecoveryRole.OWNER,
  authMethods: [
    {
      type: RecoveryType.EMAIL,
      value: "[email protected]",
    },
  ],
};

  val identity1 = listOf(RecoveryAccountIdentity(
        RecoveryRole.OWNER,
        listOf(RecoveryAccountAuthMethod(RecoveryType.STELLAR_ADDRESS, recoveryKp.address))
      )
    )

    val identity2 = listOf(RecoveryAccountIdentity(
        RecoveryRole.OWNER,
        listOf(RecoveryAccountAuthMethod(RecoveryType.EMAIL, "[email protected]"))
      )
    )

var identity1 = [
  RecoveryAccountIdentity(RecoveryRole.owner, [
    RecoveryAccountAuthMethod(RecoveryType.stellarAddress, recoveryKp.address)
  ])
];

var identity2 = [
  RecoveryAccountIdentity(RecoveryRole.owner,
      [RecoveryAccountAuthMethod(RecoveryType.email, "[email protected]")])
];

let identity1 = [
    RecoveryAccountIdentity(role:RecoveryRole.owner,
                            authMethods: [RecoveryAccountAuthMethod(type:RecoveryType.stellarAddress,
                                                                    value:recoveryKp.address)])
]

let identity2 = [
    RecoveryAccountIdentity(role:RecoveryRole.owner,
                            authMethods: [RecoveryAccountAuthMethod(type:RecoveryType.email,
                                                                    value:"[email protected]")])
]

Here, stellar key and email are used as recovery methods. Other recovery servers may support phone as a recovery method as well. You can read more about SEP-30 identities here Next, let’s create a recoverable account:

TypeScript
Kotlin
Flutter
Swift

const config = {
  accountAddress: accountKp,
  deviceAddress: deviceKp,
  accountThreshold: { low: 10, medium: 10, high: 10 },
  accountIdentity: { [server1Key]: [identity1], [server2Key]: [identity2] },
  signerWeight: { device: 10, recoveryServer: 5 },
};
const recoverableWallet = await recovery.createRecoverableWallet(config);

  val recoverableWallet =
    recovery.createRecoverableWallet(
      RecoverableWalletConfig(
        accountKp,
        deviceKp,
        AccountThreshold(10, 10, 10),
        mapOf(first to identity1, second to identity2),
        SignerWeight(10, 5)
      )
    )

var recoverableWallet = await recovery.createRecoverableWallet(
    RecoverableWalletConfig(
        accountKp,
        deviceKp,
        AccountThreshold(10, 10, 10),
        {first: identity1, second: identity2},
        SignerWeight(10, 5)
    )
);

let config = RecoverableWalletConfig(accountAddress: accountKp,
                                    deviceAddress: deviceKp,
                                    accountThreshold: AccountThreshold(low: 10, medium: 10, high: 10),
                                    accountIdentity: [first : identity1, second: identity2],
                                    signerWeight: SignerWeight(device: 10, recoveryServer: 5))

let recoverableWallet = try await recovery.createRecoverableWallet(config: config)

With the given parameters, this function will create a transaction that will:

Set deviceKp as the primary account key. Please note that the master key belonging to accountKp will be locked. deviceKp should be used as a primary signer instead.
Set all operation thresholds to 10. You can read more about threshold in the documentation
Use identities that were defined earlier on both servers. (That means, both server will accept SEP-10 authentication via recoveryKp as an auth method)
Set device key weight to 10, and recovery server weight to 5. Given these account thresholds, both servers must be used to recover the account, as transaction signed by one will only have weight of 5, which is not sufficient to change account key.

Finally, sign and submit transaction to the network:

TypeScript
Kotlin
Flutter
Swift

recoverableWallet.transaction.sign(accountKp.keypair);

await stellar.submitTransaction(recoverableWallet.transaction);

  val tx = recoverableWallet.transaction.sign(accountKp)

  wallet.stellar().submitTransaction(tx)

var transaction = recoverableWallet.transaction;
transaction.sign(accountKp.keyPair, flutter_sdk.Network.TESTNET);
await wallet.stellar().submitTransaction(transaction);

let transaction = recoverableWallet.transaction
try transaction.sign(keyPair: accountKp.keyPair, network: Network.testnet)
try await wallet.stellar.submitTransaction(signedTransaction: transaction)

Get Account Info

You can fetch account info from one or more servers. To do so, first we need to authenticate with a recovery server using the SEP-10 authentication method:

TypeScript
Kotlin
Flutter
Swift

const authToken = await recovery
  .sep10Auth(server1Key)
  .authenticate({ accountKp: recoveryKp });

  val auth1 = recovery.sep10Auth(first).authenticate(recoveryKp)

var sep10 = await recovery.sep10Auth(first);
var authToken = await sep10.authenticate(recoveryKp);

let sep10 = try await recovery.sep10Auth(key: first)
let authToken = try await sep10.authenticate(userKeyPair: recoveryKp)

Next, get account info using auth tokens:

TypeScript
Kotlin
Flutter
Swift

const accountResp = await recovery.getAccountInfo(accountKp, {
  [server1Key]: authToken,
});

  val accountInfo = recovery.getAccountInfo(account, mapOf(first to auth1))

  println("Recoverable info: $accountInfo")

var accountInfo = await recovery.getAccountInfo(accountKp, {first: authToken.jwt});

let accountInfo = try await recovery.getAccountInfo(accountAddress: accountKp,
                                                    auth: [first:auth1Token.jwt])

Our second identity uses an email as an auth method. For that we can’t use a [SEP-10] auth token for that server. Instead we need to use a token that ties the email to the user. For example, Firebase tokens are a good use case for this. To use this, the recovery signer server needs to be prepared to handle these kinds of tokens. Getting account info using these tokens is the same as before.

TypeScript
Kotlin
Flutter
Swift

// get token from firebase
const firebaseToken = AuthToken.from(<firebase token string>)

const accountResp = await recovery.getAccountInfo(accountKp, {
  [server2Key]: firebaseToken,
});

  // get token from firebase
  val firebaseToken = AuthToken.from(<firebase token string>)

  val accountInfo = recovery.getAccountInfo(account, mapOf(second to firebaseToken))

  println("Recoverable info: $accountInfo")

var accountInfo = await recovery.getAccountInfo(accountKp, {second: <other token string>});

let accountInfo = try await recovery.getAccountInfo(accountAddress: accountKp,
                                                    auth: [second:<other token string>])

Recover Wallet

Let’s say we’ve lost our device key and need to recover our wallet. First, we need to authenticate with both recovery servers:

TypeScript
Kotlin
Flutter
Swift

const authToken1 = await recovery
  .sep10Auth(server1Key)
  .authenticate({ accountKp: recoveryKp });

// get firebase token using firebase
const firebaseToken = AuthToken.from(<firebase token string>)

  val auth1 = recovery.sep10Auth(first).authenticate(recoveryKp)

  // get firebase token using firebase
  val firebaseToken = AuthToken.from(<firebase token string>)

var sep10 = await recovery.sep10Auth(first);
var authToken = await sep10.authenticate(recoveryKp);

var auth1 = authToken.jwt;
var auth2 = "..."; // get other token e.g. firebase token

let sep10 = try await recovery.sep10Auth(key: first)
let authToken = try await sep10.authenticate(userKeyPair: recoveryKp)

let auth1 = authToken.jwt
let auth2 = "..."; // get other token e.g. firebase token

We need to know the recovery signer addresses that will be used to sign the transaction. You can get them from either the recoverable wallet object we created earlier (recoverableWallet.signers), or via fetching account info from recovery servers.

TypeScript
Kotlin
Flutter
Swift

const recoverySignerAddress1 = recoverableWallet.signers[0];
const recoverySignerAddress2 = recoverableWallet.signers[1];

  val recoverySigners = recoverableWallet.signers

var recoverySigners = recoverableWallet.signers;

let recoverySigners = recoverableWallet.signers

Next, create a new device key and retrieve a signed transaction that replaces the device key:

TypeScript
Kotlin
Flutter
Swift

const newDeviceKp = accountService.createKeypair();

const serverAuth = {
  [server1Key]: {
    signerAddress: recoverySignerAddress1,
    authToken1,
  },
  [server2Key]: {
    signerAddress: recoverySignerAddress2,
    firebaseToken,
  },
};

const recoverTxn = await recovery.replaceDeviceKey(
  accountKp,
  newDeviceKp,
  serverAuth,
);

  val newKey = wallet.stellar().account().createKeyPair()

  val serverAuth = mapOf(
    first to RecoveryServerSigning(recoverySigners[0], auth1),
    second to RecoveryServerSigning(recoverySigners[1], firebaseToken)
  )

  val signedReplaceKeyTransaction =
    recovery.replaceDeviceKey(
      accountKp,
      newKey,
      serverAuth
    )

var newKey = wallet.stellar().account().createKeyPair();
var serverAuth = {
  first: RecoveryServerSigning(recoverySigners[0], auth1),
  second: RecoveryServerSigning(recoverySigners[1], auth2)
};

var signedReplaceKeyTx = await recovery.replaceDeviceKey(accountKp, newKey, serverAuth);

let newKey = wallet.stellar.account.createKeyPair()
let serverAuth = [
    first: RecoveryServerSigning(signerAddress: recoverySigners[0] , authToken: auth1),
    second: RecoveryServerSigning(signerAddress: recoverySigners[1] , authToken: auth2),
]

let signedReplaceKeyTx = try await recovery.replaceDeviceKey(account: accountKp,
                                                             newKey: newKey,
                                                             serverAuth: serverAuth)

Calling this function will create a transaction that locks the previous device key and replaces it with your new key (having the same weight as the old one). Both recovery signers will have signed the transaction. The lost device key is deduced automatically if not given. A signer will be considered a device key, if one of these conditions matches:

It’s the only signer that’s not in serverAuth.
All signers in serverAuth have the same weight, and the potential signer is the only one with a different weight.

The account created above will match the first criteria. If a 2-3 schema were used, then the second criteria would match. (In a 2-3 schema, 3 servers are used and 2 of them are enough to recover the key. This is a recommended approach.)You can also use more low-level signWithRecoveryServers functions to sign arbitrary transactions.

Finally, it’s time to submit the transaction:

TypeScript
Kotlin
Flutter
Swift

await stellar.submitTransaction(recoverTxn);

  wallet.stellar().submitTransaction(signedReplaceKeyTransaction)

await wallet.stellar().submitTransaction(signedReplaceKeyTx);

try await wallet.stellar.submitTransaction(signedTransaction: signedReplaceKeyTx)

​Create Recoverable Account

​Get Account Info

​Recover Wallet

Create Recoverable Account

Get Account Info

Recover Wallet