P2PNetwork

Live repo status

Loading live data from GitHub...

Repository

Name: -

Description: -

Stars: -

Language: -

Last push: -

Latest Release

Tag: -

Published: -

Assets: -

Open release notes

Open Issues

Count: -

Open Milestones

Count: -

If you only read one page

Read How to Use first, then Downloads. That is the fastest path to a working network and the release artifacts.

What this project is

P2PNetwork is a Go/libp2p-based peer-to-peer system with three cooperating surfaces:

a bootstrap service that publishes joinable nodes
a peer runtime that discovers, connects, and tracks other peers
a GUI wrapper that exposes the same network behavior through a desktop app

The network is intentionally simple at the edges and more opinionated in the middle. Bootstrap is responsible for registration and removal, peers are responsible for discovery and direct connections, and the GUI is responsible for making that runtime accessible without forcing a terminal-first workflow.

Architecture Overview

Bootstrap Service

Runs as the registry of active bootstrap nodes. It records the peer ID, multiaddr, and display name so clients can pull a fresh bootstrap list before joining the network.

Peer Runtime

Loads a local config, fetches bootstrap peers, starts libp2p, joins the discovery topic, and exposes an interactive CLI for peer inspection and ad-hoc connections.

GUI Runtime

Wraps the same networking stack in a Fyne desktop app. It can start and stop the node, shows connected peers, and keeps the app accessible for non-terminal users.

Registry API

The Python FastAPI service stores bootstrap nodes in a line-delimited registry and provides a simple read endpoint plus authenticated register and unregister routes.

How the network fits together

A bootstrap node starts first and registers itself with the registry service.
A peer or GUI node fetches the current bootstrap list from the registry before creating its libp2p host.
The node creates a DHT in server mode, seeds it with any available bootstrap peers, and bootstraps the routing table.
Discovery begins on the configured topic so newly started peers can find one another beyond the initial bootstrap set.
The node tracks connected peers separately from discovered peers so operators can see what is actually connected versus what is merely visible.

That separation matters. Discovery is not the same thing as an active session, and the UI/CLI surfaces should reflect that difference instead of collapsing everything into one list.

Runtime roles in detail

Bootstrap node

The bootstrap binary is the anchor for initial network entry. It:

starts a libp2p host on the configured port
chooses the best external address from the host’s advertised addresses
registers the peer ID, address, and name with the registry API
removes itself again when it receives a termination signal

If the registry is unavailable, the bootstrap node cannot publish itself and the rest of the network has no canonical place to fetch peers from. That makes bootstrap the one component you want monitored first.

Peer node

The peer binary is the everyday node. It:

loads config.yaml
fetches bootstrap entries from the server URL in that file
turns those bootstrap addresses into libp2p peer info
starts discovery on the configured topic
exposes a small CLI for connect, peers, discovered, and exit

This is the component that exercises the network under real use. If you are testing routing, discovery, or peer-name synchronization, this is the place to start.

GUI node

The GUI wraps the same core behavior in a windowed interface. It:

loads the same config file structure as the peer runtime
resolves bootstrap nodes before startup
starts a node when the user presses Turn On
disables name editing while the node is running
refreshes the connected-peer view on demand

The GUI is not a separate network implementation. It is a presentation layer over the same libp2p behavior, which keeps the system easier to document and debug.

Message and discovery flow

The system is built around three related flows:

Registry flow: bootstrap nodes register and unregister themselves through the server.
Discovery flow: peers advertise on the configured topic and look for other peers using the DHT-backed discovery layer.
Interaction flow: once peers are found, they can be connected directly and tracked in the node’s peer map.

The practical result is that a node can learn about the network in stages. It first learns where to start, then who is available, then who is actually connected.

Configuration model

Configuration is deliberately small. The peer and GUI side use these fields:

port for the local listener port
server for the bootstrap registry endpoint
password for authenticated bootstrap registration and removal
topic for discovery scope
name for the displayed node name
logging for debug behavior in the local runtime

The bootstrap side keeps its own small config with the port, registry URL, password, and display name. The two files are separate because the bootstrap node plays a different role in the lifecycle.

Example runtime shape

port: 0
server: https://p2p-64c70676.fastapicloud.dev
password: tehe
topic: fgov
name: Desk
logging: false

Example bootstrap shape

port: 52837
server: https://p2p-64c70676.fastapicloud.dev
password: tehe
topic: fgov
name: 2-bootstrap
logging: false

Operational expectations

This project works best when you think about it as a small network stack rather than a single app.

Bootstrap should be reachable and registered before other nodes start.
Peers should be launched with a valid registry URL so they can hydrate their bootstrap list.
The topic should stay consistent across nodes that are expected to discover one another.
The name field should be treated as a human-readable label, not as a unique identifier.

Documentation map

The site is organized so each major question has a landing page:

How to Use for startup, CLI behavior, and desktop workflow
Services for the registry API and operational behavior
Downloads for release access and build handoff

Where to go next

If you are trying to bring the network up, start with How to Use. If you are trying to get a binary, go to Downloads. If you want the live project state, keep the panel above open and watch the release and repository data directly from GitHub.