UDP wire contract

Contract summary

shredstream.sh sends raw UDP datagrams from ${REGION.city} toward the configured destination pair. The receiver initiates no connection. Its wire path offers neither a dialable service endpoint nor an API key.

Every datagram originates from source IP ${SOURCE_IP}. A source-port value has not been published. Network rules should select ${SOURCE_IP} as origin, UDP as protocol, and the customer's configured destination port.

The maximum documented service packet size is ${WIRE.maxPacketBytes} bytes. Because Solana activity determines feed volume, measure a receiver rather than adopting a fixed planning figure. At transport level, ordering is absent. Retransmission is absent. Backpressure is absent.

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. With insufficient capacity, truncation behavior depends on both operating system and receive API. Record the returned byte count and any truncation signal exposed by the API.

Give downstream shred processing the complete received payload. This product contract defines no extra service wrapper to remove. The transport reference also leaves Solana's detailed shred schema undefined.

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 applicable metadata during the downstream protocol stage, then organize work from those fields. This delivery contract defines neither their exact schema nor its supported shred variants.

Keep arrival timestamps as observations. They help monitor a receiver but cannot replace protocol sequence information. No required timestamping method, clock source, or accuracy is published.

Do not wait for retransmission

A missing UDP datagram is never retransmitted by the service. This delivery path contains no acknowledgment exchange, and the customer sends no negative acknowledgment to its 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.

Challenge retries are separate from stream behavior. When an initial verification datagram is lost, the customer may ask the dashboard for another. That action never resends shreds.

Do not expect backpressure

The relay keeps sending without learning that customer-side queues have filled, whether socket or application. Backpressure is false under the wire contract. A slow receiver can therefore lose datagrams while transmission 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. Decoding, logging, storage, and external calls belong on downstream workers.

Define full-queue behavior explicitly. Applications choose whether to discard newest or oldest items, block a worker, or add workers. The product leaves those choices to the receiver. Blocking its socket reader never slows the sender.

Size the path for sustained traffic

Plan capacity from a locally measured rate across the network interface, firewall, virtual machine, kernel, socket, and application. Packet rate can constrain a virtual machine before bit rate, so check both. The Learn bandwidth worksheet converts this observation into a monthly byte total.

No specified values exist for peak bits, peak packets, burst duration, or mandatory headroom. Measure short intervals on the intended path and select capacity from 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.

With NAT present, map inbound UDP consistently between the public destination and receiver pairs. The receiver creates no outbound service session. Neither hole punching nor an application registration exchange is documented.

Observe without altering the contract

Use capture for network arrival and application counters for socket delivery. Compare both within one bounded UTC interval. Observe kernel UDP errors and downstream-queue losses separately.

Do not treat a packet capture as an acknowledgment to the service. An open socket likewise cannot prove continuous delivery. This UDP feed maintains no end-to-end session state.

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.