Skip to content
light theme Algorand Developer Portal dark theme Algorand Developer Portal Algorand Developer Portal

Master Key Export

← Back to KMD Client

Description

Section titled “Description”

This example demonstrates how to export the master derivation key (MDK) for wallet backup using the KMD exportMasterKey() method. Key concepts:

  • The master derivation key (MDK) is the root key used to deterministically generate all keys in the wallet
  • With the MDK, you can recreate a wallet and regenerate all derived keys
  • Imported keys CANNOT be recovered from the MDK
  • The MDK should be stored securely as it can regenerate all wallet keys

Prerequisites

Section titled “Prerequisites”
  • LocalNet running (via algokit localnet start)
  • Covered operations:
  • exportMasterKey() - Export the master derivation key from a wallet

Run This Example

Section titled “Run This Example”

From the repository root:

Terminal window
cd examples
npm run example kmd_client/07-master-key-export.ts

Code

Section titled “Code”

View source on GitHub

07-master-key-export.ts
/**
 * Example: Master Key Export
 *
 * This example demonstrates how to export the master derivation key (MDK)
 * for wallet backup using the KMD `exportMasterKey()` method.
 *
 * Key concepts:
 * - The master derivation key (MDK) is the root key used to deterministically
 *   generate all keys in the wallet
 * - With the MDK, you can recreate a wallet and regenerate all derived keys
 * - Imported keys CANNOT be recovered from the MDK
 * - The MDK should be stored securely as it can regenerate all wallet keys
 *
 * Prerequisites:
 * - LocalNet running (via `algokit localnet start`)
 *
 * Covered operations:
 * - exportMasterKey() - Export the master derivation key from a wallet
 */


import {
  cleanupTestWallet,
  createKmdClient,
  createTestWallet,
  printError,
  printHeader,
  printInfo,
  printStep,
  printSuccess,
} from '../shared/utils.js'


/**
 * Format a byte array for display, showing first and last few bytes for security
 */
function formatBytesForDisplay(bytes: Uint8Array, showFirst = 4, showLast = 4): string {
  const hex = Buffer.from(bytes).toString('hex')
  if (bytes.length <= showFirst + showLast) {
    return hex
  }
  const firstBytes = hex.slice(0, showFirst * 2)
  const lastBytes = hex.slice(-(showLast * 2))
  return `${firstBytes}...${lastBytes}`
}


async function main() {
  printHeader('KMD Master Key Export Example')


  const kmd = createKmdClient()
  let walletHandleToken = ''
  const walletPassword = 'test-password'


  try {
    // =========================================================================
    // Step 1: Create a Test Wallet
    // =========================================================================
    printStep(1, 'Creating a test wallet')


    const testWallet = await createTestWallet(kmd, walletPassword)
    walletHandleToken = testWallet.walletHandleToken


    printSuccess(`Test wallet created: ${testWallet.walletName}`)
    printInfo(`Wallet ID: ${testWallet.walletId}`)


    // =========================================================================
    // Step 2: Generate Several Keys in the Wallet
    // =========================================================================
    printStep(2, 'Generating several keys in the wallet')


    const generatedAddresses: string[] = []
    const numKeys = 3


    for (let i = 1; i <= numKeys; i++) {
      const result = await kmd.generateKey({ walletHandleToken })
      generatedAddresses.push(result.address.toString())
      printInfo(`Key ${i}: ${result.address}`)
    }


    printSuccess(`Generated ${numKeys} keys in the wallet`)
    printInfo('')
    printInfo('These keys are deterministically derived from the master derivation key.')
    printInfo('They can be regenerated by creating a new wallet with the same MDK.')


    // =========================================================================
    // Step 3: Export the Master Derivation Key
    // =========================================================================
    printStep(3, 'Exporting the master derivation key with exportMasterKey()')


    const exportResult = await kmd.exportMasterKey({
      walletHandleToken,
      walletPassword,
    })


    const masterKey = exportResult.masterDerivationKey


    printSuccess('Master derivation key exported successfully!')
    printInfo('')
    printInfo('ExportMasterKeyResponse fields:')
    printInfo(`  masterDerivationKey (${masterKey.length} bytes): ${formatBytesForDisplay(masterKey)}`)
    printInfo('')
    printInfo('Note: The wallet password is required to export the master key for security.')


    // =========================================================================
    // Step 4: Explain What the Master Key Is
    // =========================================================================
    printStep(4, 'Understanding the master derivation key')


    printInfo('')
    printInfo('What is the Master Derivation Key (MDK)?')
    printInfo('-'.repeat(40))
    printInfo('')
    printInfo('The MDK is the cryptographic root of your wallet. It is used to:')
    printInfo('')
    printInfo('  1. BACKUP/RECOVERY: Store this key to recover your wallet')
    printInfo('     - Create a new wallet with the MDK to restore it')
    printInfo('     - Call generateKey() the same number of times to recover keys')
    printInfo(`     - In this example, calling generateKey() ${numKeys} times would`)
    printInfo('       regenerate the exact same addresses')
    printInfo('')
    printInfo('  2. DETERMINISTIC DERIVATION: Keys are derived in sequence')
    printInfo('     - First generateKey() call always produces the same address')
    printInfo('     - Second call produces the same second address, etc.')
    printInfo('     - This sequence is reproducible with the same MDK')


    // =========================================================================
    // Step 5: Important Limitations
    // =========================================================================
    printStep(5, 'Important limitations - Imported keys')


    printInfo('')
    printInfo('IMPORTANT: Imported keys CANNOT be recovered from the MDK!')
    printInfo('-'.repeat(40))
    printInfo('')
    printInfo('The MDK only protects keys generated with generateKey().')
    printInfo('')
    printInfo('Keys imported with importKey():')
    printInfo('  - Are stored in the wallet database')
    printInfo('  - Can be used for transactions while the wallet exists')
    printInfo('  - CANNOT be regenerated from the MDK')
    printInfo('  - Must be backed up separately using exportKey()')
    printInfo('')
    printInfo('To fully backup a wallet with imported keys:')
    printInfo('  1. Export and store the MDK (for generated keys)')
    printInfo('  2. Export and store each imported key separately')
    printInfo('  3. Or backup the entire wallet database file')


    // =========================================================================
    // Step 6: Security Implications
    // =========================================================================
    printStep(6, 'Security implications')


    printInfo('')
    printInfo('⚠️  SECURITY WARNING: Handle the MDK with extreme care!')
    printInfo('-'.repeat(40))
    printInfo('')
    printInfo('Anyone with access to your MDK can:')
    printInfo('  - Recreate your entire wallet')
    printInfo('  - Generate all your derived keys')
    printInfo('  - Sign transactions and move your funds')
    printInfo('')
    printInfo('Best practices for MDK storage:')
    printInfo('  - Never store it in plain text on your computer')
    printInfo('  - Use hardware security modules (HSM) for production')
    printInfo('  - Consider splitting the key using Shamir Secret Sharing')
    printInfo('  - Store backups in secure, offline locations')
    printInfo('  - Never transmit the MDK over insecure channels')
    printInfo('')
    printInfo('The MDK in this example is for demonstration only.')
    printInfo('In production, implement proper key management practices.')


    // =========================================================================
    // Step 7: Verify Keys Can Be Listed
    // =========================================================================
    printStep(7, 'Verifying wallet state')


    const listResult = await kmd.listKeysInWallet({ walletHandleToken })


    printSuccess(`Wallet contains ${listResult.addresses.length} key(s)`)
    printInfo('')
    printInfo('Generated addresses (would be recoverable from MDK):')
    listResult.addresses.forEach((addr, i) => {
      printInfo(`  ${i + 1}. ${addr}`)
    })


    // =========================================================================
    // Cleanup
    // =========================================================================
    printStep(8, 'Cleaning up test wallet')


    await cleanupTestWallet(kmd, walletHandleToken)
    walletHandleToken = '' // Mark as cleaned up


    printSuccess('Test wallet handle released')


    // =========================================================================
    // Summary
    // =========================================================================
    printHeader('Summary')
    printInfo('This example demonstrated master key export in KMD:')
    printInfo('')
    printInfo('  exportMasterKey()')
    printInfo('    Parameters: walletHandleToken, walletPassword')
    printInfo(`    Returns:    masterDerivationKey (${masterKey.length}-byte Uint8Array)`)
    printInfo('')
    printInfo('Key takeaways:')
    printInfo('  - The MDK is the root key for deterministic key derivation')
    printInfo(`  - MDK is ${masterKey.length} bytes (256 bits) for ed25519`)
    printInfo('  - Wallet password is required to export the MDK')
    printInfo('  - Generated keys can be recovered with the MDK')
    printInfo('  - Imported keys CANNOT be recovered with the MDK')
    printInfo('  - The MDK must be stored securely - it controls all funds!')
    printInfo('')
    printInfo('Note: The test wallet remains in KMD (wallets cannot be deleted via API).')
  } catch (error) {
    printError(`Error: ${error instanceof Error ? error.message : String(error)}`)
    printInfo('')
    printInfo('Troubleshooting:')
    printInfo('  - Ensure LocalNet is running: algokit localnet start')
    printInfo('  - If LocalNet issues occur: algokit localnet reset')
    printInfo('  - Check that KMD is accessible on port 4002')


    // Cleanup on error
    if (walletHandleToken) {
      await cleanupTestWallet(kmd, walletHandleToken)
    }


    process.exit(1)
  }
}


main().catch((error) => {
  console.error('Fatal error:', error)
  process.exit(1)
})

Other examples in KMD Client

Section titled “Other examples in KMD Client”