Hyperledger Fabric Key History Service

Syntax:

com.ibi.agents.XDFabricKeyHistoryAgent

Description:

This service queries the Hyperledger Fabric for the history of a single key showing the assignments going back in time. The report starts from a given key version and continues with previous versions, provided the transaction that wrote the key also read the previous value. Technically, this means the key must also appear in the KVReads when it appears in the KVWrites of the transaction.

Parameters:

The following table describes the parameters of the Hyperledger Fabric Key History service.

Main
Parameter	Description
Fabric Channel Provider	The name of the configured Hyperledger Fabric Channel provider.
Namespace	Namespace of the key, this is usually the chaincode name.
Key	Name of the key.
Block Number	The number of a block containing a transaction with a write of the key. This is a non negative integer block number, or a negative integer block number relative to the current block height (-1 is the latest block).
Transaction Number	The index of the transaction within the selected block.
Encoding	Determines how the value will be converted to string. Choose UTF-8 or type a Charset name to convert the bytes to string, or choose Hex to convert the ByteString to a hex encoded string with two hex characters per byte.
Early Limit	Format is `yyyy-MM-dd'T'HH:mm:ss.SSSXXX` where `XXX` is an ISO 8601 time zone. Limit the key history depth to key writes timestamped earlier than the early limit. Timestamps are created by clients without a central clock. It is therefore recommended to specify a date earlier than necessary by some margin.
Maximum Depth	The maximum number of versions of the key to report.
History Format	Format of the history in the output document.

The service refers to the Fabric Channel Provider by name to gain access to the reconstructed Channel.

A key is private to a chaincode instance. The Namespace specifies which chaincode owns the key. The key version to start the trace is given by the Block Number and the Transaction Number within that block. The Block Number can be a non-negative integer as usual, or or a negative integer block number relative to the current block height (-1 is the latest block).

The value of a key is a ByteString. The Encoding parameter specifies how it will be converted to a string in the history. For example, the bytes can be converted to string according to the rules of a specified Charset, like the suggested UTF-8 or any other Charset name typed in the field. The other option is to convert to a Hex String with two hex characters per byte. This is the default.

The Maximum Depth limits the size of the history if the origin block is not reached first. The Early Limit also limits the size of the history to the transactions that are timestamped on or after the specified date.

The History Format can be XML or JSON. The output document stores the key history encoded in an XML or JSON parsed tree.

Edges:

The following table lists and describes the edges that are returned by the Hyperledger Fabric Key History service.

Edge	Description
success	The operation was successful.
fail_parse	An iFL expression could not be evaluated.
fail_operation	The operation could not be completed successfully.

Example:

This example shows how to query the history of the a key maintained by the chaincode example_cc_go.

Parameter	Value
Fabric Channel Provider	fabric1
Namespace	example_cc_go
Key	a
Block Number	-1
Transaction Number	0
Encoding	UTF-8
Maximum Depth	5
History Format	XML

The following is a sample output in XML format, which has been indented for display purposes only.

<KVHistory>
  <Namespace>example_cc_go</Namespace>
  <Key>a</Key>
 <KVPuts>
   <KVPut>
     <Value>300</Value>
     <BlockNum>116</BlockNum>
     <TxNum>0</TxNum>
   </KVPut>
   <KVPut>
     <Value>325</Value>
     <BlockNum>115</BlockNum>
     <TxNum>0</TxNum>
   </KVPut>
   <KVPut>
     <Value>350</Value>
     <BlockNum>114</BlockNum>
     <TxNum>0</TxNum>
   </KVPut>
   <KVPut>
     <Value>375</Value>
     <BlockNum>113</BlockNum>
     <TxNum>0</TxNum>
   </KVPut>
   <KVPut>
     <Value>400</Value>
     <BlockNum>112</BlockNum>
     <TxNum>0</TxNum>
   </KVPut>
 </KVPuts>
</KVHistory>

The following is a sample of the same history in JSON format, which has been indented for display purposes only.

{
"Namespace":"example_cc_go",
"Key":"a",
"KVPuts":
 [
   {
     "Value":"300",
     "BlockNum":116,
     "TxNum":0},
   {
     "Value":"325",
     "BlockNum":115,
     "TxNum":0},
   {
     "Value":"350",
     "BlockNum":114,
     "TxNum":0},
   {
     "Value":"375",
     "BlockNum":113,
     "TxNum":0},
   {
     "Value":"400",
    "BlockNum":112,
    "TxNum":0}
 ]
}