Hyperledger Fabric 管理鏈碼 peer lifecycle chaincode 指令使用

鏈上代碼（Chaincode）簡稱鏈碼，包括系統(tǒng)鏈碼和用戶鏈碼。系統(tǒng)鏈碼（System Chaincode）指的是Fabric Peer中負責系統(tǒng)配置、查詢、背書、驗證等平臺功能的代碼邏輯，運行在Peer進程內(nèi)，將在第14章介紹。用戶鏈碼指的是用戶編寫的用來實現(xiàn)智能合約的應用代碼。如無特殊說明，鏈碼一般指的就是用戶鏈碼。

鏈碼被部署在Peer節(jié)點上，運行在獨立的沙盒（目前為Docker容器）中，并通過gRPC協(xié)議與相應的Peer節(jié)點進行交互。用戶可以通過命令行或SDK調(diào)用鏈碼方法，鏈碼被調(diào)用時，會按照鏈碼內(nèi)預定邏輯來計算賬本狀態(tài)的更新集合（讀寫集合）。

鏈碼操作命令

Operate a chaincode: install|instantiate|invoke|package|query|signpackage|upgrade|list.Usage:peer chaincode [command]Available Commands:install Install a chaincode.instantiate Deploy the specified chaincode to the network.invoke Invoke the specified chaincode.list Get the instantiated chaincodes on a channel or installed chaincodes on a peer.package Package a chaincodequery Query using the specified chaincode.signpackage Sign the specified chaincode packageupgrade Upgrade chaincode.Flags:--cafile string Path to file containing PEM-encoded trusted certificate(s) for the ordering endpoint--certfile string Path to file containing PEM-encoded X509 public key to use for mutual TLS communication with the orderer endpoint--clientauth Use mutual TLS when communicating with the orderer endpoint--connTimeout duration Timeout for client to connect (default 3s)-h, --help help for chaincode--keyfile string Path to file containing PEM-encoded private key to use for mutual TLS communication with the orderer endpoint-o, --orderer string Ordering service endpoint--ordererTLSHostnameOverride string The hostname override to use when validating the TLS connection to the orderer--tls Use TLS when communicating with the orderer endpoint--tlsHandshakeTimeShift duration The amount of time to shift backwards for certificate expiration checks during TLS handshakes with the orderer endpoint--transient string Transient map of arguments in JSON encodingUse "peer chaincode [command] --help" for more information about a command.

最簡單的操作鏈碼的方式是使用命令行。Fabric自2.0版本開始正式啟用新的生命周期系統(tǒng)鏈碼（位于core/chaincode/lifecycle）來管理鏈碼（需開啟應用能力V2_0），客戶端通過新的 peer lifecycle chaincode 子命令（位于internal/peer/lifecycle）對鏈碼進行打包、安裝、批注和提交等生命周期管理，取代1.x中的 peer chaincode 命令。

相對1.x版本中的模式，新的鏈碼管理從單個組織升級為通道范疇。例如，鏈碼的背書策略可由通道內(nèi)多個組織來商定，部署和升級也作為通道層面的操作，這些都提高了鏈碼生命周期的安全性。如果要對鏈碼進行調(diào)用或查詢，仍可以使用原有的peer chaincode invoke 和 peer chaincode query 命令。

如果要使用1.x版本中的鏈碼生命周期管理（peer chaincodeinstall/instantaite/upgrade/list等命令），需要將通道的應用能力版本設(shè)置為兼容的低版本，如V1_4_2。當通道啟用了應用能力V2_0后，將無法再部署或升級原有模式下的鏈碼。

鏈碼生命周期：

鏈碼操作支持全局命令選項：

全局選項 類型 含義

--cafile	string	信任的排序服務的 TLS CA 的證書（PEM編碼格式）路徑
--certfile	string	與排序服務進行雙向 TLS 認證時使用的本地證書文件路徑
--clientauth	bool	與排序服務通信時是否啟用雙向 TLS 認證
--connTimeout	duration	客戶端連接超時，默認為 3 秒
--keyfile	string	與排序服務雙向 TLS 認證時使用的本地私鑰文件路徑
-o,--orderer	string	Orderer 服務地址
--ordererTLSHostnameOverride	string	驗證 Orderer TLS 時覆蓋所校驗的主機名
--tls	bool	連接到 Orderer 服務時是否啟用 TLS
--transient	string	調(diào)用鏈碼時傳遞的臨時信息,其他 peer 將無法獲取該信息

---

打包鏈碼

package 子命令可以封裝鏈碼相關(guān)的數(shù)據(jù)，將其打包為.tar.gz安裝包，供安裝使用。

Package a chaincode and write the package to a file.Usage:peer chaincode package [outputfile] [flags]Flags:-s, --cc-package create CC deployment spec for owner endorsements instead of raw CC deployment spec-c, --ctor string Constructor message for the chaincode in JSON format (default "{}")-h, --help help for package-i, --instantiate-policy string instantiation policy for the chaincode-l, --lang string Language the chaincode is written in (default "golang")-n, --name string Name of the chaincode-p, --path string Path to chaincode-S, --sign if creating CC deployment spec package for owner endorsements, also sign it with local MSP-v, --version string Version of the chaincode specified in install/instantiate/upgrade commandsGlobal Flags:--cafile string Path to file containing PEM-encoded trusted certificate(s) for the ordering endpoint--certfile string Path to file containing PEM-encoded X509 public key to use for mutual TLS communication with the orderer endpoint--clientauth Use mutual TLS when communicating with the orderer endpoint--connTimeout duration Timeout for client to connect (default 3s)--keyfile string Path to file containing PEM-encoded private key to use for mutual TLS communication with the orderer endpoint-o, --orderer string Ordering service endpoint--ordererTLSHostnameOverride string The hostname override to use when validating the TLS connection to the orderer--tls Use TLS when communicating with the orderer endpoint--tlsHandshakeTimeShift duration The amount of time to shift backwards for certificate expiration checks during TLS handshakes with the orderer endpoint--transient string Transient map of arguments in JSON encoding

其中，生成的打包文件中包括Chaincode-Package-Metadata.json、Code-Package.tar.gz兩個文件。Chaincode-Package-Metadata.json內(nèi)容包括鏈碼路徑、類型、標簽等信息.Code-Package.tar.gz內(nèi)容包括鏈碼的源碼包結(jié)構(gòu)，如src/examples/chaincode/go/testcc/路徑以及內(nèi)容，但不能包括對目錄以外路徑的引用。

注意:自2.0版本起，編譯鏈碼的ccenv鏡像不再包括shim層。鏈碼需要自行包括github.com/hyperledger/fabric-chaincode-go/shim和其他所需要的依賴包。

---

安裝鏈碼

打包后的鏈碼安裝包文件，可以使用install命令安裝到運行鏈碼的各個Peer。

Install a chaincode on a peer. This installs a chaincode deployment spec package (if provided) or packages the specified chaincode before subsequently installing it.Usage:peer chaincode install [flags]Flags:--connectionProfile string Connection profile that provides the necessary connection information for the network. Note: currently only supported for providing peer connection information-c, --ctor string Constructor message for the chaincode in JSON format (default "{}")-h, --help help for install-l, --lang string Language the chaincode is written in (default "golang")-n, --name string Name of the chaincode-p, --path string Path to chaincode--peerAddresses stringArray The addresses of the peers to connect to--tlsRootCertFiles stringArray If TLS is enabled, the paths to the TLS root cert files of the peers to connect to. The order and number of certs specified should match the --peerAddresses flag-v, --version string Version of the chaincode specified in install/instantiate/upgrade commandsGlobal Flags:--cafile string Path to file containing PEM-encoded trusted certificate(s) for the ordering endpoint--certfile string Path to file containing PEM-encoded X509 public key to use for mutual TLS communication with the orderer endpoint--clientauth Use mutual TLS when communicating with the orderer endpoint--connTimeout duration Timeout for client to connect (default 3s)--keyfile string Path to file containing PEM-encoded private key to use for mutual TLS communication with the orderer endpoint-o, --orderer string Ordering service endpoint--ordererTLSHostnameOverride string The hostname override to use when validating the TLS connection to the orderer--tls Use TLS when communicating with the orderer endpoint--tlsHandshakeTimeShift duration The amount of time to shift backwards for certificate expiration checks during TLS handshakes with the orderer endpoint--transient string Transient map of arguments in JSON encoding 參數(shù) 類型 含義

-- connectionProfile	string	網(wǎng)絡(luò)訪問信息文件路徑，目前僅支持 peer 連接信息
-- peerAddresses	stringArray	請求所發(fā)往的 peer 地址列表
--tlsRootCertFiles	stringArray	所連接的 peer 的信任 TLS 根證書

Peer會嘗試編譯鏈碼，如果編譯成功，則將安裝包以二進制的形式儲存到指定路徑的chaincodes子目錄下，并利用元數(shù)據(jù)標簽和安裝包生成的SHA256值作為文件名。

Peer會嘗試編譯鏈碼，如果編譯成功，則將安裝包以二進制的形式儲存到指定路徑的chaincodes子目錄下，并利用元數(shù)據(jù)標簽和安裝包生成的SHA256值作為文件名。

注意，安裝操作需要是Peer認可的組織管理員身份（證書在Peer的admincerts目錄下存在）。

---

查詢和批準鏈碼

通道內(nèi)組織在部署鏈碼前需要足夠多的組織管理員對鏈碼定義進行投票批準。鏈碼定義包括鏈碼名稱、版本、序列號、背書和驗證參數(shù)、是否需要初始化、鏈碼包Id，以及可能帶有的私密數(shù)據(jù)集合配置等。操作涉及queryinstalled、getinstalled-package、approveformyorg、checkcommitrea-diness四個鏈碼生命周期子命令。

queryinstalled子命令可以查詢目標Peer上已經(jīng)安裝的鏈碼信息。支持的參數(shù)包括：

●--connectionProf ile string，網(wǎng)絡(luò)訪問信息文件路徑，目前僅支持Peer連接信息。

●-O,--output string，結(jié)果輸出的格式，目前支持格式化為json格式。

●--peerAddresses stringArray，請求所發(fā)往的Peer地址列表。

●--tlsRootCertFiles stringArray，所連接的Peer的信任的TLS根證書。getinstalledpackage子命令可以獲取指定的鏈碼安裝包（與發(fā)送給Peer的安裝包內(nèi)容相同）。支持參數(shù)包括：

●--connectionProf ile string，網(wǎng)絡(luò)訪問信息文件路徑，目前僅支持Peer連接信息。

●--output-directory string，將獲取到的鏈碼安裝包保存到指定路徑，默認為當前路徑。

●--package-id string，所要獲取的鏈碼安裝包的ID。

●--peerAddresses stringArray，請求所發(fā)往的Peer地址列表。

●--tlsRootCertFiles stringArray，所連接的Peer的信任的TLS根證書。

approveformyorg子命令允許用戶將鏈碼的定義發(fā)送給Peer進行背書，通過后發(fā)給Orderer進行排序和確認。所有需要執(zhí)行鏈碼的組織都需要完成此步驟。默認情況下，只有通道內(nèi)大多數(shù)組織（通道內(nèi)的Channel/Application/LifecycleEndorsement策略指定，默認為通道內(nèi)大多數(shù)成員）都批準了鏈碼定義，對應鏈碼才能在通道內(nèi)部署運行。支持的參數(shù)包括：

●--channel-config-policy string，指定鏈碼的背書策略名稱，該策略名稱需要提前存儲在通道策略配置中，默認為Channel/Application/Endorsement策略（默認為通道內(nèi)大多數(shù)成員組織背書）。

●-C,--channelID string，執(zhí)行命令面向的通道名稱。

●--collections-conf ig string，啟用私密數(shù)據(jù)功能時，指定集合文件的路徑。

●--connectionProf ile string，網(wǎng)絡(luò)訪問信息文件路徑，目前僅支持Peer連接信息。

●-E,--endorsement-plugin string，鏈碼所使用的背書插件的名稱。

●--init-required，是否需要調(diào)用Init方法對鏈碼進行初始化。

●-n,--name string，鏈碼名稱。

●--package-id string，鏈碼安裝包的名稱。

●--peerAddresses stringArray，所連接的Peer節(jié)點列表。

●--sequence int，通道內(nèi)對鏈碼進行定義的序列號（默認為1），每次更新鏈碼定義則需要遞增。

●--signature-policy string，指定鏈碼的（基于簽名的）背書策略，默認采用Channel/Application/Endorsement指定的策略（默認為通道內(nèi)大多數(shù)成員組織背書），不能與--channel-conf ig-policy同時使用。

●--tlsRootCertFiles stringArray，連接Peer啟用TLS時，所信任的TLS根證書列表（注意與Peer地址順序匹配）。

●-V,--validation-plugin string，鏈碼所使用的校驗系統(tǒng)插件名稱。

●--waitForEvent，是否等待事件以確認交易在各個Peer提交（默認開啟）。

●--waitForEventTimeout duration，等待事件的時間（默認為30s）。

checkcommitreadiness子命令可以獲取指定的鏈碼安裝包當前的批準狀態(tài)，調(diào)用_lifecycle鏈碼CheckCommitReadiness方法（位于core/chaincode/lifecycle/scc.go）。支持參數(shù)與approveformyorg子命令類似。

---

提交鏈碼并查詢狀態(tài)

通道內(nèi)鏈碼得到足夠多的組織批準后，將成為可以合法運行的鏈碼。此時，任意通道內(nèi)組織可以使用commit子命令發(fā)起提交操作。鏈碼定義被成功提交到通道后，通道內(nèi)成員可以使用鏈碼（如進行調(diào)用）。支持的參數(shù)包括：

●--channel-config-policy string，指定鏈碼的背書策略名稱，該策略名稱需要提前存儲在通道策略配置中，默認為Channel/Application/Endorsement策略（默認為通道內(nèi)大多數(shù)成員組織背書）。

●-C,--channelID string，執(zhí)行命令面向的通道名稱。

●--collections-conf ig string，啟用私密數(shù)據(jù)功能時，指定集合文件的路徑。

●--connectionProf ile string，網(wǎng)絡(luò)訪問信息文件路徑，目前僅支持Peer連接信息。

●-E,--endorsement-plugin string，鏈碼所使用的背書插件的名稱。

●--init-required，是否需要調(diào)用Init方法對鏈碼進行初始化。

●-n,--name string，鏈碼名稱。

●--package-id string，鏈碼安裝包的名稱。

●--peerAddresses stringArray，所連接的Peer節(jié)點列表。

●--sequence int，通道內(nèi)對鏈碼進行定義的序列號（默認為1），每次更新鏈碼定義則需要遞增。

●--signature-policy string，指定鏈碼的（基于簽名的）背書策略，默認采用Channel/Application/Endorsement指定的策略（默認為通道內(nèi)大多數(shù)成員組織背書），不能與--channel-conf ig-policy同時使用。

●--tlsRootCertFiles stringArray，連接Peer啟用TLS時，所信任的TLS根證書列表（注意與Peer地址順序匹配）。

●-V,--validation-plugin string，鏈碼所使用的校驗系統(tǒng)插件名稱。

●--waitForEvent，是否等待事件以確認交易在各個Peer提交（默認開啟）。

●--waitForEventTimeout duration，等待事件的時間（默認為30s）。

●-C,--channelID string，執(zhí)行命令的通道名稱。

●--connectionProf ile string，網(wǎng)絡(luò)訪問信息文件路徑，目前僅支持Peer連接信息。

●-n,--name string，鏈碼名稱。

●-O,--output string，結(jié)果輸出的格式，目前支持json格式。

●--peerAddresses stringArray，所連接的Peer地址列表。

●--tlsRootCertFiles stringArray，連接Peer啟用TLS時，所信任的TLS根證書列表（注意與Peer地址順序匹配）。

首先使用commit子命令提交已經(jīng)得到批準的鏈碼定義，然后使用querycommitted子命令查詢提交狀態(tài)

---

使用私有數(shù)據(jù)

在批準和提交鏈碼定義時，可以通過--collections-conf ig collection.json來指定與私密數(shù)據(jù)相關(guān)的集合配置（Fabric v1.1.0開始支持），可以實現(xiàn)在同一通道內(nèi)私密數(shù)據(jù)的調(diào)用只有部分成員共享。如果不指定該參數(shù)則默認不啟用該特性，意味著通道內(nèi)所有成員都可以看到鏈碼調(diào)用結(jié)果。

collections_config.json 配置文件示例 :

[{"name": "collection1", // 集合名稱"policy": "OR('Org1MSP.member')", // 集合成員"requiredPeerCount": 0, // 背書之前至少擴散私有數(shù)據(jù)到的節(jié)點數(shù)"maxPeerCount": 3, // 背書之前嘗試擴散最多節(jié)點個數(shù), 不能小于 requiredPeerCount"blockToLive": 1000000, // 私有數(shù)據(jù)保存時長 0 意味著永不過期"memberOnlyRead": true, // 是否只允許集合成員來讀取私有數(shù)據(jù)"memberOnlyWrite": true ，// 是否只允許集合成員來發(fā)起對私有數(shù)據(jù)的寫交易"endorsementPolicy": "OR('Org1MSP.member')" ,// 指定對私有數(shù)據(jù)寫操作時的背書策略"signaturePolicy": "OR('Org1MSP.member')" // 指定使用簽名策略 },{"name": "collection2","policy": "OR('Org2MSP.member')","requiredPeerCount": 0,"maxPeerCount": 3,"blockToLive": 1,"memberOnlyRead": true} ]

其中，collection.json中定義了collection1和collection2兩個集合，其成員分別為Org1、Org2兩個組織。當在鏈碼邏輯中指定某個鍵值屬于特定集合時，只有集合內(nèi)成員能看到明文的讀寫集合，非集合成員即使在同一通道內(nèi)也無法獲取私密數(shù)據(jù)。對應policy只支持OR語法，指定哪些組織可以看到私密數(shù)據(jù)集合。

requiredPeerCount和maxPeerCount指定了在執(zhí)行背書過程中嘗試擴散數(shù)據(jù)到其他合法節(jié)點的個數(shù)，避免因背書節(jié)點的突然故障而導致私密數(shù)據(jù)丟失。背書階段未獲取私密數(shù)據(jù)的合法節(jié)點，在提交階段會嘗試從其他節(jié)點來拉取私密數(shù)據(jù)。

---

調(diào)用鏈碼

通過 peer chaincode invoke 命令（實現(xiàn)位于internal/peer/chaincode）可以調(diào)用運行中鏈碼定義的方法，所指定的函數(shù)名和參數(shù)會被傳到鏈碼的Invoke()方法進行處理。調(diào)用鏈碼操作需要同時與Peer和Orderer打交道。

Invoke the specified chaincode. It will try to commit the endorsed transaction to the network.Usage:peer chaincode invoke [flags]Flags:-C, --channelID string The channel on which this command should be executed--connectionProfile string Connection profile that provides the necessary connection information for the network. Note: currently only supported for providing peer connection information-c, --ctor string Constructor message for the chaincode in JSON format (default "{}")-h, --help help for invoke-I, --isInit Is this invocation for init (useful for supporting legacy chaincodes in the new lifecycle)-n, --name string Name of the chaincode--peerAddresses stringArray The addresses of the peers to connect to--tlsRootCertFiles stringArray If TLS is enabled, the paths to the TLS root cert files of the peers to connect to. The order and number of certs specified should match the --peerAddresses flag--waitForEvent Whether to wait for the event from each peer's deliver filtered service signifying that the 'invoke' transaction has been committed successfully--waitForEventTimeout duration Time to wait for the event from each peer's deliver filtered service signifying that the 'invoke' transaction has been committed successfully (default 30s)Global Flags:--cafile string Path to file containing PEM-encoded trusted certificate(s) for the ordering endpoint--certfile string Path to file containing PEM-encoded X509 public key to use for mutual TLS communication with the orderer endpoint--clientauth Use mutual TLS when communicating with the orderer endpoint--connTimeout duration Timeout for client to connect (default 3s)--keyfile string Path to file containing PEM-encoded private key to use for mutual TLS communication with the orderer endpoint-o, --orderer string Ordering service endpoint--ordererTLSHostnameOverride string The hostname override to use when validating the TLS connection to the orderer--tls Use TLS when communicating with the orderer endpoint--tlsHandshakeTimeShift duration The amount of time to shift backwards for certificate expiration checks during TLS handshakes with the orderer endpoint--transient string Transient map of arguments in JSON encoding

注意，invoke是異步操作，invoke成功只能保證交易已經(jīng)進入Orderer進行排序，但無法保證最終寫到賬本中（例如交易未通過Committer驗證而被拒絕）。需要通過事件監(jiān)聽或主動查詢等方式來進行確認交易是否最終寫到賬本上。

---

查詢鏈碼

查詢鏈碼可以通過 peer chaincode query 子命令。

該子命令實際上是invoke操作與Peer打交道的部分，即將簽名后的Proposal發(fā)給指定的Peer節(jié)點的ProcessProposal()gRPC接口。最終將-c指定的命令參數(shù)發(fā)送給了鏈碼中的Invoke()方法執(zhí)行。

query操作與invoke操作的區(qū)別在于，query操作用來查詢Peer上賬本狀態(tài)（需要鏈碼支持查詢邏輯），不生成交易，也不需要與Orderer打交道。同時，query命令默認只返回第一個Peer的查詢結(jié)果。

Get endorsed result of chaincode function call and print it. It won't generate transaction.Usage:peer chaincode query [flags]Flags:-C, --channelID string The channel on which this command should be executed--connectionProfile string Connection profile that provides the necessary connection information for the network. Note: currently only supported for providing peer connection information-c, --ctor string Constructor message for the chaincode in JSON format (default "{}")-h, --help help for query-x, --hex If true, output the query value byte array in hexadecimal. Incompatible with --raw-n, --name string Name of the chaincode--peerAddresses stringArray The addresses of the peers to connect to-r, --raw If true, output the query value as raw bytes, otherwise format as a printable string--tlsRootCertFiles stringArray If TLS is enabled, the paths to the TLS root cert files of the peers to connect to. The order and number of certs specified should match the --peerAddresses flagGlobal Flags:--cafile string Path to file containing PEM-encoded trusted certificate(s) for the ordering endpoint--certfile string Path to file containing PEM-encoded X509 public key to use for mutual TLS communication with the orderer endpoint--clientauth Use mutual TLS when communicating with the orderer endpoint--connTimeout duration Timeout for client to connect (default 3s)--keyfile string Path to file containing PEM-encoded private key to use for mutual TLS communication with the orderer endpoint-o, --orderer string Ordering service endpoint--ordererTLSHostnameOverride string The hostname override to use when validating the TLS connection to the orderer--tls Use TLS when communicating with the orderer endpoint--tlsHandshakeTimeShift duration The amount of time to shift backwards for certificate expiration checks during TLS handshakes with the orderer endpoint--transient string Transient map of arguments in JSON encoding

---

升級鏈碼

鏈碼升級過程需要重復peer lifecycle chaincode相關(guān)命令，來執(zhí)行完整的生命周期，具體步驟如下：

1）更新舊版本鏈碼的源代碼，并重新打包鏈碼包。

2）將新的鏈碼包再次安裝到Peer，獲取新的包Id。注意，相對舊版本要遞增版本號。

3）按照策略，通道內(nèi)足夠多組織都要重新對新版本的鏈碼定義進行批準。注意，序列號要遞增。

4）通道內(nèi)足夠多組織批準定義后，可以提交新版本鏈碼定義到通道。

5）再次調(diào)用鏈碼，確保鏈碼已經(jīng)自動更新為新的版本。

總結(jié)

以上是生活随笔為你收集整理的Hyperledger Fabric 管理链码 peer lifecycle chaincode 指令使用的全部內(nèi)容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網(wǎng)站內(nèi)容還不錯，歡迎將生活随笔推薦給好友。