The reference implementation contained in this repository complements the following article.

How to run our solution

Requirements

To run our solution you will need:

Azure subscription (a free trial is available)
VSCode
PowerShell
Azure CLI
Node.js
Truffle
A Mnemonic passphrase

In VS Code, we used the following required extensions:

Steps to reproduce our solution

Clone the repo
Create essential Azure Resources
Deploy Azure Functions and setup settings
Deploy Smart Contracts
Import Function Apps into Azure API Management

Optional, if you want to get email notifications:

Deploy Logic Apps
Create Data Manager Application

1. Cloning the repo

To clone the repo, just run this snippet in a directory of your preference:

git clone git@github.com:southworks/azure-blockchain-supply-chain.git

2. Create essential Azure Resources

First, make sure that you have Azure CLI installed.

Then follow these steps:

Login into your Azure account:
```
az login
```
Create the Resource Group where all services will be deployed:
```
az group create -l <region> -n <resourceGroupName>
```
E.g.: az group create -l centralus -n supplychain

NOTE: Use only lowercase letters in the RG name and avoid hyphens (-) or undercores (_). The RG name is later used to name some services.
Create the basic Azure services for our solution. You need to run the following line that will run an ARM Template. If you want to customize parameters, edit those in the template.core.parameters.json file. This ARM Template will create three Function Apps with their storage and App Insights, and it will create an Azure Blockchain Service instance with a blockchain, a CosmosDB collection, an Event Grid Topic and an API Management instance:
```
az deployment group create --resource-group <resourceGroupName> --template-file ./arm/template.core.json --verbose
```
NOTE: Creation of Azure API Management and Cosmos DB could take ~20 minutes.

3. Deploy Azure Functions and setup settings

Once your resources are created, deploy the Azure Functions projects.

To deploy Azure Functions follow these steps:

Open each Azure Function project in a separate VS Code instance (consumer, retailer and stock).
Press F1 and find Azure Functions: Deploy to Function App.

Then, go to each Function App in Azure Portal and update PRIVATE_KEY and RPC_ENDPOINT settings (see documentation, also check these links about how to get the private key and rpc endpoint values).

To retrieve the RPC Endpoint of the blockchain, the mnemonic passphrase and your private key follow these guides:

Get the RPC Endpoint

Using the VSCode extension "Blockchain Development Kit for Ethereum":

Under Blockchain Networks in Visual Studio Code, click connect to a network and select the network you want to use.
Next click on Azure Blockchain, you will then get the member's transaction node.
Select Copy RPC Endpoint Address.
The RPC endpoint is copied to your clipboard.

How to create a mnemonic passphrase

To get a mnemonic passphrase follow these steps:

Go to https://iancoleman.io/bip39/ or any other generator of your preference and generate a twelve words passphrase.
Create a mnemonic.env file in root folder of this project.
Paste the mnemonic passphrase inside mnemonic.env and save it.

Get the private key

In the root folder of this project, run:
```
node ./getPrivateKey.js
```
Copy the private key from the console

4. Deploy Smart Contracts

To deploy the smart contracts we will need:

Replace your RPC Endpoint in .env .template and rename it to .env.
Also, you will need to have an account with the mnemonic (check our guide about how to get a menmonic) in the file mnemonic.env. The mnemonic is a twelve-word seed for your private key. It can be generated automatically by Blockchain Development Kit for Ethereum.

In the truffle-config.js file is the network setup, which is something like that:

abs_consortium: {
    network_id: "*",
    gasPrice: 0,
    provider: new HDWalletProvider(fs.readFileSync(path.resolve(__dirname, './mnemonic.env'), 'utf-8'), RPC_PATH)
}

Then you have to run a migration. This migration will build and deploy the smart contract to the parametrized network (here is truffle documentation):

truffle migrate --network abs_consortium

If you have any issues running the migration, try adding --reset parameter to the migrate. It will run migrations from beginning.

5. Import Function Apps into Azure API Management

Go to API Management in Azure Portal and import Function Apps (see documentation or our below) under the path retailer, stock and consumer.

To import our Function Apps into API Management through the Azure Portal. There is a guide available in the official Microsoft documentation.

Go to API Management and click "APIs" on the left pannel. Then, click "Add API" and select "Function App" from the options under "Add new API".
A dialog box will appear, where you can choose a Function App. Select "Browse" to find the available ones.
Under "Function App", click "Configure required settings".
The following screen shows the available Function Apps. Select the one you want to import. In this example, we're selecting "retailer".
A list of all the functions from the chosen Function App will be displayed. By default, they are all selected. Click "Select" to continue.
A dialog box will be displayed, where you can choose to change the display name, name and API URL suffix. When you're done, click "Create". The Function App will be imported as an API to API Management.
Finally, in the "APIs" tab from step 1, click the imported API, select any of its functions and select the "Test" tab on the right. Scroll to the bottom and find the data under "HTTP request". You will need the Ocp-Apim-Subscription-Key to call the API's endpoints from a REST client.

6. [Optional] Deploy Logic Apps

To include Logic Apps to log transactions and get notification emails when an order is completed, follow these steps:

Replace the connection string for CosmosDB in template.logicapps.parameters.json

Deploy the logic apps running the ARM Template:

az deployment group create --resource-group <resourceGroupName> --template-file ./arm/template.logicapps.json

Run this PowerShell script to authorize the api connectors:

./arm/api_connection_authorization.ps1 -ResourceGroupName <resourceGroupName> -ConnectionName event-grid-connection
./arm/api_connection_authorization.ps1 -ResourceGroupName <resourceGroupName> -ConnectionName office365-connection

7. Configure Data Manager Application

Finally, you will need to configure Data Manager to connect the Smart Contracts with Azure. To configure that, follow this guide

Build

If you want to build smart contracts or Azure Functions to check if everything is ok, check these guides:

How to build smart contracts

To build the smart contracts there are two different options with the same result:

Using Blockchain Develop Kit for Ethereum, right click on each contract and click on Build Contract. There is the command pallete option too: open it pressing F1 or Ctrl+P, find and execute Blockchain: Build Contracts
Using truffle: run a truffle compile in the console.

How to build Azure Functions

Each Azure Function project will require a local.settings.json file with this settings:

  "Values": {
    "AzureWebJobsStorage": "",
    "FUNCTIONS_WORKER_RUNTIME": "dotnet",
    "RPC_ENDPOINT": "",
    "PRIVATE_KEY": "",
    "COSMOS_DB_URI": "<COSMOS DB URI>",
    "COSMOS_DB_PRIMARY_KEY": "<COSMOS DB PRIMARY KEY>",
    "DATABASE_ID": "<COSMOS DB SERVICE NAME>",
    "USER_CONTAINER_ID": "consumer",
    "WALLET_CONTAINER_ID": "wallets"
  }

You can get the RPC Endpoint from the transaction nodes, the private key will be generated from your mnemonic (through running getPrivateKey.js).