@yaring/mcbf

Multi-Chain Blockchain Framework (MCBF)

MCBF is a universal library for working with various blockchain networks, providing a unified interface for creating and managing cryptocurrency wallets.

Key Features

• Support for multiple blockchain networks through an adapter system
• Unified interface for working with different networks
• Wallet generation and recovery from mnemonic phrases (BIP39, Cardano, Monero)
• Data encryption using AES-GCM
• Support for various key derivation protocols
• JSON Schema-based data validation
• Support for multiple address types per network
• New: Automatic detection and validation of mnemonic types

Installation

npm install @yaring/mcbf

Supported Networks and Protocols

Network	Type	Protocol	Derivation Paths
Bitcoin	UTXO	BIP84	m/84'/0'/0'/0/0
Ethereum	Account	BIP44	m/44'/60'/0'/0/0
Cardano	Account	Cardano	m/1852'/1815'/0'/0/0
Cosmos	Dual	BIP44	m/44'/118'/0'/0/0
Dogecoin	UTXO	BIP84	m/84'/3'/0'/0/0
Litecoin	UTXO	BIP84	m/84'/2'/0'/0/0
Monero	Account	CryptoNote	-
Polkadot	Account	SR25519	m/44'/354'/0'/0/0
Solana	Account	ED25519	m/44'/501'/0'/0/0
TON	Account	ED25519	m/44'/607'/0'/0/0
TRON	Account	BIP44	m/44'/195'/0'/0/0

Quick Start

import { MCBFManager } from '@yaring/mcbf';

// Initialize manager
const mcbf = new MCBFManager();

// Create new wallet
const wallet = await mcbf.generateBIP39Wallet({
  networks: ['bitcoin', 'ethereum', 'solana']
});

console.log(wallet.mnemonic); // 12/24 word mnemonic
console.log(wallet.networks.bitcoin.addresses.default); // bc1...
console.log(wallet.networks.ethereum.addresses.default); // 0x...
console.log(wallet.networks.solana.addresses.default); // Base58...

Detailed Usage

Creating an Encrypted Wallet

const mcbf = new MCBFManager({
  encryption: {
    keyLength: 256,
    iterations: 100000
  }
});

const wallet = await mcbf.generateBIP39Wallet({
  networks: ['bitcoin', 'ethereum']
});

const encrypted = await mcbf.encryptWalletData(wallet, 'strong-password');

Restoring from Mnemonic

const wallet = await mcbf.restoreFromMnemonic(
  'your twelve or twenty four word mnemonic phrase',
  {
    networks: ['bitcoin', 'ethereum']
  }
);

Restoring from Private Key

import { MCBFManager } from '@yaring/mcbf';

const mcbf = new MCBFManager();

// BIP39 private key (32 bytes)
const wallet1 = await mcbf.restoreFromPrivateKey('e9873d79c6d87dc0fb6a5778633389f4453213303da61f20bd67fc233aa33262');
// Will restore Bitcoin, Ethereum, and other BIP39 network wallets

// Cardano private key (64 bytes)
const wallet2 = await mcbf.restoreFromPrivateKey('b8f2bece9bdfe2b0282f5bad705562ac996efb6af96b648f4445ec44f47ad95c982fc7412f9ed8a949a1655ed34d0590e0e4c4c2d49387ad8cc2a3ad729bcb63');
// Will restore Cardano wallet only

// Monero private keys (spend key + view key)
const wallet3 = await mcbf.restoreFromPrivateKey({
  spend: 'a8f2bece9bdfe2b0282f5bad705562ac996efb6af96b648f4445ec44f47ad95c',
  view: '982fc7412f9ed8a949a1655ed34d0590e0e4c4c2d49387ad8cc2a3ad729bcb63'
});
// Will restore Monero wallet only

// The returned wallet object follows the same structure as generateBIP39Wallet
console.log(wallet1.networks.bitcoin.addresses.default);  // bc1...
console.log(wallet1.networks.ethereum.addresses.default); // 0x...

Validating Mnemonic and Private Key Types

import { WalletTypeValidator } from '@yaring/mcbf';

// Validate mnemonic and get its type
const mnemonicType = WalletTypeValidator.validateMnemonic('your mnemonic phrase');

if (mnemonicType.type === null) {
  console.error('Validation failed:', mnemonicType.error);
} else {
  console.log('Mnemonic type:', mnemonicType.type);
  console.log('Supported networks:', mnemonicType.networks);
}

// Successful output example:
// {
//   type: 'BIP39', // or 'CARDANO', or 'MONERO'
//   networks: ['bitcoin', 'litecoin', 'dogecoin', 'evm', ...] // supported networks for this type
// }

// Error output example:
// {
//   type: null,
//   error: 'Invalid mnemonic' // or specific error message
// }

Validating Private Keys

import { WalletTypeValidator } from '@yaring/mcbf';

// BIP39 private key (32 bytes = 64 hex chars)
const bip39Result = WalletTypeValidator.validatePrivateKey('e9873d79c6d87dc0fb6a5778633389f4453213303da61f20bd67fc233aa33262');
// Output:
// {
//   type: 'BIP39',
//   networks: ['bitcoin', 'litecoin', 'dogecoin', 'evm', 'cosmos', 'polkadot', 'solana', 'ton', 'tron']
// }

// Cardano private key (64 bytes = 128 hex chars)
const cardanoResult = WalletTypeValidator.validatePrivateKey('b8f2bece9bdfe2b0282f5bad705562ac996efb6af96b648f4445ec44f47ad95c982fc7412f9ed8a949a1655ed34d0590e0e4c4c2d49387ad8cc2a3ad729bcb63');
// Output:
// {
//   type: 'CARDANO',
//   networks: ['cardano']
// }

// Monero private keys (spend key + view key)
const moneroResult = WalletTypeValidator.validatePrivateKey('a8f2bece9bdfe2b0282f5bad705562ac996efb6af96b648f4445ec44f47ad95c, 982fc7412f9ed8a949a1655ed34d0590e0e4c4c2d49387ad8cc2a3ad729bcb63');
// Output:
// {
//   type: 'MONERO',
//   networks: ['monero'],
//   keys: {
//     spend: 'a8f2bece9bdfe2b0282f5bad705562ac996efb6af96b648f4445ec44f47ad95c',
//     view: '982fc7412f9ed8a949a1655ed34d0590e0e4c4c2d49387ad8cc2a3ad729bcb63'
//   }
// }

// Invalid key
const invalidResult = WalletTypeValidator.validatePrivateKey('invalid-key');
// Output:
// {
//   type: null,
//   error: 'Invalid private key format: must be hexadecimal'
// }

Supported Wallet Types

Type	Description	Supported Networks	Example
BIP39	Standard BIP39 mnemonic	Bitcoin, Ethereum, Litecoin, Dogecoin, Cosmos, Polkadot, Solana, TON, TRON	"abandon ability able about above..."
CARDANO	Cardano-specific mnemonic	Cardano	"ability above abandon able about..."
MONERO	Monero-specific mnemonic	Monero	"abbey ability about above..."

Working with Specific Networks

Bitcoin

import { BitcoinNetworkAdapter } from '@yaring/mcbf';

const keys = await BitcoinNetworkAdapter.deriveKeys(mnemonic);
console.log({
  bech32: keys.addresses.bech32,   // Native SegWit (bc1...)
  segwit: keys.addresses.segwit,   // SegWit (3...)
  legacy: keys.addresses.legacy    // Legacy (1...)
});

Ethereum

import { EVMNetworkAdapter } from '@yaring/mcbf';

const keys = await EVMNetworkAdapter.deriveKeys(mnemonic);
console.log({
  address: keys.address,          // 0x...
  privateKey: keys.privateKey     // 0x...
});

Cardano

import { CardanoNetworkAdapter } from '@yaring/mcbf';

const keys = await CardanoNetworkAdapter.deriveKeys(mnemonic);
console.log({
  base: keys.addresses.base,           // addr1...
  enterprise: keys.addresses.enterprise, // addr1...
  reward: keys.addresses.reward        // stake1...
});

Data Encryption

import { Encryption } from '@yaring/mcbf';

const encryption = new Encryption({
  keyLength: 256,
  iterations: 100000,
  algorithm: 'AES-GCM'
});

// Encryption
const encrypted = await encryption.encrypt(walletData, password);

// Decryption
const decrypted = await encryption.decrypt(encrypted, password);

Data Validation

import { Validator } from '@yaring/mcbf';

const validator = new Validator();

try {
  validator.validateData(walletData);
  console.log('Data is valid');
} catch (error) {
  console.error('Validation error:', error.message);
}

Wallet Data Structure

{
  format: {
    name: "MCBF",
    version: "1.0",
    timestamp: "2024-03-20T12:00:00Z"
  },
  wallet: {
    id: "uuid-v4",
    name: "My Wallet",
    creator: {
      name: "MCBF",
      version: "1.0.0"
    }
  },
  data: {
    bip39: {
      entropy: "hex-string",
      mnemonic: "12/24 words",
      networks: {
        bitcoin: {
          derivationPath: "m/84'/0'/0'/0/0",
          privateKey: "hex",
          publicKey: "hex",
          address: "bc1..."
        },
        // Other networks...
      }
    }
  }
}

Error Handling

The library uses an exception system with informative messages:

try {
  const wallet = await mcbf.generateBIP39Wallet();
} catch (error) {
  if (error.message.includes('Invalid mnemonic')) {
    console.error('Invalid mnemonic phrase');
  } else if (error.message.includes('Unsupported network')) {
    console.error('Unsupported network');
  } else {
    console.error('Unknown error:', error.message);
  }
}

Development

Requirements

• Node.js 16+
• npm 7+

Installing Dependencies

npm install

Building

npm run build

Testing

npm test

License

MIT

Support

If you have questions or issues, please create an issue in the project repository.

Working with Network Adapters Directly

Each network adapter now supports direct key generation from private keys:

import { BitcoinNetworkAdapter, EVMNetworkAdapter } from '@yaring/mcbf';

// Using Bitcoin adapter
const btcWallet = await BitcoinNetworkAdapter.fromPrivateKey('e9873d79c6d87dc0fb6a5778633389f4453213303da61f20bd67fc233aa33262');
console.log({
  privateKey: btcWallet.privateKey,
  publicKey: btcWallet.publicKey,
  mainnetAddress: btcWallet.addresses.mainnet.mainnetAddress,
  testnetAddress: btcWallet.addresses.testnet.testnetAddress
});

// Using EVM adapter
const evmWallet = await EVMNetworkAdapter.fromPrivateKey('e9873d79c6d87dc0fb6a5778633389f4453213303da61f20bd67fc233aa33262');
console.log({
  privateKey: evmWallet.privateKey,    // 0x...
  publicKey: evmWallet.publicKey,      // 0x...
  address: evmWallet.addresses.mainnet.mainnetAddress  // 0x...
});

// Using Cardano adapter with extended private key
const cardanoWallet = await CardanoNetworkAdapter.fromPrivateKey('b8f2bece9bdfe2b0282f5bad705562ac996efb6af96b648f4445ec44f47ad95c982fc7412f9ed8a949a1655ed34d0590e0e4c4c2d49387ad8cc2a3ad729bcb63');
console.log({
  base: cardanoWallet.addresses.mainnet.base,           // addr1...
  enterprise: cardanoWallet.addresses.mainnet.enterprise, // addr1...
  reward: cardanoWallet.addresses.mainnet.reward        // stake1...
});

// Using Monero adapter with both spend and view keys
const moneroWallet = await MoneroNetworkAdapter.fromPrivateKey({
  spend: 'a8f2bece9bdfe2b0282f5bad705562ac996efb6af96b648f4445ec44f47ad95c',
  view: '982fc7412f9ed8a949a1655ed34d0590e0e4c4c2d49387ad8cc2a3ad729bcb63'
});
console.log({
  address: moneroWallet.addresses.mainnet.mainnetAddress  // 4...
});