← COMP5565 全部讲次
L07b-1 · 第 10 周

L07b-1 Chaincode:用 Go 写合约,Submit 和 Evaluate 怎么选

一个 chaincode 可装多个智能合约;改账本走 SubmitTransaction,经背书和排序;只读走 EvaluateTransaction,只问一个 peer;读 sample chaincode 的输出顺序。

一句话版

chaincode 是跑在 peer 上的合约代码,应用通过 Gateway 调它。要改账本就 Submit,走完背书和排序;只想查就 Evaluate,问一个 peer 立刻拿结果。

前四页搭好了身份体系,这一页开始写跑在网络上的代码。

先认识这几个词

词 读法 / 全称 一句人话
smart contract 智能合约 用代码写下的组织间规则
chaincode 链码 装合约的部署单位,一个可装多个合约
Fabric Gateway 网关 应用和 peer、排序服务之间的中间人
SubmitTransaction 提交交易 会改账本的调用,要背书和排序
EvaluateTransaction 评估交易 只读的调用,问一个 peer 就回
world state 世界状态 每个键当前值的数据库
GetState / PutState 读状态 / 写状态 按键读一个值 / 写一个键值对

一个类比:银行柜台办业务

你去银行办两类业务。

转账要改账,柜员先请几位主管分别核对签字,签齐了交给后台统一按顺序记账。账记进总账才算数。这是 SubmitTransaction:背书 peer 签字,排序服务排顺序,验证后写进 world state。

查余额不改账,随便找一个窗口,柜员看一眼自己手上的账本副本就告诉你,不用主管签字,也不进总账。这是 EvaluateTransaction。

银行的规章手册是 chaincode,手册里可以有好几章,转账一章、开户一章,这些章就是 smart contract。手册发下去以后,每一章都能用。

类比在哪里失效:

  • 银行查余额看的是唯一的总账,Evaluate 问的是一个 peer 的本地副本,这个 peer 还没同步到最新块时,查到的可能是旧值
  • 银行主管签字是人工审核,背书 peer 是真的把 chaincode 跑一遍,签的是执行结果
  • 银行柜员可以通融,chaincode 按代码执行,没有例外

从零讲起

1. smart contract 和 chaincode

它解决什么问题

几个组织要在同一本账上做生意,得先把规则写成大家都执行的代码。规则可能有好几套,比如资产一套、订单一套,部署时又希望一次打包上去。

从哪来(补充)

Hyperledger 是 Linux Foundation 在 2015 年 12 月宣布成立的开源区块链项目。Fabric 是其中的许可制区块链,代码最初由 IBM 和 Digital Asset 贡献。出处见 Wikipedia:Hyperledger。

直觉

智能合约用可执行代码定义不同组织之间的规则,应用调用它,生成记进账本的交易。

chaincode 是部署单位。一个 chaincode 里可以定义多个智能合约,部署后其中所有合约都对应用可用。Fabric 用户常把两个词混用,严格说一个指规则,一个指装规则的包。

一步一步看

目标:从用 Go 写合约到部署上 channel 走一遍,看出 smart contract、chaincode、应用三层各是什么。

从写到用,分这几步:

  1. 用 Go 写合约,课件用的是 fabric-contract-api-go 库
  2. 把一个或多个合约打包成一个 chaincode
  3. 外面包一个应用,负责部署、初始化等工作,类比以太坊里用 Javascript 加 Hardhat 部署合约
  4. 部署到 channel 上,每个合约都能被应用调用
层 是什么 课件例子
smart contract 一套业务规则 SmartContract,管资产的增删改查
chaincode 部署包 asset-transfer-basic 的 Go chaincode
应用 部署和调用 chaincode 的程序 同样用 Go 写,经 Gateway 调用

应用和 chaincode 可以用不同语言写,课件的例子里两者都用 Go。

怎么判断

一个 chaincode 部署一次 = 包里所有 smart contract 都可调用

意思是:问「能不能调某个合约」,先看它在不在已部署的 chaincode 里,不需要为每个合约单独部署。

常见误解

误解:一个 chaincode 只能放一个合约

可以放多个。部署一次,里面每个合约都能被应用调用。两个词常混用,但 chaincode 指部署包,smart contract 指包里的业务规则。

试一下

一个 chaincode 里有资产合约和订单合约,部署后应用能调订单合约吗?

能。chaincode 部署后,其中所有智能合约都对应用可用。

2. SubmitTransaction 和 EvaluateTransaction

它解决什么问题

改账本必须让多个组织都认可,代价高;查账本只是读一下,没必要兴师动众。两种需求要走不同的路。

直觉

Submit 走完整的背书、排序、验证流程,结果写进账本。Evaluate 只找一个 peer 问一下,结果直接回给应用,账本不动。

一步一步看

目标:分别走一遍 SubmitTransaction 和 EvaluateTransaction,看出改账要过背书和排序,查账只问一个 peer。

SubmitTransaction 与 EvaluateTransaction 两条路径对比:Submit 经 Gateway 找背书 peer、执行签名、交排序服务进块后更新 world state;Evaluate 只问一个 peer、查本地副本直接返回

Submit 这条路:

  1. 应用调 contract.SubmitTransaction,例如课件里的 SubmitTransaction(“InitLedger”)
  2. Gateway 用 service discovery 找到这个 chaincode 所需的背书 peer 集合
  3. 在所需数量的 peer 上执行 chaincode,收集背书
  4. 把交易交给排序服务,进块、验证通过后更新 world state

Evaluate 这条路:

  1. 应用调 contract.EvaluateTransaction,例如 EvaluateTransaction(“GetAllAssets”)
  2. Gateway 挑一个 peer,查它本地的账本副本
  3. 把结果返回应用,不发给排序服务,也不更新账本

课件说从 v2.4 起,应用用 evaluateTransaction() 做只读查询。

怎么判断

这次调用会改 world state 吗?会 → Submit;不会 → Evaluate

意思是:只看有没有写操作。只读查询用 Submit 也能跑,但会白白多走背书、排序和进块,结果还要等进块才返回。

常见误解

误解:Evaluate 也会留下一条交易记录

不会。Evaluate 不经排序服务,也不更新账本,链上不会多出任何东西。只有 Submit 的交易会进块。

试一下

一个只读查询用 Submit 调,会多走哪几步?

会多走背书收集、提交排序服务、进块和验证这几步。结果要等进块才算数,比 Evaluate 慢得多。

3. 读写状态的 API

它解决什么问题

chaincode 要读写 world state,需要一组 API。哪些会改状态、哪些只读,决定了应用该用 Submit 还是 Evaluate 去调。

直觉

写的只有两个:PutState 创建或更新一个键值对,DelState 删一个。其余都是读:取一个键、取多个键、取一段范围、按复合键前缀取、富 JSON 查询、取某个键的历史。

一步一步看

目标:读 ReadAsset 和 GetAllAssets 两个查询,看出按键取值和按范围扫描怎么写,哪些 API 该用 Submit 调用。

GetState 与 GetStateByRange 对比:左边 GetState 按一个键从 world state 取一个值;右边 GetStateByRange 用空串作上下界,按顺序扫全部键,返回要逐条 Next 的迭代器,用完 Close

以课件 sample chaincode 里的两个查询为例:

  1. ReadAsset 调 GetState(id),按一个键取回一个值,是 JSON 字节,没有这个键就返回空
  2. GetAllAssets 调 GetStateByRange(“”, “”),起止键都给空串,就是不设上下界
  3. 它返回一个迭代器,循环里用 HasNext() 判断、Next() 取下一条
  4. 每条取出来反序列化成 Asset,追加进结果
  5. 用完调 Close() 关掉迭代器

课件的 Chaincode API 表给每个 API 标了推荐调用方式:

API 作用 推荐
PutState(key, value) 创建或更新键值对 Submit
DelState(key) 删键值对 Submit
GetState(key) 取一个键的值 Evaluate
GetMultipleStates(keys…) 取多个键 Evaluate
GetStateByRange(start, end) 取键范围 Evaluate
GetStateByPartialCompositeKey(…) 按复合键前缀取 Evaluate
GetQueryResult(query) 富 JSON 查询,用于 CouchDB 一类状态数据库 Evaluate
GetHistoryForKey(key) 取某键的历史修改 Evaluate

怎么判断

函数里用了 PutState 或 DelState → 推荐 Submit;只用 Get 系列 → 推荐 Evaluate

意思是:看 chaincode 函数内部调了哪些 API,就知道应用该怎么调这个函数。

常见误解

误解:读 API 只能放在 Evaluate 里

表里写的是「推荐」。读操作也可以出现在 Submit 的交易里,比如先读余额再写新余额。这时读到的键会进读集,参与背书后的读写集验证。

试一下

查一个资产被谁改过、改过几次,用哪个 API?推荐怎么调?

用 GetHistoryForKey(key),推荐 EvaluateTransaction。

4. InitLedger 和字段字母序

它解决什么问题

多个背书 peer 各自执行 chaincode,结果要逐字节一致才算同一份背书。把一个 struct 序列化成 JSON 时,字段顺序一变,字节就变了。

直觉

课件的 Asset struct 有五个字段,按字母序声明:AppraisedValue int、Color string、ID string、Owner string、Size int。

Go 序列化 JSON 时保持字段的声明顺序,但不会自动排序。按字母序声明,别的语言写的 chaincode 也按字母序输出,跨语言就能保持确定性。

一步一步看

目标:跟着 InitLedger 写入六个资产再用 GetAllAssets 读回,看出读回的字段顺序和赋值顺序无关,始终按字母序排。

InitLedger 写入六个资产:asset1 到 asset6 各带颜色和估值,每个都经 json.Marshal 后 PutState 写入,写集里有六个键,背书、排序、验证通过后才写进 world state

跟着 InitLedger 走一遍:

  1. 函数里构造六个资产,构造时写的字段顺序是 ID、Color、Size、Owner、AppraisedValue
  2. 对每个资产调 json.Marshal,得到 JSON 字节
  3. 调 PutState(asset.ID, assetJSON) 写入,写集里一共六个键
  4. 背书、排序、验证通过后,六个资产才写进 world state
  5. 之后调 GetAllAssets,每个对象的字段顺序仍是 AppraisedValue、Color、ID、Owner、Size
环节 字段顺序
struct 声明 AppraisedValue、Color、ID、Owner、Size
InitLedger 里赋值 ID、Color、Size、Owner、AppraisedValue
GetAllAssets 输出 AppraisedValue、Color、ID、Owner、Size

怎么判断

JSON 输出的字段顺序 = struct 的声明顺序,与赋值顺序无关

意思是:要读懂 sample chaincode 的输出,先看 struct 怎么声明的。想让不同语言的 chaincode 输出一致,就都按字母序声明。

常见误解

误解:JSON 字段顺序无所谓

对一般应用无所谓,在 Fabric 里有所谓。多个背书 peer 各自执行 chaincode,结果要逐字节一致才算同一份背书。字段顺序不同,签出来的结果就对不上。

试一下

在 InitLedger 里把赋值顺序改成 Owner 在前,输出的字段顺序会变吗?

不会。输出顺序由 struct 的声明顺序决定,赋值顺序不影响。

把它们串起来

从部署到查询,整条链路是这样的。

先在本地起 test-network,建好 mychannel,把 asset-transfer-basic 的 Go chaincode 部署上去。网络里有一个排序节点和两个组织各一个 peer。

应用通过 Gateway 拿到 network,再拿到 contract。要初始化资产,调 SubmitTransaction(“InitLedger”)。背书 peer 各自执行,每个资产 PutState 一次。背书返回后交给排序服务,进块、验证通过才写进 world state。

要查资产,调 EvaluateTransaction。查一个用 ReadAsset,背后是 GetState;查全部用 GetAllAssets,背后是 GetStateByRange。只问一个 peer,结果立刻返回。

最后,输出的字段顺序由 struct 的字母序声明锁死,保证每个 peer 算出同样的字节。

课件里的坑

  • [读图提醒] p.72 的 Asset struct 如果从 PDF 复制文字,类型列会错位,看上去像 ID int、Owner int。以原图为准:ID string、Owner string、Size int(p.72)
  • [读图提醒] p.79 的表头是「推荐交易类型」。读 API 也可以在 Submit 的交易里调用,只是单纯查询时用 Evaluate 更合适(p.79)

课后 10 分钟

这 10 分钟怎么用:先画出 Submit 和 Evaluate 两条路径;再遮住 API 表的「推荐」一列自己填;最后把 sample chaincode 的执行顺序和输出顺序口述一遍。

必背

  1. 一个 chaincode 可含多个 smart contract,部署后全部对应用可用;包着 chaincode 的应用负责部署和初始化,两者可用不同语言写
  2. SubmitTransaction:Gateway 用 service discovery 找背书 peer,在所需数量的 peer 上执行 chaincode、收集背书,再提交排序服务,会改账本
  3. EvaluateTransaction:Gateway 挑一个 peer,查它本地的账本副本返回结果,不发给排序服务、不更新账本
  4. Chaincode API:PutState、DelState 推荐 SubmitTransaction;GetState、GetMultipleStates、GetStateByRange、GetStateByPartialCompositeKey、GetQueryResult、GetHistoryForKey 推荐 EvaluateTransaction
  5. GetState(key) 按一个键取一个值;GetStateByRange 的起止键都给空串,就是对命名空间全部键做开放式范围查询,返回迭代器,用完要 Close
  6. Asset struct 的字段按字母序声明:Go 序列化 JSON 时保持声明顺序、不会自动排序,按字母序才能跨语言保持确定性

课件例题

例 1(课件 p.69–70):部署一个应用要跑哪几条命令

./network.sh up createChannel -c mychannel -ca
./network.sh deployCC -ccn basic -ccp ../asset-transfer-basic/chaincode-go/ -ccl go
cd application-gateway-go && go run .
提示

三条命令分别对应:起网络、部署合约、跑应用。

解答

第一条在 fabric-samples 的 test-network 里起网络,创建名为 mychannel 的 channel,-ca 表示用 Fabric CA 生成身份。第二条部署 chaincode:名字 basic,路径指向 asset-transfer-basic 的 Go 实现,语言 go。第三条进入应用目录运行 Go 应用。网络拓扑见 p.70:一个排序组织的 orderer.example.com,Org1 和 Org2 各一个 peer0,两个 peer 都在 mychannel 里。

例 2(课件 p.71):SubmitTransaction(“InitLedger”) 走了哪几步

提示

按图从左往右:应用、Gateway、背书 peer、排序服务。

解答

应用先 gw.GetNetwork(channelName) 拿到 network,再 GetContract(chaincodeName) 拿到 contract,然后调 SubmitTransaction(“InitLedger”)。Gateway 用 service discovery 找到所需的背书 peer 集合,在所需数量的 peer 上执行 InitLedger(),收集背书结果,最后把交易交给排序服务,由它把交易排进块。

例 3(课件 p.72–77):sample chaincode 的执行与输出

见下方完整例题。

例 4(课件 p.78):ReadAsset 和 GetAllAssets 有什么不同

提示

一个按键取,一个按范围取;看返回值的类型。

解答

ReadAsset 用 GetState(id) 按一个键取一个值,直接返回字节,要么有、要么空。GetAllAssets 用 GetStateByRange 取一段键范围,起止都是空串就是全部键;它返回迭代器,要用 HasNext() 和 Next() 逐条取,用完 Close()。两者都只读,都推荐用 EvaluateTransaction 调用。

例 5(课件 p.79):按 API 表选调用方式

提示

先找出会改 world state 的 API。

解答

会改 world state 的只有 PutState 和 DelState,用 SubmitTransaction,走背书、排序、验证、上链。其余六个读 API 用 EvaluateTransaction,只问一个 peer、不上链。读 API 也能放进 Submit 的交易,此时读到的键进读集。

完整例题

题面:课件的 sample chaincode 里,InitLedger 写入 6 个资产:asset1 blue 5 Tomoko 300;asset2 red 5 Brad 400;asset3 green 10 Jin Soo 500;asset4 yellow 10 Max 600;asset5 black 15 Adriana 700;asset6 white 15 Michel 800(顺序为 ID、Color、Size、Owner、AppraisedValue)。应用先 Submit InitLedger,再 Evaluate GetAllAssets。回答:(1) 两次调用各走什么路径;(2) 输出里资产按什么顺序;(3) 每个对象的字段按什么顺序;(4) asset3 的输出是什么;(5) 只想要 asset3 该怎么做。

解法:

  1. SubmitTransaction(“InitLedger”):Gateway 找背书 peer,各 peer 执行 InitLedger,对 6 个资产各 json.Marshal 后 PutState(ID, JSON),写集里有 asset1 到 asset6 六个键。背书返回后交给排序服务,进块、验证通过后写进 world state
  2. EvaluateTransaction(“GetAllAssets”):Gateway 挑一个 peer,执行 GetStateByRange(“”, “”),遍历全部键,把每条 json.Unmarshal 成 Asset 放进列表返回。不经排序,不上链
  3. 资产按 asset1 到 asset6 的顺序:范围查询按键的顺序返回,六个键本身就是这个顺序
  4. 字段顺序是 AppraisedValue、Color、ID、Owner、Size:struct 按字母序声明,Go 序列化保持声明顺序;InitLedger 里的书写顺序不影响输出
  5. asset3 的输出是 {“AppraisedValue”:500,“Color”:“green”,“ID”:“asset3”,“Owner”:“Jin Soo”,“Size”:10},与 p.73 写入的值一一对应
  6. 只想要 asset3:调 EvaluateTransaction(“ReadAsset”, “asset3”),背后走 GetState(“asset3”),返回单个对象

要点:写入走 Submit,读取走 Evaluate;资产顺序看键,字段顺序看 struct 声明。

变式题

1. 给 sample chaincode 加两个函数:TransferAsset 先 GetState 读出资产、改 Owner 后 PutState 写回;AssetHistory 调 GetHistoryForKey。两个函数分别该用哪种调用?为什么?(改编自课件 p.78–79)

提示

看函数里有没有改 world state 的 API。

判分点与答案(非官方评分标准)

TransferAsset 里有 PutState,会改 world state,用 SubmitTransaction;它先读的那个键会进读集。AssetHistory 只读历史,用 EvaluateTransaction。自检:两个都选对,并说出「有没有写操作」这个判据即算对。

2. 有人把 Asset struct 改成 ID、Owner、Color、Size、AppraisedValue 的顺序,其他不变。GetAllAssets 的输出会怎样?这样改有什么风险?(改编自课件 p.72、p.77)

提示

Go 序列化保持声明顺序。

判分点与答案(非官方评分标准)

资产顺序不变,仍是 asset1 到 asset6;每个对象的字段顺序变成 ID、Owner、Color、Size、AppraisedValue。风险是不再按字母序,换用别的语言实现的 chaincode 可能序列化出不同字节,跨语言失去确定性。自检:答出字段顺序跟着声明走、资产顺序不变,并指出确定性风险即算对。

闪卡自测

1. smart contract 和 chaincode 什么关系?

常被混用;一个 chaincode 里可以定义多个 smart contract,部署后全部可用(p.68)。

2. 应用和 chaincode 必须用同一种语言吗?

不必,可以用不同语言写(p.69)。

3. SubmitTransaction 用什么找背书 peer?

service discovery(p.71)。

4. EvaluateTransaction 会发给排序服务吗?

不会,也不更新账本(p.75)。

5. EvaluateTransaction 查的是哪份账本?

被挑中的那个 peer 的本地账本副本(p.74)。

6. InitLedger 写入几个资产?用哪个 API 写?

6 个,每个用 PutState(asset.ID, assetJSON) 写入(p.73)。

7. GetStateByRange 的起止键都给空串表示什么?

对 chaincode 命名空间里全部资产做开放式范围查询(p.76)。

8. 用完 resultsIterator 要做什么?

Close(),课件用 defer resultsIterator.Close()(p.76)。

9. 哪两个 API 推荐 SubmitTransaction?

PutState、DelState(p.79)。

10. GetQueryResult 做什么?

对状态数据库做富 JSON 查询,如 CouchDB,推荐 Evaluate(p.79)。

11. Asset struct 为什么按字母序声明?

Go 序列化 JSON 保持声明顺序、不自动排序,按字母序才能跨语言保持确定性(p.72)。

下一讲

L07b-2 Fabric 落地案例:看 IBM Food Trust、Carrefour、Walmart 和水交易平台 BWX 怎么用 Fabric,再用 Gartner Hype Cycle 看区块链的热度。

下一讲 →
L07b-2 L07b-2 Fabric 案例:食品溯源、水交易和 Hype Cycle

个人整理的学习笔记,不是官方材料;数字与结论以课件和讲师为准。