Hyperledger Fabric Query Block Service

Syntax:

com.ibi.agents.XDFabricQueryBlockAgent

Description:

This service queries Hyperledger Fabric for a specific block and returns it. The query will be sent to one of the peers chosen randomly. The search criteria can be a block number, a block hash, or a Transaction ID. The result is a BlockInfo encoded in an XML or JSON parsed tree.

In batch mode, the blocks previous to the queried block can also be returned. The number of blocks can be limited by the Batch Size or a date limit.

Parameters:

The following table lists and describes the parameters for the Hyperledger Fabric Query Block service.

Main

Parameter

Description

Fabric Channel Provider

The name of the configured Hyperledger Fabric Channel provider.

Query Type

Determines the search criteria for the block query.

Query Argument

Querying by block number:

Supply a non-negative integer block number, or a negative integer block number relative to the current block height (-1 is the latest block).

Querying by block hash:

This is a hex encoded string with two hex characters per byte. When querying by transaction ID, this is the transaction ID.

Output Format

Format of the result.

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

The Query Type determines what kind of search criteria is provided in the Query Argument:

The Output Format can be XML or JSON. The output document stores the returned BlockInfo or the batch of blocks encoded in an XML or JSON parsed tree.

Batch Mode

Parameter Name

Description

Early Limit

Format is yyyy-MM-dd'T'HH:mm:ss.SSSXXX, where XXX is an ISO 8601 time zone. Specifying an Early Limit turns on batch mode, which will always return the queried block and also includes the previous blocks up to, but not including, the first encountered block with all transactions 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. The batch is also limited by the Batch Size when defined.

Batch Size

Specifying a batch size turns on batch mode, which will return up to that many blocks, starting from the queried block and its previous blocks, within the limits of the Early Limit if defined, or the origin of the chain.

Batch mode is enabled by specifying any of the Batch Mode properties. In batch mode, the queried block is always returned plus zero or more previous blocks. The Batch Size parameter is the maximum number of blocks that can be returned. The Early Limit parameter selects the previous blocks that have at least one transaction timestamped on or after the specified date. If both parameters are specified, then the batch stops with the first constraint satisfied.

Edges:

The following table lists and describes the edges that are returned by the Hyperledger Fabric Block 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.

Examples:

The following example shows the parameter values to query the latest block in the End2endIT sample of the Hyperledger Fabric Java SDK. It assumes that the fabric1 provider has the same values as the example shown in Hyperledger Fabric Channel Provider.

Parameter

Value

Fabric Channel Provider

fabric1

Query Type

Query by Block Number

Query Argument

-1

Query Format

XML

The following example shows how to query the previous block assuming the input document is the XML output of a previous call to the Hyperledger Fabric Query Block service.

Parameter

Value

Fabric Channel Provider

fabric1

Query Type

Query by Block Hash

Query Argument

_xpath(/BlockInfo/PreviousHash)

Query Format

XML

The following example shows how to query the block corresponding to the transaction committed by the latest invocation of the Hyperledger Fabric Transaction Service

Parameter

Value

Fabric Channel Provider

fabric1

Query Type

Query by Transaction ID

Query Argument

_sreg('fabric.TransactionID')

Query Format

XML

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

<BlockInfo>
  <BlockNumber>46</BlockNumber> <DataHash>26a1b666a83679a3b8fbaf16149c1b0b01e424956fd1ba6d3...</DataHash>
<PreviousHash>ce738d39292304e98289e43515c4ae91cd649421f...</PreviousHash>
  <EnvelopeInfos>
    <EnvelopeInfo>
<TransactionID>4f8d8728ffbf27adf21b32f7125de6e5929323d...</TransactionID>
      <ChannelID>foo</ChannelID>
      <Epoch>0</Epoch>
      <Timestamp>2017-07-28T17:15:52-04:00</Timestamp>
      <IsValid>true</IsValid>
      <ValidationCode>0</ValidationCode>
      <TransactionActionInfos>
        <TransactionActionInfo>
          <ResponseStatus>200</ResponseStatus>
          <ResponseMessageBytes/>
          <EndorserInfos>
            <EndorserInfo> <Signature>3044022022dcc5424b0d0b50f3ad3cdec8ad7cbda7524fg...</Signature> <Endorser>0a074f7267314d53501280062d2d2d2d2d42494e202d2d2d...</Endorser>
            </EndorserInfo>
          </EndorserInfos>
          <ChaincodeInputArgs>
            <Arg>696e766f6b65</Arg>
            <Arg>6d6f7665</Arg>
            <Arg>61</Arg>
            <Arg>62</Arg>
            <Arg>31</Arg>
          </ChaincodeInputArgs>
          <ProposalResponseStatus>200</ProposalResponseStatus>
          <ProposalResponsePayload/>
          <TxReadWriteSetInfo>
            <NsRwsetInfos>
              <NsRwsetInfo>
                <Namespace>example_cc_go</Namespace>
                <KVReads>
                  <KVRead><Key>a</Key>
                    <Version>
                      <BlockNum>45</BlockNum>
                      <TxNum>0</TxNum>
                    </Version>
                  </KVRead>
                  <KVRead>
                    <Key>b</Key>
                    <Version>
                      <BlockNum>45</BlockNum>
                      <TxNum>0</TxNum>
                    </Version>
                  </KVRead>
                </KVReads>
                <KVWrites>
                  <KVWrite>
                    <Key>a</Key>
                    <Value>313931</Value>
                  </KVWrite>
                  <KVWrite>
                    <Key>b</Key>
                    <Value>353039</Value>
                  </KVWrite>
                </KVWrites>
              </NsRwsetInfo>
              <NsRwsetInfo>
                <Namespace>lscc</Namespace>
                <KVReads>
                  <KVRead>
                    <Key>example_cc_go</Key>
                    <Version>
                      <BlockNum>1</BlockNum>
                      <TxNum>0</TxNum>
                    </Version>
                  </KVRead>
                </KVReads>
              </NsRwsetInfo>
            </NsRwsetInfos>
          </TxReadWriteSetInfo>
        </TransactionActionInfo>
      </TransactionActionInfos>
    </EnvelopeInfo>
  </EnvelopeInfos>
</BlockInfo>

The following is a sample output in JSON format, which has been indented for display purposes only. Notice that arrays are more natural in JSON.

{
  "BlockNumber": 46,
  "DataHash": "26a1b666a83679a3b8fbaf16149c1b0b01e424956fd1ba6d3ec5sf...",
  "PreviousHash": "ce738d39292304e98289e43515c4ae91cd649421f96813e8af...",
  "EnvelopeInfos": [
    {
      "TransactionID": "4f8d8728ffbf27adf21b32f7125de6e5929323d3a6a37c...",
      "ChannelID": "foo",
      "Epoch": 0,
      "Timestamp": "2017-07-28T17:15:52-04:00",
      "IsValid": true,
      "ValidationCode": 0,
      "TransactionActionInfos": [
        {
          "ResponseStatus": 200,
          "ResponseMessageBytes": "",
          "EndorserInfos": [
            {
              "Signature": "3044022022dcc5424b0d0b50f3ad3cdec8ad7cbda7gs...",
              "Endorser": "0a074f7267314d53501280062d2d2d2d2d40128006505d..."
            }
          ],
          "ChaincodeInputArgs": [
            "696e766f6b65",
            "6d6f7665",
            "61",
            "62",
            "31"
          ],
          "ProposalResponseStatus": 200,
          "ProposalResponsePayload": "",
          "TxReadWriteSetInfo": {
            "NsRwsetInfos": [
              {
                "Namespace": "example_cc_go",
                "KVReads": [
                  {
                    "Key": "a",
                    "Version": {
                      "BlockNum": 45,
                      "TxNum": 0
                    }
                  },
                  {
                    "Key": "b",
                    "Version": {
                      "BlockNum": 45,
                      "TxNum": 0
                    }
                  }
                ],
                "KVWrites": [
                  {
                    "Key": "a",
                    "Value": "313931"
                  },
                  {
                    "Key": "b",
                    "Value": "353039"
                  }
                ]
              },
              {
                "Namespace": "lscc",
                "KVReads": [
                  {
                    "Key": "example_cc_go",
                    "Version": {
                      "BlockNum": 1,
                      "TxNum": 0
                    }
                  }
                ]
              }
            ]
          }
        }
      ]
    }
  ]
}

The following is an abbreviated sample output for batch mode containing two blocks in XML format. The document has been indented for display purposes only. See the sample above for the contents of a single BlockInfo element.

<BlockInfos>
  	<BlockInfo>
  		<BlockNumber>46</BlockNumber>
  		...
  	</BlockInfo>
  	<BlockInfo>
  		<BlockNumber>45</BlockNumber>
    ...
  	</BlockInfo>
</BlockInfos>

The following is an abbreviated sample output for batch mode containing two blocks in JSON format. The document has been indented for display purposes only. In JSON, the batch of blocks is an array of BlockInfo objects. See the sample above for the contents of a single BlockInfo object.

[
  {
  	"BlockNumber": 46,
  	...
		},
  {
  	"BlockNumber": 45,
  	...
		}
]