Merge branch 'develop' into quic

# Conflicts: # libp2p/src/main/java/io/libp2p/core/dsl/HostBuilder.java # libp2p/src/main/kotlin/io/libp2p/security/tls/TLSSecureChannel.kt # libp2p/src/test/java/io/libp2p/core/HostTestJava.java # libp2p/src/testFixtures/kotlin/io/libp2p/tools/HostFactory.kt
libp2p · Jan 20, 2025 · 285b212 · 285b212
2 parents a6e34fd + 2e98c45
commit 285b212
Show file tree

Hide file tree

Showing 237 changed files with 11,812 additions and 7,520 deletions.
diff --git a/.gitattributes b/.gitattributes
@@ -0,0 +1,3 @@
+* text eol=lf
+*.bat text eol=crlf
+*.png binary
diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml
@@ -0,0 +1,55 @@
+name: Bug Report
+description: Create a bug report for jvm-libp2p
+
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thank you for filing a bug report!
+  - type: textarea
+    attributes:
+      label: Summary
+      description: Please provide a short summary of the bug, along with any information you feel relevant to replicate the bug.
+    validations:
+      required: true
+  - type: textarea
+    attributes:
+      label: Expected behavior
+      description: Describe what you expect to happen.    
+    validations:
+      required: true
+  - type: textarea
+    attributes:
+      label: Actual behavior
+      description: Describe what actually happens.    
+    validations:
+      required: true
+  - type: textarea
+    attributes:
+      label: Relevant log output
+      description: Please copy and paste any relevant log output. This will be automatically formatted into code, so no need for backticks.
+      render: shell
+    validations:
+      required: false
+  - type: textarea
+    attributes:
+      label:  Possible Solution
+      description: Suggest a fix/reason for the bug, or ideas how to implement the addition or change. 
+    validations:
+      required: false
+  - type: textarea
+    attributes:
+      label: Version
+      description: Which version of libp2p are you using? libp2p version (version number, commit, or branch)
+    validations:
+      required: false
+  - type: dropdown
+    attributes:
+      label: Would you like to work on fixing this bug ?
+      description: Any contribution towards fixing the bug is greatly appreciated. We are more than happy to provide help on the process.
+      options:
+        - "Yes"
+        - "No"
+        - Maybe
+    validations:
+      required: true
diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml
@@ -0,0 +1,8 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Technical Questions
+    url: https://github.com/libp2p/jvm-libp2p/discussions/new?category=q-a
+    about: Please ask technical questions in the jvm-libp2p Github Discussions forum.
+  - name: Community-wide libp2p Discussion
+    url: https://discuss.libp2p.io
+    about: Discussions and questions about the libp2p community.
diff --git a/.github/ISSUE_TEMPLATE/enhancement.yml b/.github/ISSUE_TEMPLATE/enhancement.yml
@@ -0,0 +1,31 @@
+name: Enhancement
+description: Suggest an improvement to an existing jvm-libp2p feature.
+body:
+  - type: textarea
+    attributes:
+      label: Description
+      description: Describe the enhancement that you are proposing.    
+    validations:
+      required: true
+  - type: textarea
+    attributes:
+      label: Motivation
+      description: Explain why this enhancement is beneficial.
+    validations:
+      required: true
+  - type: textarea
+    attributes:
+      label: Current Implementation
+      description: Describe the current implementation.
+    validations:
+      required: true
+  - type: dropdown
+    attributes:
+      label: Are you planning to do it yourself in a pull request ?
+      description: Any contribution is greatly appreciated. We are more than happy to provide help on the process.
+      options:
+        - "Yes"
+        - "No"
+        - Maybe
+    validations:
+      required: true
diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml
@@ -0,0 +1,42 @@
+name: Feature request
+description: Suggest a new feature in jvm-libp2p
+body:
+  - type: markdown
+    attributes:
+      value: |
+        If you'd like to suggest a feature related to libp2p but not specifically related to the JVM implementation, please file an issue at https://github.com/libp2p/specs instead.
+  - type: textarea
+    attributes:
+      label: Description
+      description: Briefly describe the feature that you are requesting.
+    validations:
+      required: true
+  - type: textarea
+    attributes:
+      label: Motivation
+      description: Explain why this feature is needed.
+    validations:
+      required: true
+  - type: textarea
+    attributes:
+      label: Requirements
+      description: Write a list of what you want this feature to do.
+      placeholder: "1." 
+    validations:
+      required: true
+  - type: textarea
+    attributes:
+      label: Open questions
+      description: Use this section to ask any questions that are related to the feature.
+    validations:
+      required: false
+  - type: dropdown
+    attributes:
+      label: Are you planning to do it yourself in a pull request ?
+      description: Any contribution is greatly appreciated. We are more than happy to provide help on the process.
+      options:
+        - "Yes"
+        - "No"
+        - Maybe
+    validations:
+      required: true
diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
@@ -0,0 +1,20 @@
+name: publish
+on:
+  push:
+    branches:
+      - "develop"
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-java@v3
+        with:
+          distribution: temurin
+          java-version: 11
+
+      - name: Setup Gradle
+        uses: gradle/gradle-build-action@v2
+
+      - name: Publish to Cloudsmith
+        run: ./gradlew publish -PcloudsmithUser=${{ secrets.CLOUDSMITH_USER }} -PcloudsmithApiKey=${{ secrets.CLOUDSMITH_API_KEY }}
diff --git a/.github/workflows/stale.yml b/.github/workflows/stale.yml
@@ -2,25 +2,12 @@ name: Close and mark stale issue
 
 on:
   schedule:
-  - cron: '0 0 * * *'
+    - cron: '0 0 * * *'
+
+permissions:
+  issues: write
+  pull-requests: write
 
 jobs:
   stale:
-
-    runs-on: ubuntu-latest
-    permissions:
-      issues: write
-      pull-requests: write
-
-    steps:
-    - uses: actions/stale@v3
-      with:
-        repo-token: ${{ secrets.GITHUB_TOKEN }}
-        stale-issue-message: 'Oops, seems like we needed more information for this issue, please comment with more details or this issue will be closed in 7 days.'
-        close-issue-message: 'This issue was closed because it is missing author input.'
-        stale-issue-label: 'kind/stale'
-        any-of-labels: 'need/author-input'
-        exempt-issue-labels: 'need/triage,need/community-input,need/maintainer-input,need/maintainers-input,need/analysis,status/blocked,status/in-progress,status/ready,status/deferred,status/inactive'
-        days-before-issue-stale: 6
-        days-before-issue-close: 7
-        enable-statistics: true
+    uses: pl-strflt/.github/.github/workflows/[email protected]
diff --git a/README.md b/README.md
@@ -6,116 +6,115 @@
 ![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)             |     :lemon:      |
+|                          | [autonat](https://github.com/libp2p/specs/tree/master/autonat)                                  |     :lemon:      |
+|                          | [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).
 
-[![Latest version of 'jvm-libp2p-minimal' @ Cloudsmith](https://api-prd.cloudsmith.io/v1/badges/version/libp2p/jvm-libp2p/maven/jvm-libp2p-minimal/latest/a=noarch;xg=io.libp2p/?render=true&show_latest=true)](https://cloudsmith.io/~libp2p/repos/jvm-libp2p/packages/detail/maven/jvm-libp2p-minimal/latest/a=noarch;xg=io.libp2p/)
+[![Latest version of 'jvm-libp2p' @ Cloudsmith](https://api-prd.cloudsmith.io/v1/badges/version/libp2p/jvm-libp2p/maven/jvm-libp2p/latest/a=noarch;xg=io.libp2p/?render=true&show_latest=true)](https://cloudsmith.io/~libp2p/repos/jvm-libp2p/packages/detail/maven/jvm-libp2p/latest/a=noarch;xg=io.libp2p/)
 
 As an alternative, artefacts are also available on [JitPack](https://jitpack.io/).
 
 [![](https://jitpack.io/v/libp2p/jvm-libp2p.svg)](https://jitpack.io/#libp2p/jvm-libp2p)
 
 ### Using Gradle
-Add the Cloudsmith repository to the `repositories` section of your Gradle file.
+Add the required repositories to the `repositories` section of your Gradle file.
 ```groovy
 repositories {
   // ...
   maven { url "https://dl.cloudsmith.io/public/libp2p/jvm-libp2p/maven/" }
+  maven { url "https://jitpack.io" }  
+  maven { url "https://artifacts.consensys.net/public/maven/maven/" }
 }
 ```
 Add the library to the `implementation` part of your Gradle file.
 ```groovy
 dependencies {
   // ...
-  implementation 'io.libp2p:jvm-libp2p-minimal:X.Y.Z-RELEASE'
+  implementation 'io.libp2p:jvm-libp2p:X.Y.Z-RELEASE'
 }
 ```
 ### Using Maven
-Add the repository to the `dependencyManagement` section of the pom file:
+Add the required repositories  to the `dependencyManagement` section of the pom file:
 ```xml
 <repositories>
   <repository>
     <id>libp2p-jvm-libp2p</id>
     <url>https://dl.cloudsmith.io/public/libp2p/jvm-libp2p/maven/</url>
-    <releases>
-      <enabled>true</enabled>
-      <updatePolicy>always</updatePolicy>
-    </releases>
-    <snapshots>
-      <enabled>true</enabled>
-      <updatePolicy>always</updatePolicy>
-    </snapshots>
+  </repository>
+  <repository>
+    <id>JitPack</id>
+    <url>https://jitpack.io</url>
+  </repository>
+  <repository>
+    <id>Consensys</id>
+    <url>https://artifacts.consensys.net/public/maven/maven/</url>
   </repository>
 </repositories>
 ```
-
-And then add jvm-libp2p as a dependency:
+Add the library to the `dependencies` section of the pom file:
 ``` xml
 <dependency>
   <groupId>io.libp2p</groupId>
-  <artifactId>jvm-libp2p-minimal</artifactId>
+  <artifactId>jvm-libp2p</artifactId>
   <version>X.Y.Z-RELEASE</version>
-  <type>pom</type>
 </dependency>
 ```
 
@@ -138,7 +137,15 @@ To build the library from the `jvm-libp2p` folder, run:
 ./gradlew build
 ```
 
-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`
+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