Connect a local application to the sandbox

This tutorial is specifically designed for developers trying to understand how to develop an application based on Carmentis. For this purpose, we have designed a "Hello World" application, whose the source code and the installation instructions are accessible on GitHub, being easy to install

The goal of this application is to deploy an already existing application in which anyone can post a message, later being displayed in a public board.

Step 1: Installing and configuring Your wallet

To agree on the sending of your message, you will rely on digital signature, authenticating the message your are sending in the board. Don't worry, in this tutorial and even the others, no signature key pair generation is required, it is completely transparent for you, thanks to the wallet of Carmentis.

The wallet of Carmentis takes the form of an extension in your browser, from which every approval steps is based. We refer you to the installation guide (here) to install the wallet in your favorite browser.

Once installed, you have to create your personal account (which is ultimately your signature key pair). Again, we refer you to the wallet configuration page in the documentation (here). To verify that your account has been successfully created, try to authenticate yourself at login page of Carmentis (here).

Step 2: Create a sandbox environment

Creating your personal sandbox in a minute by following these steps:

1. Visit our "Get started" page at https://data.testapps.carmentis.io/get-started.
2. Click on "Go to the sandbox".
3. Sign-in using your wallet.

Step 3: Create your application in the Carmentis workspace

To interact with the system of Carmentis (including the already running operator, the blockchain and so on), it is necessary to declare your application in your personnal workspace. Note that if you are not logged in already, you will be automatically redirected to the login page.

Observe on the left of the workspace page, the "Applications" section as shown below:

Create a new application using the New button and insert a name of your choice (the name you provide is not relevant). For simplicity, assume that our application is called "Hello World". A new row describing your freshly created application should appear. Click in the Edit field as shown below:

At this point, your application is declared to Carmentis, but you must specify now what Carmentis is supposed to deal with, namely your data. For the "Hello World" application, three (public) fields have to be declared:

• Date of type string
• Sender of type string
• Message of type string

To declare these three fields, go to the Fields section and for each of them, click on New Field, enter the name of the field (Note: every field's name is case-sensitive), made it public by clicking on Public Data and finalize using the Confirm button. Once all fields have been declared, you should obtain the following (the order of the variables is not relevant):

Then, move to the Messages section. These messages are used by Carmentis during the approval step by sending this message directly to the user. These messages allow some flexibility but we voluntarily keep the message simple. Add a new message by clicking on the New message button, put approvalMessage as the name of your message, and a message of your choice. Suppose we have written Do you agree?. To learn more about messages, we refer you to the documentation (here).

Finally, click on Publish to finalize the declaration of the application. In the Overview section is displayed the ID of your application as well as the version number.

note

The ID of your application is set once and never change. Nevertheless, you are still allowed to apply modification to your application: The publication of an updated application leads to an incrementation of the application's version number. To use the updated application, only update the version number to match the latest version.

Step 4: Download, configure and run the hello-world application

Git Requirement

Be sure to have git installed in your system to download the repository.

NodeJS and NPM Requirements

This "Hello World" application has been developed using NodeJS that should be installed in your system. The installation of NodeJS (as well as npm) depends on your system in configuration, we refer to the official NodeJS installation page (here).

Download our Github repository containing all the required source code following these commands:

git clone https://github.com/Carmentis/carmentis-app-hello-world.git
cd carmentis-app-hello-world

Duplicate the .env.example file and rename the duplicated file as .env. Only two variables has to be modified, namely CARMENTIS_APPLICATION_ID and CARMENTIS_APPLICATION_VERSION.

note

The CARMENTIS_APPLICATION_ID and CARMENTIS_APPLICATION_VERSION values are displayed in your workspace (here) in your application under the Overview section.

Launching the NodeJS web server (which is our application) is done with the following command:

nmp install && node app.mjs

You can observe that everything works by looking at the address specified in the .env file (by default, it is http://localhost:3000). Once in your browser, observe the "Operator" and "Wallet" notifications, which should be green as shown below:

At this step, you are now ready to interact with our Hello-World application, starting at the default web page consisting of a form block and a list of approved messages. In the form, one enters a name (which is not necessarily tied to your real identity) and a message of its choice.

By clicking on the submit button, an approval popup will show up to ask you to approve your message. Following the instruction, the page will be refreshed automatically with your message being displayed. Why not observing your message in the blockchain using the blochain explorer)?