bip32.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## BIP 32 Python Implementation\n",
    "\n",
    "**BIP 32** describes the generation of Hierarchical Deterministic (HD) wallets.\n",
    "\n",
    "Comprehensive step explanations can be found in the accompanying blog post: [Ethereum 201: HD Wallets](https://medium.com/@wolovim/ethereum-201-hd-wallets-11d0c93c87f7).\n",
    "\n",
    "_Disclaimer: this code is for educational purposes and not optimized for a production environment._"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Start with a seed\n",
    "BIP 32 picks up where BIP 39 left off - with a 512-bit seed:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "seed = 'fffcf9f6f3f0edeae7e4e1dedbd8d5d2cfccc9c6c3c0bdbab7b4b1aeaba8a5a29f9c999693908d8a8784817e7b7875726f6c696663605d5a5754514e4b484542'"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Derive the master private key and chain code"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "master private key (hex): 0x4b03d6fc340455b363f51020ad3ecca4f0850280cf436c70c727923f6db46c3e\n",
      "master chain code (bytes): b'`I\\x9f\\x80\\x1b\\x89m\\x83\\x17\\x9aCt\\xae\\xb7\\x82*\\xae\\xac\\xea\\xa0\\xdb\\x1f\\x85\\xee>\\x90LM\\xef\\xbd\\x96\\x89'\n"
     ]
    }
   ],
   "source": [
    "import binascii\n",
    "import hmac\n",
    "import hashlib\n",
    "\n",
    "# the HMAC-SHA512 `key` and `data` must be bytes:\n",
    "seed_bytes = binascii.unhexlify(seed)\n",
    "\n",
    "I = hmac.new(b'Bitcoin seed', seed_bytes, hashlib.sha512).digest()\n",
    "L, R = I[:32], I[32:]\n",
    "\n",
    "master_private_key = int.from_bytes(L, 'big')\n",
    "master_chain_code = R\n",
    "\n",
    "print(f'master private key (hex): {hex(master_private_key)}')\n",
    "print(f'master chain code (bytes): {master_chain_code}')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Derive the root key (extended private key)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "root key: xprv9s21ZrQH143K31xYSDQpPDxsXRTUcvj2iNHm5NUtrGiGG5e2DtALGdso3pGz6ssrdK4PFmM8NSpSBHNqPqm55Qn3LqFtT2emdEXVYsCzC2U\n"
     ]
    }
   ],
   "source": [
    "import base58\n",
    "\n",
    "VERSION_BYTES = {\n",
    "    'mainnet_public': binascii.unhexlify('0488b21e'),\n",
    "    'mainnet_private': binascii.unhexlify('0488ade4'),\n",
    "    'testnet_public': binascii.unhexlify('043587cf'),\n",
    "    'testnet_private': binascii.unhexlify('04358394'),\n",
    "}\n",
    "\n",
    "version_bytes = VERSION_BYTES['mainnet_private']\n",
    "depth_byte = b'\\x00'\n",
    "parent_fingerprint = b'\\x00' * 4\n",
    "child_number_bytes = b'\\x00' * 4\n",
    "key_bytes = b'\\x00' + L\n",
    "\n",
    "all_parts = (\n",
    "    version_bytes,      # 4 bytes  \n",
    "    depth_byte,         # 1 byte\n",
    "    parent_fingerprint, # 4 bytes\n",
    "    child_number_bytes, # 4 bytes\n",
    "    master_chain_code,  # 32 bytes\n",
    "    key_bytes,          # 33 bytes\n",
    ")\n",
    "\n",
    "all_bytes = b''.join(all_parts)\n",
    "root_key = base58.b58encode_check(all_bytes).decode('utf8')\n",
    "print(f'root key: {root_key}')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Some elliptic curve utility functions\n",
    "You can't escape math."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [],
   "source": [
    "from ecdsa import SECP256k1\n",
    "from ecdsa.ecdsa import Public_key\n",
    "\n",
    "SECP256k1_GEN = SECP256k1.generator\n",
    "\n",
    "def serialize_curve_point(p):\n",
    "   x, y = p.x(), p.y()\n",
    "   if y & 1:\n",
    "      return b'\\x03' + x.to_bytes(32, 'big')\n",
    "   else:\n",
    "      return b'\\x02' + x.to_bytes(32, 'big')\n",
    "\n",
    "def curve_point_from_int(k):\n",
    "   return Public_key(SECP256k1_GEN, SECP256k1_GEN * k).point"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Define a fingerprint function\n",
    "A fingerprint is four bytes - a link between child and parent keys."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [],
   "source": [
    "from ecdsa import SECP256k1\n",
    "from ecdsa.ecdsa import Public_key\n",
    "\n",
    "SECP256k1_GEN = SECP256k1.generator\n",
    "\n",
    "def fingerprint_from_priv_key(k):\n",
    "    K = curve_point_from_int(k)\n",
    "    K_compressed = serialize_curve_point(K)\n",
    "    identifier = hashlib.new(\n",
    "      'ripemd160',\n",
    "      hashlib.sha256(K_compressed).digest(),\n",
    "    ).digest()\n",
    "    return identifier[:4]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Define the child key derivation function"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [],
   "source": [
    "SECP256k1_ORD = SECP256k1.order\n",
    "\n",
    "def derive_ext_private_key(private_key, chain_code, child_number):\n",
    "    if child_number >= 2 ** 31:\n",
    "        # Generate a hardened key\n",
    "        data = b'\\x00' + private_key.to_bytes(32, 'big')\n",
    "    else:\n",
    "        # Generate a non-hardened key\n",
    "        p = curve_point_from_int(private_key)\n",
    "        data = serialize_curve_point(p)\n",
    "\n",
    "    data += child_number.to_bytes(4, 'big')\n",
    "\n",
    "    hmac_bytes = hmac.new(chain_code, data, hashlib.sha512).digest()\n",
    "    L, R = hmac_bytes[:32], hmac_bytes[32:]\n",
    "\n",
    "    L_as_int = int.from_bytes(L, 'big')\n",
    "    child_private_key = (L_as_int + private_key) % SECP256k1_ORD\n",
    "    child_chain_code = R\n",
    "\n",
    "    return (child_private_key, child_chain_code)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Run the child key derivation function once per path depth\n",
    "We're deriving keys for the account at the \"default\" path: `m/44'/60'/0'/0/0`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "depth: 1\n",
      "child_number: 2147483692\n",
      "parent_fingerprint: b'\\xbd\\x16\\xbe\\xe5'\n",
      "private_key: 61609765036830346750313247117170114938513374360478483024968542854420611267661\n",
      "chain_code: b']\\xf6\\xf8\\xa7\\xd2\\xa2\\xea\\xc1C\\x01\\xa1\\x90\\xdf dn\\xfe\\x11G\\xabW\\xb51Q\\xa6 \\x1b\\xc0rW\\xcf\\x19'\n",
      "\n",
      "depth: 2\n",
      "child_number: 2147483708\n",
      "parent_fingerprint: b'G\\x89\\x1eB'\n",
      "private_key: 15393795590512331372998570934590381713921834558194848920654607994440388065560\n",
      "chain_code: b'\\x05\\\\F\\xe1U\\xf2\\x04a\\x9b\\x14\\xbe\\x00\\x88\\xe6\\x95|0*\\xd5$\\xbbu\\xea~\\\\\\xdd\\xb2\\x82\\x8b\\xddC\\x99'\n",
      "\n",
      "depth: 3\n",
      "child_number: 2147483648\n",
      "parent_fingerprint: b'M\\xd6\\x18\\x80'\n",
      "private_key: 19102194832216337410531172758576291606475083221159356381572566811711190190745\n",
      "chain_code: b'6t5\\x17\\xf58\\xa4S\\xbe\\xc7\\xd9\\xd04Goa\\x9bC\\x93\\xcf\\\\\\xd03\\xaa\\xac\\xbd\\xde\\x90\\xbdS\\xdf('\n",
      "\n",
      "depth: 4\n",
      "child_number: 0\n",
      "parent_fingerprint: b'C\\xed\\x0b-'\n",
      "private_key: 40085757126754576363899103523271451610806901886905148899863161166595106319204\n",
      "chain_code: b'I\\xcc\\xe3+\\xed\\x1f^\\xf6\\xeaVH\\x89\\x80\\xae\\xed\\xf8\\x9b*\"\\xca\\x97Ei10gp\\x07p\\xec\\x19\\xb0'\n",
      "\n",
      "depth: 5\n",
      "child_number: 0\n",
      "parent_fingerprint: b'B\\xed\\xeb\\x94'\n",
      "private_key: 27274709705259927216417772762422279367947558488657189029810964524214589808527\n",
      "chain_code: b'\\xff\\x05\\xeb\\xc8\\xd5^\\x0b\\xa2.\\xc3\\xb6\\xde\\x8b[\\xb3\\xd2\\x0b\\xb2\\x93\\xff\\xb0\\xa2\\xa3\\xbb\\x14\\x8fu\\xc0\\x92\\x86\\xceA'\n",
      "\n"
     ]
    }
   ],
   "source": [
    "# Break each depth into integers (m/44'/60'/0'/0/0)\n",
    "#    e.g. (44, 60, 0, 0, 0)\n",
    "# If hardened, add 2*31 to the number:\n",
    "#    e.g. (2**31 + 44, 2**31 + 60, 2**31 + 0, 0, 0)\n",
    "path_numbers = (2147483692, 2147483708, 2147483648, 0, 0)\n",
    "\n",
    "depth = 0\n",
    "parent_fingerprint = None\n",
    "child_number = None\n",
    "private_key = master_private_key\n",
    "chain_code = master_chain_code\n",
    "\n",
    "for i in path_numbers:\n",
    "    depth += 1\n",
    "    print(f\"depth: {depth}\")\n",
    "    \n",
    "    child_number = i\n",
    "    print(f\"child_number: {child_number}\")\n",
    "    \n",
    "    parent_fingerprint = fingerprint_from_priv_key(private_key)\n",
    "    print(f\"parent_fingerprint: {parent_fingerprint}\")\n",
    "    \n",
    "    private_key, chain_code = derive_ext_private_key(private_key, chain_code, i)\n",
    "    print(f\"private_key: {private_key}\")\n",
    "    print(f\"chain_code: {chain_code}\\n\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Derive the extended private key"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "xprv: xprvA2vDkmMuK1Ae2eF92xyQpn6qZzHoGTnV5hXrBw7UExUTXeMFTZDLF7cRD6vhR785RMF2EC6mAo3ojRqFEUU8VxTSzGq1jvmXSBTxoCGSSVG\n"
     ]
    }
   ],
   "source": [
    "version_bytes = VERSION_BYTES['mainnet_private']\n",
    "depth_byte = depth.to_bytes(1, 'big')\n",
    "child_number_bytes = child_number.to_bytes(4, 'big')\n",
    "key_bytes = b'\\x00' + private_key.to_bytes(32, 'big')\n",
    "\n",
    "all_parts = (\n",
    "    version_bytes,      # 4 bytes  \n",
    "    depth_byte,         # 1 byte\n",
    "    parent_fingerprint, # 4 bytes\n",
    "    child_number_bytes, # 4 bytes\n",
    "    chain_code,         # 32 bytes\n",
    "    key_bytes,          # 33 bytes\n",
    ")\n",
    "all_bytes = b''.join(all_parts)\n",
    "extended_private_key = base58.b58encode_check(all_bytes).decode('utf8')\n",
    "print(f'xprv: {extended_private_key}')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Nailed it!** Now, for more practical purposes, we'll need a public address and a private key."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Display the private key"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "private key: 0x3c4cf049f83a5870ab31c396a0d46783c3e3974da1364ea5a2477548d36b5f8f\n"
     ]
    }
   ],
   "source": [
    "print(f'private key: {hex(private_key)}')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Derive the public key"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Point object: (34628879175116161227789129351591737524694652815106357809683939650023911982126,16686316349534243923155184728961992244162372383889866453776214730676940635074)\n",
      "\n",
      "public key (hex): 0x024c8f4044470bd42b81a8b233e2f954b63f4ee2c32c8d44288b44188754e2042e\n"
     ]
    }
   ],
   "source": [
    "# Derive the public key Point:\n",
    "p = curve_point_from_int(private_key)\n",
    "print(f'Point object: {p}\\n')\n",
    "\n",
    "# Serialize the Point, p\n",
    "public_key_bytes = serialize_curve_point(p)\n",
    "\n",
    "print(f'public key (hex): 0x{public_key_bytes.hex()}')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Derive the public address"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "address: 0xbbec2620cb01adae3f96e1fa39f997f06bfb7ca0\n"
     ]
    }
   ],
   "source": [
    "from eth_utils import keccak\n",
    "\n",
    "# Hash the concatenated x and y public key point values:\n",
    "digest = keccak(p.x().to_bytes(32, 'big') + p.y().to_bytes(32, 'big'))\n",
    "\n",
    "# Take the last 20 bytes and add '0x' to the front:\n",
    "address = '0x' + digest[-20:].hex()\n",
    "\n",
    "print(f'address: {address}')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# 🚀"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.7.6"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}