Median Client-Side Key Generation

A React-compatible JavaScript/TypeScript library for generating Median blockchain wallets client-side in the browser.

Features

• ✅ Client-side generation: All key generation happens in the user's browser
• ✅ BIP39 compliant: 12/24 word mnemonic phrases
• ✅ BIP32/BIP44 derivation: Standard Cosmos SDK derivation paths
• ✅ secp256k1 elliptic curve: Industry-standard cryptography
• ✅ Bech32 addresses: Median blockchain address format (median1...)
• ✅ React compatible: Easy integration with React applications
• ✅ TypeScript support: Full type definitions included
• ✅ Zero dependencies: Minimal, secure dependencies

Installation

npm install median-client-keygen
# or
yarn add median-client-keygen

Quick Start

Generating a New Wallet

import { generateWallet, validateAddress } from 'median-client-keygen';

// Generate a new wallet (24 words by default)
const wallet = generateWallet({
  passphrase: 'optional-passphrase', // BIP39 passphrase (optional)
  addressCount: 3,                   // Generate multiple addresses
  hrp: 'median'                      // Human Readable Prefix (default: 'median')
});

console.log('Mnemonic:', wallet.mnemonic);
console.log('Primary address:', wallet.keyPair.address);
console.log('Private key:', wallet.keyPair.privateKey); // Handle with extreme care!

// Validate the generated address
const isValid = validateAddress(wallet.keyPair.address, 'median');
console.log('Address valid:', isValid);

Importing an Existing Wallet

import { importWallet, validateMnemonic } from 'median-client-keygen';

const mnemonic = 'your 12 or 24 word mnemonic phrase here';

// First, validate the mnemonic
if (!validateMnemonic(mnemonic)) {
  throw new Error('Invalid mnemonic phrase');
}

// Import the wallet
const wallet = importWallet(mnemonic, {
  passphrase: 'your-passphrase', // Optional, must match original
  addressCount: 1,
  hrp: 'median'
});

console.log('Recovered address:', wallet.keyPair.address);

React Component Example

import React, { useState } from 'react';
import { generateWallet, importWallet, validateMnemonic } from 'median-client-keygen';

function MedianWallet() {
  const [wallet, setWallet] = useState(null);
  const [mnemonic, setMnemonic] = useState('');

  const handleGenerate = () => {
    const newWallet = generateWallet();
    setWallet(newWallet);
    setMnemonic(newWallet.mnemonic);
  };

  const handleImport = () => {
    if (!validateMnemonic(mnemonic)) {
      alert('Invalid mnemonic phrase');
      return;
    }
    const importedWallet = importWallet(mnemonic);
    setWallet(importedWallet);
  };

  return (
    <div>
      <button onClick={handleGenerate}>Generate New Wallet</button>
      <textarea
        value={mnemonic}
        onChange={(e) => setMnemonic(e.target.value)}
        placeholder="Enter mnemonic to import"
      />
      <button onClick={handleImport}>Import Wallet</button>

      {wallet && (
        <div>
          <h3>Your Wallet</h3>
          <p>Address: {wallet.keyPair.address}</p>
          <p><small>Mnemonic: {wallet.mnemonic.substring(0, 20)}...</small></p>
        </div>
      )}
    </div>
  );
}

API Reference

Core Functions

generateWallet(options?: KeyGenerationOptions): Wallet

Generates a new wallet with a random mnemonic.

Options:

• strength?: 128 | 256 - Entropy strength (128 for 12 words, 256 for 24 words, default: 256)
• passphrase?: string - BIP39 passphrase (optional)
• derivationPath?: string - Derivation path template (default: m/44'/118'/0'/{index})
• addressCount?: number - Number of addresses to generate (default: 1)
• hrp?: string - Human Readable Prefix for addresses (default: 'median')
• startIndex?: number - Starting address index (default: 0)

importWallet(mnemonic: string, options?: KeyGenerationOptions): Wallet

Imports an existing wallet from a mnemonic phrase.

generateMnemonic(strength: number = 256): string

Generates a BIP39 mnemonic phrase.

validateMnemonic(mnemonic: string): boolean

Validates a BIP39 mnemonic phrase.

mnemonicToKeyPair(options: DerivationOptions): KeyPair

Derives a key pair directly from a mnemonic.

validateAddress(address: string, expectedHrp: string = 'median'): boolean

Validates a Median address.

Types

interface Wallet {
  mnemonic: string;                    // BIP39 mnemonic phrase
  keyPair: KeyPair;                    // Primary key pair
  derivedKeyPairs?: Record<number, KeyPair>; // Additional addresses
}

interface KeyPair {
  privateKey: string;  // Private key in hex format (64 chars)
  publicKey: string;   // Public key in hex format (66 chars, compressed)
  address: string;     // Median address (bech32 encoded)
}

interface KeyGenerationOptions {
  strength?: 128 | 256;
  passphrase?: string;
  derivationPath?: string;
  addressCount?: number;
  hrp?: string;
  startIndex?: number;
}

interface DerivationOptions {
  mnemonic: string;
  passphrase?: string;
  path?: string;  // Default: "m/44'/118'/0'/0/0"
  hrp?: string;   // Default: 'median'
}

Security Considerations

🔒 Private Key Security

• Never store private keys in plaintext
• Never transmit private keys over unsecured channels
• Consider using hardware wallets for large amounts

🔐 Mnemonic Phrase Security

• Store offline: Write down on paper, store in safe
• Never digital: Avoid screenshots, cloud storage, emails
• Multiple copies: Store in multiple secure locations
• Test recovery: Verify you can recover before depositing funds

🛡️ Browser Security

• HTTPS only: Only use on HTTPS websites
• Secure context: Requires secure browser context for crypto APIs
• Clear memory: Private keys remain in memory until page refresh

Derivation Paths

Median uses standard Cosmos SDK derivation:

m/44'/118'/0'/0/{index}

Where:

• 44': BIP44 purpose (cryptocurrency)
• 118': SLIP44 coin type for Cosmos
• 0': Account index
• 0: Change (0 = external addresses)
• {index}: Address index (0, 1, 2, ...)

Compatibility with Median Python SDK

This library is designed to be compatible with the Median Python SDK. Wallets generated with this library can be imported into the Python SDK using the same mnemonic and derivation path.

Verification Test

cd client-keygen
npm run test:compat

This runs compatibility tests against known test vectors from the Median SDK.

Development

Building from Source

git clone https://github.com/Median/sdk.git
cd sdk/client-keygen
npm install
npm run build

Running Tests

npm test
npm run test:compat

Project Structure

client-keygen/
├── src/
│   ├── index.ts          # Main exports
│   ├── types.ts          # TypeScript definitions
│   ├── keygen.ts         # Key generation logic
│   └── utils.ts          # Utility functions
├── examples/
│   └── WalletGenerator.tsx  # React component example
├── dist/                 # Built output
├── package.json
├── tsconfig.json
└── rollup.config.js

License

Apache 2.0 - See LICENSE file.

Support

• GitHub Issues: Median SDK Repository
• Documentation: Median Blockchain Docs

Acknowledgments

• Built on standards: BIP39, BIP32, BIP44, SLIP44
• Uses industry-standard cryptography: secp256k1, SHA256, RIPEMD160
• Compatible with Cosmos SDK ecosystem