Open Source Ecosystems

.. image:: https://raw.githubusercontent.com/protolambda/eth2.py/master/docs/_static/logo.png :width: 100 px

`eth2`

.. image:: https://img.shields.io/pypi/l/eth2.svg :target: https://pypi.python.org/pypi/eth2

.. image:: https://img.shields.io/pypi/pyversions/eth2.svg :target: https://pypi.python.org/pypi/eth2

.. image:: https://img.shields.io/pypi/status/eth2.svg :target: https://pypi.python.org/pypi/eth2

.. image:: https://img.shields.io/pypi/implementation/eth2.svg :target: https://pypi.python.org/pypi/eth2

.. image:: https://github.com/protolambda/eth2.py/workflows/Eth2%20API%20Python%20CI/badge.svg :target: https://github.com/protolambda/eth2.py/actions

Eth2.py: Python API interface to the Eth2.0 API <https://github.com/ethereum/eth2.0-apis>_.

If you are looking for the Eth2 spec, see eth2spec on PyPi <https://pypi.org/project/eth2spec/>_ and GitHub <https://github.com/ethereum/eth2.0-specs>_.

Features

Uses the excellent httpx <https://www.python-httpx.org/>_ library, with support <https://www.python-httpx.org/async/>_
for Trio <https://github.com/python-trio/trio>_ and AsyncIO <https://docs.python.org/3/library/asyncio.html>_ async runtimes.
Full type annotations, type hints for every API method
Compatible with the eth2spec package types and remerkleable for SSZ.
Through the eth2spec package, Beacon types can be configured, to use the API for testnets or other Eth2 variants.
Extensive use of Python 3.8 Protocol typing (PEP 544 <https://www.python.org/dev/peps/pep-0544/>_).
Testing has your code has never been easier, just mock the object, type-safe!.
Easy extension and definition of API routes. The API function signatures and object types are all you need.

Example

Getting started ^^^^^^^^^^^^^^^^^

.. code-block:: python

import trio
from eth2.models import lighthouse
from eth2.core import ContentType
from eth2.providers.http import Eth2HttpClient, Eth2HttpOptions

async def start():
    # Customize this to use your Beacon endpoint
    address = 'http://localhost:4000'
    # Optionally bring in your own HTTP client
    # async with httpx.AsyncClient() as client:
    #     prov = Eth2HttpProvider(client, options=Eth2HttpOptions(api_base_url=address))
    async with Eth2HttpClient(options=Eth2HttpOptions(
            api_base_url=address,
            default_req_type=ContentType.json,
            default_resp_type=ContentType.ssz)) as prov:
        # The provider can be extended with any API model.
        await fun(prov.extended_api(lighthouse.Eth2API))
    print("done!")

trio.run(start)

Using the API model ^^^^^^^^^^^^^^^^^^^^^

.. code-block:: python

from eth2.models.lighthouse import Eth2API

async def fun(api: Eth2API):
    print("fetching state!")
    data = await api.beacon.state(slot=spec.Slot(1))
    print(data.beacon_state.eth1_data)

    # Much faster than retrieving full state!
    head = await api.beacon.head()
    print(f"finalized: {head.finalized_block_root.hex()} {head.finalized_slot}")

    enr = await api.network.enr()
    print(enr)

    # Will error, the slashing is invalid, two equal headers (and no signatures ofc)
    await api.beacon.post_proposer_slashing(spec.ProposerSlashing())

Advanced API calls ^^^^^^^^^^^^^^^^^^^^

When you need to tweak individual API call settings

.. code-block:: python

from eth2.core import ContentType, APIEndpointFn
from eth2.models.lighthouse import Eth2API, APIState

async def advanced(api: Eth2API):
    # Make a copy of the callable function, to then change its settings
    fn = APIEndpointFn(api.beacon.state)
    fn.resp_type = ContentType.json  # Instead of default ssz, because why not

    # The most inefficient way to retrieve finalized checkpoint.
    # Full state, as json.
    # But hey, access any data, and process with the spec as you like.
    data: APIState = await fn(slot=spec.Slot(300))
    print(data.beacon_state.finalized_checkpoint)

Defining custom models ^^^^^^^^^^^^^^^^^^^^^^^^

The HTTP provider can "learn" how to use a model of routes, on the fly! No need to hardcode any API calls. Just define the model as a Pytho 3.8 Protocol. The Eth2 API provider will shadow this model with an implementation.

Any Protocol class with annotations can be interpreted as route model. Fields are sub-routes.
api() decorator to make function calls usable endpoints. Customize endpoint options if you need.
var_path() decorator to make function calls construct dynamic paths

Currently the Lighthouse API model is well supported, and the new standard-API is being experimented with, but incomplete.