作者: 時躍堂,曹國波
《使用BSN 一天學會區塊鏈開發》系列文章可以幫助具有一定開發經驗的開發者,在不需要學習區塊鏈開發語言的情況下,在區塊鏈服務網絡(BSN)上完成區塊鏈應用的開發。
本文主要介紹用戶如何通過鏈下業務系統使用golang語言與鏈上數據進行交互而進行的相關操作流程說明,但在說明鏈下業務系統與鏈上進行數據交互之前,首先對用戶如何在區塊鏈服務門戶註冊、應用發佈服務、應用服務參與以及應用管理進行一一說明。
註冊和登錄
打開區塊鏈服務網絡網址:www.bsnbase.com, 點擊登錄頁面中的【內測申請】按鈕進入內測申請頁:
根據頁面中的提示填寫內測申請信息並提交內測申請,內測申請用戶分爲 個人用戶和 企業用戶兩種,申請人應根據自己的用戶類型任選一種進行申請, 內測申請提交後需等待系統審覈,待系統審覈通過後將向申請者發送激活郵件,申請用戶可根據【激活郵件】中的激活鏈接來激活賬, 帳戶激活後即可登錄系統使用。
應用服務發佈
應用服務是指在區塊鏈服務網絡中已經發布並運行的區塊鏈應用,用戶可以通過服務網絡門戶發佈自己的區塊鏈應用服務,應用服務分爲公開和非公開兩種 (內測期間發佈的服務默認爲非公開,如需公開服務需提交公開申請,後臺運營人員進行審覈,只有審覈通過後服務纔可在服務門戶的應用商店中進行查看),此處就不一一截圖了,就概述一下應用服務發佈整體流程:
登錄區塊鏈服務門戶以後,進入 我發佈的應用->我發佈的服務頁面;
點擊 創建新服務按鈕,進入創建新服務頁面,根據提示輸入相應的信息;
點擊下一步按鈕開始上傳鏈碼包(上傳鏈碼包可以使用自己開發的鏈碼包或直接使用服務網絡提供的預製鏈碼包),再定義服務功能及角色(表示鏈下業務系統調用鏈碼所對應的權限)、選擇發佈的城市節點(表示當前發佈的服務所對應的鏈碼部署在哪些城市節點)、付費週期以及是否使用雲服務等信息;
繼續點擊 下一步按鈕,進入到 設置接入方式頁面,輸入網站地址、移動終端接入以及API服務接入等信息 (接入方式均爲鏈下接入的相關信息) ,如果暫時不需要設置接入方式,可跳過此頁面繼續點擊下一步按鈕,進入服務賬單頁面進行確定 (服務網絡內測期間,所有資源均免費使用) ;
點擊 確定後,在 我發佈的應用->我發佈的服務列表頁面可以看到該條新創建的服務,且該服務的狀態爲“待初審”狀態,發佈者需等待運營和運維人員進行審覈和發佈,服務發佈後發佈者默認不參與服務。
應用服務參與
在服務網絡內測期間,所有發佈的服務均爲非公開,如果自己或其他用戶想要參與已經發布的服務,可通過在 我發佈的應用 -> 我發佈的服務 列表中 邀請參與者 ,將 邀請參與者 的鏈接地址發給需要參與服務的用戶,應用參與服務整體流程如下:
根據邀請的鏈接地址,進入 服務信息頁面,點擊 申請參與應用按鈕,進入服務角色及城市節點選擇頁面;
選擇需要使用的服務角色和城市節點(角色是指用戶參與服務後鏈下業務系統訪問鏈上所對應的權限;城市節點是指用戶的鏈下業務系統通過該城市節點與鏈上進行數據交互)。用戶選擇服務角色以後,系統會顯示角色對應的功能使用費,選擇城市節點的時候申請新證書或選擇已有的證書。
點擊 確定按鈕,提示接入城市節點、接入方式以及費用信息:
確認參與服務的接入城市節點、接入方式以及費用信息(內測期間,所有資源均免費)後,在我 參與的應用-> 我參與的列表頁面可以查看到所參與的應用服務,該應用服務的狀態爲 待發布者審覈,等待應用服務的發佈者對參與者進行審覈。
服務網絡內測期間只要發佈者對服務參與申請審覈通過後,服務參與信息的狀態更新爲 已確認。至此,參與應用服務成功。
應用服務參與成功以後,鏈下業務系統就可以調用城市節點所對應的節點網關,將數據推送上鍊和從獲取上鍊數據以及鏈上區塊信息,調用節點網關所對應的參數可進入 我參與的服務->我參與的->查看->接入的城市節點和服務接入配置參數部分進行查看, 接入的城市節點用於接入的城市節點證書進行下載以及城市節點網關的調用地址進行展示, 應用服務接入配置參數用於對鏈下業務系統調用城市節點網關的相關參數進行展示,此部分的細節描述參考“ 數據交互”部分;
應用管理
應用服務發佈以後,可進入 我發佈的應用-> 我發佈的服務管理列表中對已經發布的服務進行統一管理,管理列表具體包含以下功能:
邀請參與者:主要用於將應用參與的邀請鏈接地址發給其它用戶,其它用於可以通過此邀請鏈接地址參與此服務;
申請公開:主要是內測期間,所有發佈的服務默認均爲非公開,如果需要將服務公開,則可以通過此功能提交公開申請;
服務升級:主要用於對應用服務的鏈碼包進行升級;
配置升級:主要用於對應用服務的配置資源進行升級,如部署的城市節點以及節點的資源的配置信息;
歷史版本:主要用於對服務升級以後的歷史版本進行查詢;
運行信息:主要用於對應用服務的部署節點以及節點資源信息和鏈上數據 (來源於鏈下業務系統通過調用節點網關接口將數據推送上鍊) 進行監控;
設置接入方式:主要用於對應用服務的鏈下業務系統的接入進行配置;
查看:主要用於對應用服務的基本信息、鏈碼及部署信息、服務角色信息、審批記錄信息以及接入方式等信息進行查看。
應用鏈碼開發
鏈碼(ChainCode)又稱爲智能合約,是用計算機語言描述合約條款、交易的條件、交易的業務邏輯等,通過調用智能合約實現交易的自動執行和對賬本數據的操作。一個區塊鏈應用可以部署多個鏈碼,每個鏈碼包含多個方法。
鏈碼支持多種語言編寫,包括golang、java、node.js。每個鏈碼程序都必須實現Chaincode接口,鏈碼包含:Init ,Invoke,Query三個基本操作:
Init : 鏈碼初始化的方法,在鏈碼實例化或者升級的時候調用一次,以便鏈碼可以執行任何必要的 初始化,包括應用程序狀態的初始化。
Invoke : 接收和處理鏈下業務系統調用事務處理提案,其參數包含調用的鏈碼程序中函數的名稱和具體業務處理數據參數。即在Invoke中根據不同的方法參數調用其他分支處理響應的業務。Invoke可以簡單的理解爲鏈碼方法的入口。
Query : 提供查詢鏈碼數據的方法,該方法只作爲查詢使用,不提供操作鏈上數據的操作。可在Query操作時調用,亦可在Invoke方法中作爲某些方法的分支被調用。該方法可以不實現。
下面以通用數據鏈碼包爲例詳細說明一下。
通用數據鏈碼包是我們爲應用開發者提供對業務數據進行增刪改查基本操作的鏈碼(Golang語言編寫)。應用開發者可以在此鏈碼包的基礎上根據應用業務需求進一步拓展鏈碼功能。此鏈碼支持存儲的數據類型有字符串、整型、浮點型、集合(map、list)等等。
鏈碼包下載地址: www.bsnbase.com/static/base/BaseChainCode.zip
1. 鏈碼包功能如下:
1.1. 增加數據(set)
輸入參數說明
baseKey:需要保存的唯一的主鍵標識,baseValue:保存的數據信息
例:{"baseKey":"str","baseValue":"thisis string"}
注: 其中baseKey是不能爲空的字符串,baseValue可以是任意類型的數據。如果baseKey已經存在,則直接返回已經存在,不能添加;如果不存在,則添加數據。
1.2. 修改數據(update)
輸入參數說明
baseKey:需要修改的唯一的主鍵標,baseValue:保存的數據信息
例:{"baseKey":"str","baseValue":"thisis string"}
注: 其中baseKey是不能爲空的字符串,baseValue可以是任意類型的數據。如果baseKey不存在,則無法更新,如果已經存在,則修改數據。
1.3. 刪除數據(delete)
輸入參數說明
baseKey:需要刪除的唯一的主鍵標識的值
例:"str"
注: 其中baseKey的值不能爲空,且必須存在,否則將無法刪除。
1.4. 獲取數據(get)
輸入參數說明
baseKey:需要獲取的唯一的主鍵標識的值
例:"str"
注: 其中baseKey的值不能爲空,且必須存在,否則將無法獲取到相應的信息。
2. 鏈碼介紹
2.1.Init 方法
這個就是最簡單的鏈碼初始化功能,寫日誌、初始化一條數據、保存到數據庫、響應。
建議在鏈碼初始化(Init)的時候,不要有太多的業務操作。
2.2. Invoke
stub.GetFunctionAndParameters():獲取請求的方法名稱(string)和參數信息([]string)
return t.set(stub, args)//調用保存的方法,具體的業務處理
節點網關
節點網關是部署在各個城市節點,接收應用系統的請求,使用託管的用戶身份信息,向相應的應用鏈碼發起訪問並返回鏈碼的執行結果。節點網關的調用是通過向區塊鏈服務的各個城市節點的網關服務發送HTTP請求來實現。節點網關負責驗證用戶身份信息、應用信息,通過用戶身份信息和應用信息以及需要訪問的鏈碼、鏈碼方法來傳遞鏈碼參數、獲取鏈碼執行結果的服務通道。
業務系統需要按照接口說明在請求中加入相應的請求參數,調用節點網關以後,節點網關會返回鏈碼的執行結果。
接口地址:https://節點網關地址/api/node/reqChainCode
注:用戶參與服務成功後可以在服務詳情頁面查看並下載應用鏈下業務系統開發所需要的應用服務配置參數、節點網關地址和應用身份證書,如下圖:
通訊方式:POST
簽名算法:
1、將userCode+ appCode+ chainCode+ funcName的值以及args中每一項數據拼接成字符串A;
2、對字符串A使用用戶證書的私鑰進行SHA256WITHECDSA簽名。
請求參數
響應參數
數據交互
應用服務參與審覈通過之後,鏈下業務系統就可以通過節點網關與鏈上數據進行數據交互,調用節點網關需要節點網關接入地址、節點網關請求參數以及證書等信息,此部分數據可以通過 我參與的應用-> 我參與的->查看明細頁面進行獲取,下面對這三方面的參數進行一一說明;
節點網關接入地址:爲鏈下業務系統調用鏈上所對應的城市節點入口,所有與鏈上的數據交互都是通過此地址進行訪問,如下圖所示:
節點網關請求參數:如果需要通過節點網關接入地址與鏈上進行數據交互,肯定需要按照節點網關接口調用規範,節點網關接口調用需要userCode、appCode、tid、chainCode、funcName、agrs等參數信息,下面對相關參數進行概要說明。
*userCode : 應用發佈者或者參與者的登錄名(也就是登錄門戶的用戶名)。
*appCode : 參與應用的唯一標識。應用創建時,系統自動生成的唯一標識。
*tid : 用戶與參與的應用之間關聯的唯一標識。
*chainCode : 區塊鏈服務網絡中,運維部署的鏈碼的名稱。需要注意的是,這裏的鏈碼名稱不是服務發佈時的鏈碼名稱。
*funcName : 調用鏈碼的方法名稱。
*agrs : 調用鏈碼方法的參數集合。字符串類型的數組,參與者需要與應用發佈者聯繫,獲取方法對應的參數。
參數獲取頁面如下圖所示:
節點用戶證書:在請求節點網關過程中需要https證書、請求報文簽名證書(即用戶身份證書)和響應結果驗簽證書。
*https 請求證書 :爲保障數據傳輸層的安全,需要使用https請求。
*請求報文簽名證書: 用戶私鑰證書。
*響應結果驗簽證書: 網關公鑰證書。
用戶身份證書的下載可以通過我參與的應用->我參與的->查看->接入的城市節點部分進行下載,也可以通過進入我的身份證書-證書查看列表中找到對應的應用信息,進行證書下載。下載的證書文件包含https證書、用戶證書(私鑰證書、公鑰證書(網關對報文的驗籤))、網關證書(網關公鑰證書)。證書下載頁面如下圖所示
業務系統開發
業務系統就是鏈下業務系統,需要與鏈上進行數據交互的系統,下面根據預置鏈碼包的golang開發實例(可從門戶下載)着重說一下與網關交互的說明。
項目環境準備:
1 、JetBrains GoLand/VS Code(可以使用您習慣的IDE)
2 、Go 1.12.5
項目介紹:
上圖爲項目的目錄結構:
1. Certs:主要用於存放用戶的公私證書、網關的公鑰證書以及請求網關時所需要的Https公鑰證書
bsngate_https.crt:節點網關API的Https公鑰證書(用於對請求網關API地址所需加載的公鑰證書)
gateway_public_cert.crt:網關公鑰證書(用於對網關響應的數據採用橢圓曲線算法進行驗籤)
private_key.pem:用戶私鑰證書(用於對請求網關的數據採用橢圓曲線算法進行簽名)
public_cert.pem:用戶公鑰證書(目前沒有用到)
2. common:主要用於存放公共庫,本示例中用於對ecdsa橢圓曲線算法工具類進行定義
ecdsa.go:用於對ecdsa橢圓曲線算法工具類進行定義
3. model :主要用於對請求網關和網關的響應報文數據結構進行定義
request.go :用於對請求節點網關API的數據報文進行定義
response.go:用於對節點網關API響應的數據報文進行定義
4. main.go:main文件是示例程序的入口以及包含調用節點網關API的相關業務邏輯代碼。
流程說明:
1. 修改調用網關所對應的請求參數
2. 拼接待簽名的字符串,對字符串使用用戶私鑰證書進行 SHA256WITHECDSA 簽名加密(調用ecdsa.go下的SignECDSA方法進行簽名,並生成base64格式的mac值)
3. 發起post請求,並且附加HTTPS證書
4. 獲取返回報文中的mac值,對返回報文中的mac值,使用網關的公鑰證書進行驗籤,驗籤內容與傳參時簽名字符串相同
5. 並將驗證結果輸出到控制檯
詳細說明
瞭解更多區塊鏈服網絡(BSN)最新動態請掃碼關注微信公衆號
關注區塊鏈服務網絡BSN