Technology · GProtocol

GProtocol

GProtocol defines all communication between the app and nodes: the request and response format, 62 actions, how errors are expressed, and which fields may only hold ciphertext.

Current version 8.0.0

Transport and versioning

App to node: WebSocket + JSON, with all fields in camelCase.
Between nodes: libp2p, with protocol IDs such as /gather/message/1.0.0; node-to-node protocols are implemented inside the node and are not part of GProtocol.
Versioning rules: a breaking change bumps the major version, and minor versions only add fields. The protocol version is sent at login, and a request with a different major version is rejected with a prompt to upgrade.
Real-time actions (such as typing indicators and call signaling) are dropped if they cannot be delivered; they are not stored as offline messages.

Requests and responses

requestType: regular is handled by the node; route is forwarded point to point
action: The action path, for example /message/send
requestId: Used to match a response to its request
submitter / receiver: Addresses of both sides; the sender is replaced by the node with the authenticated identity
data: Business data; anything that is content has already been encrypted in the app
signature: The request signature
errorKey: Errors are expressed as a key; the app shows text in the local language for that key, and text returned by a node is never shown to the user directly

A message, as a node sees it

This is a direct message the app sends to its entry node. The fields needed for routing are in the clear; the content is just ciphertext.

wss://…/ws · /message/send

{
  "requestType": "route",
  "action": "/message/send",
  "requestId": "9c1e…a42f",
  "submitter": "N4k2…Qx7",
  "receiver": "Np8V…3dL",
  "timestamp": 1794420000000,
  "data": "q8Zr4t…/Hk1yWQ==",
  "signature": "3045…e1b0"
}

Illustration: field names match GProtocol 8.0.0; the values are made up.

14 modules, 62 actions

Removed modules are no longer listed.

Module	Actions	Purpose
/user	10	Handshake, login and logout, heartbeat, online status, peer-to-peer profile exchange
/message	9	Send, acknowledge, fetch offline, read, typing, unsend, edit, reactions
/file	8	Chunked upload and download, pickup by credential
/call	7	One-to-one call signaling, ICE and relay configuration
/friend	6	Contact request, accept, decline, delete, list
/key	6	Upload, fetch, replenish and low-stock reminder for X3DH prekeys
/group	4	Anonymous fan-out, reading and writing encrypted state blocks, unsend (nodes do not host groups)
/push	3	Push token registration, deregistration and testing
/backup	2	Encrypted relationship backup and favorites backup
/device	2	Active sessions on this node, sign out a device
/node	2	Node identity proof, node directory
/card · /security · /tip	3	Contact cards, safety code check, tip forwarding

Security design in the protocol

Login

The wallet key signs "user · device · timestamp"; the node accepts only signatures within a very short time window, and checks the protocol major version at the same time.

Node identity

The app sends a random number and the node returns a signature; the app checks that the public key matches the node ID, and checks the operator attestation and the release manifest.

Offline mailbox

The mailbox ID changes every day; content is sealed with X25519, with the sender inside the seal; both pickup and acknowledgement must be signed.

Groups

Nodes see only an anonymous delivery target and encrypted state blocks; they cannot see the group name or members.

Files

The pickup credential is derived from the file key, and nodes do not store a share list.

Backup

The backup location is derived by the client and writes must be signed; the network-wide shared key has been removed.

Protocol status

GProtocol is not frozen yet. Major versions may still change before launch, and compatibility across major versions is not provided for now. The protocol definition libraries are not publicly released at this time.

SDK