Hyperledger Composer's Transaction Processor Function explained

In the last article, we understood how to write a basic model file in Hyperledger Composer. In that article, we had a real-world example. Author writing and publishing an article. We declared the transaction function in that article. For reference, I am quoting it here again.

transaction createPost {
  -> Author owner
  o String title
  o Category category
}

The Simplicity

The one fascinating thing about the Transaction Processor function is its simplicity. It is easy to understand and there are very few things you have to consider while defining the function. Let us go one by one and understand them in detail.

The Structure

The Hyperledger Composer documentation quotes as follows,

The structure of transaction processor functions includes decorators and metadata followed by a JavaScript function, both parts are required for a transaction processor function to work.

  /**
  * Describe the transaction processor function
  * @param `{org.svr.createPost}` post - the Post model as a parameter
  * @transaction
  */

The above lines are the decorators and metadata for the transaction processor function. Line 2 is the description of the function which helps the users/developers understand the function's definition. Line 3 is where the parameters are declared. In our example, the function takes one parameter called post which is from Post Model. (Refer to our previous post to understand how the Post Model works) Line 4 contains the @transaction tag, this tag identifies the code as a transaction processor function and is required. Else, it is considered as a normal function

So, after the metadata and decorators, here comes our logic of the function. The function name and components are already declared in our model(.cto) file. Now it's time to define the amazing thing it could do.

Let's create the logic to create a post by the author who is signed in to our network.

function createPost(post) {
  var author:getCurrentParticipant();
  var factory:getFactory();
  return getAssetRegistry("org.svr.Post")
  .then(function(postAssetRegistry) {
      var pId:getRandomId();
      newPost:factory.newResource("org.svr", "Post", pId);
      newPost.title:post.title;
      newPost.category:post.category;
      newPost.author:author;
      newPost.timestamp:new Date();
 
      return postAssetRegistry.add(newPost);
  })
}

P.S. The Javascript function in Transaction Processor function is always asynchronous and uses lots of promises. If you want to know more about async nature of Javascript and how to use promises, please feel free to Google. Articles like this can also help you.

Let us come back to our createPost function. Line 1 is the normal way of Javascript function definition. Line 2 uses getCurrentParticipant() function to capture the currently logged in user. This is Composer's built-in function. Line 3 initializes a factory model. Why factory model might be your next question. Good. A Factory creates new instances of assets, participants, transactions, and relationships. In our case, we used the factory to create an instance of Post asset. It can also be used to create a new relationship between asset-asset, asset-participant etc. There are also few more examples here. Line 4-14 has few things we need to focus more. I'll break it into bits for your understanding. First, the AssetRegistry is used to manage a set of assets stored on the Blockchain. So, to add a new Post asset to our AssetRegistry, we invoke getAssetRegistry("org.svr.Post") and make a synchronous operation by writing a promise. The function postAssetRegistry.add(newPost); will add the post to our asset and now it's successfully in the Blockchain.

What next?

Even editing one's own post in a Blockchain is also a transaction and it needs a Transaction Processor Function. But how can we make the post editable only by the author? Is there anyway to make admin edit all posts and author to edit only his/her posts? The answer is YES.

So How? It is using ACL (Access Control Language). We will learn how to write ACL to permit/deny access to the users of Blockchain in the Next Episode. Until then, bye.