语言
技术 · GProtocol

GProtocol 协议

GProtocol 定义了 App 与节点之间的全部通信：请求与响应的格式、62 个动作、错误怎么表达，以及哪些字段只能是密文。

当前版本 8.0.0

传输与版本

  • App 到节点：WebSocket + JSON，字段统一使用小驼峰命名。
  • 节点之间：libp2p，协议 ID 形如 /gather/message/1.0.0；节点间协议在节点内部实现，不属于 GProtocol。
  • 版本规则：有破坏性变更就升大版本，小版本只加字段。登录时带协议版本，大版本不一致的请求会被拒绝并提示升级。
  • 实时类动作（如正在输入、通话信令）投递不到就丢弃，不会存成离线消息。

请求与响应

requestType
regular 交给节点处理；route 点对点转发
action
动作路径，例如 /message/send
requestId
用来把响应和请求对应起来
submitter / receiver
双方地址；发送方会被节点替换成已认证的身份
data
业务数据，凡是内容都已在 App 端加密
signature
请求签名
errorKey
错误用 key 表示，App 按 key 显示本地语言的文案，节点返回的文字不会直接显示给用户

节点眼中的一条消息

这是 App 发给入口节点的一条私聊消息。路由需要的字段是明文，消息内容只是一段密文。

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"
}

示意：字段名与 GProtocol 8.0.0 一致，取值为虚构示例。

14 个模块，62 个动作

已删除的模块不再列出。

模块动作数用途
/user10握手、登录登出、心跳、在线状态、点对点资料交换
/message9发送、确认、拉取离线、已读、正在输入、撤回、编辑、表情回应
/file8分片上传与下载，凭据取件
/call7一对一通话信令、ICE 与中继配置
/friend6好友申请、同意、拒绝、删除、列表
/key6X3DH 预密钥的上传、获取、补充与低量提醒
/group4匿名扇出、加密状态块读写、撤回（节点不托管群）
/push3推送令牌注册、注销与测试
/backup2加密的关系备份与收藏备份
/device2本节点上的活跃会话、踢下线
/node2节点身份证明、节点目录
/card · /security · /tip3名片、安全码核对、打赏转发

协议里的安全设计

登录

钱包密钥对「用户 · 设备 · 时间戳」签名，节点只接受很短时间窗内的签名，并同时检查协议大版本。

节点身份

App 发随机数，节点签名返回；App 核对公钥与节点 ID 一致，并核对运营方归属证与发布清单。

离线信箱

信箱标识每天更换；内容用 X25519 封装，发件人在封装里面；取件和确认都要签名。

群组

节点只看到匿名的投递目标和加密的状态块，看不到群名和成员。

文件

取件凭据由文件密钥派生，节点不保存分享名单。

备份

备份位置由客户端派生，写入要签名；全网共享的密钥已经取消。

协议状态

GProtocol 尚未冻结，上线前大版本仍可能变化，暂不提供跨大版本兼容。协议定义库目前未公开发布。

SDK