processBulkRequest

This method processes a bulk request that has been created using the prepareBulkRequest method. It executes the bulk processing of multiple protected data items efficiently, creating one or more tasks depending on the number of protected data items and the maxProtectedDataPerTask limit.

Prerequisites

Before using this method, make sure you have:

1. Recipients granted access with bulk processing: When calling grantAccess on the Data Protector SDK, recipients must set allowBulk: true

2. Prepared the bulk request: Use prepareBulkRequest to create the bulk request that will be passed to this method

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

// Process the bulk request
const { tasks } = await dataProtectorCore.processBulkRequest({
  bulkRequest: bulkRequest,
});

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

// Process the bulk request
const { tasks } = await dataProtectorCore.processBulkRequest({
  bulkRequest: bulkRequest,
});

Parameters

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

bulkRequest Required *

Type: BulkRequest

The prepared bulk request object that was created using prepareBulkRequest. This object contains all the necessary information to process multiple protected data items together.

const { tasks } = await dataProtectorCore.processBulkRequest({
  bulkRequest: bulkRequest, 
});

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.

const { tasks } = await dataProtectorCore.processBulkRequest({
  bulkRequest: bulkRequest,
  workerpool: '0xa5de76...', 
});

path Optional

Type: string | undefined

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. This applies to all protected data items in the bulk request.

const { tasks } = await dataProtectorCore.processBulkRequest({
  bulkRequest: bulkRequest,
  path: 'my-content', 
});

pemPrivateKey Optional

Type: string | undefined

Private key in PEM format for result decryption. Required if bulkRequest uses result encryption (when encryptResult was set to true in prepareBulkRequest) and waitForResult is true.

const { tasks } = await dataProtectorCore.processBulkRequest({
  bulkRequest: bulkRequest,
  pemPrivateKey: pemPrivateKey, 
  waitForResult: true,
});

waitForResult Optional

Type: boolean | undefined

Default: false

Whether to wait for the result of the bulk request processing. If true, the method will wait for all tasks to complete and return results. If false, it will return immediately with task IDs.

const { tasks } = await dataProtectorCore.processBulkRequest({
  bulkRequest: bulkRequest,
  waitForResult: true, 
});

onStatusUpdate Optional

Type: OnStatusUpdateFn<ProcessBulkRequestStatuses>

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

• 'FETCH_ORDERS' - Fetching app and workerpool orders
• 'CREATE_BULK_TASKS' - Creating bulk tasks from matched orders
• 'WAIT_FOR_WORKERPOOL_AVAILABILITY' - Waiting for workerpool availability (when no workerpool order is available)
• 'REQUEST_TO_PROCESS_BULK_DATA' - Requesting to process bulk data (matching orders)
• 'PROCESS_BULK_SLICE' - Processing a slice of the bulk request (only when waitForResult: true)
• 'TASK_EXECUTION' - Task execution in progress (only when waitForResult: true)
• 'TASK_RESULT_DOWNLOAD' - Downloading task result (only when waitForResult: true)
• 'TASK_RESULT_DECRYPT' - Decrypting task result (only when waitForResult: true and encryption is enabled)

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

const { tasks } = await dataProtectorCore.processBulkRequest({
  bulkRequest: bulkRequest,
  onStatusUpdate: ({ title, isDone, payload }) => {
    // Handle status updates
  }, 
});

Return Value

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

tasks

Type: Array<{ taskId: string; dealId: string; bulkIndex: number }> (when waitForResult: false)

Type:Array<{ taskId: string; dealId: string; bulkIndex: number; success: boolean; status: TaskStatus; result?: ArrayBuffer; error?: Error }> (when waitForResult: true)

An array of task objects created by processing the bulk request. Each task represents a batch of protected data items being processed together.

When waitForResult: false (default):

• taskId: A unique identifier for the task
• dealId: Identifies the specific deal associated with this task
• bulkIndex: The index of this task within the bulk request (useful when multiple tasks are created)

When waitForResult: true:

• taskId: A unique identifier for the task
• dealId: Identifies the specific deal associated with this task
• bulkIndex: The index of this task within the bulk request
• success: Whether the task completed successfully
• status: The task status ('COMPLETED' | 'FAILED' | 'TIMEOUT')
• result: The task result as an ArrayBuffer (only present if successful)
• error: Error object if the task failed (only present if failed)

const { tasks } = await dataProtectorCore.processBulkRequest({
  bulkRequest: bulkRequest,
});

Related Documentation

• prepareBulkRequest Method - Prepare a bulk request for processing
• grantAccess Method - Grant access with bulk processing capability
• processProtectedData Method - Process a single protected data item
• getResultFromCompletedTask Method - Retrieve results from completed tasks