prepareBulkRequest

This method prepares a bulk request by grouping multiple protected data items that can be processed together efficiently. The prepared bulk request can then be processed using the processBulkRequest method.

INFO

This method is part of a two-step bulk processing process:

1. Prepare the bulk request using prepareBulkRequest to create a bulk request
2. Process the bulk request using processBulkRequest to execute the bulk processing

Usage

Browser

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

const web3Provider = window.ethereum;
const dataProtectorCore = new IExecDataProtectorCore(web3Provider);

// Get granted accesses with bulk capability
const { grantedAccess } = await dataProtectorCore.getGrantedAccess({
  bulkOnly: true,
});

// Prepare the bulk request
const { bulkRequest } = await dataProtectorCore.prepareBulkRequest({
  bulkAccesses: grantedAccess,
  app: '0x456def...',
  maxProtectedDataPerTask: 100,
});

NodeJS

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

const web3Provider = getWeb3Provider('PRIVATE_KEY');
const dataProtectorCore = new IExecDataProtectorCore(web3Provider);

// Get granted accesses with bulk capability
const { grantedAccess } = await dataProtectorCore.getGrantedAccess({
  bulkOnly: true,
});

// Prepare the bulk request
const { bulkRequest } = await dataProtectorCore.prepareBulkRequest({
  bulkAccesses: grantedAccess,
  app: '0x456def...',
  maxProtectedDataPerTask: 100,
});

Parameters

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

bulkAccesses Required *

Type: GrantedAccess[]

An array of GrantedAccess objects representing protected data items that have been granted access with bulk processing capability. Use bulkOnly: true option in getGrantedAccess to obtain bulk accesses. Each GrantedAccess must have been created with allowBulk: true when calling grantAccess.

const { bulkRequest } = await dataProtectorCore.prepareBulkRequest({
  bulkAccesses: grantedAccess, 
  app: '0x456def...',
});

app Required *

Type: AddressOrENS

The ETH address or Ethereum Name Service (ENS) address for the iExec application that will process the protected data items in the bulk request.

const { bulkRequest } = await dataProtectorCore.prepareBulkRequest({
  bulkAccesses: grantedAccess,
  app: '0x456def...', 
});

maxProtectedDataPerTask Optional

Type: number | undefined

Default: 100

Limits the number of protected data items processed per task. If you have more protected data items than this limit, multiple tasks will be created.

const { bulkRequest } = await dataProtectorCore.prepareBulkRequest({
  bulkAccesses: grantedAccess,
  app: '0x456def...',
  maxProtectedDataPerTask: 50, 
});

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.

You can specify this during preparation or when processing the bulk request.

const { bulkRequest } = await dataProtectorCore.prepareBulkRequest({
  bulkAccesses: grantedAccess,
  app: '0x456def...',
  workerpool: '0xa5de76...', 
});

workerpoolMaxPrice Optional

Type: number | undefined

Default: 0

The maximum amount (in nRLC) you are willing to pay the workerpool provider for using their infrastructure to run the application. You can specify this during preparation or when processing the bulk request.

const { bulkRequest } = await dataProtectorCore.prepareBulkRequest({
  bulkAccesses: grantedAccess,
  app: '0x456def...',
  workerpoolMaxPrice: 0.1 * 1e9, 
});

appMaxPrice Optional

Type: number | undefined

Default: 0

The maximum amount (in nRLC) you are willing to pay the application provider for using the application.

const { bulkRequest } = await dataProtectorCore.prepareBulkRequest({
  bulkAccesses: grantedAccess,
  app: '0x456def...',
  appMaxPrice: 0.1 * 1e9, 
});

args Optional

Type: string | undefined

Set of execution arguments for the application that will be used for all tasks in the bulk request.

const { bulkRequest } = await dataProtectorCore.prepareBulkRequest({
  bulkAccesses: grantedAccess,
  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[] | undefined

A set of URLs representing the input files required for application execution. These files will be used for all tasks in the bulk request.

const { bulkRequest } = await dataProtectorCore.prepareBulkRequest({
  bulkAccesses: grantedAccess,
  app: '0x456def...',
  inputFiles: ['https://example.com/file1', 'https://example.com/file2'], 
});

secrets Optional

Type: Record<number, string> | undefined

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 { bulkRequest } = await dataProtectorCore.prepareBulkRequest({
  bulkAccesses: grantedAccess,
  app: '0x456def...',
  secrets: {
    1: 'secret1', 
    2: 'secret2', 
  }, 
});

encryptResult Optional

Type: boolean | undefined

Default: false

Enable result encryption for the processed data. If enabled, you'll need to provide the pemPrivateKey when processing the bulk request to decrypt the results.

const { bulkRequest, pemPrivateKey } =
  await dataProtectorCore.prepareBulkRequest({
    bulkAccesses: grantedAccess,
    app: '0x456def...',
    encryptResult: true, 
  });

pemPrivateKey Optional

Type: string | undefined

Private key in PEM format for result encryption/decryption. If not provided and encryptResult is true, a new key pair will be generated and returned in the response.

const { bulkRequest, pemPrivateKey } =
  await dataProtectorCore.prepareBulkRequest({
    bulkAccesses: grantedAccess,
    app: '0x456def...',
    encryptResult: true,
    pemPrivateKey:
      '-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----', 
  });

onStatusUpdate Optional

Type: OnStatusUpdateFn<PrepareBulkRequestStatuses>

Callback function to be notified at intermediate steps during bulk request preparation. You can expect this callback function to be called with the following titles:

• 'PUSH_REQUESTER_SECRET' - Pushing requester secrets to the SMS
• 'GENERATE_ENCRYPTION_KEY' - Generating encryption key pair (if encryptResult: true)
• 'PUSH_ENCRYPTION_KEY' - Pushing encryption public key to the SMS (if encryptResult: true)
• 'PREPARE_PROTECTED_DATA_BULK' - Preparing the protected data bulk
• 'CREATE_BULK_REQUEST' - Creating the bulk request order

Each status is called once with isDone: false, and then with isDone: true.

const { bulkRequest } = await dataProtectorCore.prepareBulkRequest({
  bulkAccesses: grantedAccess,
  app: '0x456def...',
  onStatusUpdate: ({ title, isDone }) => {
    // Handle status updates
  }, 
});

Return Value

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

bulkRequest

Type: BulkRequest

The prepared bulk request object that contains all the necessary information to process multiple protected data items together. This object should be passed to processBulkRequest to execute the bulk processing.

pemPrivateKey

Type: string | undefined

The private key in PEM format for result decryption. This is only returned if encryptResult was set to true when preparing the bulk request. You'll need to provide this key when processing the bulk request if you want to decrypt the results.

// Get granted accesses with bulk capability
const { grantedAccess } = await dataProtectorCore.getGrantedAccess({
  bulkOnly: true,
});

// Prepare the bulk request with encryption
const { bulkRequest, pemPrivateKey } =
  await dataProtectorCore.prepareBulkRequest({
    bulkAccesses: grantedAccess,
    app: '0x456def...',
    encryptResult: true,
  });

// Use the bulkRequest and pemPrivateKey to process the bulk request
const { tasks } = await dataProtectorCore.processBulkRequest({
  bulkRequest: bulkRequest, 
  pemPrivateKey: pemPrivateKey, 
  waitForResult: true,
});

Related Documentation

• processBulkRequest Method - Process a prepared bulk request
• grantAccess Method - Grant access with bulk processing capability
• processProtectedData Method - Process a single protected data item