Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update README.md for upcoming v1.0.0 #301

Merged
merged 8 commits into from
Aug 18, 2023
Merged

Update README.md for upcoming v1.0.0 #301

Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
c1e5006
Add component status table
Nashatyrev Aug 17, 2023
ff9b8a6
Remove outdated roadmap and the old list of components
Nashatyrev Aug 17, 2023
7b9eb52
Add 'Notable Users' section
Nashatyrev Aug 17, 2023
373a826
Add secio to the list of components
Nashatyrev Aug 17, 2023
cb3c86a
Fix Consensys letter 'S' to a rebranded letter 's' in the URL
Nashatyrev Aug 17, 2023
a48e86b
Add 'Android support' module
Nashatyrev Aug 17, 2023
18002ad
Change the wordings
Nashatyrev Aug 17, 2023
309b016
Mention Peergos projects as library users
Nashatyrev Aug 18, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
111 changes: 59 additions & 52 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,65 +6,64 @@
![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

Deterministic Gossip simulator which may simulate networks as large as 10000 of peers

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).
Expand Down Expand Up @@ -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-minimal-0.x.y-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
Expand Down