PROTOCOL NOTES / 11

Wire reference

Field widths, versions, control authority, and implemented constants.

Android and iOS software implemented · Apple Wi-Fi Aware, Bluetooth LE and mixing tested on hosts and emulators only · Physical qualification pending

Start with the exact bytes

Unsigned binary integers use network byte order unless specified otherwise. Base64 uses the canonical unpadded URL-safe alphabet. JSON signatures cover exact body.dump() bytes. Unknown message types do not gain authority.

Versions on the wire

ObjectVersion
Signed control bodies, hello and readiness probesv 2
Invitation text, after the rideweave:v2: prefixFormat 3
Discovery advertisementFormat 3
Transport greetingtransportVersion 4
Media envelopeVersion 3

A peer presenting another transport version is refused at the greeting. An invitation of another format is refused with update guidance, and an advertisement of another format is ignored, so phones of different versions never link.

An 18-byte bundle header and a 5-byte frame entry

Public synthetic fixture with one frame. The protected RTP packet and the 16-byte HMAC follow these bytes. Select a field to highlight its bytes; the complete explanation remains below.

030001020304050607000000000000000901020007000e
FieldByte offsetsMeaning
Version0–0Media envelope version 3.
Ride tag1–8First eight SHA-256 bytes of the textual ride ID.
Hop sequence9–16Directional per-link sequence, one per datagram, used with authentication and the 1,024-position replay window.
Frame count17–17Number of bundled frames, 1–8.
Hop budget18–18Remaining forwarding budget of this frame; reduced across relays.
Age19–20Accumulated media age of this frame in milliseconds.
Length21–22Length of the protected RTP packet that follows.

Public test-only values; payload demonstrates envelope layout, not a valid SRTP ciphertext

Discovery advertisement

OffsetBytesField
01Version 3 (advertisementVersion)
18Ride tag
932Raw public Ed25519 key
411Root roster index; 255 denotes unassigned admission state
421Path length
43path lengthRoster indexes from root to advertiser
p4Root pulse
p+44Advertisement serial
p+81Capability flags (table below)
p+92Cumulative cost, at most 12,000; the parent's offered cost plus the adjacent cost of the parent link, with the BLE formula max(600, C_adj + 400) when that link is ble
p+1164Ed25519 signature of every preceding byte

Capability flags

The byte at offset p+8 carries capability flags, covered by the advertisement signature. The same layout without bit 0 is the static capabilities value of join and roster member records.

Capability bitMaskMeaning
00x01Wi-Fi Aware child capacity (live NDP headroom)
10x02Apple platform
20x04Wi-Fi Aware available
30x08NAN Pairing capable; set with bit 2 by every Apple device and by an Android phone whose platform reports NAN Pairing candidacy
40x10BLE link capable
50x20BLE host capable; requires bit 4
6–70xC0Maximum BLE links minus one (0–3 means 1–4); 0 on Android API level 29 and older; ignored when bit 4 is clear

Direct link objects

Direct link objects are TLS-protected, unsigned and never relayed; the ordered TLS stream supplies their order.

TypeFieldsAuthorization and timing
hellov:2, ride, name, tokenFirst engine object on every link; see above
advertadvertisement: base64url of the signed binary discovery advertisementAccepted only on a verified link (valid hello received), in any role except closing. Its raw public key must hash to the TLS peer ID. A failed structural check or identity mismatch closes the link; a serial not above the last one received on this link is ignored; a path that contains the receiver is accepted as route information but excludes the sender as a parent candidate (a child's advertisement always contains its parent). Sent after the link is verified and whenever the local advertisement is re-signed (refresh period or route-shape change). Processed exactly like a discovery observation with this link as its path

Control message catalogue

TypeAdditional body fieldsAuthorization and propagation
joinname, key public PEM, token, capabilities:uint8 (static capability flags, bit 0 zero)Open admission, matching secret, signed source identity; relayed to organizer; at most 24 pending candidates
rosterversion:uint32, name, open:boolean, members[]Organizer only, increasing version; fixed after seal/start; can reach pending links
streamstream descriptor belowAdmitted source after seal; increasing source control seq per descriptor key (source, kind, edge); admitted active propagation/state sync only
syncNoneAdmitted sealed source requests re-publication of every current descriptor (voice and mix); no microphone activation
heartbeatmuted:boolean, active:boolean, root, pulse:uint32, path[], cost, optional media:{ssrc,nextIndex}, optional transmission; the immediate heartbeat of a local mute change carries only muted and activeAdmitted source, propagated; route refresh only if source is direct neighbor and shape valid; over a BLE link only on a muted/active change or at most every 3 s per source
source_statustransmissionAdmitted sealed source; current SSRC and ordered source progress; propagated on active admitted aware edges, never over a BLE link
feedbackreports[], links[]Admitted receivers; source reports at most 11, link reports at most 16; propagated, advisory adaptation; over a BLE link only the sender's own, and never relayed onward from a BLE link
pingstamp:uint64 monotonic ms, token:uint64Direct TLS neighbor only; signed, never flooded
pongping:uint64 echoed stamp, token:uint64, receivedAtMs:uint64, sentAtMs:uint64 responder monotonic msDirect neighbor only; ordered responder times with processing <= total RTT, matched outstanding single-use ping; never flooded
leaveNoneSigned local admitted departure; propagated; marks source unavailable, does not remove/rekey roster or end others' sessions
path_offerroot, path[], pulse:uint32, cost, revision:uint64, parentGeneration:uint64Direct admitted neighbor only; ordered fresh signed route; never flooded
handoff_prepareattempt:uint64, generation:uint64, revision:uint64Direct child asks candidate parent; tuple binds current offer, excludes known cycles; creates bounded lease
handoff_readySame tupleCandidate parent after bidirectional probes; child still needs its own proof
handoff_activateSame tuple, optional rollback:trueChild commits candidate; rollback requires newer generation on retained old active-child edge
handoff_ackSame tupleCandidate confirms its active-child role; child publishes new path only after exact match
handoff_abortattempt, generation, optional revision, optional reasonExact current tuple only; release candidate/preparation, not unrelated links
handoff_retireattempt, generationExact old active-child tuple; drain then scoped release

Bluetooth LE channel frames

A Bluetooth LE link multiplexes one L2CAP channel. Each frame is a 2-byte big-endian length (1–2,046, counting kind and body), a 1-byte kind and a body; a whole frame is at most 2,048 bytes.

KindBody
0 stream1–512 bytes of the TLS neighbor stream, in order; never dropped
1 datagramOne media envelope version 3 (67–1,280 bytes) or one readiness probe (66 bytes), never split or combined
2 ackuint64 big-endian cumulative count of bytes of kind-0 and kind-1 frames received, headers included

Mix payload header

A mix source’s SRTP plaintext begins with this header, followed by one 20 ms Opus frame. Bit i of each set is roster index i, 0–11; bits 12–15 are sent as zero and ignored.

OffsetBytesField
02Speaker set, unsigned big-endian roster bitmask
22Mixer set, unsigned big-endian roster bitmask
4restOne 20 ms Opus frame

An exact signed-body example

This public test vector demonstrates deterministic serialization. It is a synthetic ping, not a live ride token or captured user message.

{"ride":"000102030405060708090a0b0c0d0e0f","seq":7,"source":"56475aa75463474c0285df5dbf2bcab73da651358839e9b77481b2eab107708c","stamp":1234,"token":9,"type":"ping","v":2}

Implemented constants

These values are extracted from the generated protocol reference at build time. Bluetooth LE, Apple and mixing values belong to the mixed-platform extension, which is tested on hosts and emulators only. Timer, radio and acoustic defaults remain physically unqualified.

Production nameC++ typeValue
versionstd::uint8_t2
invitationVersionstd::uint8_t3
advertisementVersionstd::uint8_t3
invitationPrefixchar"rideweave:v2:"
serviceNamechar"_rideweave._tcp"
awareKeyLabelchar"rideweave-aware-v2:"
hopKeyLabelchar"rideweave-hop-v2:"
exporterLabelchar"EXPORTER-RideWeave-hop-v2"
controlPortunsigned38471
maxControlBytesstd::size_t16384
maxQueuedControlBytesstd::size_t131072
maxMediaBytesstd::size_t1280
transportVersionstd::uint8_t4
mediaEnvelopeVersionstd::uint8_t3
mediaBundleHeaderBytesstd::size_t18
mediaEntryHeaderBytesstd::size_t5
mediaBundleFramesstd::size_t8
mediaCoalesceMsstd::uint64_t5
hopMacBytesstd::size_t16
maxMembersunsigned12
initialHopBudgetunsigned12
mediaAgeMsstd::uint64_t180
mediaQueueMsstd::uint64_t40
ingressPacketsstd::size_t48
egressPacketsstd::size_t32
handshakeMsstd::uint64_t5000
pingIntervalMsstd::uint64_t1000
linkSuspectMsstd::uint64_t3000
linkEarlySuspectMsstd::uint64_t2000
linkMediaSilenceMsstd::uint64_t1000
linkDeadMsstd::uint64_t6000
linkRecoveryPongsunsigned2
discoveryFreshMsstd::uint64_t6000
rootFreshMsstd::uint64_t4500
discoveryRefreshMsstd::uint64_t1000
discoverySettledRefreshMsstd::uint64_t3000
pathEstablishMsstd::uint64_t25000
handoffProbeMsstd::uint64_t1000
handoffProbeIntervalMsstd::uint64_t250
handoffProbeAttemptsunsigned3
handoffAckMsstd::uint64_t1000
handoffDrainMsstd::uint64_t500
preparationLeaseMsstd::uint64_t2000
probeBytesstd::size_t66
probeRequeststd::uint8_t128
probeReplystd::uint8_t129
parentBetterMsstd::uint64_t10000
parentBetterLargeMsstd::uint64_t2000
parentHoldMsstd::uint64_t1500
routeCostMaxunsigned12000
adjacentCostMaxunsigned1000
adjacentCostMinunsigned5
adjacentUnknownCostunsigned50
adjacentLossCostunsigned200
improvementNumeratorunsigned4
improvementDenominatorunsigned5
discoveryPruneMsstd::uint64_t15000
feedbackFreshMsstd::uint64_t3000
bitrateRecoveryMsstd::uint64_t10000
bitrateLowint16000
bitrateInitialint24000
bitrateHighint32000
initialExpectedLossPercentint5
maximumExpectedLossPercentint20
lossDegradeddouble0.03
lossHealthydouble0.01
congestionRttGrowthMsunsigned40
congestionArrivalJitterMsunsigned15
congestionWindowsunsigned2
jitterInitialMsint60
jitterMinimumMsint40
jitterMaximumMsint160
receiverReanchorMsstd::uint64_t1000
maximumPlcFramesunsigned3
lateSpeechMsint600
sourceHintFreshMsstd::uint64_t3000
dtxStartupMsstd::uint64_t2000
dtxHangoverMsstd::uint64_t1000
dtxAnalysisFreshMsstd::uint64_t20
dtxCallbackGapMsstd::uint64_t30
dtxSpeechProbabilityfloat0.5f
dtxOnsetDbfloat12.0f
dtxFloorRiseDbfloat0.05f
dtxPrerollFramesunsigned5
dtxNearRangeDbfloat25.0f
mediaReceiveBudgetunsigned16
mediaSendBudgetunsigned128
mediaMailboxPacketsstd::size_t1024
controlDedupEntriesstd::size_t4096
hopReplayWindowstd::uint64_t1024
capabilityChildCapacitystd::uint8_t0x01
capabilityApplestd::uint8_t0x02
capabilityAwarestd::uint8_t0x04
capabilityNanPairingstd::uint8_t0x08
capabilityBleLinkstd::uint8_t0x10
capabilityBleHoststd::uint8_t0x20
capabilityBleLinksShiftunsigned6
bleServiceUuidPrefixchar"6B1E0000-7C3A-4E55-9D2E-"
bleRideTagUuidBytesstd::size_t6
bleRideInfoCharacteristicUuidchar"6B1E0001-7C3A-4E55-9D2E-000000000000"
bleRideInfoKeyLabelchar"rideweave-ble-v2:"
discoveryKeyLabelchar"rideweave-discovery-v2:"
bleRideInfoNonceBytesstd::size_t12
bleFrameStreamstd::uint8_t0
bleFrameDatagramstd::uint8_t1
bleFrameAckstd::uint8_t2
bleMaxFrameBytesstd::size_t2048
bleStreamFrameBytesstd::size_t512
bleTlsRecordBytesstd::size_t1024
bleWindowMinBytesstd::size_t1536
bleWindowMsstd::uint64_t100
bleStreamAllowanceBytesstd::size_t1024
bleMediaQueueMsstd::uint64_t100
bleAckIntervalMsstd::uint64_t20
bleAckBytesstd::size_t1024
bleMaxQueuedControlBytesstd::size_t32768
bleHeartbeatRelayMsstd::uint64_t3000
bleCostPenaltyunsigned400
bleCostMinunsigned600
bleMaxLinksunsigned4
bleLegacyMaxLinksunsigned1
bleIdleLinkMsstd::uint64_t10000
bleHostIdleLinkMsstd::uint64_t20000
bleAdvertReadMsstd::uint64_t3000
bleAdvertSlowReadMsstd::uint64_t15000
bleAdvertIdleReadMsstd::uint64_t60000
bleRejectMsstd::uint64_t60000
bleClientHelloMsstd::uint64_t1000
bleMergeJitterMsstd::uint64_t2000
btCallStuckMsstd::uint64_t5000
appleAwareMaxLinksunsigned4
mixBitrateint32000
mixHeaderBytesstd::size_t4
mixAnomalyWindowMsstd::uint64_t1000

Authority: Wire reference; generated constants; public test vectors. Public examples are synthetic. This guide is maintained against the private implementation; it does not imply access to its source.