KadePy

High-Performance P2P Swarm Implementation via Official Hyperswarm Bindings

KadePy is a robust and efficient library for connecting to the Hyperswarm network. It leverages the official, battle-tested Hyperswarm stack (Node.js) through a high-performance native binding, ensuring 100% protocol compliance, reliable holepunching, and secure communications.

Features

• Official Hyperswarm Stack: Powered by hyperswarm, hyperdht, dht-rpc, and libudx.
• Full Compatibility: Guaranteed wire compatibility with any Hyperswarm peer (Node.js, Holepunch, etc.).
• Native Bindings:
  • Uses a lightweight, managed Node.js daemon for protocol handling.
  • Transparent IPC bridge for high-performance communication between Python and the swarm.
• Secure:
  • Noise Handshake (XX Pattern): Authenticated, encrypted connections using libsodium (Ed25519/Curve25519).
  • UDX Transport: Reliable, congestion-controlled UDP transport.
• Easy to Use: Simple Python API for joining topics, finding peers, and exchanging data.
• Zero-Config: Automatically handles dependency management and process lifecycle.

Installation

Requirements

• Python 3.10+
• Node.js & npm (Required for the underlying native bindings)

From Source

git clone https://github.com/ON00dev/KadePy.git
cd KadePy
pip install .

Quick Start

Basic Swarm Node

fromkadepyimportSwarmimporthashlibimporttime# Create a node (automatically initializes the native backend)node=Swarm()
print("Node started!")
# Generate a topic key (32-byte hex string or bytes)topic=hashlib.sha256(b"my-app-topic").digest().hex()
print(f"Joining topic: {topic}")
# Join the swarm for this topicnode.join(topic)
# Define callback for new connectionsdefon_connection(socket, info):
print(f"New connection! Peer Key: {info.get('publicKey')}")
# Send a greetingsocket.sendall(b"Hello from KadePy!")
# Receive data in a loop (simple example)whileTrue:
data=socket.recv(1024)
ifnotdata: breakprint(f"Received: {data.decode()}")
# Register the callbacknode.on("connection", on_connection)
# Keep the process alivetry:
whileTrue:
time.sleep(1)
exceptKeyboardInterrupt:
print("Stopping...")
node.close()

Interoperability Example

KadePy is fully compatible with standard Node.js Hyperswarm peers.

1. Node.js Peer (peer.js)

First, install hyperswarm: npm install hyperswarm

constHyperswarm=require('hyperswarm')constcrypto=require('crypto')constswarm=newHyperswarm()// Use the same topic as Pythonconsttopic=crypto.createHash('sha256').update('my-interop-topic').digest()swarm.join(topic)swarm.on('connection',(socket)=>{console.log('New connection from KadePy!')socket.write('Hello from Node.js')socket.on('data',data=>console.log('Received:',data.toString()))})

2. Python Peer (peer.py)

fromkadepyimportSwarmimporthashlibimporttimenode=Swarm()
# Use the same topic as Node.jstopic=hashlib.sha256(b"my-interop-topic").digest().hex()
node.join(topic)
defon_connection(socket, info):
print("Connected to Node.js peer!")
# Send message to Node.jssocket.sendall(b"Hello from Python")
# Receive message from Node.jsprint("Received:", socket.recv(1024).decode())
node.on("connection", on_connection)
# Keep alivetry:
whileTrue:
time.sleep(1)
exceptKeyboardInterrupt:
node.close()

Architecture

KadePy v0.3.0 adopts a "Native Binding" architecture:

1. Python Frontend: Provides the idiomatic Swarm class and event handling.
2. Native Daemon: A pinned, vendored version of the official Hyperswarm stack running as a managed subprocess.
3. IPC Bridge: High-speed local TCP bridge for stream piping, allowing Python to interact with raw UDX streams as if they were local sockets.

This architecture ensures that KadePy behaves exactly like a native Node.js Hyperswarm peer on the network layer, eliminating protocol drift and implementation bugs.

Contributing

Contributions are welcome! Please check out the CONTRIBUTING.md guide for details.

License

Distributed under the MIT License. See LICENSE for more information.