QUIC implementation in Py-libp2p

[seetadev]

Dear Py-libp2p team members,

Following the initial review and interoperability testing phase, I’d like to outline the next phase of the QUIC implementation and development work. This phase will be key to strengthening our Python-based QUIC transport for libp2p and aligning it better with broader ecosystem efforts.

After completing the MVP and interoperability testing, our focus should be on implementing QUIC more robustly by leveraging one of the following lower-level approaches:

• MSQUIC-based approach (either through a direct wrapper or via an intermediate like Zig or C bindings)
• NAPI/Rust library-based approach (Rust bindings exposed to Python, possibly via PyO3 or other wrappers)
• C library-based approach (direct CPython bindings if necessary)

Depending on your preference and what you find easier to work with, we can decide the exact pathway — all three options are valid and have their own trade-offs in terms of performance, maintenance, and compatibility.

Additionally, it’s worth keeping an eye on some related efforts across the libp2p ecosystem, which could significantly inform and refine our own design:

• zig-msquic + zig-libp2p:
  There’s work happening to wrap ms-quic using Zig’s FFI capabilities for use within Zig-libp2p: please visit https://github.com/MarcoPolo/zig-libp2p
  ➔ This could offer valuable insights into performance optimization and interoperability techniques, and potentially inspire native bindings strategies for Python.
  ➔ Aleksey (@flcl42) is also exploring MSQUIC integration in dotnet-libp2p, providing another parallel track we can learn from: please visit https://github.com/NethermindEth/dotnet-libp2p/tree/main and Quic on Windows should use OpenSSL version NethermindEth/dotnet-libp2p#45

• Cayman’s js-libp2p-quic (Rust-backed for JS stack):
  Cayman (@wemeetagain) has built a Rust-based QUIC transport for js-libp2p : please visit https://github.com/ChainSafe/js-libp2p-quic
  ➔ This can be very useful to validate handshake compatibility and muxing behavior across different runtimes, which will become crucial once we do transport interop with js-libp2p.
  ➔ Great work by Cayman that we can learn from as we aim for smooth cross-language interoperability.

• Waku team's ngtcp2 bindings in Nim:
  Our collaborators at Waku are wrapping ngtcp2 (another QUIC implementation) in Nim using OpenSSL.
  ➔ See here: Waku Nim-libp2p QUIC Transport
  ➔ Their approach will be a wonderful reference, especially if we consider evaluating other QUIC backend libraries for our use cases or future interop scenarios.
  ➔ Hats off to @richard-ramos and @vladopajic for their great work here.

Immediate next steps for you:

1. Study the specs on QUIC and try learning from the current MVP PR and get hands-on familiarity.
2. Attempt interoperability testing with other libp2p nodes (Go, Rust, JS) as described.
3. Based on the outcome, start planning the deeper integration using either MSQUIC, a Rust binding, or C library binding — whichever you are most comfortable with.
4. Keep tracking related ecosystem projects as they might offer shortcuts, better techniques, or libraries we can use instead of building everything from scratch.

[AkMo3]

I had been spending some thoughts regarding what approach we should take regarding implementation of QUIC.

Questions and Considerations:

1. What implementation other libp2p projects are using?

Libp2p Implementation	QUIC Framework
go-libp2p	quic-go
rust-libp2p	quinn
js-libp2p	quinn (via Rust/NAPI bindings)

2. Possible implementation plans:

   1. Python Native Implementation using aioquic - https://github.com/aiortc/aioquic (Python Implementation conforming with RFC 9000 (QUIC v1) and RFC 9369 (QUIC v2))
   2. Use FFI to generate python bindings for quinn - https://github.com/quinn-rs/quinn (Rust implementation, can be used inside python project using PyO3 which will generate rust binding similar to js-libp2p)

3. Interoperability result:

   1. The https://interop.seemann.io/ provides great interop status of various QUIC client and server implementation. Here is a summarised versioned filtered according to our needs.

   2. Client (aioquic vs quinn):
      

   3. Server (aioquic vs quinn):
      

   4. Summary:

      1. Server Performance:

         • quinn: The quinn server column shows a nearly perfect record. It successfully handles connections and all test cases (like Handshake, Data Transfer, Connection Migration, and Retry) from almost every client implementation in the matrix, including aioquic, quic-go, mvfst (Meta), quiche (Cloudflare), and msquic (Microsoft).
         • aioquic: The aioquic server column also shows a very strong performance, with successful tests against the vast majority of clients. It demonstrates full compatibility with all major libp2p-relevant clients like quic-go and quinn.

      2. Client Performance:

         • quinn: As a client, quinn successfully connects to and passes all test cases against nearly every server in the matrix. Its row is overwhelmingly green, showing it can reliably talk to servers from Google, Meta, Microsoft, and others.
         • aioquic: Similarly, the aioquic client has a very high success rate. It passes the test suites against all major server implementations, including quinn, proving its robustness as a client.

      3. Direct aioquic vs. quinn Interaction:

         • The test cell for aioquic (client) connecting to quinn (server) is green.
         • The test cell for quinn (client) connecting to aioquic (server) is green.

         In conclusion, the live data shows no meaningful difference in standards compliance or interoperability between aioquic and quinn.

4. Performance:

   • aioquic in itself doesn't provide any benchmarks, but I found a interesting graph in one of the reasearch study

 As expected, `aioquic` was least performant since it is the only interpreted and not compiled implementation. I similarly expect `quinn` to be more performant one here.

6. Maintainability:

   1. Using quinn with PyO3 will require some significant changes:
   • Development Environment:

   - Rust toolchain: rustc, cargo, rustfmt, clippy installation
   - maturin: Python-Rust build tool (pip install maturin)
   - Platform linkers: MSVC on Windows, appropriate cross-compilation toolchains
   - Python dev headers: For all target Python versions (python3-dev packages)
   

   • Build System:

   - Multi-stage builds: Rust compilation → Python extension building
   - Cross-ecosystem dependencies: Rust crates + Python packages coordination
   - Platform-specific compilation: Different flags for Linux/macOS/Windows
   - Build time impact: 3-5x longer than pure Python builds
   

   • Package Distribution:

   - Wheel matrix: Multiple platforms × Python versions (12+ wheel variants typical)
   - Binary size: ~10-50MB wheels vs ~1MB pure Python
   - Build infrastructure: High-CPU runners for compilation
   - Storage costs: Significantly larger artifact storage requirements
   

   2. Project Activity: The quinn implementation is better maintained and undergoing active development, whereas the aioquic project development is quite slow paced.

   3. Production Ready: The quinn implementation is fairly production ready, while aioquic is used by projects like mitmproxy, I am yet to see a fairly large production grade project yet to use it.

7. My thoughts:

It is a very tough choice, using quinn will bring significant performance and better interoperability with other libp2p projects using quinn, but at the significant cost of harder development lifecycle.

Are the performance benefits worth the cost, I would beg to differ at this point.

Rather I would like to go first with the python native approach resulting in a much faster implementation of QUIC, and it has all the features 0-RTT, HTTP/3 support etc. If and when we see a requirement of bringing high-performance QUIC transport, then we can come back here, curse me and start development of a new transport.

Would love to hear your thoughts on this @seetadev @pacrob

[seetadev]

@AkMo3 : Thank you so much for the incredibly thorough and thoughtful breakdown — this is excellent work, and I really appreciate the depth of analysis you’ve brought in here. You've laid out the trade-offs between the two implementation options for QUIC with great clarity, especially factoring in performance, interoperability, and maintainability.

The proposed path — starting with aioquic as the initial QUIC transport layer — makes a lot of sense in our current context.

On the same note, thanks for also sharing your feedback on the existing efforts on QUIC transport layer within Py-libp2p.

Here's why I strongly agree with your approach:

1. Rapid Prototyping and Implementation Velocity:
   Choosing aioquic allows us to move faster with a native Python implementation that keeps the development process lightweight and aligned with the existing ecosystem. This is especially important as we continue to evolve the py-libp2p stack — early integration, testing, and iteration matter more than premature optimization.

2. Interoperability Looks Strong:
   The test results from https://interop.seemann.io/ are very reassuring — the direct aioquic ↔ quinn compatibility greenlights interoperability with rust-libp2p and, by extension, other language implementations like js-libp2p and go-libp2p.

3. Clear Migration Path:
   Your suggestion to revisit a quinn + PyO3 approach only when performance demands it is a balanced and forward-looking idea. It leaves the door open for optimization while allowing us to validate the protocol integration first.

4. Lower Overhead for New Contributors:
   Keeping the stack Python-native at this stage lowers the entry barrier, especially for contributors who may not be familiar with the complexities of a Rust-based toolchain or FFI builds. That supports broader community involvement and makes mentoring and onboarding easier.

5. Community Alignment:
   While quinn is being used more broadly across the libp2p ecosystem, aioquic is still a highly standards-compliant implementation with growing adoption. And as you noted, its features like 0-RTT and HTTP/3 are all there.

Overall, I’m fully aligned with your proposal to go ahead with aioquic as our initial QUIC transport layer for py-libp2p. It strikes a great balance between pragmatism and future extensibility.

Please go ahead and start shaping the transport layer around aioquic.

Let’s keep tracking performance metrics, and if any bottlenecks arise during usage or scaling, we can revisit and prioritize optimization.

Thanks again for the clarity and leadership here — delighted to see this move forward.

[pacrob]

Thanks for your thorough review, @AkMo3. I agree with your and @seetadev's view.

[seetadev]

@pacrob : Thank you Paul for your kind feedback and pointers. Appreciate it.