Hyperledger Fabric Transaction Service

Syntax:

com.ibi.agents.XDFabricAgent

Description:

This service invokes chaincode to execute a transaction on a blockchain in the Hyperledger Fabric. It starts by sending a transaction proposal request to all the configured peers. If enough proposal responses are successful (and not too many have failed), then the transaction is sent to the configured Orderers.

In synchronous mode, the service waits for the transaction event from the configured event hubs to make sure the transaction was committed to the blockchain. In asynchronous mode, the service returns immediately because a message is sent to an internal queue when the event finally arrives. An internal queue listener must be configured to read that internal queue to continue processing after the confirmation event.

The TransactionID is stored in the Special Register (SREG) named fabric.TransactionID. Upon error, the output is an error document. When successful in synchronous mode, the output document can be the input document, the chaincode return value, or the TransactionEvent. When successful in asynchronous mode, the output document is the input document.

Parameters:

The following tables list and describe the parameters for the Hyperledger Fabric Transaction service.

In the Main group of parameters, the service refers to the Fabric Channel Provider by name to gain access to the reconstructed Channel. The chaincode name, path and version are determined when the chaincode is installed. The path is similar to a namespace and is not related to a path in the file system. The chaincode must already be installed before calling the Hyperledger Fabric Transaction service.

The Hyperledger Fabric Transaction service has a simple acceptance criterion to decide if the transaction is sent to the Orderers to be committed to the blockchain. There must be a minimum number of successful proposals and the number of failed proposals cannot exceed a maximum. This simple criterion is used by the service as an optimization. It does not have to be perfect. The real endorsement policy is evaluated by the Orderers when creating the block.

The Return parameter determines the contents of the output document in synchronous mode. The output document can be the input document, the chaincode return value, or the TransactionEvent, The chaincode return value is a ByteString, which can be parsed in different ways. The chaincode return value can be:

• Interpreted as a UTF8 string.
• Encoded as a hexadecimal string with two consecutive hexadecimal characters per byte.
• Encoded as a string in Base64.
• Parsed as XML or JSON, and returned as a parsed tree.

The TransactionEvent is an object that can be serialized in XML or JSON, and returned as a parsed tree. In asynchronous mode, the Return parameter is ignored because the transaction is not yet complete. In this mode, the output document is always the input document unless there is an error.

In the Call group of parameters, the Argument N properties are the arguments to the chaincode invocation. By convention, Argument 0 is often an operation name understood by the chaincode. There can be an unlimited number of arguments. This is done by defining user properties with names of the form argN. For example, the next argument after Argument 4 is arg5. The list of arguments stops at the first empty argument.

The type of the arguments can be string or byte array. All arguments must be the same type. A byte array is encoded as an hexadecimal string with two consecutive hexadecimal characters per byte. For example, 616263 is abc in a UTF8 byte array.

Asynchronous mode is enabled by selecting the Is Asynchronous parameter. The Queue Name parameter tells the service where the message will be sent when the TransactionEvent arrives. The Event Format chooses the format of the document, either XML or JSON. Want User Registers determines if the User registers are preserved with the message. The priority of the message affects in which order the messages are processed by the internal queue listener. The Put Timeout determines how long the callback will wait for the queue to become available when sending the message. After this timeout, the message is dropped.

The Request Context Namespace selects which registers will be preserved with the message. For example, if the value is ns, then all registers with names beginning with ns. (such as ns.reg1) are preserved. Select Default to preserve registers with no prefix. Select None to ignore all registers. Enter an asterisk character (*) to select all registers.

Edges:

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

Example 1:

Example 1 shows the parameter values for an invocation of the chaincode 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.

fabric1

example_cc_go

github.com/example_cc

1

String

move

a

b

20

1

0

Example 2:

Example 2 shows that the same invocation can be achieved with the chaincode arguments encoded as byte arrays. The iFL function _hex(value,charset) might be useful.

fabric1

example_cc_go

github.com/example_cc

1

Hex String

_hex('move', 'UTF8')

61

62

3230

1

0

Example 3:

Example 3 shows the extra properties that can be added to example 1 or 2 to enable asynchronous mode. In this mode, the service will return immediately after sending the transaction to the Orderers. A message will be sent to the internal queue q1 when the transaction event arrives, confirming the transaction is part of the blockchain.

true

q1

XML

true

4

3000

*

The following is a sample output document when the Return parameter is TransactionEvent as XML in synchronous mode. A message similar to this is sent to the Internal queue in asynchronous mode when the Event Format is XML. This document has been indented for display purposes only.

<TransactionEvent>
  <EventHub>
     <Name>peer0</Name>
     <Url>grpc://thor.ibi.com:7053</Url>
  </EventHub>
  <TransactionID>90fdd06ad2752deaed7c9beab00c46bd770667e...</TransactionID>
  <ChannelID>foo</ChannelID>
  <Epoch>0</Epoch>
  <Timestamp>2017-09-26T12:51:32.138-04:00</Timestamp>
  <IsValid>true</IsValid>
  <ValidationCode>0</ValidationCode>
  <TransactionActionInfos>
    <TransactionActionInfo>
      <ResponseStatus>200</ResponseStatus>
      <ResponseMessageBytes/>
      <EndorserInfos>
        <EndorserInfo>
          <Signature>30440220720e51c11b98c17b72ab9a50fbb6...</Signature>
          <Endorser>0a074f7267314d53501280062d2d2d2d2d424...</Endorser>
        </EndorserInfo>
      </EndorserInfos>
      <ChaincodeInputArgs>
        <Arg>696e766f6b65</Arg>
        <Arg>6d6f7665</Arg>
        <Arg>61</Arg>
        <Arg>62</Arg>
        <Arg>3230</Arg>
      </ChaincodeInputArgs>
      <ProposalResponseStatus>200</ProposalResponseStatus>
      <ProposalResponsePayload/>
    </TransactionActionInfo>
  </TransactionActionInfos>
</TransactionEvent>

The following is a sample output document when the Return parameter is TransactionEvent as JSON in synchronous mode. A message similar to this is sent to the Internal queue in asynchronous mode when the Event Format is JSON. The document has been indented for display purposes only.

{
  "EventHub":{"Name":"peer0",
  "Url":"grpc://thor.ibi.com:7053"},
  "TransactionID":"49fa1193bc30c17cc011a6b5850f8e57c92...",
  "ChannelID":"foo",
  "Epoch":0,
  "Timestamp":"2017-09-26T12:54:56.689-04:00",
  "IsValid":true,
  "ValidationCode": 0,
  "TransactionActionInfos": [
    {
      "ResponseStatus": 200,
      "ResponseMessageBytes": "",
      "EndorserInfos": [
        {
          "Signature": "3045022100e5181d03460959d751...",
          "Endorser": "0a074f7267314d53501280062d2d2..."
        }
      ],
      "ChaincodeInputArgs": [
        "696e766f6b65",
        "6d6f7665",
        "61",
        "62",
        "3230"
      ],
      "ProposalResponseStatus": 200,
      "ProposalResponsePayload": ""
    }
  ]
}