Seed from Mnemonic

Description

This example demonstrates how to use seedFromMnemonic() to convert a 25-word Algorand mnemonic back to its original 32-byte seed. This is the reverse operation of mnemonicFromSeed(). Key concepts:

seedFromMnemonic() reverses the mnemonic encoding process
The checksum word is verified to ensure mnemonic integrity
Round-trip conversion: seed -> mnemonic -> seed produces identical bytes

Prerequisites

No LocalNet required

Run This Example

From the repository root:

cd examples
npm run example algo25/02-seed-from-mnemonic.ts

Code

View source on GitHub

/**
 * Example: Seed from Mnemonic
 *
 * This example demonstrates how to use seedFromMnemonic() to convert a 25-word
 * Algorand mnemonic back to its original 32-byte seed. This is the reverse
 * operation of mnemonicFromSeed().
 *
 * Key concepts:
 * - seedFromMnemonic() reverses the mnemonic encoding process
 * - The checksum word is verified to ensure mnemonic integrity
 * - Round-trip conversion: seed -> mnemonic -> seed produces identical bytes
 *
 * Prerequisites:
 * - No LocalNet required
 */

import { mnemonicFromSeed, seedFromMnemonic } from '@algorandfoundation/algokit-utils/algo25';
import {
  formatHex,
  printError,
  printHeader,
  printInfo,
  printStep,
  printSuccess,
} from '../shared/utils.js';

/**
 * Compare two Uint8Arrays for equality
 */
function arrayEqual(a: Uint8Array, b: Uint8Array): boolean {
  if (a.length !== b.length) return false;
  for (let i = 0; i < a.length; i++) {
    if (a[i] !== b[i]) return false;
  }
  return true;
}

function main() {
  printHeader('Seed from Mnemonic Example');

  // Step 1: Generate a random 32-byte seed
  printStep(1, 'Generate a Random 32-byte Seed');

  const originalSeed = new Uint8Array(32);
  crypto.getRandomValues(originalSeed);

  printInfo(`Original seed length: ${originalSeed.length} bytes (256 bits)`);
  printInfo(`Original seed hex: ${formatHex(originalSeed)}`);

  // Step 2: Convert seed to mnemonic
  printStep(2, 'Convert Seed to 25-Word Mnemonic');

  const mnemonic = mnemonicFromSeed(originalSeed);
  const words = mnemonic.split(' ');

  printInfo(`Mnemonic has ${words.length} words`);
  printInfo('Mnemonic words:');
  // Display words in rows of 5 for readability
  for (let i = 0; i < words.length; i += 5) {
    const row = words.slice(i, i + 5);
    const numbered = row
      .map((w, j) => `${(i + j + 1).toString().padStart(2, ' ')}. ${w.padEnd(10)}`)
      .join(' ');
    printInfo(`  ${numbered}`);
  }

  // Step 3: Recover seed from mnemonic
  printStep(3, 'Recover Seed from Mnemonic using seedFromMnemonic()');

  const recoveredSeed = seedFromMnemonic(mnemonic);

  printInfo(`Recovered seed length: ${recoveredSeed.length} bytes`);
  printInfo(`Recovered seed hex: ${formatHex(recoveredSeed)}`);

  // Step 4: Compare original and recovered seeds
  printStep(4, 'Compare Original and Recovered Seeds');

  printInfo('Original seed:');
  printInfo(`  ${formatHex(originalSeed)}`);
  printInfo('Recovered seed:');
  printInfo(`  ${formatHex(recoveredSeed)}`);

  const seedsMatch = arrayEqual(originalSeed, recoveredSeed);
  printInfo(`Seeds are identical: ${seedsMatch ? 'Yes' : 'No'}`);

  if (seedsMatch) {
    printSuccess(
      'Round-trip verification passed: seedFromMnemonic(mnemonicFromSeed(seed)) === seed',
    );
  } else {
    printError('Round-trip verification failed!');
    return;
  }

  // Step 5: Byte-by-byte comparison
  printStep(5, 'Byte-by-Byte Verification');

  printInfo('Comparing first 8 bytes:');
  for (let i = 0; i < 8; i++) {
    const origByte = originalSeed[i].toString(16).padStart(2, '0');
    const recByte = recoveredSeed[i].toString(16).padStart(2, '0');
    const match = originalSeed[i] === recoveredSeed[i] ? '✓' : '✗';
    printInfo(`  Byte ${i}: original=0x${origByte}, recovered=0x${recByte} ${match}`);
  }
  printInfo('  ... (all 32 bytes verified)');

  // Step 6: Explain how seedFromMnemonic works
  printStep(6, 'How seedFromMnemonic() Works');

  printInfo('The recovery process:');
  printInfo('  1. Split the mnemonic into 25 words');
  printInfo('  2. Separate the first 24 words (data) from the 25th word (checksum)');
  printInfo('  3. Look up each data word in the BIP39 wordlist to get its 11-bit index');
  printInfo('  4. Combine the 24 × 11 = 264 bits back into bytes');
  printInfo('  5. Remove the last byte (8 padding bits) to get the 32-byte seed');
  printInfo('  6. Recompute the checksum from the recovered seed');
  printInfo('  7. Verify the computed checksum matches the 25th word');
  printInfo('  8. Return the 32-byte seed if checksum is valid');

  // Step 7: Demonstrate checksum validation
  printStep(7, 'Checksum Validation Protects Against Errors');

  printInfo(`Checksum word (25th word): "${words[24]}"`);
  printInfo('The checksum is computed from SHA-512/256 hash of the seed.');
  printInfo('If any word is changed, the checksum will not match.');

  // Create an invalid mnemonic by changing one word
  const tamperedWords = [...words];
  tamperedWords[0] = tamperedWords[0] === 'abandon' ? 'about' : 'abandon';
  const tamperedMnemonic = tamperedWords.join(' ');

  printInfo('');
  printInfo('Attempting to decode a tampered mnemonic...');
  printInfo(`  Changed word 1 from "${words[0]}" to "${tamperedWords[0]}"`);

  try {
    seedFromMnemonic(tamperedMnemonic);
    printError('Unexpectedly succeeded with tampered mnemonic!');
  } catch (error) {
    printSuccess(`Checksum validation caught the error: "${(error as Error).message}"`);
  }

  // Step 8: Summary
  printStep(8, 'Summary');

  printInfo('seedFromMnemonic() converts a 25-word mnemonic back to a 32-byte seed:');
  printInfo('  - Input: Space-separated string of 25 words');
  printInfo('  - Output: 32-byte Uint8Array (the original seed)');
  printInfo('  - Validates the checksum to ensure integrity');
  printInfo('  - Throws an error if:');
  printInfo('    - Any word is not in the BIP39 wordlist');
  printInfo('    - The checksum word does not match');
  printInfo('  - Enables round-trip: seed → mnemonic → seed');
  printInfo('  - Use case: Recover a seed from a backed-up mnemonic phrase');

  printSuccess('Seed from Mnemonic example completed successfully!');
}

main();

Seed from Mnemonic

Description

Prerequisites

Run This Example

Code

Other examples in Mnemonic Utilities