June 2018
Volume 33 Number 6
[Blockchain]
Introducing Azure Blockchain Workbench
By Stefano Tempesta | June 2018
Azure Blockchain Workbench (aka.ms/abcworkbench) is the latest step in Microsoft’s journey to enable customers to adopt blockchain technologies and get started with Azure Blockchain. To provide context, Azure Blockchain is a collection of Azure services and capabilities designed to help enterprises create and deploy a new class of applications for sharing business processes and data with multiple, semi-trusted organizations. Currently customers can deploy these services into their Azure subscriptions and integrate them with blockchains available on the Azure Marketplace. Now, with Azure Blockchain Workbench, the heavy lifting is done for them, so they can focus less on scaffolding and more on logic and smart contracts.
Azure Blockchain Workbench orchestrates several Azure services around popular blockchain digital ledgers and into a reference architecture that can be used to build blockchain-based applications. It’s a free, easy-to-use tool with a simplified interface that enables users to create end-to-end decentralized applications leveraging all of Azure Blockchain’s capabilities. It comes equipped with sample cross-organizational workflows and smart contracts, as well as an out-of-the-box UI that customers can use to drastically reduce development costs and accelerate proofs of concept.
If you’re new to blockchain, I recommend you read Jonathan Waldman’s outstanding article, “Blockchain Fundamentals” (msdn.com/magazine/mt845650), in the March 2018 issue of MSDN Magazine. Also, make a point to watch the Microsoft Mechanics video, “Intro to Blockchain and Azure Blockchain Workbench,” at aka.ms/workbenchintro.
Introducing Azure Blockchain Workbench
In much the same way that applications today interact with databases, decentralized applications running on a blockchain communicate and execute logic against a specific digital ledger, such as Ethereum or Hyperledger. A digital ledger network consists of a peer-to-peer decentralized network of nodes. These nodes maintain a copy of the data store and run a virtual machine to support arbitrary computation against the ledger, while maintaining consensus. Smart contracts are the mechanism that allows for this complicated computation on the network, similar to stored procedures on a traditional relational database.
Despite the potential to leverage blockchain in a growing variety of business processes, there are obstacles to overcome before enterprises can adopt blockchain technologies. Lack of governance, network performance and scalability are often cited as challenges that impact the adoption of blockchain in the enterprise space.
Building a complete solution running on blockchain typically requires provisioning infrastructure and developing a client application, writing and deploying a gateway API, implementing support for off-chain storage, writing logs and reports, and integrating identity and key vault services into the solution. There's a common set of challenges related to blockchain app development that are addressed by Azure Blockchain Workbench, which dramatically reduces the amount of time needed to build a blockchain solution.
Azure Blockchain Workbench provides code assets and ARM template-driven deployment for all the scaffolding needed for blockchain POCs, including the blockchain network, a gateway API, a responsive Web application, Azure Active Directory integration, Azure Key Vault integration, a SQL DB configured for collecting on-chain data, and a set of supporting services for data hashing and signing. The tool also makes it possible to create a Web front end without writing any code. It uses metadata provided for smart contracts to dynamically deliver a contextual UX for participants. Because the framework populates SQL DB as an off-chain store, it enables an organization to leverage existing skills and tools to light up additional capabilities.
The result: Azure Blockchain Workbench reduces time and cost for proof-of-concept (POC) projects. It enables customers to focus on creating innovative applications that demonstrate the potential of blockchain, by spending less time and resources on integration tasks that are required to stand up a basic POC.
Azure Blockchain Workbench is available on the Azure Marketplace (aka.ms/tryworkbench), and a video of Workbench in action is available by the Microsoft Mechanics team at aka.ms/workbenchdemo.
Deploy Azure Blockchain Workbench
The deployment of Azure Blockchain Workbench requires the following prerequisite steps:
1. An Azure Active Directory (Azure AD) tenant to host the necessary Azure AD and Key Vault apps.
2. Registration of an Azure AD app and a Key Vault value to be referenced during the deployment of Azure Blockchain Workbench.
You may want to create a new Azure AD tenant for setting up test users or registering applications in a different Azure AD tenant than your corporate Azure AD tenant. Detailed instructions on these configuration steps are reported in the official Azure Blockchain Workbench documentation at aka.ms/workbenchdocs.
Once the prerequisite steps have been completed, the Workbench can be deployed. Sign in to the Azure portal and add a new resource from the Azure Marketplace, shown in Figure 1. Search for and select Azure Blockchain Workbench to start the provisioning process.
Figure 1 The Azure Blockchain Workbench in the Azure Marketplace
This solution template is designed to ease deployment and integration of the services needed to build an application on a blockchain network. With a handful of user inputs and a single-click deployment through the Azure portal, you can deploy a blockchain ledger along with the relevant Azure services needed to build an end-to-end blockchain application, packaged with a sample Web UI. The generated application includes a Web application, REST API, off-chain storage and the like. Rather than spending hours building out and configuring the services needed to integrate with a blockchain network, the Azure team has automated these time-consuming pieces so you can focus on building out your scenarios. Through the Azure Blockchain Workbench Web application, you can generate an end-to-end UX for your business workflows based on smart contracts.
Provisioning Azure Blockchain Workbench requires six steps, with the first two establishing configuration parameters, and the next two addressing network capacity and monitoring. Step 1 requires some basic settings, depicted in Figure 2, which include:
• A unique identifier as a prefix for naming all Azure resources provisioned as part of this template.
• The admin username for all provisioned virtual machines (VMs).
• An SSH public key used for connecting to the VMs. Copy and paste an RSA public key in the single-line format (starting with “ssh-rsa”) or the multi-line PEM format. You can generate SSH keys using ssh-keygen on Linux and macOS, or PuTTYGen on Windows.
• A password to protect access to the database included as part of the Workbench deployment.
• The Azure subscription you wish to use for your deployment. Remember, use of Azure Blockchain Workbench is free of any license cost, but you pay for the provisioned Azure computing, storage and network resources.
• The Resource group to use to group all these resources together. I recommend creating a new resource group for your Blockchain Workbench solution.
• The region to which you wish to deploy the resources.
Figure 2 Getting Started Provisioning Azure Blockchain Workbench
Step 2 requires you to have completed the prerequisite steps of registration of the blockchain client app in Azure AD, as you’ll need the Registration Application ID and key to enter when requested. You also need to specify the Tenant domain name obtained as part of the registration of the client app in Azure AD.
In Step 3 you can specify the number of nodes in the provisioned blockchain ledger and the size of the allocated VMs. Step 4 is for optionally opting in to the Operations Management Suite (OMS) for monitoring the deployed solution.
Steps 5 and 6 are simply a summary of the resources being provisioned and your acknowledgment that you understand that there is a cost implication. Once the deployment of the Workbench has completed, you’ll see a new Resource Group with the specified name. Some resources deployed here, such as Application Insights, will allow you to get more information about the state of the Workbench, including details about the deployed VMs and networks.
As I noted earlier, Azure Blockchain Workbench leverages Azure AD for authentication, access control and workflow persona identification. Only users specified in the referenced Azure AD will be able to authenticate and use the deployed resources. In addition, users must be associated with a specific user group in order to interact and perform actions. It’s therefore necessary to manage user accounts interacting with Azure Blockchain Workbench and assign them the required permissions.
Deploying a Smart Contract
Once deployed, you can access Azure Blockchain Workbench by navigating to its URL. You’ll see an Azure AD-backed login experience where you can enter your work or personal Microsoft account credentials to access the application.
You can now start leveraging smart contracts, which contain business logic that drives different scenario flows. This approach provides the immutability, deterministic execution and transparency required in untrusted environments. Smart contracts are written in blockchain stack-specific languages. For example, Solidity is used for Ethereum, while Go is used for Hyperledger Fabric. A smart contract is deployed to all nodes on the blockchain. During execution, the information it conveys is also replicated to all the nodes on the network.
The main goal of Azure Blockchain Workbench is to stand up the scaffolding around the blockchain application, so users can focus on creating the smart contract-based business logic. Once a smart contract is instantiated in the Workbench, it’s written to the blockchain, and subsequent updates to the smart contract are recorded on the blockchain. After the Azure Blockchain Workbench administrator has deployed smart contracts and completed user assignments for the smart contracts, other users can interact with the blockchain application and engage in the smart contract workflows.
Let’s start by deploying any of the existing demo smart contracts. After signing in successfully, you should see an Admin link on the top right. Click on the Admin link to access the Administrator Dashboard. There are currently three actions available to the Administrator in the Workbench, shown in Figure 3. From here you can assign users, deploy demo contracts, and deploy custom contracts.
Figure 3 The Administrator Dashboard
Clicking on Deploy Demo Contract in the Administrator Dashboard brings you to a list of all the demo contracts that can be provided. The current release of Blockchain Workbench contains a set of demo smart contracts and configuration files to get you started. The Workbench documentation provides more information about the specific scenarios and a step-by-step walk-through of the UI. There are also detailed instructions on how the demo smart contracts and associated configuration files were created, and how to set up the right user accounts in Azure AD to enable this scenario.
Uploading a Custom Contract
You can also create custom contracts in any of the programming languages supported by the blockchain platform of reference, and deploy them in Azure Blockchain Workbench. All Azure Blockchain Workbench requires is three files that define business logic, interactions and visualizations of the implemented workflows. These are:
Smart Contract: To begin, you must create a smart contract that contains the business logic for the scenario. In the following example, the smart contract is targeting the Ethereum blockchain, so the contracts are written in the Solidity programming language.
Configuration: In the configuration file, users map properties, actions and blockchain protocol information for the smart contract. You also define what parameters are required from the participants for the instantiation and actions on the smart contract.
UI Configuration: In the configuration UI files, you define the UI for role-based access control at each state of the smart contract, such as restricting which personas can take specific actions. In this file, the user maps states and personas, and specifies state definitions, percentage complete at each state of the contract, and eligible actions at each state.
Smart Contract Creation
The contract definition contains a few components that must be specified to work with Azure Blockchain Workbench. Before defining the contract details specific to the scenario such as states, participants and the functions that describe the logic behind each action, you have to implement a LexingtonBase contract. The actual contract with the business logic for the business scenario will inherit from the LexingtonBase contract (which is equivalent to a class in C#), as shown in Figure 4.
Figure 4 LexingtonBase Contract
contract LexingtonBase {
event LexingtonContractCreated(string contractType, address originatingAddress);
event LexingtonContractUpdated(string contractType, string action, address originatingAddress);
string internal ContractType;
function LexingtonBase(string contractType) internal {
ContractType = contractType;
}
function ContractCreated() internal {
LexingtonContractCreated(ContractType, msg.sender);
}
function ContractUpdated(string action) internal {
LexingtonContractUpdated(ContractType, action, msg.sender);
}
}
Each contract should have a state that represents the current state of the contract, addresses for participants involved in the smart contract, data that’s stored in the contract, functions defining the business logic for different actions and a constructor for when the smart contract is instantiated. Figure 5 provides an example of the constructor and properties of the Asset Transfer smart contract.
Figure 5 Asset Transfer Smart Contract
contract AssetTransfer is LexingtonBase('AssetTransfer')
{
enum AssetState { Created, Active, OfferPlaced, PendingInspection,
Inspected, Appraised,
NotionalAcceptance, BuyerAccepted, SellerAccepted, Accepted,
Complete, Terminated }
address public Owner;
string public Description;
uint public AskingPrice;
AssetState public State;
address public Buyer;
uint public OfferPrice;
address public Inspector;
address public Appraiser;
function AssetTransfer(string description, uint256 price)
{
Owner = msg.sender;
AskingPrice = price;
Description = description;
State = AssetState.Active;
ContractCreated();
}
}
Be sure that your class name and constructor name match. You can find the sample source code in Solidity language for this smart contract, along with the JSON configuration files, on my GitHub repository at bit.ly/2HJPcET.
Configuration File Creation
The configuration file defines the main properties and parameters for the smart contract. This includes listing out all properties and types, as well as defining a constructor indicating what parameters the user needs to input to instantiate the smart contract. Figure 6 shows an example of the Asset Transfer properties and constructor from the configuration file.
Figure 6 Asset Transfer Properties and Constructor
"Properties": {
"State": {
"Type": "state"
},
"Owner": {
"Type": "user"
},
"Description": {
"Type": "string"
},
"AskingPrice": {
"Type": "money"
},
"Buyer": {
"Type": "user"
},
"OfferPrice": {
"Type": "money"
},
"Inspector": {
"Type": "user"
},
"Appraiser": {
"Type": "user"
}
},
"Constructor": {
"description": {
"Type": "string"
},
"price": {
"Type": "money"
}
},
In addition, the user must enumerate and provide detail for all possible actions, including specifying input parameters for each action. Figure 7 shows an example of the MakeOffer action specification from the Asset Transfer configuration file, which requires the user to input an inspector, appraiser and an offer price.
Figure 7 MakeOffer Action Specification
"MakeOffer": {
"Parameters": {
"inspector": {
"Type": "user"
},
"appraiser": {
"Type": "user"
},
"offerPrice": {
"Type": "money"
}
}
},
Last, include the blockchain configuration information, as follows:
"Chains": {
"Ethereum": {
"Type": "Ethereum",
"Version": "1.0",
"Location": "AssetTransfer.sol",
"TypeName": "AssetTransfer",
"ActionOverrides": {},
"PropertyOverrides": {}
}
}
UI Configuration File Creation
Users define the UI details for each action in the UI configuration file. This includes details on the users, such as the initiator or participant role and persona mapping, state mappings, as well as a constructor indicating text to be displayed when a user wants to instantiate the smart contract. Figure 8 shows an example of the Asset Transfer properties and constructor from the UI configuration file.
Figure 8 InitiatingRoles
"InitiatingRoles": [
"Admin",
"User"
],
"Personas": {
"Owner": {
"Role": "Initiator",
"IsInitiator": true,
"PropertyMapping": "Owner"
},
"Buyer": {
"Role": "Participant",
"PropertyMapping": "Buyer"
},
"Appraiser": {
"Role": "Participant",
"PropertyMapping": "Appraiser"
},
"Inspector": {
"Role": "Participant",
"PropertyMapping": "Inspector"
}
},
"StateProperty": "State",
"StateMapping": {
"Created": 0,
"Active": 1,
"OfferPlaced": 2,
"PendingInspection": 3,
"Inspected": 4,
"Appraised": 5,
"NotionalAcceptance": 6,
"BuyerAccepted": 7,
"SellerAccepted": 8,
"Accepted": 9,
"Complete": 10,
"Terminated": 11
},
"Constructor": {
"DisplayName": "Create Asset Transfer",
"Description": "Description of asset transfer"
},
In addition, the user should enumerate all possible states and include details for each state specifying actions that can be taken at each step per persona, as well as a percentage-complete value to give users a visualization of progress through the smart contract. For example, the Asset Transfer contract UI configuration file shows that once the state shows an offer has been placed, only owners and buyers can take specified actions, as shown in the code in Figure 9.
Figure 9 OfferPlaced Code
"OfferPlaced": {
"PercentComplete": 30,
"Style": "Success",
"Actions": {
"Owner": {
"AcceptOffer": {},
"Reject": {},
"Terminate": {}
},
"Buyer": {
"RescindOffer": {}
}
}
}
Once you’ve created your custom smart contract and associated configuration files, the next task is to deploy the smart contract. After selecting Upload Custom Contract in the Administrator Dashboard of Azure Blockchain Workbench, you’ll see a page to upload your custom contract and configuration files. There are three files that you need to provide. Select the smart contract file and the two config files created earlier, as indicated in the Upload Contract screen depicted In Figure 10.
Figure 10 The Upload Contract Screen
User Assignment
Once a smart contract (demo or custom) is deployed, users with initiator personas can create new contract instances. To create an instance of a particular contract, the user must have a persona associated with that contract. Depending on the specification of the smart contract, not every persona may have rights to create a contract. As an administrator, you can assign a user to a contract and specify their role (the persona) in the business process. Note that before an administrator can perform any user assignment actions, there must be at least one contract (demo or custom) deployed. Once a contract is uploaded, the next step is to complete the user assignment for the contract. Administrators can assign users to smart contracts from the User Assignment screen in the Azure Blockchain Workbench Administrator Dashboard.
Once assigned to contracts, users can participate in the smart contract workflows by signing in to Azure Blockchain Workbench to create contracts. Say that the user wants to generate a new asset transfer, as shown in Figure 11. He or she must create a new contract by clicking Create New Contract on the upper right of the view and enter the details for the contract (this view will vary based on your smart contract) and submit. The screen is automatically generated, based on the metadata provided as part of the Smart Contract definition.
Figure 11 Entering Contract Details
After a contract instance is created, a user can drill down into the details to view available actions, given the current state of the contract.
Extending Azure Blockchain Workbench
At the core of Azure Blockchain Workbench is Azure Service Bus, enabling an extensible and pluggable model that allows multiple distributed ledger technologies, storage and database offerings to be used as part of the blockchain solution. There are also opportunities to integrate other services with the Workbench to extend functionality, such as with Azure Logic Apps, Web APIs, Notification Hubs and the like. Off-chain storage of data will allow for post-processing storage and analytics scenarios, with options such as with Power BI, Azure Machine Learning, HD Insight, Azure Data Lake and other services where contract data is shared.
Blockchain has the potential to extend digital transformation beyond a company’s walls and into the processes it shares with suppliers, customers and partners. As I’ve shown, at its core a blockchain is both a computing and data structure that can be used to create a digital transaction ledger that, instead of resting with a single provider, is shared among a distributed network of computers. The result is a more transparent and verifiable system that will change the way you think about exchanging value and assets, enforcing contracts, and sharing data.
Microsoft is committed to bringing blockchain to the enterprise and bringing the full benefits of Azure to bear for developers and organizations looking to build distributed applications. The goal is to help companies thrive in this new era of secure, multi-party computation by delivering scalable platforms and services that any company—from ledger startups and retailers to health providers and global banks—can use to improve shared business processes. Azure Blockchain Workbench is part of an ecosystem of services in Azure, along with the announced Azure Confidential Computing and the Confidential Consortium Blockchain Framework, that helps bridge the gap between the blockchain world and enterprise requirements for governance, security and scalability. Watch this space for additional development in the near future!
Stefano Tempesta is a Microsoft Regional Director and MVP, as well as chapter leader for CRMUG in Switzerland, the largest community of Dynamics 365/CRM experts in the world. Tempesta is an instructor of courses about Dynamics 365, blockchain and machine learning, and a regular speaker at international IT conferences, including Microsoft Ignite and Tech Summit. He founded Blogchain Space (blogchain.space), a blog about blockchain technologies, writes for MSDN Magazine and MS Dynamics World, and publishes machine learning experiments on the Azure AI Gallery (gal-lery.azure.ai).