From 7b1a1b54c281e98aa9802c38bd736ff0f2b80cce Mon Sep 17 00:00:00 2001 From: Andrei Ivasko Date: Mon, 12 Apr 2021 03:18:07 -0700 Subject: [PATCH] Keyring migrate command doc (#8979) * draft * update * address comments, ready for review * delete thr last line * Update docs/migrations/keyring.md Co-authored-by: Barrie Byron * Update docs/migrations/keyring.md Co-authored-by: Barrie Byron * Update docs/migrations/keyring.md Co-authored-by: Barrie Byron * Update docs/migrations/keyring.md Co-authored-by: Barrie Byron * Update docs/migrations/keyring.md Co-authored-by: Barrie Byron * Update docs/migrations/keyring.md Co-authored-by: Barrie Byron * Update docs/migrations/keyring.md Co-authored-by: Barrie Byron * ready for review * Update docs/migrations/keyring.md Co-authored-by: Amaury <1293565+amaurym@users.noreply.github.com> Co-authored-by: SaReN Co-authored-by: Barrie Byron Co-authored-by: Alessio Treglia Co-authored-by: Amaury <1293565+amaurym@users.noreply.github.com> (cherry picked from commit d5f5fe68d0e93d271718ef13f40b74687ad0026a) --- docs/migrations/README.md | 1 + docs/migrations/keyring.md | 31 +++++++++++++++++++++++++++++++ 2 files changed, 32 insertions(+) create mode 100644 docs/migrations/keyring.md diff --git a/docs/migrations/README.md b/docs/migrations/README.md index 845f661425e4..9b122044ec7b 100644 --- a/docs/migrations/README.md +++ b/docs/migrations/README.md @@ -11,3 +11,4 @@ This folder contains all the migration guides to update your app and modules to 1. [App and Modules Migration](./app_and_modules.md) 1. [Chain Upgrade Guide to v0.40](./chain-upgrade-guide-040.md) 1. [REST Endpoints Migration](./rest.md) +1. [Keyring Migration](./keyring.md) diff --git a/docs/migrations/keyring.md b/docs/migrations/keyring.md new file mode 100644 index 000000000000..dbd51269b600 --- /dev/null +++ b/docs/migrations/keyring.md @@ -0,0 +1,31 @@ + +# Keyring Migrate Quick Start + +`keyring` is the Cosmos SDK mechanism to manage the public/private keypair. Cosmos SDK v0.42 (Stargate) introduced breaking changes in the keyring. + +To upgrade your chain from v0.39 (Launchpad) and earlier to Stargate, you must migrate your keys inside the keyring to the latest version. For details on configuring and using the keyring, see [Setting up the keyring](../run-node/keyring.md). + +This guide describes how to migrate your keyrings. + +The following command migrates your keyrings: + +```bash +Usage +simd keys migrate +``` + +The migration process moves key information from the legacy db-based Keybase to the [keyring](https://github.com/99designs/keyring)-based Keyring. The legacy Keybase persists keys in a LevelDB database in a 'keys' sub-directory of the client application home directory (`old_home_dir`). For example, `$HOME/.gaiacli/keys/` for [Gaia](https://github.com/cosmos/gaia). + +You can migrate or skip the migration for each key entry found in the specified `old_home_dir` directory. Each key migration requires a valid passphrase. If an invalid passphrase is entered, the command exits. Run the command again to restart the keyring migration. + +The `migrate` command takes the following flags: +- `--dry-run` boolean + + - true - run the migration but do not persist changes to the new Keybase. + - false - run the migration and persist keys to the new Keybase. + +Recommended: Use `--dry-run true` to test the migration without persisting changes before you migrate and persist keys. + +- `--keyring-backend` string flag. It allows you to select a backend. For more detailed information about the available backends, you can read [the keyring guide](../run-node/keyring.md).