How to Get Started With the IOTA Industry Marketplace: A Step-by-Step Guide

We recently launched the Industry Marketplace: a vendor and industry-neutral platform developed by IOTA and world-leading innovators. This blog post is for anyone who wants to contribute to the Industry Marketplace by setting up an instance of a Service Requesteror a Service Provider. In the following section, I will quickly wrap up the main purpose of the Industry Marketplace and its key elements. Then I will go into detail on how to install, run, and configure the essential MarketManager component.

Don’t forget to keep track of the blog posts that will be released in the upcoming weeks. A cooperation engagement process will be posted soon in a separate blog post.

The Industry Marketplace establishes a vendor-neutral marketplace for Industry 4.0 (I4.0) components to buy and sell goods, data, and services. Unlike conventional virtual marketplaces, the Industry Marketplace, powered by IOTA, is an autonomous and decentralized platform for offering and searching for data and services, which is open to everyone free of charge.

A participant in the Industry Marketplace can take one of two roles: the role of Service Requester or Service Provider. The Service Requester searches for some data or services, e.g. charging, transporting, drilling, etc., offered by a Service Provider. The Service Requester chooses a Service Provider and processes a payment in IOTA tokens, once the service is successfully fulfilled.

In order to realize the potential behind the Industry Marketplace, it is crucial that all participating actors communicate in a precise and distinct language. Humans might understand the essentials of a message without speaking the same language due to their imagination and intelligence. However, machines are required to communicate in the same language in order to understand each other.

Accordingly, a request sent out by a Service Requester has to be interpreted the same way by all participants within the Industry Marketplace. To achieve this, all messages exchanged on the platform follow the specifications of the Industry 4.0 language.

Based on this, the Service Requester sends out its request as a call for proposals in which they specify their requested service. Service Providers can then generate Proposals in response. Both the Call For Proposal and the proposal itself contain a technical and commercial description of the service. This can include, for example, the price, time, quality, and place for the provision of a service. To make sure that all participants have the same understanding of the services, eCl@ss properties are part of the transaction data.

Further messages and their sequence of exchange are pictured below.

Feel free to find more information about the Industry 4.0 language(English) and eCl@sson their websites and dedicated papers.

To create Industry 4.0 language messages and perform the logical mapping between Service Requesters and Service Providers, a MarketManager component is provided as a core part of the Industry Marketplace. The MarketManager plays the role of the middleman between the user and the IOTA Tangle, IOTA’s underlying data structure, and has the following tasks:

Translation of the I4.0 language messages from the SR and SP into IOTA transactions sent to a node.
Translation of received IOTA transactions into I4.0 language messages and filtering those relevant for the connected SR and SP.
Authentication of interacting parties by creating and verifying proof of decentralized authentication and identification (DID) ownership

The MarketManager component provided within the source code comes with a user interface, which forwards user input to the MarketManager Back-end.

It is also possible to use the MarketManager without a user interface by sending API Requests as described within our Technical Documentation.

However, within this article, the focus is set on the implementation of the MarketManager with the user interface.

Let’s get started with the implementation of your own MarketManager instance. Before, make sure you have installed the following prerequisites:

Git
Yarn
Node.js(v. >10)

We support Node.js version 10 and above, please update if your Node.js version is older. To check your Node.js version by running “node -v” in your console or terminal.

If all prerequisites are installed, you can follow the step-by-step instructions below.

Go ahead and clone or download the Industry Marketplace repository from GitHub

$ git clone https://github.com/iotaledger/industry-marketplace.git

2. Go to the project folder of the ServiceApp

$ cd /industry-marketplace/ServiceApp

3. Install all required packages, build and launch the application with the yarn dev command (This might require opening a new terminal window when working with Windows operating system).

$ yarn dev

This will start the Back-end MarketManager on http://localhost:4000as well as the User Interface on http://localhost:3000.

If the User Interface does not open automatically, you can open it by entering http://localhost:3000into your browser.

To configure your installed instance of MarketManager, please click on the gearwheel in the left-bottom corner of the user interface. A configuration dialog will open up.

Here you can specify your user with the entity name and location (as address or GPS coordinates), and select one of the available types (Requester or Provider). You can also fund an existing internal wallet using the free Devnet IOTA Tokens by activating the box. The funding process of your wallet might take a couple of minutes, please do not interrupt this process.

Once the configuration dialog is submitted for the first time, the MarketManager automatically generates a Digital ID for its instance. This is done by initializing a MAM-Channel and taking its root as a DID.

Within the same step, an RSA Keypair consisting of a private and public key is created for encryption purposes. The public key of an entity can be used by others to encrypt sensitive data, that should only be accessible only by the entity. This is enabled via asynchronous encryption, where messages that are encrypted with a public key can only be decrypted with the matching private key.

Furthermore, a random address for communication is generated. This random address will be used later on to receive verifiable credentials from the IOTA Foundation to prove that the MarketManager is a Trusted Identity.

DID, keypair, and the random address are combined into a DID Document and published to the MAM-Channel. In addition, DID, private key, and seed of the MAM are stored in the local DB of the MarketManager.

If you run your MarketManager instance as a Service Requester and funded your wallet as described above, you are now ready to create your first Call For Proposal by clicking the Create Request button. A window will pop up where you can specify the operation and its attributes that you want to request.

If you do not want to enter real values into the required input fields, you can use a built-in randomizer to generate valid values for each field. The generated values can be adjusted according to your preferences. Press the crossed arrows on the top of the dialog to generate random values.

As soon as you submit your request, the Back-end MarketManager will translate your input into an I4.0 language message and send it to a node. Your Call For Proposal will show up in the Awaiting Proposal section and will remain there until a Service Provider of the Industry Marketplace will respond with a Proposal message.

Your Call For Proposal will disappear as soon as a Proposal arrived.

As you can see below, we received a proposal from user ServiceProvider to fulfill our request for 2 IOTA tokens. Here you can either accept or reject the proposal.

Expired Requests can no longer be accepted.

If you accept the proposal, the card will move to the “Awaiting fulfillment” category and will remain there until the Service Provider sends an inform confirm message, that the operation was successfully fulfilled. Afterward, the card will move to the “Awaiting payment” section, where you can process the payment.

The payment will be added to your payment queue, which collects all payments in five minutes and executes them as one. More information about the payment queue can be found in our Technical Documentation

After your payment was successfully added to the payment queue, the card will move to the “Completed” section.

If you configured your instance as a Service Provider, you are waiting for incoming Call For Proposals in the first step.

After receiving a Call For Proposal, it can be accepted by entering a price for the service. The price needs to be entered in IOTA tokens. Until the price is entered, the button to send out a proposal remains disabled. Expired requests can not be accepted.

In case the proposal was accepted, the card will appear in the “Awaiting Fulfilment” category.

At this point, you are hypothetically executing the service and sending anInform Confirm message as soon as the task is done. If the task cannot be executed unexpectedly, the request can still be rejected by hitting the “Reject Request” button.

As soon as the Service Requester processes the payment, the card will move from “Awaiting payment” to “Completed” and your balance will increase within the next couple of minutes.

The Service provider and Service requester have the opportunity to enable a filter for Trusted Requests in the upper right corner.

If the filter is enabled, only messages from Requesters and/or Providers labeled as trusted are forwarded to the user interface. However, to be able to receive proposals from trusted Requesters and/or Providers, your MarketManager has to become a Trusted Identity itself.

To be labeled as a Trusted Identity, the MarketManager needs to receive a Verifiable Credential from the IOTA Foundation. This can be done by emailing the DID of the MarketManager instance (Requester or Provider) to industry@iota.org.

The DID can be retrieved by sending a GET API-Request to the endpoint. Open your browser with http://localhost:4000/user, and copy the “did:IOTA:” with the following ID into the email with your company name and keep the MarketManager online at least until a confirmation email has been sent. This will take up to 24 hours and is usually done from Monday to Friday.

We will then verify your identity and send Verifiable Credentials to your MarketManager instance via the randomly generated address created during configuration. This process will be improved in the next set of updates. It will later be possible to whitelist your own DIDs directly. Any party that trusts the organization will then trust every DID white-labeled by that organization.

Verifiable Credentials offer a medium to prove which other actors have identified an actor as trusted. All DIDs of the participants of the Industry Marketplace has received a Verifiable Credential stating they are a trusted actor from the IOTA Foundation’s DID.

The Service Provider and Service Requester both have to opportunity to take a look at the transaction history by clicking on the request card header. The data visible on the new page is retrieved directly from the encrypted MAM channel on the Tangle, and can only be accessed by Service Requester and Service Provider entities participating in the transaction. The data can be used as an audit log.

If the requested service is for providing data from a device or sensor, the data can be accessed on the same page where the transaction log is available.

Click on the request card header, and wait until data is fetched from the encrypted MAM channel using credentials provided by the Service Provider. The data is displayed as cards in chronological order.

This information can also be retrieved using a script and therefore can be exported into another application. Please note that the data is only available after the request was marked as fulfilled.

The Service Provider can determine how long the data will remain available.

All blue-colored captions on the upper part of the request card are clickable links.

The link redirects to the respective parameter description in the eCl@ss catalog.

Another type of external link redirects to a Google Maps service with the location specified by GPS coordinates.

The messages received by the User Interface are filtered out by the MarketManager in the Back-end. The filters can be configured using the config.json file from the ServiceApp/server/src folder.

Filter by Operation Type. This filter applies to both Service Requester (SR) and Service Provider (SP) roles. An entity can specify a list of supported operations under the attribute operations: […] within the configuration script (config.json) of the Market Manager. The operation identifier is added to the transaction tag for faster filtering. Only messages related to operations from the list are allowed to pass through.

Configuration parameter operations from the config.js on file

Filter by Entity Role and Message Type: We differentiate between Service Requester (SR) and Service Provider (SP) roles. Each role has a specific set of messages that it can accept. For SR the valid messages are proposal and inform Confirm. For SP the valid messages are call For Proposal, accept Proposal, reject Proposal, and inform Payment. For the YellowPages Application accepted messages are Call For Proposal, proposal, and accept Proposal.

Filter by Location: This filter only applies to the Service Provider. If the entity has defined its location and maximum range within requests that should be accepted, the filter calculates the distance between SR and SP. This distance is then compared with the maximum range value defined in the configuration script. Only requests from Service Requester located within this range are allowed to pass through.

Configuration parameter maxDistance from the config.js on file, along with its own location, configured via API or MarketManager UI configuration dialog.

Filter by Recipient (user DID): This last filter applies for message types different from call For Proposal, which is sent to every Service Provider. All other messages already specify the receiver ID field, which is retrieved and compared to the internal DID of the entity. Only in case of a match, the message is allowed to pass through.

If you still have questions about how to get started, please join us at Discord and engage directly with us in the dedicated channel for the Industry Marketplace.

Visit the Industry Marketplace and participate now: industry.iota.org