Software Engineering

The Benefits of Formosa Crypto Wallet Management

Cryptocurrency wallet management relies on a cryptographic recovery key—a secret word or expression with which a user protects and recovers their wallet. The BIP39 recovery key implementation supports keyword options that are far easier to recall than the random alphanumeric string keys of yesteryear. For this reason, BIP39 is credited for profoundly and positively impacting the crypto user experience. But memorizing a BIP39 recovery key is still no easy feat.

Enter Formosa, a powerful open-source project that generates recovery keys intended to be easier to remember. Formosa is compatible with BIP39, improves security, and features a selection of themes for users to choose from. Users can move from theme to theme with no risk to their existing keys.

To better acquaint you with Formosa, we will cover the basics of crypto wallet management with a concrete recovery phrase example. We will then dive deeper into a Python tutorial that shows how to leverage Formosa in security projects.

Note: Do not use our example Formosa keys or seeds in any crypto wallet as their publication here compromises their secrecy.

Crypto Wallet Management

Crypto wallet management refers to a wallet’s creation, recovery, and general function of receiving and exchanging coins. These high-level use cases depend on the associated seed that is created when the wallet is instantiated.

Seed Structuring, Security, and Recovery: The BIP39 Perspective

For a crypto wallet to function as intended, a unique and private seed is required. The seed should be kept secret and never shared. Such a seed is the basis for creating private-public key pairs, which are used for signing and verifying transactions.

Each private-public key pair generates a single address to be used in inter-wallet transactions. An address is the “owner” of currency, and is used to anonymously represent ownership of currency amounts on the blockchain. For the sake of security and anonymity, it is a good practice to never reuse an address from your crypto wallet.

Any crypto wallet can generate or recover private-public key pairs and associated addresses from any seed. BIP39-compatible wallets provide a mechanism with which to enter our recovery word list and instantiate our associated keys and addresses on that platform or device.

The beauty of this cryptocurrency wallet system is that, should a user lose access to their crypto wallet, they can simply enter the given seed or its recovery phrase into any BIP39-implemented wallet, where they would regain access to their currency, linking that wallet to that seed’s every transaction.

So how do these seeds function from a technical perspective? A seed’s strength grows exponentially with the number of bits it contains—generally either 128 bits or 256 bits.

BIP39 pulls from a list of 2,048 words. Because 2,048 = 2¹¹, making a one-to-one mapping of all 2,048 BIP39 words to all possible 11-bit sequences is simple enough to do: We use binary notation (hence the otherwise arbitrary choice of 2,048) to assign to each word the bit sequence that represents its position in the BIP39 word list.

Since each word takes 11 bits, we would use 12 recovery words in order to generate a 128-bit seed. Astute readers will notice that a 12-word sequence yields 132 bits—four more bits than is required to reach the 128-bit security standard. Those four are checksum bits, used to check for data errors; they provide a layer of protection for when these words are typed either by a user from memory or through transcription.

Restated mathematically: 12 words * 11 bits per word = 132 total bits, 128 of which generate the seed. 132-128 = 4 remaining checksum bits. In the event of a transcription error, a wallet equipped with a BIP39 input interface and using 128-bit seeds has a: 1/2⁴ or 6.25% chance of failing to detect the error.

In comparison, to generate a 256-bit seed, BIP39 pulls 24 words, yielding eight such checksum bits. Restated mathematically: 24 words * 11 bits per word = 264 total bits, 256 of which generate the seed. 264-256 = 8 remaining checksum bits. And in the event of a transcription error, a wallet equipped with a BIP39 input interface and 256-bit seeds has a 1/2⁸ or ≅ 0.4% chance of failing to detect the error.

An additional relevant property of BIP39 is that the first four characters in each word of its English word list are unique. This allows for efficient auto-complete interfaces, as well as a BIP39 password format in which the first four characters of all words are concatenated. If a seed word is a mere three letters (the minimum word length), a hyphen is appended as its fourth character in order to make the presence of three-letter words inconspicuous. In such a case, we would have a consistent ratio of 11/4 = 2.75 bits of randomness per digit, if checksum bits are excluded, or (132-4)/(4*12) = 128/48 = 8/3 = 2.67 bits per digit if checksum bits are included.

Recovery Sentences Are Better: The Formosa Perspective

Formosa provides everything that BIP39 does—and more. Like BIP39, a Formosa wallet may be used for all types of cryptocurrencies, such as Bitcoin. In terms of cryptographic strength, Formosa offers the same checksum bit ratio and password strength densities as BIP39 in the case of either the presence or absence of checksum bits.

But Formosa outclasses BIP39 by codifying its secret random information into sentences that are easier for us to remember than the standard and disparate BIP39 word list.

Another useful Formosa feature is its theme capability. Offering an impressive and growing collection of themes (e.g., Fairy Tale, Tourism), Formosa empowers us to source phrases that are associated with the theme of our choosing, making such phrases cohesive and memorable. Phrases may be converted between Formosa themes without compromising security.

We can do round-trip conversions between Formosa and BIP39 seeds—all without a loss of security. A common reason we might wish to convert from BIP39 to Formosa is to gain access to more memorable recovery phrase options while also retaining our existing crypto account addresses. From a human perspective, there may be no use case for conversion from Formosa to BIP39, but we do need our interface to perform such conversions each time we enter our Formosa recovery phrases and access our existing BIP39 crypto account addresses.

A Detailed Recovery Phrase Generation Example

The following step-by-step example demonstrates how to generate a BIP39 recovery phrase and its corresponding Formosa recovery phrase, given a specific seed. As a reminder, you should avoid using any of our example keys or seeds in a crypto wallet or other applications since they are published and, therefore, are not private.

Let’s pick a 16-byte hexadecimal seed (i.e., a seed consisting of 16*8 = 128 bits), 0XE41FEEEEE282BC5411CE97DF78B3660E, as our starting point. This is equivalent to this binary 128-bit representation, plus its four checksum bits: 11100100000111111110111011101110111000101000001010111100010101000001000111001110100101111101111101111000101100110110011000001110 0100.

BIP39 splits this 132-bit result into 11-bit random words. Formosa, on the other hand, splits the binary 132-bit string into four 33-bit strings (illustrated by the four rows in the following table). Formosa then splits each 33-bit array into a fixed pattern of five- or six-bit chunks used to form phrases:


Formosa (Medieval Fantasy Theme)

3 x 11-bit Chunks:
Random Word

5-bit Chunk:

6-bit Chunk:

6-bit Chunk:

5-bit Chunk:

6-bit Chunk:
Wild Card

5-bit Chunk:

11100100000: tomato
11111111011: youth
10111011101: roof
11100: unveil 100000: king 111111: wine 11011: sweet 101110: queen 11101:
11000101000: shallow
00101011110: cloth
00101010000: claw
11000: swing 101000: ogre 001010: club 11110: wooden 001010: cyclops 10000: mountain
01000111001: elbow
11010010111: spray
11011111011: term
01000: create 111001: summoner 110100: spellbook 10111: secret 110111: spirit 11011: temple
11000101100: sheriff
11011001100: sunset
00011100100: broken
11000: swing 101100: pirate 110110: tankard 01100: fizzy 000111: buccaneer 00100: brewery

The association that exists between the words that comprise a Formosa recovery key phrase provides a story-centric alternative to a BIP39 phrase, making for more memorable outputs:

BIP39 Final Output

Formosa Final Output

tomato youth roof

king unveil sweet wine queen throne_room

shallow cloth claw

ogre swing wooden club cyclops mountain

elbow spray term

summoner create secret spellbook spirit temple

sheriff sunset broken

pirate swing fizzy tankard buccaneer brewery

Consider the following diagram that shows the dependencies that lead to a Formosa recovery key:

The dependencies that lead to a Formosa recovery key.
  1. The first bit chunk specifies a verb: It is interpreted as a number that corresponds to an entry in a list in the Formosa theme’s JSON file.
  2. The second chunk specifies a subject: It is interpreted as a number that corresponds to an entry in a list provided by the previously defined verb.
  3. The third chunk specifies an object: It is interpreted as a number that corresponds to an entry in a list provided by the previously defined subject.
  4. The fourth chunk specifies an adjective: It is interpreted as a number that corresponds to an entry in a list provided by the previously defined object.
  5. The fifth chunk specifies a wild card: It is interpreted as a number that corresponds to an entry in a list provided by the previously defined subject.
  6. The sixth chunk specifies a place: It is interpreted as a number that corresponds to an entry in a list provided by the previously defined wild card.

Using the example of our first 33-bit string, this first chunk indexes the verb “unveil,” which is associated with 64 possible subjects. The second chunk indexes the subject “king,” which is associated with 64 possible objects and 64 possible wild cards. The third chunk indexes the word “wine,” which is associated with 32 possible adjectives, and chooses the word “sweet,” which is not associated with an additional list. The fifth chunk indexes the word “queen,” which is associated with 32 possible places, and the sixth chunk indexes the two-word expression “throne_room.”

In this case we end up with the sequence: king unveil sweet wine queen throne_room. To aid in retention of the mnemonic, a user can invoke grammar and auxiliary parts of speech: “[The] king unveil[s the] sweet wine [to the] queen [in the] throne_room” or “[The] king unveil[s the] sweet wine [at the] queen[’s] throne_room” is an example phrase for our sequence. Our end result is a memorable, visual scene.

Python and Formosa: Crypto Wallet Code

We have covered the basics of cryptographic wallet security and use, and shared an example of converting an array of random bits into a recovery phrase. Now let’s use Formosa in a simple Python project in which we will create a seed and then convert it between BIP39 and Formosa.

To begin, clone the project, specifying Formosa as the project folder name. Next, run the following script in Formosa’s parent directory to import our library and create a standard BIP39 mnemonic:

# Import library into python project via:
from formosa.src.mnemonic.mnemonic import Mnemonic

theme = "BIP39"
mnemo = Mnemonic(theme)

Since the mnemo.generate method is designed to draw random bits, output will vary if you run the script more than once. Now we’ll generate a BIP39 word list having a strength (quantity of bits) that is a multiple of 32 and is between 32 and 256:

words = mnemo.generate(strength=128)
# Output: tomato youth roof shallow cloth claw elbow spray term sheriff sunset broken

Given the generated word list, we can calculate the original input bits of our BIP39-formatted phrase, formatted as a hexadecimal string:

entropy = mnemo.to_entropy(words)
# Output: E41FEEEEE282BC5411CE97DF78B3660E

It is also possible to convert one mnemonic theme to another given the word list and both theme names. Let’s convert our BIP39 phrase to a Formosa phrase in the medieval fantasy theme:

new_words = mnemo.convert_theme(words, "medieval_fantasy", "BIP39")
# We instantiate a new Mnemonic object with the theme "medieval_fantasy", and then use it to format output.

# Output:
# password            =   kiunswwiquthogswwoclcymosucrsespsptepiswfitabubr
# formosa_sentences =   king unveil sweet wine queen throne_room
#                       ogre swing wooden club cyclops mountain
#                       summoner create secret spellbook spirit temple
#                       pirate swing fizzy tankard buccaneer brewery

Using the same method, we can also convert back to the original BIP39 theme:

original_words = mnemo.convert_theme(new_words, "BIP39", "medieval_fantasy")

In other words, using Formosa, anyone with a BIP39 passphrase can generate a themed semantic passphrase. Our succinct code blocks show how easy it is to use Formosa.

Formosa: An Upgrade to Your Cryptocurrency Wallet

BIP39 wallets abound in the crypto space, and integrate seamlessly with Formosa recovery phrases to improve the cryptocurrency user experience. The many cryptocurrency users who already have a recovery word list and corresponding addresses may keep and enhance their current addresses by adopting Formosa. Formosa is a significant step forward in seamlessly improving the human machine interface for cryptocurrency users.

The editorial team of the Toptal Engineering Blog extends its gratitude to Edson Cilos Vargas Júnior for reviewing the code samples and other technical content presented in this article.