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

``bash
npm install median-client-keygen


or

`typescript
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);
`

$3

`typescript
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);
`

$3

`tsx
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 (


#### 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.

$3

`typescript
interface Wallet {
mnemonic: string; // BIP39 mnemonic phrase
keyPair: KeyPair; // Primary key pair
derivedKeyPairs?: Record; // 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

$3

`
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.

$3

`bash
cd client-keygen
npm run test:compat
`

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

Development

$3

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

$3

`bash
npm test
npm run test:compat
`

$3

`
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