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...', 
  });

encryptResult Optional

Type: boolean
Default: false

When set to true, the computation result will be encrypted using RSA encryption. This ensures that only you can decrypt and access the result, providing an additional layer of privacy and security for sensitive computation outputs.

If encryptResult is true and no pemPrivateKey is provided, a new RSA key pair will be automatically generated. The generated private key will be returned in the response as pemPrivateKey, which you must securely store to decrypt the result later.

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

TIP

When encryptResult is enabled, the onStatusUpdate callback will be notified with the following additional status titles:

'GENERATE_ENCRYPTION_KEY' - When a new key pair is being generated
'PUSH_ENCRYPTION_KEY' - When the public key is being pushed to the secrets manager

pemPrivateKey Optional

Type: string

A PEM-formatted RSA private key used to decrypt the encrypted computation result. This parameter can only be used when encryptResult is set to true.

If you provide a pemPrivateKey, it will be used to decrypt the result. If you don't provide one but have encryptResult: true, a new key pair will be generated automatically, and the private key will be returned in the response for you to store securely.

const processProtectedDataResponse
 =
  await dataProtectorCore
.processProtectedData
({
    protectedData
: '0x123abc...',
    app
: '0x456def...',
    encryptResult
: true, 
    pemPrivateKey
:
      '-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----', 
  });

DANGER

If you provide a pemPrivateKey, you must also set encryptResult: true. The method will throw a validation error if pemPrivateKey is provided without encryptResult being enabled.

TIP

The pemPrivateKey (whether provided or auto-generated) will be included in the response object when encryptResult is true. Make sure to securely store this key if you need to decrypt the result later using the getResultFromCompletedTask() method.

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 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: 0x2C06263943180Cc024dAFfeEe15612DB6e5fD248

It's the confidential computer on which the iExec application will run.

TIP

iExec currently offers a workerpool located at the address 0x2C06263943180Cc024dAFfeEe15612DB6e5fD248. This is the default workerpool for running confidential computations on the iExec platform.

TDX Chain Not Supported

🧪 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_ORDERS';
'PUSH_REQUESTER_SECRET';
'GENERATE_ENCRYPTION_KEY';
'PUSH_ENCRYPTION_KEY';
'REQUEST_TO_PROCESS_PROTECTED_DATA';
'TASK_EXECUTION';
'CONSUME_TASK';
'CONSUME_RESULT_DOWNLOAD';
'CONSUME_RESULT_DECRYPT';

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

INFO

The 'GENERATE_ENCRYPTION_KEY' and 'PUSH_ENCRYPTION_KEY' status titles are only triggered when encryptResult is set to 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 protocol. You can monitor task execution using the iExec 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.

pemPrivateKey

string

The PEM-formatted RSA private key used to decrypt the encrypted computation result. This property is only present in the response when encryptResult is set to true.

If you provided a pemPrivateKey in the parameters, the same key will be returned. If you didn't provide one but enabled encryptResult, a newly generated private key will be returned, which you must securely store to decrypt the result.

TIP

You can use this pemPrivateKey with the getResultFromCompletedTask() method to decrypt and retrieve the result of a completed task.

processProtectedData ​

Usage ​

Parameters ​

protectedData Required * ​

app Required * ​

path Optional ​

userWhitelist Optional ​

encryptResult Optional ​

pemPrivateKey Optional ​

args Optional ​

inputFiles Optional ​

secrets Optional ​

workerpool Optional ​

dataMaxPrice Optional ​

appMaxPrice Optional ​

workerpoolMaxPrice Optional ​

onStatusUpdate Optional ​

Return Value ​

txHash ​

dealId ​

taskId ​

result ​

pemPrivateKey ​

processProtectedData

Usage

Parameters

protectedData Required *

app Required *

path Optional

userWhitelist Optional

encryptResult Optional

pemPrivateKey Optional

args Optional

inputFiles Optional

secrets Optional

workerpool Optional

dataMaxPrice Optional

appMaxPrice Optional

workerpoolMaxPrice Optional

onStatusUpdate Optional

Return Value

txHash

dealId

taskId

result

pemPrivateKey