Omnia Backend

Omnia Backend is the core of the Omnia Network and is deployed as a canister on the Internet Computer. It manages the interaction main components of the Omnia Network.

We suggest reading the Architecture document to understand how the Omnia Network works before diving into the code.

Structure

The Omnia Backend is fully deployed on the Internet Computer and is composed of the following canisters:

• omnia_backend, the main canister that exposes the methods to Gateways, Managers and Applications.
• database, that stores all the data (devices, gateways, applications, etc.) using custom Create, Read, Update and Delete (CRUD) BTreeMaps structures.

omnia_backend canister depends on database, so they're always deployed together.

An RDF database is also embedded in the omnia_backend canister. See RDF database for details.

Additional libraries

To serve the purposes of the canisters mentioned above, some additional libraries are available in the source code:

• omnia_utils contains some utility functions used by the other canisters.
• omnia_types contains the types shared between the canisters.

Development

We suggest using the Dev Container with Visual Studio Code. If you can't use it (e.g. there are some problems with macOS on M1/M2 chips), have a look at the Dockerfile and install the dependencies manually.

Generate DIDs

dfx utility still doesn't support automatic did interfaces generation. There's a workaround, which uses Rust tests and Rust DFINITY CDK under the hood: for each canister, there's a generate_candid_interface test function that saves the candid interface in the canister's .did file. To run the did generation, run:

npm run generate:dids

TODO:

DIDs describe methods that canisters expose. According to the amazing Effective Rust Canisters guide, DIDs should be the single source of truth and should be written manually. DIDs should also include documentation (comments) to make it easier to understand what each method does. Hence, whenever a new method is added to a canister, or an existing method is changed, the corresponding DID should be updated as well.

Generate Typescript types

Frontend canisters need Typescript types reflect backend canisters did interfaces and make the @dfinity/agent-js library work properly. To generate them simply run:

npm run generate:types

Run canisters locally

Start local IC replica

To start a local IC replica, use the following command:

dfx start [--background] [--clean]

where --background is optional and makes it run in the background and --clean is optional and cleans the replica from previous deployments if there are.

First deployment

First of all, start a local IC replica (see above).

omnia_backend canister depends on database and needs to know the database canister id to make inter-canister calls work. For this reason, you must execute this command to deploy everything correctly:

npm run generate-dids-and-deploy

Deployment

Before executing any of the following commands, make sure you create a .env file by copying the .env.example file and filling in the parameters.

Available commands:

• npm run deploy: deploys all canisters
• npm run generate-dids-and-deploy: first generates dids and then deploys all canisters

Tests

We use Jest to run integration tests. All tests are in the __tests__ folder.

To run tests, first deploy the canisters (see above for details):

npm run deploy:tests -- --clean

This command will deploy also the application_placeholder canister, which is used to test some features, like signing access keys, that require the local replica runtime. See application_placeholder for the source code.

and then run:

npm run test

After running the tests, it's recommended to stop the local replica and start it again with the --clean flag (see above).

License

Licensed under the MIT License.

Dependencies report

To generate a report of all dependencies licenses, run:

npm run report:licenses