Skip to content

BIP-39: say what separates two words - #2237

Open
fametrano wants to merge 1 commit into
bitcoin:masterfrom
fametrano:bip39_word_separator
Open

BIP-39: say what separates two words#2237
fametrano wants to merge 1 commit into
bitcoin:masterfrom
fametrano:bip39_word_separator

Conversation

@fametrano

@fametrano fametrano commented Aug 5, 2026

Copy link
Copy Markdown
Contributor

The BIP never says it. The rule exists — the Japanese wordlist page requires
the ideographic space U+3000, added in #130 — but it is not in the BIP text,
and the note there holds a caveat: ASCII and ideographic spaces are
equivalent "as long as your code never shows the user an ASCII space
separated phrase or tries to split the phrase input by the user".

The reference implementation splits the input, on U+0020, and so cannot read
back the Japanese sentences it writes: to_entropy raises on all 24
Japanese vectors of its own vectors.json. The fix of the reference
implementation is open there: trezor/python-mnemonic#145

This adds three sentences to "From mnemonic to seed": the separator, the
Japanese exception, and what it means for software that splits a sentence
before normalizing it. No test vector changes, and nothing that is correct
today becomes incorrect.

Found downstream in btclib: btclib-org/btclib#258.

🤖 Generated with Claude Code

The BIP never says it. The rule is on the wordlist page, which requires
the ideographic space for Japanese, and it is not quoted here; the note
there also holds a caveat that ASCII and ideographic spaces are the same
"as long as your code ... [does not try] to split the phrase input by
the user". The reference implementation does split it, on U+0020, and so
cannot read back the Japanese sentences it writes.

No test vector changes.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@murchandamus murchandamus added Proposed BIP modification PR by non-owner to update BIP content Pending acceptance This BIP modification requires sign-off by the champion of the BIP being modified labels Aug 5, 2026
@fametrano

Copy link
Copy Markdown
Contributor Author

If this lands and there is interest, I am happy to write the follow-up on the
other half of the question: what a reader should do with whitespace that is
not the separator — a leading or trailing space, the line break of a paper
backup wrapped over two lines, a doubled space from a copy-paste.

The BIP mandates NFKD and says nothing more, so implementations differ and the
failure mode is quiet: to_seed hashes whatever it is given, so a sentence
that a checksum check would reject still derives a seed — a valid-looking
wallet that is not the user's. Two answers look defensible: refuse anything
but the canonical single-space form, or collapse any run of whitespace after
NFKD. No test vector changes under either; btclib, which I maintain, collapses.

I left it out of this PR because it is new normative text rather than a
clarification of what the wordlist page already requires, and it should not
hold up the separator sentence. Glad to open it separately if the authors want
it, or to drop it if the view is that a Deployed BIP should not grow new
requirements.

@murchandamus

Copy link
Copy Markdown
Member

cc authors: @prusnak, @ebfull, @slush0, @voisine

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Pending acceptance This BIP modification requires sign-off by the champion of the BIP being modified Proposed BIP modification PR by non-owner to update BIP content

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants