Making your First Mercata App
Introduction
This is a guide for new developers or business users looking to build their first application on the STRATO Mercata network. This guides uses the Asset Framework, which is a tool built by BlockApps to help jumpstart and shorten the time of app development by using tried and true application development patterns, found to work well on the Mercata Blockchain.
For more information on The Asset Framework, visit its dedicated Documentation homepage or visit its Github Repository.
This guides goal is to help you build an application that achieves the following:
- Define a data model for your application, in order to understand how your asset's attributes are represented on the blockchain.
- Build an App in a Private Dapp Realm, so all of its data is kept private between the app's members
- Create and update the data of a private Asset, tracked on the Mercata Network
- Transfer the ownership of an Asset to another user on the Mercata network
- View the audit log of an Asset's attributes overtime
Defining your Data Model
Project Overview
On the first sheet, "Project Overview", enter your project name in the respective cell underneath the "Project Name" cell. Fill in the other values as necessary.
Assets
The Asset Framework uses a spreadsheet to define the project's assets and configuration. You can download an example data model here, and use that to fill in your own custom asset names and attributes.
First think of a 2 or 3 assets that you want to track in your application, some ideas might be:
- Cars & Licenses
- Properties & their Deeds
- Software Licenses
- Commodities (oil, grain, coffee, etc.)
Get creative with your idea! It can really be any thing that exists in the real world, either physically or digitally. These will be the ultimate entities tracked and represented on the STRATO Mercata Network.
Asset Attributes
Once you have determined what your application's assets will be, you need to determine what the attributes are of each one. For example, a Software license might have some of the following attributes:
| Software License | ID | Software Name | Version | Release Date | Publisher | Owner |
|---|---|---|---|---|---|---|
| - | text | text | text | datetime | string | string |
For this example, it is fairly straightforward to determine the correct attributes that need to be recorded for the asset, however, it might take a longer time to discover every data point that must be tracked. Note that in the Software License model, we need to track its owner. However in the data model spreadsheet, we do not have to define an asset owner, because the Asset Framework automatically tracks an Asset's owner.
Once you have every attribute for each asset, on the "Assets" sheet, fill them in in the "Asset Attribute" column of the spreadsheet, with the corresponding asset that it belongs to in the "Asset Name" column. In the "Asset Attribute Type" column, enter the data type that this attribute has. The spreadsheet will display a dropdown menu for the possible types.
If your asset contains a foreign reference to another asset or assets, (asset attribute type is "reference"), then fill in the "Reference to" column with the name(s) of those assets.
For now, you can ignore the "Unit of Measure", "Description", and "Sample Value" columns.
So our final data model spreadsheet might look like this:
| Asset Name | Asset Attribute | Unit of Measure | Description | Sample Value | Asset Attribute Type | Reference to |
|---|---|---|---|---|---|---|
| Software License | ID | - | - | text | - | - |
| Software License | Software Name | - | - | text | - | - |
| Software License | Version | - | - | text | - | - |
| Software License | Release Date | - | - | datetime | - | - |
| Software License | Publisher | - | - | text | - | - |
You are now done creating you application's data model, and may move on to generating the application.
Generating your Project
Setup
To generate your app with the Asset Framework, several things are needed:
- Asset Framework tool downloaded onto your computer
- Github Repository
- Click "Code" in top right, then "Download Zip"
- Alternatively clone the repo from your computer's command line using
git.
- Completed data model spreadsheet (see above)
- Node JS
- Yarn 🐈
- Strato Mercata membership and accessible node
- Docker
Generation
Once you have the previous things setup, follow these steps to generate your app:
1. Install Code-Generation Tools
From a command line, navigate to the downloaded asset-framework directory.
Enter
yarn install
to install the necessary third-party tools for the Asset Framework to generate your project.
2. Copy your completed data model spreadsheet into the asset-framework directory.
3. Setup your Mercata login credentials
Within the asset-framework directory, there is a backend/ sub-directory. Navigate there and create a new file named ".env".
Within that file, write the following values:
GLOBAL_ADMIN_NAME=<your-mercata-username>
GLOBAL_ADMIN_PASSWORD=<your-mercata-password>
4. Generate your App
From the command line in the top-level asset-framework directory run the following command:
yarn generate <data-model-filename.xlsx> <target/directory>
This will start the generation of your app using your asset data model. The expected runtime to fully generate your project is ~90-120 seconds. Once this has completed, your app has been successfully created and installed!
Reference:
<data-model-filename>.xlsx- The name of your data model spreadsheet file located in the asset-framework directory
- Example:
data-model.xlsx <target/directory>- The directory where the generated project will be created, relative to the asset-framework directory
- Example:
../my-app
Start the App
Now that the app is created, we just need to start it up so that you can start tracking your assets right on the Mercata Network.
Deploy your App to Mercata
To get your app started, you first need to deploy the core app smart contracts and asset smart contracts into a new Private Dapp Realm, just for this application. This will put your application's asset data model onto the blockchain so that you can create. read, and update actual instances of the assets on the network in the future.
From the command line, navigate to the directory of the generated project (my-app/).
Run the command
yarn deploy
Once complete, your Private Dapp Realm will have been created and your app will be ready for use on the STRATO Mercata network.
Start your App's Programs
To actively use and view the application, you must start the necessary programs to make their services accessible.
1. Start Proxy Server
Navigate to the nginx-docker directory of your new project and run:
Linux:
HOST_IP=172.17.0.1 docker-compose up -d
Mac OS:
HOST_IP=docker.for.mac.localhost docker-compose up -d
2. Start the Application's API
Navigate to the backend directory of your new project and run:
yarn start
3. Start the Application's Interface
Keeping the current command line window open, create a new command line window or tab.
In the new window, navigate to the project's ui directory and run the following command:
yarn develop
View the application at: https://localhost and sign-in with your Mercata account.
Create your First Asset
Now that the application is up and running, you can now create, view, and update assets.
To create your first asset in the app, visit the application's homepage on https://localhost.
You will be presented with a Mercata login page, here sign in with your Mercata username and password.
This will now redirect you to the app's homepage.
On the left side, there is a navigation menu, which shows each asset type in your app. By default you will view the first asset type defined in the data model.
Click on an asset type to manage that type of asset.
It will display a table of the assets in the app that have access to. At first this will be empty since you have not created any assets yet.
In the top corner, click the "Create
The table will update to display your newly created asset. You may select it in the table to view the asset's attributes in further detail.
Update your Asset
Now that you have created your first asset, lets walkthrough the steps of updating the attributes of an asset.
In the asset table, select the asset you just created with the checkbox on the left side of the table. Now In the top top corner, select the "Edit" button.
This will present a form for each attribute of the asset, fill in any of the fields with values to set for this asset.
Once you submit this form, you will see a new entry at the bottom of this page showing the asset's audit log. This is the trail of updates on this particular asset overtime.
So now that you have updated some data points on this asset, you will see an entry displaying the first values for the asset when it was created, as well as the entry for the most current values after you made the update.
Transfer Asset Ownership
The Asset Framework uses the global list of Verfied Identities to allow you to transfer assets to any other user on Mercata.
To do this, select an asset on the Asset's table.
In the top right corner, select the "Transfer Ownership" button.
This will present you with a menu to select the user you want to transfer ownership to. Users are identified by their Common Name and Organization in their Identity Certificate. Once the selection is confirmed, that user will now be the owner of the asset, and be able view and update it in the app.
You can confirm this is the case by viewing the asset's details, and noticing the new values for the asset's owner attributes. You can also view the change of hands by seeing the asset's aubit log, and seeing the old owner (your Mercata address) and the new owner (their Mercata address).
You have now completed building your first application on STRATO Mercata using the Asset Framework! You can use this application as a starting point to create your very own, full fledged Mercata app.