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

package/src/handlers/transfers/FxFulfilService.js

@@ -0,0 +1,387 @@
+/*****
+ 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>
+
+ * Eugen Klymniuk <eugen.klymniuk@infitx.com>
+ --------------
+ **********/
+
+/* eslint-disable space-before-function-paren */
+const { Enum, Util } = require('@mojaloop/central-services-shared')
+const cyril = require('../../domain/fx/cyril')
+const TransferObjectTransform = require('../../domain/transfer/transform')
+const fspiopErrorFactory = require('../../shared/fspiopErrorFactory')
+const ErrorHandler = require('@mojaloop/central-services-error-handling')
+
+const { Type, Action } = Enum.Events.Event
+const { SOURCE, DESTINATION } = Enum.Http.Headers.FSPIOP
+const { TransferState, TransferInternalState } = Enum.Transfers
+
+const consumerCommit = true
+const fromSwitch = true
+
+class FxFulfilService {
+  // #state = null
+
+  constructor(deps) {
+    this.log = deps.log
+    this.Config = deps.Config
+    this.Comparators = deps.Comparators
+    this.Validator = deps.Validator
+    this.FxTransferModel = deps.FxTransferModel
+    this.Kafka = deps.Kafka
+    this.params = deps.params // todo: rename to kafkaParams
+    this.cyril = deps.cyril || cyril
+    this.transform = deps.transform || TransferObjectTransform
+  }
+
+  async getFxTransferDetails(commitRequestId, functionality) {
+    const fxTransfer = await this.FxTransferModel.fxTransfer.getAllDetailsByCommitRequestIdForProxiedFxTransfer(commitRequestId)
+
+    if (!fxTransfer) {
+      const fspiopError = fspiopErrorFactory.fxTransferNotFound()
+      const apiFSPIOPError = fspiopError.toApiErrorObject(this.Config.ERROR_HANDLING)
+      const eventDetail = {
+        functionality,
+        action: Action.FX_RESERVE
+      }
+      this.log.warn('fxTransfer not found', { commitRequestId, eventDetail, apiFSPIOPError })
+
+      await this.kafkaProceed({
+        consumerCommit,
+        fspiopError: apiFSPIOPError,
+        eventDetail,
+        fromSwitch
+      })
+      throw fspiopError
+    }
+
+    this.log.debug('fxTransfer is found', { fxTransfer })
+    return fxTransfer
+  }
+
+  async validateHeaders({ transfer, headers, payload }) {
+    let fspiopError = null
+
+    if (!transfer.counterPartyFspIsProxy && (headers[SOURCE]?.toLowerCase() !== transfer.counterPartyFspName.toLowerCase())) {
+      fspiopError = fspiopErrorFactory.fxHeaderSourceValidationError()
+    }
+    if (!transfer.initiatingFspIsProxy && (headers[DESTINATION]?.toLowerCase() !== transfer.initiatingFspName.toLowerCase())) {
+      fspiopError = fspiopErrorFactory.fxHeaderDestinationValidationError()
+    }
+
+    if (fspiopError) {
+      const apiFSPIOPError = fspiopError.toApiErrorObject(this.Config.ERROR_HANDLING)
+      const eventDetail = {
+        functionality: Type.POSITION,
+        action: Action.FX_ABORT_VALIDATION
+      }
+      this.log.warn('headers validation error', { eventDetail, apiFSPIOPError })
+
+      // Lets handle the abort validation and change the fxTransfer state to reflect this
+      await this.FxTransferModel.fxTransfer.saveFxFulfilResponse(transfer.commitRequestId, payload, eventDetail.action, apiFSPIOPError)
+
+      await this._handleAbortValidation(transfer, apiFSPIOPError, eventDetail)
+      throw fspiopError
+    }
+  }
+
+  async _handleAbortValidation(fxTransfer, apiFSPIOPError, eventDetail) {
+    const cyrilResult = await this.cyril.processFxAbortMessage(fxTransfer.commitRequestId)
+
+    this.params.message.value.content.context = {
+      ...this.params.message.value.content.context,
+      cyrilResult
+    }
+    if (cyrilResult.positionChanges.length > 0) {
+      const participantCurrencyId = cyrilResult.positionChanges[0].participantCurrencyId
+      await this.kafkaProceed({
+        consumerCommit,
+        fspiopError: apiFSPIOPError,
+        eventDetail,
+        fromSwitch,
+        toDestination: fxTransfer.externalInitiatingFspName || fxTransfer.initiatingFspName,
+        messageKey: participantCurrencyId.toString(),
+        topicNameOverride: this.Config.KAFKA_CONFIG.EVENT_TYPE_ACTION_TOPIC_MAP?.POSITION?.FX_ABORT
+      })
+    } else {
+      const fspiopError = ErrorHandler.Factory.createInternalServerFSPIOPError('Invalid cyril result')
+      throw fspiopError
+    }
+  }
+
+  async getDuplicateCheckResult({ commitRequestId, payload, action }) {
+    const { duplicateCheck } = this.FxTransferModel
+    const isFxTransferError = action === Action.FX_ABORT
+
+    const getDuplicateFn = isFxTransferError
+      ? duplicateCheck.getFxTransferErrorDuplicateCheck
+      : duplicateCheck.getFxTransferFulfilmentDuplicateCheck
+    const saveHashFn = isFxTransferError
+      ? duplicateCheck.saveFxTransferErrorDuplicateCheck
+      : duplicateCheck.saveFxTransferFulfilmentDuplicateCheck
+
+    return this.Comparators.duplicateCheckComparator(
+      commitRequestId,
+      payload,
+      getDuplicateFn,
+      saveHashFn
+    )
+  }
+
+  async checkDuplication({ dupCheckResult, transfer, functionality, action, type }) {
+    const transferStateEnum = transfer?.transferStateEnumeration
+    this.log.info('fxTransfer checkDuplication...', { dupCheckResult, action, transferStateEnum })
+
+    if (!dupCheckResult.hasDuplicateId) {
+      this.log.debug('No duplication found')
+      return false
+    }
+
+    if (!dupCheckResult.hasDuplicateHash) {
+      // ERROR: We've seen fxTransfer of this ID before, but it's message hash doesn't match the previous message hash.
+      const fspiopError = fspiopErrorFactory.noFxDuplicateHash()
+      const apiFSPIOPError = fspiopError.toApiErrorObject(this.Config.ERROR_HANDLING)
+      const eventDetail = {
+        functionality,
+        action: action === Action.FX_ABORT ? Action.FX_ABORT_DUPLICATE : Action.FX_FULFIL_DUPLICATE
+      }
+      this.log.warn('callbackErrorModified - no hasDuplicateHash', { eventDetail, apiFSPIOPError })
+
+      await this.kafkaProceed({
+        consumerCommit,
+        fspiopError: apiFSPIOPError,
+        eventDetail,
+        fromSwitch
+      })
+      throw fspiopError
+    }
+
+    // This is a duplicate message for a fxTransfer that is already in a finalized state
+    // respond as if we received a GET /fxTransfers/{ID} from the client
+    if ([TransferState.COMMITTED, TransferState.ABORTED].includes(transferStateEnum)) {
+      this.params.message.value.content.payload = this.transform.toFulfil(transfer)
+      const eventDetail = {
+        functionality,
+        action: action === Action.FX_ABORT ? Action.FX_ABORT_DUPLICATE : Action.FX_FULFIL_DUPLICATE
+      }
+      this.log.info('eventDetail:', { eventDetail })
+      await this.kafkaProceed({ consumerCommit, eventDetail, fromSwitch })
+      return true
+    }
+
+    if ([TransferState.RECEIVED, TransferState.RESERVED].includes(transferStateEnum)) {
+      this.log.info('state: RECEIVED or RESERVED')
+      await this.kafkaProceed({ consumerCommit })
+      // this code doesn't publish any message to kafka, coz we don't provide eventDetail:
+      // https://github.com/mojaloop/central-services-shared/blob/main/src/util/kafka/index.js#L315
+      return true
+    }
+
+    // Error scenario - fxTransfer.transferStateEnumeration is in some invalid state
+    const fspiopError = fspiopErrorFactory.invalidFxTransferState({ transferStateEnum, action, type })
+    const apiFSPIOPError = fspiopError.toApiErrorObject(this.Config.ERROR_HANDLING)
+    const eventDetail = {
+      functionality,
+      action: Action.FX_RESERVE
+    }
+    this.log.warn('callbackErrorInvalidTransferStateEnum', { eventDetail, apiFSPIOPError })
+    await this.kafkaProceed({
+      consumerCommit,
+      fspiopError: apiFSPIOPError,
+      eventDetail,
+      fromSwitch
+    })
+
+    return true
+  }
+
+  async validateEventType(type, functionality) {
+    if (type !== Type.FULFIL) {
+      const fspiopError = fspiopErrorFactory.invalidEventType(type)
+      const apiFSPIOPError = fspiopError.toApiErrorObject(this.Config.ERROR_HANDLING)
+      const eventDetail = {
+        functionality,
+        action: Action.FX_RESERVE
+      }
+      this.log.warn('callbackErrorInvalidEventType', { type, eventDetail, apiFSPIOPError })
+
+      await this.kafkaProceed({
+        consumerCommit,
+        fspiopError: apiFSPIOPError,
+        eventDetail,
+        fromSwitch
+      })
+      throw fspiopError
+    }
+    this.log.debug('validateEventType is passed', { type, functionality })
+  }
+
+  async validateFulfilment(fxTransfer, payload) {
+    const isValid = this.validateFulfilCondition(payload.fulfilment, fxTransfer.ilpCondition)
+
+    if (!isValid) {
+      const fspiopError = fspiopErrorFactory.fxInvalidFulfilment()
+      const apiFSPIOPError = fspiopError.toApiErrorObject(this.Config.ERROR_HANDLING)
+      const eventDetail = {
+        functionality: Type.POSITION,
+        action: Action.FX_ABORT_VALIDATION
+      }
+      this.log.warn('callbackErrorInvalidFulfilment', { eventDetail, apiFSPIOPError, fxTransfer, payload })
+      await this.FxTransferModel.fxTransfer.saveFxFulfilResponse(fxTransfer.commitRequestId, payload, eventDetail.action, apiFSPIOPError)
+
+      await this._handleAbortValidation(fxTransfer, apiFSPIOPError, eventDetail)
+      throw fspiopError
+    }
+
+    this.log.info('fulfilmentCheck passed successfully', { isValid })
+    return isValid
+  }
+
+  async validateTransferState(transfer, functionality) {
+    if (transfer.transferState !== TransferInternalState.RESERVED &&
+        transfer.transferState !== TransferInternalState.RESERVED_FORWARDED) {
+      const fspiopError = fspiopErrorFactory.fxTransferNonReservedState()
+      const apiFSPIOPError = fspiopError.toApiErrorObject(this.Config.ERROR_HANDLING)
+      const eventDetail = {
+        functionality,
+        action: Action.FX_RESERVE
+      }
+      this.log.warn('callbackErrorNonReservedState', { eventDetail, apiFSPIOPError, transfer })
+
+      await this.kafkaProceed({
+        consumerCommit,
+        fspiopError: apiFSPIOPError,
+        eventDetail,
+        fromSwitch
+      })
+      throw fspiopError
+    }
+    this.log.debug('validateTransferState is passed')
+    return true
+  }
+
+  async validateExpirationDate(transfer, functionality) {
+    if (transfer.expirationDate <= new Date(Util.Time.getUTCString(new Date()))) {
+      const fspiopError = fspiopErrorFactory.fxTransferExpired()
+      const apiFSPIOPError = fspiopError.toApiErrorObject(this.Config.ERROR_HANDLING)
+      const eventDetail = {
+        functionality,
+        action: Action.FX_RESERVE
+      }
+      this.log.warn('callbackErrorTransferExpired', { eventDetail, apiFSPIOPError })
+
+      await this.kafkaProceed({
+        consumerCommit,
+        fspiopError: apiFSPIOPError,
+        eventDetail,
+        fromSwitch
+      })
+      throw fspiopError
+    }
+  }
+
+  async processFxAbort({ transfer, payload, action }) {
+    const fspiopError = fspiopErrorFactory.fromErrorInformation(payload.errorInformation)
+    const apiFSPIOPError = fspiopError.toApiErrorObject(this.Config.ERROR_HANDLING)
+    const eventDetail = {
+      functionality: Type.POSITION,
+      action // FX_ABORT
+    }
+    this.log.warn('FX_ABORT case', { eventDetail, apiFSPIOPError })
+
+    await this.FxTransferModel.fxTransfer.saveFxFulfilResponse(transfer.commitRequestId, payload, action, apiFSPIOPError)
+    const cyrilResult = await this.cyril.processFxAbortMessage(transfer.commitRequestId)
+
+    this.params.message.value.content.context = {
+      ...this.params.message.value.content.context,
+      cyrilResult
+    }
+    if (cyrilResult.positionChanges.length > 0) {
+      const participantCurrencyId = cyrilResult.positionChanges[0].participantCurrencyId
+      await this.kafkaProceed({
+        consumerCommit,
+        eventDetail,
+        messageKey: participantCurrencyId.toString(),
+        topicNameOverride: this.Config.KAFKA_CONFIG.EVENT_TYPE_ACTION_TOPIC_MAP?.POSITION?.FX_ABORT
+      })
+    } else {
+      const fspiopError = ErrorHandler.Factory.createInternalServerFSPIOPError('Invalid cyril result')
+      throw fspiopError
+    }
+    return true
+  }
+
+  async processFxFulfil({ transfer, payload, action }) {
+    await this.FxTransferModel.fxTransfer.saveFxFulfilResponse(transfer.commitRequestId, payload, action)
+    await this.cyril.processFxFulfilMessage(transfer.commitRequestId)
+    const eventDetail = {
+      functionality: Type.POSITION,
+      action
+    }
+    this.log.info('handle fxFulfilResponse', { eventDetail })
+
+    await this.kafkaProceed({
+      consumerCommit,
+      eventDetail,
+      messageKey: transfer.counterPartyFspSourceParticipantCurrencyId.toString(),
+      topicNameOverride: this.Config.KAFKA_CONFIG.EVENT_TYPE_ACTION_TOPIC_MAP?.POSITION?.COMMIT
+    })
+    return true
+  }
+
+  async kafkaProceed(kafkaOpts) {
+    return this.Kafka.proceed(this.Config.KAFKA_CONFIG, this.params, {
+      ...kafkaOpts,
+      hubName: this.Config.HUB_NAME
+    })
+  }
+
+  validateFulfilCondition(fulfilment, condition) {
+    try {
+      const isValid = fulfilment && this.Validator.validateFulfilCondition(fulfilment, condition)
+      this.log.debug('validateFulfilCondition result:', { isValid, fulfilment, condition })
+      return isValid
+    } catch (err) {
+      this.log.warn(`validateFulfilCondition error: ${err?.message}`, { fulfilment, condition })
+      return false
+    }
+  }
+
+  static decodeKafkaMessage(message) {
+    if (!message?.value) {
+      throw TypeError('Invalid message format!')
+    }
+    const payload = Util.StreamingProtocol.decodePayload(message.value.content.payload)
+    const { headers } = message.value.content
+    const { type, action } = message.value.metadata.event
+    const commitRequestId = message.value.content.uriParams.id
+
+    return Object.freeze({
+      payload,
+      headers,
+      type,
+      action,
+      commitRequestId,
+      kafkaTopic: message.topic
+    })
+  }
+}
+
+module.exports = FxFulfilService

package/src/handlers/transfers/createRemittanceEntity.js

@@ -0,0 +1,106 @@
+const fxTransferModel = require('../../models/fxTransfer')
+const TransferService = require('../../domain/transfer')
+const cyril = require('../../domain/fx/cyril')
+const { logger } = require('../../shared/logger')
+
+/** @import { ProxyObligation } from './prepare.js' */
+
+// abstraction on transfer and fxTransfer
+const createRemittanceEntity = (isFx) => {
+  return {
+    isFx,
+
+    async getDuplicate (id) {
+      return isFx
+        ? fxTransferModel.duplicateCheck.getFxTransferDuplicateCheck(id)
+        : TransferService.getTransferDuplicateCheck(id)
+    },
+    async saveDuplicateHash (id, hash) {
+      return isFx
+        ? fxTransferModel.duplicateCheck.saveFxTransferDuplicateCheck(id, hash)
+        : TransferService.saveTransferDuplicateCheck(id, hash)
+    },
+
+    /**
+     * Saves prepare transfer/fxTransfer details to DB.
+     *
+     * @param {Object} payload - Message payload.
+     * @param {string | null} reason - Validation failure reasons.
+     * @param {Boolean} isValid - isValid.
+     * @param {DeterminingTransferCheckResult} determiningTransferCheckResult - The determining transfer check result.
+     * @param {ProxyObligation} proxyObligation - The proxy obligation
+     * @returns {Promise<void>}
+     */
+    async savePreparedRequest (
+      payload,
+      reason,
+      isValid,
+      determiningTransferCheckResult,
+      proxyObligation
+    ) {
+      return isFx
+        ? fxTransferModel.fxTransfer.savePreparedRequest(
+          payload,
+          reason,
+          isValid,
+          determiningTransferCheckResult,
+          proxyObligation
+        )
+        : TransferService.prepare(
+          payload,
+          reason,
+          isValid,
+          determiningTransferCheckResult,
+          proxyObligation
+        )
+    },
+
+    async getByIdLight (id) {
+      return isFx
+        ? fxTransferModel.fxTransfer.getByIdLight(id)
+        : TransferService.getByIdLight(id)
+    },
+
+    /**
+     * @typedef {Object} DeterminingTransferCheckResult
+     *
+     * @property {boolean} determiningTransferExists - Indicates if the determining transfer exists.
+     * @property {Array<{participantName, currencyId}>} participantCurrencyValidationList - List of validations for participant currencies.
+     * @property {Object} [transferRecord] - Determining transfer for the FX transfer (optional).
+     * @property {Array} [watchListRecords] - Records from fxWatchList-table for the transfer (optional).
+     */
+    /**
+     * Checks if a determining transfer exists based on the payload and proxy obligation.
+     * The function determines which method to use based on whether it is an FX transfer.
+     *
+     * @param {Object} payload - The payload data required for the transfer check.
+     * @param {ProxyObligation} proxyObligation - The proxy obligation details.
+     * @returns {DeterminingTransferCheckResult} determiningTransferCheckResult
+     */
+    async checkIfDeterminingTransferExists (payload, proxyObligation) {
+      const result = isFx
+        ? await cyril.checkIfDeterminingTransferExistsForFxTransferMessage(payload, proxyObligation)
+        : await cyril.checkIfDeterminingTransferExistsForTransferMessage(payload, proxyObligation)
+
+      logger.debug('cyril determiningTransferCheckResult:', { result })
+      return result
+    },
+
+    async getPositionParticipant (payload, determiningTransferCheckResult, proxyObligation) {
+      const result = isFx
+        ? await cyril.getParticipantAndCurrencyForFxTransferMessage(payload, determiningTransferCheckResult)
+        : await cyril.getParticipantAndCurrencyForTransferMessage(payload, determiningTransferCheckResult, proxyObligation)
+
+      logger.debug('cyril getPositionParticipant result:', { result })
+      return result
+    },
+
+    async logTransferError (id, errorCode, errorDescription) {
+      return isFx
+        ? fxTransferModel.stateChange.logTransferError(id, errorCode, errorDescription)
+        : TransferService.logTransferError(id, errorCode, errorDescription)
+    }
+  }
+}
+
+module.exports = createRemittanceEntity

package/src/handlers/transfers/dto.js

@@ -0,0 +1,53 @@
+const { Util, Enum } = require('@mojaloop/central-services-shared')
+const { PROM_METRICS } = require('../../shared/constants')
+
+const { decodePayload } = Util.StreamingProtocol
+const { Action, Type } = Enum.Events.Event
+
+const prepareInputDto = (error, messages) => {
+  if (error || !messages) {
+    return {
+      error,
+      metric: PROM_METRICS.transferPrepare()
+    }
+  }
+
+  const message = Array.isArray(messages) ? messages[0] : messages
+  if (!message) throw new Error('No input kafka message')
+
+  const payload = decodePayload(message.value.content.payload)
+  const isFx = !payload.transferId
+
+  const { action } = message.value.metadata.event
+  const isForwarded = [Action.FORWARDED, Action.FX_FORWARDED].includes(action)
+  const isPrepare = [Action.PREPARE, Action.FX_PREPARE, Action.FORWARDED, Action.FX_FORWARDED].includes(action)
+
+  const actionLetter = isPrepare
+    ? Enum.Events.ActionLetter.prepare
+    : (action === Action.BULK_PREPARE
+        ? Enum.Events.ActionLetter.bulkPrepare
+        : Enum.Events.ActionLetter.unknown)
+
+  const functionality = isPrepare
+    ? Type.NOTIFICATION
+    : (action === Action.BULK_PREPARE
+        ? Type.BULK_PROCESSING
+        : Enum.Events.ActionLetter.unknown)
+
+  return {
+    message,
+    payload,
+    action,
+    functionality,
+    isFx,
+    isForwarded,
+    ID: payload.transferId || payload.commitRequestId || message.value.id,
+    headers: message.value.content.headers,
+    metric: PROM_METRICS.transferPrepare(isFx, isForwarded),
+    actionLetter // just for logging
+  }
+}
+
+module.exports = {
+  prepareInputDto
+}