Interoperability between js-libp2p and py-libp2p focused on ping protocol

[seetadev]

🔄 Py ↔ JS libp2p Interoperability: /ipfs/ping/1.0.0

The goal of this project is to establish interoperability between py-libp2p and js-libp2p, with a focus on the core /ipfs/ping/1.0.0 protocol.

It enables testing, validation, and cross-implementation compatibility between Python and JavaScript libp2p stacks.

---

🎯 Objective

Ensure that a py-libp2p node can connect to and exchange pings with a js-libp2p node using:

• /ipfs/ping/1.0.0 protocol
• TCP/WebSocket transports
• Multiaddr-based peer discovery

---

🛠️ Tech Stack

Component	Technology
Python node	py-libp2p
JavaScript node	js-libp2p
Protocol	/ipfs/ping/1.0.0
Transport	TCP / WebSockets
Format	32-byte raw echo ping

---

✅ Phase 0: Setup & Basic Ping

JS (Listener)

• Create a basic js-libp2p node with /ipfs/ping/1.0.0 handler
• Use TCP or WebSockets and print the peer ID + multiaddrs

Python (Dialer)

• Launch a minimal py-libp2p node
• Connect to JS peer using the given multiaddr
• Dial /ipfs/ping/1.0.0 and send a 32-byte payload
• Validate echoed response

---

🔍 Phase 1: Interop Validation

Tests

• Confirm proper stream negotiation and protocol selection
• Measure round-trip ping latency
• Handle malformed payloads, dropped packets, and timeouts

Logs

• Output peer IDs, multiaddrs, payload hex, RTT metrics

---

📦 Directory Structure

interop-py-js-libp2p/
├── js_node/
│   └── ping-server.js      # JS ping listener
├── py_node/
│   └── ping_client.py      # Python dialer
├── scripts/
│   └── run_test.sh         # Launch both nodes and validate
├── README.md               # This file

---

🧪 Sample Multiaddr Flow

# JS node prints:
Listening on /ip4/127.0.0.1/tcp/15001/ws/p2p/QmJSNode

# Python node dials:
/ip4/127.0.0.1/tcp/15001/ws/p2p/QmJSNode

---

📊 Success Criteria

• Stream to /ipfs/ping/1.0.0 opens
• Ping echoed correctly and matches RTT expectations
• Compatible framing and protocol handling

---

🚀 Future Roadmap

Following successful ping interop:

• Add /libp2p/identify/1.0.0 test
• Enable NAT traversal via relay nodes
• Support QUIC and WebRTC transports
• Integrate with automated libp2p interop testbench

[acul71]

@seetadev
I believe there will be many tests between py and js libp2p so about the dir structure

interop-py-js-libp2p/
├── js_node/
│   └── ping-server.js      # JS ping listener
├── py_node/
│   └── ping_client.py      # Python dialer
├── scripts/
│   └── run_test.sh         # Launch both nodes and validate
├── README.md               # This file

how do you suggest to add other test like identify, etc. using this structure ?

[acul71]

@paschal533 @Nkovaturient

Ok I understand now:
For example for chat:
Just add js code in js_node like chat.js and py code in py_node like chat.py and modify run_test.sh
In this way every implementation can have only one dir with relative needed packages (dependencies)

[Nkovaturient]

Thanks @acul71 ,
will look into it.

[paschal533]

@paschal533 @Nkovaturient

Ok I understand now: For example for chat: Just add js code in js_node like chat.js and py code in py_node like chat.py and modify run_test.sh In this way every implementation can have only one dir with relative needed packages (dependencies)

Thank you, Luca. Will do that right away.

[acul71]

@Nkovaturient @paschal533
I will do ping test and identify . I will work on this sunday

[acul71]

@seetadev

@Nkovaturient @paschal533 I will do ping test and identify . I will work on this sunday

I'm busy with ruff (lint and typecheck stuff) please go ahead if you want cause I will not be able to do it, I presume 'till next week or even later.

[seetadev]

@acul71 , @Nkovaturient and @paschal533 : Great initiative. Appreciate the efforts. I am opening an issue right away.

[seetadev]

Wish to share some key meeting points from JS-libp2p maintainer's meeting. To enable successful /ipfs/ping/1.0.0 communication with a js-libp2p node, the following capabilities need to be tested or implemented in py-libp2p:

• Stream Multiplexer Compatibility

  • Ensure py-libp2p uses yamux (preferred) and negotiates correctly with JS.

• Multistream Protocol Negotiation

  • Confirm that multistream-select works per libp2p spec and correctly selects /ipfs/ping/1.0.0.

• Ping Protocol Handler

  • Verify or implement the ability to send and read raw 32-byte payloads for /ipfs/ping/1.0.0.

• Transport Layer Support

  • Ensure TCP is fully supported; optionally test WebSocket compatibility if needed.

• Multiaddr Parsing

  • Dialing a multiaddr string like /ip4/127.0.0.1/tcp/15001/ws/p2p/<peer-id> must resolve correctly.

• Logging + Debug Info

  • Print peer ID, RTT, and payload hex for debugging.

Once these are in place, basic interop tests (e.g., successful echo and RTT) can be conducted reliably.

@acul71 , @paschal533 and @Nkovaturient : Looking forward to the PR. Interop tests will be added at https://github.com/libp2p/test-plans

[acul71]

@Nkovaturient
See #620 (comment) for good news.

[Nkovaturient]

spot on! @paschal533 . ⚡
@acul71, thats indeed a remarkable reveal!

[paschal533]

Hi @acul71, @Nkovaturient, @seetadev

I've been working on the py-libp2p ↔ js-libp2p interop testing and found an interesting issue with the multistream-select negotiation.

The initial connection and Yamux muxing works fine, I can see successful stream creation in the logs. The problem occurs during protocol negotiation when js-libp2p tries to read the multistream response. Python side shows streams with IDs 1 and 3 being created, but then hits a RawConnError during handle_incoming. JS side gets an AbortError when trying to read the length-prefixed stream during multistream-select.

The connection establishment is successful (both sides show proper peer IDs). Yamux multiplexing is working (streams are being created). The failure happens specifically in the multistream-select protocol negotiation. The JS side is timing out/aborting when trying to read the protocol response

Potential issues I'm investigating:

• Length-prefixed message framing differences between implementations
• Timing issues in the multistream handshake
• Protocol string formatting/encoding mismatches
• Stream flow control during negotiation

The fact that we get to the point of creating Yamux streams suggests the core networking stack is compatible, but there's something subtle in the protocol negotiation layer that's causing the abort.

I'm going to dig deeper into the multistream-select implementation differences and see if there are any known compatibility issues between the Python and JS versions. Will update with findings.