Handling clusters

Introduction to TEE clusters in the Ternoa JS SDK

If you are not familiar with Ternoa's TEE architecture for privacy yet, we strongly recommend you look at the following sections of the documentation and understand the key concepts:

• User workflow to interact with the cluster's enclaves.

• Secure Environment with the TEE.

• Ternoa privacy architecture.

• Enclaves definition

The quickest way to summarize the flow to encrypt and store content could be as follows:

The Secret or Capsule creation process involves encrypting content before uploading it to IPFS. The user's content is secured using a set of private and public keys, the Ternoa Chain, and the TEE. Content is encrypted with the public key, while the private key is split into 5 Shamir shares and stored in the TEE Cluster, which contains 5 enclaves.

Now, let's see how to select a cluster.

All code snippets below and on the subsequent pages are designed to function within a Node.js environment. If you require information on how it operates in a browser environment, please consult this section.

How to choose a cluster:

Unless specific use cases require it, data must be sent to one of the PUBLIC clusters registered on the chain. (Private clusters are available for specific use cases. Admin clusters should not be targeted.)

The selected public cluster ID does not matter since all clusters are synced with each other. However, in case you want to implement a retry function or want to manually handle cluster selection, you can use getPublicsClusters(). Otherwise, getFirstPublicClusterAvailable() is here for you.

Get all the public cluster ids

import { getPublicsClusters, initializeApi } from "ternoa-js";

const getClustersList = async () => {
  try {
    await initializeApi();
    const clusters = await getPublicsClusters();
    console.log(clusters); //Expected output is an array of cluster ids (number) ex: [0,2,3]
    console.log(clusters[0]); //Expected output a cluster id (number) ex: 0
    process.exit(0);
  } catch (error) {
    process.exit(1);
  }
};

Get the first public cluster available

import { getFirstPublicClusterAvailable, initializeApi } from "ternoa-js";

const getClusterId = async () => {
  try {
    await initializeApi();
    const cluster = await getFirstPublicClusterAvailable();
    console.log(cluster); //Expected output a cluster id (number) ex: 0
    process.exit(0);
  } catch (error) {
    process.exit(1);
  }
};

Now the cluster is selected, it is necessary to verify the health status of the cluster.

Cluster health

Before moving on to creation, the good practice is to verify the status of the selected cluster. An enclave in a cluster may not be available because it's in maintenance mode. Therefore, it's important to check the status of the selected cluster.

In most cases, it's not necessary to use or store the data in a variable. Just run the promise getEnclaveHealthStatus() to check if any errors are occurring. In case you need to use the cluster health data, use getEnclaveDataAndHealth().

import {
  getEnclaveHealthStatus,
  getFirstPublicClusterAvailable,
  initializeApi,
} from "ternoa-js";

const checkClusterHealth = async () => {
  try {
    await initializeApi();
    const cluster = await getFirstPublicClusterAvailable();
    await getEnclaveHealthStatus(cluster); // No output expected
    //...
    process.exit(0);
  } catch (error) {
    process.exit(1);
  }
};

import {
  getEnclaveDataAndHealth,
  getFirstPublicClusterAvailable,
  initializeApi,
} from "ternoa-js";

const getClusterHealth = async () => {
  try {
    await initializeApi();
    const cluster = await getFirstPublicClusterAvailable();
    const healthData = await getEnclaveDataAndHealth(cluster); // Expected output is Promise<EnclaveDataAndHealthType[]>
    console.log(healthData);
    //...
    process.exit(0);
  } catch (error) {
    process.exit(1);
  }
};