最近我接手了一個(gè)比較有意思的適配任務(wù)把一個(gè) Flutter 生態(tài)里常用的 TON 鏈上交互庫(kù) ton_dart 搬到鴻蒙應(yīng)用里還要在實(shí)際場(chǎng)景中跑通資產(chǎn)查詢、轉(zhuǎn)賬還有 TON 治理投票的鏈路。ton_dart 這個(gè)庫(kù)在 Dart 世界里算是 TON 相關(guān)功能最全的三方庫(kù)之一錢(qián)包、Jetton、NFT、合約交互都有覆蓋可它畢竟是跑在標(biāo)準(zhǔn) Dart VM 上的到了鴻蒙原生環(huán)境里網(wǎng)絡(luò)請(qǐng)求、密鑰生成、消息簽名這些底子都得重新對(duì)接。這篇文章就是把我在模擬項(xiàng)目里真實(shí)趟過(guò)的鴻蒙化路徑、改造成本、關(guān)鍵代碼和踩坑點(diǎn)完整寫(xiě)出來(lái)適合要在鴻蒙上做 Web3 錢(qián)包、鏈上治理工具或者資產(chǎn)看板的開(kāi)發(fā)者直接參考。這套適配的核心思路不是把 ton_dart 重寫(xiě)一遍而是做一層“能力替換層”。鴻蒙側(cè)沒(méi)有 Dart VM 對(duì)原生插件的那套自動(dòng)綁定但 Flutter 工程可以通過(guò) MethodChannel/Pigeon 和鴻蒙原生代碼通信所以我們可以把 ton_dart 依賴(lài)原生能力的部分抽出來(lái)在鴻蒙側(cè)用系統(tǒng)級(jí)的 Crypto 和網(wǎng)絡(luò)能力補(bǔ)上把純 Dart 的協(xié)議邏輯保留下來(lái)。這樣既保住了 ton_dart 里成熟的 TON 消息構(gòu)造、BOC 序列化、地址解析邏輯又讓它在鴻蒙上真正跑得動(dòng)。下面我從方案選型開(kāi)始一步步拆。1. 項(xiàng)目背景與適配思路拆解1.1 ton_dart 到底解決了什么問(wèn)題如果你對(duì) TON 鏈上開(kāi)發(fā)有了解就知道這個(gè)生態(tài)里最成熟的開(kāi)發(fā)生態(tài)其實(shí)是 TypeScript其次有 Python SDKDart 這邊能用的完整客戶端庫(kù)并不多。ton_dart 是這個(gè)生態(tài)里少有的全能型選擇它支持從助記詞生成、HD 錢(qián)包派生到賬戶余額查詢、Jetton 代幣解析、NFT 列表查詢?cè)俚綐?gòu)造并發(fā)送各種類(lèi)型的 TON 消息甚至能對(duì)接鏈上治理相關(guān)的提案數(shù)據(jù)和投票消息。對(duì)于 Flutter 團(tuán)隊(duì)來(lái)說(shuō)要在同一套代碼里同時(shí)覆蓋 iOS、Android 和鴻蒙把業(yè)務(wù)邏輯寫(xiě)在 Dart 層是最舒服的。ton_dart 的存在意味著合約編解碼、地址轉(zhuǎn)換這些純邏輯可以全部復(fù)用不需要在每個(gè)平臺(tái)上各自寫(xiě)一套 TON 協(xié)議的實(shí)現(xiàn)。我在這次適配里最看重的是它的“消息構(gòu)造”能力。TON 的鏈上操作本質(zhì)上是把一筆交易或一條消息編碼成二進(jìn)制格式然后廣播到網(wǎng)絡(luò)里去。這個(gè)過(guò)程涉及斷言Cell、引用Ref、BOC 字節(jié)流、TL-B 序列化規(guī)則手動(dòng)實(shí)現(xiàn)一遍很容易出錯(cuò)。ton_dart 把這套東西封裝成了比較干凈的 API我們只需要傳遞業(yè)務(wù)參數(shù)就能得到打包好的消息體。所以適配的第一原則出現(xiàn)了凡是不依賴(lài)平臺(tái)的純 Dart 邏輯原樣保留凡是依賴(lài)平臺(tái)的堅(jiān)決替換。1.2 鴻蒙平臺(tái)對(duì) Flutter 插件的真實(shí)限制鴻蒙應(yīng)用目前走的 Flutter 集成路徑和傳統(tǒng) Android/iOS 有一個(gè)關(guān)鍵差別Dart 側(cè)不能直接調(diào)用常見(jiàn)的原生插件自動(dòng)生成的膠水代碼因?yàn)轼櫭傻?Flutter 引擎對(duì)外提供的通道是拍平過(guò)的平臺(tái)通道。也就是說(shuō)你在 Android 上常用的MethodChannel、EventChannel、Pigeon這些機(jī)制在鴻蒙上同樣存在只是對(duì)端的實(shí)現(xiàn)語(yǔ)言變成了 ArkTS不再是 JVM 或 Objective-C。ton_dart 原樣跑在鴻蒙上的最大阻礙有三個(gè)。第一是網(wǎng)絡(luò)庫(kù)ton_dart 默認(rèn)用的 Darthttp包在鴻蒙上雖然能發(fā)請(qǐng)求但在長(zhǎng)連接、證書(shū)校驗(yàn)和連接池復(fù)用這些環(huán)節(jié)上和鴻蒙系統(tǒng)網(wǎng)絡(luò)棧有兼容差異遇到復(fù)雜鏈上響應(yīng)時(shí)容易出奇怪現(xiàn)象。第二是安全隨機(jī)數(shù)和密鑰管理助記詞、私鑰這種東西如果只存在 Dart 側(cè)的內(nèi)存里對(duì)錢(qián)包應(yīng)用來(lái)說(shuō)是不及格的。第三是簽名算法TON 鏈上主要用 Ed25519 做消息簽名鴻蒙系統(tǒng)的密鑰管理與加解密框架原生支持這個(gè)算法這給了我們用系統(tǒng)能力替代純 Dart 實(shí)現(xiàn)的絕佳條件。1.3 三方適配方案選型對(duì)比我在正式動(dòng)手前對(duì)比過(guò)三條路線。第一是全量重寫(xiě)在鴻蒙側(cè)用 ArkTS 直接實(shí)現(xiàn) TON 錢(qián)包和治理邏輯好處是沒(méi)有跨語(yǔ)言的橋接損耗但壞處是工作量大而且要重新處理地址、BOC、Jetton 元數(shù)據(jù)這些繁瑣協(xié)議維護(hù)成本極高。第二是純 Flutter 層硬跑直接把 ton_dart 放進(jìn)工程只在鴻蒙側(cè)補(bǔ)網(wǎng)絡(luò)權(quán)限這條路最快但只適合簡(jiǎn)單查詢一旦涉及簽名和安全的密鑰存儲(chǔ)就基本應(yīng)用不了。第三是橋接式適配保留 ton_dart 的協(xié)議層把密鑰生成、簽名、網(wǎng)絡(luò)請(qǐng)求、安全存儲(chǔ)這四類(lèi)能力橋接到鴻蒙原生實(shí)現(xiàn)。我選了第三種理由很直接它能最大程度復(fù)用 ton_dart 里成熟的純 Dart 邏輯又把最需要平臺(tái)能力的地方交給了鴻蒙系統(tǒng)框架。橋接的代碼量其實(shí)不多核心就是幾個(gè)方法通道和一套參數(shù)約定。相比之下全量重寫(xiě)的風(fēng)險(xiǎn)高且收益低而純 Flutter 硬跑又扛不住真實(shí)錢(qián)包業(yè)務(wù)對(duì)安全性的要求。適配完成后的整體架構(gòu)可以簡(jiǎn)單概括為Dart 側(cè)跑協(xié)議鴻蒙側(cè)跑系統(tǒng)能力中間過(guò)橋傳二進(jìn)制。2. 前期準(zhǔn)備與工程改造要點(diǎn)2.1 基線工程與依賴(lài)落地我在模擬項(xiàng)目里用的基線是鴻蒙系統(tǒng)當(dāng)前主流的 Flutter 混合工程結(jié)構(gòu)也就是在鴻蒙原生工程里掛一個(gè) Flutter 模塊Flutter 側(cè)保持標(biāo)準(zhǔn)的 pub 依賴(lài)管理。ton_dart 目前發(fā)布在 pub 倉(cāng)庫(kù)上直接在pubspec.yaml里聲明依賴(lài)就能拉下來(lái)。不過(guò)要注意版本收斂問(wèn)題ton_dart 對(duì) Dart SDK 版本有要求如果你項(xiàng)目的 Flutter SDK 太老要先升級(jí) Flutter 版本再跑依賴(lài)解析。另外要提醒一點(diǎn)因?yàn)?ton_dart 會(huì)間接依賴(lài)一些常見(jiàn)的 Dart 包在部分網(wǎng)絡(luò)環(huán)境下依賴(lài)?yán)?huì)比較慢建議提前把 pub 源的鏡像地址配好或者把整包離線緩存下來(lái)。工程落地時(shí)還要在鴻蒙側(cè)的模塊描述文件里把網(wǎng)絡(luò)權(quán)限加上否則后續(xù)所有鏈上請(qǐng)求都會(huì)被系統(tǒng)直接攔截而且這個(gè)權(quán)限要在真機(jī)調(diào)試前就確認(rèn)不然排查起來(lái)很容易繞彎路。2.2 依賴(lài)模塊的裁剪與適配工作量對(duì)照拿到 ton_dart 源碼后我沒(méi)有急著改代碼而是先把它經(jīng)歷的功能模塊摸了一遍用表格把“哪些可以直接用”“哪些需要替換”理清楚。這個(gè)動(dòng)作能幫助團(tuán)隊(duì)快速估算工時(shí)也避免在適配過(guò)程中釜底抽薪改動(dòng)核心模型。模塊ton_dart 原實(shí)現(xiàn)鴻蒙側(cè)問(wèn)題點(diǎn)適配方式地址解析與格式化純 Dart 邏輯無(wú)明顯問(wèn)題原樣保留BOC Cell 序列化/反序列化純 Dart 實(shí)現(xiàn)大數(shù)據(jù)量下性能一般但功能正確保留長(zhǎng)消息可在原生側(cè)拼接BIP39 助記詞Dart 隨機(jī)源與詞表隨機(jī)源安全性不夠鴻蒙原生生成并返回Dart 復(fù)用詞表私鑰與助記詞存儲(chǔ)內(nèi)存對(duì)象沒(méi)有系統(tǒng)級(jí)安全存儲(chǔ)鴻蒙 KeyStore 能力橋接Ed25519 簽名Dart 或依賴(lài)包實(shí)現(xiàn)需要與鴻蒙密鑰庫(kù)打通鴻蒙 Crypto 框架簽名網(wǎng)絡(luò)請(qǐng)求 Toncenter APIDart http連接池、證書(shū)鏈、網(wǎng)絡(luò)策略差異鴻蒙原生網(wǎng)絡(luò)棧接管這個(gè)表還有一個(gè)隱藏作用就是團(tuán)隊(duì)里如果有人想先做一部分可以照著表格劃分任務(wù)邊界。比如“地址解析”和“BOC 序列化”這兩塊完全不依賴(lài)平臺(tái)誰(shuí)都可以先做而“簽名”和“安全存儲(chǔ)”必須和鴻蒙側(cè)一起聯(lián)調(diào)應(yīng)該安排到后期集中攻堅(jiān)。2.3 權(quán)限聲明與安全存儲(chǔ)設(shè)計(jì)在鴻蒙工程里網(wǎng)絡(luò)權(quán)限需要在前臺(tái)模塊的配置文件中顯式聲明。如果你在調(diào)試時(shí)所有鏈上請(qǐng)求都報(bào)系統(tǒng)錯(cuò)誤第一件事就是檢查這個(gè)權(quán)限是否已經(jīng)添加。除了網(wǎng)絡(luò)權(quán)限錢(qián)包類(lèi)的應(yīng)用還在乎一個(gè)底線問(wèn)題助記詞不能被普通內(nèi)存持有太久。ton_dart 原生的做法是讓助記詞和私鑰以 Dart 對(duì)象形式存在這在普通 App 里問(wèn)題不大但在鏈上資產(chǎn)管理的場(chǎng)景里風(fēng)險(xiǎn)偏高。我的處理是把助記詞的生成和私鑰的加載都收口到鴻蒙原生側(cè)交給系統(tǒng)安全能力托管Dart 側(cè)只保留一個(gè)不落盤(pán)的會(huì)話句柄。簽名時(shí)由鴻蒙側(cè)根據(jù)句柄找到密鑰材料在系統(tǒng)安全環(huán)境內(nèi)完成簽名Dart 側(cè)只拿到簽名結(jié)果。這樣即使 Dart 層被攻擊私鑰材料也不會(huì)暴露完整。當(dāng)然這增加了一層橋接代碼但值得。3. 核心適配步驟與代碼實(shí)現(xiàn)3.1 用 Pigeon 建立穩(wěn)定的橋接通道如果方法通道的調(diào)用參數(shù)只有三五個(gè)少得可憐的數(shù)量用 MethodChannel 手寫(xiě)沒(méi)有問(wèn)題。但 ton_dart 橋上涉及的參數(shù)會(huì)包括助記詞、簽名輸入、交易消息、網(wǎng)絡(luò)返回體類(lèi)型復(fù)雜且數(shù)量多這時(shí)候我建議直接用官方推薦的橋接代碼生成工具 Pigeon把接口定義成類(lèi)型安全的 Dart 抽象類(lèi)再自動(dòng)生成鴻蒙側(cè)的存根代碼。這樣無(wú)論是 Dart 側(cè)還是 ArkTS 側(cè)都變得可控得多不用手寫(xiě)一長(zhǎng)串字符串類(lèi)型的 method 名和參數(shù)字典。一個(gè)容易被忽略的點(diǎn)是TON 的業(yè)務(wù)數(shù)據(jù)大量是二進(jìn)制格式比如打包好的 BOC 字節(jié)流不是普通 UTF-8 字符串。所以橋接協(xié)議我建議設(shè)計(jì)成以Uint8List為主、String為輔Dart 側(cè)的Uint8List到 ArkTS 側(cè)的Uint8Array有現(xiàn)成的轉(zhuǎn)換規(guī)則但一定要避免中間過(guò)程隱式轉(zhuǎn)成字符串又轉(zhuǎn)回來(lái)的“假二進(jìn)制”操作否則任何一次轉(zhuǎn)碼失誤都會(huì)導(dǎo)致 BOC 數(shù)據(jù)錯(cuò)位最終在鏈上解析成一個(gè)完全不同的消息。3.2 BIP39 助記詞與密鑰生成的鴻蒙化實(shí)現(xiàn)TON 的錢(qián)包助記詞遵循 BIP39 標(biāo)準(zhǔn)詞匯表生成流程是先用安全隨機(jī)源取 128/256 位熵加校驗(yàn)位后映射成 12/24 個(gè)單詞。ton_dart 里已經(jīng)有一整套詞表文件和校驗(yàn)算法這部分純 Dart 不需要?jiǎng)?。真正要換的是“安全隨機(jī)源”這一環(huán)因?yàn)?Dart 側(cè)的隨機(jī)源強(qiáng)度在不同平臺(tái)上表現(xiàn)不一致而生成助記詞是資產(chǎn)安全的第一步必須用系統(tǒng)級(jí)安全隨機(jī)數(shù)。在鴻蒙側(cè)實(shí)現(xiàn)時(shí)我用的是一個(gè)非常樸素的流程生成隨機(jī)熵 - 傳給 Dart 側(cè)的 ton_dart 詞表邏輯做校驗(yàn)位補(bǔ)齊和單詞映射。Dart 側(cè)拿到的是原始熵字節(jié)也就是 16 個(gè)或 32 個(gè)隨機(jī)數(shù)然后調(diào)用 ton_dart 里現(xiàn)成的recoverFromMnemonic和generateMnemonic相似的內(nèi)部邏輯。這里要注意不要用 Dart 側(cè)自己生成的隨機(jī)數(shù)去生成助記詞否則即使詞表邏輯對(duì)隨機(jī)源強(qiáng)度也不過(guò)關(guān)。為了保險(xiǎn)我在鴻蒙側(cè)還加了一次最小熵校驗(yàn)如果系統(tǒng)返回值全零或者固定模式就直接拒絕繼續(xù)。3.3 Ed25519 簽名鏈路的橋接與驗(yàn)簽TON 鏈上簽名用的是 Ed25519 算法而且簽名對(duì)象通常不是普通的可讀文本而是“消息 Cell 的哈?！?。在 ton_dart 的調(diào)用鏈里業(yè)務(wù)方會(huì)先構(gòu)造一個(gè) Cell取出它的哈希值再對(duì)該哈希做 Ed25519 簽名最后把簽名塞回消息的外層結(jié)構(gòu)中。鴻蒙側(cè)做簽名時(shí)我選擇把密鑰材料托管在系統(tǒng)安全能力里Dart 側(cè)只傳一個(gè)“密鑰句柄”和“待簽名數(shù)據(jù)哈?！?。ArkTS 側(cè)收到請(qǐng)求后調(diào)用系統(tǒng)框架的 Ed25519 簽名接口返回 64 字節(jié)的簽名結(jié)果。這里特別容易出錯(cuò)的是字節(jié)序和哈希長(zhǎng)度Ed25519 簽名輸入必須是 32 字節(jié)的原文哈希如果你不小心把哈希轉(zhuǎn)成了字符串再轉(zhuǎn)回二進(jìn)制長(zhǎng)度和內(nèi)容都可能變。簽名結(jié)果也要原樣傳給 Dart 側(cè)不能經(jīng)過(guò) JSON 序列化丟精度。為了驗(yàn)證橋接后的簽名是否可靠我在本地做了雙端驗(yàn)簽Dart 側(cè)用同一個(gè) Elliptic 曲線算法庫(kù)驗(yàn)一遍簽名鴻蒙側(cè)再驗(yàn)一遍兩邊結(jié)果必須一致。這個(gè)測(cè)試看起來(lái)簡(jiǎn)單卻能提前避免很多上鏈后“簽名無(wú)效”的悲慘事故。3.4 網(wǎng)絡(luò)層接管與消息廣播ton_dart 默認(rèn)的網(wǎng)絡(luò)請(qǐng)求能力在普通 Flutter 工程里是夠用的但在鴻蒙化之后我更建議把網(wǎng)絡(luò)請(qǐng)求也統(tǒng)一收口到鴻蒙原生側(cè)來(lái)做。原因有幾點(diǎn)鴻蒙系統(tǒng)網(wǎng)絡(luò)棧更擅長(zhǎng)處理系統(tǒng)級(jí)證書(shū)策略鏈上接口經(jīng)常返回較大的 JSON 數(shù)據(jù)原生側(cè)解析效率更好最重要的一點(diǎn)是TON 網(wǎng)關(guān)接口要求 POST 二進(jìn)制 BOC 數(shù)據(jù)內(nèi)容類(lèi)型和長(zhǎng)度控制得非常嚴(yán)格原生側(cè)更容易確保請(qǐng)求頭的準(zhǔn)確組裝。我在鴻蒙側(cè)封裝了一個(gè)通用的請(qǐng)求方法專(zhuān)門(mén)負(fù)責(zé)和 TON 生態(tài) HTTP API 網(wǎng)關(guān)打交道的 POST/GET 調(diào)用。Dart 側(cè)需要發(fā)交易時(shí)傳入已經(jīng)在 Dart 層構(gòu)造好的 BOC 字節(jié)流鴻蒙側(cè)追加 API Key如果有和 Content-Type發(fā)起網(wǎng)絡(luò)請(qǐng)求后把響應(yīng)字節(jié)原樣返回 Dart。這樣 Dart 側(cè)保持對(duì) ton_dart API 的調(diào)用習(xí)慣原生側(cè)掌控連接生命周期和錯(cuò)誤重試。實(shí)測(cè)下來(lái)這種拆分比 Dart 直連穩(wěn)定得多尤其在弱網(wǎng)切換場(chǎng)景下表現(xiàn)差距尤為明顯。4. 資產(chǎn)掌控實(shí)戰(zhàn)查詢、轉(zhuǎn)賬與代幣識(shí)別4.1 地址解析與余額查詢資產(chǎn)操作的第一步是余額查詢。TON 的地址有兩種表示友好地址和非友好地址。日常用戶看到的是以EQ或UQ開(kāi)頭的友好地址但內(nèi)部編碼和合約間通信有時(shí)需要非友好形式。ton_dart 自帶地址類(lèi)的解析和轉(zhuǎn)換這部分完全可以直接保留。余額查詢走的是 TON 生態(tài)通用的 HTTP API 網(wǎng)關(guān)請(qǐng)求參數(shù)是地址返回結(jié)果里有一個(gè)balance字段單位是 nanoTON也就是 10 的 9 次方分之一 TON。換算關(guān)系并不復(fù)雜但要提醒的是TON 的精度是 9 位小數(shù)很多新手會(huì)把 nanoTON 當(dāng)成 18 位精度來(lái)處理導(dǎo)致展示金額差出 10 的 9 次方倍這在資產(chǎn)展示場(chǎng)景里是非常嚴(yán)重的低級(jí)錯(cuò)誤。我在橋接層里順手加了一個(gè)保留 9 位精度的小數(shù)格式化工具避免上游返回的字符串在 JavaScript 或 ArkTS 的浮點(diǎn)轉(zhuǎn)換里丟精度。鏈上余額查詢還有個(gè)細(xì)節(jié)剛部署的錢(qián)包合約和已經(jīng)收過(guò)資產(chǎn)的錢(qián)包初始狀態(tài)不一樣。未激活的錢(qián)包地址在部分網(wǎng)關(guān)接口上會(huì)返回空余額或者空交易列表這種情況會(huì)在 UI 上表現(xiàn)為“查不到資產(chǎn)”其實(shí)是合約尚未激活。正確的做法是把它當(dāng)作余額為 0 處理并提供“首次轉(zhuǎn)入激活”的提示。4.2 Jetton 代幣與錢(qián)包內(nèi)資產(chǎn)識(shí)別除了原生 TON 幣鏈上資產(chǎn)里更多的是 Jetton 代幣你可以把它理解為 TON 生態(tài)里的可替換代幣標(biāo)準(zhǔn)。ton_dart 提供了 Jetton 相關(guān)的錢(qián)包和元數(shù)據(jù)解析邏輯拿到一個(gè) Jetton 錢(qián)包地址后可以向鏈上合約發(fā)起一個(gè)只讀查詢拿到它的余額和掛在元數(shù)據(jù)里的代幣符號(hào)、精度和小數(shù)位數(shù)。這里最容易踩坑的是元數(shù)據(jù)格式。Jetton 的元數(shù)據(jù)可能是鏈上全量存儲(chǔ)也可能只是一個(gè)指向中心化服務(wù)器的鏈接即 off-chain metadata。如果元數(shù)據(jù)是 off-chain 的那么解析時(shí)要額外發(fā)一次 HTTP 請(qǐng)求去拉取 JSON而且這個(gè)請(qǐng)求在鴻蒙環(huán)境下同樣要走網(wǎng)絡(luò)權(quán)限和證書(shū)棧。我建議把元數(shù)據(jù)解析單獨(dú)封裝成一個(gè)可以容錯(cuò)的模塊拿到必要字段就展示拿不到就顯示默認(rèn)占位符而不是讓整個(gè)資產(chǎn)列表因某一個(gè)代幣元數(shù)據(jù)異常而卡死。在資產(chǎn)列表中我還把所有代幣的余額統(tǒng)一轉(zhuǎn)換成以 TON 為單位的字符串來(lái)展示內(nèi)部用整數(shù)類(lèi)型保留精度。浮點(diǎn)型在跨語(yǔ)言橋接里真的不能碰哪怕一次毫秒級(jí)的精度偏差在資產(chǎn)核對(duì)時(shí)都會(huì)變成可信度災(zāi)難。4.3 轉(zhuǎn)賬消息構(gòu)造與廣播在 ton_dart 里構(gòu)造一筆 TON 轉(zhuǎn)賬本質(zhì)上是構(gòu)造一條內(nèi)部消息指定接收地址、轉(zhuǎn)賬金額、附加備注再把它塞進(jìn)發(fā)送方錢(qián)包合約的 outgoing message 中整個(gè)消息經(jīng)過(guò)簽名和打包變成一個(gè)可以被網(wǎng)關(guān)接受的 BOC。這段邏輯屬于 ton_dart 的精華適配時(shí)完全保留我做的只是把簽名和網(wǎng)絡(luò)廣播兩個(gè)環(huán)節(jié)替換成鴻蒙能力。一筆轉(zhuǎn)賬消息的完整調(diào)用鏈大致是// 構(gòu)造內(nèi)部消息 final internalMsg InternalMessage( dest: destAddress, value: TonCoins.fromNano(amountNano), body: TextMessageBody(text: memo), ); // 用錢(qián)包合約邏輯添加簽名 final wallet WalletV5(secretKey: secretKey); final externalMessage await wallet.createTransferMessage( messages: [internalMsg], seqno: seqno, ); // 序列化為 BOC final boc externalMessage.toBoc();拿到boc字節(jié)后Dart 側(cè)通過(guò)橋接層把它交給鴻蒙原生由原生側(cè)以 POST 方式廣播到 TON 網(wǎng)關(guān)接口提交成功后網(wǎng)關(guān)會(huì)返回交易哈希。注意TON 的交易廣播是“異步確認(rèn)”的接口返回哈希只代表網(wǎng)絡(luò)接受了這個(gè)包不代表交易已經(jīng)上鏈UI 層面必須區(qū)分“已廣播”和“已上鏈”兩種狀態(tài)否則用戶會(huì)誤以為轉(zhuǎn)賬一定成功。5. TON 治理實(shí)戰(zhàn)精密提案與鏈上投票5.1 從技術(shù)視角理解 TON 鏈上治理說(shuō)到 TON 治理很多人第一反應(yīng)是“和現(xiàn)實(shí)世界里的投票有什么關(guān)系”。其實(shí)鏈上治理完全是一個(gè)技術(shù)流程網(wǎng)絡(luò)的重要參數(shù)、協(xié)議升級(jí)、提案的執(zhí)行都由一組智能合約定義持幣者或驗(yàn)證者通過(guò)向這些合約發(fā)送特定編碼的消息來(lái)表達(dá)自己的態(tài)度。對(duì)普通用戶來(lái)說(shuō)參與治理的動(dòng)作往往就是“對(duì)某個(gè)提案投一票”而這一票本質(zhì)上是一條結(jié)構(gòu)嚴(yán)格的消息。這套機(jī)制天然符合“鴻蒙級(jí)鏈上專(zhuān)家”的主題。一個(gè)真正有用的鴻蒙錢(qián)包不應(yīng)該只做轉(zhuǎn)賬還應(yīng)該讓用戶在手機(jī)端直接讀取提案、構(gòu)造投票消息、完成簽名和鏈上提交。ton_dart 對(duì)這部分的支持主要集中在 Cell 構(gòu)造和消息簽名上而治理提案的讀取則依賴(lài)鏈上數(shù)據(jù)接口和合約狀態(tài)解析。5.2 提案讀取與狀態(tài)解析讀取治理提案時(shí)一般有兩個(gè)數(shù)據(jù)來(lái)源一是鏈上合約存儲(chǔ)的提案數(shù)據(jù)二是索引服務(wù)整理的提案列表。前者更原始后者更友好。我的做法是在 Dart 側(cè)用 ton_dart 的合約調(diào)用封裝請(qǐng)求鏈上提案狀態(tài)再把返回的 Cell 數(shù)據(jù)映射成結(jié)構(gòu)化的提案對(duì)象。提案對(duì)象至少包含提案編號(hào)、提案哈希、經(jīng)過(guò)時(shí)間、投票狀態(tài)、相關(guān)合約地址這些字段。解析過(guò)程中最容易出問(wèn)題的是“提案編號(hào)”和“提案哈希”的類(lèi)型處理。它們可能是大整數(shù)或者二進(jìn)制哈希跨語(yǔ)言傳輸時(shí)如果走 JSON 字符串接口一定要明確規(guī)定編碼格式我用的是小端十六進(jìn)制字符串統(tǒng)一表示兩端各自解析避免出現(xiàn)“0x 到底要不要帶”之類(lèi)的低級(jí)分叉。另外提案投票窗口是有時(shí)間限制的鏈上判斷是否在窗口內(nèi)完全依賴(lài)時(shí)間戳。時(shí)區(qū)換算這類(lèi)問(wèn)題在鴻蒙原生側(cè)有時(shí)會(huì)受系統(tǒng)時(shí)區(qū)設(shè)置影響我建議統(tǒng)一使用 UTC 時(shí)間戳在 Dart 側(cè)做窗口判斷不要在原生側(cè)依賴(lài)本地時(shí)區(qū)字符串。5.3 投票消息構(gòu)造與簽名上鏈投票消息的構(gòu)造邏輯可以概括成三步把投票意向編碼進(jìn)一個(gè) Cell用簽名密鑰對(duì)該 Cell 的哈希做 Ed25519 簽名再把簽名和消息主體一起打包成外發(fā)消息。ton_dart 里已經(jīng)提供了通用的 Cell 構(gòu)造方法我們只需要按具體治理提案的規(guī)范填字段。為了節(jié)省你們查文檔的時(shí)間我整理了一個(gè)通用的投票流程偽代碼// 填入投票目標(biāo)合約地址 final targetAddress Address.parse(proposalContractAddress); // 構(gòu)造投同意票的行為體 final voteCell beginCell() .storeUint(voteOptionCode, 32) // 投票選項(xiàng)編碼 .storeUint(proposalId, 64) // 提案編號(hào) .storeAddress(walletAddress) // 投票人地址 .endCell(); // 用錢(qián)包簽名并在外層包裝 final signedCell await signCell(voteCell); final externalMessage await wallet.createTransferMessage( messages: [ InternalMessage( dest: targetAddress, value: TonCoins.fromNano(voteFeeNano), body: signedCell, ), ], seqno: seqno, );這里有個(gè)實(shí)戰(zhàn)心得提案合約往往對(duì)消息體有嚴(yán)格格式要求任何字段順序錯(cuò)位都可能導(dǎo)致鏈上解析失敗而鏈上錯(cuò)誤往往不會(huì)給出明確的“字段錯(cuò)位”提示只會(huì)顯示一個(gè)通用的失敗狀態(tài)。所以務(wù)必在公司內(nèi)部側(cè)提供一個(gè)“解碼回顯”的調(diào)試工具把構(gòu)造好的消息再?gòu)?BOC 反解回字段文本肉眼確認(rèn)沒(méi)有問(wèn)題再?gòu)V播。我在模擬項(xiàng)目里就是靠這個(gè)工具定位了好幾處字段順序的問(wèn)題。投票上鏈之后還可以通過(guò)提案合約的只讀接口查詢投票結(jié)果權(quán)重。這個(gè)過(guò)程同樣可以封裝成鴻蒙應(yīng)用里的一個(gè)獨(dú)立模塊用戶投完票立刻能看到當(dāng)前累計(jì)結(jié)果體驗(yàn)會(huì)比單純的廣播返回好很多。這種“簽名-提交-回讀”的閉環(huán)才是把一個(gè)普通錢(qián)包升級(jí)成鏈上治理工具的關(guān)鍵。6. 常見(jiàn)問(wèn)題與排查技巧實(shí)錄6.1 高頻問(wèn)題速查表適配過(guò)程中踩過(guò)的坑五花八門(mén)我整理了一個(gè)高頻問(wèn)題對(duì)照表如果你在實(shí)操中也遇到類(lèi)似現(xiàn)象可以直接照著查。現(xiàn)象根因解決辦法依賴(lài)解析失敗ton_dart 版本與本地 Dart SDK 不匹配先升級(jí) Flutter/Dart 基線再重新 pub get廣播 BOC 時(shí)報(bào)數(shù)據(jù)無(wú)效跨語(yǔ)言傳二進(jìn)制時(shí)被轉(zhuǎn)成字符串丟字節(jié)橋接層全程使用字節(jié)數(shù)組禁止中間字符串化簽名結(jié)果驗(yàn)簽失敗簽名輸入不是 32 字節(jié)原始哈希檢查取哈希流程確認(rèn)結(jié)果是 Uint8List(32)余額顯示差 10^9 倍精度單位誤當(dāng) 18 位處理統(tǒng)一按 nanoTON 解析保留 9 位小數(shù)助記詞生成后無(wú)法導(dǎo)入隨機(jī)熵沒(méi)有通過(guò)安全隨機(jī)源產(chǎn)生固定使用鴻蒙原生隨機(jī)數(shù)為熵源提案投票一直失敗消息字段順序或類(lèi)型編碼不一致構(gòu)造后先解碼回顯再用測(cè)試網(wǎng)驗(yàn)證網(wǎng)絡(luò)請(qǐng)求偶發(fā)超時(shí)Dart http 連接池與鴻蒙網(wǎng)絡(luò)棧兼容問(wèn)題改由鴻蒙原生網(wǎng)絡(luò)棧統(tǒng)一發(fā)起網(wǎng)絡(luò)請(qǐng)求這張表在我的適配筆記里作用非常大相當(dāng)于一份速查清單每次聯(lián)調(diào)出現(xiàn)異常時(shí)我基本都先用這個(gè)清單排除掉最基礎(chǔ)的問(wèn)題再深入到具體的協(xié)議細(xì)節(jié)里。6.2 三條值得記住的避坑經(jīng)驗(yàn)第一不要試圖在 Flutter 的 isolate 里直接消費(fèi) ton_dart 的完整 BOC 解析能力去處理超大的鏈上消息。Dart isolate 的線程模型和鴻蒙側(cè)的原生線程調(diào)度方式存在差異大對(duì)象在 isolate 間復(fù)制時(shí)會(huì)有不可控的延遲和內(nèi)存峰值。對(duì)于消息構(gòu)造、簽名這類(lèi)高頻且對(duì)延遲敏感的操作盡量保持在主 Isolate 或者原生側(cè)完成不要為了“不卡 UI”而盲目丟給后臺(tái) isolate。第二字節(jié)序問(wèn)題比想象中更陰險(xiǎn)。TON Cell 里很多字段按位存儲(chǔ)跨語(yǔ)言讀取時(shí)Bit 的排列順序和字節(jié)序不是同一個(gè)概念。我第一次適配時(shí)只檢查了字節(jié)數(shù)組的長(zhǎng)度沒(méi)有檢查位級(jí)序列化邊界結(jié)果在真實(shí)提案數(shù)據(jù)解析時(shí)多讀了一個(gè) Bit導(dǎo)致整個(gè)后續(xù)字段錯(cuò)位。排查了將近一晚上最后是拿一個(gè)已知正確結(jié)構(gòu)的 Cell 做了逐 Bit 對(duì)照才找到問(wèn)題。建議所有字段編解碼測(cè)試都準(zhǔn)備一個(gè)“黃金樣例”用已知輸入輸出對(duì)來(lái)驗(yàn)證。第三測(cè)試網(wǎng)絡(luò)和主網(wǎng)絡(luò)的數(shù)據(jù)要嚴(yán)格隔離。鴻蒙應(yīng)用如果同時(shí)支持測(cè)試網(wǎng)和主網(wǎng)最容易出現(xiàn)的問(wèn)題是簽名消息在測(cè)試網(wǎng)驗(yàn)證通過(guò)切到主網(wǎng)環(huán)境就因?yàn)楹霞s版本不一致直接失敗。我在配置里把網(wǎng)關(guān)地址、合約版本、網(wǎng)絡(luò)代號(hào)全部做成了運(yùn)行時(shí)參數(shù)并且給每一個(gè)資產(chǎn)信息和投票入口都打上網(wǎng)絡(luò)標(biāo)記從源頭上避免用戶誤操作。我個(gè)人實(shí)際用下來(lái)的感受是鴻蒙化 ton_dart 這件事最難的地方不在 TON 協(xié)議本身而在于你對(duì)兩個(gè)生態(tài)各自邊界是否足夠清楚。誰(shuí)負(fù)責(zé)純邏輯誰(shuí)負(fù)責(zé)系統(tǒng)能力邊界一旦劃清了工作量大頭就只剩橋接層的聯(lián)調(diào)。最后再分享一個(gè)小技巧適配完成后先做最小閉環(huán)驗(yàn)證從“生成助記詞 - 本地簽名 - 構(gòu)造消息 - 廣播測(cè)試網(wǎng) - 回讀確認(rèn)”五步走通再往錢(qián)包頁(yè)面、治理模塊、資產(chǎn)列表這些功能上鋪開(kāi)。比一上來(lái)就接一堆特性要穩(wěn)妥得多排查問(wèn)題時(shí)也能把變量壓縮到可控范圍。后續(xù)如果你想在這個(gè)基礎(chǔ)上擴(kuò)展可以考慮接入去中心化交易所的聚合跳轉(zhuǎn)、多簽錢(qián)包或者更深度的 Jetton 跨合約交互這些在 ton_dart 的協(xié)議層里都已經(jīng)鋪好了地基。