This post is intended for developers of Olympia Radix wallets, or developers who are interested in the lower level details of the wallet transition process. If you’re not one of these people, there’s no need to worry about any of this – the process for users will be simple and guided.
When the Radix Network upgrades from its Olympia version to Babylon, user accounts, tokens, and stakes will all automatically migrate forward in place. However, a number of things will change about the way wallet software must interact with the network. Accounts will use a new address format, and wallet software will have to understand a completely different transaction model, method of signing, and more. That means the old Radix Olympia Desktop Wallet will cease to function, and will be replaced by an all-new Radix Wallet iOS/Android mobile app for Babylon.
This post explains the technical specification for how the new Radix Wallet’s convenient “legacy account import” will work. This feature will allow users to transition control of their existing accounts from the Radix Olympia Desktop Wallet to the new Radix Wallet. Developers of other wallets for Olympia may also choose to use this specification to enable their users to easily transition their accounts to the new Radix Wallet.
The transition process is in two parts: an export of a list of accounts from the Radix Olympia Desktop Wallet (and potentially other wallets) by QR code, and an import of that QR code (or codes) into the Radix Wallet for Babylon.
Account Export QR Code Data Format
A final update for the Radix Olympia Desktop Wallet will be released on the day of the Babylon network update. This version will disable all transaction functionality (which will cease to function anyway), and will enable a new account export feature.
Users will be able to select the accounts they wish to transition to the new Radix Wallet, and the Olympia wallet will generate a QR code (or for ~50+ accounts, multiple QR codes) containing all the information the new Radix Wallet for Babylon needs to import those account names and addresses. This includes any accounts that were created with a Ledger hardware device in the Olympia wallet.
The user’s seed phrase is not included in the QR code. To ensure good security during the transition process, the seed phrase is not directly transferred; the user will be asked to manually input it in the Babylon wallet to confirm the import of accounts, and allow the Babylon wallet to begin signing transactions for those accounts. The same seed phrase will continue to back up those accounts (at least until the Babylon wallet implements multi-factor account control).
Developers of other existing wallets for Olympia may choose to generate their own QR code(s) in the same way that the Olympia wallet will. This will work just as smoothly for the user, as long as the exact same data format for the QR code data is adhered to.
The full export content is a list of accounts and associated information for each. Because a given QR code can only contain a limited amount of data, that export content may be broken up into multiple QR payloads (although it should be noted that for most users, a single QR can handle up to around 50 accounts at scannable size). Each QR payload consists of a header and a portion of the export content.
This means that an Olympia wallet can start by constructing the full export content, split it up into reasonably-sized chunks, precede each chunk with the correct header, and the Radix Wallet for Babylon can be expected to scan all QR code payloads, reconstruct the full export content and finish the import process.
It is recommended that the export content be broken up into chunks of a maximum of 1800 characters for each QR payload. This should enable use of version 38 QR codes (or smaller). A QR code error correction setting of “M” is suggested.
Header format
Each header is a few pieces of data, separated by a “^” separator, terminated by a “]”:
- payloadCount – Starting with 0, each additional QR payload must increment this by 1
- payloadIndex – The total number of QR payloads required to transfer the full export content
- mnemonicWordCount – The number of mnemonic words used in the accounts’ seed phrase (for accounts not secured by a Ledger hardware device)
For example, a header might look like:
0^3^12]
Content format
The content is a sequence of pieces of account info, with “^” separating parts of each account entry and “~” terminating each entry. Each account entry includes:
- accountTypeChar – A single character “S” for a software account and “H” for an account secured by a Ledger device
- pubKeyBase64 – The hex (not text) public key of the account, 33 bytes compressed, base64 encoded
- addressIndex – The HD path index for the account
- accountName – The account’s name
The accountName has a number of requirements:
- May be empty
- Maximum 30 characters
- Contains none of the reserved separators: ], ^, ~, }
- Contains no unicode
- “_” may be used safely to replace any reserved separators or unicode
- Is ended with the terminating “}”
So one account entry might look like:
S^AvZppDAk2Q/eaTUczFMCLC+GcI2bPEJpNkBzPFd4I12l^0^My Main Account}~
Export Data Payloads Example
Imagine a user with three accounts:
To illustrate how breaking up payloads works, let’s use a very low QR code size such that two QR payloads are needed to transmit the three accounts. The resulting payloads would be:
Payload index=0:
2^0^12]S^AvZppDAk2Q/eaTUczFMCLC+GcI2bPEJpNkBzPFd4I12l^0^With_forbidden_char_in_n
ame}~H^A/YzLtwqoPA1w8VNdKOs7HbZtZherdzamVuX1BF3Bdez^
Payload index=1:
2^1^12]1^}~H^A1STin2yF+LmEPU4mZarY6Bw+0QUZk350V4nWupv5JfG^2^Third|account_ok}
Note how “Account 1” (with it’s <NULL> account name) spans across the two payloads.
