@mojaloop/central-ledger 17.3.2 → 17.4.0-snapshot.0

package/README.md

@@ -108,6 +108,45 @@ NOTE: Only POSITION.PREPARE is supported at this time, with additional event-typ
   }
 ```
 
+### Batch Processing Configuration Guide
+
+Batch processing can be enabled in the transfer execution flow. Follow the steps below to enable batch processing for a more efficient transfer execution:
+
+- **Step 1:** **Create a New Kafka Topic**
+  
+  Create a new Kafka topic named `topic-transfer-position-batch` to handle batch processing events.
+- **Step 2:** **Configure Action Type Mapping**
+  
+  Point the prepare handler to the newly created topic for the action type `prepare` using the `KAFKA.EVENT_TYPE_ACTION_TOPIC_MAP` configuration as shown below:
+  ```
+    "KAFKA": {
+      "EVENT_TYPE_ACTION_TOPIC_MAP" : {
+        "POSITION":{
+          "PREPARE": "topic-transfer-position-batch"
+        }
+      }
+    }
+  ```
+- **Step 3:** **Run Batch Processing Handlers**
+
+  Run the position batch handler along with the existing position handler using the following configuration options:
+  - **Configure Event Type Action Topic Map for Batch Handler:**
+
+      Configure the `EVENT_TYPE_ACTION_TOPIC_MAP` parameter for the position batch handler to consume events from the new topic (topic-transfer-position-batch).
+
+  - **Set Batch Size:**
+
+      Adjust the batch size using the parameter `KAFKA.CONSUMER.TRANSFER.POSITION_BATCH.config.options.batchSize`. This parameter determines the number of messages fetched in each batch.
+
+  - **Set Consume Timeout:**
+
+      Configure the consume timeout using the parameter `KAFKA.CONSUMER.TRANSFER.POSITION_BATCH.config.options.consumeTimeout`. This parameter specifies the number of milliseconds to wait for a batch of messages to be fetched if the specified batch size of messages is not immediately available.
+
+Example Command to Run Handlers:
+```
+node src/handlers/index.js handler --positionbatch
+```
+
 ## API
 
 For endpoint documentation, see the [API documentation](API.md).
@@ -187,6 +226,25 @@ If you want to run integration tests in a repetitive manner, you can startup the
 
 If you want to run override position topic tests you can repeat the above and use `npm run test:int-override` after configuring settings found [here](#kafka-position-event-type-action-topic-map)
 
+#### For running integration tests for batch processing interactively
+- Run dependecies
+```
+docker-compose up -d mysql kafka init-kafka kafka-debug-console
+npm run wait-4-docker
+```
+- Run central-ledger services
+```
+nvm use
+npm run migrate
+env "CLEDG_KAFKA__EVENT_TYPE_ACTION_TOPIC_MAP__POSITION__PREPARE=topic-transfer-position-batch" npm start
+```
+- Additionally, run position batch handler in a new terminal
+```
+env "CLEDG_KAFKA__EVENT_TYPE_ACTION_TOPIC_MAP__POSITION__PREPARE=topic-transfer-position-batch" "CLEDG_HANDLERS__API__DISABLED=true" node src/handlers/index.js handler --positionbatch
+```
+- Run tests using `npx tape 'test/integration-override/**/handlerBatch.test.js'`
+
+
 If you want to just run all of the integration suite non-interactively then use npm run `test:integration`.
 It will handle docker start up, migration, service starting and testing. Be sure to exit any previously ran handlers or docker commands.
 

package/config/default.json

@@ -289,7 +289,35 @@
               "group.id": "cl-group-transfer-position",
               "metadata.broker.list": "localhost:9092",
               "socket.keepalive.enable": true,
-              "allow.auto.create.topics": true
+              "allow.auto.create.topics": true,
+              "partition.assignment.strategy": "cooperative-sticky",
+              "enable.auto.commit": false
+            },
+            "topicConf": {
+              "auto.offset.reset": "earliest"
+            }
+          }
+        },
+        "POSITION_BATCH": {
+          "config": {
+            "options": {
+              "mode": 2,
+              "batchSize": 10,
+              "pollFrequency": 10,
+              "recursiveTimeout": 100,
+              "messageCharset": "utf8",
+              "messageAsJSON": true,
+              "sync": true,
+              "consumeTimeout": 10
+            },
+            "rdkafkaConf": {
+              "client.id": "cl-con-transfer-position-batch",
+              "group.id": "cl-group-transfer-position-batch",
+              "metadata.broker.list": "localhost:9092",
+              "socket.keepalive.enable": true,
+              "allow.auto.create.topics": true,
+              "partition.assignment.strategy": "cooperative-sticky",
+              "enable.auto.commit": false
             },
             "topicConf": {
               "auto.offset.reset": "earliest"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mojaloop/central-ledger",
-  "version": "17.3.2",
+  "version": "17.4.0-snapshot.0",
   "description": "Central ledger hosted by a scheme to record and settle transfers",
   "license": "Apache-2.0",
   "author": "ModusBox",
@@ -109,7 +109,7 @@
     "glob": "10.3.10",
     "hapi-auth-basic": "5.0.0",
     "hapi-auth-bearer-token": "8.0.0",
-    "hapi-swagger": "17.1.0",
+    "hapi-swagger": "17.2.0",
     "ilp-packet": "2.2.0",
     "knex": "3.0.1",
     "lodash": "4.17.21",

package/src/domain/position/binProcessor.js

@@ -0,0 +1,250 @@
+/*****
+ License
+ --------------
+ Copyright © 2017 Bill & Melinda Gates Foundation
+ The Mojaloop files are made available by the Bill & Melinda Gates Foundation under the Apache License, Version 2.0 (the "License") and you may not use these files except in compliance with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, the Mojaloop files are distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+
+ Contributors
+ --------------
+ This is the official list of the Mojaloop project contributors for this file.
+ Names of the original copyright holders (individuals or organizations)
+ should be listed with a '*' in the first column. People who have
+ contributed from an organization can be listed under the organization
+ that actually holds the copyright for their contributions (see the
+ Gates Foundation organization for an example). Those individuals should have
+ their names indented and be marked with a '-'. Email address can be added
+ optionally within square brackets <email>.
+
+ * Gates Foundation
+ - Name Surname <name.surname@gatesfoundation.com>
+
+ * INFITX
+ - Vijay Kumar Guthi <vijaya.guthi@infitx.com>
+ - Steven Oderayi <steven.oderayi@infitx.com>
+
+ --------------
+ ******/
+'use strict'
+
+const Logger = require('@mojaloop/central-services-logger')
+const BatchPositionModel = require('../../models/position/batch')
+const BatchPositionModelCached = require('../../models/position/batchCached')
+const PositionPrepareDomain = require('./prepare')
+const SettlementModelCached = require('../../models/settlement/settlementModelCached')
+const Enum = require('@mojaloop/central-services-shared').Enum
+const ErrorHandler = require('@mojaloop/central-services-error-handling')
+// TODO: We may not need this if we optimize the participantLimit query
+const participantFacade = require('../../models/participant/facade')
+
+/**
+ * @function processBins
+ *
+ * @async
+ * @description This is the domain function to process a list bins containing position messages grouped by participant account.
+ *
+ * @param {array} bins - a list of account-bins to process
+ * @param {object} trx - Database transaction object
+ *
+ * @returns {results} - Returns a list of bins with results or throws an error if failed
+ */
+const processBins = async (bins, trx) => {
+  const transferIdList = []
+  iterateThroughBins(bins, (_accountID, _action, item) => {
+    if (item.decodedPayload?.transferId) {
+      transferIdList.push(item.decodedPayload.transferId)
+    }
+  })
+  // Pre fetch latest transferStates for all the transferIds in the account-bin
+  const latestTransferStateChanges = await BatchPositionModel.getLatestTransferStateChangesByTransferIdList(trx, transferIdList)
+  const latestTransferStates = {}
+  for (const key in latestTransferStateChanges) {
+    latestTransferStates[key] = latestTransferStateChanges[key].transferStateId
+  }
+
+  const accountIds = Object.keys(bins)
+
+  // Pre fetch all settlement accounts corresponding to the position accounts
+  // Get all participantIdMap for the accountIds
+  const participantCurrencyIds = await BatchPositionModelCached.getParticipantCurrencyByIds(trx, accountIds)
+
+  // Validate that participantCurrencyIds exist for each of the accountIds
+  // i.e every unique accountId has a corresponding entry in participantCurrencyIds
+  const participantIdsHavingCurrencyIdsList = [...new Set(participantCurrencyIds.map(item => item.participantCurrencyId))]
+  const allAccountIdsHaveParticipantCurrencyIds = accountIds.every(accountId => {
+    return participantIdsHavingCurrencyIdsList.includes(Number(accountId))
+  })
+  if (!allAccountIdsHaveParticipantCurrencyIds) {
+    throw ErrorHandler.Factory.createFSPIOPError(ErrorHandler.Enums.FSPIOPErrorCodes.INTERNAL_SERVER_ERROR, 'Not all accountIds have corresponding participantCurrencyIds')
+  }
+
+  const allSettlementModels = await SettlementModelCached.getAll()
+
+  // Construct objects participantIdMap, accountIdMap and currencyIdMap
+  const participantIdMap = {}
+  const accountIdMap = {}
+  const currencyIdMap = {}
+  for (const item of participantCurrencyIds) {
+    const { participantId, currencyId, participantCurrencyId } = item
+    if (!participantIdMap[participantId]) {
+      participantIdMap[participantId] = {}
+    }
+    if (!currencyIdMap[currencyId]) {
+      currencyIdMap[currencyId] = {
+        settlementModel: _getSettlementModelForCurrency(currencyId, allSettlementModels)
+      }
+    }
+    participantIdMap[participantId][currencyId] = participantCurrencyId
+    accountIdMap[participantCurrencyId] = { participantId, currencyId }
+  }
+
+  // Get all participantCurrencyIds for the participantIdMap
+  const allParticipantCurrencyIds = await BatchPositionModelCached.getParticipantCurrencyByParticipantIds(trx, Object.keys(participantIdMap))
+  const settlementCurrencyIds = []
+  for (const pc of allParticipantCurrencyIds) {
+    const correspondingParticipantCurrencyId = participantIdMap[pc.participantId][pc.currencyId]
+    if (correspondingParticipantCurrencyId) {
+      const settlementModel = currencyIdMap[pc.currencyId].settlementModel
+      if (pc.ledgerAccountTypeId === settlementModel.settlementAccountTypeId) {
+        settlementCurrencyIds.push(pc)
+        accountIdMap[correspondingParticipantCurrencyId].settlementCurrencyId = pc.participantCurrencyId
+      }
+    }
+  }
+
+  // Pre fetch all position account balances for the account-bin and acquire lock on position
+  const positions = await BatchPositionModel.getPositionsByAccountIdsForUpdate(trx, [
+    ...accountIds,
+    ...settlementCurrencyIds.map(pc => pc.participantCurrencyId)
+  ])
+
+  let notifyMessages = []
+  let limitAlarms = []
+
+  // For each account-bin in the list
+  for (const accountID in bins) {
+    const accountBin = bins[accountID]
+    const actions = Object.keys(accountBin)
+
+    const settlementParticipantPosition = positions[accountIdMap[accountID].settlementCurrencyId].value
+    const settlementModel = currencyIdMap[accountIdMap[accountID].currencyId].settlementModel
+
+    // TODO: Refactor the following SQL query to optimize the performance
+    const participantLimit = await participantFacade.getParticipantLimitByParticipantCurrencyLimit(
+      accountIdMap[accountID].participantId,
+      accountIdMap[accountID].currencyId,
+      Enum.Accounts.LedgerAccountType.POSITION,
+      Enum.Accounts.ParticipantLimitType.NET_DEBIT_CAP
+    )
+    // Initialize accumulated values
+    // These values will be passed across various actions in the bin
+    let accumulatedPositionValue = positions[accountID].value
+    let accumulatedPositionReservedValue = positions[accountID].reservedValue
+    let accumulatedTransferStates = latestTransferStates
+    let accumulatedTransferStateChanges = []
+    let accumulatedPositionChanges = []
+
+    // If non-prepare action found, log error
+    // We need to remove this once we implement all the actions
+    if (actions.length > 1 || (actions.length === 1 && actions[0] !== 'prepare')) {
+      Logger.isErrorEnabled && Logger.error('Only prepare action is allowed in a batch')
+      // throw new Error('Only prepare action is allowed in a batch')
+    }
+    // If prepare action found then call processPositionPrepareBin function
+    const prepareActionResult = await PositionPrepareDomain.processPositionPrepareBin(
+      accountBin.prepare,
+      accumulatedPositionValue,
+      accumulatedPositionReservedValue,
+      accumulatedTransferStates,
+      settlementParticipantPosition,
+      settlementModel,
+      participantLimit
+    )
+
+    // Update accumulated values
+    accumulatedPositionValue = prepareActionResult.accumulatedPositionValue
+    accumulatedPositionReservedValue = prepareActionResult.accumulatedPositionReservedValue
+    accumulatedTransferStates = prepareActionResult.accumulatedTransferStates
+    // Append accumulated arrays
+    accumulatedTransferStateChanges = accumulatedTransferStateChanges.concat(prepareActionResult.accumulatedTransferStateChanges)
+    accumulatedPositionChanges = accumulatedPositionChanges.concat(prepareActionResult.accumulatedPositionChanges)
+    notifyMessages = notifyMessages.concat(prepareActionResult.notifyMessages)
+
+    // Update accumulated position values by calling a facade function
+    await BatchPositionModel.updateParticipantPosition(trx, positions[accountID].participantPositionId, accumulatedPositionValue, accumulatedPositionReservedValue)
+
+    // Bulk insert accumulated transferStateChanges by calling a facade function
+    await BatchPositionModel.bulkInsertTransferStateChanges(trx, accumulatedTransferStateChanges)
+
+    // Bulk get the transferStateChangeIds for transferids using select whereIn
+    const fetchedTransferStateChanges = await BatchPositionModel.getLatestTransferStateChangesByTransferIdList(trx, accumulatedTransferStateChanges.map(item => item.transferId))
+    // Mutate accumulated positionChanges with transferStateChangeIds
+    for (const positionChange of accumulatedPositionChanges) {
+      positionChange.transferStateChangeId = fetchedTransferStateChanges[positionChange.transferId].transferStateChangeId
+      positionChange.participantPositionId = positions[accountID].participantPositionId
+      delete positionChange.transferId
+    }
+    // Bulk insert accumulated positionChanges by calling a facade function
+    await BatchPositionModel.bulkInsertParticipantPositionChanges(trx, accumulatedPositionChanges)
+
+    limitAlarms = limitAlarms.concat(prepareActionResult.limitAlarms)
+  }
+
+  // Return results
+  return {
+    notifyMessages,
+    limitAlarms
+  }
+}
+
+/**
+ * @function iterateThroughBins
+ *
+ * @async
+ * @description Helper function to iterate though all messages in bins.
+ *
+ * @param {array} bins - a list of account-bins to iterate
+ * @param {async function} cb - callback function to call for each item
+ * @param {async function} errCb - callback function to call incase of any error
+ *
+ * @returns {void} - Doesn't return anything
+ */
+
+const iterateThroughBins = async (bins, cb, errCb) => {
+  for (const accountID in bins) {
+    const accountBin = bins[accountID]
+    for (const action in accountBin) {
+      const actionBin = accountBin[action]
+      for (const item of actionBin) {
+        try {
+          await cb(accountID, action, item)
+        } catch (err) {
+          if (errCb === undefined) {
+            Logger.isErrorEnabled && Logger.error(err)
+          } else {
+            await errCb(accountID, action, item)
+          }
+        }
+      }
+    }
+  }
+}
+
+const _getSettlementModelForCurrency = (currencyId, allSettlementModels) => {
+  let settlementModels = allSettlementModels.filter(model => model.currencyId === currencyId)
+  if (settlementModels.length === 0) {
+    settlementModels = allSettlementModels.filter(model => model.currencyId === null) // Default settlement model
+    if (settlementModels.length === 0) {
+      throw ErrorHandler.Factory.createFSPIOPError(ErrorHandler.Enums.FSPIOPErrorCodes.GENERIC_SETTLEMENT_ERROR, 'Unable to find a matching or default, Settlement Model')
+    }
+  }
+  return settlementModels.find(sm => sm.ledgerAccountTypeId === Enum.Accounts.LedgerAccountType.POSITION)
+}
+
+module.exports = {
+  processBins,
+  iterateThroughBins
+}

package/src/domain/position/prepare.js

@@ -0,0 +1,251 @@
+const { Enum } = require('@mojaloop/central-services-shared')
+const ErrorHandler = require('@mojaloop/central-services-error-handling')
+const Config = require('../../lib/config')
+const Utility = require('@mojaloop/central-services-shared').Util
+const resourceVersions = require('@mojaloop/central-services-shared').Util.resourceVersions
+const MLNumber = require('@mojaloop/ml-number')
+const Logger = require('@mojaloop/central-services-logger')
+
+/**
+ * @function processPositionPrepareBin
+ *
+ * @async
+ * @description This is the domain function to process a bin of position-prepare messages of a single participant account.
+ *
+ * @param {array} binItems - an array of objects that contain a position prepare message and its span. {message, span}
+ * @param {number} accumulatedPositionValue - value of position accumulated so far from previous bin processing
+ * @param {number} accumulatedPositionReservedValue - value of position reserved accumulated so far, not used but kept for consistency
+ * @param {object} accumulatedTransferStates - object with transfer id keys and transfer state id values. Used to check if transfer is in correct state for processing. Clone and update states for output.
+ * @param {number} settlementParticipantPosition - position value of the participants settlement account
+ * @param {object} settlementModel - settlement model object for the currency
+ * @param {object} participantLimit - participant limit object for the currency
+ * @returns {object} - Returns an object containing accumulatedPositionValue, accumulatedPositionReservedValue, accumulatedTransferStateChanges, accumulatedTransferStates, resultMessages, limitAlarms or throws an error if failed
+ */
+const processPositionPrepareBin = async (
+  binItems,
+  accumulatedPositionValue,
+  accumulatedPositionReservedValue,
+  accumulatedTransferStates,
+  settlementParticipantPosition,
+  settlementModel,
+  participantLimit
+) => {
+  const transferStateChanges = []
+  const participantPositionChanges = []
+  const resultMessages = []
+  const limitAlarms = []
+  const accumulatedTransferStatesCopy = Object.assign({}, accumulatedTransferStates)
+
+  let currentPosition = new MLNumber(accumulatedPositionValue)
+  const reservedPosition = new MLNumber(accumulatedPositionReservedValue)
+  const effectivePosition = new MLNumber(currentPosition.add(reservedPosition).toFixed(Config.AMOUNT.SCALE))
+  const liquidityCover = new MLNumber(settlementParticipantPosition).multiply(-1)
+  const payerLimit = new MLNumber(participantLimit.value)
+  let availablePositionBasedOnLiquidityCover = new MLNumber(liquidityCover.subtract(effectivePosition).toFixed(Config.AMOUNT.SCALE))
+  Logger.isInfoEnabled && Logger.info(`processPositionPrepareBin::availablePositionBasedOnLiquidityCover: ${availablePositionBasedOnLiquidityCover}`)
+  let availablePositionBasedOnPayerLimit = new MLNumber(payerLimit.subtract(effectivePosition).toFixed(Config.AMOUNT.SCALE))
+  Logger.isDebugEnabled && Logger.debug(`processPositionPrepareBin::availablePositionBasedOnPayerLimit: ${availablePositionBasedOnPayerLimit}`)
+
+  if (binItems && binItems.length > 0) {
+    for (const binItem of binItems) {
+      let transferStateId
+      let reason
+      let resultMessage
+      const transfer = binItem.decodedPayload
+      Logger.isDebugEnabled && Logger.debug(`processPositionPrepareBin::transfer:processingMessage: ${JSON.stringify(transfer)}`)
+
+      // Check if transfer is in correct state for processing, produce an internal error message
+      if (accumulatedTransferStates[transfer.transferId] !== Enum.Transfers.TransferInternalState.RECEIVED_PREPARE) {
+        Logger.isDebugEnabled && Logger.debug(`processPositionPrepareBin::transferState: ${accumulatedTransferStates[transfer.transferId]} !== ${Enum.Transfers.TransferInternalState.RECEIVED_PREPARE}`)
+
+        transferStateId = Enum.Transfers.TransferInternalState.ABORTED_REJECTED
+        reason = 'Transfer in incorrect state'
+
+        const headers = Utility.Http.SwitchDefaultHeaders(
+          transfer.payerFsp,
+          Enum.Http.HeaderResources.TRANSFERS,
+          Enum.Http.Headers.FSPIOP.SWITCH.value,
+          resourceVersions[Enum.Http.HeaderResources.TRANSFERS].contentVersion
+        )
+        const fspiopError = ErrorHandler.Factory.createFSPIOPError(
+          ErrorHandler.Enums.FSPIOPErrorCodes.INTERNAL_SERVER_ERROR
+        ).toApiErrorObject(Config.ERROR_HANDLING)
+        const state = Utility.StreamingProtocol.createEventState(
+          Enum.Events.EventStatus.FAILURE.status,
+          fspiopError.errorInformation.errorCode,
+          fspiopError.errorInformation.errorDescription
+        )
+        const metadata = Utility.StreamingProtocol.createMetadataWithCorrelatedEvent(
+          transfer.transferId,
+          Enum.Kafka.Topics.NOTIFICATION,
+          Enum.Events.Event.Action.PREPARE,
+          state
+        )
+
+        resultMessage = Utility.StreamingProtocol.createMessage(
+          transfer.transferId,
+          transfer.payeeFsp,
+          transfer.payerFsp,
+          metadata,
+          headers,
+          fspiopError,
+          { id: transfer.transferId },
+          'application/json'
+        )
+        binItem.result = { success: false }
+      // Check if payer has insufficient liquidity, produce an error message and abort transfer
+      } else if (availablePositionBasedOnLiquidityCover.toNumber() < transfer.amount.amount) {
+        transferStateId = Enum.Transfers.TransferInternalState.ABORTED_REJECTED
+        reason = ErrorHandler.Enums.FSPIOPErrorCodes.PAYER_FSP_INSUFFICIENT_LIQUIDITY.message
+
+        const headers = Utility.Http.SwitchDefaultHeaders(
+          transfer.payerFsp,
+          Enum.Http.HeaderResources.TRANSFERS,
+          Enum.Http.Headers.FSPIOP.SWITCH.value,
+          resourceVersions[Enum.Http.HeaderResources.TRANSFERS].contentVersion
+        )
+        const fspiopError = ErrorHandler.Factory.createFSPIOPError(
+          ErrorHandler.Enums.FSPIOPErrorCodes.PAYER_FSP_INSUFFICIENT_LIQUIDITY
+        ).toApiErrorObject(Config.ERROR_HANDLING)
+        const state = Utility.StreamingProtocol.createEventState(
+          Enum.Events.EventStatus.FAILURE.status,
+          fspiopError.errorInformation.errorCode,
+          fspiopError.errorInformation.errorDescription
+        )
+        const metadata = Utility.StreamingProtocol.createMetadataWithCorrelatedEvent(
+          transfer.transferId,
+          Enum.Kafka.Topics.NOTIFICATION,
+          Enum.Events.Event.Action.PREPARE,
+          state
+        )
+
+        resultMessage = Utility.StreamingProtocol.createMessage(
+          transfer.transferId,
+          transfer.payeeFsp,
+          transfer.payerFsp,
+          metadata,
+          headers,
+          fspiopError,
+          { id: transfer.transferId },
+          'application/json'
+        )
+        binItem.result = { success: false }
+      // Check if payer has surpassed their limit, produce an error message and abort transfer
+      } else if (availablePositionBasedOnPayerLimit.toNumber() < transfer.amount.amount) {
+        transferStateId = Enum.Transfers.TransferInternalState.ABORTED_REJECTED
+        reason = ErrorHandler.Enums.FSPIOPErrorCodes.PAYER_LIMIT_ERROR.message
+
+        const headers = Utility.Http.SwitchDefaultHeaders(
+          transfer.payerFsp,
+          Enum.Http.HeaderResources.TRANSFERS,
+          Enum.Http.Headers.FSPIOP.SWITCH.value,
+          resourceVersions[Enum.Http.HeaderResources.TRANSFERS].contentVersion
+        )
+        const fspiopError = ErrorHandler.Factory.createFSPIOPError(
+          ErrorHandler.Enums.FSPIOPErrorCodes.PAYER_LIMIT_ERROR
+        ).toApiErrorObject(Config.ERROR_HANDLING)
+        const state = Utility.StreamingProtocol.createEventState(
+          Enum.Events.EventStatus.FAILURE.status,
+          fspiopError.errorInformation.errorCode,
+          fspiopError.errorInformation.errorDescription
+        )
+        const metadata = Utility.StreamingProtocol.createMetadataWithCorrelatedEvent(
+          transfer.transferId,
+          Enum.Kafka.Topics.NOTIFICATION,
+          Enum.Events.Event.Action.PREPARE,
+          state
+        )
+
+        resultMessage = Utility.StreamingProtocol.createMessage(
+          transfer.transferId,
+          transfer.payeeFsp,
+          transfer.payerFsp,
+          metadata,
+          headers,
+          fspiopError,
+          { id: transfer.transferId },
+          'application/json'
+        )
+        binItem.result = { success: false }
+      // Payer has sufficient liquidity and limit
+      } else {
+        transferStateId = Enum.Transfers.TransferState.RESERVED
+        currentPosition = currentPosition.add(transfer.amount.amount)
+        availablePositionBasedOnLiquidityCover = availablePositionBasedOnLiquidityCover.add(transfer.amount.amount)
+        availablePositionBasedOnPayerLimit = availablePositionBasedOnPayerLimit.add(transfer.amount.amount)
+
+        // Are these the right headers?
+        const headers = Utility.Http.SwitchDefaultHeaders(
+          transfer.payeeFsp,
+          Enum.Http.HeaderResources.TRANSFERS,
+          transfer.payerFsp,
+          resourceVersions[Enum.Http.HeaderResources.TRANSFERS].contentVersion
+        )
+        const state = Utility.StreamingProtocol.createEventState(
+          Enum.Events.EventStatus.SUCCESS.status,
+          null,
+          null
+        )
+        const metadata = Utility.StreamingProtocol.createMetadataWithCorrelatedEvent(
+          transfer.transferId,
+          Enum.Kafka.Topics.TRANSFER,
+          Enum.Events.Event.Action.PREPARE,
+          state
+        )
+
+        resultMessage = Utility.StreamingProtocol.createMessage(
+          transfer.transferId,
+          transfer.payeeFsp,
+          transfer.payerFsp,
+          metadata,
+          headers,
+          transfer,
+          {},
+          'application/json'
+        )
+
+        const participantPositionChange = {
+          transferId: transfer.transferId, // Need to delete this in bin processor while updating transferStateChangeId
+          transferStateChangeId: null, // Need to update this in bin processor while executing queries
+          value: currentPosition.toNumber(),
+          reservedValue: accumulatedPositionReservedValue
+        }
+        participantPositionChanges.push(participantPositionChange)
+        Logger.isDebugEnabled && Logger.debug(`processPositionPrepareBin::participantPositionChange: ${JSON.stringify(participantPositionChange)}`)
+        binItem.result = { success: true }
+      }
+
+      resultMessages.push({ binItem, message: resultMessage })
+
+      const transferStateChange = {
+        transferId: transfer.transferId,
+        transferStateId,
+        reason
+      }
+      transferStateChanges.push(transferStateChange)
+      Logger.isDebugEnabled && Logger.debug(`processPositionPrepareBin::transferStateChange: ${JSON.stringify(transferStateChange)}`)
+
+      Logger.isDebugEnabled && Logger.debug(`processPositionPrepareBin::limitAlarm: ${currentPosition.toNumber()} > ${liquidityCover.multiply(participantLimit.thresholdAlarmPercentage)}`)
+      if (currentPosition.toNumber() > liquidityCover.multiply(participantLimit.thresholdAlarmPercentage).toNumber()) {
+        limitAlarms.push(participantLimit)
+      }
+
+      accumulatedTransferStatesCopy[transfer.transferId] = transferStateId
+      Logger.isDebugEnabled && Logger.debug(`processPositionPrepareBin::accumulatedTransferStatesCopy:finalizedTransferState ${JSON.stringify(transferStateId)}`)
+    }
+  }
+
+  return {
+    accumulatedPositionValue: currentPosition.toNumber(),
+    accumulatedTransferStates: accumulatedTransferStatesCopy, // finalized transfer state after prepare processing
+    accumulatedPositionReservedValue, // not used but kept for consistency
+    accumulatedTransferStateChanges: transferStateChanges, // transfer state changes to be persisted in order
+    limitAlarms, // array of participant limits that have been breached
+    accumulatedPositionChanges: participantPositionChanges, // participant position changes to be persisted in order
+    notifyMessages: resultMessages // array of objects containing bin item and result message. {binItem, message}
+  }
+}
+
+module.exports = {
+  processPositionPrepareBin
+}

package/src/handlers/index.js

@@ -52,6 +52,7 @@ Program.command('handler') // sub-command name, coffeeType = type, required
   .description('Start a specified Handler') // command description
   .option('--prepare', 'Start the Prepare Handler')
   .option('--position', 'Start the Position Handler')
+  .option('--positionbatch', 'Start the Position Batch Handler')
   .option('--get', 'Start the Transfer Get Handler')
   .option('--fulfil', 'Start the Fulfil Handler')
   .option('--timeout', 'Start the Timeout Handler')
@@ -81,6 +82,14 @@ Program.command('handler') // sub-command name, coffeeType = type, required
       }
       handlerList.push(handler)
     }
+    if (args.positionbatch) {
+      Logger.isDebugEnabled && Logger.debug('CLI: Executing --positionbatch')
+      const handler = {
+        type: 'positionbatch',
+        enabled: true
+      }
+      handlerList.push(handler)
+    }
     if (args.get) {
       Logger.isDebugEnabled && Logger.debug('CLI: Executing --get')
       const handler = {

package/src/handlers/positions/handlerBatch.js

@@ -0,0 +1,232 @@
+/*****
+ License
+ --------------
+ Copyright © 2017 Bill & Melinda Gates Foundation
+ The Mojaloop files are made available by the Bill & Melinda Gates Foundation under the Apache License, Version 2.0 (the "License") and you may not use these files except in compliance with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, the Mojaloop files are distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+
+ Contributors
+ --------------
+ This is the official list of the Mojaloop project contributors for this file.
+ Names of the original copyright holders (individuals or organizations)
+ should be listed with a '*' in the first column. People who have
+ contributed from an organization can be listed under the organization
+ that actually holds the copyright for their contributions (see the
+ Gates Foundation organization for an example). Those individuals should have
+ their names indented and be marked with a '-'. Email address can be added
+ optionally within square brackets <email>.
+
+ * Gates Foundation
+ - Name Surname <name.surname@gatesfoundation.com>
+
+ * INFITX
+ - Vijay Kumar Guthi <vijaya.guthi@infitx.com>
+
+ --------------
+ ******/
+'use strict'
+
+/**
+ * @module src/handlers/positions
+ */
+
+const Logger = require('@mojaloop/central-services-logger')
+const EventSdk = require('@mojaloop/event-sdk')
+const BinProcessor = require('../../domain/position/binProcessor')
+const SettlementModelCached = require('../../models/settlement/settlementModelCached')
+const Utility = require('@mojaloop/central-services-shared').Util
+const Kafka = require('@mojaloop/central-services-shared').Util.Kafka
+const Producer = require('@mojaloop/central-services-stream').Util.Producer
+const Consumer = require('@mojaloop/central-services-stream').Util.Consumer
+const Enum = require('@mojaloop/central-services-shared').Enum
+const Metrics = require('@mojaloop/central-services-metrics')
+const Config = require('../../lib/config')
+const Uuid = require('uuid4')
+// const decodePayload = require('@mojaloop/central-services-shared').Util.StreamingProtocol.decodePayload
+// const decodeMessages = require('@mojaloop/central-services-shared').Util.StreamingProtocol.decodeMessages
+const ErrorHandler = require('@mojaloop/central-services-error-handling')
+// const location = { module: 'PositionHandler', method: '', path: '' } // var object used as pointer
+const BatchPositionModel = require('../../models/position/batch')
+const decodePayload = require('@mojaloop/central-services-shared').Util.StreamingProtocol.decodePayload
+
+const consumerCommit = true
+// const fromSwitch = true
+
+/**
+ * @function positions
+ *
+ * @async
+ * @description This is the consumer callback function that gets registered to a topic. This then gets a list of messages.
+ *
+ * @param {error} error - error thrown if something fails within Kafka
+ * @param {array} messages - a list of messages to consume for the relevant topic
+ *
+ * @returns {object} - Returns a boolean: true if successful, or throws and error if failed
+ */
+
+const positions = async (error, messages) => {
+  const histTimerEnd = Metrics.getHistogram(
+    'transfer_position_batch',
+    'Consume a batch of prepare transfer messages from the kafka topic and process them',
+    ['success']
+  ).startTimer()
+
+  if (error) {
+    histTimerEnd({ success: false })
+    throw ErrorHandler.Factory.reformatFSPIOPError(error)
+  }
+  let consumedMessages = []
+
+  if (Array.isArray(messages)) {
+    consumedMessages = Array.from(messages)
+  } else {
+    consumedMessages = [Object.assign({}, Utility.clone(messages))]
+  }
+
+  const firstMessageOffset = consumedMessages[0]?.offset
+  const lastMessageOffset = consumedMessages[consumedMessages.length - 1]?.offset
+  const binId = `${firstMessageOffset}-${lastMessageOffset}`
+
+  // TODO: How to handle spans and audits for batch of messages ??
+  // Currently we have to create a span and do and audit for each message
+
+  // Iterate through consumedMessages
+  const bins = {}
+  for (const message of consumedMessages) {
+    const histTimerMsgEnd = Metrics.getHistogram(
+      'transfer_position',
+      'Process a prepare transfer message',
+      ['success', 'action']
+    ).startTimer()
+    // Create a span for each message
+    const contextFromMessage = EventSdk.Tracer.extractContextFromMessage(message.value)
+    const span = EventSdk.Tracer.createChildSpanFromContext('cl_transfer_position', contextFromMessage)
+    span.setTags({
+      processedAsBatch: true,
+      binId
+    })
+    // 1. Assign message to account-bin by accountID and child action-bin by action
+    //    (References to the messages to be stored in bins, no duplication of messages)
+    const accountID = message.key.toString()
+    const action = message.value.metadata.event.action
+
+    const accountBin = bins[accountID] || (bins[accountID] = {})
+    const actionBin = accountBin[action] || (accountBin[action] = [])
+    // Decode the payload and pass it as a separate parameter
+    const decodedPayload = decodePayload(message.value.content.payload)
+    actionBin.push({
+      message,
+      decodedPayload,
+      span,
+      result: {},
+      histTimerMsgEnd
+    })
+
+    await span.audit(message, EventSdk.AuditEventAction.start)
+  }
+
+  // 3. Start DB Transaction
+  const trx = await BatchPositionModel.startDbTransaction()
+
+  try {
+    // 4. Call Bin Processor with the list of account-bins and trx
+    // const decodedMessages = decodeMessages(consumedMessages)
+    const result = await BinProcessor.processBins(bins, trx)
+
+    // 5. If Bin Processor processed bins successfully
+    //   - 5.1. Commit Kafka offset
+    // Commit the offset of last message in the array
+    const lastMessageToCommit = consumedMessages[consumedMessages.length - 1]
+    const params = { message: lastMessageToCommit, kafkaTopic: lastMessageToCommit.topic, consumer: Consumer }
+    // We are using Kafka.proceed() to just commit the offset of the last message in the array
+    await Kafka.proceed(Config.KAFKA_CONFIG, params, { consumerCommit })
+
+    //   - 5.2. Commit DB transaction
+    await trx.commit()
+
+    //   - 5.3. Loop through results and produce notification messages and audit messages
+    for (const item of result.notifyMessages) {
+      // 5.3.1. Produce notification message and audit message
+      const action = item.binItem.message?.value.metadata.event.action
+      await Kafka.produceGeneralMessage(Config.KAFKA_CONFIG, Producer, Enum.Events.Event.Type.NOTIFICATION, action, item.message, Enum.Events.EventStatus.SUCCESS, null, item.binItem.span)
+    }
+    histTimerEnd({ success: true })
+  } catch (err) {
+    // 6. If Bin Processor returns failure
+    // 6.1. Rollback DB transaction
+    await trx.rollback()
+
+    // 6.2. Audit Error for each message
+    const fspiopError = ErrorHandler.Factory.reformatFSPIOPError(err)
+    const state = new EventSdk.EventStateMetadata(EventSdk.EventStatusType.failed, fspiopError.apiErrorCode.code, fspiopError.apiErrorCode.message)
+    await BinProcessor.iterateThroughBins(bins, async (_accountID, _action, item) => {
+      const span = item.span
+      await span.error(fspiopError, state)
+    })
+    histTimerEnd({ success: false })
+  } finally {
+    // Finish span for each message
+    await BinProcessor.iterateThroughBins(bins, async (_accountID, action, item) => {
+      item.histTimerMsgEnd({ ...item.result, action })
+      const span = item.span
+      if (!span.isFinished) {
+        await span.finish()
+      }
+    })
+  }
+}
+
+/**
+ * @function registerPositionHandler
+ *
+ * @async
+ * @description Registers the handler for position topic. Gets Kafka config from default.json
+ *
+ * @returns {boolean} - Returns a boolean: true if successful, or throws and error if failed
+ */
+const registerPositionHandler = async () => {
+  try {
+    await SettlementModelCached.initialize()
+    const positionHandler = {
+      command: positions,
+      // topicName: Kafka.transformGeneralTopicName(Config.KAFKA_CONFIG.TOPIC_TEMPLATES.GENERAL_TOPIC_TEMPLATE.TEMPLATE, Enum.Events.Event.Type.POSITION, Enum.Events.Event.Action.PREPARE),
+      // TODO: If there is no mapping, use default transformGeneralTopicName
+      topicName: Config.KAFKA_CONFIG.EVENT_TYPE_ACTION_TOPIC_MAP?.POSITION?.PREPARE,
+      // config: Kafka.getKafkaConfig(Config.KAFKA_CONFIG, Enum.Kafka.Config.CONSUMER, Enum.Events.Event.Type.TRANSFER.toUpperCase(), Enum.Events.Event.Action.POSITION.toUpperCase())
+      // There is no corresponding action for POSITION_BATCH, so using straight value
+      config: Kafka.getKafkaConfig(Config.KAFKA_CONFIG, Enum.Kafka.Config.CONSUMER, Enum.Events.Event.Type.TRANSFER.toUpperCase(), 'POSITION_BATCH')
+    }
+    positionHandler.config.rdkafkaConf['client.id'] = `${positionHandler.config.rdkafkaConf['client.id']}-${Uuid()}`
+    await Consumer.createHandler(positionHandler.topicName, positionHandler.config, positionHandler.command)
+    return true
+  } catch (err) {
+    Logger.isErrorEnabled && Logger.error(err)
+    throw ErrorHandler.Factory.reformatFSPIOPError(err)
+  }
+}
+
+/**
+ * @function RegisterAllHandlers
+ *
+ * @async
+ * @description Registers all handlers in positions
+ *
+ * @returns {boolean} - Returns a boolean: true if successful, or throws and error if failed
+ */
+const registerAllHandlers = async () => {
+  try {
+    return await registerPositionHandler()
+  } catch (err) {
+    Logger.isErrorEnabled && Logger.error(err)
+    throw ErrorHandler.Factory.reformatFSPIOPError(err)
+  }
+}
+
+module.exports = {
+  registerPositionHandler,
+  registerAllHandlers,
+  positions
+}

package/src/handlers/register.js

@@ -50,6 +50,7 @@ const Logger = require('@mojaloop/central-services-logger')
 const requireGlob = require('require-glob')
 const TransferHandlers = require('./transfers/handler')
 const PositionHandlers = require('./positions/handler')
+const PositionHandlersBatch = require('./positions/handlerBatch')
 const TimeoutHandlers = require('./timeouts/handler')
 const AdminHandlers = require('./admin/handler')
 const BulkHandlers = require('./bulk')
@@ -90,6 +91,10 @@ module.exports = {
     registerAllHandlers: PositionHandlers.registerAllHandlers,
     registerPositionHandler: PositionHandlers.registerPositionHandler
   },
+  positionsBatch: {
+    registerAllHandlers: PositionHandlersBatch.registerAllHandlers,
+    registerPositionHandler: PositionHandlersBatch.registerPositionHandler
+  },
   timeouts: {
     registerAllHandlers: TimeoutHandlers.registerAllHandlers,
     registerTimeoutHandler: TimeoutHandlers.registerTimeoutHandler

package/src/models/participant/facade.js

@@ -308,7 +308,7 @@ const getParticipantLimitByParticipantCurrencyLimit = async (participantId, curr
 
       /* Checkpoint #1: participant found and is active */
       if ((participant) && (participant.isActive)) {
-        /* use the paricipant id and incoming params to prepare the filter */
+        /* use the participant id and incoming params to prepare the filter */
         const searchFilter = {
           participantId: participant.participantId,
           currencyId,

package/src/models/position/batch.js

@@ -0,0 +1,125 @@
+/*****
+ License
+ --------------
+ Copyright © 2017 Bill & Melinda Gates Foundation
+ The Mojaloop files are made available by the Bill & Melinda Gates Foundation under the Apache License, Version 2.0 (the "License") and you may not use these files except in compliance with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, the Mojaloop files are distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+
+ Contributors
+ --------------
+ This is the official list of the Mojaloop project contributors for this file.
+ Names of the original copyright holders (individuals or organizations)
+ should be listed with a '*' in the first column. People who have
+ contributed from an organization can be listed under the organization
+ that actually holds the copyright for their contributions (see the
+ Gates Foundation organization for an example). Those individuals should have
+ their names indented and be marked with a '-'. Email address can be added
+ optionally within square brackets <email>.
+
+ * Gates Foundation
+ - Name Surname <name.surname@gatesfoundation.com>
+
+ * INFITX
+ - Vijay Kumar Guthi <vijaya.guthi@infitx.com>
+
+ --------------
+ ******/
+
+'use strict'
+
+const Db = require('../../lib/db')
+const Logger = require('@mojaloop/central-services-logger')
+
+const startDbTransaction = async () => {
+  const knex = await Db.getKnex()
+  const trx = await knex.transaction()
+  return trx
+}
+
+const getLatestTransferStateChangesByTransferIdList = async (trx, transfersIdList) => {
+  const knex = await Db.getKnex()
+  try {
+    const latestTransferStateChanges = {}
+    const results = await knex('transferStateChange')
+      .transacting(trx)
+      .whereIn('transferStateChange.transferId', transfersIdList)
+      .orderBy('transferStateChangeId', 'desc')
+      .select('*')
+
+    for (const result of results) {
+      if (!latestTransferStateChanges[result.transferId]) {
+        latestTransferStateChanges[result.transferId] = result
+      }
+    }
+    return latestTransferStateChanges
+  } catch (err) {
+    Logger.isErrorEnabled && Logger.error(err)
+    throw err
+  }
+}
+
+const getAllParticipantCurrency = async (trx) => {
+  const knex = await Db.getKnex()
+  if (trx) {
+    const result = await knex('participantCurrency')
+      .transacting(trx)
+      .select('*')
+    return result
+  } else {
+    const result = await knex('participantCurrency')
+      .select('*')
+    return result
+  }
+}
+
+const getPositionsByAccountIdsForUpdate = async (trx, accountIds) => {
+  const knex = await Db.getKnex()
+  const participantPositions = await knex('participantPosition')
+    .transacting(trx)
+    .whereIn('participantCurrencyId', accountIds)
+    .forUpdate()
+    .select('*')
+  const positions = {}
+  for (const position of participantPositions) {
+    positions[position.participantCurrencyId] = position
+  }
+  return positions
+}
+
+const updateParticipantPosition = async (trx, participantPositionId, participantPositionValue, participantPositionReservedValue = null) => {
+  const knex = await Db.getKnex()
+  const optionalValues = {}
+  if (participantPositionReservedValue !== null) {
+    optionalValues.reservedValue = participantPositionReservedValue
+  }
+  return await knex('participantPosition').transacting(trx)
+    .where({ participantPositionId })
+    .update({
+      value: participantPositionValue,
+      ...optionalValues,
+      changedDate: new Date()
+    })
+}
+
+const bulkInsertTransferStateChanges = async (trx, transferStateChangeList) => {
+  const knex = await Db.getKnex()
+  return await knex.batchInsert('transferStateChange', transferStateChangeList).transacting(trx)
+}
+
+const bulkInsertParticipantPositionChanges = async (trx, participantPositionChangeList) => {
+  const knex = await Db.getKnex()
+  return await knex.batchInsert('participantPositionChange', participantPositionChangeList).transacting(trx)
+}
+
+module.exports = {
+  startDbTransaction,
+  getLatestTransferStateChangesByTransferIdList,
+  getPositionsByAccountIdsForUpdate,
+  updateParticipantPosition,
+  bulkInsertTransferStateChanges,
+  bulkInsertParticipantPositionChanges,
+  getAllParticipantCurrency
+}

package/src/models/position/batchCached.js

@@ -0,0 +1,134 @@
+/*****
+ License
+ --------------
+ Copyright © 2017 Bill & Melinda Gates Foundation
+ The Mojaloop files are made available by the Bill & Melinda Gates Foundation under the Apache License, Version 2.0 (the "License") and you may not use these files except in compliance with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, the Mojaloop files are distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+
+ Contributors
+ --------------
+ This is the official list of the Mojaloop project contributors for this file.
+ Names of the original copyright holders (individuals or organizations)
+ should be listed with a '*' in the first column. People who have
+ contributed from an organization can be listed under the organization
+ that actually holds the copyright for their contributions (see the
+ Gates Foundation organization for an example). Those individuals should have
+ their names indented and be marked with a '-'. Email address can be added
+ optionally within square brackets <email>.
+
+ * Gates Foundation
+ - Name Surname <name.surname@gatesfoundation.com>
+
+ * INFITX
+ - Kevin Leyow <kevin.leyow@infitx.com>
+
+ --------------
+ ******/
+
+'use strict'
+
+const ErrorHandler = require('@mojaloop/central-services-error-handling')
+const Cache = require('../../lib/cache')
+const Metrics = require('@mojaloop/central-services-metrics')
+const BatchPositionModel = require('./batch')
+
+let cacheClient
+let participantCurrencyAllCacheKey
+
+/*
+  Private API
+*/
+
+const buildUnifiedParticipantCurrencyData = (allParticipantCurrency) => {
+  // build indexes (or indices?) - optimization for byId and byName access
+  const indexById = {}
+  const indexByParticipantId = {}
+
+  for (const oneParticipantCurrency of allParticipantCurrency) {
+    // Participant API returns Date type, but cache internals will serialize it to String
+    // by calling JSON.stringify(), which calls .toISOString() on a Date object.
+    // Let's ensure all places return same kind of String.
+    oneParticipantCurrency.createdDate = JSON.stringify(oneParticipantCurrency.createdDate)
+
+    // Add to indexes
+    if (!(oneParticipantCurrency.participantId in indexByParticipantId)) {
+      indexByParticipantId[oneParticipantCurrency.participantId] = []
+    }
+    indexByParticipantId[oneParticipantCurrency.participantId].push(oneParticipantCurrency)
+    indexById[oneParticipantCurrency.participantCurrencyId] = oneParticipantCurrency
+  }
+
+  // build unified structure - indexes + data
+  const unifiedParticipantsCurrency = {
+    indexById,
+    indexByParticipantId,
+    allParticipantCurrency
+  }
+  return unifiedParticipantsCurrency
+}
+
+const getParticipantCurrencyCached = async (trx) => {
+  const histTimer = Metrics.getHistogram(
+    'model_participant_batch',
+    'model_getParticipantsCached - Metrics for participant model',
+    ['success', 'queryName', 'hit']
+  ).startTimer()
+  // Do we have valid participants list in the cache ?
+  let cachedParticipantCurrency = cacheClient.get(participantCurrencyAllCacheKey)
+  if (!cachedParticipantCurrency) {
+    const allParticipantCurrency = await BatchPositionModel.getAllParticipantCurrency(trx)
+    cachedParticipantCurrency = buildUnifiedParticipantCurrencyData(allParticipantCurrency)
+
+    // store in cache
+    cacheClient.set(participantCurrencyAllCacheKey, cachedParticipantCurrency)
+    histTimer({ success: true, queryName: 'model_getParticipantCurrencyBatchCached', hit: false })
+  } else {
+    // unwrap participants list from catbox structure
+    cachedParticipantCurrency = cachedParticipantCurrency.item
+    histTimer({ success: true, queryName: 'model_getParticipantCurrencyBatchCached', hit: true })
+  }
+  return cachedParticipantCurrency
+}
+
+/*
+  Public API
+*/
+exports.initialize = async () => {
+  /* Register as cache client */
+  const participantCurrencyCacheClientMeta = {
+    id: 'participantCurrency',
+    preloadCache: getParticipantCurrencyCached
+  }
+
+  cacheClient = Cache.registerCacheClient(participantCurrencyCacheClientMeta)
+  participantCurrencyAllCacheKey = cacheClient.createKey('participantCurrency')
+}
+
+exports.getParticipantCurrencyByIds = async (trx, participantCurrencyIds) => {
+  try {
+    let participantCurrencies = []
+    const cachedParticipantCurrency = await getParticipantCurrencyCached(trx)
+    for (const participantCurrencyId of participantCurrencyIds) {
+      participantCurrencies = participantCurrencies.concat(cachedParticipantCurrency.indexById[participantCurrencyId])
+    }
+    return participantCurrencies
+  } catch (err) {
+    throw ErrorHandler.Factory.reformatFSPIOPError(err)
+  }
+}
+
+exports.getParticipantCurrencyByParticipantIds = async (trx, participantIds) => {
+  try {
+    let participantCurrencies = []
+    const cachedParticipantCurrency = await getParticipantCurrencyCached(trx)
+    for (const participantId of participantIds) {
+      participantCurrencies = participantCurrencies.concat(cachedParticipantCurrency.indexByParticipantId[participantId])
+    }
+    return participantCurrencies
+  } catch (err) {
+    throw ErrorHandler.Factory.reformatFSPIOPError(err)
+  }
+}

package/src/models/settlement/settlementModelCached.js

@@ -42,12 +42,12 @@ const buildUnifiedSettlementModelsData = (allSettlementModels) => {
   const indexByName = {}
   const indexByLedgerAccountTypeId = {}
 
-  allSettlementModels.forEach((oneSettlementModel) => {
+  for (const oneSettlementModel of allSettlementModels) {
     // Add to indexes
     indexById[oneSettlementModel.settlementModelId] = oneSettlementModel
     indexByName[oneSettlementModel.name] = oneSettlementModel
     indexByLedgerAccountTypeId[oneSettlementModel.ledgerAccountTypeId] = oneSettlementModel
-  })
+  }
 
   // build unified structure - indexes + data
   const unifiedSettlementModels = {

package/src/shared/setup.js

@@ -51,6 +51,7 @@ const EnumCached = require('../lib/enumCached')
 const ParticipantCached = require('../models/participant/participantCached')
 const ParticipantCurrencyCached = require('../models/participant/participantCurrencyCached')
 const ParticipantLimitCached = require('../models/participant/participantLimitCached')
+const BatchPositionModelCached = require('../models/position/batchCached')
 const MongoUriBuilder = require('mongo-uri-builder')
 
 const migrate = (runMigrations) => {
@@ -175,6 +176,10 @@ const createHandlers = async (handlers) => {
           // }
           break
         }
+        case 'positionbatch': {
+          await RegisterHandlers.positionsBatch.registerPositionHandler()
+          break
+        }
         case 'fulfil': {
           await RegisterHandlers.transfers.registerFulfilHandler()
           break
@@ -230,6 +235,7 @@ const initializeCache = async () => {
   await ParticipantCached.initialize()
   await ParticipantCurrencyCached.initialize()
   await ParticipantLimitCached.initialize()
+  await BatchPositionModelCached.initialize()
   await Cache.initCache()
 }