Azure Blockchain Workbench

Contents
Azure Blockchain Workbench (public preview)

Overview
About Azure Blockchain Workbench
Concepts
Architecture
Integration patterns
How-to guides
Deploy Workbench
Create blockchain app
Manage Workbench users
Use blockchain app
Use Workbench API
Troubleshoot apps
Use Workbench data
Configure DB firewall
Get DB details
Use data in Excel
Use data in Power BI
Use data in SQL Management Studio
Reference
Configuration
Database views
Messaging API
REST API
Resources
Blog
Code samples
Community
Forum
Product feedback
Solution templates
Ethereum Proof-of-Authority Consortium
Ethereum Proof-of-Work Consortium
Hyperledger Fabric Consortium
What is Azure Blockchain Workbench?
10/2/2018 • 2 minutes to read • Edit Online
Azure Blockchain Workbench is a collection of Azure services and capabilities designed to help you create and
deploy blockchain applications to share business processes and data with other organizations. Azure Blockchain
Workbench provides the infrastructure scaffolding for building blockchain applications enabling developers to
focus on creating business logic and smart contracts. It also makes it easier to create blockchain applications by
integrating several Azure services and capabilities to help automate common development tasks.
Create blockchain applications

With Blockchain Workbench, you can define blockchain applications using configuration and writing smart contract
code. You can jumpstart blockchain application development and focus on defining your contract and writing
business logic instead of building scaffolding and setting up supporting services.
Manage applications and users

Azure Blockchain Workbench provides a web application and REST APIs for managing blockchain applications and
users. Blockchain Workbench administrators can manage application access and assign your users to application
roles. Azure AD users are automatically mapped to members in the application.
Integrate blockchain with applications

You can use the Blockchain Workbench REST APIs and message-based APIs to integrate with existing systems.
The APIs provide an interface to allow for replacing or using multiple distributed ledger technologies, storage, and
database offerings.
Blockchain Workbench can transform messages sent to its message-based API to build transactions in a format
expected by that blockchain’s native API. Workbench can sign and route transactions to the appropriate blockchain.
Workbench automatically delivers events to Service Bus and Event Grid to send messages to downstream
consumers. Developers can integrate with either of these messaging systems to drive transactions and to look at
results.
Deploy a blockchain network

Azure Blockchain Workbench simplifies consortium blockchain network setup as a preconfigured solution with an
Azure Resource Manager solution template. The template provides simplified deployment that deploys all
components needed to run a consortium. Today, Blockchain Workbench currently supports Ethereum.
Use Active Directory login

With existing blockchain protocols, blockchain identities are represented as an address on the network. Azure
Blockchain Workbench abstracts away the blockchain identity by associating it with an Active Directory identity,
making it simpler to build enterprise applications with Active Directory identities.
Synchronize on-chain data with off-chain storage

Azure Blockchain Workbench makes it easier to analyze blockchain events and data by automatically synchronizing
data on the blockchain to off-chain storage. Instead of extracting data directly from the blockchain, you can query
off-chain database systems such as SQL Server. Blockchain specific expertise is not required for end users who are
doing data analysis tasks.
Next steps
Azure Blockchain Workbench architecture
Azure Blockchain Workbench simplifies blockchain application development by providing a solution using several
Azure components. Blockchain Workbench can be deployed using a solution template in the Azure Marketplace.
The template allows you to pick modules and components to deploy including blockchain stack, type of client
application, and support for IoT integration. Once deployed, Blockchain Workbench provides access to a web app,
iOS app, and Android app.
Identity and authentication

Using Blockchain Workbench, a consortium can federate their enterprise identities using Azure Active Directory
(Azure AD ). Workbench generates new user accounts for on-chain identities with the enterprise identities stored in
Azure AD. The identity mapping facilitates authenticated login to client APIs and applications and uses the
authentication policies of organizations. Workbench also provides the ability to associate enterprise identities to
specific roles within a given smart contract. In addition, Workbench also provides a mechanism to identify the
actions those roles can take and at what time.
After Blockchain Workbench is deployed, users interact with Blockchain Workbench either via the client
applications, REST-based client API, or Messaging API. In all cases, interactions must be authenticated, either via
Azure Active Directory (Azure AD ) or device-specific credentials.
Users federate their identities to a consortium Azure AD by sending an email invitation to participants at their
email address. When logging in, these users are authenticated using the name, password, and policies. For
example, two-factor authentication of their organization.
Azure AD is used to manage all users who have access to Blockchain Workbench. Each device connecting to a
smart contract is also associated with Azure AD.
Azure AD is also used to assign users to a special administrator group. Users associated with the administrator
group are granted access to rights and actions within Blockchain Workbench including deploying contracts and
giving permissions to a user to access a contract. Users outside this group do not have access to administrator
actions.
Client applications
Workbench provides automatically generated client applications for web and mobile (iOS, Android), which can be
used to validate, test, and view blockchain applications. The application interface is dynamically generated based
on smart contract metadata and can accommodate any use case. The client applications deliver a user-facing front
end to the complete blockchain applications generated by Blockchain Workbench. Client applications authenticate
users via Azure Active Directory (Azure AD ) and then present a user experience tailored to the business context of
the smart contract. The user experience enables the creation of new smart contract instances by authorized
individuals and then presents the ability to execute certain types of transactions at appropriate points in the
business process the smart contract represents.
In the web application, authorized users can access the Administrator Console. The console is available to users in
the Administrator group in Azure AD and provides access to the following functionality:
Deploy Microsoft provided smart contracts for popular scenarios. For example, an asset transfer scenario.
Upload and deploy their own smart contracts.
Assign a user access to the smart contract in the context of a specific role.
Gateway service API

Blockchain Workbench includes a REST-based gateway service API. When writing to a blockchain, the API
generates and delivers messages to an event broker. When data is requested by the API, queries are sent to the
off-chain SQL database. The SQL database contains a replica of on-chain data and metadata that provides context
and configuration information for supported smart contracts. Queries return the required data from the off-chain
replica in a format informed by the metadata for the contract.
Developers can access the gateway service API to build or integrate blockchain solutions without relying on
Blockchain Workbench client apps.
NOTE
To enable authenticated access to the API, two client applications are registered in Azure Active Directory. Azure Active
Directory requires distinct application registrations each application type (native and web).
Message broker for incoming messages

Developers who want to send messages directly to Blockchain Workbench can send messages directly to Service
Bus. For example, messages API could be used for system-to-system integration or IoT devices.
Message broker for downstream consumers

During the lifecycle of the application, events occur. Events can be triggered by the Gateway API or on the ledger.
Event notifications can initiate downstream code based on the event.
Blockchain Workbench automatically deploys two types of event consumers. One consumer is triggered by
blockchain events to populate the off-chain SQL store. The other consumer is to capture metadata for events
generated by the API related to the upload and storage of documents.
Message consumers
Message consumers take messages from Service Bus. The underlying eventing model for message consumers
allows for extensions of additional services and systems. For example, you could add support to populate
CosmosDB or evaluate messages using Azure Streaming Analytics. The following sections describe the message
consumers included in Blockchain Workbench.
Distributed ledger consumer
Distributed ledger technology (DLT) messages contain the metadata for transactions to be written to the
blockchain. The consumer retrieves the messages and pushes the data to a transaction builder, signer, and router.
Database consumer
The database consumer takes messages from Service Bus and pushes the data to an attached database, such as
SQL database.
Storage consumer
The storage consumer takes messages from Service Bus and pushes data to an attached storage. For example,
storing hashed documents in Azure Storage.
Transaction builder and signer

If a message on the inbound message broker needs to be written to the blockchain, it will be processed by the DLT
consumer. The DLT consumer is a service, which retrieves the message containing metadata for a desired
transaction to execute and then sends the information to the transaction builder and signer. The transaction
builder and signer assembles a blockchain transaction based on the data and the desired blockchain destination.
Once assembled, the transaction is signed. Private keys are stored in Azure Key Vault.
Blockchain Workbench retrieves the appropriate private key from Key Vault and signs the transaction outside of
Key Vault. Once signed, the transaction is sent to transaction routers and ledgers.
Transaction routers and ledgers

Transaction routers and ledgers take signed transactions and route them to the appropriate blockchain. Currently,
Blockchain Workbench supports Ethereum as its target blockchain.
DLT watcher
A distributed ledger technology (DLT) watcher monitors events occurring on block chains attached to Blockchain
Workbench. Events reflect information relevant to individuals and systems. For example, the creation of new
contract instances, execution of transactions, and changes of state. The events are captured and sent to the
outbound message broker, so they can be consumed by downstream consumers.
For example, the SQL consumer monitors events, consumes them, and populates the SQL database with the
included values. The copy enables recreation of a replica of on-chain data in an off-chain store.
Azure SQL database

The Azure SQL database attached to Blockchain Workbench stores contract definitions, configuration metadata,
and a SQL -accessible replica of data stored in the blockchain. This data can easily be queried, visualized, or
analyzed by directly accessing the database. Developers and other users can use the database for reporting,
analytics, or other data-centric integrations. For example, users can visualize transaction data using Power BI.
This off-chain storage provides the ability for enterprise organizations to query data in SQL rather than in a
blockchain ledger. Also, by standardizing on a standard schema that's agnostic of blockchain technology stacks, the
off-chain storage enables the reuse of reports and other artifacts across projects, scenarios, and organizations.
Azure Storage
Azure Storage is used to store contracts and metadata associated with contracts.
From purchase orders and bills of lading, to images used in the news and medical imagery, to video originating
from a continuum including police body cameras and major motion pictures, documents play a role in many
blockchain-centric scenarios. Documents are not appropriate to place directly on the blockchain.
Blockchain Workbench supports the ability to add documents or other media content with blockchain business
logic. A hash of the document or media content is stored in the blockchain and the actual document or media
content is stored in Azure Storage. The associated transaction information is delivered to the inbound message
broker, packaged up, signed, and routed to the blockchain. This process triggers events, which are shared via the
outbound message broker. The SQL DB consumes this information and sends it to the DB for later querying.
Downstream systems could also consume these events to act as appropriate.
Monitoring
Workbench provides application logging using Application Insights and Azure Monitor. Application Insights is
used to store all logged information from Blockchain Workbench and includes errors, warnings, and successful
operations. Application Insights can be used by developers to debug issues with Blockchain Workbench.
Azure Monitor provides information on the health of the blockchain network.
Next steps
Deploy Azure Blockchain Workbench
Smart contract integration patterns
Smart contracts will often represent a business workflow that needs to integrate with external systems and devices.
The requirements of these workflows include a need to initiate transactions on a distributed ledger that include
data from an external system, service, or device. They also need to have external systems react to events
originating from smart contracts on a distributed ledger.
The REST API and messaging integration provide the ability to both send transactions from external systems to
smart contracts included in an Azure Blockchain Workbench application, as well as send event notifications to
external systems based on changes that take place within an application.
For data integration scenarios, Azure Blockchain Workbench includes a set of database views that merge a
combination of transactional data from the blockchain and meta-data about applications and smart contracts.
In addition, some scenarios, such as those related to supply chain or media, may also require the integration of
documents. While Azure Blockchain Workbench does not provide API calls for handling documents directly,
documents can be incorporated into an Azure Blockchain Application. This section also includes that pattern.
This section includes the patterns identified for implementing each of these types of integrations in your end to end
solutions.
REST API-based integration

Capabilities within the Azure Blockchain Workbench generated web application are exposed via the REST API.
Capabilities include Azure Blockchain Workbench uploading, configuration and administration of applications,
sending transactions to a distributed ledger, and the querying of application metadata and ledger data.
The REST API is primarily used for interactive clients such as web, mobile, and bot applications.
This section looks at patterns focused on the aspects of the REST API that send transactions to a distributed ledger
and those that query data about transactions from Azure Blockchain Workbench's off chain SQL database.
Sending transactions to a distributed ledger from an external system
The Azure Blockchain Workbench REST API provides the ability to send authenticated requests to execute
transactions on a distributed ledger.
This occurs using the process depicted above, where:

The external application authenticates to the Azure Active Directory provisioned as part of the Azure Blockchain
Workbench deployment.
Authorized users receive a bearer token that can be sent with requests to the API.
External applications make calls to the REST API using the bearer token.
The REST API packages the request as a message and sends it to the Service Bus. From here it will be retrieved,
signed, and sent to the appropriate distributed ledger.
The REST API makes a request to the Azure Blockchain Workbench SQL DB to record the request and establish
the current provisioning status.
The SQL DB returns the provisioning status and the API call returns the ID to the external application that
called it.
Querying Blockchain Workbench metadata and distributed ledger transactions
The Azure Blockchain Workbench REST API provides the ability to send authenticated requests to query details
related to smart contract execution on a distributed ledger.

1. The external application authenticates to the Azure Active Directory provisioned as part of the Azure Blockchain
Workbench deployment.
2. Authorized users receive a bearer token that can be sent with requests to the API.
3. External applications make calls to the REST API using the bearer token.
4. The REST API queries the data for the request from the SQL DB and returns it to the client.
Messaging integration
Messaging integration facilitates interaction with systems, services, and devices where an interactive login is not
possible or desirable. Messaging integration focuses on two types of messages, those that request that transactions
be executed on a distributed ledger and events that are exposed by that ledger when transactions have taken place.
Messaging integration focuses on the execution and monitoring of transactions related to user creation, contract
creation, and execution of transactions on contracts and is primarily used by headless back-end systems.
This section looks at patterns focused on the aspects of the message-based API that send transactions to a
distributed ledger and those that represent event messages exposed by the underlying distributed ledger.
One -way event delivery from a smart contract to an event consumer
In this scenario, an event occurs within a smart contract, for example, a state change or the execution of a specific
type of transaction. This event is broadcast via an Event Grid to downstream consumers, and those consumers then
take appropriate actions.
An example of this scenario is that when a transaction occurs, a consumer would be alerted and could take action,
such as recording the information in a SQL DB or the Common Data Service. This is the same pattern that
Workbench follows to populate its off chain SQL DB.
Another would be if a smart contract transitions to a particular state, for example when a contract goes into an
OutOfCompliance. When this state change happens, it could trigger an alert to be sent to an administrator's
mobile phone.
The smart contract transitions to a new state and sends an event to the ledger.
The ledger receives and delivers the event to Azure Blockchain Workbench.
Azure Blockchain Workbench is subscribed to events from the ledger and receives the event.
Azure Blockchain Workbench publishes the event to subscribers on the Event Grid.
External systems are subscribed to the Event Grid, consume the message, and take the appropriate action(s).
One-way event delivery of a message from an external system to a

smart contract
There is also a scenario that flows from the opposite direction. In this case, an event is generated by a sensor or an
external system and the data from that event should be sent to a smart contract.
A common example is the delivery of data from financial markets, for example, prices of commodities, stock, or
bonds, to a smart contract.
Direct delivery of an Azure Blockchain Workbench in the expected format
Some applications are built to integrate with Azure Blockchain Workbench and directly generates and send
messages in the expected formats.

An event occurs in an external system that triggers the creation of a message for Azure Blockchain Workbench.
The external system has code written to create this message in a known format and sends this directly to the
Service Bus.
Azure Blockchain Workbench is subscribed to events from the Service Bus and retrieves the message.
Azure Blockchain Workbench initiates a call to the ledger, sending data from the external system to a specific
contract.
Upon receipt of the message, the contract transitions to a new state.
Delivery of a message in a format unknown to Azure Blockchain Workbench
Some systems cannot be modified to deliver messages in the standard formats used by Azure Blockchain
Workbench. In these cases, existing mechanisms and message formats from these systems can often be used.
Specifically, the native message types of these systems can be transformed using Logic Apps, Azure Functions, or
other custom code to map to one of the standard messaging formats expected.

An event occurs in an external system that triggers the creation of a message.
A Logic App or custom code is used to receive that message and transform it to a standard Azure Blockchain
Workbench formatted message.
The Logic App sends the transformed message directly to the Service Bus.
function on the contract.
The function executes and typically modifies the state. The change of state moves forward the business
workflow reflected in the smart contract, enabling other functions to now be executed as appropriate.
Transitioning control to an external process and await completion
There are scenarios where a smart contract must stop internal execution and hand off to an external process. That
external process would then complete, send a message to the smart contract, and execution would then continue
within the smart contract.
Transition to the external process
This pattern is typically implemented using the following approach:
The smart contract transitions to a specific state. In this state, either no or a limited number of functions can be
executed until an external system takes a desired action.
The change of state is surfaced as an event to a downstream consumer.
The downstream consumer receives the event and triggers external code execution.
Return of control from the smart contract
Depending on the ability to customize the external system it may or may not be able to deliver messages in one of
the standard formats that Azure Blockchain Workbench expects. Based on the external systems ability to generate
one of these messages will determine which of the following two return paths will be taken.
D i r e c t d e l i v e r y o f a n A z u r e B l o c k c h a i n W o r k b e n c h i n t h e e x p e c t e d fo r m a t
In this model, the communication to the contract and subsequent state change occurs following the above process
where -
Upon reaching the completion or a specific milestone in the external code execution, an event is sent to the
Service Bus connected to Azure Blockchain Workbench.
For systems that can't be directly adapted to write a message that conforms to the expectations of the API, it
will be transformed.
The content of the message is packaged up and sent to a specific function on the smart contract. This is
done on behalf of the user associated with the external system.
The function executes and typically will modify the state. The change of state moves forward the business
Delivery of a message in a format unknown to Azure Blockchain Workbench
In this model where a message in a standard format cannot be sent directly, the communication to the contract and
subsequent state change occurs following the above process where:
1. Upon reaching the completion or a specific milestone in the external code execution, an event is sent to the
Service Bus connected to Azure Blockchain Workbench.
2. A Logic App or custom code is used to receive that message and transform it to a standard Azure Blockchain
Workbench formatted message.
3. The Logic App sends the transformed message directly to the Service Bus.
4. Azure Blockchain Workbench is subscribed to events from the Service Bus and retrieves the message.
5. Azure Blockchain Workbench initiates a call to the ledger, sending data from the external system to a specific
contract.
6. The content of the message is packaged up and sent to a specific function on the smart contract. This is done on
behalf of the user associated with the external system.
7. The function executes and typically will modify the state. The change of state moves forward the business
IoT integration
A common integration scenario is the inclusion of telemetry data retrieved from sensors in a smart contract. Based
on data delivered by sensors, smart contracts could take informed actions and alter the state of the contract.
For example, if a truck delivering medicine had its temperature soar to 110 degrees, it may impact the effectiveness
of the medicine and may cause a public safety issue if not detected and removed from the supply chain. If a driver
accelerated his car to 100 miles per hour, the resulting sensor information could trigger a cancelation of insurance
by his insurance provider. If the car was a rental car, GPS data could indicate when the driver went outside a
geography covered by his rental agreement and charge a penalty.
The challenge is that these sensors can be delivering data on a constant basis and it is not appropriate to send all of
this data to a smart contract. A typical approach is to limit the number of messages sent to the blockchain while
delivering all messages to a secondary store. For example, deliver messages received at only fixed interval, for
example, once per hour, and when a contained value falls outside of an agreed upon range for a smart contract.
Checking values that fall outside of tolerances, ensures that the data relevant to the contracts business logic is
received and executed. Checking the value at the interval confirms that the sensor is still reporting. All data is sent
to a secondary reporting store to enable broader reporting, analytics, and machine learning. For example, while
getting sensor readings for GPS may not be required every minute for a smart contract, they could provide
interesting data to be used in reports or mapping routes.
On the Azure platform, integration with devices is typically done with IoT Hub. IoT Hub provides the ability to
route messages based on content, and enables the type of functionality described above.
The process above depicts a pattern for this is implemented:
A device communicates directly or via a field gateway to IoT Hub.
IoT Hub receives the messages and evaluates the messages against routes established that check the content of
the message, for example. Does the sensor report a temperature greater than 50 degrees?
The IoT Hub sends messages that meet the criteria to a defined Service Bus for the route.
A Logic App or other code listens to the Service Bus that IoT Hub has established for the route.
The Logic App or other code retrieves and transform the message to a known format.
The transformed message, now in a standard format, is sent to the Service Bus for Azure Blockchain
Workbench.
contract.
Upon receipt of the message, the contract evaluates the data and may change the state based on the outcome of
that evaluation, for example, for a high temperature, change the state to Out of Compliance.
Data integration
In addition to REST and message-based API, Azure Blockchain Workbench also provides access to a SQL DB
populated with application and contract meta-data as well as transactional data from distributed ledgers.
The data integration is well known:

Azure Blockchain Workbench stores metadata about applications, workflows, contracts, and transactions as part
of its normal operating behavior.
External systems or tools provide one or more dialogs to facilitate the collection of information about the
database, such as database server name, database name, type of authentication, login credentials, and which
database views to utilize.
Queries are written against SQL database views to facilitate downstream consumption by external systems,
services, reporting, developer tools, and enterprise productivity tools.
Storage integration
Many scenarios may require the need to incorporate attestable files. For multiple reasons, it will be inappropriate
to put files on a blockchain. Instead, a common approach is to perform a cryptographic hash (for example, SHA-
256) against a file and share that hash on a distributed ledger. Performing the hash again at any future time should
return the same result. If the file is modified, even if just one pixel is modified in an image, the hash will return a
different value.
The pattern can be implemented where:

An external system persists a file in a storage mechanism, such as Azure Storage.
A hash is generated with the file or the file and associated metadata such as an identifier for the owner, the URL
where the file is located, etc.
The hash and any metadata is sent to a function on a smart contract, such as FileAdded
In future, the file and meta-data can be hashed again and compared against the values stored on the ledger.
Prerequisites for implementing integration patterns using the REST and

message APIs
To facilitate the ability for an external system or device to interact with the smart contract using either the REST or
message API, the following must occur -
1. In the Azure Active Directory for the consortium, an account is created that represents the external system or
device.
2. The appropriate smart contract(s) for your Azure Blockchain Workbench application have functions defined to
accept the events from your external system or device.
3. The Application configuration file for your smart contract contains the role, which the system or device will be
assigned.
4. The Application configuration file for your smart contract identifies in which states this function can be called by
the defined role.
5. The Application configuration file and its smart contracts are uploaded to Azure Blockchain Workbench.
Once the application is uploaded, the Azure Active Directory account for the external system is assigned to the
contract and the associated role.
Testing External System Integration Flows Prior to Writing Integration

Code
Providing the ability to integrate with external systems is a key requirement of many scenarios. It is desirable to be
able to validate smart contract design prior or in parallel to the development of code to integrate with external
systems.
The use of Azure Active Directory (Azure AD ) can greatly accelerate developer productivity and time to value.
Specifically, the code integration with an external system may take a non-trivial amount of time. By using Azure AD
and the auto-generation of UX by Azure Blockchain Workbench, this can allow developers to log in to Workbench
as that external system and populate values expected from that external system via the UX. This allows for rapidly
developing and validating of ideas in a proof of concept environment either prior to or in parallel to integration
code being written for the external systems.
Deploy Azure Blockchain Workbench
Azure Blockchain Workbench is deployed using a solution template in the Azure Marketplace. The template
simplifies the deployment of components needed to create blockchain applications. Once deployed, Blockchain
Workbench provides access to client apps to create and manage users and blockchain applications.
For more information about the components of Blockchain Workbench, see Azure Blockchain Workbench
architecture.
Prepare for deployment

Blockchain Workbench allows you to deploy a blockchain ledger along with a set of relevant Azure services most
often used to build a blockchain-based application. Deploying Blockchain Workbench results in the following
Azure services being provisioned within a resource group in your Azure subscription.
1 Event Grid Topic
1 Service Bus Namespace
1 Application Insights
1 SQL Database (Standard S0)
2 App Services (Standard)
2 Azure Key Vaults
2 Azure Storage accounts (Standard LRS )
2 Virtual machine scale sets (for validator and worker nodes)
2 Virtual Networks (including load balancer, network security group, and public IP address for each virtual
network)
Optional: Azure Monitor
The following is an example deployment created in myblockchain resource group.
The cost of Blockchain Workbench is an aggregate of the cost of the underlying Azure services. Pricing
information for Azure services can be calculated using the pricing calculator.
Azure Blockchain Workbench requires several prerequisites prior to the deployment. The prerequisites include
Azure AD configuration and application registrations.
Blockchain Workbench API app registration
Blockchain Workbench deployment requires registration of an Azure AD application. You need an Azure Active
Directory (Azure AD ) tenant to register the app. You can use an existing tenant or create a new tenant. If you are
using an existing Azure AD tenant, you need sufficient permissions to register applications and grant Graph API
permissions within an Azure AD tenant. If you do not have sufficient permissions in an existing Azure AD tenant
create a new tenant.
IMPORTANT
Workbench does not have to be deployed in the same tenant as the one you are using to register an Azure AD application.
Workbench must be deployed in a tenant where you have sufficient permissions to deploy resources. For more information
on Azure AD tenants, see How to get an Active Directory tenant and Integrating applications with Azure Active Directory.
1. Sign in to the Azure portal.

2. Select your account in the top right corner, and switch to the desired Azure AD tenant. The tenant should be the
subscription admin's tenant of the subscription where Workbench is deployed and you have sufficient
permissions to register applications.
3. In the left-hand navigation pane, select the Azure Active Directory service. Select App registrations >
New application registration.
4. Provide a Name and Sign-on URL for the application. You can use placeholder values since the values are
changed during the deployment.
SETTING VALUE
Name Blockchain API
Application type Web app / API
Sign-on URL https://blockchainapi
5. Select Create to register the Azure AD application.

Modify application manifest
Next, you need to modify the application manifest to use application roles within Azure AD to specify Blockchain
Workbench administrators. For more information about application manifests, see Azure Active Directory
application manifest.
1. For the application you registered, select Manifest in the registered application details pane.
2. Generate a GUID. You can generate a GUID using the PowerShell command [guid] :: NewGuid () or New -GUID
cmdlet. Another option is to use a GUID generator website.
3. You are going to update the appRoles section of the manifest. In the Edit manifest pane, select Edit and
replace "appRoles": [] with the provided JSON. Be sure to replace the value for the id field with the GUID
you generated.
"appRoles": [
{
"allowedMemberTypes": [
"User",
"Application"
],
"displayName": "Administrator",
"id": "<A unique GUID>",
"isEnabled": true,
"description": "Blockchain Workbench administrator role allows creation of applications, user to
role assignments, etc.",
"value": "Administrator"
}
],
IMPORTANT
The value Administrator is needed to identify Blockchain Workbench administrators.
4. Click Save to save the application manifest changes.

Add Graph API required permissions
The API application needs to request permission from the user to access the directory. Set the following required
permission for the API application:
1. In the Blockchain API app registration, select Settings > Required permissions > Select an API >
Microsoft Graph.
Click Select.
2. In Enable Access under Application permissions, choose Read all users' full profiles.
Click Select then click Done.

3. In Required permissions, select Grant Permissions then select Yes for the verification prompt.
Granting permission allows Blockchain Workbench to access users in the directory. The read permission is
required to search and add members to Blockchain Workbench.
Add Graph API key to application
Blockchain Workbench uses Azure AD as the main identity management system for users interacting with
blockchain applications. In order for Blockchain Workbench to access Azure AD and retrieve user information,
such as names and emails, you need to add an access key. Blockchain Workbench uses the key to authenticate with
Azure AD.
1. For the application you registered, select Settings in the registered application details pane.
2. Select Keys.
3. Add a new key by specifying a key description and choosing expires duration value.
SETTING VALUE
Description Service
Expires Choose an expiration duration
4. Select Save.
5. Copy the value of the key and store it for later. You need it for deployment.
IMPORTANT
If you don't save the key for the deployment, you will need to generate a new key. You can't retrieve the key value
from the portal later.
Get application ID
The application ID and tenant information are required for deployment. Collect and store the information for use
during deployment.
1. For the application you registered, select Settings > Properties.
2. In the Properties pane, copy and store the following values for later use during deployment.
SETTING TO STORE USE IN DEPLOYMENT
Application ID Azure Active Directory setup > Application ID

Get tenant domain name
Collect and store the Active Directory tenant domain name where the applications are registered.
In the left-hand navigation pane, select the Azure Active Directory service. Select Custom domain names.
Copy and store the domain name.
Deploy Blockchain Workbench

Once the prerequisite steps have been completed, you are ready to deploy the Blockchain Workbench. The
following sections outline how to deploy the framework.
2. Select your account in the top right corner, and switch to the desired Azure AD tenant where you want to
deploy Azure Blockchain Workbench.
3. In the left pane, select Create a resource. Search for Azure Blockchain Workbench in the Search the
Marketplace search bar.
4. Select Azure Blockchain Workbench.

5. Select Create.
6. Complete the basic settings.
SETTING DESCRIPTION
Resource prefix Short unique identifier for your deployment. This value is
used as a base for naming resources.
VM user name The user name is used as administrator for all virtual
machines (VM).
Authentication type Select if you want to use a password or key for connecting
to VMs.
Password The password is used for connecting to VMs.
SSH Use an RSA public key in the single-line format beginning

with ssh-rsa or use the multi-line PEM format. You can
generate SSH keys using ssh-keygen on Linux and OS X,
or by using PuTTYGen on Windows. More information on
SSH keys, see How to use SSH keys with Windows on
Azure.
Database password / Confirm database password Specify the password to use for access to the database
created as part of the deployment.
Deployment region Specify where to deploy Blockchain Workbench resources.

For best availability, this should match the Location
setting.
Subscription Specify the Azure Subscription you wish to use for your
deployment.
Resource groups Create a new Resource group by selecting Create new

and specify a unique resource group name.
Location Specify the region you wish to deploy the framework.
7. Select OK to finish the basic setting configuration section.

8. Complete the Azure Active Directory setup.
SETTING DESCRIPTION
Domain Name Use the Azure AD tenant collected in the Get tenant
domain name prerequisite section.
Application ID Use the Application ID from the Blockchain client app

registration collected in the Get application ID prerequisite
section.
Application Key Use the Application key from the Blockchain client app
registration collected in the Add Graph API key to
application prerequisite section.
9. Click OK to finish the Azure AD Parameters configuration section.

10. In Network Settings and Performance, choose if you want to create a new blockchain network or use an
existing proof-of-authority blockchain network.
For Create new:
The create new option creates a set of Ethereum Proof-of Authority (PoA) nodes within a single member’s
subscription.
SETTING DESCRIPTION
Number of blockchain nodes Choose the number of Ethereum PoA validator nodes to
be deployed in your network.
Storage performance Choose the preferred VM storage performance for your

blockchain network.
Virtual machine size Choose the preferred VM size for your blockchain
network.
For Use existing:

The use existing option allows you to specify an Ethereum Proof-of-Authority (PoA) blockchain network.
Endpoints have the following requirements.
The endpoint must be an Ethereum Proof-of-Authority (PoA) blockchain network.
The endpoint must be publicly accessible over the network.
The PoA blockchain network should be configured to have gas price set to zero (Note: Blockchain
Workbench accounts are not funded. If funds are required, the transactions fail).
SETTING DESCRIPTION
Ethereum RPC Endpoint Provide the RPC endpoint of an existing PoA blockchain
network. The endpoint starts with http:// and ends with a
port number. For example,
http://contoso-chain.onmicrosoft.com:8545
Storage performance Choose the preferred VM storage performance for your

blockchain network.
Virtual machine size Choose the preferred VM size for your blockchain
network.
11. Select OK to finish network settings and performance.

12. Complete the Azure Monitor settings.
SETTING DESCRIPTION
SETTING DESCRIPTION
Monitoring Choose whether you want to enable Azure Monitor to

monitor your blockchain network
Connect to existing Log Analytics instance Choose whether you want to use an existing Log Analytics
instance or create a new one. If using an existing instance,
enter your workspace ID and primary key.
13. Click OK to finish the Azure Monitor section.

14. Review the summary to verify your parameters are accurate.
15. Select Create to agree to the terms and deploy your Azure Blockchain Workbench.
The deployment can take up to 90 minutes. You can use the Azure portal to monitor progress. In the newly created
resource group, select Deployments > Overview to see the status of the deployed artifacts.
Blockchain Workbench Web URL

Once the deployment of the Blockchain Workbench has completed, a new resource group contains your
Blockchain Workbench resources. Blockchain Workbench services are accessed through a web URL. The following
steps show you how to retrieve the web URL of the deployed framework.
2. In the left-hand navigation pane, select Resource groups
3. Choose the resource group name you specified when deploying Blockchain Workbench.
4. Click the TYPE column heading to sort the list alphabetically by type.
5. There are two resources with type App Service. Select the resource of type App Service without the "-api"
suffix.
6. In the App Service Essentials section, copy the URL value, which represents the web URL to your deployed
Blockchain Workbench.
To associate a custom domain name with Blockchain Workbench, see configuring a custom domain name for a
web app in Azure App Service using Traffic Manager.
Configuring the Reply URL

Once the Azure Blockchain Workbench has been deployed, the next step is to make sure the Azure Active
Directory (Azure AD ) client application is registered to the correct Reply URL of the deployed Blockchain
Workbench web URL.
2. Verify you are in the tenant where you registered the Azure AD client application.
3. In the left-hand navigation pane, select the Azure Active Directory service. Select App registrations.
4. Select the Azure AD client application you registered in the prerequisite section.
5. Select Settings > Reply URLs.
6. Specify the main web URL of the Azure Blockchain Workbench deployment you retrieved in the Get the
Azure Blockchain Workbench Web URL section. The Reply URL is prefixed with https:// . For example,
https://myblockchain2-7v75.azurewebsites.net
7. Select Save to update the client registration.

Remove a deployment
When a deployment is no longer needed, you can remove a deployment by deleting the Blockchain Workbench
resource group.
1. In the Azure portal, navigate to Resource group in the left navigation pane and select the resource group you
want to delete.
2. Select Delete resource group. Verify deletion by entering the resource group name and select Delete.
Next steps
In this how -to article, you deployed Azure Blockchain Workbench. To learn how to create a blockchain application,
continue to the next how -to article.
Create a blockchain application in Azure Blockchain Workbench
Create a blockchain application in Azure Blockchain
Workbench
You can use Azure Blockchain Workbench to create blockchain applications that represent multi-party workflows
defined by configuration and smart contract code.
You learn how to:
Configure a blockchain application
Create a smart contract code file
Add a blockchain application to Blockchain Workbench
Add members to the blockchain application
Prerequisites
A Blockchain Workbench deployment. For more information, see Azure Blockchain Workbench deployment for
details on deployment.
Azure Active Directory users in the tenant associated with Blockchain Workbench. For more information, see
add Azure AD users in Azure Blockchain Workbench.
A Blockchain Workbench administrator account. For more information, see add Blockchain Workbench
administrators in Azure Blockchain Workbench.
Hello, Blockchain!
Let's build a basic application in which a requestor sends a request and a responder send a response to the
request. For example, a request can be, "Hello, how are you?", and the response can be, "I'm great!". Both the
request and the response are recorded on the underlying blockchain.
Follow the steps to create the application files or you can download the sample from GitHub.
Configuration file
Configuration metadata 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.
1. In your favorite editor, create a file named HelloBlockchain.json .
2. Add the following JSON to define the configuration of the blockchain application.
{
"ApplicationName": "HelloBlockchain",
"DisplayName": "Hello, Blockchain!",
"Description": "A simple application to send request and get response",
"ApplicationRoles": [
{
"Name": "Requestor",
"Description": "A person sending a request."
},
{
"Name": "Responder",
"Description": "A person responding to a request"
}
],
],
"Workflows": [
{
"Name": "HelloBlockchain",
"DisplayName": "Request Response",
"Description": "A simple workflow to send a request and receive a response.",
"Initiators": [ "Requestor" ],
"StartState": "Request",
"Properties": [
{
"Name": "State",
"DisplayName": "State",
"Description": "Holds the state of the contract.",
"Type": {
"Name": "state"
}
},
{
"Name": "Requestor",
"DisplayName": "Requestor",
"Description": "A person sending a request.",
"Type": {
"Name": "Requestor"
}
},
{
"Name": "Responder",
"DisplayName": "Responder",
"Description": "A person sending a response.",
"Type": {
"Name": "Responder"
}
},
{
"Name": "RequestMessage",
"DisplayName": "Request Message",
"Description": "A request message.",
"Type": {
"Name": "string"
}
},
{
"Name": "ResponseMessage",
"DisplayName": "Response Message",
"Description": "A response message.",
"Type": {
"Name": "string"
}
}
],
"Constructor": {
"Parameters": [
{
"Name": "message",
"Description": "...",
"Type": {
"Name": "string"
}
}
]
},
"Functions": [
{
"Name": "SendRequest",
"DisplayName": "Request",
"Parameters": [
{
"Name": "requestMessage",
"Name": "requestMessage",
"Type": {
"Name": "string"
}
}
]
},
{
"Name": "SendResponse",
"DisplayName": "Response",
"Parameters": [
{
"Name": "responseMessage",
"DisplayName": "Response Message",
"Type": {
"Name": "string"
}
}
]
}
],
"States": [
{
"Name": "Request",
"DisplayName": "Request",
"PercentComplete": 50,
"Value": 0,
"Style": "Success",
"Transitions": [
{
"AllowedRoles": ["Responder"],
"AllowedInstanceRoles": [],
"Function": "SendResponse",
"NextStates": [ "Respond" ],
"DisplayName": "Send Response"
}
]
},
{
"Name": "Respond",
"DisplayName": "Respond",
"Value": 1,
"Style": "Success",
"Transitions": [
{
"AllowedRoles": [],
"AllowedInstanceRoles": ["Requestor"],
"Function": "SendRequest",
"NextStates": [ "Request" ],
"DisplayName": "Send Request"
}
]
}
]
}
]
}
3. Save the HelloBlockchain.json file.

The configuration file has several sections. Details about each section are as follows:
Application metadata
The beginning of the configuration file contains information about the application including application name and
description.
Application roles
The application roles section defines the user roles who can act or participate within the blockchain application.
You define a set of distinct roles based on functionality. In the request-response scenario, there is a distinction
between the functionality of a requestor as an entity that produces requests and a responder as an entity that
produces responses.
Workflows
Workflows define one or more stages and actions of the contract. In the request-response scenario, the first stage
(state) of the workflow is a requestor (role) takes an action (transition) to send a request (function). The next stage
(state) is a responder (role) takes an action (transition) to send a response (function). An application's workflow can
involve properties, functions, and states required describe the flow of a contract.
For more information about the contents of configuration files, see Azure Blockchain Workflow configuration
reference.
Smart contract code file

Smart contracts represent the business logic of the blockchain application. Currently, Blockchain Workbench
supports Ethereum for the blockchain ledger. Ethereum uses Solidity as its programming language for writing
self-enforcing business logic for smart contracts.
Smart contracts in Solidity are similar to classes in object-oriented languages. Each contract contains state and
functions to implement stages and actions of the smart contract.
In your favorite editor, create a file called HelloBlockchain.sol .
Version pragma
As a best practice, indicate the version of Solidity you are targeting. Specifying the version helps avoid
incompatibilities with future Solidity versions.
Add the following version pragma at the top of HelloBlockchain.sol smart contract code file.
pragma solidity ^0.4.20;
Base class
WorkbenchBase base class enables Blockchain Workbench to create and update the contract. The base class is
required for Blockchain Workbench specific smart contract code. Your contract needs to inherit from the
WorkbenchBase base class.
In HelloBlockchain.sol smart contract code file, add the WorkbenchBase class at the beginning of the file.
contract WorkbenchBase {
event WorkbenchContractCreated(string applicationName, string workflowName, address originatingAddress);
event WorkbenchContractUpdated(string applicationName, string workflowName, string action, address
originatingAddress);
string internal ApplicationName;

string internal WorkflowName;
function WorkbenchBase(string applicationName, string workflowName) internal {

ApplicationName = applicationName;
WorkflowName = workflowName;
}
function ContractCreated() internal {

WorkbenchContractCreated(ApplicationName, WorkflowName, msg.sender);
}
function ContractUpdated(string action) internal {

WorkbenchContractUpdated(ApplicationName, WorkflowName, action, msg.sender);
}
}
The base class includes two important functions:
BASE CLASS FUNCTION PURPOSE WHEN TO CALL
ContractCreated() Notifies Blockchain Workbench a Before exiting the contract constructor

contract has been created
ContractUpdated() Notifies Blockchain Workbench a Before exiting a contract function

contract state has been updated
Configuration and smart contract code relationship

Blockchain Workbench uses the configuration file and smart contract code file to create a blockchain application.
There is a relationship between what is defined in the configuration and the code in the smart contract. Contract
details, functions, parameters, and types are required to match to create the application. Blockchain Workbench
verifies the files prior to application creation.
Contract
For Blockchain Workbench, contracts need to inherit from the WorkbenchBase base class. When declaring the
contract, you need to pass the application name and the workflow name as arguments.
Add the contract header to your HelloBlockchain.sol smart contract code file.
contract HelloBlockchain is WorkbenchBase('HelloBlockchain', 'HelloBlockchain') {
Your contract needs to inherit from the WorkbenchBase base class and pass in the parameters
ApplicationName and the workflow Name as defined in the configuration file. In this case, the application name
and workflow name are the same.
State variables
State variables store values of the state for each contract instance. The state variables in your contract must match
the workflow properties defined in the configuration file.
Add the state variables to your contract in your HelloBlockchain.sol smart contract code file.
//Set of States
enum StateType { Request, Respond}
//List of properties
StateType public State;
address public Requestor;
address public Responder;
string public RequestMessage;

string public ResponseMessage;
Constructor
The constructor defines input parameters for a new smart contract instance of a workflow. The constructor is
declared as a function with the same name as the contract. Required parameters for the constructor are defined as
constructor parameters in the configuration file. The number, order, and type of parameters must match in both
files.
In the constructor function, write any business logic you want to perform prior to creating the contract. For
example, initialize the state variables with starting values.
Before exiting the constructor function, call the ContractCreated() function. This function notifies Blockchain
Workbench a contract has been created.
Add the constructor function to your contract in your HelloBlockchain.sol smart contract code file.
// constructor function
function HelloBlockchain(string message) public
{
Requestor = msg.sender;
RequestMessage = message;
State = StateType.Request;
// call ContractCreated() to create an instance of this workflow

ContractCreated();
}
Functions
Functions are the executable units of business logic within a contract. Required parameters for the function are
defined as function parameters in the configuration file. The number, order, and type of parameters must match in
both files. Functions are associated to transitions in a Blockchain Workbench workflow in the configuration file. A
transition is an action performed to move to the next stage of an application's workflow as determined by the
contract.
Write any business logic you want to perform in the function. For example, modifying a state variable's value.
Before exiting the function, call the ContractUpdated() function. The function notifies Blockchain Workbench
contract state has been updated. If you want to undo state changes made in the function, call revert(). Revert
discards state changes made since the last call to ContractUpdated().
1. Add the following functions to your contract in your HelloBlockchain.sol smart contract code file.
// call this function to send a request
function SendRequest(string requestMessage) public
{
if (Requestor != msg.sender)
{
revert();
}
RequestMessage = requestMessage;
State = StateType.Request;
// call ContractUpdated() to record this action

ContractUpdated('SendRequest');
}
// call this function to send a response

function SendResponse(string responseMessage) public
{
Responder = msg.sender;
// call ContractUpdated() to record this action

ResponseMessage = responseMessage;
State = StateType.Respond;
ContractUpdated('SendResponse');
}
}
2. Save your HelloBlockchain.sol smart contract code file.
Add blockchain application to Blockchain Workbench

To add a blockchain application to Blockchain Workbench, you upload the configuration and smart contract files to
define the application.
1. In a web browser, navigate to the Blockchain Workbench web address. For example,
https://{workbench URL}.azurewebsites.net/ The web application is created when you deploy Blockchain
Workbench. For information on how to find your Blockchain Workbench web address, see Blockchain
Workbench Web URL
2. Sign in as a Blockchain Workbench administrator.
3. Select Applications > New. The New application pane is displayed.
4. Select Upload the contract configuration > Browse to locate the HelloBlockchain.json configuration file
you created. The configuration file is automatically validated. Select the Show link to display validation errors.
Fix validation errors before you deploy the application.
5. Select Upload the contract code > Browse to locate the HelloBlockchain.sol smart contract code file. The
code file is automatically validated. Select the Show link to display validation errors. Fix validation errors before
you deploy the application.
6. Select Deploy to create the blockchain application based on the configuration and smart contract files.
Deployment of the blockchain application takes a few minutes. When deployment is finished, the new application
is displayed in Applications.
NOTE
You can also create blockchain applications by using the Azure Blockchain Workbench REST API.
Add blockchain application members

Add application members to your application to initiate and take actions on contracts. To add application members,
you need to be a Blockchain Workbench administrator.
1. Select Applications > Hello, Blockchain!.
2. The number of members associated to the application is displayed in the upper right corner of the page. For a
new application, the number of members will be zero.
3. Select the members link in the upper right corner of the page. A current list of members for the application is
displayed.
4. In the membership list, select Add members.
5. Select or enter the member's name you want to add. Only Azure AD users that exist in the Blockchain
Workbench tenant are listed. If the user is not found, you need to add Azure AD users.
6. Select the Role for the member. For the first member, selectRequestor as the role.
7. Select Add to add the member with the associated role to the application.
8. Add another member to the application with the Responder role.
For more information about managing users in Blockchain Workbench, see managing users in Azure Blockchain
Workbench
Next steps
In this how -to article, you've created a basic request and response application. To learn how to use the application,
continue to the next how -to article.
Using a blockchain application
Manage Users in Azure Blockchain Workbench
Azure Blockchain Workbench includes user management for people and organizations that are part of your
consortium.
Prerequisites
A Blockchain Workbench deployment is required. See Azure Blockchain Workbench deployment for details on
deployment.
Add Azure AD users

The Azure Blockchain Workbench uses Azure Active Directory (Azure AD ) for authentication, access control, and
roles. Users in the Blockchain Workbench Azure AD tenant can authenticate and use Blockchain Workbench. Add
users to the Administrator application role to interact and perform actions.
Blockchain Workbench users need to exist in the Azure AD tenant before you can assign them to applications and
roles. To add users to Azure AD, use the following steps:
2. Select your account in the top right corner, and switch to the Azure AD tenant associated to Blockchain
Workbench.
3. Select Azure Active Directory > Users. You see a list of users in your directory.
4. To add users to the directory, select New user. For external users, select New guest user.
5. Complete the required fields for the new user. Select Create.
Visit Azure AD documentation for more details on how to manage users within Azure AD.
Manage Blockchain Workbench administrators

Once users have been added to the directory, the next step is to choose which users are Blockchain Workbench
administrators. Users in the Administrator group are associated with the Administrator application role in
Blockchain Workbench. Administrators can add or remove users, assign users to specific scenarios, and create new
applications.
To add users to the Administrator group in the Azure AD directory:
2. Verify you are in the Azure AD tenant associated to Blockchain Workbench by selecting your account in the top
right corner.
3. Select Azure Active Directory > Enterprise applications.
4. Select the Azure AD client application for Blockchain Workbench
5. Select Users and groups > Add user.

6. In Add Assignment, select Users. Choose or search for the user you want to add as an administrator. Click
Select when finished choosing.
7. Verify Role is set to Administrator

8. Select Assign. The added users are displayed in the list with the administrator role assigned.
Managing Blockchain Workbench members
Use the Blockchain Workbench application to manage users and organizations that are part of your consortium.
You can add or remove users to applications and roles.
1. Open the Blockchain Workbench in your browser and sign in as an administrator.
Members are added to each application. Members can have one or more application roles to initiate
contracts or take actions.
2. To manage members for an application, select an application tile in the Applications pane.
The number of members associated to the selected application is reflected in the members tile.
Add member to application

1. Select the member tile to display a list of the current members.
2. Select Add members.
3. Search for the user's name. Only Azure AD users that exist in the Blockchain Workbench tenant are listed. If
the user is not found, you need to Add Azure AD users.
4. Select a Role from the drop-down.
5. Select Add to add the member with the associated role to the application.
Remove member from application
2. For the user you want to remove, choose Remove from the role drop-down.
Change or add role
2. For the user you want to change, click the drop-down and select the new role.
Next steps
In this how -to article, you have learned how to manage users for Azure Blockchain Workbench. To learn how to
create a blockchain application, continue to the next how -to article.
Create a blockchain application in Azure Blockchain Workbench
Using applications in Azure Blockchain Workbench
You can use Blockchain Workbench to create and take actions on contracts. You can also view contract details such
as status and transaction history.
Prerequisites
A Blockchain Workbench deployment. For more information, see Azure Blockchain Workbench deployment for
details on deployment
A deployed blockchain application in Blockchain Workbench. See Create a blockchain application in Azure
Blockchain Workbench
Open the Blockchain Workbench in your browser.
You need to sign in as a member of the Blockchain Workbench. If there are no applications listed, you are a
member of Blockchain Workbench but not a member of any applications. The Blockchain Workbench
administrator can assign members to applications.
Create new contract

To create a new contract, you need to be a member specified as an contract initiator. For information defining
application roles and initiators for the contract, see workflows in the configuration overview. For information on
assigning members to application roles, see add a member to application.
1. In Blockchain Workbench application section, select the application tile that contains the contract you want
to create. A list of active contracts are displayed.
2. To create a new contract, select New contract.
3. The New contract pane is displayed. Specify the initial parameters values. Select Create.
The newly created contract is displayed in the list with the other active contracts.
Take action on contract

Depending on the state the contract is in, members can take actions to transition to the next state of the contract.
Actions are defined as transitions within a state. Members belonging to an allowed application or instance role for
the transition can take the action.
1. In Blockchain Workbench application section, select the application tile that contains the contract to take the
action.
2. Select the contract in the list. Details about the contract are displayed in different sections.
SECTION DESCRIPTION
Status Lists the current progress within the contract stages
Details The current values of the contract
Action Details about the last action
Activity Transaction history of the contract
3. In the Action section, select Take action.

4. The details about the current state of the contract are displayed in a pane. Choose the action you want to
take in the drop-down.
5. Select Take action to initiate the action.
6. If parameters are required for the action, specify the values for the action.
7. Select Take action to execute the action.
Next steps
How to troubleshoot Azure Blockchain Workbench
Using the Azure Blockchain Workbench REST API
Azure Blockchain Workbench REST API provides developers and information workers a way to build rich
integrations to blockchain applications. This document walks you through several key methods of the Workbench
REST API. Consider a scenario where a developer wants to create a custom blockchain client, which allows signed
in users to view and interact with their assigned blockchain applications. The client allows users to view contract
instances and take actions on smart contracts. The client uses the Workbench REST API in the context of the
signed-in user to do the following:
List applications
List workflows for an application
List smart contract instances for a workflow
List available actions for a contract
Execute an action for a contract
The example blockchain applications used in the scenarios, can be downloaded from GitHub.
List applications
Once a user has signed into the blockchain client, the first task is to retrieve all Blockchain Workbench applications
for the user. In this scenario, the user has access to two applications:
1. Asset transfer
2. Refrigerated transportation
Use the Applications GET API:
GET /api/v1/applications
Authorization : Bearer {access token}
The response lists all blockchain applications to which a user has access in Blockchain Workbench. Blockchain
Workbench administrators get all blockchain applications, while non-Workbench administrators get all blockchains
for which they have at least one associated application role or an associated smart contract instance role.
HTTP/1.1 200 OK
Content-type: application/json
{
"nextLink": "/api/v1/applications?skip=2",
"applications": [
{
"id": 1,
"name": "AssetTransfer",
"description": "Allows transfer of assets between a buyer and a seller, with appraisal/inspection
functionality",
"displayName": "Asset Transfer",
"createdByUserId": 1,
"createdDtTm": "2018-04-28T05:59:14.4733333",
"enabled": true,
"applicationRoles": null
},
{
"id": 2,
"name": "RefrigeratedTransportation",
"description": "Application to track end-to-end transportation of perishable goods.",
"displayName": "Refrigerated Transportation",
"createdByUserId": 7,
"createdDtTm": "2018-04-28T18:25:38.71",
"enabled": true,
"applicationRoles": null
}
]
}
List workflows for an application

Once a user selects the applicable blockchain application, in this case, Asset Transfer, the blockchain client
retrieves all workflows of the specific blockchain application. Users can then select the applicable workflow before
being shown all smart contract instances for the workflow. Each blockchain application has one or more workflows
and each workflow has zero or smart contract instances. When building blockchain client applications, it is
recommended to skip the user experience flow allowing users to select the appropriate workflow when there is
only one workflow for the blockchain application. In this case, Asset Transfer has only one workflow, also called
Asset Transfer.
Use the Applications Workflows GET API:
GET /api/v1/applications/{applicationId}/workflows
Authorization: Bearer {access token}
Response lists all workflows of the specified blockchain application to which a user has access in Blockchain
Workbench. Blockchain Workbench administrators get all blockchain workflows, while non-Workbench
administrators get all workflows for which they have at least one associated application role or is associated with a
smart contract instance role.
HTTP/1.1 200 OK
{
"nextLink": "/api/v1/applications/1/workflows?skip=1",
"workflows": [
{
"id": 1,
"name": "AssetTransfer",
"description": "Handles the business logic for the asset transfer scenario",
"displayName": "Asset Transfer",
"applicationId": 1,
"constructorId": 1,
"startStateId": 1
}
]
}
List smart contract instances for a workflow

Once a user selects the applicable workflow, this case Asset Transfer, the blockchain client will retrieve all smart
contract instances for the specified workflow. You can use this information to show all smart contract instances for
the workflow and allow users to deep dive into any of the shown smart contract instances. In this example, consider
a user would like to interact with one of the smart contract instances to take action.
Use the Contracts GET API:
GET api/v1/contracts?workflowId={workflowId}
Response lists all smart contract instances of the specified workflow. Workbench administrators get all smart
contract instances, while non-Workbench administrators get all smart contract instances for which they have at
least one associated application role or is associated with a smart contract instance role.
HTTP/1.1 200 OK
{
"nextLink": "/api/v1/contracts?skip=3&workflowId=1",
"contracts": [
{
"id": 1,
"provisioningStatus": 2,
"connectionID": 1,
"ledgerIdentifier": "0xbcb6127be062acd37818af290c0e43479a153a1c",
"deployedByUserId": 1,
"workflowId": 1,
"contractCodeId": 1,
"contractProperties": [
{
"workflowPropertyId": 1,
"value": "0"
},
{
"value": "My first car"
},
{
"value": "54321"
},
{
"value": "0"
"value": "0"
},
{
"value": "0x0000000000000000000000000000000000000000"
},
{
"value": "0x0000000000000000000000000000000000000000"
},
{
"value": "0x0000000000000000000000000000000000000000"
},
{
"value": "0xd882530eb3d6395e697508287900c7679dbe02d7"
}
],
"transactions": [
{
"id": 1,
"connectionId": 1,
"transactionHash": "0xf3abb829884dc396e03ae9e115a770b230fcf41bb03d39457201449e077080f4",
"blockID": 241,
"from": "0xd882530eb3d6395e697508287900c7679dbe02d7",
"to": null,
"value": 0,
"isAppBuilderTx": true
}
],
"contractActions": [
{
"id": 1,
"userId": 1,
"provisioningStatus": 2,
"timestamp": "2018-04-29T23:41:14.9333333",
"parameters": [
{
"name": "Description",
"value": "My first car"
},
{
"name": "Price",
"value": "54321"
}
],
"workflowFunctionId": 1,
"transactionId": 1,
"workflowStateId": 1
}
]
}
]
}
List available actions for a contract

Once a user has decided to deep dive into one of the contracts, the blockchain client can then show all available
actions to the user given the state of the contract. In this example, the user is looking at all available actions for a
new smart contract they created:
Modify: Allows the user to modify the description and price of an asset.
Terminate: Allows the user to terminate the contract of the asset.
Use the Contract Action GET API:
GET /api/v1/contracts/{contractId}/actions
Response lists all actions to which a user can take given the current state of the specified smart contract instance.
Users get all applicable actions if the user has an associated application role or is associated with a smart contract
instance role for the current state of the specified smart contract instance.
HTTP/1.1 200 OK
{
"nextLink": "/api/v1/contracts/1/actions?skip=2",
"workflowFunctions": [
{
"id": 2,
"name": "Modify",
"description": "Modify the description/price attributes of this asset transfer instance",
"displayName": "Modify",
"parameters": [
{
"id": 1,
"name": "description",
"description": "The new description of the asset",
"displayName": "Description",
"type": {
"id": 2,
"name": "string",
"elementType": null,
"elementTypeId": 0
}
},
{
"id": 2,
"name": "price",
"description": "The new price of the asset",
"displayName": "Price",
"type": {
"id": 3,
"name": "money",
"elementType": null,
"elementTypeId": 0
}
}
],
"workflowId": 1
},
{
"id": 3,
"name": "Terminate",
"description": "Used to cancel this particular instance of asset transfer",
"displayName": "Terminate",
"parameters": [],
"workflowId": 1
}
]
}
Execute an action for a contract

A user can then decide to take action for the specified smart contract instance. In this case, consider the scenario
where a user would like to modify the description and price of an asset to the following:
Description: "My updated car"
Price: 54321
Use the Contract Action POST API:
POST /api/v1/contracts/{contractId}/actions
actionInformation: {
"workflowFunctionId": 2,
"workflowActionParameters": [
{
"name": "description",
"value": "My updated car"
},
{
"name": "price",
"value": "54321"
}
]
}
Users are only able to execute the action given the current state of the specified smart contract instance and the
user's associated application role or smart contract instance role. If the post is successful, an HTTP 200 OK
response is returned with no response body.
HTTP/1.1 200 OK
Next steps
Azure Blockchain Workbench REST API reference
Azure Blockchain Workbench troubleshooting
A PowerShell script is available to assist with developer debugging or support. The script generates a summary
and collects detailed logs for troubleshooting. Collected logs include:
Blockchain network, such as Ethereum
Blockchain Workbench microservices
Application Insights
Azure Monitoring (Log Analytics)
You can use the information to determine next steps and determine root cause of issues.
Troubleshooting script
The PowerShell troubleshooting script is available on GitHub. Download a zip file or clone the sample from
GitHub.
git clone https://github.com/Azure-Samples/blockchain.git
Run the script

If needed, install the Azure PowerShell module using the instructions found in the Azure PowerShell guide, and
then run Connect-AzureRmAccount to create a connection with Azure. Also, you need to have an SSH public key
named id_rsa.pub in the .ssh directory of your user profile.
Run the collectBlockchainWorkbenchTroubleshooting.ps1 script to collect logs and create a ZIP file containing a
folder of troubleshooting information. For example:
collectBlockchainWorkbenchTroubleshooting.ps1 -SubscriptionID "<subscription_id>" -ResourceGroupName

"workbench-resource-group-name"
The script accepts the following parameters:
PARAMETER DESCRIPTION REQUIRED
SubscriptionID SubscriptionID to create or locate all Yes

resources.
ResourceGroupName Name of the Azure Resource Group Yes

where Blockchain Workbench has been
deployed.
OutputDirectory Path to create the output .ZIP file. If not No

specified, defaults to the current
directory.
LookbackHours Number of hours to use when pulling No

telemetry. Default value is 24 hours.
Maximum value is 90 hours
PARAMETER DESCRIPTION REQUIRED
OmsSubscriptionId The subscription ID where Log Analytics No

is deployed. Only pass this parameter if
the Log Analytics for the blockchain
network is deployed outside of
Blockchain Workbench's resource
group.
OmsResourceGroup The resource group where Log Analytics No

is deployed. Only pass this parameter if
the Log Analytics for the blockchain
network is deployed outside of
Blockchain Workbench's resource
group.
OmsWorkspaceName The Log Analytics workspace name. No

Only pass this parameter if the Log
Analytics for the blockchain network is
deployed outside of Blockchain
Workbench's resource group
What is collected?
The output ZIP file contains the following folder structure:
FOLDER OR FILE DESCRIPTION
\Summary.txt Summary of the system
\Metrics\blockchain Metrics about the blockchain
\Metrics\Workbench Metrics about the workbench
\Details\Blockchain Detailed logs about the blockchain
\Details\Workbench Detailed logs about the workbench
The summary file gives you a snapshot of the overall state of the application and health of the application. The
summary provides recommended actions, highlights top errors, and metadata about running services.
The Metrics folder contains metrics of various system components over time. For example, the output file
\Details\Workbench\apiMetrics.txt contains a summary of different response codes, and response times
throughout the collection period. The Details folder contains detailed logs for troubleshooting specific issues with
Workbench or the underlying blockchain network. For example, \Details\Workbench\Exceptions.csv contains a list
of the most recent exceptions that have occurred in the system, which is useful for troubleshooting errors with
smart contracts or interactions with the blockchain.
Next steps
Configure the Azure Blockchain Workbench database
firewall
This article shows how to configure a firewall rule using the Azure portal. Firewall rules let external clients or
applications connect to your Azure Blockchain Workbench database.
Connect to the Blockchain Workbench database

To connect to the database where you want to configure a rule:
1. Sign in to the Azure Portal with an account that has Owner permissions for the Azure Blockchain Workbench
resources.
2. In the left navigation pane, choose Resource groups.
3. Choose the name of the resource group for your Blockchain Workbench deployment.
4. Select Type to sort the list of resources, and then choose your SQL server.
5. The resource list example in the following screen capture shows two databases: master and lsgn-sdk. You
configure the firewall rule on lsgn-sdk.
Create a database firewall rule

To create a firewall rule:
1. Choose the link to the "lsgn-sdk" database.
2. On the menu bar, select Set server firewall.
3. To create a rule for your organization:

Enter a RULE NAME
Enter an IP address for the START IP of the address range
Enter an IP address for the END IP of the address range
NOTE
If you only want to add the IP address of your computer, choose + Add client IP.
4. To save your firewall configuration, select Save.

5. Test the IP address range you configured for the database by connecting from an application or tool. For
example, SQL Server Management Studio.
Next steps
Database views in Azure Blockchain Workbench
Get information about your Azure Blockchain
Workbench database
This article shows how to get detailed information about your Azure Blockchain Workbench database.
Overview
Information about applications, workflows, and smart contract execution is provided using database views in the
Blockchain Workbench SQL DB. Developers can use this information when using tools such as Microsoft Excel,
PowerBI, Visual Studio, and SQL Server Management Studio.
Before a developer can connect to the database, they need:
External client access allowed in the database firewall. This article about configuring a database firewall article
explains how to allow access.
The database server name and database name.

To connect to the database:
1. Sign in to the Azure Portal with an account that has Owner permissions for the Azure Blockchain Workbench
resources.
2. In the left navigation pane, choose Resource groups.
3. Choose the name of the resource group for your Blockchain Workbench deployment.
4. Select Type to sort the resource list, and then choose your SQL server. The sorted list in the next screen
capture shows two SQL databases, "master" and one that uses "lhgn" as the Resource prefix.
5. To see detailed information about the Blockchain Workbench database, select the link for the database with
the Resource prefix you provided for deploying Blockchain Workbench.
The database server name and database name let you connect to the Blockchain Workbench database using your
development or reporting tool.
Next steps
View Azure Blockchain Workbench data with
Microsoft Excel
You can use Microsoft Excel to view data in Azure Blockchain Workbench's SQL DB. This article provides the steps
you need to:
Connect to the Blockchain Workbench database from Microsoft Excel
Look at Blockchain Workbench database tables and views
Load Blockchain Workbench view data into Excel

To connect to a Blockchain Workbench database:
1. Open Microsoft Excel.
2. On the Data tab, choose Get Data.
3. Select From Azure and then select From Azure SQL Database.
4. In the SQL Server database dialog box:

For Server, enter the name of the Blockchain Workbench server.
For Database (optional), enter the name of the database.
5. In the SQL Server database dialog navigation bar, select Database. Enter your Username and Password,
and then select Connect.
NOTE
If you're using the credentials created during the Azure Blockchain Workbench deployment process, the User name is
dbadmin . The Password is the one you created when you deployed the Blockchain Workbench.
Look at database tables and views

The Excel Navigator dialog opens after you connect to the database. You can use the Navigator to look at the tables
and views in the database. The views are designed for reporting and their names are prefixed with vw.
Load view data into an Excel workbook
The next example shows how you can load data from a view into an Excel workbook.
1. In the Navigator scroll bar, select the vwContractAction view. The vwContractAction preview shows all the
actions related to a contract in the Blockchain Workbench database.
2. Select Load to retrieve all the data in the view and put it in your Excel workbook.
Now that you have the data loaded, you can use Excel features to create your own reports using the metadata and
transaction data from the Azure Blockchain Workbench database.
Next steps
Using Azure Blockchain Workbench data with
Microsoft Power BI
Microsoft Power BI provides the ability to easily generate powerful reports from SQL DB databases using Power
BI Desktop and then publish them to https://www.powerbi.com.
This article contains a step by step walkthrough of how to connect to Azure Blockchain Workbench's SQL
Database from within PowerBI desktop, create a report, and deploy the report to powerbi.com.
Prerequisites
Download PowerBI Desktop.
Connecting PowerBI to data in Azure Blockchain Workbench

1. Open Power BI Desktop.
2. Select Get Data.
3. Select SQL Server from the list of data source types.

4. Provide the server and database name in the dialog. Specify if you want to import the data or perform a
DirectQuery. Select OK.
5. Provide the database credentials to access Azure Blockchain Workbench. Select Database and enter your
credentials.
If you are using the credentials created by the Azure Blockchain Workbench deployment process, the
username is dbadmin and the password is the one you provided during deployment.
6. Once connected to the database, the Navigator dialog displays the tables and views available within the
database. The views are designed for reporting and are all prefixed vw.
7. Select the views you wish to include. For demonstration purposes, we include vwContractAction, which
provides details on all of the actions that have taken place on a contract.
You can now create and publish reports as you normally would with Power BI.
Next steps
Using Azure Blockchain Workbench data with SQL
Server Management Studio
Microsoft SQL Server Management Studio provides the ability to rapidly write and test queries against Azure
Blockhain Workbench's SQL DB. This section contains a step by step walkthrough of how to connect to Azure
Blockchain Workbench's SQL Database from within SQL Server Management Studio.
Prerequisites
Download SQL Server Management Studio.
Connecting SQL Server Management Studio to data in Azure

1. Open the SQL Server Management Studio and select Connect.
2. Select Database Engine.
3. In the Connect to Server dialog, enter the server name and your database credentials.
If you are using the credentials created by the Azure Blockchain Workbench deployment process, the
username will be dbadmin and the password will be the one you provided during deployment.
a. SQL Server Management Studio displays the list of databases, database views, and stored
procedures in the Azure Blockchain Workbench database.
4. To view the data associated with any of the database views, you can automatically generate a select
statement using the following steps.
5. Right click on any of the database views in the Object Explorer.
6. Select Script View as.
7. Choose SELECT to.
8. Select New Query Editor Window.
9. A new query can be created by selecting New Query.
Next steps
Azure Blockchain Workbench configuration reference
Azure Blockchain Workbench applications are multi-party workflows defined by configuration metadata and smart
contract code. Configuration metadata defines the high-level workflows and interaction model of the blockchain
application. Smart contracts define the business logic of the blockchain application. Workbench uses configuration
and smart contract code to generate blockchain application user experiences.
Configuration metadata specifies the following information for each blockchain application:
Name and description of the blockchain application
Unique roles for users who can act or participate within the blockchain application
One or more workflows. Each workflow acts as a state machine to control the flow of the business logic.
Workflows can be independent or interact with one another.
Each defined workflow specifies the following:
Name and description of the workflow
States of the workflow. Each state is a stage in the business logic's control flow.
Actions to transition to the next state
User roles permitted to initiate each action
Smart contracts that represent business logic in code files
Application
A blockchain application contains configuration metadata, workflows, and user roles who can act or participate
within the application.
FIELD DESCRIPTION REQUIRED
ApplicationName Unique application name. The Yes

corresponding smart contract must use
the same ApplicationName for the
applicable contract class.
DisplayName Friendly display name of the application. Yes
Description Description of the application. No
ApplicationRoles Collection of ApplicationRoles. User Yes

roles who can act or participate within
the application.
Workflows Collection of Workflows. Each workflow Yes

acts as a state machine to control the
flow of the business logic.
For an example, see configuration file example.
Workflows
An application's business logic may be modeled as a state machine where taking an action causes the flow of the
business logic to move from one state to another. A workflow is a collection of such states and actions. Each
workflow consists of one or more smart contracts, which represent the business logic in code files. An executable
contract is an instance of a workflow.
Name Unique workflow name. The Yes

the same Name for the applicable
contract class.
DisplayName Friendly display name of the workflow. Yes
Description Description of the workflow. No
Initiators Collection of ApplicationRoles. Roles Yes

that are assigned to users who are
authorized to create contracts in the
workflow.
StartState Name of the initial state of the Yes

workflow.
Properties Collection of identifiers. Represents data Yes

that can be read off-chain or visualized
in a user experience tool.
Constructor Defines input parameters for creating Yes

an instance of the workflow.
Functions A collection of functions that can be Yes

executed in the workflow.
States A collection of workflow states. Yes
For an example, see configuration file example.
Type
Supported data types.
TYPE DESCRIPTION
address Blockchain address type, such as contracts or users.
array Single level array of type integer, bool, money, or time. Arrays
can be static or dynamic. Use ElementType to specify the
datatype of the elements within the array. See example
configuration.
bool Boolean data type.
contract Address of type contract.

TYPE DESCRIPTION
enum Enumerated set of named values. When using the enum type,
you also specify a list of EnumValues. Each value is limited to
255 characters. Valid value characters include upper and lower
case letters (A-Z, a-z) and numbers (0-9). See example
configuration and use in Solidity.
int Integer data type.
money Money data type.
state Workflow state.
string String data type. 4000 character maximum. See example

configuration.
user Address of type user.
time Time data type.
[ Application Role Name ] Any name specified in application role. Limits users to be of
that role type.
Example configuration of type array
{
"Name": "Quotes",
"Description": "Market quotes",
"DisplayName": "Quotes",
"Type": {
"Name": "array",
"ElementType": {
"Name": "int"
}
}
}
Using a property of type array

If you define a property as type array in configuration, you need to include an explicit get function to return the
public property of the array type in Solidity. For example:
function GetQuotes() public constant returns (int[]) {

return Quotes;
}
Example configuration of type string
{
"Name": "description",
"Description": "Descriptive text",
"DisplayName": "Description",
"Type": {
"Name": "string"
}
}
Example configuration of type enum
{
"Name": "PropertyType",
"DisplayName": "Property Type",
"Description": "The type of the property",
"Type": {
"Name": "enum",
"EnumValues": ["House", "Townhouse", "Condo", "Land"]
}
}
Using enumeration type in Solidity

Once an enum is defined in configuration, you can use enumeration types in Solidity. For example, you can define
an enum called PropertyTypeEnum.
enum PropertyTypeEnum {House, Townhouse, Condo, Land} PropertyTypeEnum public PropertyType;
The list of strings need to match between the configuration and smart contract to be valid and consistent
declarations in Blockchain Workbench.
Assignment example:
PropertyType = PropertyTypeEnum.Townhouse;
Function parameter example:
function AssetTransfer(string description, uint256 price, PropertyTypeEnum propertyType) public

{
InstanceOwner = msg.sender;
AskingPrice = price;
Description = description;
PropertyType = propertyType;
State = StateType.Active;
ContractCreated();
}
Constructor
Defines input parameters for an instance of a workflow.
Parameters Collection of identifiers required to Yes

initiate a smart contract.
Constructor example
{
"Parameters": [
{
"Description": "The description of this asset",
"Type": {
"Name": "string"
}
},
{
"Name": "price",
"Description": "The price of this asset",
"DisplayName": "Price",
"Type": {
"Name": "money"
}
}
]
}
Functions
Defines functions that can be executed on the workflow.
Name The unique name of the function. The Yes

function.
DisplayName Friendly display name of the function. Yes
Description Description of the function No
Parameters Collection of identifiers corresponding Yes

to the parameters of the function.
Functions example
"Functions": [
{
"Name": "Modify",
"DisplayName": "Modify",
"Description": "Modify the description/price attributes of this asset transfer instance",
"Parameters": [
{
"Description": "The new description of the asset",
"Type": {
"Name": "string"
}
},
{
"Name": "price",
"Description": "The new price of the asset",
"Type": {
"Name": "money"
}
}
]
},
{
"Name": "Terminate",
"DisplayName": "Terminate",
"Description": "Used to cancel this particular instance of asset transfer",
"Parameters": []
}
]
States
A collection of unique states within a workflow. Each state captures a step in the business logic's control flow.
Name Unique name of the state. The Yes

state.
DisplayName Friendly display name of the state. Yes
Description Description of the state. No
PercentComplete An integer value displayed in the Yes

Blockchain Workbench user interface to
show the progress within the business
logic control flow.
Style Visual hint indicating whether the state Yes

represents a success or failure state.
There are two valid values: Success or
Failure .
Transitions Collection of available transitions from No

the current state to the next set of
states.
States example
"States": [
{
"Name": "Active",
"DisplayName": "Active",
"Description": "The initial state of the asset transfer workflow",
"Style": "Success",
"Transitions": [
{
"AllowedRoles": [],
"AllowedInstanceRoles": [ "InstanceOwner" ],
"Description": "Cancels this instance of asset transfer",
"Function": "Terminate",
"NextStates": [ "Terminated" ],
"DisplayName": "Terminate Offer"
},
{
"AllowedRoles": [ "Buyer" ],
"Description": "Make an offer for this asset",
"Function": "MakeOffer",
"NextStates": [ "OfferPlaced" ],
"DisplayName": "Make Offer"
},
{
"AllowedRoles": [],
"Description": "Modify attributes of this asset transfer instance",
"Function": "Modify",
"NextStates": [ "Active" ],
"DisplayName": "Modify"
}
]
},
{
"Name": "Accepted",
"DisplayName": "Accepted",
"Description": "Asset transfer process is complete",
"Style": "Success",
"Transitions": []
},
{
"Name": "Terminated",
"DisplayName": "Terminated",
"Description": "Asset transfer has been cancelled",
"Style": "Failure",
"Transitions": []
}
]
Transitions
Available actions to the next state. One or more user roles may perform an action at each state, where an action
may transition a state to another state in the workflow.

AllowedRoles List of applications roles allowed to No

initiate the transition. All users of the
specified role may be able to perform
the action.
AllowedInstanceRoles List of user roles participating or No

specified in the smart contract allowed
to initiate the transition. Instance roles
are defined in Properties within
workflows. AllowedInstanceRoles
represent a user participating in an
instance of a smart contract.
AllowedInstanceRoles give you the
ability to restrict taking an action to a
user role in a contract instance. For
example, you may only want to allow
the user who created the contract
(InstanceOwner) to be able to terminate
rather than all users in role type
(Owner) if you specified the role in
AllowedRoles.
DisplayName Friendly display name of the transition. Yes
Description Description of the transition. No
Function The name of the function to initiate the Yes

transition.
NextStates A collection of potential next states Yes

after a successful transition.
Transitions example
"Transitions": [
{
"AllowedRoles": [],
},
{
},
{
"AllowedRoles": [],
}
]
Application roles
Application roles define a set of roles that can be assigned to users who want to act or participate within the
application. Application roles can be used to restrict actions and participation within the blockchain application and
corresponding workflows.
Name The unique name of the application Yes

role. The corresponding smart contract
must use the same Name for the
applicable role. Base type names are
reserved. You cannot name an
application role with the same name as
Type
Description Description of the application role. No
Application roles example
{
"Name": "Appraiser",
"Description": "User that signs off on the asset price"
},
{
"Name": "Buyer",
"Description": "User that places an offer on an asset"
}
]
Identifiers
Identifiers represent a collection of information used to describe workflow properties, constructor, and function
parameters.
Name The unique name of the property or Yes

parameter. The corresponding smart
contract must use the same Name for
the applicable property or parameter.
DisplayName Friendly display name for the property Yes

or parameter.
Description Description of the property or No

parameter.
Identifiers example
"Properties": [
{
"Name": "State",
"Description": "Holds the state of the contract",
"Type": {
"Name": "state"
}
},
{
"Name": "Description",
"Description": "Describes the asset being sold",
"Type": {
"Name": "string"
}
}
]
Configuration file example

Asset transfer is a smart contract scenario for buying and selling high value assets, which require an inspector and
appraiser. Sellers can list their assets by instantiating an asset transfer smart contract. Buyers can make offers by
taking an action on the smart contract, and other parties can take actions to inspect or appraise the asset. Once the
asset is marked both inspected and appraised, the buyer and seller will confirm the sale again before the contract is
set to complete. At each point in the process, all participants have visibility into the state of the contract as it is
updated.
For more information including the code files, see asset transfer sample for Azure Blockchain Workbench
The following configuration file is for the asset transfer sample:
{
"ApplicationName": "AssetTransfer",
"DisplayName": "Asset Transfer",
"Description": "Allows transfer of assets between a buyer and a seller, with appraisal/inspection
functionality",
{
"Name": "Appraiser",
},
{
"Name": "Buyer",
"Description": "User that places an offer on an asset"
},
{
"Name": "Inspector",
"Description": "User that inspects the asset and signs off on inspection"
},
{
"Name": "Owner",
}
],
"Workflows": [
{
"Name": "AssetTransfer",
"DisplayName": "Asset Transfer",
"Description": "Handles the business logic for the asset transfer scenario",
"Initiators": [ "Owner" ],
"StartState": "Active",
"Properties": [
{
"Name": "State",
"Description": "Holds the state of the contract",
"Type": {
"Name": "state"
}
},
{
"Name": "Description",
"Description": "Describes the asset being sold",
"Type": {
"Name": "string"
}
},
{
"Name": "AskingPrice",
"DisplayName": "Asking Price",
"Description": "The asking price for the asset",
"Type": {
"Name": "money"
}
},
{
"Name": "OfferPrice",
"DisplayName": "Offer Price",
"Description": "The price being offered for the asset",
"Type": {
"Name": "money"
}
},
{
"Name": "InstanceAppraiser",
"DisplayName": "Instance Appraiser",
"Description": "The user that appraises the asset",
"Type": {
"Name": "Appraiser"
}
},
{
"Name": "InstanceBuyer",
"DisplayName": "Instance Buyer",
"Description": "The user that places an offer for this asset",
"Type": {
"Name": "Buyer"
}
},
{
"Name": "InstanceInspector",
"DisplayName": "Instance Inspector",
"Description": "The user that inspects this asset",
"Type": {
"Name": "Inspector"
}
},
{
"Name": "InstanceOwner",
"DisplayName": "Instance Owner",
"Description": "The seller of this particular asset",
"Type": {
"Name": "Owner"
}
}
],
"Constructor": {
"Parameters": [
{
"Description": "The description of this asset",
"Type": {
"Name": "string"
}
},
{
"Name": "price",
"Description": "The price of this asset",
"Type": {
"Name": "money"
}
}
]
},
"Functions": [
{
"Name": "Modify",
"DisplayName": "Modify",
"Description": "Modify the description/price attributes of this asset transfer instance",
"Parameters": [
{
"Description": "The new description of the asset",
"Type": {
"Name": "string"
}
},
{
"Name": "price",
"Description": "The new price of the asset",
"Type": {
"Name": "money"
}
}
]
},
{
"Name": "Terminate",
"DisplayName": "Terminate",
"Description": "Used to cancel this particular instance of asset transfer",
"Parameters": []
},
{
"Name": "MakeOffer",
"Name": "MakeOffer",
"DisplayName": "Make Offer",
"Description": "Place an offer for this asset",
"Parameters": [
{
"Name": "inspector",
"Description": "Specify a user to inspect this asset",
"DisplayName": "Inspector",
"Type": {
"Name": "Inspector"
}
},
{
"Name": "appraiser",
"Description": "Specify a user to appraise this asset",
"DisplayName": "Appraiser",
"Type": {
"Name": "Appraiser"
}
},
{
"Name": "offerPrice",
"Description": "Specify your offer price for this asset",
"DisplayName": "Offer Price",
"Type": {
"Name": "money"
}
}
]
},
{
"Name": "Reject",
"DisplayName": "Reject",
"Description": "Reject the user's offer",
"Parameters": []
},
{
"Name": "AcceptOffer",
"DisplayName": "Accept Offer",
"Description": "Accept the user's offer",
"Parameters": []
},
{
"Name": "RescindOffer",
"DisplayName": "Rescind Offer",
"Description": "Rescind your placed offer",
"Parameters": []
},
{
"Name": "ModifyOffer",
"DisplayName": "Modify Offer",
"Description": "Modify the price of your placed offer",
"Parameters": [
{
"Name": "offerPrice",
"Type": {
"Name": "money"
}
}
]
},
{
"Name": "Accept",
"DisplayName": "Accept",
"Description": "Accept the inspection/appraisal results",
"Parameters": []
},
{
"Name": "MarkInspected",
"Name": "MarkInspected",
"DisplayName": "Mark Inspected",
"Description": "Mark the asset as inspected",
"Parameters": []
},
{
"Name": "MarkAppraised",
"DisplayName": "Mark Appraised",
"Description": "Mark the asset as appraised",
"Parameters": []
}
],
"States": [
{
"Name": "Active",
"DisplayName": "Active",
"Description": "The initial state of the asset transfer workflow",
"Style": "Success",
"Transitions": [
{
"AllowedRoles": [],
},
{
},
{
"AllowedRoles": [],
}
]
},
{
"Name": "OfferPlaced",
"DisplayName": "Offer Placed",
"Description": "Offer has been placed for the asset",
"Style": "Success",
"Transitions": [
{
"AllowedRoles": [],
"Description": "Accept the proposed offer for the asset",
"Function": "AcceptOffer",
"NextStates": [ "PendingInspection" ],
"DisplayName": "Accept Offer"
},
{
"AllowedRoles": [],
"Description": "Reject the proposed offer for the asset",
"Function": "Reject",
"DisplayName": "Reject"
},
{
{
"AllowedRoles": [],
"Description": "Cancel this instance of asset transfer",
"DisplayName": "Terminate"
},
{
"AllowedRoles": [],
"AllowedInstanceRoles": [ "InstanceBuyer" ],
"Description": "Rescind the offer you previously placed for this asset",
"Function": "RescindOffer",
"DisplayName": "Rescind Offer"
},
{
"AllowedRoles": [],
"Description": "Modify the price that you specified for your offer",
"Function": "ModifyOffer",
"DisplayName": "Modify Offer"
}
]
},
{
"Name": "PendingInspection",
"DisplayName": "Pending Inspection",
"Description": "Asset is pending inspection",
"Style": "Success",
"Transitions": [
{
"AllowedRoles": [],
"Description": "Reject the offer",
},
{
"AllowedRoles": [],
"Description": "Cancel the offer",
},
{
"AllowedRoles": [],
"Description": "Rescind the offer you placed for this asset",
},
{
"AllowedRoles": [],
"AllowedInstanceRoles": [ "InstanceInspector" ],
"Description": "Mark this asset as inspected",
"Function": "MarkInspected",
"NextStates": [ "Inspected" ],
"DisplayName": "Mark Inspected"
},
{
"AllowedRoles": [],
"AllowedInstanceRoles": [ "InstanceAppraiser" ],
"Description": "Mark this asset as appraised",
"Function": "MarkAppraised",
"NextStates": [ "Appraised" ],
"DisplayName": "Mark Appraised"
}
]
},
{
"Name": "Inspected",
"DisplayName": "Inspected",
"Style": "Success",
"Transitions": [
{
"AllowedRoles": [],
},
{
"AllowedRoles": [],
},
{
"AllowedRoles": [],
},
{
"AllowedRoles": [],
"AllowedInstanceRoles": [ "InstanceAppraiser" ],
"Description": "Mark this asset as appraised",
"NextStates": [ "NotionalAcceptance" ],
"DisplayName": "Mark Appraised"
}
]
},
{
"Name": "Appraised",
"DisplayName": "Appraised",
"Description": "Asset has been appraised, now awaiting inspection",
"Style": "Success",
"Transitions": [
{
"AllowedRoles": [],
},
{
"AllowedRoles": [],
},
{
"AllowedRoles": [],
},
{
"AllowedRoles": [],
"AllowedInstanceRoles": [ "InstanceInspector" ],
"Description": "Mark the asset as inspected",
"Function": "MarkInspected",
"NextStates": [ "NotionalAcceptance" ],
"DisplayName": "Mark Inspected"
}
]
},
{
"Name": "NotionalAcceptance",
"DisplayName": "Notional Acceptance",
"Description": "Asset has been inspected and appraised, awaiting final sign-off from buyer and
seller",
"Style": "Success",
"Transitions": [
{
"AllowedRoles": [],
"Description": "Sign-off on inspection and appraisal",
"Function": "Accept",
"NextStates": [ "SellerAccepted" ],
"DisplayName": "SellerAccept"
},
{
"AllowedRoles": [],
},
{
"AllowedRoles": [],
},
{
"AllowedRoles": [],
"NextStates": [ "BuyerAccepted" ],
"DisplayName": "BuyerAccept"
},
{
"AllowedRoles": [],
}
]
},
{
"Name": "BuyerAccepted",
"DisplayName": "Buyer Accepted",
"Description": "Buyer has signed-off on inspection and appraisal",
"Style": "Success",
"Transitions": [
{
"AllowedRoles": [],
"NextStates": [ "SellerAccepted" ],
"DisplayName": "Accept"
},
{
"AllowedRoles": [],
},
{
"AllowedRoles": [],
}
]
},
{
"Name": "SellerAccepted",
"DisplayName": "Seller Accepted",
"Description": "Seller has signed-off on inspection and appraisal",
"Style": "Success",
"Transitions": [
{
"AllowedRoles": [],
"NextStates": [ "Accepted" ],
"DisplayName": "Accept"
},
{
"AllowedRoles": [],
}
]
},
{
"Name": "Accepted",
"DisplayName": "Accepted",
"Description": "Asset transfer process is complete",
"Style": "Success",
"Transitions": []
},
{
"Name": "Terminated",
"DisplayName": "Terminated",
"Style": "Failure",
"Transitions": []
}
]
}
]
}
Next steps
Azure Blockchain Workbench REST API reference
Azure Blockchain Workbench delivers data from distributed ledgers to an off-chain SQL DB database. This makes
it possible to use SQL and existing tools, such as SQL Server Management Studio, to interact with blockchain
data.
Azure Blockchain Workbench provides a set of database views that provide access to data that will be helpful
when performing your queries. These views are heavily denormalized to make it easy to quickly get started
building reports, analytics, and otherwise consume blockchain data with existing tools and without having to
retrain database staff.
This section includes an overview of the database views and the data they contain.
NOTE
Any direct usage of database tables found in the database outside of these views, while possible, is not supported.
vwApplication
This view provides details on Applications that have been uploaded to Azure Blockchain Workbench.
NAME TYPE CAN BE NULL DESCRIPTION
ApplicationId int No A unique identifier for the

application.
ApplicationName nvarchar(50) No The name of the application.
ApplicationDescription nvarchar(255) Yes A description of the

application
ApplicationDisplayName nvarchar(255) No The name to be displayed in

a user interface.
ApplicationEnabled bit No Identifies if the application is

currently enabled.
Note: Even though an
application can be reflected
as disabled in the database,
associated contracts remain
on the blockchain and data
about those contracts
remain in the database.
UploadedDtTm datetime2(7) No The date and time a contract

was uploaded.
UploadedByUserId int No The ID of the user who

uploaded the application.
UploadedByUserExternalId nvarchar(255) No The external identifier for the

user who uploaded the
application. By default, this is
the ID for the user from the
Azure Active Directory for
the consortium.
UploadedByUserProvisionin int No Identifies the current status

gStatus of provisioning process for
the user. Possible values are
0 – User has been created
by the API
1 – A key has been
associated with the user in
the database
2 – The user is fully
provisioned
UploadedByUserFirstName nvarchar(50) Yes The first name of the user

who uploaded the contract.
UploadedByUserLastName nvarchar(50) Yes The last name of the user

who uploaded the contract.
UploadedByUserEmailAddre nvarchar(255) Yes The email address of the

ss user who uploaded the
contract.
vwApplicationRole
This view provides details on the roles that have been defined in Azure Blockchain Workbench applications.
In an Asset Transfer application, for example, roles such as Buyer and Seller roles may be defined.

application
ApplicationName nvarchar(50) No The name of the application

application

a user interface
RoleId int No A unique identifier for a role

in the application
RoleName nvarchar50) No The name of the role
RoleDescription description(255) Yes A description of the role

vwApplicationRoleUser
This view provides details on the roles that have been defined in Azure Blockchain Workbench applications and
the users associated with them.
In an Asset Transfer application, for example, John Smith may be associated with the Buyer role.

application
ApplicationName nvarchar(50) No The name of the application

application

a user interface
ApplicationRoleId int No A unique identifier for a role

in the application
ApplicationRoleName nvarchar50) No The name of the role
ApplicationRoleDescription nvarchar(255) Yes A description of the role
UserId int No The ID of the user

associated with the role.
UserExternalId nvarchar(255) No The external identifier for the

user who is associated with
the role. By default, this is
the ID for the user from the
Azure Active Directory for
the consortium.
UserProvisioningStatus int No Identifies the current status

of provisioning process for
the user. Possible values are:
by the API
the database
provisioned
UserFirstName nvarchar(50) Yes The first name of the user

who is associated with the
role.
UserLastName nvarchar(255) Yes The last name of the user

role.
UserEmailAddress nvarchar(255) Yes The email address of the

the role.
vwConnectionUser
This view provides details on the connections defined in Azure Blockchain Workbench and the users associated
with them. For each connection, this view contains the following data:
Associated ledger details
Associated user information
ConnectionId int No The unique identifier for a

connection in Azure
ConnectionEndpointUrl nvarchar(50) No The endpoint url for a

connection.
ConnectionFundingAccount nvarchar(255) Yes The funding account

associated with a
connection, if applicable.
LedgerId int No The unique identifier for a

ledger.
LedgerName nvarchar(50) No The name of the ledger.
LedgerDisplayName nvarchar(255) No The name of the ledger to

display in the UI.
UserId int No The ID of the user

associated with the
connection.
UserExternalId nvarchar(255) No The external identifier for the

the connection. By default,
this is the ID for the user
from the Azure Active
Directory for the
consortium.
UserProvisioningStatus int No Identifies the current status

by the API
the database
provisioned
UserFirstName nvarchar(50) Yes The first name of the user

connection.
UserLastName nvarchar(255) Yes The last name of the user

connection.
UserEmailAddress nvarchar(255) Yes The email address of the

the connection.
vwContract
This view provides details about deployed contracts. For each contract, this view contains the following data:
Associated application definition
Associated workflow definition
Associated ledger implementation for the function
Details for the user who initiated the action
Details related to the blockchain block and transaction
ConnectionId int No The unique identifier for a

connection in Azure
ConnectionEndpointUrl nvarchar(50) No The endpoint url for a

connection.
ConnectionFundingAccount nvarchar(255) Yes The funding account

associated with a
connection, if applicable.
LedgerId int No The unique identifier for a

ledger.
LedgerName nvarchar(50) No The name of the ledger.
LedgerDisplayName nvarchar(255) No The name of the ledger to

display in the UI.

application.
ApplicationName nvarchar (50) No The name of the application.
ApplicationDisplayName nvarchar (255) No The name to be displayed in

a user interface.

currently enabled.
WorkflowId int No A unique identifier for the

workflow associated with a
contract.
WorkflowName nvarchar(50) No The name of the workflow

associated with a contract.
WorkflowDisplayName nvarchar(255) No The name of the workflow

associated with the contract
to displayed in the user
interface.
WorkflowDescription nvarchar(255) Yes The description of the

workflow associated with a
contract.
ContractCodeId int No A unique identifier for the

contract code associated
with the contract.
ContractFileName int No The name of the file

containing the smart
contract code for this
workflow.
ContractUploadedDtTm int No The date and time the

contract code was uploaded.
ContractId int No The unique identifier for the

contract.
ContractProvisioningStatus int No The last name of the user

who deployed the contract.
ContractLedgerIdentifier nvarchar (255) The email address of the

user who deployed the
contract.
ContractDeployedByUserId int No An external identifier for the

user who deployed the
contract. By default, this is
the guid representing the
Azure Active Directory ID for
the user.
ContractDeployedByUserExt nvarchar(255) No An external identifier for the

ernalId user that deployed the
contract. By default, this is
the guid representing the
Azure Active Directory ID for
the user.
ContractDeployedByUserPro int No Identifies the current status

visioningStatus of the provisioning process
for the user. Possible values
are:
0 – user has been created by
the API
the database
provisioned
ContractDeployedByUserFirs nvarchar(50) Yes The first name of the user

tName who deployed the contract.
ContractDeployedByUserLas nvarchar(255) Yes The last name of the user

tName who deployed the contract.
ContractDeployedByUserEm nvarchar(255) Yes The email address of the

ailAddress user who deployed the
contract.
vwContractAction
This view represents the majority of information related to actions taken on contracts and is designed to readily
facilitate common reporting scenarios. For each action taken, this view contains the following data:
Associated smart contract function and parameter definition
Associated ledger implementation for the function
Specific instance values provided for parameters
Details for the user who initiated the action
Details related to the blockchain block and transaction

application.

a user interface.
ApplicationEnabled bit No This field identifies if the

application is currently
enabled. Note – Even
though an application can
be reflected as disabled in
the database, associated
contracts remain on the
blockchain and data about
those contracts remain in
the database.
WorkflowId int No A unique identifier for a

workflow.
WorkflowName nvarchar(50) No The name of the workflow.
WorkflowDisplayName nvarchar(255) No The name of the workflow to

display in a user interface.

workflow.
ContractId int No A unique identifier for the

contract.
ContractProvisioningStatus int No Identifies the current status

of the provisioning process
for the contract. Possible
values are:
0 – The contract has been
created by the API in the
database
sent to the ledger
successfully deployed to the
ledger

code implementation of the
contract.
ContractLedgerIdentifier nvarchar(255) Yes A unique identifier

associated with the
deployed version of a smart
contract for a specific
distributed ledger. For
example, Ethereum.
ContractDeployedByUserId int No The unique identifier of the

user that deployed the
contract.
ContractDeployedByUserFirs nvarchar(50) Yes First name of the user who

tName deployed the contract.
ContractDeployedByUserLas nvarchar(255) Yes Last name of the user who

ContractDeployedByUserExt nvarchar(255) No External identifier of the user

ernalId who deployed the contract.
By default this is the guid
that represents their identity
in the consortium Azure
Active Directory.

contract.
WorkflowFunctionId int No A unique identifier for a

workflow function.
WorkflowFunctionName nvarchar(50) No The name of the function.
WorkflowFunctionDisplayNa nvarchar(255) No The name of a function to

me be displayed in the user
interface.
WorkflowFunctionDescriptio nvarchar(255) No The description of the

n function.
ContractActionId int No The unique identifier for a

contract action.
ContractActionProvisioningS int No Identifies the current status

tatus of the provisioning process
for the contract action.
Possible values are:
0 – The contract action has
been created by the API in
the database
been sent to the ledger
been successfully deployed
to the ledger
ContractActionTimestamp datetime(2,7) No The timestamp of the

contract action.
ContractActionExecutedByU int No Unique identifier of the user

serId that executed the contract
action.
ContractActionExecutedByU int Yes First name of the user who

serFirstName executed the contract action.
ContractActionExecutedByU nvarchar(50) Yes Last name of the user who

serLastName executed the contract action.
ContractActionExecutedByU nvarchar(255) Yes External identifier of the user

serExternalId who executed the contract
action. By default this is the
guid that represents their
identity in the consortium
Azure Active Directory
ContractActionExecutedByU nvarchar(255) Yes The email address of the

serEmailAddress user who executed the
contract action.
WorkflowFunctionParameter int No A unique identifier for a

Id parameter of the function.
WorkflowFunctionParameter nvarchar(50) No The name of a parameter of

Name the function.
WorkflowFunctionParameter nvarchar(255) No The name of a function

DisplayName parameter to be displayed in
the user interface.
WorkflowFunctionParameter int No The unique identifier for the

DataTypeId data type associated with a
workflow function
parameter.
WorkflowParameterDataTyp nvarchar(50) No The name of a data type

eName associated with a workflow
function parameter.
ContractActionParameterVal nvarchar(255) No The value for the parameter

ue stored in the smart contract.
BlockHash nvarchar(255) Yes The hash of the block.
BlockNumber int Yes The number of the block on

the ledger.
BlockTimestamp datetime(2,7) Yes The time stamp of the block.
TransactionId int No A unique identifier for the

transaction.
TransactionFrom nvarchar(255) Yes The party that originated

the transaction.
TransactionTo nvarchar(255) Yes The party that was

transacted with.
TransactionHash nvarchar(255) Yes The hash of a transaction.
TransactionIsWorkbenchTran bit Yes A bit that identifies if the

saction transaction is a Azure
transaction.
TransactionProvisioningStat int Yes Identifies the current status

us of the provisioning process
for the transaction. Possible
values are:
0 – The transaction has been
database
sent to the ledger
ledger
TransactionValue decimal(32,2) Yes The value of the transaction.
vwContractProperty
This view represents the majority of information related to properties associated with a contract and is designed
to readily facilitate common reporting scenarios. For each property taken, this view contains the following data:
Details for the user who deployed the workflow
Associated smart contract property definition
Specific instance values for properties
Details for the state property of the contract

application.

a user interface.

currently enabled.
WorkflowId int No The unique identifier for the

workflow.

displayed in the user
interface.

workflow.
ContractId int No The unique identifier for the

contract.

values are:
database
sent to the ledger
ledger

contract.
ContractLedgerIdentifier nvarchar(255) Yes A unique identifier

associated with the
example, Ethereum.
ContractDeployedByUserId int No The unique identifier of the

user that deployed the
contract.



Active Directory

contract.
WorkflowPropertyId int A unique identifier for a

property of a workflow.
WorkflowPropertyDataTypeI int No The ID of the data type of

d the property.
WorkflowPropertyDataType nvarchar(50) No The name of the data type

Name of the property.
WorkflowPropertyName nvarchar(50) No The name of the workflow

property.
WorkflowPropertyDisplayNa nvarchar(255) No The display name of the

me workflow property.
WorkflowPropertyDescriptio nvarchar(255) Yes A description of the

n property.
ContractPropertyValue nvarchar(255) No The value for a property on

the contract.
StateName nvarchar(50) Yes If this property contains the

state of the contract, this is
the display name for the
state. If it is not associated
with the state, the value will
be null.
StateDisplayName nvarchar(255) No If this property contains the

state, this is the display
name for the state. If it is
not associated with the
state, the value will be null.
StateValue nvarchar(255) Yes If this property contains the

state, this is the state value.
If it is not associated with
the state, the value will be
null.
vwContractState
This view represents the majority of information related to the state of a specific contract and is designed to
readily facilitate common reporting scenarios. Each record in this view contains the following data:
Details for the user who deployed the workflow
Associated smart contract property definition
Details for the state property of the contract

application.

a user interface.

currently enabled.

workflow.
WorkflowDisplayName nvarchar(255) No The name to displayed in

the user interface.

workflow.
ContractLedgerImplementat nvarchar(255) Yes A unique identifier

ionId associated with the
example, Ethereum.
ContractId int No A unique identifier for the

contract.

values are:
database
sent to the ledger
ledger
ConnectionId int No A unique identifier for the

blockchain instance the
workflow is deployed to

contract.
ContractDeployedByUserId int No Unique identifier of the user

that deployed the contract.

Active Directory.



contract.
WorkflowPropertyId int No A unique identifier for a

workflow property.
WorkflowPropertyDataTypeI int No The ID of the data type of

d the workflow property.

Name of the workflow property.
WorkflowPropertyName nvarchar(50) No The name of the workflow

property.
WorkflowPropertyDisplayNa nvarchar(255) No The display name of the

me property to show in a UI.
WorkflowPropertyDescriptio nvarchar(255) Yes The description of the

n property.
ContractPropertyValue nvarchar(255) No The value for a property

stored in the contract.
StateName nvarchar(50) Yes If this property contains the

StateDisplayName nvarchar(255) No If this property contains the

StateValue nvarchar(255) Yes If this property contains the

state, this is the state value.
If it is not associated with
the state, the value will be
null.
vwUser
This view provides details on the consortium members that are provisioned to use Azure Blockchain Workbench.
By default, data is populated through the initial provisioning of the user.
ID int No A unique identifier for a user.
ExternalID nvarchar(255) No An external identifier for a

user. By default, this is the
guid representing the Azure
Active Directory ID for the
user.
ProvisioningStatus int No Identifies the current status

by the API
the database
provisioned
FirstName nvarchar(50) Yes The first name of the user.
LastName nvarchar(50) Yes The last name of the user.
EmailAddress nvarchar(255) Yes The email address of the

user.
vwWorkflow
This view represents the details core workflow metadata as well as the workflow’s functions and parameters.
Designed for reporting, this also contains metadata about the application associated with the workflow. This view
contains data from multiple underlying tables to facilitate reporting on workflows. For each workflow, this view
contains the following data:
Associated workflow start state information

Application
ApplicationName nvarchar(50) No The name of the Application

a user interface

enabled
WorkflowId int Yes A unique identifier for a

workflow
WorkflowName nvarchar(50) No The name of the workflow

the user interface

workflow.
WorkflowConstructorFuncti int No The identifier of the

onId workflow function that
serves as the constructor for
the workflow.
WorkflowStartStateId int No A unique identifier for the

state.
WorkflowStartStateName nvarchar(50) No The name of the state.
WorkflowStartStateDisplayN nvarchar(255) No The name to be displayed in

ame the user interface for the
state.
WorkflowStartStateDescripti nvarchar(255) Yes A description of the

on workflow state.
WorkflowStartStateStyle nvarchar(50) Yes This value identifies the

percentage complete that
the workflow is when in this
state.
WorkflowStartStateValue int No This is the value of the state.
WorkflowStartStatePercentC int No A text description that

omplete provides a hint to clients on
how to render this state in
the UI. Supported states
include Success and Failure
vwWorkflowFunction
This view represents the details core workflow metadata as well as the workflow’s functions and parameters.
Designed for reporting, this also contains metadata about the application associated with the workflow. This view
contains data from multiple underlying tables to facilitate reporting on workflows. For each workflow function,
this view contains the following data:
Workflow function details

application
ApplicationName nvarchar(50) No The name of the Application

a user interface

enabled
WorkflowId int No A unique identifier for a

workflow.

displayed in the user
interface.

workflow.
WorkflowFunctionId int No A unique identifier for a

function.
WorkflowFunctionName nvarchar(50) Yes The name of the function.
WorkflowFunctionDisplayNa nvarchar(255) No The name of a function to

me be displayed in the user
interface
WorkflowFunctionDescriptio nvarchar(255) Yes The description of the

n workflow function.
WorkflowFunctionIsConstru bit No This identifies if the workflow

ctor function is the constructor
for the workflow.
WorkflowFunctionParameter int No A unique identifier for a

Id parameter of a function.
WorkflowFunctionParameter nvarchar(50) No The name of a parameter of

Name the function.
WorkflowFunctionParameter nvarchar(255) No The name of a function

DisplayName parameter to be displayed in
the user interface
WorkflowFunctionParameter int No A unique identifier for the

DataTypeId data type associated with a
workflow function
parameter.
WorkflowParameterDataTyp nvarchar(50) No The name of a data type

eName associated with a workflow
function parameter.
vwWorkflowProperty
This view represents the properties defined for a workflow. For each property, this view contains the following
data:
Workflow property details

application.

a user interface.

currently enabled.

workflow.
WorkflowDisplayName nvarchar(255) No The name to be displayed

for the workflow in a user
interface.
WorkflowDescription nvarchar(255) Yes A description of the

workflow.
WorkflowPropertyID int No A unique identifier for a

property of a workflow.
WorkflowPropertyName nvarchar(50) No The name of the property
WorkflowPropertyDescriptio nvarchar(255) Yes A description of the

n property
WorkflowPropertyDisplayNa nvarchar(255) No The name to be displayed in

me a user interface
WorkflowPropertyWorkflowI int No The ID of the workflow to

d which this property is
associated
WorkflowPropertyDataTypeI int No The ID of the data type

d defined for the property

Name defined for the property
WorkflowPropertyIsState bit No This field identifies if this

workflow property contains
the state of the workflow.
vwWorkflowState
This view represents the properties associated with a workflow. For each contract, this view contains the following
data:
Workflow state information

application.
ApplicationDisplayName nvarchar(255) No A description of the

application

currently enabled.
WorkflowId int No The unique identifier for the

workflow.

the user interface for the
workflow.

workflow.
WorkflowStateID int No The unique identifier for the

state.
WorkflowStateName nvarchar(50) No The name of the state.
WorkflowStateDisplayName nvarchar(255) No The name to be displayed in

the user interface for the
state.
WorkflowStateDescription nvarchar(255) Yes A description of the

workflow state.
WorkflowStatePercentCompl int No This value identifies the

ete percentage complete that
the workflow is when in this
state.
WorkflowStateValue nvarchar(50) No This is the value of the state.
WorkflowStateStyle nvarchar(50) No A text description that

provides a hint to clients on
how to render this state in
the UI. Supported states
include Success and Failure
Azure Blockchain Workbench messaging integration
In addition to providing a REST API, Azure Blockchain Workbench also provides messaging-based integration.
Workbench publishes ledger-centric events via Azure Event Grid, enabling downstream consumers to ingest data
or take action based on these events. For those clients that require reliable messaging, Azure Blockchain
Workbench delivers messages to an Azure Service Bus endpoint as well.
Developers have also expressed interest in the ability to have external systems communicate initiate transactions to
create users, create contracts, and update contracts on a ledger. While this functionality is not currently exposed in
public preview, a sample that delivers that capability can be found at http://aka.ms/blockchain-workbench-
integration-sample.
Event notifications
Event notifications can be used to notify users and downstream systems of events that happen in Blockchain
Workbench and the blockchain network it is connected to. Event notifications can be consumed directly in code or
used with tools such as Logic Apps and Flow to trigger flow of data to downstream systems.
See Notification message reference for details of various messages that can be received.
Consuming Event Grid events with Azure Functions
If a user wants to use Event Grid to be notified about events that happen in Blockchain Workbench, you can
consume events from Event Grid by using Azure Functions.
1. Create an Azure Function App in the Azure portal.
2. Create a new function.
3. Locate the template for Event Grid. Basic template code for reading the message is shown. Modify the code as
needed.
4. Save the Function.
5. Select the Event Grid from Blockchain Workbench’s resource group.
Consuming Event Grid events with Logic Apps
1. Create a new Azure Logic App in the Azure portal.
2. When opening the Azure Logic App in the portal, you will be prompted to select a trigger. Select Azure Event
Grid -- When a resource event occurs.
3. When the workflow designer is displayed, you will be prompted to sign in.
4. Select the Subscription. Resource as Microsoft.EventGrid.Topics. Select the Resource Name from the name
of the resource from the Azure Blockchain Workbench resource group.
5. Select the Event Grid from Blockchain Workbench's resource group.
Using Service Bus Topics for notifications

Service Bus Topics can be used to notify users about events that happen in Blockchain Workbench.
1. Browse to the Service Bus within the Workbench’s resource group.
2. Select Topics.
3. Select workbench-external.
4. Create a new subscription to this topic. Obtain a key for it.
5. Create a program, which subscribes to events from this subscription.
Consuming Service Bus Messages with Logic Apps
1. Create a new Azure Logic App in the Azure portal.
2. When opening the Azure Logic App in the portal, you will be prompted to select a trigger. Type Service Bus
into the search box and select the trigger appropriate for the type of interaction you want to have with the
Service Bus. For example, Service Bus -- When a message is received in a topic subscription (auto-
complete).
3. When the workflow designer is displayed, specify the connection information for the Service Bus.
4. Select your subscription and specify the topic of workbench-external.
5. Develop the logic for your application that utilizes the message from this trigger.
Notification message reference

Depending on the OperationName, the notification messages have one of the following message types.
AccountCreated
Indicates that a new account has been requested to be added to the specified chain.
NAME DESCRIPTION
UserId ID of the user that was created.
ChainIdentifier Address of the user that was created on the blockchain

network. In Ethereum, this would be the user's on-chain
address.
public class NewAccountRequest : MessageModelBase

{
public int UserID { get; set; }
public string ChainIdentifier { get; set; }
}
ContractInsertedOrUpdated
Indicates that a request has been made to insert or update a contract on a distributed ledger.
NAME DESCRIPTION
ChainID A unique identifier for the chain associated with the request.
BlockId The unique identifier for a block on the ledger.
ContractId A unique identifier for the contract.
ContractAddress The address of the contract on the ledger.
TransactionHash The hash of the transaction on the ledger.
OriginatingAddress The address of the originator of the transaction.
ActionName The name of the action.
IsUpdate Identifies if this is an update.

NAME DESCRIPTION
Parameters A list of objects that identify the name, value, and data type of
parameters sent to an action.
TopLevelInputParams In scenarios where a contract is connected to one or more

other contracts, these are the parameters from the top-level
contract.
public class ContractInsertOrUpdateRequest : MessageModelBase

{
public int ChainId { get; set; }
public int BlockId { get; set; }
public int ContractId { get; set; }
public string ContractAddress { get; set; }
public string TransactionHash { get; set; }
public string OriginatingAddress { get; set; }
public string ActionName { get; set; }
public bool IsUpdate { get; set; }
public List<ContractProperty> Parameters { get; set; }
public bool IsTopLevelUpdate { get; set; }
public List<ContractInputParameter> TopLevelInputParams { get; set; }
}
UpdateContractAction
Indicates that a request has been made to execution an action on a specific contract on a distributed ledger.
NAME DESCRIPTION
ContractActionId The unique identifier for this contract action
ChainIdentifier The unique identifier for the chain
ConnectionId The unique identifier for the connection
UserChainIdentifier Address of the user that was created on the blockchain

network. In Ethereum, this would be the user’s “on chain”
address.
ContractLedgerIdentifier Address of the contract on the ledger.
WorkflowFunctionName Name of the workflow function.
WorkflowName Name of the workflow.
WorkflowBlobStorageURL The url of the contract in blob storage.
ContractActionParameters Parameters for the contract action.
TransactionHash The hash of the transaction on the ledger.

NAME DESCRIPTION
Provisioning Status The current provisioning status of the action.

0 – Created
1 – In Process
2 – Complete
Complete indicates a confirmation from the ledger that this as
been successfully added.
public class ContractActionRequest : MessageModelBase

{
public int ContractActionId { get; set; }
public int ConnectionId { get; set; }
public string UserChainIdentifier { get; set; }
public string ContractLedgerIdentifier { get; set; }
public string WorkflowFunctionName { get; set; }
public string WorkflowName { get; set; }
public string WorkflowBlobStorageURL { get; set; }
public IEnumerable<ContractActionParameter> ContractActionParameters { get; set; }
public int ProvisioningStatus { get; set; }
}
UpdateUserBalance
Indicates that a request has been made to update the user balance on a specific distributed ledger.
NOTE
This message is generated only for those ledgers that require the funding of accounts.
NAME DESCRIPTION
Address The address of the user that was funded.
Balance The balance of the user balance.
ChainID The unique identifier for the chain.
public class UpdateUserBalanceRequest : MessageModelBase

{
public string Address { get; set; }
public decimal Balance { get; set; }
public int ChainID { get; set; }
}
InsertBlock
Message indicates that a request has been made to add a block on a distributed ledger.
NAME DESCRIPTION
ChainId The unique identifier of the chain to which the block was
added.
NAME DESCRIPTION
BlockId The unique identifier for the block inside Azure Blockchain
Workbench.
BlockHash The hash of the block.
BlockTimeStamp The timestamp of the block.
public class InsertBlockRequest : MessageModelBase

{
public string BlockHash { get; set; }
public int BlockTimestamp { get; set; }
}
InsertTransaction
Message provides details on a request to add a transaction on a distributed ledger.
NAME DESCRIPTION
ChainId The unique identifier of the chain to which the block was
added.
BlockId The unique identifier for the block inside Azure Blockchain
Workbench.
TransactionHash The hash of the transaction.
From The address of the originator of the transaction.
To The address of the intended recipient of the transaction.
Value The value included in the transaction.
IsAppBuilderTx Identifies if this is a Blockchain Workbench transaction.
public class InsertTransactionRequest : MessageModelBase

{
public string From { get; set; }
public string To { get; set; }
public decimal Value { get; set; }
public bool IsAppBuilderTx { get; set; }
}
AssignContractChainIdentifier
Provides details on the assignment of a chain identifier for a contract. For example, in Ethereum blockchain, the
address of a contract on the ledger.
NAME DESCRIPTION
ContractId This is the unique identifier for the contract inside Azure
ChainIdentifier This is the identifier for the contract on the chain.
public class AssignContractChainIdentifierRequest : MessageModelBase

{
public int ContractId { get; set; }
public string ChainIdentifier { get; set; }
}
Classes used by message types

MessageModelBase
The base model for all messages.
NAME DESCRIPTION
OperationName The name of the operation.
RequestId A unique identifier for the request.
public class MessageModelBase

{
public string OperationName { get; set; }
public string RequestId { get; set; }
}
ContractInputParameter
Contains the name, value and type of a parameter.
NAME DESCRIPTION
Name The name of the parameter.
Value The value of the parameter.
Type The type of the parameter.
public class ContractInputParameter

{
public string Name { get; set; }
public string Value { get; set; }
public string Type { get; set; }
}
ContractProperty
Contains the ID, name, value and type of a property.
NAME DESCRIPTION
Id The ID of the property.
Name The name of the property.
Value The value of the property.
Type The type of the property.
public class ContractProperty

{
public int Id { get; set; }
public string Name { get; set; }
public string Value { get; set; }
public string DataType { get; set; }
}
Next steps
Smart contract integration patterns
Ethereum proof-of-authority consortium
Overview
This solution is designed to make it easier to deploy, configure, and govern a multi-member consortium Proof-of-
authority Ethereum network with minimal Azure and Ethereum knowledge.
With a handful of user inputs and a single-click deployment through the Azure portal, each member can provision
a network footprint, using Microsoft Azure Compute, networking, and storage services across the globe. Each
member's network footprint consists of a set of load-balanced validator nodes with which an application or user
can interact to submit Ethereum transactions.
Concepts
Terminology
Consensus - The act of synchronizing data across the distributed network through block validation and
creation.
Consortium member - An entity that participates in consensus on the Blockchain network.
Admin - An Ethereum account that is used to manage participation for a given consortium member.
Validator - A machine associated with an Ethereum account that participates in consensus on behalf of an
Admin.
Proof-of-authority
For those of you who are new to the blockchain community, the release of this solution is a great opportunity to
learn about the technology in an easy and configurable manner on Azure. Proof-of-work is a Sybil-resistance
mechanism that leverages computation costs to self-regulate the network and allow fair participation. This works
great in anonymous, open blockchain networks where competition for cryptocurrency promotes security on the
network. However, in private/consortium networks the underlying Ether has no value. An alternative protocol,
proof-of-authority, is more suitable for permissioned networks where all consensus participants are known and
reputable. Without the need for mining, Proof-of-authority is more efficient while still retaining Byzantine fault
tolerance.
Consortium governance
Since proof-of-authority relies upon a permissioned list of network authorities to keep the network healthy, it's
important to provide a fair mechanism to make modifications to this permission list. Each deployment comes with
a set of smart-contracts and portal for on-chain governance of this permissioned list. Once a proposed change
reaches a majority vote by consortium members, the change is enacted. This allows new consensus participants to
be added or compromised participants to be removed in a transparent way that encourages an honest network.
Admin account
During the deployment of the proof-of-authority nodes, you will be asked for an Admin Ethereum address. You
may use several different mechanisms to generate and secure this Ethereum account. Once this address is added
as an authority on the network, you can use this account to participate in governance. This admin account will also
be used to delegate consensus participation to the validator nodes that are created as part of this deployment.
Since only the public Ethereum address is used, each admin has the flexibility to secure their private keys in a way
that complies with their desired security model.
Validator node
In the proof-of-authority protocol, validator nodes take the place of traditional miner nodes. Each validator has a
unique Ethereum identity that gets added to a smart-contract permission list. Once a validator is on this list, it can
participate in the block creation process. To learn more about this process, see Parity's documentation on Authority
Round consensus. Each consortium member can provision two or more validator nodes across five regions, for
geo-redundancy. Validator nodes communicate with other validator nodes to come to consensus on the state of the
underlying distributed ledger. To ensure fair participation on the network, each consortium member is prohibited
from using more validators than the first member on the network (if the first member deploys three validators,
each member can only have up to three validators).
Identity store
Since each member will have multiple validator nodes running simultaneously and each node must have a
permissioned identity, it's important that the validators can safely acquire a unique active identity on the network.
To facilitate this, we've built an Identity Store that gets deployed in each member's subscription which securely
holds the generated Ethereum identities. Upon deployment the orchestration container will generate an Ethereum
private key for each validator and store it in Azure Key Vault. Before the parity node starts up, it first acquires a
lease on an unused identity to ensure the identity isn't picked up by another node. The identity is provided to the
client which gives it the authority to start creating blocks. If the hosting VM experiences an outage, the identity
lease will be released, allowing a replacement node to resume its identity in the future.
Bootnode registrar
To enable the ease of connectivity, each member will host a set of connection information at the data API endpoint.
This data includes a list of bootnodes which are provided as peering nodes for the joining member. As part of this
data API, we keep this bootnode list up-to-date
Bring your own operator
Often a consortium member will want to participate in network governance but don't want to operate and
maintain their infrastructure. Unlike traditional systems, having a single operator across the network works against
the decentralized model of blockchain systems. Instead of hiring a centralized intermediary to operate a network,
each consortium member can delegate infrastructure management to the operator of their choosing. This allows a
hybrid model where each member can choose to operate his or her own infrastructure or delegate operation to a
different partner. The delegated operation workflow works as follows:
1. Consortium Member generates an Ethereum address (holds private key)
2. Consortium Member provides public Ethereum address to Operator
3. Operator deploys and configures the PoA validator nodes using our Azure Resource Manager solution
4. Operator provides the RPC and management endpoint to Consortium Member
5. Consortium Member uses their private key to sign a request accepting the validator nodes Operator has
deployed to participate on their behalf
Azure Monitor
This solution also comes with Azure Monitor to track node and network statistics. For application developers, this
provides visibility into the underlying blockchain to track block generation statistics. Network operators can use
Azure Monitor to quickly detect and prevent network outages through infrastructure statistics and queryable logs.
See Service monitoring for more details.
Deployment architecture
Description
This solution can deploy a single or multi-region based multi-member Ethereum consortium network. By default,
the RPC and peering endpoints are accessible over public IP to enable simplified connectivity across subscriptions
and clouds. We recommend leveraging Parity's permissioning contracts for application level access-controls. We
also support networks deployed behind VPNs, which leverage VNet gateways for cross-subscription connectivity.
These deployments are more complex, so it is recommended to start with the public IP model first.
Consortium member overview
Each consortium member deployment includes:
Virtual Machines for running the PoA validators
Azure Load Balancer for distributing RPC, peering, and Governance DApp requests
Azure Key Vault for securing the validator identities
Azure Storage for hosting persistent network information and coordinating leasing
Azure Monitor for aggregating logs and performance statistics
VNet Gateway (optional) for allowing VPN connections across private VNets
We leverage Docker containers for reliability and modularity. We use Azure Container Registry to host and serve
versioned images as part of each deployment. The container images consist of:
Orchestrator
Runs once during deployment
Generates identities and governance contracts
Stores identities in Identity Store
Parity Client
Leases identity from Identity Store
Discovers and connects to peers
EthStats Agent
Collects local logs and stats via RPC and pushes to Azure Monitor
Governance DApp
Web interface for interacting with Governance contracts
How-to guides
Governance DApp
At the heart of proof-of-authority is decentralized governance. The governance DApp is a set of pre-deployed
smart contracts and a web application that are used to govern the authorities on the network. Authorities are
broken up into Admin identities and Validator nodes. Admins have the power to delegate consensus participation
to a set of Validator nodes. Admins also may vote other admins into or out of the network.
Decentralized Governance - Changes in network authorities are administered through on-chain voting by
select administrators.
Validator Delegation - Authorities can manage their validator nodes that are set up in each PoA
deployment.
Auditable Change History - Each change is recorded on the blockchain providing transparency and
auditability.
Getting started with governance
To perform any kind of transactions through the Governance DApp, you will need to leverage an Ethereum wallet.
The most straightforward approach is to use an in-browser wallet such as MetaMask; however, because these are
smart contracts deployed on the network you may also automate your interactions to the Governance contract.
After installing MetaMask, navigate to the Governance DApp in the browser. You can locate the URL in the
deployment confirmation email or through Azure portal in the deployment output. If you don't have an in-browser
wallet installed you will not be able to perform any actions; however, you'll still be able to read the administrator
state.
Becoming an admin
If you are the first member that deployed on the network, then you will automatically become an Admin and your
Parity nodes will be listed as Validators. If you are joining the network, you will need to get voted in as an Admin by
a majority (greater than 50%) of the existing Admin set. If you choose not to become an Admin then your nodes
will still sync and validate the blockchain; however, they will not participate in the block creation process. To start
the voting process to become an Admin, click Nominate and enter your Ethereum address and alias.
Candidates
Selecting the Candidates tab will show you the current set of candidate administrators. Once a Candidate reaches
a majority vote by the current Admins, the Candidate will get promoted to an Admin. To vote on a Candidate, select
the row and click "Vote in" at the top. If you change your mind on a vote, you may select the candidate and click
"Rescind vote".
Admins
The Admins tab will show the current set of Admins and provide you the ability to vote against. Once an Admin
loses more than 50% support, they will be removed as an Admin on the network. Any validator nodes that this
Admin owns will lose validator status and become transaction nodes on the network. An Admin may be removed
for any number of reasons; however, it is up to the consortium to agree on a policy in advance.
Validators
Selecting the Validators tab in the left menu will display the current deployed Parity nodes for this instance and
their current status (Node type). Note that each consortium member will have a different set of validators in this
list, since this view represents the current deployed consortium member. If this is a newly deployed instance and
you have not yet added your validators, you will be shown the option to 'Add Validators'. Selecting this will
automatically choose a regionally-balanced set of Parity nodes and assign them to your validator set. If you have
deployed more nodes than the allowed capacity, the remaining nodes will become transaction nodes on the
network.
The address of each validator is automatically assigned via the identity store in Azure. If a node goes down, it will
relinquish its identity, allowing another node in your deployment to take its place. This ensures that your consensus
participation is highly available.
Consortium name
Any Admin may update the Consortium Name, displayed at the top of the page. Select the gear icon in the top left
to update the Consortium Name.
Account menu
In the top-right is your Ethereum account alias and identicon. If you are an Admin you will have the ability to
update your alias.
Deploy Ethereum Proof-of-Authority

Here's an example of a multi-party deployment flow:
1. Three members each generate an Ethereum account using MetaMask
2. Member A deploys Ethereum PoA, providing their Ethereum Public Address
3. Member A provides the consortium URL to Member B and Member C
4. Member B and Member C deploy, Ethereum PoA, providing their Ethereum Public Address and Member A's
consortium URL
5. Member A votes in Member B as an admin
6. Member A and Member B both vote Member C as an admin
This process requires an Azure subscription that can support deploying several virtual machines and managed
disks. If necessary, create a free Azure account to begin.
Once a subscription is secured, go to Azure portal. Select '+', Marketplace ('See all'), and search for Ethereum PoA
Consortium.
The following section will walk you through configuring the first member's footprint in the network. The
deployment flow is divided into five steps: Basics, Deployment regions, Network size and performance, Ethereum
settings, Azure Monitor.
Basics
Under Basics, specify values for standard parameters for any deployment, such as subscription, resource group
and basic virtual machine properties.
A detailed description of each parameter follows:
PARAMETER NAME DESCRIPTION ALLOWED VALUES DEFAULT VALUES
Create a new network or join Create a new network or join Create New Join Existing Create New
existing network? a preexisting consortium
network
Email Address (Optional) You'll receive an email Valid email address NA

notification when your
deployment completes with
information about your
deployment.
VM user name Administrator username of 1-64 characters NA

each deployed VM
(alphanumeric characters
only)
Authentication type The method to authenticate Password or SSH public key Password
to the virtual machine.
Password (Authentication The password for the 12-72 characters NA

type = Password) administrator account for
each of the virtual machines
deployed. The password
must contain 3 of the
following: 1 upper case
character, 1 lower case
character, 1 number, and 1
special character. While all
VMs initially have the same
password, you can change
the password after
provisioning.
SSH Key (Authentication The secure shell key used for NA

type = Public Key) remote login.
Subscription The subscription to which to NA

deploy the consortium
network
Resource Group The resource group to which NA

to deploy the consortium
network.
Location The Azure region for NA

resource group.
A sample deployment is shown below:

Deployment regions
Next, under Deployment regions, specify inputs for number of region(s) to deploy the consortium network and
selection of Azure regions based on the number of regions given. User can deploy in maximum of 5 regions. We
recommend choosing the first region to match the resource group location from Basics section. For development
or test networks, a single region per member is recommended. For production, we recommend deploying across
two or more regions for high-availability.
Number of region(s) Number of regions to deploy 1, 2, 3, 4, 5 1

the consortium network
First region First region to deploy the All allowed Azure regions NA
consortium network
Second region Second region to deploy the All allowed Azure regions NA
consortium network (Visible
only when number of
regions is selected as 2)
Third region Third region to deploy the All allowed Azure regions NA
only when number of
Fourth region Fourth region to deploy the All allowed Azure regions NA
only when number of
Fifth region Fifth region to deploy the All allowed Azure regions NA
only when number of

Network size and performance
Next, under 'Network size and performance' specify inputs for the size of the consortium network, such as number
and size of validator nodes. The validator node storage size will dictate the potential size of the blockchain. This can
be changed after deployment.
Number of load balanced The number of validator 2-15 2

validator nodes nodes to provision as part of
the network
Validator node storage The type of managed disk Standard SSD or Premium Standard SSD
performance backing each of the
deployed validator nodes.
Validator node virtual The virtual machine size Standard A, Standard D, Standard D1 v2
machine size used for validator nodes. Standard D-v2, Standard F
series, Standard DS, and
Standard FS
Storage Pricing Details

Virtual Machine Pricing Details
Note that Virtual Machine and Storage Tier will affect network performance. We recommend the following SKUs
based on desired cost-efficiency:
VIRTUAL MACHINE SKU STORAGE TIER PRICE THROUGHPUT LATENCY
F1 Standard SSD low low high
D2_v3 Standard SSD medium medium medium
F16s Premium SSD high high low

Ethereum settings
Next, under Ethereum settings, specify Ethereum-related configuration settings, like the network ID and Ethereum
account password or genesis block.
Consortium Member ID The ID associated with each 0-255 NA

member participating in the
consortium network used to
configure IP address spaces
to avoid collision. In the case
of a private network,
Member ID should be
unique across different
organizations in the same
network. A unique member
ID is needed even when the
same organization deploys
to multiple regions. Make
note of the value of this
parameter since you will
need to share it with other
joining members to ensure
there’s no collision.
Network ID The network ID for the 5 - 999,999,999 10101010

consortium Ethereum
network being deployed.
Each Ethereum network has
its own Network ID, with 1
being the ID for the public
network.
Admin Ethereum Address Ethereum account address 42 alphanumeric characters NA

that is used for participating starting with 0x
in PoA governance. We
recommend using
MetaMask for generating an
Ethereum address.
Advanced Options Advanced options for Enable or Disable Disable

Ethereum settings
Public IP (Advanced Options Deploys the network behind Public IP Private VNet Public IP
= Enable) a VNet Gateway and
removes peering access. If
this option is selected, all
members must use a VNet
Gateway for the connection
to be compatible.
Block Gas Limit (Advanced The starting block gas limit Any numeric 50,000,00
Options = Enable) of the network
Block Reseal Period (sec) The frequency at which Any numeric 15

empty blocks will be created
when there are no
transactions on the network.
A higher frequency will have
faster finality but increased
storage costs.
Transaction Permission Bytecode for the Transaction Contract bytecode NA

Contract (Advanced Options Permissioning contract.
= Enable) Restricts smart contract
deployment and execution
to a permissioned list of
Ethereum accounts.

Monitoring
The Monitoring blade allows you to configure a Log Analytics resource for your network. The monitoring agent
will collect and surface useful metrics and logs from your network, providing the ability to quickly check the
network health or debug issues.
Monitoring Option to enable Monitoring Enable or Disable Enable
Connect to existing Log Create a new Log Analytics Create new or Join existing Create new
Analytics instance or join an existing
instance
Monitor Location(Connect The region where the new All Log Analytics regions NA
to existing Log Analytics= Log Analytics instance will be
Create new) deployed
Existing Log Analytics Workspace ID of the existing NA

Workspace Id (Connect to Log Analytics instance
existing Log Analytics = Join
Existing)
Existing Log Analytics The primary key used to NA

Primary Key (Connect to connect to the existing Log
existing Log Analytics = Join Analytics instance
Existing)
Summary
Click through the summary blade to review the inputs specified and to run basic pre-deployment validation. Before
deploying you may download the template and parameters.
Review legal and privacy terms and click 'Purchase' to deploy. If the deployment includes VNet Gateways, the
deployment will take up 45 to 50 minutes.
Post deployment
Depl o ym en t o u t pu t
Once the deployment has completed, you'll be able to access the necessary parameters via the confirmation email
or through the Azure portal. In these parameters you'll find:
Ethereum RPC endpoint
Governance Dashboard URL
Azure Monitor URL
Data URL
VNet Gateway Resource ID (optional)
C o n fi r m a t i o n e m a i l
If you provide an email address (Basics Section), an email would be sent to the email address with the deployment
output information.
Port al
Once the deployment has completed successfully and all resources have been provisioned you'll be able to view
the output parameters in your resource group.
1. Locate your resource group in the portal
2. Navigate to Deployments
3. Select the top deployment with the same name as your resource group
4. Select Outputs
Growing the consortium
To expand your consortium, you must first connect the physical network. Using the Public IP -based deployment
this first step is seamless. If deploying behind a VPN, see the section Connecting VNet Gateway to perform the
network connection as part of the new member deployment. Once your deployment completes use the
Governance DApp to become a network Admin.
New member deployment
1. Share the following information with the joining member. This information can be found in your post-
deployment email or in the portal deployment output.
Consortium Data Url
The number of nodes you've deployed
VNet Gateway Resource ID (if using VPN )
2. The deploying member should use the same solution when deploying their network presence with keeping
the following in mind:
Select Join Existing
Choose the same number of validator nodes as the rest of the members on the network to ensure fair
representation
Use the same Ethereum address that was provided in the previous step
Pass in the provided Consortium Data Url on the Ethereum Settings tab
If the rest of the network is behind a VPN, select Private VNet under the advanced section
Connecting VNet gateways
You may ignore this step if you've deployed using the default Public IP settings. In the case of a private network,
the different members are connected via VNet gateway connections. Before a member can join the network and
see transaction traffic, an existing member must perform a final configuration on their VPN gateway to accept the
connection. This means that the Ethereum nodes of the joining member will not run until a connection is
established. It is recommended to create redundant network connections (mesh) into the consortium to reduce
chances of a single point of failure.
After the new member deploys, the existing member must complete the bi-directional connection by setting up a
VNet gateway connection to the new member. To achieve this, existing member will need:
1. The VNet gateway ResourceID of the connecting member (see deployment output)
2. The shared connection key
The existing member must run the following PowerShell script to complete the connection. We recommend using
Azure Cloud Shell located in the top right navigation bar in the portal.
$MyGatewayResourceId = "<EXISTING_MEMBER_RESOURCEID>"
$OtherGatewayResourceId = "<NEW_MEMBER_RESOURCEID]"
$ConnectionName = "Leader2Member"
$SharedKey = "<NEW_MEMBER_KEY>"
## $myGatewayResourceId tells me what subscription I am in, what ResourceGroup and the VNetGatewayName
$splitValue = $MyGatewayResourceId.Split('/')
$MySubscriptionid = $splitValue[2]
$MyResourceGroup = $splitValue[4]
$MyGatewayName = $splitValue[8]
## $otherGatewayResourceid tells me what the subscription and VNet GatewayName are

$OtherGatewayName = $OtherGatewayResourceId.Split('/')[8]
$Subscription=Select-AzureRmSubscription -SubscriptionId $MySubscriptionid
## create a PSVirtualNetworkGateway instance for the gateway I want to connect to

$OtherGateway=New-Object Microsoft.Azure.Commands.Network.Models.PSVirtualNetworkGateway
$OtherGateway.Name = $OtherGatewayName
$OtherGateway.Id = $OtherGatewayResourceId
$OtherGateway.GatewayType = "Vpn"
$OtherGateway.VpnType = "RouteBased"
## get a PSVirtualNetworkGateway instance for my gateway

$MyGateway = Get-AzureRmVirtualNetworkGateway -Name $MyGatewayName -ResourceGroupName $MyResourceGroup
## create the connection

New-AzureRmVirtualNetworkGatewayConnection -Name $ConnectionName -ResourceGroupName $MyResourceGroup -
VirtualNetworkGateway1 $MyGateway -VirtualNetworkGateway2 $OtherGateway -Location $MyGateway.Location -
ConnectionType Vnet2Vnet -SharedKey $SharedKey -EnableBgp $True
Service monitoring
You can locate your Azure Monitor portal either by following the link in the deployment email or locating the
parameter in the deployment output [OMS_PORTAL_URL ].
The portal will first display high-level network statistics and node overview.
Selecting Node Overview will direct you to a portal to view per-node infrastructure statistics.
Selecting Network Stats will direct you to view Ethereum network statistics.
Sample Log Analytics queries

Behind these dashboards is a set of queryable raw logs. You can use these raw logs to customize the dashboards,
investigate failures, or setup threshold alerting. Below you'll find a set of example queries that can be ran in the Log
Search tool:
L i st s b l o c k s t h a t h a v e b e e n r e p o r t e d b y m o r e t h a n o n e v a l i d a t o r. U se fu l t o h e l p fi n d c h a i n fo r k s.
MinedBlock_CL
| summarize DistinctMiners = dcount(BlockMiner_s) by BlockNumber_d, BlockMiner_s
| where DistinctMiners > 1
G e t a v e r a g e p e e r c o u n t fo r a sp e c i fi e d v a l i d a t o r n o d e a v e r a g e d o v e r 5 m i n u t e b u c k e t s.
let PeerCountRegex = @"Syncing with peers: (\d+) active, (\d+) confirmed, (\d+)";
ParityLog_CL
| where Computer == "vl-devn3lgdm-reg1000001"
| project RawData, TimeGenerated
| where RawData matches regex PeerCountRegex
| extend ActivePeers = extract(PeerCountRegex, 1, RawData, typeof(int))
| summarize avg(ActivePeers) by bin(TimeGenerated, 5m)
SSH access
For security reasons, the SSH port access is denied by a network group security rule by default. To access the
virtual machine instances in the PoA network, you will need to change this rule to "Allow"
1. Start in the Overview section of the deployed resource group from Azure portal.
2. Select the Network Security Group for the region of the VM that you are wanting to access
3. Select the "allow -ssh" rule
4. Change "Action" to Allow

5. Click "Save" (Changes may take a few minutes to apply)
You can now remotely connect to the virtual machines for the validator nodes via SSH with your provided admin
username and password/SSH key. The SSH command to run to access the first validator node is listed in the
template deployment output parameter as, 'SSH_TO_FIRST_VL_NODE_REGION1' (for the sample deployment:
ssh -p 4000 poaadmin@leader4vb.eastus.cloudapp.azure.com). To get to additional transaction nodes, increment
the port number by one (For example, the first transaction node is on port 4000).
If you deployed to more than one region, change the above command to the DNS name or IP address of the load
balancer in that region. To find the DNS name or IP address of the other regions, find the resource with the naming
convention *****-lbpip-reg#, and view its DNS name and IP address properties.
Azure Traffic Manager load balancing
Azure Traffic Manager can help reduce downtime and improve responsiveness of the PoA network by routing
incoming traffic across multiple deployments in different regions. Built-in health checks and automatic re-routing
help ensure high availability of the RPC endpoints and the Governance DApp. This feature is useful if you have
deployed to multiple regions and are production ready.
Use Traffic Manager to:
Improve PoA network availability with automatic failover.
Increase your networks responsiveness by routing end users to the Azure location with lowest network
latency.
If you decide to create a Traffic Manager profile, you can use the DNS name of the profile to access your network.
Once other consortium members have been added to the network, the Traffic Manager can also be used to load
balance across their deployed validators.
Creating a Traffic Manager profile
Search for and select "Traffic Manager profile" after clicking the "Create a resource" button in the Azure portal.
Give the profile a unique name and select the Resource Group that was created during the PoA deployment. Click
the "Create" button to deploy.
Once it is deployed, then select the instance in the resource group. The DNS name to access the traffic manager
can be found in the Overview tab
Select the Endpoints tab and click the Add button. Give the endpoint a unique name. Change the Target resource
type to Public IP address. Then select the public IP address of the first region's load balancer.
Repeat for each region in the deployed network. Once the endpoints are in the "enabled" status, they will be
automatically load and region balanced at the DNS name of the traffic manager. You can now use this DNS name
in place of the [CONSORTIUM_DATA_URL ] parameter in other steps of the document.
Data API
Each consortium member hosts the necessary information for others to connect to the network. The existing
member will provide the [CONSORTIUM_DATA_URL ] prior to the member's deployment. Upon deployment, a
joining member will retrieve information from the JSON interface at the following endpoint:
<CONSORTIUM_DATA_URL>/networkinfo
The response will contain information useful for joining members (Genesis block, Validator Set contract ABI,
bootnodes) as well as information useful to the existing member (validator addresses). We encourage use of this
standardization to extend the consortium across cloud providers. This API will return a JSON formatted response
with the following structure:
{
"$id": "",
"type": "object",
"definitions": {},
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"properties": {
"majorVersion": {
"$id": "/properties/majorVersion",
"type": "integer",
"title": "This schema’s major version",
"default": 0,
"examples": [
0
]
},
"minorVersion": {
"$id": "/properties/minorVersion",
"type": "integer",
"title": "This schema’s minor version",
"default": 0,
"examples": [
0
]
},
"bootnodes": {
"$id": "/properties/bootnodes",
"type": "array",
"items": {
"$id": "/properties/bootnodes/items",
"type": "string",
"title": "This member’s bootnodes",
"default": "",
"examples": [
"enode://a348586f0fb0516c19de75bf54ca930a08f1594b7202020810b72c5f8d90635189d72d8b96f306f08761d576836a6bfce112cf
b6ae6a3330588260f79a3d0ecb@10.1.17.5:30300",
"enode://2d8474289af0bb38e3600a7a481734b2ab19d4eaf719f698fe885fb239f5d33faf217a860b170e2763b67c2f18d91c41272de3
7ac67386f80d1de57a3d58ddf2@10.1.17.4:30300"
]
}
},
"valSetContract": {
"$id": "/properties/valSetContract",
"type": "string",
"title": "The ValidatorSet Contract Source",
"default": "",
"examples": [
"pragma solidity 0.4.21;\n\nimport \"./SafeMath.sol\";\nimport \"./Utils.sol\";\n\ncontract
ValidatorSet …"
]
},
"adminContract": {
"$id": "/properties/adminContract",
"type": "string",
"title": "The AdminSet Contract Source",
"default": "",
"examples": [
"pragma solidity 0.4.21;\nimport \"./SafeMath.sol\";\nimport \"./SimpleValidatorSet.sol\";\nimport
\"./Admin.sol\";\n\ncontract AdminValidatorSet is SimpleValidatorSet { …"
]
},
"adminContractABI": {
"$id": "/properties/adminContractABI",
"type": "string",
"title": "The Admin Contract ABI",
"default": "",
"examples": [
"[{\"constant\":false,\"inputs\":[{\"name\":\"proposedAdminAddress\",\"type\":\"address\"},…"
]
},
"paritySpec": {
"$id": "/properties/paritySpec",
"type": "string",
"title": "The Parity client spec file",
"title": "The Parity client spec file",
"default": "",
"examples": [
"\n{\n \"name\": \"PoA\",\n \"engine\": {\n \"authorityRound\": {\n \"params\": {\n \"stepDuration\":
\"2\",\n \"validators\" : {\n \"safeContract\": \"0x0000000000000000000000000000000000000006\"\n },\n
\"gasLimitBoundDivisor\": \"0x400\",\n \"maximumExtraDataSize\": \"0x2A\",\n \"minGasLimit\": \"0x2FAF080\",\n
\"networkID\" : \"0x9a2112\"\n }\n }\n },\n \"params\": {\n \"gasLimitBoundDivisor\": \"0x400\",\n
\"maximumExtraDataSize\": \"0x2A\",\n \"minGasLimit\": \"0x2FAF080\",\n \"networkID\" : \"0x9a2112\",\n
\"wasmActivationTransition\": \"0x0\"\n },\n \"genesis\": {\n \"seal\": {\n \"authorityRound\": {\n \"step\":
\"0x0\",\n \"signature\":
\"0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
00000000000000000000000\"\n }\n },\n \"difficulty\": \"0x20000\",\n \"gasLimit\": \"0x2FAF080\"\n },\n
\"accounts\": {\n \"0x0000000000000000000000000000000000000001\": { \"balance\": \"1\", \"builtin\": {
\"name\": \"ecrecover\", \"pricing\": { \"linear\": { \"base\": 3000, \"word\": 0 } } } },\n
\"0x0000000000000000000000000000000000000002\": { \"balance\": \"1\", \"builtin\": { \"name\": \"sha256\",
\"pricing\": { \"linear\": { \"base\": 60, \"word\": 12 } } } },\n
\"0x0000000000000000000000000000000000000003\": { \"balance\": \"1\", \"builtin\": { \"name\": \"ripemd160\",
\"0x0000000000000000000000000000000000000004\": { \"balance\": \"1\", \"builtin\": { \"name\": \"identity\",
\"0x0000000000000000000000000000000000000006\": { \"balance\": \"0\", \"constructor\" : \"…\" }\n }\n}"
]
},
"errorMessage": {
"$id": "/properties/errorMessage",
"type": "string",
"title": "Error message",
"default": "",
"examples": [
""
]
},
"addressList": {
"$id": "/properties/addressList",
"type": "object",
"properties": {
"addresses": {
"$id": "/properties/addressList/properties/addresses",
"type": "array",
"items": {
"$id": "/properties/addressList/properties/addresses/items",
"type": "string",
"title": "This member’s validator addresses",
"default": "",
"examples": [
"0x00a3cff0dccc0ecb6ae0461045e0e467cff4805f",
"0x009ce13a7b2532cbd89b2d28cecd75f7cc8c0727"
]
}
}
}
}
}
}
Tutorials
Programmatically interacting with a smart contract
WARNING
Never send your Ethereum private key over the network! Ensure that each transaction is signed locally first and the signed
transaction is sent over the network.
In the following example, we use ethereumjs-wallet to generate an Ethereum address, ethereumjs-tx to sign locally,
and web3 to send the raw transaction to the Ethereum RPC endpoint.
We'll use this simple Hello-World smart contract for this example:
pragma solidity ^0.4.11;

contract postBox {
string message;
function postMsg(string text) public {
message = text;
}
function getMsg() public view returns (string) {
return message;
}
}
This example assumes the contract is already deployed. You can use solc and web3 for deploying a contract
programmatically. First install the following node modules:
sudo npm install web3@0.20.2

sudo npm install ethereumjs-tx@1.3.6
sudo npm install ethereumjs-wallet@0.6.1
This nodeJS script will perform the following:

Construct a raw transaction: postMsg
Sign the transaction using the generated private key
Submit the signed transaction to the Ethereum network
var ethereumjs = require('ethereumjs-tx')
var wallet = require('ethereumjs-wallet')
var Web3 = require('web3')
// TODO Replace with your contract address

var address = "0xfe53559f5f7a77125039a993e8d5d9c2901edc58";
var abi = [{"constant": false,"inputs": [{"name": "text","type": "string"}],"name": "postMsg","outputs":
[],"payable": false,"stateMutability": "nonpayable","type": "function"},{"constant": true,"inputs": [],"name":
"getMsg","outputs": [{"name": "","type": "string"}],"payable": false,"stateMutability": "view","type":
"function"}];
// Generate a new Ethereum account

var account = wallet.generate();
var accountAddress = account.getAddressString()
var privateKey = account.getPrivateKey();
// TODO Replace with your RPC endpoint

var web3 = new Web3(new Web3.providers.HttpProvider(
"http://testzvdky-dns-reg1.eastus.cloudapp.azure.com:8545"));
// Get the current nonce of the account

web3.eth.getTransactionCount(accountAddress, function (err, nonce) {
var data = web3.eth.contract(abi).at(address).postMsg.getData("Hello World");
var rawTx = {
nonce: nonce,
gasPrice: '0x00',
gasLimit: '0x2FAF080',
to: address,
value: '0x00',
data: data
}
var tx = new ethereumjs(rawTx);
tx.sign(privateKey);
var raw = '0x' + tx.serialize().toString('hex');

web3.eth.sendRawTransaction(raw, function (txErr, transactionHash) {
console.log("TX Hash: " + transactionHash);
console.log("Error: " + txErr);
});
});
Deploy smart contract with Truffle

Install necessary libraries
npm init
npm install truffle-hdwallet-provider --save
In truffle.js, add following code to unlock your MetaMask account and configure the PoA node as entry point by
providing the mnemonic phrase (MetaMask / Settings / Reveal Seed Words)
var HDWalletProvider = require("truffle-hdwallet-provider");
var rpc_endpoint = "XXXXXX";

var mnemonic = "twelve words you can find in metamask/settings/reveal seed words";
module.exports = {
networks: {
development: {
host: "localhost",
port: 8545,
network_id: "*" // Match any network id
},
poa: {
provider: new HDWalletProvider(mnemonic, rpc_endpoint),
network_id: 3,
gasPrice : 0
}
}
};
Deploy to PoA network
$ truffle migrate --network poa
Debug smart contract with Truffle

Truffle has a local develop network that is available for debugging smart contract. You can find the full tutorial here.
WebAssembly (WASM ) support
WebAssembly support is already enabled for you on newly deployed PoA networks. It allows for smart-contract
development in any language that transpiles to Web-Assembly (Rust, C, C++). See the links below for additional
information
Parity Overview of WebAssembly - https://wiki.parity.io/WebAssembly-Home
Tutorial from Parity Tech - https://github.com/paritytech/pwasm-tutorial
Reference
FAQ
I notice there are many transactions on the network that I didn't send. Where are these coming from?
It is insecure to unlock the personal API. Bots listen for unlocked Ethereum accounts and attempt to drain the
funds. The bot assumes these accounts contain real-ether and attempt to be the first to siphon the balance. Do not
enable the personal API on the network. Instead pre-sign the transactions either manually using a wallet like
MetaMask or programmatically as outlined in the section Programmatically Interacting with a Smart Contract.
How to SSH onto a VM?
The SSH port is not exposed for security reasons. Follow this guide to enable the SSH port.
How do I set up an audit member or transaction nodes?
Transaction nodes are a set of Parity clients that are peered with the network but are not participating in consensus.
These nodes can still be used to submit Ethereum transactions and read the smart contract state. This works well as
a mechanism for providing auditability to non-authority consortium members on the network. To achieve this
simply follow Step 2 from Growing the Consortium.
Why are MetaMask transactions taking a long time?
To ensure transactions are received in the correct order, each Ethereum transaction comes with an incrementing
nonce. If you've used an account in MetaMask on a different network, you'll need to reset the nonce value. Click on
the settings icon (3-bars), Settings, Reset Account. The transaction history will be cleared and now you can
resubmit the transaction.
Do I need to specify gas fee in MetaMask?
Ether doesn't serve a purpose in proof-of-authority consortium. Hence there is no need to specify gas fee when
submitting transactions in MetaMask.
What should I do if my deployment fails due to failure to provision Azure OMS?
Monitoring is an optional feature. In some rare cases where your deployment fails because of inability to
successfully provision Azure Monitor resource you can redeploy without Azure Monitor.
Are public IP deployments compatible with private network deployments?
No, peering requires two-way communication so the entire network must either be public or private.
What is the expected transaction throughput of Proof-of-Authority?
The transaction throughput will be highly dependent upon the types of transactions and the network topology.
Using simple transactions, we've benchmarked an average of 400 transactions per second with a network deployed
across multiple regions.
How do I subscribe to smart contract events?
Ethereum Proof-of-Authority now supports web-sockets. Check your deployment email or deployment output to
locate the web-socket URL and port.
Next steps
Get started by using the Ethereum Proof-of-Authority Consortium solution.
Ethereum proof-of-work consortium solution template
The Ethereum Proof-of-Work Consortium solution template is designed to make it easier and quicker to deploy
and configure a multi-member consortium Ethereum network with minimal Azure and Ethereum knowledge.
With a handful of user inputs and a single-click deployment through the Azure portal, each member can provision
their network footprint, using Microsoft Azure Compute, networking, and storage services across the globe. Each
member's network footprint consists of a set of load-balanced transaction nodes with which an application or user
can interact to submit transactions, a set of mining nodes to record transactions, and a VPN gateway. A subsequent
connection step connects the gateways to create a fully configured multi-member blockchain network.
About blockchain
For those of you who are new to the blockchain community, the release of this solution is a great opportunity to
learn about the technology in an easy and configurable manner on Azure. However, to get started, we recommend
deploying the simpler standalone Ethereum network topology with this guided walkthrough, before building out
multi-member consortium networks.
Mining node details
Nodes that mine transactions are separated from the nodes that accept transactions to ensure that the two actions
are not competing for the same resources.
A consortium member can provision up to five regions containing one or more mining nodes, backed by a
managed disk. One or more nodes in the region are configured as a boot node to support dynamic discoverability
of the nodes in the network. Mining nodes communicate with other mining nodes to come to consensus on the
state of the underlying distributed ledger. There is no need for your application to be aware of or communicate with
these nodes. By focusing on private networks, the mining nodes are isolated from inbound public internet traffic to
add a secondary layer of protection. Outbound traffic is allowed, but not to the Ethereum discovery port.
All nodes have a stable version of the Go Ethereum (Geth) client and are configured to be mining nodes. If you did
not supply a custom genesis block, all nodes use the same Ethereum address and key pair that is protected by the
Ethereum account password. The Ethereum passphrase you provided is used to generate the default account
(coinbase) for each mining node. As mining nodes, mine, they collect fees that are added to this account.
The number of mining nodes per consortium member depends on the overall size of the network desired and the
amount of hashing power dedicated to each member. The larger the network, the more nodes that need to be
compromised to gain an unfair advantage. The template supports up to 15 mining nodes per region provisioned
using virtual machine scale sets.
Transaction node details
A consortium member also has a set of load-balanced transaction nodes. These nodes are reachable from outside
the virtual network, so that applications can use these nodes to submit transactions or execute smart contracts
within the blockchain network. All nodes have a stable version of the Go Ethereum (Geth) client and are configured
to maintain a complete copy of the distributed ledger. If a custom genesis block is not provided, these nodes use
the same Ethereum account, protected by the Ethereum account password.
Transaction nodes are load-balanced within an availability set to maintain high availability. The template supports
up to five transaction nodes provisioned using virtual machine scale sets.
Log analytics details
Each deployment also creates a new Log Analytics instance or can join an existing instance. This allows the
monitoring of various performance metrics of each virtual machine that makes up the deployed network.
Deployment architecture
Description
This solution template can deploy single or multi region-based multi member Ethereum consortium network. The
virtual network of each region is connected to other region in a chain topology using the VNET gateways and
connection resources. It also provisions a registrar, which contains required information of all the Miner and
Transaction nodes deployed in each region.
Standalone and consortium leader overview
Joining consortium member overview

Getting started
This process requires an Azure subscription that can support deploying several virtual machines scale sets and
managed disks. If necessary, create a free Azure account to begin.
Once a subscription is secured, go to Azure portal. Select + Create a resource, Marketplace (See all), and search
for Ethereum Proof-of-Work Consortium.
The template deployment will walk you through configuring the first member's footprint in the network. The
deployment flow is divided into five steps: Basics, Operations Management Suite, Deployment regions, Network
size, and performance, Ethereum settings.
Basics
Under Basics, specify values for standard parameters for any deployment, such as subscription, resource group,
and basic virtual machine properties.

Create a new network or join Create a new network or join Create New Join Existing Create New
existing network? a pre-existing consortium
network
Deploy a network that will A consortium network Standalone Consortium Standalone

be part of a consortium? allows future deployments
to join this network (visible
when Create New is selected
above)
Resource Prefix String used as a base for Alphanumeric characters NA

naming resources (2 to 4 with length 2 to 4
alphanumeric characters). A
unique hash is prepended to
the string for some
resources, while resource-
specific information is
appended.
VM user name Administrator username of 1 - 64 characters gethadmin

each deployed VM
(alphanumeric characters
only)
Password (Authentication The password for the 12 - 72 characters NA

following requirements: 1
upper case character, 1 lower
case character, 1 number,
and 1 special character.
While all VMs initially have
the same password, you can
change the password after
provisioning.
SSH Key(Authentication type The secure shell key used for NA

= Public Key) remote login.
Subscription The subscription to which to NA

deploy the consortium
network

network.
Location The Azure region for NA

resource group.
Operations Management Suite

The Operations Management Suite (OMS ) blade allows you to configure an OMS resource for your network.
OMS will collect and surface useful metrics and logs from your network, providing the ability to quickly check the
network health or debug issues. The free offering of OMS will fail gracefully once capacity is reached.
Connect to existing OMS Create a new Log Analytics Create new Join existing Create new Log Analytics
instance or join an existing Location
instance
Existing OMS Workspace Id Workspace ID of the existing Choose the pricing tier for Free Standalone Per Node
instance (Visible if Join the new instance. More Info
Existing is selected) OMS at
Service Tier https://azure.microsoft.com/
pricing/details/log-analytics/
(Visible if Join Existing is
selected)
Existing OMS Primary Key The primary key used to

connect to the existing OMS
instance (Visible if Join
Existing is selected)
Deployment regions
Next, under Deployment regions, specify inputs for Number of region(s) to deploy the consortium network
and selection of Azure regions based on the number of regions given. User can deploy in maximum of five regions.
Number of region(s) Number of regions to deploy 1, 2, 3, 4, 5 2

the consortium network
First region First region to deploy the All allowed Azure regions West US
consortium network
Second region Second region to deploy the All allowed Azure regions East US
only when number of
Third region Third region to deploy the All allowed Azure regions Central US
only when number of
Fourth region Fourth region to deploy the All allowed Azure regions East US 2
only when number of
Fifth region Fifth region to deploy the All allowed Azure regions West US 2
only when number of

Next, under Network size and performance specify inputs for the size of the consortium network, such as
number and size of mining nodes and transaction nodes.
Number of mining nodes The number of mining nodes 2 - 15 2

deployed per region
Mining node storage The type of managed disk Standard or Premium Standard
deployed mining nodes.
Mining node virtual machine The virtual machine size Standard A, Standard D1v2
size used for mining nodes. Standard D,
Standard D-v2,
Standard F series,
Standard DS,
and Standard FS
Number of load balanced The number of transaction 1-5 2

transaction nodes nodes to provision as part of
the network.
Transaction node storage The type of managed disk Standard or Premium Standard
deployed transaction nodes.
Transaction node virtual The virtual machine size Standard A, Standard D1v2
machine size used for transaction nodes. Standard D,
Standard D-v2,
Standard F series,
Standard DS,
and Standard FS
Ethereum settings
Next, under Ethereum settings, specify Ethereum-related configuration settings, like the network ID and
Ethereum account password or genesis block.

ConsortiumMember ID The ID associated with each 0 - 255

member participating in the
consortium network used to
configure IP address spaces
to avoid collision.
Member ID should be
unique across different
organizations in the same
network. A unique member
ID is needed even when the
same organization deploys
to multiple regions.
Make note of the value of

this parameter since you will
need to share it with other
joining members.
Ethereum Network ID The network ID for the 5 - 999,999,999 10101010

consortium Ethereum
network being deployed.
Each Ethereum network has
its own Network ID, with 1
being the ID for the public
network. While network
access is restricted for
mining nodes, we still
recommend using a large
number to prevent collisions.
Custom genesis block Option to either Yes/No No

automatically generate a
genesis block or provide a
custom one.
Ethereum Account Password The administrator password 12 or more characters NA

(Custom genesis block = No) used to secure the Ethereum
account imported into each
node. The password must
contain the following: 1
case character, and 1
number.
Ethereum private key The passphrase used to 12 or more characters NA

passphrase (Custom genesis generate the ECC private
block = No) key associated with the
default Ethereum account
that is generated. A pre-
generated private key does
not need to be explicitly
passed in.
Consider a passphrase with

sufficient randomness to
ensure a strong private key
and no overlap with other
consortium members. The
passphrase must contain the
following at a minimum: 1
case character, and 1
number.
Note if two members use

the same passphrase the
accounts generated will be
the same. The same
passphrase is useful if a
single organization is trying
to deploy across regions and
wants to share a single
account (coin base) across all
nodes.
Genesis block(Custom JSON string representing Valid JSON NA

genesis block = Yes) custom genesis block. You
can find more details on the
format of the genesis block
here, under Custom
Networks.
An Ethereum account is still

created when providing a
custom genesis block.
Consider specifying a
prefunded Ethereum
account in the genesis block
to not wait for mining.
Shared Key for Connection A Shared key for connection 12 or more characters NA
between VNET gateways.
Consortium Data URL The URL pointing to the NA

relevant consortium
configuration data provided
by another member's
deployment.
This information is provided

by an already connected
member who has a
deployment. If you deployed
the rest of the network, the
URL is the template
deployment output, named
CONSORTIUM-DATA.
VNet Gateway to Connect to The resource path of the NA

VNet Gateway to which to
connect.
This information is provided
by an already connected
member who has a
deployment. If you deployed
the rest of the network, the
URL is in template
deployment output, named
CONSORTIUM_MEMBER_GA
TEWAY_ID. Note: The same
member's consortium data
URL and VNet Gateway
resource must be used.
Endpoint of Peer information Peer info endpoint provided Valid endpoint of first NA
registrar by another member's member in consortium
deployment
Key of Peer information Peer info primary key Valid primary key of first NA
registrar provided by another member in consortium
member's deployment
Summary
Click through the summary blade to review the inputs specified and to run basic pre-deployment validation.
Review legal and privacy terms and click Purchase to deploy. If the deployment has more than one region, or is for
a consortium network, then this template pre-deploys the necessary VPN gateways to support network
connectivity with other members. Deployment of the gateway can take up to 45 to 50 minutes.
Post deployment sanity checks

Administrator page
Once the deployment has completed successfully and all resources have been provisioned, you can go to the
administrator page to get a view of your blockchain network and sanity check the deployment state. The URL of
the admin page is the DNS name of the load balancer; it is present in the output section of the template
deployment named as ADMIN_SITE.
To find it, select the resource group that was deployed. Then, select Overview, and click on the link immediately
under Deployments that shows the number that succeeded.
The new screen shows deployment history. Select the first deployment resource (For example, microsoft-azure-
blockchain.azure-blockchain-servi...) and look for the Outputs section in the lower half of the page. You`ll see the
URL for the admin page listed in the template deployment output parameter as ADMIN_SITE.
To get to the admin page, copy the ADMIN -SITE output and open it in another tab.
On the admin page, you can get a high-level overview of the topology you deployed by reviewing the Ethereum
Node Status section. It includes all node hostnames, their peer count, and the latest block seen. The peer count for
each node is between the minimum of one less than the total node count and the configured maximum peer count.
Note, that the peer count does not restrict the number of nodes that can be deployed within the network.
Occasionally, you will see the peer count fluctuate and be less than the (total number of nodes - 1). The difference
in the count is not always a sign that the nodes are unhealthy, since forks in the ledger can cause minor changes in
peer count. Finally, you can inspect the latest block seen by each node in the network to determine forks or lags in
the system.
The node status is refreshed every 10 seconds. Reload the page via the browser or Reload button to update the
view.
OMS portal
You can locate your OMS portal either by following the link in the deployment output (OMSPORTALURL ) or by
selecting the OMS resource in your deployed resource group.
The portal will first display high-level network statistics as an overview.
Clicking on the overview will direct you to a portal to view per-node statistics.
Accessing nodes
You can remotely connect to the virtual machines for the transaction nodes via SSH with your provided admin
username and password/SSH key. Since the transaction node VMs do not have their own public IP addresses, you
will need to go through the load balancer and specify the port number. The SSH command to run to access the first
transaction node is listed in the template deployment output parameter as, SSH_TO_FIRST_TX_NODE (for the
sample deployment: ssh -p 4000 gethadmin@leader4vb.eastus.cloudapp.azure.com). To get to additional
transaction nodes, increment the port number by one (For example, the first transaction node is on port 4000).
Since the virtual machines on which the mining nodes run are not externally accessible, you need to go through
one of the transaction nodes. Once you have an SSH session to a transaction node, install your private key on the
transaction node or use your password to start an SSH session into any of the mining nodes.
Note
The hostnames can be obtained from Admin Site or from the Azure portal. In Azure portal, the hostnames of
nodes present in the virtual machine scale set (VMSS ) resource is listed under Instances, which differs from the
actual hostnames. For example, the hostname in Azure portal may look like mn-asdfmv-reg1_0 but the actual
hostname would be like mn-asdfmv-reg.
For example:
AZURE PORTAL HOSTNAME ACTUAL HOSTNAME
mn-ethwvu-reg1_0 mn-ethwvu-reg1000000
Adding a new consortium member

Sharing data
As the first member (or a connected member) of the consortium, you need to provide other members a few pieces
of information so they can join and establish their connection. Specifically:
1. Shared Consortium Configuration Data: There is a set of data that is used to orchestrate the Ethereum
connection between two members. The necessary information, including the genesis block, consortium network
ID, and boot nodes, is written to a file on the transaction nodes of the leader or another deployed member. The
location of this file is listed in the template deployment output parameter named CONSORTIUM -DATA.
2. Peer Info endpoint: The Peer info registrar endpoint to get information of all the nodes already connected to
the Ethereum network from the Leaders or another member's deployment. The DB stores a set of information
regarding each node connected in the network, information such as node's hostname, private IP address etc.
This is the template deployment output parameter named PEER_INFO_ENDPOINT.
3. Peer Info Primary Key: The Peer info registrar Primary key is used to get access to the leader's or other
member's Peer info primary key. This is the template deployment output parameter named
PEER_INFO_PRIMARY_KEY.
4. VNET Gateway: Each member establishes a connection to the entire blockchain network through an
existing member. To connect VNET, you need the resource path to the VNET Gateway of the member to
which you are connecting. This is the template deployment output parameter named
CONSORTIUM_MEMBER_GATEWAY_ID.
5. Shared Key: A pre-established secret between two members of the consortium network that are establishing a
connection. This is an alphanumeric string (between 1 to 128 characters) that has been agreed upon outside the
context of the deployment. (For example, MySharedKeyAbc123)
Acceptance of new member
This step should be done after the joining member has deployed their network successfully. Before a member can
join the network and see transaction traffic, an existing member must perform a final configuration on their VPN
Gateway to accept the connection. This means the Ethereum nodes of the joining member will not run until a
connection is established. This configuration can be done via PowerShell or xPlat CLI. A PowerShell module and
xPlat CLI script are also stored on the transaction node, alongside the consortium data. The script location is the
deployment output parameters named PAIR-GATEWAY -PS -MODULE and PAIR-GATEWAY -AZURE -
CLISCRIPT, respectively.
PowerShell/CLI Setup
Additional information on how to get started with Azure PowerShell cmdlets and Azure xPlat CLI can be found in
Azure documentation.
You will need the latest version of the Azure cmdlets installed locally and a session open. Make sure to log into the
session with your Azure subscription credentials.
PowerShell: Establish Connection
Download the PowerShell module and store it locally. The location of the PowerShell module is specified as the
PAIR-GATEWAY -PS -MODULE template deployment output parameter.
If not already enabled, use the Set-ExecutionPolicy cmdlet for the local session to allow running an unsigned
module.
Set-ExecutionPolicy Unrestricted CurrentUser
Next, login to your Azure Subscription in which you deployed the Leader deployment using
Login-AzureRmAccount
Next, import the module:
Import-Module
Finally, run the function with the appropriate input:
MyGatewayResourceId : Resource path of your Gateway. This is the template deployment output parameter
named CONSORTIUM_MEMBER_GATEWAY_ID.
OtherGatewayResourceId : Resource path of the joining member's gateway. This is provided by the joining
member and is the template deployment output parameter of also named
ConnectionName : A name for you to identify this Gateway connection.
Shared Key : The pre-established secret between the two members of the consortium network that are
establishing a connection.
CreateConnection - MyGatewayResourceId -OtherGatewayResourceId <resource path of the joining member's
gateway> -ConnectionName myConnection -SharedKey "MySharedKeyAbc123"
xPlat CLI: Establish Connection
Download the Azure CLI script and store it locally. The location of the Azure CLI script is specified in the template
deployment parameter named PAIR-GATEWAY -AZURE -CLI -SCRIPT.
Run the script with the appropriate input:
MyGatewayResourceId : Resource path of your Gateway. This is the template deployment output parameter
named CONSORTIUM_MEMBER_GATEWAY_ID.
OtherGatewayResourceId : Resource path of the joining member's gateway. This is provided by the joining
member and is the template deployment parameter of their deployment also named
ConnectionName : A name for you to identify this Gateway connection.
Shared Key : The pre-established secret between the two members of the consortium network that are
establishing a connection.
Location : The Azure region where your gateway resource is deployed.
az network vpn-connection create --name $ConnectionName --resource-group

$MyResourceGroup --vnet-gateway1 $MyGatewayResourceId --shared-key $SharedKey --vnet-
gateway2 $OtherGatewayResourceId --enable-bgp
The architecture will be as follows after you have successfully configured connection between leader and member
deployments.
Fund new member account

Generated genesis block
As the first member, your Ethereum account is funded with one trillion ether if the deployment generates the
genesis block (Custom Genesis Block = No). Other members will have an account that is not pre-funded and must
wait to accumulate Ether as their mining nodes begin to mine blocks. To avoid having new members wait for Ether,
you will need to explicitly fund joining members' Ethereum accounts.
To do so, joining members must provide you with the Ethereum account that is displayed on their admin website.
You can then use your admin website to transfer Ether from your account to their account by entering the account
provided.
Custom genesis block
If a custom genesis block is provided with a specified Ethereum account, you can use MetaMask or another tool to
transfer ether from that specified account to the pre-generated Ethereum account visible in the admin website. For
instructions on how to use MetaMask, see Creating Ethereum Account.
If a custom genesis block is provided without an account or you do not have access to any pre-allocated accounts,
you will need to wait until your mining nodes begin to mine to generate Ether into your account (coin base). How
quickly the funds are generated depends on the difficulty level you specify in the custom genesis block.
Create Ethereum account

To create an additional account, you can use a variety of solutions. One such solution is MetaMask, a Chrome
extension that provides an identity vault and connection to an Ethereum network, public, test, or custom.
MetaMask formulates a transaction to register the account in the network.
This transaction, like any other transaction, will go to one of the transaction nodes, and eventually be mined into a
block as illustrated below.
To install the extension in Chrome, go to Customize and control Google Chrome (overflow button) > More Tools >
Extensions > Get More Extensions, and search for MetaMask.
Once installed, open MetaMask and create a new vault. By default, the vault will be connected to the Morden Test
Network. You will need to change this to connect to the deployed private consortium network, specifically to the
load balancer in front of the transaction nodes. From the template output, retrieve the exposed Ethereum RPC
endpoint at port 8545, named as ETHEREUM-RPC-ENDPOINT , and enter it in custom RPC as shown below.
By creating the vault, you create a wallet containing an account. To create additional accounts, select Switch
Accounts and then the + button.
Initiate initial Ether allocation

Through the administrator page, you can formulate a transaction to transfer Ether from the pre-allocated account
to another Ethereum account. This Ether transfer is a transaction that is sent to the transaction node and mined into
a block as illustrated below.
Via the clipboard icon in the MetaMask wallet, copy the address of the Ethereum account to which you want to
transfer ether and go back to the administrator page. Paste the copied account into the input field to transfer 1000
ether from the pre-allocated Ethereum account to your newly created account. Click Submit and wait for the
transaction to be mined into a block.
Once the transaction is committed into a mined block, the account balance in MetaMask for your account will
reflect the transfer of 1000 Ether.
Transfer of Ether between accounts

At this point, you are ready to execute transactions within your private consortium network. The simplest
transaction is to transfer Ether from one account to another. To formulate such a transaction, you can use
MetaMask once again, transferring money from the first account used above to a second account.
From Wallet 1 in MetaMask, click on send. Copy the address of the second wallet created into Recipient Address
input field and amount of Ether to transfer in the Amount input field. Click Send and accept the transaction.
Once again, when the transaction is mined and committed into a block, the account balances are reflected
accordingly. Note, Wallet 1's balance is deducted more than 15 Ether, since you had to pay a mining fee to process
the transaction.
Next steps
You are now ready to focus on application and smart contract development against your private consortium
blockchain network.
Hyperledger Fabric single member network
You can use the Hyperledger Fabric Consortium solution template to deploy and configure a Hyperledger Fabric
single member (multi-node) network.
After reading this article, you will:
Obtain working knowledge of blockchain, Hyperledger Fabric, and more complicated consortium network
architectures
Learn how to deploy and configure a single-member Hyperledger Fabric consortium network from within the
Azure portal
About blockchain
If you are new to the blockchain community, this is a great opportunity to learn about the technology in an easy
and configurable manner on Azure. Blockchain is the underlying technology behind Bitcoin; however, it is much
more than just an enabler for a virtual currency. It is a composite of existing database, distributed system, and
cryptographic technologies that enables secure multi-party computation with guarantees around immutability,
verifiability, auditability, and resiliency to attack. Different protocols employ different mechanisms to provide these
attributes. Hyperledger Fabric is one such protocol.
Consortium architecture on Azure

This template deploys a topology to help test and simulate production for users within a single organization (single
member). This deployment comprises of a multi-node network in a single region, soon to be expanded to multiple
regions.
The network is comprised of three types of nodes:
1. Member Node: A node running the Fabric membership service that registers and manages members of the
network. This node can eventually be clustered for scalability and high availability, however in this lab, a single
member node will be used.
2. Orderer Nodes: A node running the communication service implementing a delivery guarantee, such as total
order broadcast or atomic transactions.
3. Peer Nodes: A node that commits transactions and maintains the state and a copy of the distributed ledger.
Getting started
To begin, you will need an Azure subscription that can support deploying several virtual machines and standard
storage accounts. If you do not have an Azure subscription, you can create a free Azure account.
By default, most subscription types support a small deployment topology without needing to increase quota. The
smallest possible deployment for one member will need:
5 virtual machines (5 cores)
1 VNet
1 load balancer
1 public IP address
Once you have a subscription, go to the Azure portal. Select +, select Blockchain, and select Hyperledger Fabric
Single Member Blockchain.
Deployment
To start, select the Hyperledger Fabric Single Member Blockchain and click Create. This will open the Basics
blade in the wizard.
The Template Deployment will walk you through configuring the multi-node network. The deployment flow is
divided into three steps: Basics, Network configuration, and Fabric configuration.
Basics
Under the Basics blade, specify values for standard parameters for any deployment, such as subscription, resource
group, and basic virtual machine properties.
PARAMETER NAME DESCRIPTION ALLOWED VALUES DEFAULT VALUE
Resource prefix A string used as a base for 6 characters or less NA

naming the deployed
resources.
VM user name The user name of the 1 - 64 characters azureuser

administrator for each of the
virtual machines deployed
for this member.
Password (Authentication The password for the 12 - 72 characters NA

following: 1 upper case
character, 1 lower case
character, 1 number, and 1
special character.
While all VMs initially have

the same password, you can
change the password after
provisioning.
SSH Key (Authentication The secure shell key used for NA

type = Public Key) remote login.
Restrict access by IP Setting to determine type Yes/No No

address whether client endpoint
access is restricted or not.
Allowed IP address or The IP address or the set of NA

subnet (restrict access by IP addresses that is allowed
IP address = Yes) to access the client endpoint
when access control is
enabled.
Subscription The subscription to which to

deploy.

network.
Location The Azure region to which to

deploy the first member**s
network footprint.

Next, under Network size and performance, specify inputs for the size of the consortium network, such as the
number of membership, orderer, and peer nodes. Choose infrastructure options and your virtual machine size.
Number of Membership The number of nodes that 1 1

Nodes run the membership service.
For additional details on the
membership service, look at
Security & Membership
Services under the
Hyperledger documentation.
This value is currently

restricted to 1 node, but we
plan to support scale out
through clustering in the
next revision.
Number of Orderer The number of nodes that 1 1

Nodes order (organize) transactions
into a block.--> This
statement is wordy and
confusing. For additional
details on the ordering
service, visit the Hyperledger
documentation.
This value is currently

restricted to 1 node.
Number of Peer Nodes Nodes that are owned by 3 3-9

consortium members that
execute transactions and
maintain the state and a
copy of the ledger.
For additional details on the

ordering service, visit the
Hyperledger documentation.
Storage performance The type of storage backing Standard or Premium Standard

each of the deployed nodes.
To learn more about storage,
visit Introduction to
Microsoft Azure Storage and
Premium Storage.
Virtual machine size The virtual machine size Standard A, Standard D1_v2
used for all nodes in the Standard D,
network Standard D-v2,
Standard F series,
Standard DS,
and Standard FS
Fabric specific settings

Finally, under Fabric Settings, specify Fabric-related configuration settings.
Bootstrap User Name The initial authorized user 9 or fewer characters admin
that will be registered with
the member services in the
deployed network.
Bootstrap User Password The administrator password 12 or more characters NA

for Fabric CA used to secure the Fabric CA
account imported into the
Membership node.
The password must contain

one upper case character,
one lower case character,
and one number.
Deploy
In Summary, review the inputs specified and to run basic pre-deployment validation.
Review legal and privacy terms and click Purchase to deploy. Depending on the number of VMs being
provisioned, deployment time can vary from a few minutes to tens of minutes.
Accessing nodes
Once the deployment is finished, an Overview is displayed.
If the screen does not appear automatically (maybe because you moved around the management portal while the
deployment was running), you can always find it in the Resource Groups tab in the left-side navigation bar. Click on
the Resource Group name you entered in step 1 to go to the Overview page.
Overview lists all of the resources that were deployed by the solution template. You can explore them at will, but
from this screen you can also access the output parameters generated by the template. These output parameters
will give you useful information when connecting to your Hyperledger Fabric network.
To access the output parameters, first click on the Deployments tab in the Resource Group blade. The deployment
history is displayed.
From the Deployment History, click on the first deployment in the list to look at the details.
The details screen will show you a summary of the deployment, followed by three useful output parameters:
The API -ENDPOINT can be used once you deploy an application on the network.
The PREFIX , also called deployment prefix , uniquely identifies your resources and your deployment. It will be
used when using the command-line based tools.
The SSH -TO -FIRST -VM gives you a pre-assembled ssh command with all the right parameters required to
connect to the first VM in your network; in the case of Hyperledger Fabric, it will be the Fabric-CA node.
You can remotely connect to the virtual machines for each node via SSH with your provided admin username and
password/SSH key. Since the node VMs do not have their own public IP addresses, you will need to go through
the load balancer and specify the port number. The SSH command to access the first transaction node is the third
template output, **SSH-TO -FIRST-VM (for the sample deployment:
sh -p 3000 azureuser@hlf2racpt.northeurope.cloudapp.azure.com ). To get to additional transaction nodes, increment
the port number by one (For example, the first transaction node is on port 3000, the second is on 3001, the third is
on 3002, etc.).
Next steps
You are now ready to focus on application and chaincode development against your Hyperledger consortium
blockchain network.

Azure Blockchain Workbench

Uploaded by

Copyright:

Available Formats

Azure Blockchain Workbench

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Azure Blockchain Workbench

Uploaded by

Copyright:

Available Formats

What is Azure Blockchain Workbench?

What is Azure Blockchain Workbench?

How does Azure Blockchain Workbench simplify blockchain application development?

How does Azure Blockchain Workbench simplify blockchain application development?

Contents

Azure Blockchain Workbench (public preview)

Create blockchain applications

Manage applications and users

Integrate blockchain with applications

Deploy a blockchain network

Use Active Directory login

Synchronize on-chain data with off-chain storage

Identity and authentication

Gateway service API

Message broker for incoming messages

Message broker for downstream consumers

Transaction builder and signer

Transaction routers and ledgers

Azure SQL database

REST API-based integration

This occurs using the process depicted above, where:

This occurs using the process depicted above, where:

One-way event delivery of a message from an external system to a

This occurs using the process depicted above, where:

This occurs using the process depicted above, where:

The data integration is well known:

The pattern can be implemented where:

Prerequisites for implementing integration patterns using the REST and

Testing External System Integration Flows Prior to Writing Integration

Prepare for deployment

1. Sign in to the Azure portal.

Name Blockchain API

Application type Web app / API

Sign-on URL https://blockchainapi

5. Select Create to register the Azure AD application.

4. Click Save to save the application manifest changes.

Click Select then click Done.

Expires Choose an expiration duration

SETTING TO STORE USE IN DEPLOYMENT

Application ID Azure Active Directory setup > Application ID

Deploy Blockchain Workbench

4. Select Azure Blockchain Workbench.

Password The password is used for connecting to VMs.

SSH Use an RSA public key in the single-line format beginning

Deployment region Specify where to deploy Blockchain Workbench resources.

Resource groups Create a new Resource group by selecting Create new

Location Specify the region you wish to deploy the framework.

7. Select OK to finish the basic setting configuration section.

Application ID Use the Application ID from the Blockchain client app

9. Click OK to finish the Azure AD Parameters configuration section.

Storage performance Choose the preferred VM storage performance for your

For Use existing:

Storage performance Choose the preferred VM storage performance for your

11. Select OK to finish network settings and performance.

Monitoring Choose whether you want to enable Azure Monitor to

13. Click OK to finish the Azure Monitor section.

Blockchain Workbench Web URL

Configuring the Reply URL

7. Select Save to update the client registration.

3. Save the HelloBlockchain.json file.