BTCRecover tokenlists vs passwordlists

The difference that changes your search

A passwordlist contains complete guesses, one per line. A tokenlist describes pieces from which BTCRecover builds guesses. In a tokenlist, alternatives separated by whitespace on one line compete for the same choice; entries on different lines can be combined. Treating one format as the other changes the search, sometimes drastically. See the upstream passwordlist and tokenlist references.

Use complete guesses when you know complete guesses

River Stone!
River2022!

As a passwordlist, these are two complete candidates. The space in the first line is part of that password. Our literal-password exercise confirms those two results. Adding typo options is a separate decision: the input format alone does not imply typo expansion.

Use tokens when you remember components

+ ^River
+ 2021 2022
+ !$

Here all three lines are required, the middle line chooses one year, and the anchors fix the first and last pieces. The result is two candidates. Remove only the suffix line’s leading plus and the count becomes four: each year is tested with and without the exclamation mark. Remove the start/end anchors while keeping every line required and the count becomes twelve: two year choices times six orders.

These counts are measured for the exact fixtures in our laboratory. They are not a universal formula for tokenlists: duplicate outputs, optional lines, repeated tokens and positional rules can alter the result.

Required does not mean anchored

The leading + controls whether a line must contribute a token. A leading ^ or trailing $ controls position if a token is selected. An anchor alone does not make a line required. In the tested revision, attaching both beginning and ending anchors to the same token is rejected. For a single required token, use + River; no anchors are needed to keep a one-token candidate intact.

A practical review before a long run

1. Write down two candidates that must appear and two that should not.
2. Preview a small, invented equivalent with --listpass.
3. Check whitespace, required lines and anchors separately.
4. Make the actual private candidate file in your offline recovery environment.
5. Save the exact file and command with the search record.

Preview output can reveal real password hints. Public bug reports should reproduce the syntax with invented strings, as these exercises do.