.. DO NOT EDIT.
.. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY.
.. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE:
.. "api/gallery/economics/rewards/plot_02_halving_schedule.py"
.. LINE NUMBERS ARE GIVEN BELOW.

.. only:: html

    .. note::
        :class: sphx-glr-download-link-note

        :ref:`Go to the end <sphx_glr_download_api_gallery_economics_rewards_plot_02_halving_schedule.py>`
        to download the full example code or to run this example in your browser via JupyterLite.

.. rst-class:: sphx-glr-example-title

.. _sphx_glr_api_gallery_economics_rewards_plot_02_halving_schedule.py:


Fixed supply and the halving schedule (2009)
============================================

The first Bitcoin release fixed the monetary policy in code. The block at
height :math:`h` creates

.. math::

   S(h) = \left\lfloor 50 \cdot 10^8 \,/\, 2^{\lfloor h / 210\,000 \rfloor} \right\rfloor
   \text{ satoshis},

so the subsidy halves every 210,000 blocks, about every four years, and the
supply approaches a geometric limit of 21 million coins. Because the
division is a right shift that drops fractions of a satoshi, issuance stops
at the 33rd halving, around the year 2140, and the total falls short of 21
million by about 0.023 BTC. After that, miners are paid by fees alone.

.. GENERATED FROM PYTHON SOURCE LINES 21-26

.. code-block:: Python

    import matplotlib.pyplot as plt

    import blockchainkit as bk
    from blockchainkit.economics.systems.rewards import COIN, HALVING_INTERVAL








.. GENERATED FROM PYTHON SOURCE LINES 27-29

Supply and subsidy over time
----------------------------

.. GENERATED FROM PYTHON SOURCE LINES 29-51

.. code-block:: Python


    cap = bk.economics.issued_supply(64 * HALVING_INTERVAL)
    print(f"final supply: {cap / COIN:,.8f} BTC, short of 21 million by {21e6 - cap / COIN:.4f}")
    assert cap == 2_099_999_997_690_000
    last_era = max(e for e in range(64) if bk.economics.block_subsidy(e * HALVING_INTERVAL) > 0)
    assert last_era == 32  # Halving 33 brings the subsidy to zero.
    print("last block with a subsidy:", (last_era + 1) * HALVING_INTERVAL - 1)

    years = [2009 + 4 * h / HALVING_INTERVAL for h in range(0, 35 * HALVING_INTERVAL, 10_000)]
    heights = range(0, 35 * HALVING_INTERVAL, 10_000)
    fig, (left, right) = plt.subplots(1, 2, figsize=(11, 4.2))
    left.plot(years, [bk.economics.issued_supply(h) / COIN / 1e6 for h in heights], color="#2563eb")
    left.axhline(21, color="black", linestyle=":")
    left.set(xlabel="year (four years per halving)", ylabel="coins issued (millions)")
    left.set_title("A geometric series that stops just short of 21 million")
    paying = [(y, bk.economics.block_subsidy(h)) for y, h in zip(years, heights, strict=True)]
    paying = [(y, subsidy) for y, subsidy in paying if subsidy > 0]
    right.semilogy(*zip(*paying, strict=True), color="#dc2626")
    right.set(xlabel="year", ylabel="subsidy per block (satoshis)")
    right.set_title("Halving every 210,000 blocks")
    fig.tight_layout()




.. image-sg:: /api/gallery/economics/rewards/images/sphx_glr_plot_02_halving_schedule_001.png
   :alt: A geometric series that stops just short of 21 million, Halving every 210,000 blocks
   :srcset: /api/gallery/economics/rewards/images/sphx_glr_plot_02_halving_schedule_001.png
   :class: sphx-glr-single-img


.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    final supply: 20,999,999.97690000 BTC, short of 21 million by 0.0231
    last block with a subsidy: 6929999




.. GENERATED FROM PYTHON SOURCE LINES 52-56

Half of what is left
--------------------

Each era issues as much as all later eras together, plus a little rounding.

.. GENERATED FROM PYTHON SOURCE LINES 56-68

.. code-block:: Python


    for era in range(4):
        issued = bk.economics.issued_supply((era + 1) * HALVING_INTERVAL)
        issued -= bk.economics.issued_supply(era * HALVING_INTERVAL)
        later = cap - bk.economics.issued_supply((era + 1) * HALVING_INTERVAL)
        print(
            f"era {era}: {issued / COIN:>12,.0f} BTC issued, {later / COIN:>12,.2f} BTC still to come"
        )
        assert issued - later < COIN

    plt.show()





.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    era 0:   10,500,000 BTC issued, 10,499,999.98 BTC still to come
    era 1:    5,250,000 BTC issued, 5,249,999.98 BTC still to come
    era 2:    2,625,000 BTC issued, 2,624,999.98 BTC still to come
    era 3:    1,312,500 BTC issued, 1,312,499.98 BTC still to come




.. GENERATED FROM PYTHON SOURCE LINES 69-74

Exercise
--------
If the subsidy were divided exactly instead of shifted, how many coins
would eventually exist? Which halving produces the first rounding loss?
A worked solution is in :doc:`/exercises/economics`.


.. rst-class:: sphx-glr-timing

   **Total running time of the script:** (0 minutes 0.068 seconds)


.. _sphx_glr_download_api_gallery_economics_rewards_plot_02_halving_schedule.py:

.. only:: html

  .. container:: sphx-glr-footer sphx-glr-footer-example

    .. container:: lite-badge

      .. image:: images/jupyterlite_badge_logo.svg
        :target: ../../../../lite/lab/index.html?path=api/gallery/economics/rewards/plot_02_halving_schedule.ipynb
        :alt: Launch JupyterLite
        :width: 150 px

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

      :download:`Download Jupyter notebook: plot_02_halving_schedule.ipynb <plot_02_halving_schedule.ipynb>`

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

      :download:`Download Python source code: plot_02_halving_schedule.py <plot_02_halving_schedule.py>`

    .. container:: sphx-glr-download sphx-glr-download-zip

      :download:`Download zipped: plot_02_halving_schedule.zip <plot_02_halving_schedule.zip>`


.. only:: html

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

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