:orphan:

Examples
========

This gallery walks through ``blockchainkit.wallets``, one experiment per
breakthrough on the :doc:`wallets history page </history/wallets_breakthroughs>`:
the error-detecting codes behind addresses, from BCH codes and Verhoeff's
check digit to Base58Check, Bech32 and Bech32m; PBKDF2, scrypt and the
brain wallets that had neither; hierarchical deterministic keys, mnemonic
seed phrases and derivation paths; and shared control of keys, from P2SH
multisig and threshold ECDSA to social recovery and ERC-4337.

Each script is self-contained and runs with
``python examples/wallets/<section>/<script>.py``.


.. raw:: html

  <div id='sg-tag-list' class='sphx-glr-tag-list'></div>


.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. thumbnail-parent-div-close

.. raw:: html

    </div>

Address encodings
-----------------

Writing a key's hash so that a typo is refused rather than paid.


.. raw:: html

  <div id='sg-tag-list' class='sphx-glr-tag-list'></div>


.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Bitcoin&#x27;s first release wrote an address as a version byte, the 20-byte HASH160 of a public key and a 4-byte checksum, in base 58: the digits and letters without 0, O, I and l, which are easily confused. A wallet refuses to pay an address whose checksum fails, so a typo is caught unless it happens to match the checksum, with probability">

.. only:: html

  .. image:: /api/gallery/wallets/addresses/images/thumb/sphx_glr_plot_01_base58check_addresses_thumb.png
    :alt:

  :doc:`/api/gallery/wallets/addresses/plot_01_base58check_addresses`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Base58Check addresses (2009)</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Pieter Wuille and Gregory Maxwell designed Bech32 for segregated-witness addresses. It uses one case and 32 characters chosen to avoid look-alikes, and a 6-character checksum that is a BCH code over GF(32): the string, read as a polynomial, must satisfy">

.. only:: html

  .. image:: /api/gallery/wallets/addresses/images/thumb/sphx_glr_plot_02_bech32_addresses_thumb.png
    :alt:

  :doc:`/api/gallery/wallets/addresses/plot_02_bech32_addresses`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Bech32 addresses (BIP173, 2017)</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="In 2019 it was found that Bech32 has a blind spot: when a string ends in p, inserting or deleting q characters just before that p leaves the checksum valid. q is the value 0, and p is 1, the constant the checksum must leave, so the extra zeros multiply the polynomial by powers of x without changing its remainder. Witness version 0 survives, because its programs must be 20 or 32 bytes, but Taproot&#x27;s version 1 and later allow other lengths. Pieter Wuille&#x27;s Bech32m changes only the constant,">

.. only:: html

  .. image:: /api/gallery/wallets/addresses/images/thumb/sphx_glr_plot_03_bech32m_checksum_flaw_thumb.png
    :alt:

  :doc:`/api/gallery/wallets/addresses/plot_03_bech32m_checksum_flaw`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Bech32m and the insertion flaw in Bech32 (BIP350, 2020)</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>

Error-detecting codes
---------------------

Catching the mistakes people make when they copy a number.


.. raw:: html

  <div id='sg-tag-list' class='sphx-glr-tag-list'></div>


.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Alexis Hocquenghem in 1959, and Raj Chandra Bose and Dijen Ray-Chaudhuri in 1960, found how to build binary codes that correct any chosen number t of flipped bits. A word of n = 2m - 1 bits is read as a polynomial, and the codewords are the multiples of a generator g(x) that vanishes at \alpha, \alpha^2, \dots, \alpha^{2t} in GF(2m). Any two codewords then differ in at least">

.. only:: html

  .. image:: /api/gallery/wallets/codes/images/thumb/sphx_glr_plot_01_bch_codes_thumb.png
    :alt:

  :doc:`/api/gallery/wallets/codes/plot_01_bch_codes`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">BCH error-correcting codes (1959-1960)</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Jacobus Verhoeff studied the errors Dutch clerks made when copying numbers: most were one wrong digit, and most of the rest were two neighbouring digits swapped. A check digit chosen so that the digit sum is a multiple of 10 catches every wrong digit but no swap, since addition commutes. Luhn&#x27;s scheme, used on payment cards, catches every swap but 09 and 90. Verhoeff catches all of them by computing in the dihedral group D5, where a  b \ne b  a, and permuting each digit by its position:">

.. only:: html

  .. image:: /api/gallery/wallets/codes/images/thumb/sphx_glr_plot_02_verhoeff_check_digit_thumb.png
    :alt:

  :doc:`/api/gallery/wallets/codes/plot_02_verhoeff_check_digit`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Verhoeff's check digit and detecting transpositions (1969)</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>

Shared control
--------------

Removing the single point of failure: multisig, threshold signatures, guardians and smart accounts.


.. raw:: html

  <div id='sg-tag-list' class='sphx-glr-tag-list'></div>


.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="One key is one point of failure. A coin locked to 2 of 3 keys survives the loss or theft of one, but before 2012 the payer had to write the whole locking script, and pay for its size. Gavin Andresen&#x27;s BIP16 locks a coin to the hash of a redeem script instead,">

.. only:: html

  .. image:: /api/gallery/wallets/custody/images/thumb/sphx_glr_plot_01_p2sh_multisig_thumb.png
    :alt:

  :doc:`/api/gallery/wallets/custody/plot_01_p2sh_multisig`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Pay-to-script-hash and multisig (BIP16, 2012)</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="A multisig script shows its policy on chain and needs a signature per signer. A threshold signature is one ordinary signature under one key, made by any t of n parties holding Shamir shares of a private key that no one ever assembles. Schnorr responses add, but ECDSA&#x27;s">

.. only:: html

  .. image:: /api/gallery/wallets/custody/images/thumb/sphx_glr_plot_02_threshold_ecdsa_thumb.png
    :alt:

  :doc:`/api/gallery/wallets/custody/plot_02_threshold_ecdsa`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Threshold ECDSA (Gennaro and Goldfeder, 2018)</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Vitalik Buterin argued in January 2021 for wallets that need no seed-phrase backup. A social-recovery wallet is a contract with one signing key for daily use and n guardians, any m of whom can replace that key. Losing the key no longer loses the coins, and a thief with the key alone can be locked out. If each guardian is independently lost with probability p_l or corrupt with probability p_c,">

.. only:: html

  .. image:: /api/gallery/wallets/custody/images/thumb/sphx_glr_plot_03_social_recovery_wallets_thumb.png
    :alt:

  :doc:`/api/gallery/wallets/custody/plot_03_social_recovery_wallets`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Social-recovery wallets (2021)</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="An Ethereum key-pair account can start transactions but follows fixed rules: one ECDSA key, gas paid in ether. A contract account can follow any rule but cannot start a transaction. ERC-4337, proposed in 2021 by Vitalik Buterin, Yoav Weiss and others and deployed in 2023, lets contract accounts act on their own without a protocol change. Owners sign user operations; a bundler submits them to an EntryPoint contract, which asks each account to validate its operation and pay its fee, then runs it. The owner signs">

.. only:: html

  .. image:: /api/gallery/wallets/custody/images/thumb/sphx_glr_plot_04_erc4337_account_abstraction_thumb.png
    :alt:

  :doc:`/api/gallery/wallets/custody/plot_04_erc4337_account_abstraction`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Account abstraction with ERC-4337 (2021)</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>

Key derivation
--------------

One seed, written as words, for a whole tree of keys that every wallet can find again.


.. raw:: html

  <div id='sg-tag-list' class='sphx-glr-tag-list'></div>


.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Early Bitcoin wallets drew each key at random, so a backup went stale with the next payment. Pieter Wuille&#x27;s BIP32 derives a tree of keys from one seed. An extended key is a key k and a chain code c, and child i is">

.. only:: html

  .. image:: /api/gallery/wallets/derivation/images/thumb/sphx_glr_plot_01_bip32_hd_wallets_thumb.png
    :alt:

  :doc:`/api/gallery/wallets/derivation/plot_01_bip32_hd_wallets`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Hierarchical deterministic wallets (BIP32, 2012)</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Marek Palatinus, Pavol Rusnak, Aaron Voisine and Sean Bowe proposed writing a wallet&#x27;s seed as words. The entropy gets a checksum, the first ENT/32 bits of its SHA-256, and the bits are cut into 11-bit indices into a list of 2048 words,">

.. only:: html

  .. image:: /api/gallery/wallets/derivation/images/thumb/sphx_glr_plot_02_bip39_mnemonic_seed_phrases_thumb.png
    :alt:

  :doc:`/api/gallery/wallets/derivation/plot_02_bip39_mnemonic_seed_phrases`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Mnemonic seed phrases (BIP39, 2013)</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="BIP32 allows any tree of keys, so one wallet program could not restore another&#x27;s from the same seed. Marek Palatinus and Pavol Rusnak fixed five levels,">

.. only:: html

  .. image:: /api/gallery/wallets/derivation/images/thumb/sphx_glr_plot_03_bip44_derivation_paths_thumb.png
    :alt:

  :doc:`/api/gallery/wallets/derivation/plot_03_bip44_derivation_paths`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Multi-account derivation paths (BIP44, 2014)</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>

Key stretching
--------------

Making every guess at a password cost time and memory, and what happens without it.


.. raw:: html

  <div id='sg-tag-list' class='sphx-glr-tag-list'></div>


.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="A key derived from a password is only as hard to find as the password. Burt Kaliski&#x27;s PBKDF2, in RFC 2898, cannot add entropy, but it makes every guess expensive: it iterates HMAC c times, and mixes in a salt so that one precomputed table cannot serve every user,">

.. only:: html

  .. image:: /api/gallery/wallets/stretching/images/thumb/sphx_glr_plot_01_pbkdf2_key_stretching_thumb.png
    :alt:

  :doc:`/api/gallery/wallets/stretching/plot_01_pbkdf2_key_stretching`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">PBKDF2 key stretching (2000)</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="PBKDF2 makes each guess slow but needs almost no memory, so custom chips run millions of guesses in parallel. Colin Percival&#x27;s scrypt makes each guess need a large table as well. Its core, ROMix, fills a table of N blocks and then reads it at N data-dependent addresses,">

.. only:: html

  .. image:: /api/gallery/wallets/stretching/images/thumb/sphx_glr_plot_02_scrypt_memory_hardness_thumb.png
    :alt:

  :doc:`/api/gallery/wallets/stretching/plot_02_scrypt_memory_hardness`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">scrypt and memory-hard key derivation (2009)</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="A brain wallet&#x27;s private key is the SHA-256 of a passphrase,">

.. only:: html

  .. image:: /api/gallery/wallets/stretching/images/thumb/sphx_glr_plot_03_brain_wallet_drain_thumb.png
    :alt:

  :doc:`/api/gallery/wallets/stretching/plot_03_brain_wallet_drain`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">The brain-wallet drain (Vasek et al., 2016)</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>


.. toctree::
   :hidden:
   :includehidden:


   /api/gallery/wallets/addresses/index.rst
   /api/gallery/wallets/codes/index.rst
   /api/gallery/wallets/custody/index.rst
   /api/gallery/wallets/derivation/index.rst
   /api/gallery/wallets/stretching/index.rst


.. only:: html

  .. container:: sphx-glr-footer sphx-glr-footer-gallery

    .. container:: sphx-glr-download sphx-glr-download-python

      :download:`Download all examples in Python source code: wallets_python.zip </api/gallery/wallets/wallets_python.zip>`

    .. container:: sphx-glr-download sphx-glr-download-jupyter

      :download:`Download all examples in Jupyter notebooks: wallets_jupyter.zip </api/gallery/wallets/wallets_jupyter.zip>`


.. only:: html

 .. rst-class:: sphx-glr-signature

    `Gallery generated by Sphinx-Gallery <https://sphinx-gallery.github.io>`_