The Python implementation of the libp2p networking stack 🐍 [under development]
Go to file
Kevin Mai-Husan Chia d2c2a5f933
Merge pull request #431 from wolfgang/patch-1
Don't hash data passed to nacl library in Ed25519PublicKey.verify
2021-03-17 15:45:46 +08:00
.circleci Setup towncrier to generate release notes 2019-11-25 21:44:29 +01:00
.github Fill in template variables 2019-11-26 13:33:57 -08:00
.project-template Fill in template variables 2019-11-26 13:33:57 -08:00
assets added to readme 2018-11-07 13:06:29 -05:00
docs Release notes fix: v0.1.15 -> v0.1.5 2020-03-25 15:59:45 -07:00
examples PR feedback 2020-01-28 15:48:41 +08:00
libp2p Update ed25519.py 2021-03-16 08:55:44 +01:00
newsfragments add release notes for v0.1.15 2020-03-23 18:06:40 -07:00
scripts/release Add missing package test script used by Makefile 2019-11-26 13:33:58 -08:00
tests Use trio.lowlevel instead of trio.hazmat 2021-02-23 22:02:34 +07:00
tests_interop Use trio.lowlevel instead of trio.hazmat 2021-02-23 22:02:34 +07:00
.bumpversion.cfg Bump version: 0.1.4 → 0.1.5 2020-03-25 15:50:57 -07:00
.gitignore Splice in project template 2019-11-26 13:30:41 -08:00
.pydocstyle.ini Add docstring checking with pydocstyle 2019-01-24 13:57:17 -07:00
.travis.yml travis CI: use the latest go version 2020-02-28 15:50:03 +08:00
codecov.yml Ignore kademlia folder in code coverage (#109) 2019-01-28 16:06:03 -05:00
COPYRIGHT Dual license (MIT+Apache2) 2018-11-16 11:55:12 -08:00
LICENSE Remove attribution to specific person 2019-03-25 15:14:04 -06:00
LICENSE-APACHE Dual license (MIT+Apache2) 2018-11-16 11:55:12 -08:00
LICENSE-MIT Dual license (MIT+Apache2) 2018-11-16 11:55:12 -08:00
Makefile Noise: add compiled pb2.py 2020-02-09 13:23:12 +08:00
mypy.ini Disable incremental mode of mypy 2020-02-06 13:21:36 +01:00
pyproject.toml Customize release notes title 2019-11-27 16:09:27 -08:00
pytest.ini Splice in project template 2019-11-26 13:30:41 -08:00
README.md Fix broken release notes link 2020-08-27 01:01:45 +00:00
requirements-docs.txt Strip out fastecdsa in setup.py, during doc build 2019-11-27 14:07:14 -08:00
setup.py Use trio.lowlevel instead of trio.hazmat 2021-02-23 22:02:34 +07:00
tox.ini isort: add noise to 3rd party config 2020-02-15 12:18:44 +08:00

py-libp2p

Join the chat at https://gitter.im/py-libp2p/Lobby Build Status PyPI version Python versions Docs build Freenode Matrix Discord

py-libp2p hex logo

WARNING

py-libp2p is an experimental and work-in-progress repo under heavy development. We do not yet recommend using py-libp2p in production environments.

The Python implementation of the libp2p networking stack

Read more in the documentation on ReadTheDocs. View the release notes.

Sponsorship

This project is graciously sponsored by the Ethereum Foundation through Wave 5 of their Grants Program.

Maintainers

The py-libp2p team consists of:

@zixuanzh @alexh @stuckinaboot @robzajac @carver

Development

py-libp2p requires Python 3.7 and the best way to guarantee a clean Python 3.7 environment is with virtualenv

git clone git@github.com:libp2p/py-libp2p.git
cd py-libp2p
virtualenv -p python3.7 venv
. venv/bin/activate
pip install -e .[dev]

Testing Setup

During development, you might like to have tests run on every file save.

Show flake8 errors on file change:

# Test flake8
when-changed -v -s -r -1 libp2p/ tests/ -c "clear; flake8 libp2p tests && echo 'flake8 success' || echo 'error'"

Run multi-process tests in one command, but without color:

# in the project root:
pytest --numprocesses=4 --looponfail --maxfail=1
# the same thing, succinctly:
pytest -n 4 -f --maxfail=1

Run in one thread, with color and desktop notifications:

cd venv
ptw --onfail "notify-send -t 5000 'Test failure ⚠⚠⚠⚠⚠' 'python 3 test on py-libp2p failed'" ../tests ../libp2p

Note that tests/libp2p/test_libp2p.py contains an end-to-end messaging test between two libp2p hosts, which is the bulk of our proof of concept.

Release setup

Releases follow the same basic pattern as releases of some tangentially-related projects, like Trinity. See Trinity's release instructions.

Requirements

The protobuf description in this repository was generated by protoc at version 3.7.1.

Feature Breakdown

py-libp2p aims for conformity with the standard libp2p modules. Below is a breakdown of the modules we have developed, are developing, and may develop in the future.

Legend: 🍏 Done   🍋 In Progress   🍅 Missing   🌰 Not planned

libp2p Node Status
libp2p 🍏
Identify Protocol Status
Identify 🍋
Transport Protocols Status
TCP 🍏
UDP 🍅
WebSockets 🌰
UTP 🌰
WebRTC 🌰
SCTP 🌰
Tor 🌰
i2p 🌰
cjdns 🌰
Bluetooth LE 🌰
Audio TP 🌰
Zerotier 🌰
QUIC 🌰
Stream Muxers Status
multiplex 🍏
yamux 🍅
benchmarks 🌰
muxado 🌰
spdystream 🌰
spdy 🌰
http2 🌰
QUIC 🌰
Protocol Muxers Status
multiselect 🍏
Switch (Swarm) Status
Switch 🍏
Dialer stack 🍏
Peer Discovery Status
bootstrap list 🍅
Kademlia DHT 🌰
mDNS 🌰
PEX 🌰
DNS 🌰
Content Routing Status
Kademlia DHT 🌰
floodsub 🍏
gossipsub 🍏
PHT 🌰
Peer Routing Status
Kademlia DHT 🌰
floodsub 🍏
gossipsub 🍏
PHT 🌰
NAT Traversal Status
nat-pmp 🌰
upnp 🌰
ext addr discovery 🌰
STUN-like 🌰
line-switch relay 🌰
pkt-switch relay 🌰
Exchange Status
HTTP 🌰
Bitswap 🌰
Bittorrent 🌰
Consensus Status
Paxos 🌰
Raft 🌰
PBTF 🌰
Nakamoto 🌰

Explanation of Basic Two Node Communication

Core Concepts

(non-normative, useful for team notes, not a reference)

Several components of the libp2p stack take part when establishing a connection between two nodes:

  1. Host: a node in the libp2p network.
  2. Connection: the layer 3 connection between two nodes in a libp2p network.
  3. Transport: the component that creates a Connection, e.g. TCP, UDP, QUIC, etc.
  4. Streams: an abstraction on top of a Connection representing parallel conversations about different matters, each of which is identified by a protocol ID. Multiple streams are layered on top of a Connection via the Multiplexer.
  5. Multiplexer: a component that is responsible for wrapping messages sent on a stream with an envelope that identifies the stream they pertain to, normally via an ID. The multiplexer on the other unwraps the message and routes it internally based on the stream identification.
  6. Secure channel: optionally establishes a secure, encrypted, and authenticated channel over the Connection.
  7. Upgrader: a component that takes a raw layer 3 connection returned by the Transport, and performs the security and multiplexing negotiation to set up a secure, multiplexed channel on top of which Streams can be opened.

Communication between two hosts X and Y

(non-normative, useful for team notes, not a reference)

Initiate the connection: A host is simply a node in the libp2p network that is able to communicate with other nodes in the network. In order for X and Y to communicate with one another, one of the hosts must initiate the connection. Let's say that X is going to initiate the connection. X will first open a connection to Y. This connection is where all of the actual communication will take place.

Communication over one connection with multiple protocols: X and Y can communicate over the same connection using different protocols and the multiplexer will appropriately route messages for a given protocol to a particular handler function for that protocol, which allows for each host to handle different protocols with separate functions. Furthermore, we can use multiple streams for a given protocol that allow for the same protocol and same underlying connection to be used for communication about separate topics between nodes X and Y.

Why use multiple streams?: The purpose of using the same connection for multiple streams to communicate over is to avoid the overhead of having multiple connections between X and Y. In order for X and Y to differentiate between messages on different streams and different protocols, a multiplexer is used to encode the messages when a message will be sent and decode a message when a message is received. The multiplexer encodes the message by adding a header to the beginning of any message to be sent that contains the stream id (along with some other info). Then, the message is sent across the raw connection and the receiving host will use its multiplexer to decode the message, i.e. determine which stream id the message should be routed to.