Export quantus-cli wallet files #8

New Issue

grenade · 2026-09-15T06:54:07Z

grenade commented

2026-09-15 06:54:07 +00:00

The counterpart to #7. Filed because the assumption that blocked it turns out to be false.

The question

have i understood correctly that we couldn't export cli format anyway since we won't store the mnemonic?

No — we can. The CLI's own format has a null-mnemonic variant, it produces those itself, and it accepts one written by something else.

Evidence

The CLI writes "mnemonic": null for raw-seed wallets. crystal_alice, created by quantus developer create-test-wallets, has exactly that alongside "derivation_path": "m/" — and is a fully functional CLI wallet.

So a wallet with no mnemonic is not a degraded artifact the CLI tolerates; it is one of its normal shapes.

Confirmed empirically rather than inferred. A CLI-format wallet was constructed from key material alone — mnemonic: null, Argon2id + AES-256-GCM, container version 2 — dropped into ~/.quantus/wallets/, and:

quantus wallet list listed it, with the right address, scheme and human checkphrase
quantus wallet view showed it
quantus wallet export --format mnemonic failed with "Mnemonic phrase is not available for this wallet"

That last one is the proof. Reaching that error requires the CLI to have derived the Argon2 key, opened the AES-GCM box, parsed the payload JSON and inspected a field inside it. It is a correct answer about our file, not a rejection of it.

As a positive control, the same wallet written with the dev phrase in it round-tripped: export --format mnemonic returned the phrase verbatim. Both probes were removed afterwards.

What a null-mnemonic export costs the user

Nothing about spending. It costs exactly one thing: quantus wallet export --format mnemonic on that wallet will say the phrase is unavailable, and the CLI cannot derive further accounts from it.

That is the honest consequence of the extension not storing a phrase it was shown once — and it is the same position a user is in with a raw-seed CLI wallet today.

Why do it

#7 lets a user bring a CLI wallet in. Without this, that is a one-way door, and the extension's own backup is readable only by polkadot-js-format tooling (quantus/extension#8). Export closes the loop and removes the "your backup only works in the thing that made it" problem.

Scope

Serialise { name, keypair: { public_key, private_key, scheme }, mnemonic: null, derivation_path, metadata }
Argon2id with the parameters we choose, written into argon2_params as a PHC string so a future CLI reads them rather than assumes ours
AES-256-GCM, fresh 16-byte salt and 12-byte nonce per export
encryption_version: 2, empty kyber_*
address in the outer container, from the account id
derivation_path where known; "m/" for a raw-seed account, matching what the CLI writes

Mark it in metadata as exported by the extension. A CLI maintainer looking at a bug report should be able to tell where the file came from.

Acceptance

an exported wallet appears in quantus wallet list with the correct address and scheme
quantus wallet view shows it
the CLI can spend from it against a node — the one thing the probes above could not check offline
export --format mnemonic says the phrase is unavailable, rather than failing obscurely
both schemes
a password-protected export opens with that password in the CLI
round-trips back through #7

The counterpart to #7. Filed because the assumption that blocked it turns out to be false. ## The question > have i understood correctly that we couldn't export cli format anyway since we won't store the mnemonic? **No — we can.** The CLI's own format has a null-mnemonic variant, it produces those itself, and it accepts one written by something else. ## Evidence The CLI writes `"mnemonic": null` for raw-seed wallets. `crystal_alice`, created by `quantus developer create-test-wallets`, has exactly that alongside `"derivation_path": "m/"` — and is a fully functional CLI wallet. So a wallet with no mnemonic is not a degraded artifact the CLI tolerates; it is one of its normal shapes. Confirmed empirically rather than inferred. A CLI-format wallet was constructed from key material alone — `mnemonic: null`, Argon2id + AES-256-GCM, container version 2 — dropped into `~/.quantus/wallets/`, and: - `quantus wallet list` listed it, with the right address, scheme and human checkphrase - `quantus wallet view` showed it - `quantus wallet export --format mnemonic` failed with **"Mnemonic phrase is not available for this wallet"** That last one is the proof. Reaching that error requires the CLI to have derived the Argon2 key, opened the AES-GCM box, parsed the payload JSON and inspected a field inside it. It is a *correct* answer about our file, not a rejection of it. As a positive control, the same wallet written *with* the dev phrase in it round-tripped: `export --format mnemonic` returned the phrase verbatim. Both probes were removed afterwards. ## What a null-mnemonic export costs the user Nothing about spending. It costs exactly one thing: `quantus wallet export --format mnemonic` on that wallet will say the phrase is unavailable, and the CLI cannot derive further accounts from it. That is the honest consequence of the extension not storing a phrase it was shown once — and it is the same position a user is in with a raw-seed CLI wallet today. ## Why do it #7 lets a user bring a CLI wallet in. Without this, that is a one-way door, and the extension's own backup is readable only by polkadot-js-format tooling (quantus/extension#8). Export closes the loop and removes the "your backup only works in the thing that made it" problem. ## Scope - Serialise `{ name, keypair: { public_key, private_key, scheme }, mnemonic: null, derivation_path, metadata }` - Argon2id with the parameters we choose, written into `argon2_params` as a PHC string so a future CLI reads them rather than assumes ours - AES-256-GCM, fresh 16-byte salt and 12-byte nonce per export - `encryption_version: 2`, empty `kyber_*` - `address` in the outer container, from the account id - `derivation_path` where known; `"m/"` for a raw-seed account, matching what the CLI writes Mark it in `metadata` as exported by the extension. A CLI maintainer looking at a bug report should be able to tell where the file came from. ## Acceptance - [ ] an exported wallet appears in `quantus wallet list` with the correct address and scheme - [ ] `quantus wallet view` shows it - [ ] the CLI can spend from it against a node — the one thing the probes above could not check offline - [ ] `export --format mnemonic` says the phrase is unavailable, rather than failing obscurely - [ ] both schemes - [ ] a password-protected export opens with that password in the CLI - [ ] round-trips back through #7

grenade referenced this issue from a commit

2026-09-15 07:33:25 +00:00

feat(util-crypto): export quantus-cli wallet files

Sign in to join this conversation.

Branches Tags

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: quantus/common#8