BIP-039

The functions in this section implement support for the BIP-39 standard, which defines the process of converting entropy into a human-readable mnemonic phrase and vice versa. These mnemonics are widely used in cryptocurrency wallets for secure key generation and backup.

Currently, the implementation only supports the English BIP-39 wordlist. This limitation is intentional to simplify the library and focus on the most widely used configuration. Future versions of the library may include support for additional languages.

cardano_error_t cardano_bip39_entropy_to_mnemonic_words(const byte_t *entropy, size_t entropy_size, const char **words, size_t *word_count)

Converts entropy into a BIP-39 mnemonic word sequence.

This function takes entropy (a binary sequence) and converts it into a corresponding BIP-39 mnemonic sequence of words. The mnemonic words are pointers to a static, preloaded wordlist and do not require dynamic memory management. The caller must not attempt to free the returned pointers.

byte_t entropy[32] = { 256 bits of entropy  };
char* words[24] = { 0 };
size_t word_count = 0U;

cardano_error_t result = cardano_bip39_entropy_to_mnemonic_words(entropy, sizeof(entropy), words, &word_count);

if (result == CARDANO_SUCCESS)
{
  printf("Mnemonic words:\n");

  for (size_t i = 0; i < word_count; ++i)
  {
    printf("%s ", words[i]);
  }

  printf("\n");
}
else
{
   printf("Failed to create mnemonic words: %s\n", cardano_error_to_string(result));
}

Note

  • This function only supports the English BIP-39 wordlist.

  • The function does not allocate memory for the words; it simply assigns pointers to statically allocated strings from the preloaded English wordlist.

  • The caller must not free the pointers in the words array as they point to static memory.

Parameters:
const byte_t *entropy

[in] Pointer to the entropy buffer. Must not be NULL.

size_t entropy_size

[in] Size of the entropy in bytes. Supported sizes are 16, 20, 24, 28, or 32 bytes.

const char **words

[out] Array of pointers to char* where the mnemonic words will be stored. The caller must provide an array of size 24 to hold the maximum possible words. Each element in the array will point to a statically allocated string.

size_t *word_count

[out] Pointer to a size_t where the number of words in the mnemonic will be stored. The number of words depends on the entropy size:

  • 16 bytes (128 bits) → 12 words

  • 20 bytes (160 bits) → 15 words

  • 24 bytes (192 bits) → 18 words

  • 28 bytes (224 bits) → 21 words

  • 32 bytes (256 bits) → 24 words

Returns:

On success, returns CARDANO_SUCCESS. On failure, returns an error code indicating the reason for failure.

cardano_error_t cardano_bip39_mnemonic_words_to_entropy(const char **words, size_t word_count, byte_t *entropy, size_t entropy_buf_size, size_t *entropy_size)

Converts a BIP-39 mnemonic word sequence back into entropy.

This function takes a mnemonic sequence of BIP-39 words and converts it back into the corresponding binary entropy. The provided mnemonic words must belong to the English BIP-39 wordlist. The resulting entropy will be written to the provided buffer.

const char* words[12] = {
  "abandon", "abandon", "abandon", "abandon", "abandon", "abandon",
  "abandon", "abandon", "abandon", "abandon", "abandon", "about"
};
uint8_t entropy[32] = { 0 };
size_t entropy_size = 0U;

cardano_error_t result = cardano_bip39_mnemonic_words_to_entropy(
    words,
    12,
    entropy,
    sizeof(entropy),  // Provide the size of the buffer
    &entropy_size     // Output parameter for the actual entropy size
);

if (result == CARDANO_SUCCESS)
{
  printf("Entropy (size: %zu bytes): ", entropy_size);

  for (size_t i = 0; i < entropy_size; ++i)
  {
    printf("%02x", entropy[i]);
  }

  printf("\n");
}
else
{
  printf("Failed to convert mnemonic words to entropy: %s\n", cardano_error_to_string(result));
}

Note

  • This function only supports the English BIP-39 wordlist.

  • The provided mnemonic words must be valid and match the BIP-39 specification.

  • The caller must ensure the entropy buffer is large enough to accommodate the resulting entropy.

Parameters:
const char **words

[in] Array of pointers to the mnemonic words. Each word must be a valid BIP-39 English word. Must not be NULL.

size_t word_count

[in] Number of words in the mnemonic sequence. Supported values are:

  • 12 words (128-bit entropy)

  • 15 words (160-bit entropy)

  • 18 words (192-bit entropy)

  • 21 words (224-bit entropy)

  • 24 words (256-bit entropy)

byte_t *entropy

[out] Pointer to the buffer where the resulting entropy will be stored. Must not be NULL.

size_t entropy_buf_size

[in] Size of the entropy buffer provided (in bytes). Must be at least the size of the expected entropy corresponding to the word count (16–32 bytes).

size_t *entropy_size

[out] Pointer to a size_t where the actual size of the resulting entropy (in bytes) will be stored. Must not be NULL.

Returns:

On success, returns CARDANO_SUCCESS. On failure, returns an error code indicating the reason for failure.