語言
技術 · GProtocol

GProtocol 協定

GProtocol 定義了應用與節點之間的全部通訊：請求與回應的格式、62 個動作、錯誤怎麼表達，以及哪些欄位只能是密文。

目前版本 8.0.0

傳輸與版本

  • 應用到節點：WebSocket + JSON，欄位統一使用小駝峰命名。
  • 節點之間：libp2p，協定 ID 形如 /gather/message/1.0.0；節點間協定在節點內部實作，不屬於 GProtocol。
  • 版本規則：有破壞性變更就升大版本，小版本只加欄位。登入時帶協定版本，大版本不一致的請求會被拒絕並提示升級。
  • 即時類動作（如正在輸入、通話信令）投遞不到就丟棄，不會存成離線訊息。

請求與回應

requestType
regular 交給節點處理；route 點對點轉送
action
動作路徑，例如 /message/send
requestId
用來把回應和請求對應起來
submitter / receiver
雙方地址；寄件人會被節點替換成已認證的身分
data
業務資料，凡是內容都已在應用端加密
signature
請求簽章
errorKey
錯誤用 key 表示，應用依 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名片、安全碼核對、打賞轉送

協定裡的安全設計

登入

錢包金鑰對「使用者 · 裝置 · 時間戳」簽章，節點只接受很短時間窗內的簽章，並同時檢查協定大版本。

節點身分

應用傳隨機數，節點簽章回傳；應用核對公鑰與節點 ID 一致，並核對營運方歸屬證與發布清單。

離線信箱

信箱標識每天更換；內容用 X25519 封裝，寄件人在封裝裡面；取件和確認都要簽章。

群組

節點只看到匿名的投遞目標和加密的狀態區塊，看不到群名和成員。

檔案

取件憑據由檔案金鑰衍生，節點不保存分享名單。

備份

備份位置由用戶端衍生，寫入要簽章；全網共用的金鑰已經取消。

協定狀態

GProtocol 尚未凍結，上線前大版本仍可能變化，暫不提供跨大版本相容。協定定義庫目前未公開發布。

SDK