KGEX 設計理念

保管核心系統的設計原則、實作與流程

KGEX 是什麼

架構方向階段的整理;「所以」開頭的句子是推論,不是規格原文

KGEX 是 KryptoGO 的保管核心系統:替客戶保管鏈上資產、記客戶的帳、處理入金、出金與公司資產調度,並定期驗證客戶池的鏈上資產是否足以覆蓋對客戶的負債。 第一階段不含交易市場。這一段先講範圍設計原則GCP 上的實作

01 · 範圍

第一階段只做交易所的資金層

範圍是錢包、帳本、出入金、站內轉帳、對帳,以及支撐它們的客戶身份、員工權限與核准。交易與法幣不在範圍內;法遵/風險以決策接口接入(allow/review/reject/freeze),詳細規則與阻擋點待確認。

上面三層不在這套設計裡。分層是本文的示意,不是原文的架構分層。點每一層看說明。

交易層撮合・order book・行情・定價
法幣層入出金・銀行・TWD
合規執行決策接口已定・執行方與規則待定
資金層錢包・帳本・出入金・對帳
點一層

01 · 範圍

資金層的四個部分

資產分成四個池子(未歸集的入金地址也算客戶資產),帳只記對客戶的負債,資金移動由狀態機推進,對帳則逐鏈對齊截止區塊後,按同一種資產合計比較資產是否 ≥ 負債。每一部分對應下面的一個互動區。

錢放在哪客戶/公司 × 熱/冷四個池子。熱端交託管商,冷端員工自己多簽。四個資產池 ↓
帳怎麼記對客戶的負債記在一本只能追加的複式帳裡,餘額是算出來的。Ledger 邊界 ↓
錢怎麼動入金、出金、站內轉帳、公司調度各有狀態機;鏈上事實由自己掃鏈取得。四條流程 ↓
怎麼驗證覆蓋選一個截止時間,每條鏈各取那之前最後一個 finalized block,比客戶池資產是否 ≥ 對客戶負債。對帳流程 ↓

01 · 範圍

客戶資產與公司資產分開保管,只開公司 → 客戶一個方向

不同錢包、不同白名單、不同權限(簽署人可以相同,共用的風險待確認)。公司熱錢包補流動性給客戶池要核准,完成後那筆錢即歸入客戶資產;反方向預設禁止,第一階段不提供一般流程,後台也不顯示。

資金歸屬單向,客戶資產覆蓋的計算才算得清。

客戶
Customer Hot託管商保管,撐出金
Customer Cold3-of-5,至少 85%
公司
Company Hot補流動性、付 gas
Company Cold3-of-5
↑ 公司 → 客戶:需核准↓ 客戶 → 公司:預設禁止
85% 是要監測並自動補足的目標,3-of-5 是第一階段固定的多簽配置
看每個方向經過哪些控制層
Custody & Treasury · Automation

往冷端收是自動的,往熱端放要核准,從冷錢包出款再加一次鏈上 3-of-5 簽名,三道各自計票;客戶 → 公司預設禁止。

客戶資產 對應對客戶之負債 公司自有資產 客戶的外部地址 離開系統,不可回收 入金地址 託管商配發 Customer Hot 跨鏈調度需核准 Customer Cold ≥ 85%・3-of-5 Relayer Wallet 代付 gas Company Hot 跨鏈調度需核准 Company Cold 3-of-5・無比例要求 自動歸集 自動 sweep 核准 + 3-of-5 客戶提款・超過門檻需核准 gas 自動撥補 自動 sweep 核准 + 3-of-5 Funding Gas Funding 需核准 sweep gas 限額內自動 客戶 → 公司 不予授權
自動執行 需 KGEX 核准 核准 + 鏈上 3-of-5 簽名 不予授權
點選箭頭展開對應說明

02 · 設計的三層

本文把設計分三類:不變量、實作、政策與配置

不變量必須維持的規則,實作怎麼換都不能破。點開三條原則
實作在 GCP 上實現不變量的方式。可替換。點開 GCP 架構
政策與配置第一階段的選擇:入金 confirmed 即入帳、85% 冷比例、3000U/10000U 初始門檻、3-of-5、LINE Pay 登入。要改得走各自的核准流程。點開入金政策

每類事實以誰為準

Hub §7 · Source of truth

四類事實各有一個權威來源,來源分開也代表寫入權限分開。第五列是託管商的回報:用來追蹤提交與執行,不能替代前四者。

客戶餘額
對客戶之負債
Ledger 的 immutable journal。複式分錄不可竄改,餘額係 journal 的投影, 而非可獨立寫入的欄位。任何模組欲產生帳務效果,一律經 Ledger command,不得逕行異動餘額。
鏈上事實
與錢包餘額
KG Chain Indexer 與 RPC。涵蓋每個 block 的 confirmed、finalized、reorged 事實, 以及受影響地址的 per-block 餘額。
交易生命週期
業務狀態
Money Movement 與 Treasury 各自的 aggregate。 business state 與鏈上狀態分屬兩套,何時推進由各自的 state machine 認定。
核准紀錄
與授權軌跡
Approval Core。保存 proposal、每一票 decision、comment、時間與執行結果; 持有 subject reference、申請人、票數與每票決定;domain payload 與執行仍歸各 domain owner。
託管商回報
不具真相地位
不構成真相,僅為 execution evidence。 provider 回覆 approved 不等同 KGEX 已核准,回覆 failed 亦不等同鏈上未發生。 它不能單獨證明鏈上成功,也不能證明 KGEX 已核准。

四條主流程

Hub §6 · Main End-to-End Flows

四條流程逐步播放。每一步看四條軌道怎麼變:鏈上事實、Ledger、流程狀態、客戶看到什麼。

文件原句

這條流程會出什麼事

模組怎麼溝通

Hub §5 · Communication Patterns

模組怎麼呼叫、哪些資料一起提交、哪些工作非同步執行,是三個不同的問題,可以組合。整個系統是一個 codebase 的 modular monolith,所以前兩者做得到。

同一個 DB transaction
必須同時成立、不能有中間狀態的事,一起 commit。
出金建立 + 可用→鎖定 + 待執行任務
入金 confirmed + 入帳 + 暫扣
最後一票 + 核准 + 執行任務
同一個 process 內的 command
要改別的模組的資料,呼叫它的 command,不碰它的表。同步呼叫;需要一起成立時,就把它放進上一層的同一個 transaction。
Money Movement 請 Ledger 鎖定/入帳/扣除
Custody 把 Treasury 操作送給 Approval
Approval 最後一票啟動 domain 執行
先落地,再非同步送
要碰外部系統,或要把鏈上事實廣播出去:先把意圖寫進自己的 DB,再由 Cloud Tasks(派工作)/Pub/Sub(傳鏈上事實)送。投遞可重複、接收端去重、crash 後從 DB 續跑;外部結果不明時先查,不盲目重送。
配發入金地址、向託管商送單、執行 Treasury 操作
Indexer 發出 block confirmed/finalized/reorged

兩條不變的規則:跨模組的寫入只能經過 owner 的 command,沒有共用可寫的 repository;任何外部 side effect 之前,本地意圖先 commit,重試要冪等、逾時要查證。

看 48 條線的全圖,依規則篩選

模組邊界

Hub §4 · Business Module Boundaries

切分依據是各類事實由誰負責:Money Movement 決定流程進度,Ledger 產生帳務效果,Custody 管資產與執行證據,Approval 保存人員決策,Finance 驗證資產與負債是否一致。它們可以在同一個 transaction 協作,但不能互相直接改表。