Bulk endpoint

Ledger v2.O - _bulk endpoint

In order to perform multiple operations at once, starting ledger v2, you can use the _bulk endpoint to perform those.

• Batch endpoint from v1 (atomic) is being replaced for an elastic-like bulk endpoint (atomic at the tx level within the bulk) meaning that e.g. N transactions out of 100 in the bulk can go through if the remaining 100-N are not valid (as opposed to the batch endpoint from the v1 endpoint, which would reject the whole batch)

• Transactions processed and validated by the ledger are then inserted into the database in batch mode, limiting network round-trips and significantly increasing write throughput. The writing is done by a worker whose role is to loop continuously and insert pending transactions into the buffer.

• you can add idempotency-key on actions in the bulk, so in case it stops, you can safely replay the same batch without having duplicates. Besides, there is a parameter continueOnFailure available.

  continueOnFailure=false (default)
  → the bulk will stop on the first error returned

  continueOnFailure=true
  → the bulk won't stop processing

POST /<ledger>/_bulk
[
    {"action": "CREATE_TRANSACTION", "data": {...}},
    {"action": "CREATE_TRANSACTION", "data": {...}},
    {"action": "ADD_METADATA", "data": {...}},
    ...
]

Available actions

* CREATE_TRANSACTION

* ADD_METADATA

* REVERT_TRANSACTION

* DELETE_METADATA

You can pass the following argument to the Ledger: --bulk-max-size

📄 How to increase the bulk transaction size limit

Ledger v2.2 - Enhanced _bulk Endpoint

The _bulk endpoint has been significantly improved with three major capabilities:

Streaming Support

Bulk requests can now be streamed, allowing large payloads to be processed efficiently without requiring the entire request to be loaded into memory.

📄 How to Use Bulk Operations with Streaming in the Ledger API

Parallel vs. Sequential Processing

You can now specify whether bulk elements should be processed in parallel or sequentially using the parallel query parameter:

• parallel=true: Elements are processed in parallel, improving throughput.

• parallel=false: Elements are processed sequentially, maintaining order.

Atomic Bulk Execution

You can now decide whether bulk elements should be committed atomically using the atomic query parameter:

• atomic=true: The entire batch is committed as a single transaction. If any element fails, the entire batch is rolled back.

• atomic=false: Each element is processed independently. If one element fails, it does not affect the others.