module

Spacetime::Docs::B_GUIDES::BsatnAndWireProtocol

BSATN & v1 Wire Protocol

SpacetimeDB v1 supports two WebSocket subprotocols:

  • v1.bsatn.spacetimedb: Compact little-endian binary wire encoding with optional plain (0x00), Brotli (0x01), or Gzip (0x02) server frame compression.
  • v1.json.spacetimedb: SATS-JSON text encoding for browser and debugging compatibility.

Executive Summary & Key Topics

Topic Method / Anchor Description
BSATN Wire Format Specification .topic_01_bsatn_wire_format Little-endian binary layout for primitives, strings, options, and structs.
Client & Server Protocol Envelopes .topic_02_protocol_messages SpacetimeDB v1 ClientMessage and ServerMessage sum tags.

Related Guides & Source References

  • Spacetime::BSATN
  • Spacetime::BSATN::Encoder
  • Spacetime::BSATN::Decoder
  • Spacetime::Protocol

Class methods

topic_01_bsatn_wire_format

BSATN Wire Format Specification: Little-endian binary layout for primitives, strings, options, and structs.

Key Topics & Information

  • Booleans: 0x00 (false) or 0x01 (true). Any other byte raises Spacetime::BSATNError.
  • Integers & Floats: Little-endian fixed-width bytes (UInt8..UInt256, Int8..Int256, Float32, Float64).
  • Strings & Byte Arrays: UInt32 byte length prefix followed by raw UTF-8 or binary bytes.
  • Arrays: UInt32 element count prefix followed by each encoded element.
  • Options (T?): Sum tag 0x00 for Some(value) followed by the encoded T, or 0x01 for None (nil).
  • Product Types (Structs): Fields encoded sequentially in declaration order with no field names or padding on the wire.
Source
topic_02_protocol_messages

Client & Server Protocol Envelopes: SpacetimeDB v1 ClientMessage and ServerMessage sum tags.

Spacetime::Protocol::ClientMessage supports CallReducer (tag 0), Subscribe (tag 1), OneOffQuery (tag 2), SubscribeSingle (tag 3), SubscribeMulti (tag 4), and Unsubscribe (tag 5). Spacetime::Protocol::ServerMessage decodes InitialSubscription (tag 0), TransactionUpdate (tag 1), TransactionUpdateLight (tag 2), IdentityToken (tag 3), OneOffQueryResponse (tag 4), SubscribeApplied (tag 5), UnsubscribeApplied (tag 6), SubscriptionError (tag 7), SubscribeMultiApplied (tag 8), and EnergyQuanta (tag 9).

Working Examples

require "spacetime"

struct Position include Spacetime::Serializable

getter x : Float32 getter y : Float32 getter label : String?

def initialize(@x : Float32, @y : Float32, @label : String? = nil) end end

pos = Position.new(12.5_f32, -4.0_f32, "spawn") wire_bytes = pos.to_bsatn restored = Position.from_bsatn(wire_bytes)

Source