From 40e8b619cec78555aafd9dc1c1ac57f23585ecf1 Mon Sep 17 00:00:00 2001
From: Conor Schaefer <conor@ruin.dev>
Date: Tue, 10 Sep 2024 11:03:40 -0700
Subject: [PATCH] docs: add 'pcli migrate balance' explainer

Adds a short explainer for how the `pcli migrate balance` functionality
works. Refs:

* https://github.com/penumbra-zone/penumbra/issues/4831
* https://github.com/penumbra-zone/penumbra/issues/4849
---
 pages/pcli/_meta.json   |  5 +++--
 pages/pcli/migrating.md | 18 ++++++++++++++++++
 2 files changed, 21 insertions(+), 2 deletions(-)
 create mode 100644 pages/pcli/migrating.md

diff --git a/pages/pcli/_meta.json b/pages/pcli/_meta.json
index 7e975b6..e3bd242 100644
--- a/pages/pcli/_meta.json
+++ b/pages/pcli/_meta.json
@@ -3,5 +3,6 @@
   "wallet": "Generating a Wallet",
   "balance": "Viewing Balances",
   "transaction": "Sending Transactions",
-  "governance": "Using Governance"
-}
\ No newline at end of file
+  "governance": "Using Governance",
+  "migrating": "Migrating wallets"
+}
diff --git a/pages/pcli/migrating.md b/pages/pcli/migrating.md
new file mode 100644
index 0000000..9d4317c
--- /dev/null
+++ b/pages/pcli/migrating.md
@@ -0,0 +1,18 @@
+# Migrating wallets
+
+In order to transfer all assets in your wallet to a new wallet,
+first [generate a new wallet](wallet.md). After doing so, inspect the generated `config.toml`
+file for the `full_viewing_key` (FVK) field. You'll need this value to designate
+the new wallet, to which funds will be transferred.
+
+Then, run the migrate balance command from the first wallet, the one you want to empty of funds:
+
+```bash
+pcli migrate balance
+```
+
+That command will prompt for the FVK of the destination wallet.
+Paste in the FVK, and hit enter to build and submit the transaction.
+After sending, the source wallet should be completely empty, and the destination wallet
+should have all assets, minus any gas fees that were paid for the transaction.
+Assets will be preserved in their numbered accounts across source and destination wallets.