概要

區(qū)塊鏈網(wǎng)絡(luò)使用

• gRPC 協(xié)議
• Protocol Buffers(格式的 API)

使用的協(xié)議

• gRPC

Protocol Buffers 格式的 API 包括

• 交易處理
• 安全的成員關(guān)系服務(wù)
• 區(qū)塊鏈遍歷
• 事件處理

SDK 提供的 API 最小集合實現(xiàn)

目標(biāo)

• 要解決客戶在區(qū)塊鏈網(wǎng)絡(luò)中直接面對的一些原始需求
• 做一些頂層的合理抽象以方便開發(fā)人員開發(fā)
• 在本地應(yīng)用代碼中使用這些 API 后方便開發(fā)工作的進行。

使用 SDK 并不會妨礙應(yīng)用直接調(diào)用 gRPC 的操作。

注意： 當(dāng)前的 REST API 并不被推薦使用，SDK 不應(yīng)該基于使用 REST API 而創(chuàng)建。跳過 REST 直接使用 gRPC 的原因是：能夠控制 全雙向的數(shù)據(jù)流（大部分的 API 調(diào)用都是異步的），更好的性能。此外，自從節(jié)點內(nèi)部模塊通信使用了 gRPC 之后，便不必再開放更多的 HTTP/HTTPS 端口了

例外的情況 新的成員服務(wù)方式（CA）是按 REST API 的規(guī)則實現(xiàn)的

作為參考，F(xiàn)abric v1.0的架構(gòu)和交互模型可以在下面 這個鏈接 所指向的工作單元的附件文檔里面查看

目標(biāo)

應(yīng)用開發(fā)

為開發(fā)人員提供編寫應(yīng)用程序的多種操作區(qū)塊鏈網(wǎng)絡(luò)的方式。

• 部署/執(zhí)行 chaincode
• 監(jiān)聽網(wǎng)絡(luò)中產(chǎn)生的事件
• 接收塊信息
• 把交易存儲到賬本中，等等

chaincode 開發(fā)

可以為開發(fā)人員提供編寫 chaincode 單元測試代碼
開發(fā)人員應(yīng)該能夠在不把 chaincode 部署到網(wǎng)絡(luò)上的情況下快速測試 chaincode

原則

良好的 API 文檔，數(shù)據(jù)模型，示例代碼

提供清晰的文檔說明

便于使用

便于使用

• chaincode 開發(fā)人員和應(yīng)用程序開發(fā)人員關(guān)注于書寫業(yè)務(wù)邏輯代碼。
• SDK 編譯時間上不應(yīng)該對 fabric project 有任何依賴。（除非原始文件定義了多種合約？？需要看英文原文）
• SDK packages/jars/libraries 應(yīng)該在常用的資源庫網(wǎng)站上可獲取 引用的包需要常用且方便查找

性能

• 高吞吐量
• 水平擴展能力
• 更低的延遲

SDK 應(yīng)該是一個組件狀態(tài)無關(guān)化的理想實現(xiàn)，或者允許應(yīng)用實例數(shù)據(jù)庫共享狀態(tài)

版本控制

統(tǒng)一的版本控制下，建議將 SDK 通過多種語言實現(xiàn)，并且多種實現(xiàn)的 SDK 之間在功能上能夠保持互通

可服務(wù)性

本 SDK 應(yīng)該方便于在可服務(wù)性支持中添加插件，即日志系統(tǒng)。具體細(xì)節(jié)不是很理解。

它應(yīng)該允許SDK使用方的應(yīng)用添加一個日志處理的實例。應(yīng)用傾向于在SDK內(nèi)部和外部使用一個通用的日志系統(tǒng)，這是非常有用的。一個IT組織為了監(jiān)視和分析通常會安裝日志腳本，比如對一個標(biāo)準(zhǔn)日志格式的需求。本SDK應(yīng)該有一個編譯進版本的日志系統(tǒng)以便于開發(fā)人員通過默認(rèn)方式獲取日志。但是它必須允許設(shè)置一個擁有一系列標(biāo)準(zhǔn)集合的外部日志系統(tǒng)來記錄API日志。

場景

有許多種可能場景，但是讓我們關(guān)注一少部分來說明 SDK 的整體功能

成員的注冊和登記

需要有身份認(rèn)證的證書，證書的提供者，證書可被驗證

• 為了跟 fabric 交互，需要具備一個專有的身份認(rèn)證，它被編碼進 ECert (登記證書) 的成員證書里
• 證書可能是外部認(rèn)證機構(gòu)提供，或者由 fabric 成員服務(wù)提供
• ECert可以被fabric組件在建立鏈的信任鏈時驗證即可

如果用一個標(biāo)準(zhǔn)的CA來管理分配ECert，交易會被ECert簽名。這將使得每一個交易對于每一個客戶端都是可驗證的。

TCert 怎么產(chǎn)生的？
MSP 在 fabric 中的設(shè)計是，利用一個加密算法從 ECert 的密鑰對導(dǎo)出一個密鑰對，因此為每一個交易產(chǎn)生一個假名證書

一個 TCert 不能代表一個認(rèn)證的身份，但是能通過成員服務(wù)追蹤到原始的 ECert。這個技術(shù)在許多業(yè)務(wù)場景下隱藏交易認(rèn)證是非常有用的。

Fabric 提供了 MSP 接口的一種實現(xiàn)，命名為 “COP” 立意來源于它的作用就像警察，而不是來源于首字母。在github 的組織超級賬本里面的代碼庫 fabric-cop 就是它。（注：現(xiàn)在這個倉庫在 github 上的 hyperledger-archives 目錄下，目前此倉庫的狀態(tài)為只讀狀態(tài)，已經(jīng)棄用）

給一個基于 fabric 的網(wǎng)絡(luò)配置一個外部的 CA，用戶注冊也會在外部維護。這個外部的用戶注冊系統(tǒng)負(fù)責(zé)認(rèn)證用戶。一個已經(jīng)被認(rèn)證的用戶為了獲取 ECert 可以使用 CA 請求登記。

就 SDK 而言，應(yīng)該有兩種 API

• 支持任何 CA（包括內(nèi)建的和外部的）通用 API

  • enroll(): 使用 SDK 的應(yīng)用程序執(zhí)行最基本的操作 比如關(guān)聯(lián)用戶身份，為認(rèn)證用戶獲取 ECert 的程序
  • getTCert(): 獲取交易證書允許用戶提交交易

• 專門為 fabric 的內(nèi)建成員服務(wù)提供的 API

客戶端有關(guān)可選的成員服務(wù)實現(xiàn)（即COP）的設(shè)計需要單獨的文檔來說明

鏈的創(chuàng)建

Hyperledger Fabric 所設(shè)計的支持隱私性和機密性的通道和賬本，統(tǒng)一被稱為一條『鏈』。

通道和賬本設(shè)計更多內(nèi)容請查看

• 通信（傳輸中的數(shù)據(jù)）被限制在參與方之間的通道內(nèi)
• 同時塊內(nèi)數(shù)據(jù)（已被持久化的數(shù)據(jù)）保存在一個私有的僅僅在這些參與方之間分布式存儲的賬本中。
• 不屬于鏈的網(wǎng)絡(luò)節(jié)點不了解通道和私有賬本內(nèi)部任何數(shù)據(jù)，也不能利用這些數(shù)據(jù)。

一旦一個鏈被創(chuàng)建，應(yīng)用可以發(fā)送交易給鏈上以私有方式存在的節(jié)點，并且已提交被驗證的交易到私有賬本。這句話不通

創(chuàng)建鏈的責(zé)任落在應(yīng)用程序身上。通過 SDK 應(yīng)用程序初始化鏈的組織團體（網(wǎng)絡(luò)成員的代表）構(gòu)成并且給排序服務(wù)。為什么是給排序服務(wù)

• 在 SDK 里，通道和它本身關(guān)聯(lián)的賬本的綁定由鏈類體現(xiàn)。
• 應(yīng)用和指定的排序節(jié)點第一次準(zhǔn)備一個新的通道并且獲取一個包含關(guān)于新鏈的密鑰信息的創(chuàng)世區(qū)塊，
  • 參與者信息（URL 和證書）、
  • 排序節(jié)點信息（URL 和證書）。

Q: 應(yīng)用通過什么來協(xié)調(diào)新通道與參與節(jié)點的邀請?

A: 應(yīng)用通過 目標(biāo)是配置系統(tǒng) chaincode 的配置化交易 來協(xié)調(diào)新通道對參與節(jié)點的邀請。（這句話還是不夠直白，看英文自己理解吧~）

sdk-image01

交易支持

一個交易包含兩個明確的步驟：

• 背書：是請求節(jié)點對交易的結(jié)果進行運行并背書（簽名）
• 提交：是在交易和交易的背書內(nèi)容的有效期內(nèi)請求共識 這個是什么意思

下圖說明交易時客戶端SDK和節(jié)點之間的交互。更多信息請查看 架構(gòu)文檔

流程簡介：

首先 SDK 和應(yīng)用協(xié)同工作，使用 應(yīng)用 的（或者被認(rèn)證用戶的）私鑰給信息簽名（所有的外部信息都需要簽名認(rèn)證）。然后它根據(jù) 背書策略（通過驗證系統(tǒng)鏈碼或者VSCC實現(xiàn)的）給一個或多個節(jié)點 發(fā)送信息。它獲得 異步的反饋 并且決定是否執(zhí)行創(chuàng)建和提交交易到共識服務(wù)。執(zhí)行交易提交的決定是基于背書策略謂詞（就像 2 out of 3）基于帶外知識。一旦提交，交易的處理流程便是異步的，所以SDK監(jiān)聽提交事件來通知應(yīng)用交易處理流程的完成或者拒絕的結(jié)果。

image02

上圖是對交易流程非常上層的描述。SDK 中有詳細(xì)的執(zhí)行網(wǎng)絡(luò)和環(huán)境配置，包括 獲取簽名密鑰來安全的管理成員，處理交易和事件流，（依賴應(yīng)用的）多種共識通道。

客戶端服務(wù)器 API 參考

下面的產(chǎn)指向 gRPC 與 fabric （節(jié)點，排序者和成員服務(wù)）溝通的信息和服務(wù)定義

• Proposal (部署或者交易調(diào)用的提案)
• ProposalResponse (全局的提案回應(yīng))
• Chaincode (chaincode, 調(diào)用，部署，等細(xì)節(jié))
• ChaincodeProposal (chaincode-specific proposal header and payload)
• Transaction (transaction invocation)
• ChaincodeTransaction (chaincode-specific transaction action payload)

新的COP API是基于json的，需要添加到新的成員服務(wù)設(shè)計中。** COP 已棄用**

消息定義應(yīng)該是設(shè)計 SDK APIs 的一個靈感來源。因為 SDK 可以使用 智能缺省 和 狀態(tài)信息 來最小化請求的參數(shù)。

詳細(xì)說明

這里討論設(shè)計的原則和架構(gòu)思路

總的來說，我們有不同等級的（數(shù)值越小表示等級越高）一些模塊：

package: Hyperledger Fabric Client

Package: Member Service

以上各模塊的關(guān)系，我們給出了以下 UML 圖：

sdk-image03

客戶端

和終端用戶主要的交互處理器?？蛻舳藢嵗峁┮粋€和 網(wǎng)絡(luò)上的節(jié)點，排序者，可選成員服務(wù)交互的處理器。應(yīng)用程序使用 SDK 需要和多個網(wǎng)絡(luò)交互，分別通過單獨的客戶端實例進行。

每個客戶端被創(chuàng)建時，應(yīng)該是使用來自于共識服務(wù)的配置數(shù)據(jù)初始化創(chuàng)建，這些數(shù)據(jù)包含一個被信任的根的列表，排序節(jié)點證書和IP地址，還有一個節(jié)點證書列表和可使用的IP地址。這必須是作為應(yīng)用程序環(huán)境的一部分進行的。應(yīng)用程序負(fù)責(zé)維護客戶端的配置，因為 SDK 不持久地保存這個對象

• 共識服務(wù)的配置數(shù)據(jù)包括：
  • 一個被信任的根的列表
  • 排序節(jié)點證書
  • IP地址
  • 一個節(jié)點證書列表
  • 可使用的IP地址

每個客戶端實例可以維護幾條鏈代表通道和相關(guān)的賬本。

• new_chain （創(chuàng)建一個新鏈）

根據(jù)參數(shù)給出的名字創(chuàng)建一個鏈的實例。這實際上代表“通道”（正如上面解釋的），這個調(diào)用返回一個空對象。初始化這個通道，這個返回的對象上必須配置一個參與方的背書者列表和排序者節(jié)點。

Params (參數(shù))

+ name(str): 鏈的名稱，推薦使用命名空間防止碰撞

Return（返回值）

+ （Chain instance）:未初始化的鏈的實例

• get_chain (獲取鏈)

獲取鏈的實例。本接口允許保存已存在的鏈實例供之后的檢索，并且在應(yīng)用程序?qū)嵗g共享。記錄鏈的信息是應(yīng)用程序或者 SDK 負(fù)責(zé)的事情。如果應(yīng)用程序不能查看存儲中鏈的信息，它可以調(diào)用另外一種 API 查詢一個或多個節(jié)點來獲得這些信息。

Params

+ name (str): The name of the chain （鏈的名稱）

Returns

+ (Chain instance or None): the chain instance for the name. （以入?yún)⒚逆湹膶嵗?

Error:

+ The state store has not been set (還沒有設(shè)置存儲狀態(tài))
+ A chain does not exist under that name (不存在該名稱命名的鏈)

• query_chain_info（查詢鏈的信息）

這是一個網(wǎng)絡(luò)調(diào)用，用來查詢指定的節(jié)點上鏈的信息。目標(biāo)節(jié)點必須是屬于目標(biāo)鏈，才能夠返回請求的信息。

Params

+ name (str): The name of the chain （鏈名）
+ peers (array of Peer instances): target Peers to query（查詢的目標(biāo)節(jié)點）

Returns

+ (Chain instance or None): the chain instance for the name.（以入?yún)⒚逆湹膶嵗?。?

Error:

+ The target Peer(s) does not know anything about the chain（目標(biāo)節(jié)點不了解鏈的信息）

有沒有可能就沒有這條鏈

• set_state_store（設(shè)置狀態(tài)的存儲）

SDK 應(yīng)該有一個內(nèi)建的鍵值存儲的實現(xiàn)（建議是基于文件的實現(xiàn)，以便于在開發(fā)中設(shè)置）。但是生產(chǎn)系統(tǒng)需要通過數(shù)據(jù)庫為更多的穩(wěn)定存儲和聚簇存儲備份，所以多種應(yīng)用程序?qū)嵗梢酝ㄟ^數(shù)據(jù)庫共享應(yīng)用狀態(tài)（備注：應(yīng)用不需要豐富的狀態(tài)）。這個 API 使得存儲模塊具有可插拔特性，所以應(yīng)用程序可以選擇不同的存儲實現(xiàn)。

Params

+ store (KeyValueStore): instance of an alternative KeyValueStore implementation provided by the consuming app.（使用方應(yīng)用程序提供的鍵值存儲實現(xiàn)的實例）

Returns

+ None

• get_state_store（獲取狀態(tài)存儲）

為 client 提供的獲取狀態(tài)存儲對象的便利方法

Params

+ None

Returns
+ (KeyValueStore instance): The KeyValueStore implementation object set within this Client, or null if it does not exist（返回設(shè)置到client中的按鍵值對方式實現(xiàn)的存儲對象，如果不存在返回空）

• set_crypto_suite (設(shè)置加密模塊)

設(shè)置一個加密模塊的實例，該實例是按 CryptoSuite 接口實現(xiàn)的。一個加密模塊打包了數(shù)字簽名的算法和使用非對稱密鑰對的加密功能，使用對稱密鑰加密的消息，安全的 hashing 處理和 MAC

Params

+ Suite (object): an instance of a crypto suite implementation（按接口實現(xiàn)的加密模塊的實例）

• get_crypto_suite (獲取加密模塊)

Client獲取加密模塊對象的便利方法。

Params

+ None

Returns

+ (CryptoSuite instance): The CryptoSuite implementation object set within this Client, or null if it does not exist（加密模塊的對象）

• set_user_context（設(shè)置用戶上下文）

根據(jù) client 實例的安全的上下文設(shè)置用戶類的實例。用戶的資格證書會被用來執(zhí)行交易并且查詢區(qū)塊鏈網(wǎng)絡(luò)。如果狀態(tài)存儲已經(jīng)設(shè)置到了 client 實例上，根據(jù)設(shè)定的用戶上下文，SDK 可以把對象保存在一個持久化的緩存中。如果沒有設(shè)置狀態(tài)存儲，當(dāng)應(yīng)用程序崩潰或者被覆蓋時，緩存不能被創(chuàng)建，并且應(yīng)用程序需要再次設(shè)置用戶上下文。

Params

+ user (User): an instance of the User class encapsulating the authenticated user’s signing materials (private key and enrollment certificate) （參數(shù)是用戶，用戶類的實例，它把被認(rèn)證用戶擁有的簽名材料（私鑰和背書證書）打包在內(nèi)）

• get_user_context（獲取用戶上下文）

正如上面所解釋的，client 實例可以擁有一個可選的狀態(tài)存儲。SDK 保存已注冊用戶到可以被應(yīng)用程序的已認(rèn)證用戶（認(rèn)證的工作在 SDK 之外由應(yīng)用程序完成）利用的存儲中。本方法試圖通過本地存儲中的名稱（通過鍵值存儲接口獲?。┘虞d用戶。已加載的用戶對象必須代表一個已注冊用戶，并且該用戶擁有一個已信任的 CA（如 COP 服務(wù)）簽名的可用的背書證書。

Params

+ name (str): The name of the user （用戶名稱）

Returns

+ (User instance): The user object corresponding to the name, or null if the user does not exist or if the state store has not been set（返回匹配名稱的用戶對象，如果用戶不存在或者狀態(tài)存儲未設(shè)置返回空）

鏈

“鏈”對象從通道獲取設(shè)置項，由排序者節(jié)點創(chuàng)建，與排序者給通道上參與的節(jié)點派發(fā)交易的行為相隔離。根據(jù)節(jié)點列表和排序者列表配置鏈之后，它必須被初始化。初始化過程給排序者節(jié)點發(fā)送一個配置交易來創(chuàng)建特定的通道，并且詢問節(jié)點加入通道。

• add_peer（添加節(jié)點）

給鏈對象添加節(jié)點，這是純本地操作。

Params

peer (Peer): an instance of the Peer class that has been initialized with URL, TLC certificate, and enrollment certificate（入?yún)ⅲ罕?URL，TLC 證書，和 背書證書 初始化之后的 Peer 類的對象。）

• remove_peer (移除節(jié)點)

從鏈對象移除節(jié)點，這是一個純本地操作

Params

+ peer (Peer): an instance of the Peer class（節(jié)點實例）

• get_peers (獲取節(jié)點)

從鏈的本地信息獲取節(jié)點。

Params

+ None

Returns

+ (Peer list): The peer list on the chain（返回鏈上的節(jié)點列表。）

• add_orderer（添加排序節(jié)點）

給鏈對象添加排序者節(jié)點，這是純本地操作。 鏈實例可以選擇使用單個的排序者節(jié)點，這個排序者負(fù)責(zé)向排序者網(wǎng)絡(luò)中其他排序者廣播請求?；蛘呷绻麘?yīng)用不信任排序者節(jié)點，它可以選擇使用更多的排序者，僅需要向鏈對象添加它們即可。有關(guān)某個排序者的所有API會同時廣播給所有的排序者。

Params

+ orderer (Orderer): an instance of the Orderer class （Orderer實例）

• remove_orderer（移除排序節(jié)點）

從鏈對象移除排序者節(jié)點，這是純本地操作。

Params

+ orderer (Orderer): an instance of the Orderer class

get_orderers（獲取排序節(jié)點）

獲取鏈的排序節(jié)點，這是純本地操作。

Params

+ None

Returns

+ (Orderer list): The orderer list on the chain

• initialize_chain（初始化鏈）

調(diào)用排序者來開始創(chuàng)建新的鏈，創(chuàng)建動作本身是開放的新的消息流和連接參與節(jié)點的組合。這是一個耗時的處理。只有一個應(yīng)用程序?qū)嵗枰{(diào)用這個方法。一旦鏈被成功創(chuàng)建，其他的應(yīng)用程序?qū)嵗齼H僅需要調(diào)用 get_chain() 來獲取有關(guān)鏈的信息。

Params

+ None

Returns （鏈的初始化動作是否執(zhí)行成功）

+ (bool): whether the chain initialization process was successful

• update_chain（更新鏈）

調(diào)用排序者節(jié)點來更新已經(jīng)存在的鏈。這允許給已存在的鏈添加或刪除節(jié)點，也是基于證書重建對節(jié)點證書信息進行更新。

Params

+ None

Returns （更新鏈的操作是否成功）

+ (bool): whether the chain update process was successful

• is_readonly（是否只讀）

獲取鏈的狀態(tài)來查看底層通道是否已經(jīng)被終止，創(chuàng)建一個只讀鏈，可以查詢信息（交易和狀態(tài)）但是不可以提交新的交易。

Params

+ None

Returns （是否只讀）

+ (bool): is ready-only (true) or not

• query_info（查詢信息）

查詢鏈的狀態(tài)（高度，已知的節(jié)點）中多種有用信息。

Params

+ none

Returns

+ (ChainInfo) with height, currently the only useful info (高度，當(dāng)前有用的信息)

• query_block（查詢塊）

根據(jù)塊號查詢塊。

Params

+ blockNumber (number)

Returns

+ Object containing the block

• query_transaction（查詢交易）

根據(jù)交易號查詢交易。

Params

+ transactionID

Returns

+ TransactionInfo containing the transaction (交易包含的交易信息)

• create_deploy_proposal（創(chuàng)建部署提案）

創(chuàng)建交易提案。通過數(shù)據(jù)（chaincodeID，chaincode 調(diào)用，等）裝配提案，并且使用匹配 ECert 簽名的私鑰簽名提案。

Params

+ chaincode_path (string): path to the chaincode to deploy

+ chaincode_name (string): a custom name to identify the chaincode on the chain

+ fcn (string): name of the chaincode function to call after deploy to

+ initiate the state（chaincode 的方法名，部署后初始化狀態(tài)時要調(diào)用它）

+ args (string[]): arguments for calling the init function designated by “fcn”（上面 fcn 的參數(shù)）

+ sign (Bool): Whether to sign the transaction, default to True

Returns

+ (Proposal): The created Proposal instance or None.

• create_transaction_proposal（創(chuàng)建交易提案）

為交易創(chuàng)建一個提案。通過數(shù)據(jù)（chaincode 名稱，需要調(diào)用的方法，參數(shù)等）裝配提案，并且使用匹配ECert簽名的私鑰給提案簽名。

Params

+ chaincode_name (string): The name given to the target chaincode to invoke（要執(zhí)行的目標(biāo)chaincode的名稱）

+ args (string[]): arguments for calling the “invoke” method on the chaincode（正在調(diào)用執(zhí)行的chaincode上的方法的參數(shù)）

+ Sign (Bool): Whether to sign the transaction, default to True

Returns

+ (Transaction_Proposal instance): The created Transaction_Proposal instance or None.

• send_transaction_proposal（發(fā)送交易提案）

把創(chuàng)建好的提案發(fā)送給節(jié)點去背書。

Params

+ transaction_proposal (Transaction_Proposal): The transaction proposal data（交易提案的數(shù)據(jù)）

+ chain: The target chain whose peers the proposal will be sent to（提案將要發(fā)送給的節(jié)點所在的目標(biāo)鏈）

+ retry (Number): Times to retry when failure, by default to 0 (no retry)（重試次數(shù)，默認(rèn)0）

Returns

+ (Transaction_Proposal_Response response): The response to send proposal request.（發(fā)送提案請求后的響應(yīng)）

• create_transaction (創(chuàng)建交易)

遵從背書策略根據(jù)提案的響應(yīng)信息創(chuàng)建交易。

Params

+ proposal_responses ([Transaction_Proposal_Response]): The array of proposal responses received in the proposal call.（在提案的調(diào)用中返回的響應(yīng)信息的數(shù)組）

Returns

+ (Transaction instance): The created transaction object instance.（創(chuàng)建的交易對象實例）

• send_transaction（發(fā)送交易）

給鏈的排序服務(wù)（由一個或多個排序者節(jié)點組成）發(fā)送交易，然后做共識和提交到賬本的工作。

本調(diào)用是異步的，并且交易提交成功信息是通過塊或者 chaincode 事件通知的。（本方法必須給應(yīng)用程序提供一個響應(yīng)機制關(guān)聯(lián)事件監(jiān)聽器處理“交易已提交”，“交易完成”，“錯誤”等事件。）

下面有兩種有關(guān) fabric 后端的溝通方式，觸發(fā)不同的事件回調(diào)給應(yīng)用程序處理器

排序者服務(wù)的 gRPC 客戶端在“廣播”調(diào)用的請求或響應(yīng)方法中使用常規(guī)的無狀態(tài)的 HTTP 連接。這個方法的實現(xiàn)需要在響應(yīng)中接收到成功確認(rèn)時發(fā)送“交易已提交”事件，或者在接收到錯誤時發(fā)送“錯誤”事件
為了支持 fabric “BLOCK” ”, “CHAINCODE” 和 “TRANSACTION” 事件，這個方法的實現(xiàn)需要和作為內(nèi)部事件樞紐機制一部分的鏈?zhǔn)录垂?jié)點維護一個持久的連接。這些事件應(yīng)該引發(fā)方法給應(yīng)用程序發(fā)送 “完成” 或 “錯誤” 事件。

Params

+ transaction (Transaction): The transaction object constructed above（上面創(chuàng)建的交易對象。）

Returns（一個事件處理，可以關(guān)聯(lián)到應(yīng)用程序事件處理器的）

+ result (EventEmitter): an handle to allow the application to attach event handlers on“submitted”, “complete”, and “error”.

用戶

用戶類代表已經(jīng)通過 注冊證書注冊 和 簽名密鑰簽名 的已登記用戶。注冊證書必須通過區(qū)塊鏈網(wǎng)絡(luò)配置信任的 CA 證書簽名。已注冊用戶（擁有已簽名密鑰和注冊證書）可以引導(dǎo) chaincode 部署，交易和鏈上查詢。

用戶注冊證書可以事先作為部署應(yīng)用程序的一部分從 CA 獲取，或者可以通過它本身的登記程序從可選的 fabric COP ( 已棄用 ) 服務(wù)獲取。

有時用戶認(rèn)證和節(jié)點認(rèn)證會混淆。因為用戶可以利用私鑰，所以用戶身份有代理簽名的能力，而節(jié)點在應(yīng)用程序 /SDKs 上下文中只有驗證簽名的認(rèn)證能力。應(yīng)用程序不能使用節(jié)點身份來簽名因為應(yīng)用程序不能利用節(jié)點身份的私鑰。

什么是用戶認(rèn)證，什么是節(jié)點認(rèn)證？

用戶可以利用私鑰，所以用戶身份有代理簽名的能力

節(jié)點在應(yīng)用程序 /SDKs 上下文中只有驗證簽名的認(rèn)證能力

• get_name（獲取名稱）

獲取成員名稱。從對象實例請求參數(shù)。

Returns (str):

+ The name of the user

• get_roles（獲取角色）

  獲取用戶的角色。它可能是“客戶端”“審計員”這類值的數(shù)組。成員服務(wù)多定義了兩個的角色用來保存節(jié)點成員關(guān)系，如“節(jié)點”和“驗證者”，這兩個沒有暴露給應(yīng)用程序。

Returns (str[]):

The roles for this user

• get_enrollment_certificate（獲取背書證書）

返回底層認(rèn)證證書代表的用戶身份證書。

Params:

+ none

Returns:

+ Certificate in PEM format signed by the trusted CA（返回已信任的CA按PEM格式簽名的證書）

• set_name（設(shè)置名稱）

設(shè)置用戶的名稱/ID。

Params:

+ name (string[): The user name / id.

• set_roles（設(shè)置角色）

按上面定義的角色值設(shè)置用戶角色。

Params:

+ Roles (string[]): The list of roles for the user（入?yún)⒂脩舻慕巧斜怼＃?

• set_enrollment_certificate（設(shè)置背書證書）

設(shè)置用戶的背書證書。

Params:

+ Certificate : The certificate in PEM format signed by the trusted CA（入?yún)⑹潜灰研湃蔚腃A按PEM格式簽名的證書）

• generate_tcerts（生成交易證書）

獲取一系列 TCert，可以在交易中使用。TCert 和交易之間是一對一的關(guān)系。TCert 可以在本地通過 SDK 使用用戶的加密數(shù)據(jù)項生成。

Params

+ count (number): how many in the batch to obtain?（獲取的交易證書的數(shù)量）

+ Attributes (string[]): list of attributes to include in the TCert（TCert包含的屬性的列表）

Returns (TCert[]):

+ An array of TCerts

節(jié)點

節(jié)點類代表了遠(yuǎn)程節(jié)點和它本身網(wǎng)絡(luò)成員的數(shù)據(jù)，即用來驗證簽名的 ECert。節(jié)點成員代表組織，不像用戶成員代表個體。

當(dāng)節(jié)點被創(chuàng)建后，只要配置一個名為 “eventSourceUrl” 的屬性，節(jié)點實例就可以被指定為一個事件源。允許 SDK 自動關(guān)聯(lián)交易事件監(jiān)聽器事件流。

需要說明的是 節(jié)點事件流功能在 節(jié)點層次，不在 鏈 和 chaincode 的層次。

• connectEventSource（連接事件源）

由于幾乎所有節(jié)點都是事件的生產(chǎn)者，當(dāng)創(chuàng)建一個節(jié)點實例時，應(yīng)用可以指定它作為應(yīng)用程序的事件源。只需要鏈上的一個節(jié)點成為事件源，因為鏈上的所有節(jié)點產(chǎn)生的事件相同。本方法告訴 SDK 對于客戶端應(yīng)用程序來說哪一個節(jié)點作為事件源使用。管理與節(jié)點的 EventHub 連接的生命周期是 SDK 的責(zé)任。理解并通知選擇的節(jié)點想接收哪種事件類型以及想使用哪個回調(diào)方法，是客戶端應(yīng)用程序的責(zé)任。

SDK: 管理與節(jié)點的 EventHub 連接的生命周期
客戶端應(yīng)用程序：理解并通知選擇的節(jié)點想接收哪種事件類型以及想使用哪個回調(diào)方法

Params:

+ None

Result:

+ Promise/Future: this gives the app a handle to attach “success” and “error” listeners（應(yīng)用獲得一個處理程序來關(guān)聯(lián)“成功”或“錯誤”的監(jiān)聽器）

• is_event_listened（事件是否已被監(jiān)聽的標(biāo)記）

網(wǎng)絡(luò)調(diào)用可以顯示出是否至少有一個監(jiān)聽器已經(jīng)連接到事件的目標(biāo)節(jié)點。這能幫助應(yīng)用實例在崩潰后恢復(fù)中或者多個實例部署的情況下決定是否需要連接事件源。

備注：這個請求對節(jié)點上事件的生成者有強化作用。不是很理解

Params:

+ eventName (string): required （必需的）
+ chain (Chain): optional （可選的）

Result:（是否已經(jīng)被鏈上的一些應(yīng)用實例監(jiān)聽）

+ (boolean): whether the said event has been listened on by some application instance on that chain

• addListener（添加監(jiān)聽器）

方法為連接到事件源的節(jié)點提供，監(jiān)聽器注冊在 EventCallBack，用以接收事件類型集的回調(diào)。添加監(jiān)聽器的方法可以被執(zhí)行多次來支持不同的 EventCallBack 方法接收不同類型的事件。

說明：以下的參數(shù)在某些語言里是可選的，比如 Java，為監(jiān)聽器接口創(chuàng)建一個實例，并把該實例作為參數(shù)。

Params:

+ eventType : ie. Block, Chaincode, Transaction （事件類型）

+ eventTypeData : Object Specific for event type as necessary, currently needed for “Chaincode” event type, specifying a matching pattern to the event name set in the chaincode(s) being executed on the target Peer, and for “Transaction” event type, specifying the transaction ID （事件類型數(shù)據(jù)：事件類型有必要有一個特定的對象，對于“chaincode”事件類型要求是，在目標(biāo)節(jié)點上執(zhí)行的chaincode中設(shè)置一個指定的事件名匹配范式；對于“Transaction”事件類型，要指定交易ID。）

+ eventCallback : Client Application class registering for the callback.（事件回調(diào)：客戶端應(yīng)用程序類為回調(diào)而注冊的。）

Returns:

+ [event-listener-ref] a reference to the event listener, some language uses an ID (javascript), others uses object reference (Java)（返回值：事件監(jiān)聽器的引用，指向事件監(jiān)聽器的引用，有些語言（javascript）使用ID，其他的語言（Java）使用對象引用。）

• removeListener (移除監(jiān)聽器)

注銷一個監(jiān)聽器

Params:（SDK返回事件監(jiān)聽器的引用）

+ [event-listener-ref] : reference returned by SDK for event listener

Returns:

+ statusFlag: Success / Failure

• get_name (獲取名稱)

獲取節(jié)點名稱。需要對象實例的參數(shù)。

Returns (str):

+ The name of the Peer （Peer 的名稱）

• set_name (設(shè)置名稱)

Set the Peer name / id. （設(shè)置 Peer 的名稱/id）

Params:

+ Name (string): The unique name / id of this Peer.

• get_roles（獲取角色）

獲取節(jié)點參與的用戶的角色。可能的結(jié)果是“client”和“auditor”的數(shù)組。成員服務(wù)多定義了兩個角色來保存節(jié)點成員關(guān)系：“peer”和“validator”，這兩個沒有暴露給應(yīng)用程序。

Returns (str[]):

+ The roles for this user (這個用戶的角色)

• set_roles（設(shè)置角色）

設(shè)置節(jié)點參與的用戶角色。值遵從上面預(yù)定的幾個值。

Params:

+ Roles (string[]): The list of roles for the user（用戶角色列表）

• get_enrollment_certificate（獲取背書證書）

返回底層代表用戶身份的ECert。

Params:

+ none

Returns:

+ Certificate in PEM format signed by the trusted CA

• set_enrollment_certificate（設(shè)置背書證書）

Set the Peer’s enrollment certificate. （設(shè)置 Peer 的背書證書）

Params:

+ Certificate: Certificate in PEM format signed by the trusted CA （入?yún)⑹潜灰研湃蔚腃A按PEM格式簽名的證書）

鍵值存儲（接口）

區(qū)塊鏈應(yīng)用程序需要保存狀態(tài)，包含用戶登記材料（私鑰，CA簽名的證書）。這些狀態(tài)需要被持久化?！癒eyValueStore” 的接口為 SDK 自動保存狀態(tài)提供了一個簡單的機制，這對應(yīng)用程序是有益的。 如果應(yīng)用使用基于軟件密鑰生成器即 CryptoSuite 的實現(xiàn)，那么它需要鍵值存儲。如果應(yīng)用程序還沒有設(shè)置一個存儲系統(tǒng)，SDK 應(yīng)該默認(rèn)使用一個內(nèi)建的實現(xiàn)，比如一個基于本地文件系統(tǒng)的實現(xiàn)。

SDK 也可以在這個鍵值存儲系統(tǒng)里面以可選緩存的方式保存用戶登記材料。但是，如果應(yīng)用程序沒有配置一個鍵值存儲系統(tǒng)，SDK 會把應(yīng)用程序理解成選擇了總是為會話設(shè)置上下文，并且沒有意圖使用默認(rèn)的鍵值存儲。

• set_value（獲取值）

Retrieves a value given a key （獲取一個入?yún)⒌?key 的值）

Params

+ key (str): The name of the key

Returns

Result (Object):

+ The value

• set_value（存入值）

Sets the value （存入值）

Params

+ Key

+ value

Returns

+ Acknowledgement of successful storage of the value （確認(rèn)了值的成功存儲）

加密模塊（接口）

加密模塊打包了 數(shù)字簽名算法 和 非對稱加密方法，消息對稱加密方法，和 hash 以及 MAC。這是為區(qū)塊鏈加密服務(wù)提供者接口的一個鏡像設(shè)計，被 fabric 加密團隊發(fā)表。

默認(rèn)實現(xiàn)當(dāng)前 peer 和 COP 的計劃,并且還有 SDK 的默認(rèn)實現(xiàn)：

• ECDSA: curves “secp256r1” and “secp384r1”
• AES: AES128, AES256 with CBC/CTR/GCM mode key length = 128 bits
• SHA: SHA256, SHA384, SHA3_256, SHA3_384
• generate_key（生成密鑰）

基于這些選項生成一個 key。輸出可以非對稱加密算法的一個密鑰對，或者對稱加密算法的一個密鑰

Params

+ opts (Object): an object that encapsulates two properties, “algorithm” and“ephemeral”.

Returns

+ Result (Key): The key object

• deriveKey (導(dǎo)出密鑰)

Derives a key from k using opts.(從用上述選項中生成的 k 中獲取 一個 key)

Params

+ k (Key)

+ opts (Object)

Returns

+ (Key) derived key (導(dǎo)出 密鑰)

• importKey（導(dǎo)入密鑰）

Imports a key from its raw representation using opts.

Params

+ k (Key)

+ opts (Object)

Returns

+ (Key) An instance of the Key class wrapping the raw key bytes

• getKey（獲取密鑰）

Returns the key this CSP associates to the Subject Key Identifier ski .

Params

+ ski (byte[])

Returns

+ (Key) An instance of the Key class corresponding to the ski

• hash（hash處理）

Hashes messages msg using options opts .

Params

+ msg (byte[])

+ opts (Object) an object that encapsulates property “algorithm” with values for hashing algorithms such as “SHA2” or “SHA3”

Returns

+ (Key) An instance of the Key class corresponding to the ski

• encrypt（加密）

Encrypt plain text.

Params

+ key (Key) public encryption key

+ plainText (byte[])

+ opts (Object)

Returns

+ (byte[]) Cipher text

• decrypt（解密）

Decrypt cipher text.

Params

+ key (Key) private decryption key

+ cipherText (byte[])

+ opts (Object)

Returns

+ (byte[]) Plain text

• sign（簽名）

Sign the data.

Params

+ Key (Key) private signing key

+ digest (byte[]) fixed-length digest of the target message to be signed

+ opts (function) hashing function to use

Returns

+ Result(Object):Signature object

• verify（驗證）

Verify the signature.

Params

+ key (Key) public verification key

+ signature (byte[]) signature

+ digest (byte[]) original digest that was signed

Returns

+ (bool): verification successful or not

處理網(wǎng)絡(luò)錯誤

客戶端 SDK 和 fabric 用兩個方法溝通：無狀態(tài)的 HTTP 連接和 HTTP 長連接。

發(fā)送提案和發(fā)送交易調(diào)用在請求/響應(yīng)中是無狀態(tài)的。如果出現(xiàn)網(wǎng)絡(luò)錯誤，調(diào)用會超時。SDK 應(yīng)該有一個可配置的超時時間，方便應(yīng)用程序基于對客戶端應(yīng)用和 fabric 節(jié)點之間的網(wǎng)絡(luò)特征的理解控制調(diào)用的動作。

另外，這些方法可能有一個重試次數(shù)，以便于 SDK 根據(jù)超時錯誤自動試圖重連 HTTP 調(diào)用。這些重試都嘗試并且仍然發(fā)生超時錯誤之后，連接方法應(yīng)該返回一個錯誤。

另一方面，事件流連接 SDK 和事件源節(jié)點是長連接。特別地，由于事件流接口被 fabric 定義，連接是雙向的，允許消息發(fā)送到兩方。對于網(wǎng)絡(luò)錯誤，以防丟失事件和不能觸發(fā) client 應(yīng)用注冊的監(jiān)聽器的結(jié)果，連接會被斷開。

為應(yīng)用的利益考慮SDK應(yīng)該試圖重新發(fā)起連接。但是，如果在嘗試了重連次數(shù)之后不能恢復(fù)連接，應(yīng)該用一個高級別的嚴(yán)重錯誤通知應(yīng)用這種情況。

參考

1. Next-Consensus-Architecture_Proposal

2. Consensus endorsing, consenting, and committing model

3. Node.js SDK

4. Fabric-Cop Design 這篇文檔已棄用

5. Next Hyperledger-Fabric Architecture Protocol messages