UDP wire contract
This page lets you design a receiver that conforms to the raw UDP delivery contract without assuming TCP behavior.
Before you start
- Understand UDP sockets and datagram boundaries.
- Have the customer-selected destination IP and UDP port.
- Permit inbound UDP from 64.130.40.90 when testing a live destination.
Contract summary
shredstream.sh sends raw UDP datagrams from ${REGION.city} to the IP address and port configured for the destination. The receiver does not initiate a connection. There is no service endpoint to dial and no API key in the data path.
Every datagram originates from source IP ${SOURCE_IP}. The source UDP port is not currently specified. Match the source IP, UDP protocol, and customer-selected destination port in network rules.
The maximum documented service packet size is ${WIRE.maxPacketBytes} bytes. The feed was measured at ${FEED.meanPacketBytes} mean bytes, ${FEED.packetsPerSecond.toLocaleString("en-US")} packets per second, and ${FEED.mbps} Mbps. The transport provides no ordering, no retransmission, and no backpressure.
Preserve datagram boundaries
UDP is message-oriented. One successful receive call returns bytes from one datagram up to the buffer capacity supplied by the application. Do not join adjacent receives into a continuous transport stream. Do not split one received payload based on an assumed record length.
Allocate a receive buffer that can hold at least ${WIRE.maxPacketBytes} payload bytes. A larger buffer is acceptable. A smaller buffer can truncate a datagram, depending on the operating system and receive API. Record the returned byte count and any truncation signal exposed by the API.
Pass the complete received payload to downstream shred processing. The product contract does not specify an additional service envelope that should be removed. The detailed Solana shred payload schema is not currently specified here.
Do not assume ordering
Datagrams can arrive in a different order than they were sent. Multiple network paths, queues, kernel scheduling, and application scheduling can alter arrival order. The service contract explicitly sets ordering to false.
Do not use arrival position as the canonical shred sequence. Parse the applicable shred metadata in the downstream protocol stage and organize work according to that metadata. The exact metadata schema and supported shred variants are not currently specified by the delivery contract.
Keep arrival timestamps as observations. They are useful for receiver monitoring but do not replace protocol sequence information. A timestamping method, clock source, and accuracy requirement are not currently specified.
Do not wait for retransmission
The service does not retransmit a missing UDP datagram. UDP has no acknowledgment exchange in this delivery path, and the customer does not send a negative acknowledgment to the relay.
Advance the receiver through a gap. Use Solana's applicable shred recovery behavior downstream when enough recovery data is present. A service replay API, resend endpoint for stream packets, and historical backfill are not currently specified.
The verification challenge is different from stream retransmission. The customer can request another one-time verification challenge when the first challenge is lost. That resend behavior does not apply to the shred stream.
Do not expect backpressure
The relay continues sending without learning whether the customer socket queue or application queue is full. The wire contract sets backpressure to false. A slow receiver can lose datagrams while the sender continues.
Keep the socket-reading path short. Read each datagram, record minimal metadata, place it into a bounded application structure, and return to the socket. Move decoding, logging, storage, and external calls away from the receive loop.
Define full-queue behavior explicitly. Dropping the newest item, dropping the oldest item, blocking a worker, or scaling workers are application design decisions and are not currently specified by the product. Blocking the socket reader does not slow the sender.
Size the path for sustained traffic
Plan for the measured ${FEED.mbps} Mbps and ${FEED.packetsPerSecond.toLocaleString("en-US")} packets per second across the network interface, firewall, virtual machine, kernel, socket, and application. Approximately ${FEED.terabytesPerMonth} TB reaches one destination over a month at the published measurement.
Peak bit rate, peak packet rate, burst duration, and a required headroom factor are not currently specified. Measure short intervals on the intended path and select capacity based on local loss tolerance.
Avoid per-packet terminal logs in the live receive loop. At the measured packet rate, text formatting and synchronous writes can consume the processing budget. Emit counters and sampled diagnostics instead.
Bind the destination correctly
Bind UDP, not TCP, on the configured destination port. Bind the local address that receives traffic after routing or NAT. Binding 0.0.0.0 on an IPv4 host listens on all local IPv4 interfaces, subject to operating-system behavior. Supported receiver operating systems are not currently specified.
When NAT is present, configure a stable inbound UDP mapping from the public destination pair to the receiver pair. The receiver does not create an outbound session with the service. NAT hole punching and an application registration exchange are not currently specified.
Observe without altering the contract
Use packet capture to confirm network arrival and application counters to confirm socket delivery. Compare both over the same UTC interval. Monitor kernel UDP receive errors and application queue drops.
Do not treat a packet capture as an acknowledgment to the service. Do not treat an open socket as proof of continuous delivery. UDP maintains no end-to-end session state for this feed.
Keep the firewall allowlist active for ${SOURCE_IP}. Verification status does not cause a blocked packet to bypass the customer network. Conversely, the presence of a source-specific allow rule does not prove the process is bound or keeping up.
Treat unspecified behavior as unspecified
The contract does not currently specify the source UDP port, exact activation delay, availability target, latency target, jitter target, peak rate, packet checksum policy beyond normal UDP/IP behavior, encryption, per-packet signature added by the service, replay, or delivery acknowledgments. Do not derive these properties from one capture.
Parameters
When it goes wrong
The receiver reports truncated datagrams. Example error: `MSG_TRUNC: payload exceeded receive buffer`.
Cause. The per-call receive buffer is smaller than the 1228 byte documented maximum.
Fix. Allocate at least 1228 bytes per receive and preserve the complete returned datagram.
Sequence handling rejects valid traffic. Example error: `unexpected next packet`.
Cause. The application assumes UDP arrival order is canonical.
Fix. Accept reordered datagrams and use downstream shred metadata for sequence handling.
Kernel receive errors increase. Example error: `packet receive errors: 912`.
Cause. The receive loop or downstream queue falls behind while UDP continues without backpressure.
Fix. Shorten the receive path, inspect queue capacity, monitor drops, and add processing or network headroom.
Questions
- Does raw UDP preserve shred order?
- No. The delivery contract provides no ordering. Read each datagram as an independent message and use the applicable Solana shred metadata during downstream assembly. Arrival timestamps and receive order are operational observations, not canonical sequence fields. The detailed payload schema is not currently specified by this transport reference.
- Can the receiver ask for a missing stream packet again?
- No stream retransmission or replay interface is currently specified. UDP delivery has no acknowledgment exchange, and the relay does not resend missing stream datagrams. Continue through gaps and apply the applicable Solana recovery behavior downstream. The separate dashboard action for resending a verification challenge does not cover stream packets.
- What happens when my receiver is too slow?
- The sender continues because the UDP path has no backpressure. Datagrams can be dropped in the network, kernel socket queue, or application queue. Keep socket reads short, avoid per-packet logs, monitor receive errors, and plan capacity around the measured ${FEED.mbps} Mbps and ${FEED.packetsPerSecond.toLocaleString("en-US")} packets per second.