createGroup (52)

The createGroup message is sent by the group creator to each initial participant to establish a new peer-to-peer group chat. Upon receiving this message, each participant derives the deterministic group address, adds it to their contact list, and begins participating in the group.

This message is sent within a SpixiMessage envelope with code 52. Unlike most group messages, createGroup does not set the groupAddress field on the SpixiMessage envelope - it is sent directly to each participant's address as a standard peer-to-peer message.

Core Data Types

Payload Structure

The data field of the SpixiMessage is a serialized CreateGroupMessage with the following fields, in order:

FieldData TypeMinMaxDescription
randomIdIxiBytes16 bytes16 bytesA cryptographically random identifier generated by the group creator. Used together with the creator's address to deterministically derive the group address via GroupChat.DeriveGroupAddress().
groupNameIxiBytes (UTF-8)1*The human-readable display name of the group.
hideParticipantAddressesbyte01A boolean flag (1 = enabled, 0 = disabled). When enabled, participant addresses are hidden from each other by deriving pseudonymous group-scoped addresses using DeriveGroupAddress(participantAddress, randomId).
participantCountIxiVarUInt010The number of participant entries that follow. Limited to a maximum of 10.
participants[]repeatedA list of participantCount entries, each consisting of:
↳ addressIxiBytes**The participant's address. If hideParticipantAddresses is enabled, this is the derived group-scoped address. Otherwise, it is the participant's real address.
↳ nameIxiBytes (UTF-8)0*The participant's display name. May be empty (null / zero-length bytes).
channelCountIxiVarUInt010The number of channel entries that follow. Limited to a maximum of 10.
channels[]repeatedA list of channelCount entries, each consisting of:
↳ channelNameIxiBytes (UTF-8)**The name of the channel (e.g., "general").
↳ channelDataIxiBytes**A serialized BotChannel object containing index (int32) and channelName (string).

Group Address Derivation

The group address is deterministically derived from the creator's address and the randomId:

derivationBytes = creator.addressNoChecksum || randomId
hash = SHA3-512-SQ-Trunc(derivationBytes, addressVersionLength - 1)
groupAddress = [version_byte=1] || hash

This ensures a unique, collision-resistant address that all participants can independently compute using only the creator's public key (from which the address is derived) and the randomId.

Behavioral Notes

  • Sending: The creator calls GroupChat.CreateGroup() to generate the group locally (including randomId, friend entry, user list, and metadata). The creator then wraps the CreateGroupMessage in a SpixiMessage of type createGroup and sends it to each participant individually. The groupAddress field on the SpixiMessage is intentionally not set for this message type.
  • Receiving: Upon receiving a createGroup message, the recipient calls GroupChat.JoinGroup(), which derives the group address from the sender's public key and the randomId, adds the group as a FriendType.Group contact, registers all participants, and saves the metadata. It then requests the group's avatar.
  • Replay Protection: If the recipient has already joined the group, the message's StreamMessage.timestamp is compared against the stored lastReceivedHandshakeMessageTimestamp. If the new message is older, the join is rejected.
  • Participant Limit: The participant list is hard-limited to 10 entries. Deserialization throws an exception if this limit is exceeded.
  • Channel Limit: The channel list is hard-limited to 10 entries, with the same overflow protection.
  • Hidden Addresses Mode: When hideParticipantAddresses is enabled, all group messages are routed exclusively through the group owner. Each participant's real address is replaced with a derived group-scoped address, providing address-level anonymity within the group.

avatar (24)

getAvatar (25)