getting-started.md

description	Get started with the @iexec/dataprotector SDK. Learn how to install, configure, and instantiate core and sharing modules to protect and manage data in Web3 applications.

Getting Started

Overview

Prerequisites

Before getting started, ensure that you have the following installed on your system:

- Node.js version 18 or higher

- NPM (Node.js package manager)

Installation

::: code-group

npm install @iexec/dataprotector

yarn add @iexec/dataprotector

pnpm add @iexec/dataprotector

bun add @iexec/dataprotector

:::

This package is an ESM package. Your project needs to use ESM too.  Read more

If you use it with Webpack, some polyfills will be needed. You can find a minimal working project here.

Instantiate SDK

Depending on your project's requirements, you can instantiate the SDK using the umbrella module for full functionality or opt for one of the submodules to access specific sets of features.

Instantiate using the umbrella module

For projects requiring the full functionality of the SDK, including both core and sharing functions.

::: code-group

declare global {
  interface Window {
    ethereum: any;
  }
}
// ---cut---
import { IExecDataProtector } from '@iexec/dataprotector';

const web3Provider = window.ethereum;
// Instantiate using the umbrella module for full functionality
const dataProtector = new IExecDataProtector(web3Provider);

const dataProtectorCore = dataProtector.core;
const dataProtectorSharing = dataProtector.sharing;

import { IExecDataProtector, getWeb3Provider } from '@iexec/dataprotector';

// Get Web3 provider from a private key
const web3Provider = getWeb3Provider('YOUR_PRIVATE_KEY');

// Instantiate using the umbrella module for full functionality
const dataProtector = new IExecDataProtector(web3Provider);

const dataProtectorCore = dataProtector.core; // access to core methods
const dataProtectorSharing = dataProtector.sharing; // access to methods

:::

Instantiate only the core module

For projects focusing solely on core data protection functions.

::: code-group

declare global {
  interface Window {
    ethereum: any;
  }
}
// ---cut---
import { IExecDataProtectorCore } from '@iexec/dataprotector';

const web3Provider = window.ethereum;
// Instantiate only the Core module
const dataProtectorCore = new IExecDataProtectorCore(web3Provider);

import { IExecDataProtectorCore, getWeb3Provider } from '@iexec/dataprotector';

// Get Web3 provider from a private key
const web3Provider = getWeb3Provider('YOUR_PRIVATE_KEY');

// Instantiate only the Core module
const dataProtectorCore = new IExecDataProtectorCore(web3Provider);

:::

Instantiate only the sharing module

For projects that need access management functions specifically.

::: code-group

declare global {
  interface Window {
    ethereum: any;
  }
}
// ---cut---
import { IExecDataProtectorSharing } from '@iexec/dataprotector';

const web3Provider = window.ethereum;
// Instantiate only the Sharing module
const dataProtectorSharing = new IExecDataProtectorSharing(web3Provider);

import {
  IExecDataProtectorSharing,
  getWeb3Provider,
} from '@iexec/dataprotector';

// Get Web3 provider from a private key
const web3Provider = getWeb3Provider('YOUR_PRIVATE_KEY');

// Instantiate only the Sharing module
const dataProtectorSharing = new IExecDataProtectorSharing(web3Provider);

:::

Instantiate without a Web3 provider

For projects that only require read functions, you can instantiate the SDK without a Web3 provider.

::: code-group

import {
  IExecDataProtectorSharing,
  IExecDataProtectorCore,
} from '@iexec/dataprotector';

// Instantiate only the Core module for read-only core methods
const dataProtectorCore = new IExecDataProtectorCore();
// Instantiate only the Sharing module for read-only sharing methods
const dataProtectorSharing = new IExecDataProtectorSharing();

import { IExecDataProtector } from '@iexec/dataprotector';

// Instantiate using the umbrella module for read-only functions
const dataProtector = new IExecDataProtector();

// Access to read-only core methods
const dataProtectorCore = dataProtector.core;
// Access to read-only sharing methods
const dataProtectorSharing = dataProtector.sharing;

:::

Advanced configuration

To add optional parameters, see advanced configuration.

::: info

🧪 While protected data are processed in TEE by intel SGX technology by default, @iexec/dataprotector can be configured to create and process protected data in the experimental intel TDX environment.

For more details see:

• configure DataProtector TDX
• create TDX protected data
• process TDX protected data

⚠️ Keep in mind: TDX mode is experimental and can be subject to instabilities or discontinuity.

:::

Sandbox

Core methods

⚡  Code Sandbox

Corresponding GitHub repository:

🔎  GitHub repository sandbox

Sharing methods

⚡  Code Sandbox

Corresponding GitHub repository:

🔎  GitHub repository sandbox