From 95a2a69f799a6f0e6568933f3122cec743088abe Mon Sep 17 00:00:00 2001 From: Anton Nashatyrev Date: Fri, 18 Aug 2023 16:02:32 +0300 Subject: [PATCH] Update README.md for upcoming v1.0.0 (#301) * Add component status table * Remove outdated roadmap and the old list of components * Add 'Notable Users' section * Add 'Android support' module --- README.md | 111 +++++++++++++++++++++++++++++------------------------- 1 file changed, 59 insertions(+), 52 deletions(-) diff --git a/README.md b/README.md index 83708458..a61e2b44 100644 --- a/README.md +++ b/README.md @@ -6,58 +6,45 @@ ![Build Status](https://github.com/libp2p/jvm-libp2p/actions/workflows/build.yml/badge.svg?branch=master) [![Discourse posts](https://img.shields.io/discourse/https/discuss.libp2p.io/posts.svg)](https://discuss.libp2p.io) -> a libp2p implementation for the JVM, written in Kotlin šŸ”„ - -**āš ļø This is heavy work in progress! āš ļø** - -## Roadmap - -The endeavour to build jvm-libp2p is split in two phases: - -* **minimal phase (v0.x):** aims to provide the bare minimum stack that will - allow JVM-based Ethereum 2.0 clients to interoperate with other clients that - rely on fully-fledged libp2p stacks written in other languages. - * To achieve this, we have to be wire-compliant, but don't need to fulfill - the complete catalogue of libp2p abstractions. - * This effort will act as a starting point to evolve this project into a - fully-fledged libp2p stack for JVM environments, including Android - runtimes. - * We are shooting for Aug/early Sept 2019. - * Only Java-friendly faƧade. - -* **maturity phase (v1.x):** upgrades the minimal version to a flexible and - versatile stack adhering to the key design principles of modularity and - pluggability that define the libp2p project. It adds features present in - mature implementations like go-libp2p, rust-libp2p, js-libp2p. - * will offer: pluggable peerstore, connection manager, QUIC transport, - circuit relay, AutoNAT, AutoRelay, NAT traversal, etc. - * Android-friendly. - * Kotlin coroutine-based faƧade, possibly a Reactive Streams faƧade too. - * work will begin after the minimal phase concludes. - -## minimal phase (v0.x): Definition of Done - -We have identified the following components on the path to attaining a minimal -implementation: - -- [X] multistream-select 1.0 -- [X] multiformats: [multiaddr](https://github.com/multiformats/multiaddr) -- [X] crypto (RSA, ed25519, secp256k1) -- [X] [secio](https://github.com/libp2p/specs/pull/106) -- [X] [connection bootstrapping](https://github.com/libp2p/specs/pull/168) -- [X] mplex as a multiplexer -- [X] stream multiplexing -- [X] TCP transport (dialing and listening) -- [X] Identify protocol -- [X] Ping protocol -- [X] [peer ID](https://github.com/libp2p/specs/pull/100) -- [X] noise security protocol -- [X] MDNS -- [X] Gossip 1.1 pubsub - -We are explicitly leaving out the peerstore, DHT, pubsub, connection manager, -etc. and other subsystems or concepts that are internal to implementations and -do not impact the ability to hold communications with other libp2p processes. +[Libp2p](https://libp2p.io/) implementation for the JVM, written in Kotlin šŸ”„ + +## Components + +List of components in the Libp2p spec and their JVM implementation status + +| | Component | Status | +|--------------------------|-------------------------------------------------------------------------------------------------|:----------------:| +| **Transport** | tcp | :green_apple: | +| | [quic](https://github.com/libp2p/specs/tree/master/quic) | :tomato: | +| | websocket | :lemon: | +| | [webtransport](https://github.com/libp2p/specs/tree/master/webtransport) | | +| | [webrtc-browser-to-server](https://github.com/libp2p/specs/blob/master/webrtc/webrtc-direct.md) | | +| | [webrtc-private-to-private](https://github.com/libp2p/specs/blob/master/webrtc/webrtc.md) | | +| **Secure Communication** | [noise](https://github.com/libp2p/specs/blob/master/noise/) | :green_apple: | +| | [tls](https://github.com/libp2p/specs/blob/master/tls/tls.md) | :lemon: | +| | [plaintext](https://github.com/libp2p/specs/blob/master/plaintext/README.md) | :lemon: | +| | [secio](https://github.com/libp2p/specs/blob/master/secio/README.md) **(deprecated)** | :green_apple: | +| **Protocol Select** | [multistream](https://github.com/multiformats/multistream-select) | :green_apple: | +| **Stream Multiplexing** | [yamux](https://github.com/libp2p/specs/blob/master/yamux/README.md) | :lemon: | +| | [mplex](https://github.com/libp2p/specs/blob/master/mplex/README.md) | :green_apple: | +| **NAT Traversal** | [circuit-relay-v2](https://github.com/libp2p/specs/blob/master/relay/circuit-v2.md) | | +| | [autonat](https://github.com/libp2p/specs/tree/master/autonat) | | +| | [hole-punching](https://github.com/libp2p/specs/blob/master/connections/hole-punching.md) | | +| **Discovery** | [bootstrap](https://github.com/libp2p/specs/blob/master/kad-dht/README.md#bootstrap-process) | | +| | random-walk | | +| | [mdns-discovery](https://github.com/libp2p/specs/blob/master/discovery/mdns.md) | :lemon: | +| | [rendezvous](https://github.com/libp2p/specs/blob/master/rendezvous/README.md) | | +| **Peer Routing** | [kad-dht](https://github.com/libp2p/specs/blob/master/kad-dht/README.md) | | +| **Publish/Subscribe** | floodsub | :lemon: | +| | [gossipsub](https://github.com/libp2p/specs/tree/master/pubsub/gossipsub) | :green_apple: | +| **Storage** | record | | +| **Other protocols** | [ping](https://github.com/libp2p/specs/blob/master/ping/ping.md) | :green_apple: | +| | [identify](https://github.com/libp2p/specs/blob/master/identify/README.md) | :green_apple: | + +Legend: +- :green_apple: - tested in production +- :lemon: - prototype or beta, not tested in production +- :tomato: - in progress ## Gossip simulator @@ -65,6 +52,18 @@ Deterministic Gossip simulator which may simulate networks as large as 10000 of Please check the Simulator [README](tools/simulator/README.md) for more details +## Android support + +The library is basically being developed with Android compatibility in mind. +However we are not aware of anyone using it in production. + +The `examples/android-chatter` module contains working sample Android application. This module is ignored by the Gradle +build when no Android SDK is installed. +To include the Android module define a valid SDK location with an `ANDROID_HOME` environment variable +or by setting the `sdk.dir` path in your project's local properties file local.properties. + +Importing the project into Android Studio should work out of the box. + ## Adding as a dependency to your project Hosting of artefacts is graciously provided by [Cloudsmith](https://cloudsmith.com). @@ -140,6 +139,14 @@ To build the library from the `jvm-libp2p` folder, run: After the build is complete you may find the library `.jar` file here: `jvm-libp2p/build/libs/jvm-libp2p-X.Y.Z-RELEASE.jar` +## Notable users + +- [Teku](https://github.com/Consensys/teku) - Ethereum Consensus Layer client +- [Nabu](https://github.com/peergos/nabu) - minimal Java implementation of IPFS +- [Peergos](https://github.com/peergos/peergos) - peer-to-peer encrypted global filesystem + +(Please open a pull request if you want your project to be added here) + ## License Dual-licensed under MIT and ASLv2, by way of the [Permissive License