Native protocol SDKs

​

What each baseline implements

• Canonical JSON — deterministic serialization with sorted object keys and no insignificant whitespace, so two implementations produce byte-identical output for the same logical value.
• CLX1 framing — a 4-byte big-endian length prefix followed by the canonical JSON payload (sdks/rust/src/lib.rs::encode_frame, CrosslinkProtocol.encodeFrame in Kotlin/Swift).
• Incremental frame decoding — a decoder that can be fed partial byte chunks (as they arrive off a socket) and yields complete messages once a full frame is buffered, enforcing the max-frame-size limit before allocating.
• Protocol version checks — rejecting a frame whose v field isn’t the supported CLX1 version.
• Shared fixtures — the same messages-v1.json and invalid-v1.json corpus every language SDK is checked against.

// sdks/rust/src/lib.rs
pub const PROTOCOL_VERSION: &str = "1.0";
pub const DEFAULT_MAX_FRAME_BYTES: usize = 1_048_576;

pub fn canonical_json(value: &Value) -> Result<String, ProtocolError> { /* ... */ }
pub fn encode_frame(value: &Value, max_bytes: usize) -> Result<Vec<u8>, ProtocolError> { /* ... */ }

// sdks/kotlin/src/main/kotlin/dev/crosslink/sdk/Protocol.kt
object CrosslinkProtocol {
    const val VERSION = "1.0"
    const val DEFAULT_MAX_FRAME_BYTES = 1_048_576
    fun canonicalJson(value: CrosslinkValue): String { /* ... */ }
    fun encodeFrame(value: CrosslinkValue.ObjectValue, maxBytes: Int = DEFAULT_MAX_FRAME_BYTES): ByteArray { /* ... */ }
}

// sdks/swift/Sources/Crosslink/Protocol.swift
public enum CrosslinkProtocol {
    public static let version = "1.0"
    public static let defaultMaxFrameBytes = 1_048_576
    public static func canonicalJSON(_ value: Any) throws -> String { /* ... */ }
    public static func encodeMessage(_ object: [String: Any]) throws -> Data { /* ... */ }
}

​

What they deliberately do not implement yet

• Transport selection — no WebSocket/WebRTC client, no LAN vs. relay candidate racing (see Networking)
• The CLX1 handshake — no X25519/Ed25519 key exchange, no hybrid PQ support (see Encryption and Hybrid post-quantum exchange)
• Pairing UI — no QR/code entry flow, no SAS verification
• Persistent identity — no keychain/keystore-backed device identity across restarts
• Reconnect policy — no backoff, no session resumption

​

Adding a language

1. Implement canonical JSON and the 4-byte big-endian frame length prefix.
2. Enforce frame-size and protocol-version limits before allocating memory for the payload — the negative fixtures include an oversized-frame case specifically to catch implementations that decode first and check second.
3. Port every fixture from packages/protocol/fixtures/messages-v1.json and packages/conformance/fixtures/invalid-v1.json without changing them — fixtures are generated from (and only ever edited alongside) the TypeScript reference in packages/protocol.
4. Assert the exact stable error code (parse_error, version_unsupported, invalid_message, …) for every negative fixture, not just “an error was thrown.”
5. Add the SDK’s test command to .github/workflows/ci.yml’s native-protocol job before implementing transports or crypto, so conformance regressions are caught from the first commit.