Part 3. Smart Contracts and Configuration WorkFlow files.

Solidity

Currently the only blockchain network supported by the workbench is Ethereum so we only need to consider Solidity, a JavaScript like language in which all Ethereum smart contracts are written. Detailed information about Solidity can be found here. You have a choice of development tool such as for example Remix run either online or off, or Visual Code using the Solidity plugin. We prefer Remix. The Blockchain workbench does not provide additional support for Solidity such as IDE’s, tools, or language enhancements other than the provision of a base class called WorkbenchBase, from which all implemented classes in the your Solidity contract file “must” inherit. This class provides the Workbench specific callback interfaces that allow the Blockchain Workbench network to monitor and record events and data from the Smart Contract as it runs and store them, off-chain, in the SQL DB.

Examples of Solidity based smart contracts written specifically for the Azure Blockchain Workbench can be found here and there are many online Solidity tutorials available which we’d recommend if you are new to the area. “Start simple”, would be our motto because you have to ensure that your Smart Contract code, its states, transitions and personas must, as discussed below, map to a Configuration Workflow file, which is not as simple as you may think. Also remember to include the Microsoft specific WorkbenchBase base class.  The Blockchain Workbench Forum may also be of help.

The Configuration Workflow file

Whilst the Solidity file defines and implements the smart contract on the Blockchain, the JSON based Configuration Workflow file defines the state engine that is used to map the smart contract’s data, rules, interactions and persona to create the state machine whose transitions and flow are used to build the workbench schema. It is this “model” that the workbench employs to build its interfaces, populate its database tables and configure test UI.

The Configuration Workflow file is unique to the Azure Blockchain Workbench and offers “interesting” challenges since for to get it to work properly and reflect the actions and personas defined in the smart contract, every possible interaction must be captured and encapsulated in this file.  It is this file which “defines the high-level workflows and interaction model of the Blockchain application. Configuration metadata represents the workflow stages and interaction model of the Blockchain application.”

The truth is that building a working workflow file can be tricky process, there is no editor, or tool to convert the Solidity code file into some form of representation that would capture its key features and encapsulate them in a form required by the Configuration Workflow. Instead you have to do it by hand, which can be very error prone, particularly as the number of transitions and personas increases. We have raised this issue on the Blockchain Workstation forum, hopefully the workbench team will come up with a tool or procedure to automate this process sometime soon. In the end a short and simple Solidity example can end up with hundreds of lines of Json Workflow file as one tries to map all the various state transitions. Further details on the required content of the Configuration Workflow file can be found here. We recommended checking this out together with a couple of the provided examples before you start.

Examples of our own, based on a simple supply chain contact with just 5 participants and a few transitions, are show in Fig 6  to 9. Here a Solidity file with perhaps around 200 hundred lines of code resulted in the creation of a Workflow file of 800 or more lines once each of the required sections e.g. Properties, Functions and States had been defined and populated. As we have stressed, and will do again, this can be a tiresome process.

Now we have our smart contract and a configuration workflow file, join us in Part 4 so we can test what we’ve built.