datagrams: Add initial datagram draft by MarcoPolo · Pull Request #680 · libp2p/specs

MarcoPolo · 2025-05-24T04:55:53Z

Initial text for specifying how datagrams will work on libp2p.

marten-seemann

Have you considered tying a datagram flow to a stream, similar to what HTTP DATAGRAMS (RFC 9297) does?

This would have the following benefits:

Shorter datagram header (especially important given MTU restrictions).
Both peers get the opportunity to cancel a datagram flow (by closing / resetting the associated stream).
A reliable control channel, e.g. for application protocols that need to send an occasional control message next to a datagram flow.

MarcoPolo · 2025-05-27T16:19:13Z

Thanks @marten-seemann! That's a nice idea. We can include the versioning information in the stream as well so we don't pay that overhead on every datagram. The datagram itself then only has a single varint of overhead.

johannamoran · 2026-06-26T15:29:29Z

@jxs - I've reached out to zig, nim, py and dotnet for feedback to get this moving.

richard-ramos · 2026-06-29T19:24:41Z

+libp2p datagrams on WebTransport behave the same as libp2p datagrams on QUIC.
+However, the application data may be further limited by the overhead of HTTP
+Datagram's Quarter Stream ID field.
+
+In the future, a separate spec may be able to remove this overhead.


the quic encoding uses a stream id as the control stream identifier, but browser webtransport doesn't expose quic stream ids. If browser implementations are expected to support this, how is the control stream identified? would some specific webtransport flow identifier be needed?

richard-ramos · 2026-06-29T19:29:30Z

+start sending datagrams at once. There is currently no other use for the control
+stream besides negotiating the application protocol ID. Receipt of a QUIC
+DATAGRAM frame whose payload is too short to allow parsing the Control Stream ID
+field MUST be treated as a connection error of type PROTOCOL_VIOLATION (0x1003).


Perhaps something like this so the name does not clash with QUIC's own PROTOCOL_VIOLATION (0x0a) error? (also on line 71:72)

Suggested change

field MUST be treated as a connection error of type PROTOCOL_VIOLATION (0x1003).

field MUST be treated as a connection error of type DG_PROTOCOL_VIOLATION (0x1003).

richard-ramos · 2026-06-29T19:36:17Z

+If a libp2p datagram is received and its Control Stream ID field maps to a
+stream that cannot be created due to client-initiated bidirectional stream
+limits, it MUST be treated as a connection error of type PROTOCOL_VIOLATION
+(0x1003).


i'm a bit confused by the reference to "client-initiated bidirectional stream limits". Can control streams be opened by either peer?

richard-ramos · 2026-06-29T19:44:16Z

+protocol. A control stream is a QUIC bidirectional stream that has negotiated
+the libp2p datagram control stream protocol ID `/dg/1`. The initiator MUST send
+the related application protocol ID with a [uvarint] length prefix after
+negotiating the control stream. The control stream MUST stay open for the


i think it would help to clarify the receiver behavior if the application protocol id is unsupported or malformed. (i.e. close stream / reset?). Is this going to use multistream-select?

I'd say probably be closed

richard-ramos · 2026-06-29T19:52:47Z

+the related application protocol ID with a [uvarint] length prefix after
+negotiating the control stream. The control stream MUST stay open for the
+duration of the datagram flow. Implementation MAY create the control stream and
+start sending datagrams at once. There is currently no other use for the control


What should happen to datagrams that arrive before control stream has finished /dg1 processing and application protocol negotiation? should they be dropped or buffered?

I suggest discarding them, buffering them introduces a possible attack vector

gmelodie · 2026-08-12T12:49:09Z

+This specification defines libp2p datagrams, which enable the transmission of
+MTU-sized, unreliable, and low latency messages between peers.


the transmission of ... unreliable ... messages between peers

It's not very clear to me what these are. If the definition is the same of QUIC's unreliable datagrams, maybe it's worth it to be explicit here?

Come to think of it... are not all datagrams unreliable? This is a different discussion but the name seems confusing.

gmelodie · 2026-08-12T12:58:30Z

+Some libp2p transports natively support datagrams, such as QUIC and
+WebTransport. libp2p implementations MUST use the native datagram support to


such as QUIC and WebTransport

But then what follows is a detailed description of how datagrams in QUIC are supposed to be handled. At least to me this seems to telegraph that this document will hold an extensive list of the supported underlying protocols, and how to handle each of them.

In other words, reading this makes me think that following there will be a list of all supported protocols and how to handle them, otherwise they're not supported at all.

So I guess if we'll have particular cases such as QUIC, we must also have a non-particular (i.e. default) case that hopefully most of the underlying protocols will follow

In other words, sth like this:

such as quic and webtransport

Datagrams

for most protocols this is the case...

Excepctions

QUIC Datagrams

blabla

another exception

The alternative would be to have an extensive list of supported underlying protos, but to me that would make it harder to extend and the spec would need constant maintenance

gmelodie · 2026-08-12T13:00:31Z

+closed, the received datagrams MUST be silently dropped.
+
+If a libp2p datagram is received and its Control Stream ID field maps to a
+stream that has not yet been created, the receiver SHALL either drop that


Suggested change

stream that has not yet been created, the receiver SHALL either drop that

stream that has not yet been created, the receiver MUST either drop that

gmelodie · 2026-08-12T13:00:42Z

+
+### Encoding
+
+Each libp2p datagram SHALL be encoded with the following structure.


Suggested change

Each libp2p datagram SHALL be encoded with the following structure.

Each libp2p datagram MUST be encoded with the following structure.

gmelodie · 2026-08-12T13:07:39Z

+Each datagram flow MUST be associated with a control stream. A datagram flow is
+defined as a logical flow of datagrams related to a specific application
+protocol. A control stream is a QUIC bidirectional stream that has negotiated


A datagram flow is defined as a logical flow of datagrams related to a specific application protocol. A control stream is a QUIC bidirectional stream that has negotiated...

These could be in a Terminology section to make it easier to understand when only reading parts of the document.

gmelodie · 2026-08-12T13:10:11Z

+stream besides negotiating the application protocol ID. Receipt of a QUIC
+DATAGRAM frame whose payload is too short to allow parsing the Control Stream ID
+field MUST be treated as a connection error of type PROTOCOL_VIOLATION (0x1003).


nit: wording

Suggested change

stream besides negotiating the application protocol ID. Receipt of a QUIC

DATAGRAM frame whose payload is too short to allow parsing the Control Stream ID

field MUST be treated as a connection error of type PROTOCOL_VIOLATION (0x1003).

stream besides negotiating the application protocol ID. If a DATAGRAM frame's payload cannot be parsed as a Control Stream ID followed by application data, the endpoint MUST close the connection with a PROTOCOL_VIOLATION (0x1003) error.

gmelodie · 2026-08-12T13:11:43Z

+libp2p datagrams MUST NOT be sent unless the control stream's send side is open.
+If a datagram is received after the corresponding stream's receive side is
+closed, the received datagrams MUST be silently dropped.


nit: wording

Suggested change

libp2p datagrams MUST NOT be sent unless the control stream's send side is open.

If a datagram is received after the corresponding stream's receive side is

closed, the received datagrams MUST be silently dropped.

An endpoint MUST NOT send libp2p datagrams unless the send side of the associated control stream is open. An endpoint that receives a datagram after the receive side of the corresponding control stream is closed MUST silently drop it.

datagrams: Add initial datagram draft

3f0745c

github-project-automation Bot added this to libp2p Specs May 24, 2025

github-project-automation Bot moved this to Triage in libp2p Specs May 24, 2025

marten-seemann reviewed May 24, 2025

View reviewed changes

MarcoPolo added 3 commits May 27, 2025 18:13

Update spec to use stream ID pointer as protocol ID and version

c4217cd

Specify control stream protocol id

6442799

Specify uvarint length prefix

1b5c110

MarcoPolo force-pushed the marco/datagrams branch from 8dac785 to 1b5c110 Compare May 28, 2025 15:28

sukunrt self-requested a review May 29, 2025 14:02

haxxpop mentioned this pull request Oct 2, 2025

Add Marco Munizaga from EF P2P team protocolguild/documentation#425

Merged

This was referenced Jun 17, 2026

IP over libp2p #626

Open

feat: unreliable datagram support (QUIC + libp2p-datagram) libp2p/rust-libp2p#6489

Open

richard-ramos reviewed Jun 29, 2026

View reviewed changes

gmelodie reviewed Aug 12, 2026

View reviewed changes

	field MUST be treated as a connection error of type PROTOCOL_VIOLATION (0x1003).
	field MUST be treated as a connection error of type DG_PROTOCOL_VIOLATION (0x1003).

		This specification defines libp2p datagrams, which enable the transmission of
		MTU-sized, unreliable, and low latency messages between peers.

		Some libp2p transports natively support datagrams, such as QUIC and
		WebTransport. libp2p implementations MUST use the native datagram support to

	stream that has not yet been created, the receiver SHALL either drop that
	stream that has not yet been created, the receiver MUST either drop that


		### Encoding

		Each libp2p datagram SHALL be encoded with the following structure.

	Each libp2p datagram SHALL be encoded with the following structure.
	Each libp2p datagram MUST be encoded with the following structure.

Uh oh!

Conversation

MarcoPolo commented May 24, 2025

Uh oh!

marten-seemann left a comment

Choose a reason for hiding this comment

Uh oh!

MarcoPolo commented May 27, 2025

Uh oh!

johannamoran commented Jun 26, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Datagrams

Excepctions

QUIC Datagrams

another exception

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants