Tutorial: Use Blockchain Data Manager to send data to Azure Cosmos DB

In this tutorial, you use Blockchain Data Manager for Azure Blockchain Service to record blockchain transaction data in Azure Cosmos DB. Blockchain Data Manager captures, transforms, and delivers blockchain ledger data to Azure Event Grid Topics. From Azure Event Grid, you use an Azure Logic App connector to create documents in an Azure Cosmos DB database. When finished with tutorial, you can explore blockchain transaction data in Azure Cosmos DB Data Explorer.

Screenshot shows blockchain transaction details.

In this tutorial, you:

  • Create a Blockchain Data Manager instance
  • Add a blockchain application to decode transaction properties and events
  • Create an Azure Cosmos DB account and database to store transaction data
  • Create an Azure Logic App to connect an Azure Event Grid Topic to Azure Cosmos DB
  • Send a transaction to a blockchain ledger
  • View the decoded transaction data in Azure Cosmos DB

If you don't have an Azure subscription, create a free account before you begin.

Prerequisites

Create instance

A Blockchain Data Manager instance connects and monitors an Azure Blockchain Service transaction node. An instance captures all raw block and raw transaction data from the transaction node. An outbound connection sends blockchain data to Azure Event Grid. You configure a single outbound connection when you create the instance.

  1. Sign in to the Azure portal.

  2. Go to the Azure Blockchain Service member you created in the prerequisite Quickstart: Create a blockchain member using the Azure portal. Select Blockchain Data Manager.

  3. Select Add.

    Add Blockchain Data Manager

    Enter the following details:

    Setting Example Description
    Name mywatcher Enter a unique name for a connected Blockchain Data Manager.
    Transaction node myblockchainmember Choose the default transaction node of the Azure Blockchain Service member you created in the prerequisite.
    Connection name cosmosdb Enter a unique name of the outbound connection where blockchain transaction data is sent.
    Event grid endpoint myTopic Choose an event grid topic you created in the prerequisite. Note: The Blockchain Data Manager instance and the event grid topic must be in the same subscription.
  4. Select OK.

    It takes less than a minute to create a Blockchain Data Manager instance. After the instance is deployed, it is automatically started. A running Blockchain Data Manager instance captures blockchain events from the transaction node and sends data to event grid.

Add application

Add the helloblockchain blockchain application so that Blockchain Data Manager decodes event and property state. Blockchain Data Manager requires the smart contract ABI and bytecode file to add the application.

Get contract ABI and bytecode

The contract ABI defines the smart contract interfaces. It describes how to interact with the smart contract. You can use the Azure Blockchain Development Kit for Ethereum extension to copy the contract ABI to the clipboard.

  1. In the Visual Studio Code explorer pane, expand the build/contracts folder of the helloblockchain Solidity project you created in the prerequisite Tutorial: Use Visual Studio Code to create, build, and deploy smart contracts.

  2. Right-click the contract metadata JSON file. The file name is the smart contract name followed by the .json extension.

  3. Select Copy Contract ABI.

    Visual Studio Code pane with the Copy Contract ABI selection

    The contract ABI is copied to the clipboard.

  4. Save the abi array as a JSON file. For example, abi.json. You use the file in a later step.

Blockchain Data Manager requires the deployed bytecode for the smart contract. The deployed bytecode is different than the smart contract bytecode. You use the Azure blockchain development kit extension to copy the bytecode to the clipboard.

  1. In the Visual Studio Code explorer pane, expand the build/contracts folder of your Solidity project.

  2. Right-click the contract metadata JSON file. The file name is the smart contract name followed by the .json extension.

  3. Select Copy Transaction Bytecode.

    Visual Studio Code pane with the Copy Transaction Bytecode selection

    The bytecode is copied to the clipboard.

  4. Save the bytecode value as a JSON file. For example, bytecode.json. You use the file in a later step.

The following example shows abi.json and bytecode.json files open in the VS Code editor. Your files should look similar.

Example of abi.json and bytecode.json files

Create contract ABI and bytecode URL

Blockchain Data Manager requires the contract ABI and bytecode files to be accessible by a URL when adding an application. You can use an Azure Storage account to provide a privately accessible URL.

Create storage account

To create a general-purpose v2 storage account in the Azure portal, follow these steps:

  1. On the Azure portal menu, select All services. In the list of resources, type Storage Accounts. As you begin typing, the list filters based on your input. Select Storage Accounts.
  2. On the Storage Accounts window that appears, choose Add.
  3. On the Basics tab, select the subscription in which to create the storage account.
  4. Under the Resource group field, select your desired resource group, or create a new resource group. For more information on Azure resource groups, see Azure Resource Manager overview.
  5. Next, enter a name for your storage account. The name you choose must be unique across Azure. The name also must be between 3 and 24 characters in length, and may include only numbers and lowercase letters.
  6. Select a location for your storage account, or use the default location.
  7. Select a performance tier. The default tier is Standard.
  8. Set the Account kind field to Storage V2 (general-purpose v2).
  9. Specify how the storage account will be replicated. The default replication option is Read-access geo-redundant storage (RA-GRS). For more information about available replication options, see Azure Storage redundancy.
  10. Additional options are available on the Networking, Data protection, Advanced, and Tags tabs. To use Azure Data Lake Storage, choose the Advanced tab, and then set Hierarchical namespace to Enabled. For more information, see Azure Data Lake Storage Gen2 Introduction
  11. Select Review + Create to review your storage account settings and create the account.
  12. Select Create.

The following image shows the settings on the Basics tab for a new storage account:

Screenshot showing how to create a storage account in the Azure portal

Upload contract files

  1. Create a new container for the storage account. Select Containers > Container.

    Create a storage account container

    Setting Description
    Name Name the container. For example, smartcontract
    Public access level Choose Private (no anonymous access)
  2. Select OK to create the container.

  3. Select the container then select Upload.

  4. Choose both JSON files you created in the Get Contract ABI and bytecode section.

    Upload blob

    Select Upload.

Generate URL

For each blob, generate a shared access signature.

  1. Select the ABI JSON blob.

  2. Select Generate SAS

  3. Set desired access signature expiration then select Generate blob SAS token and URL.

    Generate SAS token

  4. Copy the Blob SAS URL and save it for the next section.

  5. Repeat the Generate URL steps for the bytecode JSON blob.

Add helloblockchain application to instance

  1. Select your Blockchain Data Manager instance from the instance list.

  2. Select Blockchain applications.

  3. Select Add.

    Add a blockchain application

    Enter the name of the blockchain application and the smart contract ABI and bytecode URLs.

    Setting Description
    Name Enter a unique name for the blockchain application to track.
    Contract ABI URL path to the Contract ABI file. For more information, see Create contract ABI and bytecode URL.
    Contract Bytecode URL path to bytecode file. For more information, see Create contract ABI and bytecode URL.
  4. Select OK.

    Once the application is created, the application appears in the list of blockchain applications.

    Blockchain application list

You can delete the Azure Storage account or use it to configure more blockchain applications. If you wish to delete the Azure Storage account, you can delete the resource group. Deleting the resource group also deletes the associated storage account, and any other resources associated with the resource group.

Create Azure Cosmos DB

  1. From the Azure portal menu or the Home page, select Create a resource.

  2. On the New page, search for and select Azure Cosmos DB.

  3. On the Azure Cosmos DB page, select Create.

  4. On the Create Azure Cosmos DB Account page, enter the basic settings for the new Azure Cosmos account.

    Setting Value Description
    Subscription Subscription name Select the Azure subscription that you want to use for this Azure Cosmos account.
    Resource Group Resource group name Select a resource group, or select Create new, then enter a unique name for the new resource group.
    Account Name A unique name Enter a name to identify your Azure Cosmos account. Because documents.azure.com is appended to the name that you provide to create your URI, use a unique name.

    The name can only contain lowercase letters, numbers, and the hyphen (-) character. It must be between 3-44 characters in length.
    API The type of account to create Select Core (SQL) to create a document database and query by using SQL syntax.

    The API determines the type of account to create. Azure Cosmos DB provides five APIs: Core (SQL) and MongoDB for document data, Gremlin for graph data, Azure Table, and Cassandra. Currently, you must create a separate account for each API.
    Capacity mode Provisioned throughput or Serverless Select Provisioned throughput to create an account in provisioned throughput mode. Select Serverless to create an account in serverless mode.
    Apply Free Tier Discount Apply or Do not apply With Azure Cosmos DB free tier, you will get the first 400 RU/s and 5 GB of storage for free in an account. Learn more about free tier.
    Location The region closest to your users Select a geographic location to host your Azure Cosmos DB account. Use the location that is closest to your users to give them the fastest access to the data.
    Account Type Production or Non-Production Select Production if the account will be used for a production workload. Select Non-Production if the account will be used for non-production, e.g. development, testing, QA, or staging. This is an Azure resource tag setting that tunes the Portal experience but does not affect the underlying Azure Cosmos DB account. You can change this value anytime.

    Note

    You can have up to one free tier Azure Cosmos DB account per Azure subscription and must opt-in when creating the account. If you do not see the option to apply the free tier discount, this means another account in the subscription has already been enabled with free tier.

    Note

    The following options are not available if you select Serverless as the Capacity mode:

    • Apply Free Tier Discount
    • Geo-redundancy
    • Multi-region Writes

    The new account page for Azure Cosmos DB

  5. Select Review + create. You can skip the Network and Tags sections.

  6. Review the account settings, and then select Create. It takes a few minutes to create the account. Wait for the portal page to display Your deployment is complete.

    The Azure portal Notifications pane

  7. Select Go to resource to go to the Azure Cosmos DB account page.

    The Azure Cosmos DB account page

Add a database and container

You can use the Data Explorer in the Azure portal to create a database and container.

  1. Select Data Explorer from the left navigation on your Azure Cosmos DB account page, and then select New Container.

  2. In the Add container pane, enter the settings for the new container.

    Add container settings

    Setting Description
    Database ID Enter blockchain-data as the name for the new database.
    Throughput Leave the throughput at 400 request units per second (RU/s). If you want to reduce latency, you can scale up the throughput later.
    Container ID Enter Messages as the name for your new container.
    Partition key Use /MessageType as the partition key.
  3. Select OK. The Data Explorer displays the new database and the container that you created.

Create Logic App

Azure Logic Apps helps you schedule and automate business processes and workflows when you need to integrate systems and services. You can use a logic app to connect Event Grid to Azure Cosmos DB.

  1. In the Azure portal, select Create a resource > Integration > Logic App.

  2. Provide details on where to create your logic app. After you're done, select Create.

    For more information on creating logic apps, see Create automated workflows with Azure Logic Apps.

  3. After Azure deploys your app, select your logic app resource.

  4. In the Logic Apps Designer, under Templates, select Blank Logic App.

Add Event Grid trigger

Every logic app must start with a trigger, which fires when a specific event happens or when a specific condition is met. Each time the trigger fires, the Logic Apps engine creates a logic app instance that starts and runs your workflow. Use an Azure Event Grid trigger to sends blockchain transaction data from Event Grid to Cosmos DB.

  1. In the Logic Apps Designer, search for and select the Azure Event Grid connector.

  2. From the Triggers tab, select When a resource event occurs.

  3. Create an API connection to your Event Grid Topic.

    Event grid trigger settings

    Setting Description
    Subscription Choose the subscription that contains the Event Grid Topic.
    Resource Type Choose Microsoft.EventGrid.Topics.
    Resource Name Choose the name of the Event Grid Topic where Blockchain Data Manager is sending transaction data messages.

Add Cosmos DB action

Add an action to create a document in Cosmos DB for each transaction. Use the transaction message type as the partition key to categorize the messages.

  1. Select New step.

  2. On Choose an action, search for Azure Cosmos DB.

  3. Choose Azure Cosmos DB > Actions > Create or update document.

  4. Create an API connection to your Cosmos DB database.

    Cosmos DB connection settings

    Setting Description
    Connection Name Choose the subscription that contains the Event Grid Topic.
    DocumentDB Account Choose the DocumentDB account you created in the Create Azure Cosmos DB account section.
  5. Enter the Database ID and Collection ID for your Azure Cosmos DB that you created previously in the Add a database and container section.

  6. Select the Document setting. In the Add dynamic content pop-out, select Expression and copy and paste the following expression:

    addProperty(triggerBody()?['data'], 'id', utcNow())
    

    The expression gets the data portion of the message and sets the ID to a timestamp value.

  7. Select Add new parameter and choose Partition key value.

  8. Set the Partition key value to "@{triggerBody()['data']['MessageType']}". The value must be surrounded by double quotes.

    Logic Apps Designer with Cosmos DB settings

    The value sets the partition key to the transaction message type.

  9. Select Save.

The logic app monitors the Event Grid Topic. When a new transaction message is sent from Blockchain Data Manager, the logic app creates a document in Cosmos DB.

Send a transaction

Next, send a transaction to the blockchain ledger to test what you created. Use the HelloBlockchain contract's SendRequest function you created in the prerequisite Tutorial: Use Visual Studio Code to create, build, and deploy smart contracts.

  1. Use the Azure Blockchain Development Kit smart contract interaction page to call the SendRequest function. Right-click HelloBlockchain.sol and choose Show Smart Contract Interaction Page from the menu.

    Choose Show Smart Contract Interaction Page from menu

  2. Choose SendRequest contract action and enter Hello, Blockchain! for the requestMessage parameter. Select Execute to call the SendRequest function via a transaction.

    Execute SendRequest action

The SendRequest function sets the RequestMessage and State fields. The current state for RequestMessage is the argument you passed Hello, Blockchain. The State field value remains Request.

View transaction data

Now that you have connected your Blockchain Data Manager to Azure Cosmos DB, you can view the blockchain transaction messages in Cosmos DB Data Explorer.

  1. Go to the Cosmos DB Data Explorer view. For example, cosmosdb-blockchain > Data Explorer > blockchain-data > Messages > Items.

    Cosmos DB Data Explorer

    Data Explorer lists the blockchain data messages that were created in the Cosmos DB database.

  2. Browse through the messages by selecting item ID and find the message with the matching transaction hash.

    Screenshot shows the blockchain transaction details of a selected item.

    The raw transaction message contains detail about the transaction. However, the property information is encrypted.

    Since you added the HelloBlockchain smart contract to the Blockchain Data Manager instance, a ContractProperties message type is also sent that contains decoded property information.

  3. Find the ContractProperties message for the transaction. It should be the next message in the list.

    Blockchain transaction detail

    The DecodedProperties array contains the properties of the transaction.

Congratulations! You have successfully created a transaction message explorer using Blockchain Data Manager and Azure Cosmos DB.

Clean up resources

When no longer needed, you can delete the resources and resource groups you used for this tutorial. To delete a 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

Learn more about integrating with blockchain ledgers.