Hyperledger Fabric 链码 生命周期和API

Posted 2021-06-08 thefist11

1. Chaincode的5个生命周期命令

• 链码打包
• 链码安装
  eg.peer chaincode install ccpack.out
• 链码实例化
  eg. peer.sh chaincode instantiate -n mycc -v 0 -c ‘{“Args”:[“init”,“a”,“100”,“b”,“200”]}’ -C mychannel
• 链码升级（当链码的代码发生改变时，就需要升级链码）
• 链码签名

2. peer命令提供了8个子命令管理链码

• Install
• instantiate
• invoke
• list
• package
• query
• signpackage
• upgrade

3.链码API(主要是shim包提供，分为5类)

3.1 参数解析API：用来获取参数的账本数据状态

• GetStringArgs() []string
  返回调用链码时指定提供的参数列表（以字符串数组形式返回）

• GetFunctionAndParameters() (function string, params []string)
  返回调用链码时在交易提案中指定提供的被调用的函数名称及函数的参数列表（以字符串数组形式返回）

• GetArgsSlice() ([]byte, error)
  返回提交交易提案时提供的参数列表（以字节串数组形式返回）

• GetArgs() [][]byte
  返回调用链码时在交易提案中指定提供的被调用的函数名称及函数的参数列表（以字符串数组形式返回）

3.2 操作API：对账本数据查询、更新等

• GetState(key string) ([]byte, error)
  查询账本，返回指定键对应的值

• PutState(key string, value []byte) error
  尝试添加/更新账本中的一对键值。 这一对键值会被添加到写集合中，等待 Committer 进一步确认，验证通过后才会真正写入到账本

• DelState(key string) error
  尝试删除账本中的一对键值。 同样，对该对键值删除会添加到写集合中，等待 Committer 进一步确认，验证通过后才会真正写入到账本

• GetStateByRange(startKey, endKey string) (StateQueryIteratorInterface, error)
  查询指定范围的键值，startKey 和 endkey 分别指定开始（包括）和终止（不包括），当为空时默认是最大范围。 返回结果是一个迭代器结构，可以按照字典序迭代每个键值对，最后需要调用 Close() 方法关闭

• GetHistoryForKey(key string) (HistoryQueryIteratorInterface, error)
  返回指定键的所有历史值。该方法的使用需要节点配置中打开历史数据库特性（ledger.history.enableHistoryDatabase=true）

• CreateCompositeKey(objectType string, attributes []string) (string, error)
  给定一组属性（attributes），将这些属性组合起来构造返回一个复合键。eg.CreateComositeKey(“name-age”,[]string{“Alice”, “12”});

• SplitCompositeKey(compositeKey string) (string, []string, error)
  将指定的复合键进行分割，拆分成构造复合键时所用的属性

• GetStateByPartialCompositeKey(objectType string, keys []string)
  根据局部的复合键（前缀）返回所有匹配的键值，即与账本中的键进行前缀匹配。返回结果是一个迭代器结构，可以按照字典序迭代每个键值对，最后需要调用 Close() 方法关闭
  (StateQueryIteratorInterface, error)

• GetQueryResult(query string) (StateQueryIteratorInterface, error)
  对(支持富查询功能的)状态数据库进行富查询，返回结果是一个迭代器结构，目前只支持 CouchDB。注意该方法不会被 Committer 重新执行进行验证，所以不能用于更新账本状态的交易中

注意： 通过 put 写入的数据状态不能立刻 get 到，因为 put 只是链码执行的模拟交易（防止重复提交攻击），并不会真正将状态保存到账本中，必须经过 Orderer 达成共识之后，将数据状态保存在区块中，然后保存在各 peer 节点的账本中。

3.3 交易信息获取API：获取提交的交易信息

• GetTxID() string
  返回交易提案中指定的交易 ID。一般情况下，交易 ID 是客户端提交提案时由 Nonce 随机串和签名者身份信息哈希产生的数字摘要

• GetChannelID() string
  返回交易提案中指定的 Channel ID

• GetTxTimestamp() (*timestamp.Timestamp, error)
  返回交易被创建时的客户端打上的的时间戳。这个时间戳是直接从交易 ChannnelHeader 中提取的，所以在所以背书节点处看到的值都相同

• GetBinding() ([]byte, error)
  返回交易的 binding 信息。交易的 binding 信息是将交提案的 nonse、Creator、epoch 等信息组合起来哈希得到数字摘要

• GetSignedProposal() (*pb.SignedProposal, error)
  返回该 stub 的 SignedProposal 结构，包括了跟交易提案相关的所有数据

• GetCreator() ([]byte, error)
  返回该交易提交者的身份信息（用户证书）。 从 SignedProposal 中的 SignatureHeader.Creator 提取

• GetTransient() (map[string][]byte, error)
  返回交易中带有的一些临时信息。从 ChaincodeProposalPayload.transient 提取，可以存放与应用相关的保密信息，该信息不会被写入到账本

3.4 事件处理API：与事件处理相关

• GetPrivateData(collection, key string) ([]byte, error)
  根据指定的 key，从指定的私有数据集中查询对应的私有数据

• PutPrivateData(collection string, key string, value []byte) error
  将指定的 key 与 value 保存到私有数据集中

• DelPrivateData(collection, key string) error
  根据指定的 key 从私有数据集中删除相应的数据

• GetPrivateDataByRange(collection, startKey, endKey string) (StateQueryIteratorInterface, error)
  根据指定的开始与结束 key 查询范围（不包含结束key）内的私有数据

• GetPrivateDataByPartialCompositeKey(collection, objectType string, keys []string) (StateQueryIteratorInterface, error)
  根据给定的部分组合键的集合，查询给定的私有状态

• GetPrivateDataQueryResult(collection, query string) (StateQueryIteratorInterface, error)
  根据指定的查询字符串执行富查询 （只支持支持富查询的 CouchDB）

3.5 对私有数据操作的API：专门对私有数据操作

• SetEvent(name string, payload []byte) error
  设定当这个交易在 Committer 处被认证通过，写入到区块时发送的事件（event），一般由 Client 监听

• InvokeChaincode(chaincodeName string, args [][]byte, channel string) pb.Response
  调用另外一个链码的 Invoke 方法。 如果被调用链码在同一个通道内，则添加其读写集合信息到调用交易；否则执行调用但不影响读写集合信息// 如果 channel 为空，则默认为当前通道。目前仅限读操作，同时不会生成新的交易