Mercata Quickstart Guide
This page helps point new users to some of STRATO Mercata's most important and fundamental features. On this page you will learn how to:
- View your On-chain Identity
- Create a Private Shard
- Manage Private Shard Members
- Write a Smart Contract for the Blockchain
- Call a function on a contract
- View a contract's data
The goal of this guide is not to walk through every step along the way, but to guide users along the path to better understand the full capabilities of the STRATO Mercata Network.
This guide assumes you already have a registered account on STRATO Mercata, if you do not, please register at https://login.blockapps.net. You will not be able to interact with the Network until you have a valid account.
As a reminder, all requests to the STRATO API are authenticated through a configured OAuth provider for the Node to which you are connecting. For information on OAuth Providers in STRATO, please see the OAuth Provider Documentation. Each Mercata node has its own URL, like node1.mercata.blockapps.net, this is the URL you must make all API calls to, and is what should be replaced in all endpoint examples that have <strato_address> in it.
View your Identity
Your identity on Mercata is one of the most important things you have on The Network. It is what associates your virtual, digital blockchain account with real world credentials. Verified Identities enable collaboration between trusted partners. Without a real-world identity, you would only be identified by a blockchain address, a not-very-helpful string of numbers and letters.
Mercata Homepage
Your identity is accessible on the Mercata homepage by viewing the "Accounts" tab on the left menu. From there, scroll through the list or search for your username in the search bar. Once you have found yourself, select your card to view more information, such as your blockchain address or number of total public transactions made (nonce).
API Call
You can also access your identity directly through the STRATO API. To do this, make a request to the following endpoint on Mercata:
GET https://<strato_address>/cirrus/search/Certificate?commonName=<your-name-here>
In this request you are accessing the on-chain identity database and searching for identities with names that match your own. Make sure to replace <your-name-here> with the name registered in your Mercata Identity.
If you are unsure about what exactly your name is on Mercata, follow these steps below.
1. Retrieve your STRATO blockchain address
This can be done by making a request to the STRATO /key endpoint:
GET https://<strato_address>/strato/v2.3/key
This will return to you your STRATO address:
{
"status": "Success",
"address": "cafeb0ba"
}
2. Query the Identity database for your identity based on your blockchain address
GET https://<strato_address>/cirrus/search/Certificate?userAddress=<your-address-here>
Please see the X.509 Identity Documentation for more information on identity in STRATO Mercata.
Create a Private Shard
A private shard is a separate private space on which users can manage data on the blockchain. A private shard has its own distinct list of members, which are individual nodes on the Mercata network. Only the members of a shard can access the data on the shard. Private shards are typically used as launch pads for Distributed Applications, allowing users to selectively share application data with particular members. Private shard data is anonymously hashed and recorded on the Mercata main chain, allowing it to maintain the verifiability of the blockchain while still keeping it private amongst participants. It is also traceable and auditable amongst the shard members.
Please visit the Private Shard Documentation for more information.
In the example, we will walkthrough creating a private shard that represents a very simple app - a ___ factory/manager.
Mercata Homepage
Navigate to the "Chains" tab on the left menu. Once there, select the "Create chain" button in the top right. This will present you with a form for the details of your new shard.
For the shard label, provide something like "
For the contract, select "AutoApprove". This contract will be used as the initial "Governance Contract" of the shard, and is what governs the members of the shard. For the AutoApprove option, this allows any member to be instantly added to a shard once added by another member.
Select "SolidVM" for the VM. This option allows you to choose how the contract will be interpreted and run during its execution. It is always strongly recommended to use "SolidVM", BlockApps custom built in-house Solditity Interpreter. (See Full SolidVM Documentation.)
You will not need to provide any arguments.
For members, you do not need to provide anything, since you, the creator of the shard will be a member by default. However, if you wish to share this test shard with another organization on Mercata, you can do so here by adding that org's info here in the shard's members. Otherwise you will have to add members after the shard is created.
Finally click "Create chain", and the private shard will have been created!
You can view this shard by navigating to the "Chains" tab on the left menu.
Select it in the list or search for it by the label you gave it.
Upon selection, you can view its chainId and current members by their X.509 Identity. Copy the chainId and save it somewhere for later.
In the top right, open the dropdown menu that currently shows "Main Chain" and scroll to select your newly created private shard. Once you have found it, select it. This will allow all your operations done on the STRATO Mercata Management Dashboard to be done on this shard. So for this section, we will be creating a Property Deed contract on your private shard.
API Call
To make a new private chard directly from an API call to STRATO Mercata, use this endpoint:
POST https://<strato_address>/bloc/v2.2/chain
Add the following details to your request body:
{
"args": {},
"members": [
{
"orgUnit": "",
"commonName": "",
"orgName": "<your-org-name>"
},
],
"balances": [],
"contract": "AutoApprove",
"src": "<AutoApprove-contract-src>",
"metadata": {
"VM": "SolidVM"
},
"label": "<your-name>TestShard"
}
Copy and paste the following "AutoApprove" contract into the "src" field of the request body. This is the same contract that is used on the Mercata homepage.
contract AutoApprove {
event OrgAdded (string orgName);
event OrgUnitAdded (string orgName, string orgUnit);
event CommonNameAdded (string orgName, string orgUnit, string commonName);
event OrgRemoved (string orgName);
event OrgUnitRemoved (string orgName, string orgUnit);
event CommonNameRemoved (string orgName, string orgUnit, string commonName);
constructor() {}
function addOrg(string orgName) {
emit OrgAdded(orgName);
}
function addOrgUnit(string orgName, string orgUnit) {
emit OrgUnitAdded(orgName, orgUnit);
}
function addCommonName(string orgName, string orgUnit, string commonName) {
emit CommonNameAdded(orgName, orgUnit, commonName);
}
function removeOrg(string orgName) {
emit OrgRemoved(orgName);
}
function removeOrgUnit(string orgName, string orgUnit) {
emit OrgUnitRemoved(orgName, orgUnit);
}
function removeCommonName(string orgName, string orgUnit, string commonName) {
emit CommonNameRemoved(orgName, orgUnit, commonName);
}
}
Make sure to save the returned chainId from the response for later.
Create a Contract
In the previous section, you created a private shard that was initialized with a Governance contract provided to you. In practice, that contract does not provide any real value or data on-chain. It only serves to control the members of the shard.
In this section, we will go through the basic concepts and steps of putting meaningful smart contracts onto the STRATO Mercata Network. We will walkthrough designing a simple smart contract and posting it to your newly created private shard, so that it will only be accessible to the members of that shard.
Smart Contract Design
At its core, a smart contract is a piece of code that describes a set of data fields (state variables) and the rules (functions) that govern the updating of that data. Smart contracts have names that represent what the contract describes - on Mercata these are typically real world assets like a Car, Property Deed, etc. These contracts make "objects" that reside at particular addresses on the blockchain. Private shards create a new private address space for those contracts to live on.
For this guide, we will use the following contract to represent a Property Deed:
contract Deed {
// the blockchain address of the deed owner
address public owner;
// the location of this property
string public propertyAddress;
// the area in acreage of this property
uint public acreage;
// the date the current owner acquired the property
uint public dateAcquired;
constructor(string _propertyAddress, uint _acreage) {
// set the owner to user that created this deed
owner = tx.origin;
// set the property address and acreage to the provided values
propertyAddress = _propertyAddress;
acreage = _acreage;
// set the date acquired to the current time this contract was created
dateAcquired = block.timestamp;
}
// create a way to transfer the deed to a new owner (user on the network)
function transferDeed(address _newOwner) {
// ensure the person initiating the transfer is the current owner
require(tx.origin == owner, "Only the current owner can transfer ownership");
owner = _newOwner;
dateAcquired = block.timestamp;
}
function updateAcreage(uint _acreage) {
require(tx.origin == owner, "Only the current owner can update fields");
acreage = _acreage;
}
function updatePropertyAddress(string _propertyAddress) {
require(tx.origin == owner, "Only the current owner can update fields");
propertyAddress = _propertyAddress;
}
}
The Deed contract stores 4 data fields, declared at the top of the code: owner, propertyAddress, acreage, and dateAcquired. In a real application, this contract might include many more fields as necessary to more closely match a real world property deed. These fields are initially set in the constructor, with the owner and dateAcquired being set automatically without any manual user input. This is done to prevent any possible human error when providing these values.
Then we provide several ways to update the data of this deed - the most notable one is through the transferDeed function. This function allows the current owner to provide the blockchain address of another user, and give them control of this Deed. Notice again the dateAcquired field is automatically updated when this function is called. The next 2 update functions provide a simple way for the owner to update the data of this deed in case there was an error when initially inputting them.
When this contract is uploaded, a new instance of this contract is created on the blockchain with a new unique address identifying "where" it is on the chain. This can be used later to call its functions, reference it from other contracts, or retrieve this specific instance's data.
Mercata Homepage
Navigate to the "Contract Editor" tab on the left menu.
Copy the Deed contract from above, and copy it into the text editor.
In the top right, select "Compile" and then "SolidVM" this will check the provided contract for any syntax errors before actually uploading it to the network.
Select the "Create Contract" button in the top right. This will present you with options for creating your Deed contract.
In the Shard input, select your newly created private shard by its label you gave it.
Then select the singular Shard ID from the next dropdown. Note that if there are multiple shards with the same label, you will have to select the shard ID of the correct one, determined by finding the shardId from the Shards page.
You will not need to provide any data for "Username" or "Address".
For Contracts, since your contract source code only contains one type of contract, you do not need to change the default value of "Deed". If there were multiple types of contract types defined in one contract upload, you would have to choose which of these contracts you actually want to instantiate and create on the blockchain.
You may also ignore "VM" and "History".
Finally the Args, you must provide the initial values for the contract's data fields as defined in the Deed's constructor. Provide some simple values for both the propertyAddress and the acreage. Since this is just a test contract, the values do not need to represent any type of real property. Make sure to provide a text value like "123 Main St." for the propertyAddress and a number like "2" for the acreage. (Do not include quotes.)
Now you have all the required options filled-in for creating your first contract, and may click the "Create Contract" button.
Your contract will be created on your private shard and is viewable through the "Contracts" tab on the left menu. (See section for viewing contract details.)
API Call
You may create a new contract directly through the STRATO API by using the following endpoint:
POST https://<strato_address>/strato/v2.3/transaction?resolve=true
Provide the following in the request body:
{
"txs": [
{
"payload": {
"contract": "Deed",
"src": "<Deed-contract-source>",
"args": {
"_storedData": "123 Main St.",
"_acreage": 2
},
"chainid": "<your-shard-id>"
},
"type": "CONTRACT"
}
],
"txParams": {
"gasLimit": 32100000000,
"gasPrice": 1
}
}
Remember to replace the "src" value for the Deed contract source code as referenced above, and the chainid with the shardId of your new shard.
This will return to you an address of the newly created Deed contract in the data.contents.address property. Save this somewhere for later.
For more information on creating contracts or SolidVM/Solidity Programming, see the SolidVM Documentation.
For more information on creating real asset contracts on the Mercata network, see the Assets Documentation.
Call a Contract's Function
We will now modify the data of the contract we just created by calling one of its functions. Both a contract creation and function call are transactions on the STRATO Mercata blockchain. Since every action on the blockchain is signed by its sender and verified by the network, all parties can be assured that the sender of the transaction is who they say they are, and the action was not modified along the way.
The Deed contract has the transferDeed, updateAcreage, and updatePropertyAddress functions to perform the same actions that they describe. Think of a function as a verb associated with the data of the contract instance, typically analogous to a real world action done on that type of object. We are transferring the deed as a whole, or updating the other individual fields.
Mercata Homepage
Navigate to the "Contracts" tab on the left menu.
In the top right dropdown menu, select your newly created private shard based on the label you gave it. This allows you to view and interact with contracts on this shard.
You will see a list of names of contracts on this shard, including the AutoApprove contract used to create the shard. On the Deed contract select the "Show Contracts" button and it will expand to show you all the created instances of the Deed contract. Since we have only created one Deed on the shard, there will only be one entry. Select this entry and on the right side of the page you will shown a list of the current state of this contract instance and the available functions that you can call.
On the "updateAcreage" section, select "Call Method". This will present you with the form to provide the values for the selected function.
For Shard and Shard ID, select your private shard's label and corresponding shardId.
For Parameters, provide a new value for this Deed's acreage.
Click "Call Method" and the Deed's acreage will now have the new value you provided. This will be immediately reflected in the contract's state once you close the pop-up.
API Call
You may create a new contract directly through the STRATO API by using the following endpoint:
POST https://<strato_address>/strato/v2.3/transaction?resolve=true
Within the request body, provide the following data:
{
"txs": [
{
"payload": {
"contractName": "Deed",
"contractAddress": "<your-Deed-contract-address>",
"method": "updateAcreage",
"args": {
"_acreage": 5
},
"chainid": "<your-shard-id>"
},
"type": "FUNCTION"
}
],
"txParams": {
"gasLimit": 32100000000,
"gasPrice": 1
}
}
View Contract Data
Now that you have created some data on the Mercata Network yourself, lets view it in an easy to read, tabular format. This is done through STRATO Mercata's Cirrus API. Cirrus is a service of Mercata that allows contract data to be indexed into read-only SQL tables, making their data rapidly and easily accessible. You can view both the current data held in a contract, as well as the historical log of each update that occured on a contract.
You will need to know the address of your newly created Deed contract and the name of the organization registered with your Mercata account.
Current Data
Make the following request to the STRATO API:
GET https://<strato_address>/cirrus/search/<your-organization>-Deed?address=eq.<your-contract-address>&chainId=eq.<your-shard-id>
Notice in this request the 2 query parameters of address and chainId, each one of these filters the results from the Deed SQL table into the final response based on the column values matching the provided values, just like this equivalent SQL query:
SELECT * from "<your-organization>-Deed" WHERE address = '<your-contract-address>' AND chainId = '<your-shard-id>'
This will return to you a JSON object looking something similar to this:
[
{
"record_id": "<deed-address>:<shard-id>",
"address": "<deed-address>",
"chainId": "<shard-id>",
"block_hash": "...",
"block_timestamp": "...",
"block_number": "...",
"transaction_hash": "...",
"transaction_sender": "<your-address>",
"owner": "<your-address>",
"propertyAddress": "123 Main St.",
"acreage": 5,
"dateAcquired": 12345...
},
]
If we were to have created multiple Deed contracts, then their info would also have been returned in the response had we not provided any filters on the search.
Historical Log
Make the following request to the STRATO API:
GET https://<strato_address>/cirrus/search/history@<your-organization>-Deed?address=eq.<your-contract-address>&chainId=eq.<your-shard-id>
Notice we add the prefix of "history" to indicate that we are querying the history of this contract type.
Like before, we use the 2 query parameters of address and chainId to only retrieve the records that have the matching values in the respective columns. However unlike before, we will get back multiple rows, one for each update that happened on our contract.
This will return to you a JSON object looking something similar to this:
[
{
"record_id": "<deed-address>:<shard-id>",
"address": "<deed-address>",
"chainId": "<shard-id>",
"block_hash": "...",
"block_timestamp": "...",
"block_number": "...",
"transaction_hash": "...",
"transaction_sender": "<your-address>",
"owner": "<your-address>",
"propertyAddress": "123 Main St.",
"acreage": 5,
"dateAcquired": 12345...
},
{
"record_id": "<deed-address>:<shard-id>",
"address": "<deed-address>",
"chainId": "<shard-id>",
"block_hash": "...",
"block_timestamp": "...",
"block_number": "...",
"transaction_hash": "...",
"transaction_sender": "<your-address>",
"owner": "<your-address>",
"propertyAddress": "123 Main St.",
"acreage": 2,
"dateAcquired": 12345...
},
]
The first row (the first element in the array) is the most recent value of the Deed contract, with its acreage value being the same as the current value. The second row (the second element in the array) is the previous value for this contract, in our case the initial value when we first created it.
For more information on Cirrus in general, view the Cirrus Documentation.
For more information on using Cirrus in your applications, please visit the Using the Cirrus API Documentation.
After you have completed these steps, you have all the tools you need to start building basic apps on Mercata. Visit the pages under Mercata Application Development > Application Design Patterns. A great place to start is the Multinode/Distributed App Development Concepts.