@mojaloop/central-ledger 17.7.8 → 17.8.0-orb.1

package/src/domain/position/fx-prepare.js

@@ -0,0 +1,280 @@
+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 MLNumber = require('@mojaloop/ml-number')
+const Logger = require('@mojaloop/central-services-logger')
+
+/**
+ * @function processFxPositionPrepareBin
+ *
+ * @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, decodedPayload, span}
+ * @param {object} options
+ *   @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} accumulatedFxTransferStates - object with fx commit request id keys and fx transfer state id values. Used to check if fx 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} participantLimit - participant limit object for the currency
+ *   @param {boolean} changePositions - whether to change positions or not
+ * @returns {object} - Returns an object containing accumulatedPositionValue, accumulatedPositionReservedValue, accumulatedFxTransferStateChanges, accumulatedTransferStates, resultMessages, limitAlarms or throws an error if failed
+ */
+const processFxPositionPrepareBin = async (
+  binItems,
+  {
+    accumulatedPositionValue,
+    accumulatedPositionReservedValue,
+    accumulatedFxTransferStates,
+    settlementParticipantPosition,
+    participantLimit,
+    changePositions = true
+  }
+) => {
+  const fxTransferStateChanges = []
+  const participantPositionChanges = []
+  const resultMessages = []
+  const limitAlarms = []
+  const accumulatedFxTransferStatesCopy = Object.assign({}, accumulatedFxTransferStates)
+
+  let currentPosition = new MLNumber(accumulatedPositionValue)
+  let liquidityCover = 0
+  let availablePositionBasedOnLiquidityCover = 0
+  let availablePositionBasedOnPayerLimit = 0
+
+  if (changePositions) {
+    const reservedPosition = new MLNumber(accumulatedPositionReservedValue)
+    const effectivePosition = new MLNumber(currentPosition.add(reservedPosition).toFixed(Config.AMOUNT.SCALE))
+    const payerLimit = new MLNumber(participantLimit.value)
+    liquidityCover = new MLNumber(settlementParticipantPosition).multiply(-1)
+    availablePositionBasedOnLiquidityCover = new MLNumber(liquidityCover.subtract(effectivePosition).toFixed(Config.AMOUNT.SCALE))
+    Logger.isInfoEnabled && Logger.info(`processFxPositionPrepareBin::availablePositionBasedOnLiquidityCover: ${availablePositionBasedOnLiquidityCover}`)
+    availablePositionBasedOnPayerLimit = new MLNumber(payerLimit.subtract(effectivePosition).toFixed(Config.AMOUNT.SCALE))
+    Logger.isDebugEnabled && Logger.debug(`processFxPositionPrepareBin::availablePositionBasedOnPayerLimit: ${availablePositionBasedOnPayerLimit}`)
+  }
+
+  if (binItems && binItems.length > 0) {
+    for (const binItem of binItems) {
+      let transferStateId
+      let reason
+      let resultMessage
+      const fxTransfer = binItem.decodedPayload
+      const cyrilResult = binItem.message.value.content.context.cyrilResult
+      const transferAmount = fxTransfer.targetAmount.currency === cyrilResult.currencyId ? fxTransfer.targetAmount.amount : fxTransfer.sourceAmount.amount
+
+      Logger.isDebugEnabled && Logger.debug(`processFxPositionPrepareBin::transfer:processingMessage: ${JSON.stringify(fxTransfer)}`)
+
+      // Check if fxTransfer is in correct state for processing, produce an internal error message
+      if (accumulatedFxTransferStates[fxTransfer.commitRequestId] !== Enum.Transfers.TransferInternalState.RECEIVED_PREPARE) {
+        Logger.isDebugEnabled && Logger.debug(`processFxPositionPrepareBin::transferState: ${accumulatedFxTransferStates[fxTransfer.commitRequestId]} !== ${Enum.Transfers.TransferInternalState.RECEIVED_PREPARE}`)
+
+        transferStateId = Enum.Transfers.TransferInternalState.ABORTED_REJECTED
+        reason = 'FxTransfer in incorrect state'
+
+        // forward same headers from the prepare message, except the content-length header
+        // set destination to initiatingFsp and source to switch
+        const headers = { ...binItem.message.value.content.headers }
+        headers[Enum.Http.Headers.FSPIOP.DESTINATION] = fxTransfer.initiatingFsp
+        headers[Enum.Http.Headers.FSPIOP.SOURCE] = Config.HUB_NAME
+        delete headers['content-length']
+
+        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(
+          fxTransfer.commitRequestId,
+          Enum.Kafka.Topics.NOTIFICATION,
+          Enum.Events.Event.Action.FX_PREPARE,
+          state
+        )
+
+        resultMessage = Utility.StreamingProtocol.createMessage(
+          fxTransfer.commitRequestId,
+          fxTransfer.initiatingFsp,
+          Config.HUB_NAME,
+          metadata,
+          headers,
+          fspiopError,
+          { id: fxTransfer.commitRequestId },
+          'application/json'
+        )
+
+        binItem.result = { success: false }
+
+        // Check if payer has insufficient liquidity, produce an error message and abort transfer
+      } else if (changePositions && availablePositionBasedOnLiquidityCover.toNumber() < transferAmount) {
+        transferStateId = Enum.Transfers.TransferInternalState.ABORTED_REJECTED
+        reason = ErrorHandler.Enums.FSPIOPErrorCodes.PAYER_FSP_INSUFFICIENT_LIQUIDITY.message
+
+        // forward same headers from the prepare message, except the content-length header
+        // set destination to payerfsp and source to switch
+        const headers = { ...binItem.message.value.content.headers }
+        headers[Enum.Http.Headers.FSPIOP.DESTINATION] = fxTransfer.initiatingFsp
+        headers[Enum.Http.Headers.FSPIOP.SOURCE] = Config.HUB_NAME
+        delete headers['content-length']
+
+        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(
+          fxTransfer.commitRequestId,
+          Enum.Kafka.Topics.NOTIFICATION,
+          Enum.Events.Event.Action.FX_PREPARE,
+          state
+        )
+
+        resultMessage = Utility.StreamingProtocol.createMessage(
+          fxTransfer.commitRequestId,
+          fxTransfer.initiatingFsp,
+          Config.HUB_NAME,
+          metadata,
+          headers,
+          fspiopError,
+          { id: fxTransfer.commitRequestId },
+          'application/json'
+        )
+
+        binItem.result = { success: false }
+
+        // Check if payer has surpassed their limit, produce an error message and abort transfer
+      } else if (changePositions && availablePositionBasedOnPayerLimit.toNumber() < transferAmount) {
+        transferStateId = Enum.Transfers.TransferInternalState.ABORTED_REJECTED
+        reason = ErrorHandler.Enums.FSPIOPErrorCodes.PAYER_LIMIT_ERROR.message
+
+        // forward same headers from the prepare message, except the content-length header
+        // set destination to payerfsp and source to switch
+        const headers = { ...binItem.message.value.content.headers }
+        headers[Enum.Http.Headers.FSPIOP.DESTINATION] = fxTransfer.initiatingFsp
+        headers[Enum.Http.Headers.FSPIOP.SOURCE] = Config.HUB_NAME
+        delete headers['content-length']
+
+        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(
+          fxTransfer.commitRequestId,
+          Enum.Kafka.Topics.NOTIFICATION,
+          Enum.Events.Event.Action.FX_PREPARE,
+          state
+        )
+
+        resultMessage = Utility.StreamingProtocol.createMessage(
+          fxTransfer.commitRequestId,
+          fxTransfer.initiatingFsp,
+          Config.HUB_NAME,
+          metadata,
+          headers,
+          fspiopError,
+          { id: fxTransfer.commitRequestId },
+          'application/json'
+        )
+
+        binItem.result = { success: false }
+
+        // Payer has sufficient liquidity and limit
+      } else {
+        transferStateId = Enum.Transfers.TransferInternalState.RESERVED
+
+        if (changePositions) {
+          currentPosition = currentPosition.add(transferAmount)
+          availablePositionBasedOnLiquidityCover = availablePositionBasedOnLiquidityCover.add(transferAmount)
+          availablePositionBasedOnPayerLimit = availablePositionBasedOnPayerLimit.add(transferAmount)
+          const participantPositionChange = {
+            commitRequestId: fxTransfer.commitRequestId, // Need to delete this in bin processor while updating fxTransferStateChangeId
+            fxTransferStateChangeId: null, // Need to update this in bin processor while executing queries
+            value: currentPosition.toNumber(),
+            change: transferAmount,
+            reservedValue: accumulatedPositionReservedValue
+          }
+          participantPositionChanges.push(participantPositionChange)
+          Logger.isDebugEnabled && Logger.debug(`processFxPositionPrepareBin::participantPositionChange: ${JSON.stringify(participantPositionChange)}`)
+        }
+
+        // forward same headers from the prepare message, except the content-length header
+        const headers = { ...binItem.message.value.content.headers }
+        delete headers['content-length']
+
+        const state = Utility.StreamingProtocol.createEventState(
+          Enum.Events.EventStatus.SUCCESS.status,
+          null,
+          null
+        )
+        const metadata = Utility.StreamingProtocol.createMetadataWithCorrelatedEvent(
+          fxTransfer.commitRequestId,
+          Enum.Kafka.Topics.TRANSFER,
+          Enum.Events.Event.Action.FX_PREPARE,
+          state
+        )
+
+        resultMessage = Utility.StreamingProtocol.createMessage(
+          fxTransfer.commitRequestId,
+          fxTransfer.counterPartyFsp,
+          fxTransfer.initiatingFsp,
+          metadata,
+          headers,
+          fxTransfer,
+          {},
+          'application/json'
+        )
+
+        binItem.result = { success: true }
+      }
+
+      resultMessages.push({ binItem, message: resultMessage })
+
+      if (changePositions) {
+        Logger.isDebugEnabled && Logger.debug(`processFxPositionPrepareBin::limitAlarm: ${currentPosition.toNumber()} > ${liquidityCover.multiply(participantLimit.thresholdAlarmPercentage)}`)
+        if (currentPosition.toNumber() > liquidityCover.multiply(participantLimit.thresholdAlarmPercentage).toNumber()) {
+          limitAlarms.push(participantLimit)
+        }
+      }
+
+      const fxTransferStateChange = {
+        commitRequestId: fxTransfer.commitRequestId,
+        transferStateId,
+        reason
+      }
+      fxTransferStateChanges.push(fxTransferStateChange)
+      Logger.isDebugEnabled && Logger.debug(`processFxPositionPrepareBin::fxTransferStateChange: ${JSON.stringify(fxTransferStateChange)}`)
+
+      accumulatedFxTransferStatesCopy[fxTransfer.commitRequestId] = transferStateId
+      Logger.isDebugEnabled && Logger.debug(`processFxPositionPrepareBin::accumulatedTransferStatesCopy:finalizedTransferState ${JSON.stringify(transferStateId)}`)
+    }
+  }
+
+  return {
+    accumulatedPositionValue: changePositions ? currentPosition.toNumber() : accumulatedPositionValue,
+    accumulatedFxTransferStates: accumulatedFxTransferStatesCopy, // finalized transfer state after prepare processing
+    accumulatedPositionReservedValue, // not used but kept for consistency
+    accumulatedFxTransferStateChanges: fxTransferStateChanges, // fx-transfer state changes to be persisted in order
+    limitAlarms, // array of participant limits that have been breached
+    accumulatedPositionChanges: changePositions ? participantPositionChanges : [], // participant position changes to be persisted in order
+    notifyMessages: resultMessages // array of objects containing bin item and result message. {binItem, message}
+  }
+}
+
+module.exports = {
+  processFxPositionPrepareBin
+}

package/src/domain/position/fx-timeout-reserved.js

@@ -0,0 +1,159 @@
+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 MLNumber = require('@mojaloop/ml-number')
+const Logger = require('@mojaloop/central-services-logger')
+
+/**
+ * @function processPositionFxTimeoutReservedBin
+ *
+ * @async
+ * @description This is the domain function to process a bin of timeout-reserved messages of a single participant account.
+ *
+ * @param {array} fxTimeoutReservedBins - an array containing timeout-reserved action bins
+ * @param {object} options
+   * @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} accumulatedFxTransferStates - object with commitRequest id keys and fxTransfer state id values. Used to check if fxTransfer is in correct state for processing. Clone and update states for output.
+   * @param {object} transferInfoList - object with transfer id keys and transfer info values. Used to pass transfer info to domain function.
+   * @param {boolean} changePositions - whether to change positions or not
+ * @returns {object} - Returns an object containing accumulatedPositionValue, accumulatedPositionReservedValue, accumulatedTransferStateChanges, accumulatedFxTransferStates, resultMessages, limitAlarms or throws an error if failed
+ */
+const processPositionFxTimeoutReservedBin = async (
+  fxTimeoutReservedBins,
+  {
+    accumulatedPositionValue,
+    accumulatedPositionReservedValue,
+    accumulatedFxTransferStates,
+    fetchedReservedPositionChangesByCommitRequestIds,
+    changePositions = true
+  }
+) => {
+  const fxTransferStateChanges = []
+  const participantPositionChanges = []
+  const resultMessages = []
+  const accumulatedFxTransferStatesCopy = Object.assign({}, accumulatedFxTransferStates)
+  let runningPosition = new MLNumber(accumulatedPositionValue)
+  // Position action FX_RESERVED_TIMEOUT event messages are keyed with payer account id.
+  // We need to revert the payer's position for the source currency amount of the fxTransfer.
+  // We need to notify the payee of the timeout.
+  if (fxTimeoutReservedBins && fxTimeoutReservedBins.length > 0) {
+    for (const binItem of fxTimeoutReservedBins) {
+      Logger.isDebugEnabled && Logger.debug(`processPositionFxTimeoutReservedBin::binItem: ${JSON.stringify(binItem.message.value)}`)
+      const participantAccountId = binItem.message.key.toString()
+      const commitRequestId = binItem.message.value.content.uriParams.id
+      const counterPartyFsp = binItem.message.value.to
+      const initiatingFsp = binItem.message.value.from
+
+      // If the transfer is not in `RESERVED_TIMEOUT`, a position fx-timeout-reserved message was incorrectly published.
+      // i.e Something has gone extremely wrong.
+      if (accumulatedFxTransferStates[commitRequestId] !== Enum.Transfers.TransferInternalState.RESERVED_TIMEOUT) {
+        throw ErrorHandler.Factory.createInternalServerFSPIOPError(ErrorHandler.Enums.FSPIOPErrorCodes.INTERNAL_SERVER_ERROR.message)
+      } else {
+        Logger.isDebugEnabled && Logger.debug(`accumulatedFxTransferStates: ${JSON.stringify(accumulatedFxTransferStates)}`)
+
+        const transferAmount = fetchedReservedPositionChangesByCommitRequestIds[commitRequestId][participantAccountId].change
+
+        // Construct payee notification message
+        const resultMessage = _constructFxTimeoutReservedResultMessage(
+          binItem,
+          commitRequestId,
+          counterPartyFsp,
+          initiatingFsp
+        )
+        Logger.isDebugEnabled && Logger.debug(`processPositionFxTimeoutReservedBin::resultMessage: ${JSON.stringify(resultMessage)}`)
+
+        // Revert payer's position for the amount of the transfer
+        const { participantPositionChange, fxTransferStateChange, transferStateId, updatedRunningPosition } =
+          _handleParticipantPositionChange(runningPosition, transferAmount, commitRequestId, accumulatedPositionReservedValue)
+        Logger.isDebugEnabled && Logger.debug(`processPositionFxTimeoutReservedBin::participantPositionChange: ${JSON.stringify(participantPositionChange)}`)
+        runningPosition = updatedRunningPosition
+        binItem.result = { success: true }
+        participantPositionChanges.push(participantPositionChange)
+        fxTransferStateChanges.push(fxTransferStateChange)
+        accumulatedFxTransferStatesCopy[commitRequestId] = transferStateId
+        resultMessages.push({ binItem, message: resultMessage })
+      }
+    }
+  }
+
+  return {
+    accumulatedPositionValue: changePositions ? runningPosition.toNumber() : accumulatedPositionValue,
+    accumulatedFxTransferStates: accumulatedFxTransferStatesCopy, // finalized transfer state after fx fulfil processing
+    accumulatedPositionReservedValue, // not used but kept for consistency
+    accumulatedFxTransferStateChanges: fxTransferStateChanges, // fx-transfer state changes to be persisted in order
+    accumulatedPositionChanges: changePositions ? participantPositionChanges : [], // participant position changes to be persisted in order
+    notifyMessages: resultMessages // array of objects containing bin item and result message. {binItem, message}
+  }
+}
+
+const _constructFxTimeoutReservedResultMessage = (binItem, commitRequestId, counterPartyFsp, initiatingFsp) => {
+  // IMPORTANT: This singular message is taken by the ml-api-adapter and used to
+  //            notify the payer and payee of the timeout.
+  //            As long as the `to` and `from` message values are the payer and payee,
+  //            and the action is `timeout-reserved`, the ml-api-adapter will notify both.
+  // Create a FSPIOPError object for timeout payee notification
+  const fspiopError = ErrorHandler.Factory.createFSPIOPError(
+    ErrorHandler.Enums.FSPIOPErrorCodes.TRANSFER_EXPIRED,
+    null,
+    null,
+    null,
+    null
+  ).toApiErrorObject(Config.ERROR_HANDLING)
+
+  const state = Utility.StreamingProtocol.createEventState(
+    Enum.Events.EventStatus.FAILURE.status,
+    fspiopError.errorInformation.errorCode,
+    fspiopError.errorInformation.errorDescription
+  )
+
+  // Create metadata for the message, associating the payee notification
+  // with the position event fx-timeout-reserved action
+  const metadata = Utility.StreamingProtocol.createMetadataWithCorrelatedEvent(
+    commitRequestId,
+    Enum.Kafka.Topics.POSITION,
+    Enum.Events.Event.Action.FX_TIMEOUT_RESERVED,
+    state
+  )
+  const resultMessage = Utility.StreamingProtocol.createMessage(
+    commitRequestId,
+    counterPartyFsp,
+    initiatingFsp,
+    metadata,
+    binItem.message.value.content.headers, // Headers don't really matter here. ml-api-adapter will ignore them and create their own.
+    fspiopError,
+    { id: commitRequestId },
+    'application/json'
+  )
+
+  return resultMessage
+}
+
+const _handleParticipantPositionChange = (runningPosition, transferAmount, commitRequestId, accumulatedPositionReservedValue) => {
+  const transferStateId = Enum.Transfers.TransferInternalState.EXPIRED_RESERVED
+  // Revert payer's position for the amount of the transfer
+  const updatedRunningPosition = new MLNumber(runningPosition.subtract(transferAmount).toFixed(Config.AMOUNT.SCALE))
+  Logger.isDebugEnabled && Logger.debug(`processPositionFxTimeoutReservedBin::_handleParticipantPositionChange::updatedRunningPosition: ${updatedRunningPosition.toString()}`)
+  Logger.isDebugEnabled && Logger.debug(`processPositionFxTimeoutReservedBin::_handleParticipantPositionChange::transferAmount: ${transferAmount}`)
+  // Construct participant position change object
+  const participantPositionChange = {
+    commitRequestId, // Need to delete this in bin processor while updating transferStateChangeId
+    transferStateChangeId: null, // Need to update this in bin processor while executing queries
+    value: updatedRunningPosition.toNumber(),
+    change: transferAmount,
+    reservedValue: accumulatedPositionReservedValue
+  }
+
+  // Construct transfer state change object
+  const fxTransferStateChange = {
+    commitRequestId,
+    transferStateId,
+    reason: ErrorHandler.Enums.FSPIOPErrorCodes.TRANSFER_EXPIRED.message
+  }
+  return { participantPositionChange, fxTransferStateChange, transferStateId, updatedRunningPosition }
+}
+
+module.exports = {
+  processPositionFxTimeoutReservedBin
+}

package/src/domain/position/index.js

@@ -23,6 +23,7 @@
  - Name Surname <name.surname@gatesfoundation.com>
 
  * Shashikant Hirugade <shashikant.hirugade@modusbox.com>
+ * Vijay Kumar Guthi <vijaya.guthi@infitx.com>
 
  --------------
  ******/