processProtectedData

Allows processing a protected dataset through use of a specified iExec application.

IMPORTANT

You must ensure this application has authorization to use the protectedData. You may grant this permission using the grantAccess method.

Usage

const processProtectedDataResponse =
  await dataProtectorCore.processProtectedData({
    protectedData: '0x123abc...',
    app: '0x456def...',
    args: 'arg1 arg2',
    inputFiles: ['https://example.com/file1', 'https://example.com/file2'],
    secrets: {
      1: 'secret1',
      2: 'secret2',
    },
  });

Parameters

import { type ProcessProtectedDataParams } from '@iexec/dataprotector';

protectedData Required *

Type: AddressOrENS

The ETH address or Ethereum Name Service (ENS) reference for the protected data you wish the app to process.

const processProtectedDataResponse =
  await dataProtectorCore.processProtectedData({
    protectedData: '0x123abc...',
    app: '0x456def...',
  });

app Required *

Type: AddressOrENS

The ETH address or Ethereum Name Service (ENS) address for the iExec application to process the protected data.

const processProtectedDataResponse =
  await dataProtectorCore.processProtectedData({
    protectedData: '0x123abc...',
    app: '0x456def...',
  });

path Optional

Type: string

Under the hood, a protected data is a zip file. With this path parameter, you can specify the file you're interested in. The zip file will be uncompressed for you, and only the desired file will be given as the result.

const processProtectedDataResponse =
  await dataProtectorCore.processProtectedData({
    protectedData: '0x123abc...',
    app: '0x456def...',
    path: 'my-content',
  });

userWhitelist Optional

Type: Address

If access to the protected data is granted to a group of users via a whitelist contract, you must use this userWhitelist parameter. The value should be the whitelist contract address that has access to the protected data.

const processProtectedDataResponse =
  await dataProtectorCore.processProtectedData({
    protectedData: '0x123abc...',
    app: '0x456def...',
    userWhitelist: '0x656def...',
  });

useVoucher Optional

Type: boolean
Default: false

This optional parameter allows you to pay for the task using a voucher. By default, it uses the voucher associated with your connected wallet, but you can override this by specifying a voucherAddress.

const processProtectedDataResponse =
  await dataProtectorCore.processProtectedData({
    protectedData: '0x123abc...',
    app: '0x456def...',
    useVoucher: true,
  });

TIP

If your voucher doesn't have enough xRLC to cover the deal, the SDK will automatically get the required amount to your iExec account. Ensure that your voucher is authorized to access your iExec account and that your account has sufficient funds for this transfer to proceed.

voucherOwner Optional

Type: Address

This optional parameter allows you to pay for the task using someone else’s voucher. Make sure the voucher's owner has authorized you to use it. This parameter must be used in combination with useVoucher: true.

const processProtectedDataResponse =
  await dataProtectorCore.processProtectedData({
    protectedData: '0x123abc...',
    app: '0x456def...',
    useVoucher: true,
    voucherOwner: '0x5714eB...',
  });

args Optional

Type: string

Set of execution arguments for the application.

const processProtectedDataResponse =
  await dataProtectorCore.processProtectedData({
    protectedData: '0x123abc...',
    app: '0x456def...',
    args: 'arg1 arg2',
  });

DANGER

Do not use this to provide any sensitive information to the application. All arguments passed this way are visible in plain text using the iExec blockchain explorer.

inputFiles Optional

Type: string[]

A set of URLs representing the input files required for application execution.

const processProtectedDataResponse =
  await dataProtectorCore.processProtectedData({
    protectedData: '0x123abc...',
    app: '0x456def...',
    inputFiles: ['https://example.com/file1', 'https://example.com/file2'],
  });

secrets Optional

Type: Record<number, string>

A set of requester secrets necessary for the application's execution. This is represented as a mapping of numerical identifiers to corresponding secrets stored in the secrets manager needed for the application's execution.

Secrets are accessible during the application's execution as environment variables. For more details, see Access requester secrets.

const processProtectedDataResponse = await dataProtectorCore.processProtectedData({
  protectedData: '0x123abc...',
  app: '0x456def...',
  secrets: { 
    1: 'secret1',
    2: 'secret2',
  },
});

workerpool Optional

Type: AddressOrENS | 'any'
Default: prod-v8-bellecour.main.pools.iexec.eth

The ETH address or Ethereum Name Service (ENS) address for the iExec workerpool. It's the confidential computer on which the iExec application will run.

TIP

iExec currently offers a production workerpool located at the Ethereum Name Service (ENS) address prod-v8-bellecour.main.pools.iexec.eth. This is the default workerpool for running confidential computations on the iExec platform.

If you don't specify a workerpool preference, 0x0000000000000000000000000000000000000000 represents any randomly available workerpool.

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.

TDX mode is enabled by setting connecting the TDX SMS and using the TDX workerpool.

Browser

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

const web3Provider = window.ethereum;
// Instantiate dataProtector connected to the TDX SMS
const dataProtectorCore = new IExecDataProtectorCore(web3Provider, {
  iexecOptions: {
    smsURL: 'https://sms.labs.iex.ec',
  },
});

const processProtectedDataResponse =
  await dataProtectorCore.processProtectedData({
    protectedData: '0x123abc...',
    app: '0x456def...',
    workerpool: 'tdx-labs.pools.iexec.eth',
  });

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

const processProtectedDataResponse =
  await dataProtectorCore.processProtectedData({
    protectedData: '0x123abc...',
    app: '0x456def...',
    workerpool: '0xa5de76...',
  });

dataMaxPrice Optional

Type: number
Default: 0

Allows specifying the maximum amount (in nRLC) you are willing to pay the protected data owner for using their data. The owner of the protected data receives this as a payment for sharing their data.

const processProtectedDataResponse =
  await dataProtectorCore.processProtectedData({
    protectedData: '0x123abc...',
    app: '0x456def...',
    dataMaxPrice: 42,
  });

appMaxPrice Optional

Type: number
Default: 0

Allows specifying the maximum amount (in nRLC) you are willing to pay the iApp provider for using the deployed application.

const processProtectedDataResponse =
  await dataProtectorCore.processProtectedData({
    protectedData: '0x123abc...',
    app: '0x456def...',
    appMaxPrice: 42,
  });

workerpoolMaxPrice Optional

Type: number
Default: 0

Allows specifying the maximum amount you want to pay the workerpool provider for using their infrastructure to run the iApp in nRLC.

const processProtectedDataResponse =
  await dataProtectorCore.processProtectedData({
    protectedData: '0x123abc...',
    app: '0x456def...',
    workerpoolMaxPrice: 42,
  });

onStatusUpdate Optional

Type: OnStatusUpdateFn<ProcessProtectedDataStatuses>

Callback function to be notified at intermediate steps.

const processProtectedDataResponse = await dataProtectorCore.processProtectedData({
  protectedData: '0x123abc...',
  app: '0x456def...',
  onStatusUpdate: ({ title, isDone }) => { 
    console.log(title, isDone); 
  },
});

You can expect this callback function to be called with the following titles:

'FETCH_PROTECTED_DATA_ORDERBOOK';
'FETCH_APP_ORDERBOOK';
'FETCH_WORKERPOOL_ORDERBOOK';
'PUSH_REQUESTER_SECRET';
'REQUEST_TO_PROCESS_PROTECTED_DATA';
'CONSUME_TASK';
'CONSUME_RESULT_DOWNLOAD';
'CONSUME_RESULT_DECRYPT';

Once with isDone: false, and then with isDone: true

Return value

import { type ProcessProtectedDataResponse } from '@iexec/dataprotector';

txHash

string

The ID of the transaction that happened on iExec's side chain. You may view details on the transaction using the iExec explorer.

dealId

string

Identifies the specific deal associated with this transaction.

taskId

string

A unique identifier associated with a task currently running on the iExec Bellecour side chain. You can monitor task execution using the iExec blockchain explorer.

TIP

The getResultFromCompletedTask() function allows you to retrieve the result of a completed task using its taskId.

Additionally, you can specify a file path within the ZIP archive to extract a specific file when required.

result

ArrayBuffer

The result is a ZIP file containing at least one mandatory file:

• computed.json: This file contains metadata about the computation performed by the application.
• additional files may be included depending on the dapp used.

INFO

In the case of the Content Creator Delivery DApp, the ZIP file will also include a file named content, which corresponds to the protected data processed during the task.