A DEcentralized SMart Oracle for the Internet of Things

Overview

The DESMO-LD project aims to provide a fully integrated distributed solution for consuming IoT external data, enriched with Web of Things semantics and data model, inside the ONTOCHAIN. This addresses the ONTOCHAIN call's objectives of designing new trustful decentralized Oracles to poll semantic data from off-chain data sources. Besides, DESMO-LD introduces novel strategies to solve the known interoperability problems thanks to the heavy deployment of standard ontology and semantic oriented consensus algorithms for data quality and trustiness.

Architecture

DESMO-LD is a Decentralized Oracle for IoT data powered by WoT technologies. The system architecture is divided between an on-chain part, consisting of a set of smart contracts, and an off-chain part with the Oracle DApp and the Web of Things Thing Description Directory (TDD). The project structure is consequently organized as follows:

• Smart Contracts
• Oracle DApp
• TDD

For an overview of the system architecture, please refer to the architecture diagram.

The system allows client Smart Contracts and DApps to access off-chain data produced by a network of IoT devices. The solution enables the development of different applications according to the vertical implementation of any horizontal features developed. The value generated by the token transactions is enhanced through the development of a “pay-per-request” subscription service to access the resources. Throughout the process to retrieve information all the actors involved will be rewarded with tokens.

On-Chain: Decentralized iExecDoracle

The on-chain part is strictly connected to the development of a decentralized network of Oracles. The value of the Decentralized Oracle lies in the trustfulness of the data provided on-chain which increases the level of security and fairness of Smart Contracts. Data and process management in cross-sectors environments mostly benefit from a Smart Contract built upon Decentralized Oracles because they can enhance the intrinsic value of getting access to multiple and heterogeneous data sources that are reliable.

Off-Chain: WoT Decentralized Data Sources

The off-chain part is linked to the Web of Thing functionality and technologies. Value is created by accessing a constant real-time stream of quality IoT data from the WoT. Moreover, it features a ranking system able to assess data sources' quality to de-incentives bad or unfair behaviour. Data streamed are organized and defined in Thing Description which manifest the interactions affordances among IoT devices or services. The generated value is enhanced through the automatic rewarding of the possessors of WTs devices that the architecture guarantee.

Main Innovation

The DESMO-LD project will focus on a trusted decentralized oracle system to reliably consume IoT data from on-chain Smart Contracts. The main innovation points consists:

• Leverage on WoT interaction model and WoT ontology for implementing an interoperable connection layer with heterogeneous IoT systems and devices;
• Provide trustable means to induce real world effects thanks to attenuation APIs;
• Native support for geolocation queries and data.

Deployment

To deploy the DESMO-LD system, start by cloning the repository:

git clone --recurse-submodules https://github.com/vaimee/desmo

After the command you should see all the repositories on your local Desmo folder. Notice, as git submodule works, all the cloned repositories will be not at their latest main branch commit. We are manually update git submodule references to keep everything updated, but in case you need to fetch the latest commit, follow the next procedure:

cd ${submodule_folder}
git fetch origin
git checkout main
git pull

Remember to do that procedure for each Desmo module. At this point you should have all the latest changes on your local machine. We can now proceed with the deployment.

Prerequisites

• Docker
• Docker Compose
• Node.js 16+
• npm 7+

Deploying the Smart Contracts

The smart contracts are deployed using the Hardhat framework. To deploy the contracts, run the following commands:

cd desmo-contracts
npm ci
npm run build
npm run deploy

After the last command, you should see the new contract addresses printed on the console. Those addresses are also saved in the desmo-contracts/deployed.json file. You can use those addresses to configure the other components of the system. Now you can register the minimum number of Thing Description Directories required to start the system. To do so, run the following command:

npm run deploy:init

Currently, the script register 4 TDDs that are managed by VAIMEE. You can change this behavior by modifying the desmo-contracts/hardhat.config.ts file (check the RegisterTDDs hardhat script). Now the contracts are ready to be used. To integrate them into the other system components it is useful to published them as a npm package. Before doing so you have to change the name of the package inside the package.json. Use your npm handle and set the name property to @<yournpmuser>/desmo-contracts. Then you can publish it to npm:

npm run publish --access public

You can start deploying the other components of the system, but before that you have to configure the SDK to use the deployed contracts.

Deploying the Desmo SDK

The Desmo SDK is a TypeScript library that allows you to interact with the deployed smart contracts and the DApp. To deploy and configure the SDK, run the following commands:

cd desmo-sdk
npm ci

Now you have to configure the SDK to use the deployed contracts. It is pretty simple, just uninstall the @vaimee/desmo-contracts package and install the one you just published:

npm un @vaimee/desmo-contracts
npm i @<yournpmuser>/desmo-contracts

To use your own contracts, you have also to update all the imports in the desmo-sdk/src folder. Look for the @vaimee/desmo-contracts package imports and replace it with @<yournpmuser>/desmo-contracts. Now you can build the SDK:

npm run build

The SDK is now ready to be used. You can publish it to npm as well:

1. Rename the package inside the package.json file, use your npm handle and set the name property to @<yournpmuser>/desmo-sdk.
2. Publish it to npm: npm run publish --access public

Deploying the DApp

The DApp is a IExec applications that interact with the smart contracts and the Thing Description Directories. DApp readme contains some deployment information too, but refer to this guide to have a complete overview of the deployment process. To start deploying the DApp, run the following commands:

cd desmo-dapp/DApp
npm ci

Now install the Desmo SDK you have just published:

npm un @vaimee/desmo-sdk
npm i @<yournpmuser>/desmo-sdk

Don't forget to update the imports in the desmo-dapp/DApp/src folder. Simply look for the @vaimee/desmo-sdk package imports and replace it with @<yournpmuser>/desmo-sdk. Now you can verify if the imports are correct by running the following command:

npm run build

After you set up your wallet, you can deploy the DApp to the Iexec marketplace. To do so start from building and publish the docker image of the DApp:

npm run docker_build

# replace <your_docker_username> with your docker username
docker tag desmo-dapp <your_docker_username>/desmo-dapp:<version>
# push the image to docker hub
docker push <your_docker_username>/desmo-dapp:<version>

Copy the checksum of the docker image in the file iexec.json under app.checksumm. Check the app.multiaddr and app.owner of the same file, they need to corrispond to the URL of your docker hum image and your wallet address respectively. Now you can deploy the DApp to the Iexec marketplace:

npm run onchain_deploy

# Set up the order of the DApp
npx iexec order init --app
npx iexec order sign --app
npx iexec order publish --app

Now the DApp is ready to be used. Note the deployed.json file contains the DApp address. You can use this address to configure the other components of the system. Finally, you have to deploy the frontend.

Deploying the Desmo Frontend

The Desmo frontend is a Angular application that allows you to interact with the DApp, the contracts and the Thing Description Directory. To deploy the frontend, start with the following commands:

cd desmo-frontend
npm ci

Now you have to configure the frontend to use the deployed DApp and contracts. To do so, open the desmo-frontend/src/environments/environment.ts file and set the iExecDAppAddress property to the address of the DApp you have just deployed. Moreover, install the Desmo SDK you have published in the previous steps:

npm un @vaimee/desmo-sdk
npm i @<yournpmuser>/desmo-sdk

Don't forget to update the imports in the desmo-dapp/DApp/src folder. Simply look for the @vaimee/desmo-sdk package imports and replace it with @<yournpmuser>/desmo-sdk. Now you can verify if the imports are correct by running the following command:

npm run build

If everything is correct, you can deploy the frontend to a web server. You can use the following command to start a local web server:

npm run start

The frontend is now ready, you can head to https://localhost:4200 to use it.

Acknowledgements

This project has received funding from the European Union’s Horizon 2020 research and innovation program through the NGI ONTOCHAIN program under cascade funding agreement No 957338