ethmonic

Convert Ethereum addresses to memorable 4-word mnemonics for easy verification.

Why?

Ethereum addresses are 40 hex characters that are nearly impossible to verify at a glance. Ethmonic converts any address into 4 memorable words, making it easy to confirm you're sending to the right address.

0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 → "framework ivan masaccio weill"

The conversion is:

• Deterministic: Same address always produces the same 4 words
• One-way: You cannot recover the address from the mnemonic (this is for verification, not storage)
• Case-insensitive: Works with any address casing

Installation

npm install ethmonic

Usage

Encode an address to mnemonic

import { encode } from 'ethmonic';

const words = encode('0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045');
// Returns: ['framework', 'ivan', 'masaccio', 'weill']

console.log(words.join(' '));
// "framework ivan masaccio weill"

Verify an address matches a mnemonic

import { verify } from 'ethmonic';

// With array of words
verify('0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045', ['framework', 'ivan', 'masaccio', 'weill']); // true

// With space-separated string
verify('0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045', 'framework ivan masaccio weill'); // true

// Case-insensitive
verify('0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045', 'FRAMEWORK IVAN MASACCIO WEILL'); // true

API

encode(address: string): Mnemonic

Converts an Ethereum address to a 4-word mnemonic.

• address: Ethereum address with 0x prefix (required, any case)
• returns: Tuple of 4 lowercase words
• throws: Error if address format is invalid

verify(address: string, words: string[] | string): boolean

Checks if a mnemonic matches an address.

• address: Ethereum address to verify
• words: Array of 4 words, or space-separated string
• returns: true if the mnemonic matches, false otherwise

WORDLIST: string[]

The complete wordlist (65,536 unique words) used for encoding.

How It Works

1. The address is normalized to lowercase
2. The hex bytes are hashed with keccak256 (for uniform distribution)
3. The first 8 bytes of the hash are split into 4 × 16-bit indices
4. Each index maps to one of 65,536 unique words

This gives 64 bits of entropy (2^64 possible combinations), providing strong collision resistance for verification purposes.

Use Cases

• Wallet verification: Display a mnemonic alongside addresses in your wallet UI
• Transaction confirmation: Show the mnemonic on hardware wallet screens
• Phone verification: Read 4 words instead of 40 hex characters
• Address books: Store memorable names for frequently used addresses

Security Notes

• This is a verification tool, not a replacement for full address validation
• The mnemonic is derived from the address, not the other way around
• Always verify the full address when security is critical
• The 64-bit entropy provides strong protection against accidental collisions but is not suitable for cryptographic key derivation

License

MIT