COS:從Python-SDK談談FISCO BCOS多語言SDK

FISCOBCOS2.0從發布起就自帶官方控制臺，經過社區持續使用打磨，已經足夠強大、完善、友好。社區還有用各種開發語言開發的區塊鏈應用，為滿足開發者方便管理區塊鏈節點的需求，目前Python-SDK和Nodejs-SDK已經上架，go語言版本已經在路上。

本文以筆者最熟悉的Python-SDK為例，分享一些SDK開發的點滴，涵蓋應用開發流程、協議編解碼、網絡通信和安全事項等。

FISCOBCOS自帶快速搭建特性，五分鐘一鍵搭鏈后，開發者只需連上區塊鏈節點，寫合約、發交易。

控制臺和SDK的定位，是幫助用戶快速訪問區塊鏈，開發測試智能合約，實現業務邏輯。根據“奧卡姆剃刀”原則，設計哲學應盡量輕、模塊化、淺層次，不引入多余的功能，不給用戶和二次開發者造成額外負擔。

客戶端控制臺和SDK就像一輛操控好、配置精的快車，供開發者和用戶駕馭，輕松愜意，盡情馳騁于區塊鏈應用之路。

控制臺體驗

首先結合從準備環境到調用合約的全流程，體驗下控制臺，命令行交互界面風格如下：

1.準備環境：

在開始之前，請先通讀使用手冊和開發文檔，根據文檔介紹，stepbystep初始化環境，安裝依賴庫，目前Python-SDK支持linux/mac/windows操作系統。

為了連上區塊鏈節點，需要修改本地配置文件，填寫區塊鏈節點的對應網絡端口，如果選擇Channel協議，則需要配置相應的客戶端證書。

2.在線體驗：

配置好網絡后，可以運行console的get系列命令。試下手感，與FISCOBCOS親密接觸。確認鏈在正常工作，常用的指令有getNodeVersion、getBlockNumber、getPeers、getSyncStatus等，可以用console的usage或help命令了解所有支持的指令。

3.創建賬戶：

創建一個新的帳戶，即代表自己身份的公私鑰對，發送交易時會采用私鑰簽名。創建的帳戶用keystore格式保存在本地文件系統里，用戶可以設定密碼保護這個文件，注意記住創建帳戶時使用的密碼。

控制臺提供的帳戶相關命令是newaccount,showaccount。如果要使用剛創建的新帳戶為交易簽名，記得把它配置到client_config.py文件的相應位置。

數據：自2月13日以來投資者已從Paxos贖回約67億美元BUSD:金色財經報道，數據顯示，截至發稿時，Paxos發行的穩定幣Binance USD（BUSD）流通供應量約為95億美元，創2021年6月以來新低。此外，據加密情報公司Nansen數據顯示，自今年2月13日以來，投資者已從Paxos贖回了約67億美元的BUSD。

此前報道，Paxos于2月13日宣布將停止鑄造新的BUSD代幣，美國證券交易委員會(SEC)準備起訴Paxos提供未注冊證券。Coinbase此前宣布，將從3月13日開始暫停平臺上的BUSD交易。[2023/3/4 12:41:53]

另外，如果賬戶信息需要高等級保護，則可以進行二次開發。將其放入加密機、TEE等安全區，以及開發秘鑰分片、助記詞等方案。

4.編寫合約：

編寫一個智能合約，或者參照SDK里自帶的智能合約例子修改定制，實現自己的業務邏輯。本文重點關注solidity智能合約，FISCOBCOS還有一種“預編譯合約”，采用C開發，需要和FISCOBCOS底層代碼聯合編譯。

5.編譯部署：

對合約進行編譯，獲得合約的ABI接口文件和BIN二進制代碼文件。Python-SDK里有bcos_solc.py文件可幫助開發者簡化編譯器配置和調用，同時，只要正確配置了合約路徑和編譯器路徑信息，直接運行控制臺的部署或調用合約接口指令，也會嘗試自動去編譯合約，操作體驗相當行云流水。

獨立部署合約的話，可使用控制臺的deploy指令，部署指令成功后會得到新的合約地址。參考命令是./console.pydeploySimpleInfosave，其中SimpleInfo是合約名，最后的"save"為可選，如果指定了"save"，則將合約新地址記錄到本地文件里，以便后續使用。

6.調用合約：

用call或sendtx命令，指定合約名、合約地址、方法名、對應的參數，調用鏈上合約。

參考命令./console.pysendtxSimpleInfolastsetbalance100，即選擇SimpleInfo合約，指向其最近部署成功的地址，調用setbalance接口，傳入參數100。

交易在鏈上共識完成后，控制臺會自動打印交易回執里的方法返回碼、交易Eventlog信息列表等，供用戶查看，如果錯誤，則打印異常信息。

KCC Bridge支持將MATIC等代幣從Polygon跨鏈至KCC:12月30日，據官方消息，KCC Bridge現在支持將代幣從Polygon轉移到KCC主網，支持的資產包括USDT、USDC、ETH、MATIC。[2021/12/30 8:14:09]

如果一切正常，到此即可基本走通區塊鏈應用之路。

值得一提的是，FISCOBCOS幾個語言版本的控制臺，都支持按Tab鍵提示指令和自動完成，幫助使用者流暢無錯地操作，提升用戶體驗。

再進一步，如果希望有豐富多彩的、可視化交互式頁面體驗，不妨使用WeBASE中間件平臺。

深入了解

整個SDK的模塊組合如下，可謂是麻雀雖小五臟俱全。

功能接口

支撐控制臺等交互模塊的，是已經封裝完備、開箱即用的功能接口API，包括：

1.get系列：

諸多的“get”開頭的接口，用于獲取鏈上的各種信息，包括區塊、交易、回執、狀態、系統信息等等。雖然幾十個get接口，但其實現邏輯基本一致，都是指定命令字和參數列表，請求和處理回應，實現起來也很快。

2.call：

對應合約的常量方法。所謂常量方法，是指合約里對應代碼不修改狀態，該請求不會全網廣播，僅在指定節點上運行。

3.sendRawTransaction:

構建一個交易，用賬戶私鑰簽名，發送到鏈上，這種交易會被廣播，進行共識處理，生成的狀態數據會被全網確認。部署新合約這個操作，實際上也是一種交易，只是不需要指定目標合約地址。

相關的是sendRawTransactionGetReceipt，名字很長，在sendRawTransaction基礎上增加了獲取回執的流程，用于簡化從發交易到獲取回執的閉環流程。

4.更多：

針對FISCOBCOS的全局系統配置、節點管理、CNS、權限等系統級功能的API，其原理是讀寫鏈上的系統合約，詳細指令列表見文末。

開發者可以參考控制臺和client/bcosclient.py等代碼，進行二次開發，實現更多更酷炫的功能。另外，SDK里內置了一系列的開發庫和小工具，幫助管理帳戶、輸出日志、統一異常處理、簡單的性能和耗時統計等。

Ember Sword從Polygon遷移至ImmutableX:11月6日消息，Ember Sword表示已與以NFT為中心的以太坊擴展解決方案Immutable X建立合作伙伴關系，從Polygon遷移至ImmutableX的程序將在未來幾個月內完成。[2021/11/7 6:36:12]

合約開發相關

圍繞著合約開發，Python-SDK實現了合約編譯部署、合約地址本地化管理、ABI接口文件的管理，支持代碼自動生成，一個命令行即可生成供業務端直接使用的代碼，如

pythoncodegen.pycontracts/SimpleInfo.abi。

solidity合約編譯后的ABI文件是個好東西。ABI全稱是ApplicationBinaryInterface，里面詳細描述了合約的接口信息，包括方法名、參數列表和類型、方法類型，以及Eventlog格式定義等等。

對ABI的管理，參見client/datatype_parser.py，加載和解析ABI文件，根據方法名、方法4字節簽名、方法類型等維度，靈活查詢方法列表和方法定義，并針對方法定義、輸入數據等進行編碼解碼，解析交易返回值、Eventlogs等。

有ABI定義在手，對合約的操控簡直是可以隨心所欲，開發者讀懂了ABI描述，基本就能全面理解一個合約的輸入輸出，和合約毫無障礙地對話，這種“面向遠程接口編程”的思想，很類似WSDL、IDL、ACE、ProtoBuffer和gRPC等經典軟件設計。

事實上，整個SDK中最繁瑣的是ABI編解碼部分，為了兼容EVM，FISCOBCOS在交易處理時沿用了ABI編碼，以及兼容RLP協議。

ABI、RLP制定了嚴格的規范，對基礎數據類型、數組和變長數據、函數方法、參數列表等都有特定的編解碼方式，否則組件之間無法通信，數據無法解析，虛擬機“不認識”所輸入的交易，則不能執行合約。

如果自行手寫這里的編解碼，即使是熟手也得花不少時間，還要能保證測試通過、保持版本兼容，所幸github上已經有eth-abi、eth-utils、rlp等一系列開源項目，可以引入這些項目且根據具體的需要進行修訂，能節約不少工作量，向這些項目作者們致謝，開源就是爽！

交易數據結構相關

動態 | SEC申請將從PlexCoin ICO查封的140萬美元分配給投資者:據Finance Magnates今日消息，當地時間周四，美國證券交易委員會（SEC）想法院申請許可，以將從PlexCoin ICO查封的140萬美元分配給投資者。此前消息，美國證券交易委員會自2017年12月1日起，持續對欺詐性ICO項目PlexCoin進行制裁，并于2019年10月，最終裁定PlexCoin支付700萬美元罰款。[2020/1/3]

在搞定了基礎編解碼之外，還需要實現FISCOBCOS交易結構，重點注意支持并行處理交易增加的randomid、blocklimit字段，為支持群組特性增加的fiscoChainId和groupId字段，在交易的receipt里增加的交易output等。

其中，交易的blocklimit定義為“交易生命周期，該交易最晚被處理的塊高”，SDK需要定期到鏈上查詢當前塊高，以確定當前交易的生命周期。

對于開發者來說，清晰理解交易的輸入、交易回執、交易輸出(tx.output)是非常重要的。

交易調用合約里的某一個方法時，首先將方法名字和參數類型列表組合，如'set(string,uint256,address)'，對這一段文本進行Keccak-256(SHA-3)計算，并截取前4個字節做為“方法簽名”，然后對傳入的參數，根據類型定義依次進行ABI編碼，并和"方法簽名"拼接一串二進制數據，做為交易的輸入數據。

和交易結構體的其他字段一起再進行RLP編碼，并用帳戶私鑰進行簽名，得到一段二進制請求數據，由sendRawTransaction發往節點，節點收到后，立刻返回交易Hash給到客戶端。

交易在鏈上被網絡共識確認，處理完成后，通過getTransactionReceipt接口，可以獲得交易處理的詳細結果。

在交易回執中，以下幾個字段尤為關鍵：

1.contractAddress：

僅在部署合約交易時有效，表示新合約的地址。

2.output：

對應方法的return值，可用于判斷業務邏輯的最終處理結果。

3.Logs：

如果在合約代碼里，寫了一些Eventlog，則receipt的logs字段里可以解碼出詳細的信息。Eventlog可用于幫助客戶端監聽、跟蹤交易的處理結果，甚至可以幫助開發者調試合約執行過程，相當于在合約里打調試日志。當然，在合約正式發布時，應清除調試的Eventlog，只保留必要的log，避免冗余信息存到鏈上。

動態 | 524枚BTC從Poloniex交易所轉出 價值554萬美元:北京時間07月19日00:29, 524枚BTC從Poloniex交易所轉入1Hoox2開頭地址，按當前價格計算，價值約554萬美元，交易哈希為：1e676bb7c354aced580edd04c1ec46a6c7bf427b19341662bd94460a0b810434。[2019/7/19]

Python-SDK客戶端里內置了解析“方法簽名”、交易input/output、receipt.logs等字段的方法。

在使用控制臺命令行時，只要是查詢交易和回執的指令，在命令行后面附帶合約名，也可以自動解析出相關的數據來，例如：./console.pygetTransactionReceipt0x79b98dbb56d2eea289f756e212d5b6e5c08960beaa8ea8331740fdcfaa8dcab1SimpleInfo，最后這個“SimpleInfo”為可選合約名，不需要帶后綴，要求在contracts/目錄下有SimpleInfo.sol文件。

這個貼心小設計，可以幫助開發者直觀探秘區塊鏈交易的脈絡，對各種信息一目了然，不會迷失在天書一樣的十六進制字符海洋里。

網絡協議

最后聊聊FISCOBCOS的兩種網絡協議：JSONRPC和Channel長連接。

JSONRPC連接沒有證書驗證和通信加密，建議在本身安全可信的環境里使用，比如本機或內網，一般用于運維管理和統計分析場合。

JSONRPC的格式相當簡單通用，各種語言庫都內置了JSON編解碼以及HTTP請求協議實現，一般不需要自行開發，甚至可以采用curl、telnet等工具進行收發，如：

//Requestcurl-XPOST--data'{"jsonrpc":"2.0","method":"getBlockNumber","params":,"id":1}'http://127.0.0.1:8545|jq//Result{"id":1,"jsonrpc":"2.0","result":"0x1"}

Channel協議是FISCOBCOS獨有的協議，Channel協議的特點是安全高效，支持雙向實時通信，可用于遠程調用乃至公網的通信。

如果使用Channel長連接方式，則需要從區塊鏈節點上獲取SDK證書，放置到SDK項目的對應路徑下，證書詳見文末。

這個協議的數據包格式示意圖如下，是一種TLV(Tag/Length/Value)風格的擴展實現：

格式說明：

所有整形數編碼都是網絡序，大端；

Length實際上包含了從第一個字段到最后一個字段的整個數據包的長度；

包頭為定長，為（42324)=42字節；

數據體的實際長度根據具體內容而變，字節數為Length-42字節。

Channel長連接通信和數據收發的要點如下：

采用TLSv1.2安全傳輸，SDK和節點之間需要加載證書，用證書握手、驗證后才能建立長連接。

長連接用心跳包維護，需要定期發起心跳包。

數據按包為單位，編碼成流數據傳輸，那么在收發數據時，需要持續從socket流里獲取數據，按照數據包的格式，判斷長度是否合法，數據是否收全，是否能正確的解析，對“部分收取”的數據，要保留在接受緩沖區里，待收取完成后再進行解析，不能丟棄，否則可能導致解析錯誤。

Channel協議支持雙向通信，SDK可以主動請求節點，節點也可能往SDK推送消息，如區塊鏈系統通知、數據更新通知、AMOP跨機構消息等。

設計異步的、隊列化、回調式消息處理機制，根據消息的序列號、指令類型、狀態碼等維度，正確處理消息。Python-SDK用了多線程以及Promise庫，以盡量高速優雅地處理各種消息。

對socke流數據編程有一定經驗的開發者，理解這個協議和實現它并不會很難。對Channel協議實現，數據包解析參見client/channelpack.py，通信和數據收發參見client/channelhandler.py。

總結

Python-SDK的開發始于今年6月中旬，寫出第一個可用版本只花了一個星期，然后雕琢用戶交互細節，以及進行代碼優化、文檔完善，并進行多輪測試保證質量，團隊其他同學實現Nodejs版本SDK的用時也差不多。

總的來說，在有一些基礎代碼參考的前提下，開發一個FISCOBCOS特定語言版本SDK，還是挺敏捷寫意的事情，一點兒也不難，Justforfun。

在各語言版本SDK開發和迭代過程中，FISCOBCOS團隊和社區開發者一直保持溝通交流，納入優質pullrequest，在體驗中持續優化。

歡迎社區開發者根據自身使用場景的實際情況，繼續完善現有SDK，或貢獻更多語言類型的FISCOBCOSSDK，幫助更多開發者順暢地走在區塊鏈之路上。

最后，感謝杰哥、安總、小白、wheat等同學，以及多位社區開發者對Python-SDK的重要貢獻。

參考資料

FISCOBCOS官方控制臺：

https://github.com/FISCO-BCOS/console

Python-SDK：

https://github.com/FISCO-BCOS/python-sdk

Nodejs-SDK：

https://github.com/FISCO-BCOS/nodejs-sdk

FISCOBCOS安裝:

https://fisco-bcos-documentation.readthedocs.io/zh_CN/latest/docs/installation.html#fisco-bcos

合約開發教程：

https://fisco-bcos-documentation.readthedocs.io/zh_CN/release-2.0/docs/manual/smart_contract.html

WeBASE:

https://fintech.webank.com/webase

ABI：

https://solidity.readthedocs.io/en/latest/abi-spec.html

RLP:

https://github.com/ethereum/wiki/wiki/RLP

交易數據結構：

https://fisco-bcos-documentation.readthedocs.io/zh_CN/release-2.0/docs/design/protocol_description.html

RPC原理：

https://fisco-bcos-documentation.readthedocs.io/zh_CN/release-2.0/docs/design/rpc.html

Channel協議定義:

https://fisco-bcos-documentation.readthedocs.io/zh_CN/release-2.0/docs/design/protocol_description.html#channelmessage-v1

SDK證書:

https://fisco-bcos-documentation.readthedocs.io/zh_CN/release-2.0/docs/manual/certificates.html

AMOP跨機構:

https://fisco-bcos-documentation.readthedocs.io/zh_CN/release-2.0/docs/manual/amop_protocol.html

Tags：BCOCOSFiscoISCTBCOIN幣TacoswapDISC幣

火幣下載