module

Spacetime::Docs::B_GUIDES::ArchitectureAndSats

Architecture & SATS Type System

SpacetimeDB represents all table rows, reducer arguments, and module schemas using the Spacetime Algebraic Type System (SATS). spacetime-cr models every SATS construct both at compile time (via Spacetime::Serializable and native Crystal types) and at runtime (via Spacetime::SATS::AlgebraicType and Spacetime::SATS::AlgebraicValue).

Executive Summary & Key Topics

Topic Method / Anchor Description
256-Bit Integers, Identity, and Timestamps .topic_01_extended_integers_and_identities Fixed-width 128/256-bit integers and SpacetimeDB domain types.
Dynamic SATS AlgebraicType & AlgebraicValue .topic_02_dynamic_algebraic_values Inspecting and encoding rows dynamically without compile-time structs.

Related Guides & Source References

  • Spacetime::UInt256
  • Spacetime::Int256
  • Spacetime::Identity
  • Spacetime::ConnectionId
  • Spacetime::Timestamp
  • Spacetime::SATS::AlgebraicType
  • Spacetime::SATS::AlgebraicValue

Class methods

topic_01_extended_integers_and_identities

256-Bit Integers, Identity, and Timestamps: Fixed-width 128/256-bit integers and SpacetimeDB domain types.

Key Topics & Information

  • Spacetime::UInt256: 32-byte little-endian unsigned integer (lo : UInt128, hi : UInt128) with hex conversion and comparison operators.
  • Spacetime::Int256: 32-byte two's-complement signed integer (lo : UInt128, hi : Int128).
  • Spacetime::Identity: 256-bit (32-byte) unique participant identity, convertible to and from 64-character hex strings.
  • Spacetime::ConnectionId: 128-bit (16-byte) client session identifier.
  • Spacetime::Timestamp & Spacetime::TimeDuration: Microsecond-precision UNIX timestamps and durations.
Source
topic_02_dynamic_algebraic_values

Dynamic SATS AlgebraicType & AlgebraicValue: Inspecting and encoding rows dynamically without compile-time structs.

When working with arbitrary schemas at runtime, Spacetime::SATS::AlgebraicValue can encode and decode any SATS product, sum, array, or primitive type:

Working Examples

require "spacetime"

player_type = Spacetime::SATS::ProductType.new([ Spacetime::SATS::ProductTypeElement.new("id", Spacetime::SATS::AlgebraicType.u64), Spacetime::SATS::ProductTypeElement.new("name", Spacetime::SATS::AlgebraicType.string), ])

value = Spacetime::SATS::AlgebraicValue.product([ Spacetime::SATS::AlgebraicValue.new(42_u64), Spacetime::SATS::AlgebraicValue.new("Nova"), ])

bytes = Spacetime::BSATN.encode do |enc| value.encode_bsatn(enc) end

decoded = Spacetime::BSATN.decode(bytes) do |dec| Spacetime::SATS::AlgebraicValue.decode_bsatn(dec, Spacetime::SATS::AlgebraicType.product(player_type)) end

Source