Websocket

The websocket transport is one of the island messaging transports supported by the Decentraland comms protocol. Clients should use it when they receive an appropriate connection string from their realm's Archipelago service, or if it's indiciated as a fixed transport.

In the context of the websocket transport, an island is referred to as a room. Either name indicates the same thing: a group of nearby players that exchange updates and chat.

Connection strings begin with the ws-room: prefix, followed by a wss:// URI for the specific room. They look like this:

ws-room:wss://comms.example.com/rooms/<room-id>

In the abscence of an explicit protocol for the websocket URI, wss:// is assumed.

Connecting

The transport uses the regular websocket protocol over HTTPS. Clients can open a connection using any standard implementation at their disposal.

Websocket Packets

All messages from the websocket transport are serialized using the WsPacket structure. They implement a set of protocol-level connectivity and authentication messages, plus a container type for client messages.

The WsPacket structure should not be confused with the message [Packet][Packet]. It's an additional wrapping layer specific to the websocket transport. Actual comms messages are contained in the WsPeerUpdate type.

Field	Type	Value
message	enum	One of WsIdentification, WsChallengeRequired, WsSignedChallenge, WsWelcome, WsPeerJoin, WsPeerLeave, WsKicked or WsPeerUpdate.

Authentication

Before they can start relaying messages to others, clients must authenticate by signing a challenge string. This is required even when the transport URI was obtained from Archipelago after a previous round of authentication.

The first message a client sends when joining an island is WsIdentification, which contains a public address. It will be responded with WsChallengeRequired, and clients send a WsSignedChallenge in reply.

  .----------.                .--------.
  |  Server  |                | Client |
  '----+-----'                '---+----'
       ⋮                          |
       ⋮                  Connect |
       o - - - - - - - - - - - - -|
       |                          |
       |                          |
       |         WsIdentification |
       |<-------------------------+
       +------------------------->|
       | WsChallengeRequired      |
       |                          |
       |                          |
       |        WsSignedChallenge |
       |<-------------------------+
       +------------------------->|
       | WsWelcome                |
       |                          |

If the flow is completed successfully, the client will receive a WsWelcome and can start sending messages to peers.

---

WsIdentification ↗ source

Field	Type	Value
address	string	The public Ethereum address of the client

---

WsChallengeRequired ↗ source

Field	Type	Value
challenge_to_sign	string	The server-provided string to be signed as proof of identity
already_connected	string	A server hint to clients, indicating that prior connections may be closed.

---

WsSignedChallenge ↗ source

Field	Type	Value
auth_chain_json	string	A serialized authentication chain ending with the challenge signature.

---

WsWelcome ↗ source

Field	Type	Value
alias	uint32	A server-generated ID for the client's session
peer_identities	map<uint32, string>	The addresses of all current peers, indexed by alias

Connectivity

Three messages are defined to help clients keep track of their peers and their own status.

WsPeerJoin is received when a fellow client connects to the room and successfully authenticates, while WsPeerLeave is received when peers disconnect.

There's also the WsKicked message, which informs clients that their connection is about to be closed and the reason for it. In current practice, the main reason a server can kick a client from a room is because they've simultaneously connected to another room, when that is forbidden by server policy.

---

WsPeerJoin ↗ source

Field	Type	Value
alias	uint32	The server-generated ID sent in WsWelcome
address	string	The new peer's Ethereum address

---

WsPeerLeave ↗ source

Field	Type	Value
alias	uint32	The server-generated ID of the disconnected peer

---

WsKicked ↗ source

Field	Type	Value
reason	string	The server's explanation of why the connection will be closed

Client Messages

To send comms messages, clients wrap them in the WsPeerUpdate structure. This differentiates the transport control message types from the actual messages sent between peers.

.-------------------.
| WsPacket          |
|  .--------------. |
|  | WsPeerUpdate | |
|  | .----------. | |
|  | |  Packet  | | |
|  | '----------' | |
|  '--------------' |
'-------------------'

---

WsPeerUpdate ↗ source

Field	Type	Value
from_alias	uint32	The sender's server-generated ID
body	bytes	The serialized message being wrapped
unreliable	bool	Whether the sender prioritized speed or reliability for deliverying this message

Clients must set the from_alias field to 0 when sending, and the server will fill it with the correct identifier before delivering it to peers.