@mojaloop/central-ledger 19.14.0 → 20.1.0

package/src/settlement/domain/settlement/index.js

@@ -0,0 +1,405 @@
+/*****
+ License
+ --------------
+ Copyright © 2020-2025 Mojaloop Foundation
+ The Mojaloop files are made available by the Mojaloop 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
+ Mojaloop Foundation 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>.
+
+ * Mojaloop Foundation
+ - Name Surname <name.surname@mojaloop.io>
+ - Shashikant Hirugade <shashi.mojaloop@gmail.com>
+ * ModusBox
+ - Deon Botha <deon.botha@modusbox.com>
+ - Georgi Georgiev <georgi.georgiev@modusbox.com>
+ - Miguel de Barros <miguel.debarros@modusbox.com>
+ - Rajiv Mothilal <rajiv.mothilal@modusbox.com>
+ - Valentin Genev <valentin.genev@modusbox.com>
+ --------------
+ ******/
+'use strict'
+
+const arrayDiff = require('lodash').difference
+const SettlementModel = require('../../models/settlement')
+const SettlementModelModel = require('../../models/settlement/settlementModel')
+const SettlementWindowContentModel = require('../../models/settlementWindowContent')
+const SettlementWindowModel = require('../../models/settlementWindow')
+const ErrorHandler = require('@mojaloop/central-services-error-handling')
+const { logger } = require('../../shared/logger')
+const MLNumber = require('@mojaloop/ml-number')
+
+const prepareParticipantsResult = (participantCurrenciesList) => {
+  const participantAccounts = {}
+  for (const account of participantCurrenciesList) {
+    const { id } = account
+    const formattedAccount = {
+      id: account.participantCurrencyId,
+      state: account.state,
+      reason: account.reason,
+      netSettlementAmount: {
+        amount: new MLNumber(account.netAmount).toNumber(),
+        currency: account.currency
+      }
+    }
+    if (id in participantAccounts) {
+      const accountList = participantAccounts[id].accounts
+      accountList.push(formattedAccount)
+      participantAccounts[id] = {
+        id,
+        accounts: accountList
+      }
+    } else {
+      participantAccounts[id] = {
+        id,
+        accounts: [formattedAccount]
+      }
+    }
+  }
+  return Array.from(Object.keys(participantAccounts).map(participantId => participantAccounts[participantId]))
+}
+
+const groupSettlementWindowContentBySettlementWindow = (records) => {
+  const settlementWindows = {}
+  for (const record of records) {
+    const id = record.settlementWindowId
+    delete record.settlementWindowId
+    if (id in settlementWindows) {
+      settlementWindows[id].push(record)
+    } else {
+      settlementWindows[id] = [record]
+    }
+  }
+  return settlementWindows
+}
+
+module.exports = {
+  getById: async function ({ settlementId }, enums) {
+    const settlement = await SettlementModel.getById({ settlementId }, enums)
+    if (settlement) {
+      const settlementWindowsList = await SettlementWindowModel.getBySettlementId({ settlementId }, enums)
+      const participantCurrenciesList = await SettlementModel.settlementParticipantCurrency.getParticipantCurrencyBySettlementId({ settlementId }, enums)
+      const participants = prepareParticipantsResult(participantCurrenciesList)
+
+      // Build settlement window content array and insert into settlement window list object
+      const windowContentRecords = []
+      let windowContentResponseData = {}
+
+      for (const key of Object.keys(settlementWindowsList)) {
+        const windowContentRecord = await SettlementWindowContentModel.getBySettlementAndWindowId(settlementId, settlementWindowsList[key].id)
+        windowContentResponseData = {
+          id: windowContentRecord[0].id,
+          state: windowContentRecord[0].state,
+          ledgerAccountType: windowContentRecord[0].ledgerAccountType,
+          currencyId: windowContentRecord[0].currencyId,
+          createdDate: windowContentRecord[0].createdDate,
+          changedDate: windowContentRecord[0].changedDate
+        }
+        windowContentRecords.push(windowContentResponseData)
+        settlementWindowsList[key].content = windowContentRecords
+      }
+
+      return {
+        id: settlement.settlementId,
+        state: settlement.state,
+        reason: settlement.reason,
+        createdDate: settlement.createdDate,
+        changedDate: settlement.changedDate,
+        settlementWindows: settlementWindowsList,
+        participants
+      }
+    } else {
+      const error = ErrorHandler.Factory.createFSPIOPError(
+        ErrorHandler.Enums.FSPIOPErrorCodes.VALIDATION_ERROR,
+        `Settlement with ID '${settlementId}' not found`
+      )
+      logger.error(error)
+      throw error
+    }
+  },
+
+  putById: SettlementModel.putById,
+  abortById: async function (settlementId, payload, enums) {
+    // seq-settlement-6.2.6, step 3
+    const settlementData = await SettlementModel.getById({ settlementId })
+
+    if (!settlementData) {
+      const error = ErrorHandler.Factory.createFSPIOPError(
+        ErrorHandler.Enums.FSPIOPErrorCodes.VALIDATION_ERROR,
+        `Settlement with ID '${settlementId}' not found`
+      )
+      logger.error(error)
+      throw error
+    }
+    if (settlementData.state === enums.settlementStates.PS_TRANSFERS_COMMITTED ||
+      settlementData.state === enums.settlementStates.SETTLING ||
+      settlementData.state === enums.settlementStates.SETTLED) {
+      const error = ErrorHandler.Factory.createFSPIOPError(
+        ErrorHandler.Enums.FSPIOPErrorCodes.VALIDATION_ERROR,
+        `State change is not allowed for settlement '${settlementId}' in state '${settlementData.state}'`
+      )
+      logger.error(error)
+      throw error
+    } else if (settlementData.state === enums.settlementStates.ABORTED) {
+      return SettlementModel.abortByIdStateAborted(settlementId, payload, enums)
+    } else if (settlementData.state === enums.settlementStates.PS_TRANSFERS_RESERVED) {
+      const transferCommittedAccount = await SettlementModel.getTransferCommitedAccount(settlementId, enums)
+      if (transferCommittedAccount !== undefined) {
+        const error = ErrorHandler.Factory.createFSPIOPError(
+          ErrorHandler.Enums.FSPIOPErrorCodes.VALIDATION_ERROR,
+          `At least one settlement transfer is committed for settlement '${settlementId}'. Aborting is not allowed.`
+        )
+        logger.error(error)
+        throw error
+      }
+    }
+  },
+
+  getSettlementsByParams: async function (params, enums) {
+    // 7 filters - at least one should be used
+    Object.keys(params.query).forEach(key => params.query[key] === undefined && delete params.query[key])
+    if (Object.keys(params.query).length && Object.keys(params.query).length < 10) {
+      const settlements = {}
+      let settlement
+      let participant
+      const settlementsData = await SettlementModel.getByParams(params.query, enums)
+      if (settlementsData && settlementsData.length > 0) {
+        for (const s of settlementsData) {
+          if (!settlements[s.settlementId]) {
+            const settlementId = s.settlementId
+            const settlementWindowsList = await SettlementWindowModel.getBySettlementId({ settlementId })
+            for (const key of Object.keys(settlementWindowsList)) {
+              settlementWindowsList[key].content = await SettlementWindowContentModel.getBySettlementAndWindowId(s.settlementId, settlementWindowsList[key].id)
+            }
+            settlements[s.settlementId] = {
+              id: s.settlementId,
+              state: s.settlementStateId,
+              reason: s.settlementWindowReason,
+              createdDate: s.createdDate,
+              changedDate: s.changedDate,
+              settlementWindows: settlementWindowsList
+            }
+          }
+          settlement = settlements[s.settlementId]
+          if (!settlement.settlementWindows) {
+            settlement.settlementWindows = {}
+          }
+          if (!settlement.participants) {
+            settlement.participants = {}
+          }
+          if (!settlement.participants[s.participantId]) {
+            settlement.participants[s.participantId] = {
+              id: s.participantId
+            }
+          }
+          participant = settlement.participants[s.participantId]
+          if (!participant.accounts) {
+            participant.accounts = {}
+          }
+          participant.accounts[s.participantCurrencyId] = {
+            id: s.participantCurrencyId,
+            state: s.accountState,
+            reason: s.accountReason,
+            netSettlementAmount: {
+              amount: new MLNumber(s.accountAmount).toNumber(),
+              currency: s.accountCurrency
+            }
+          }
+        }
+        // transform settlements map to result array
+        const result = Object.keys(settlements).map((i) => {
+          let settlementWindows = settlements[i].settlementWindows
+          settlementWindows = Object.keys(settlementWindows).map((j) => {
+            return settlementWindows[j]
+          })
+          settlements[i].settlementWindows = settlementWindows
+          let participants = settlements[i].participants
+          participants = Object.keys(participants).map((j) => {
+            let accounts = participants[j].accounts
+            accounts = Object.keys(accounts).map((k) => {
+              return accounts[k]
+            })
+            participants[j].accounts = accounts
+            return participants[j]
+          })
+          settlements[i].participants = participants
+          return settlements[i]
+        })
+        return result
+      } else {
+        const error = ErrorHandler.Factory.createFSPIOPError(
+          ErrorHandler.Enums.FSPIOPErrorCodes.VALIDATION_ERROR,
+          `No settlements found matching the provided parameters: ${JSON.stringify(params.query)}`
+        )
+        logger.error(error)
+        throw error
+      }
+    } else {
+      const error = ErrorHandler.Factory.createFSPIOPError(ErrorHandler.Enums.FSPIOPErrorCodes.VALIDATION_ERROR, 'Use at least one parameter: state, fromDateTime, toDateTime, currency, settlementWindowId, fromSettlementWindowDateTime, toSettlementWindowDateTime, participantId, accountId')
+      logger.error(error)
+      throw error
+    }
+  },
+
+  settlementEventTrigger: async function (params, enums) {
+    // validate settlement model
+    const { settlementModel, reason, settlementWindows } = params
+    const settlementModelData = await SettlementModelModel.getByName(settlementModel)
+    if (!settlementModelData) {
+      const error = ErrorHandler.Factory.createFSPIOPError(
+        ErrorHandler.Enums.FSPIOPErrorCodes.VALIDATION_ERROR,
+        `Settlement model not found: ${settlementModel}`
+      )
+      logger.error(error)
+      throw error
+    } else if (settlementModelData.settlementGranularityId === enums.settlementGranularity.GROSS ||
+      settlementModelData.settlementDelayId === enums.settlementDelay.IMMEDIATE) {
+      const error = ErrorHandler.Factory.createFSPIOPError(ErrorHandler.Enums.FSPIOPErrorCodes.VALIDATION_ERROR, 'Settlement can not be created for GROSS or IMMEDIATE models')
+      logger.error(error)
+      throw error
+    }
+
+    // validate windows content
+    const idList = settlementWindows.map(v => v.id)
+    const applicableWindows = await SettlementWindowModel.getByListOfIds(idList, settlementModelData, enums.settlementWindowStates)
+    const applicableIdList = applicableWindows.map(v => v.settlementWindowId)
+    const nonApplicableIdList = arrayDiff(idList, applicableIdList)
+    if (nonApplicableIdList.length) {
+      const error = ErrorHandler.Factory.createFSPIOPError(ErrorHandler.Enums.FSPIOPErrorCodes.VALIDATION_ERROR, `Inapplicable windows ${nonApplicableIdList.join(', ')}`)
+      logger.error(error)
+      throw error
+    }
+
+    // settlement event trigger
+    const settlementId = await SettlementModel.triggerSettlementEvent({ idList, reason }, settlementModelData, enums)
+
+    // retrieve resulting data for response
+    const settlement = await SettlementModel.getById({ settlementId })
+    const settlementWindowsList = await SettlementWindowModel.getBySettlementId({ settlementId })
+    const settlementWindowContentAll = await SettlementWindowContentModel.getBySettlementId(settlementId)
+    const settlementWindowsContent = groupSettlementWindowContentBySettlementWindow(settlementWindowContentAll)
+    const settlementWindowsWithContent = settlementWindowsList.map(record => {
+      record.content = settlementWindowsContent[record.id]
+      return record
+    })
+    const participantCurrenciesList = await SettlementModel.settlementParticipantCurrency.getParticipantCurrencyBySettlementId({ settlementId })
+    const participants = prepareParticipantsResult(participantCurrenciesList)
+    return {
+      id: settlement.settlementId,
+      settlementModel,
+      state: settlement.state,
+      reason: settlement.reason,
+      createdDate: settlement.createdDate,
+      changedDate: settlement.changedDate,
+      settlementWindows: settlementWindowsWithContent,
+      participants
+    }
+  },
+
+  getByIdParticipantAccount: async function ({ settlementId, participantId, accountId = null }, enums) {
+    let participantFoundInSettlement = false
+    const accountProvided = accountId > 0
+    let participantAndAccountMatched = !accountProvided
+    let accountFoundInSettlement = !accountProvided
+
+    const settlement = await SettlementModel.getById({ settlementId }, enums) // 3
+    const settlementFound = !!settlement
+
+    let settlementParticipantCurrencyIdList, account, settlementAccount
+
+    if (settlementFound) {
+      settlementParticipantCurrencyIdList = await SettlementModel.settlementParticipantCurrency.getAccountsInSettlementByIds({
+        settlementId,
+        participantId
+      }, enums) // 6
+      participantFoundInSettlement = settlementParticipantCurrencyIdList.length > 0
+
+      if (participantFoundInSettlement && accountProvided) {
+        account = await SettlementModel.checkParticipantAccountExists({
+          participantId,
+          accountId
+        }, enums) // 9
+        participantAndAccountMatched = !!account
+
+        if (participantAndAccountMatched) {
+          settlementAccount = await SettlementModel.getAccountInSettlement({
+            settlementId,
+            accountId
+          }, enums) // 12
+          accountFoundInSettlement = !!settlementAccount
+        }
+      }
+    }
+
+    let settlementWindows
+    let accounts
+    let participants
+    if (settlementFound && participantFoundInSettlement && participantAndAccountMatched && accountFoundInSettlement) {
+      if (accountProvided) { // 16
+        settlementWindows = await SettlementModel.settlementSettlementWindow.getWindowsBySettlementIdAndAccountId({
+          settlementId,
+          accountId
+        }, enums)
+        accounts = await SettlementModel.settlementParticipantCurrency.getSettlementAccountById(settlementAccount.settlementParticipantCurrencyId, enums)
+        participants = prepareParticipantsResult(accounts)
+      } else {
+        settlementWindows = await SettlementModel.settlementSettlementWindow.getWindowsBySettlementIdAndParticipantId({
+          settlementId,
+          participantId
+        }, enums)
+        const ids = settlementParticipantCurrencyIdList.map(record => record.settlementParticipantCurrencyId)
+        accounts = await SettlementModel.settlementParticipantCurrency.getSettlementAccountsByListOfIds(ids, enums)
+        participants = prepareParticipantsResult(accounts)
+      }
+    } else {
+      if (!settlementFound) {
+        const error = ErrorHandler.Factory.createFSPIOPError(
+          ErrorHandler.Enums.FSPIOPErrorCodes.VALIDATION_ERROR,
+          `Settlement with ID '${settlementId}' not found`
+        )
+        logger.error(error)
+        throw error
+      } else if (!participantFoundInSettlement) {
+        const error = ErrorHandler.Factory.createFSPIOPError(
+          ErrorHandler.Enums.FSPIOPErrorCodes.VALIDATION_ERROR,
+          `Participant with ID '${participantId}' is not part of settlement '${settlementId}'`
+        )
+        logger.error(error)
+        throw error
+      } else if (!participantAndAccountMatched) {
+        const error = ErrorHandler.Factory.createFSPIOPError(
+          ErrorHandler.Enums.FSPIOPErrorCodes.VALIDATION_ERROR,
+          `Provided account ID '${accountId}' does not match any position account for participant '${participantId}' in settlement '${settlementId}'`
+        )
+        logger.error(error)
+        throw error
+      } else {
+        const error = ErrorHandler.Factory.createFSPIOPError(
+          ErrorHandler.Enums.FSPIOPErrorCodes.VALIDATION_ERROR,
+          `Account ID '${accountId}' is not part of settlement '${settlementId}'`
+        )
+        logger.error(error)
+        throw error
+      }
+    }
+
+    return {
+      id: settlement.settlementId,
+      state: settlement.state,
+      settlementWindows,
+      participants
+    }
+  }
+}

package/src/settlement/domain/settlementWindow/index.js

@@ -0,0 +1,117 @@
+/*****
+ License
+ --------------
+ Copyright © 2020-2025 Mojaloop Foundation
+ The Mojaloop files are made available by the Mojaloop 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
+ Mojaloop Foundation 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>.
+
+ * Mojaloop Foundation
+ - Name Surname <name.surname@mojaloop.io>
+
+ * ModusBox
+ - Deon Botha <deon.botha@modusbox.com>
+ - Georgi Georgiev <georgi.georgiev@modusbox.com>
+ - Miguel de Barros <miguel.debarros@modusbox.com>
+ - Rajiv Mothilal <rajiv.mothilal@modusbox.com>
+ - Valentin Genev <valentin.genev@modusbox.com>
+ - Lazola Lucas <lazola.lucas@modusbox.com>
+--------------
+ ******/
+
+const Config = require('../../../lib/config')
+const Enum = require('@mojaloop/central-services-shared').Enum
+const ErrorHandler = require('@mojaloop/central-services-error-handling')
+const hasFilters = require('./../../utils/truthyProperty')
+const Producer = require('@mojaloop/central-services-stream').Util.Producer
+const KafkaUtil = require('@mojaloop/central-services-shared').Util.Kafka
+const SettlementWindowModel = require('../../models/settlementWindow')
+const SettlementWindowContentModel = require('../../models/settlementWindowContent')
+const StreamingProtocol = require('@mojaloop/central-services-shared').Util.StreamingProtocol
+const { logger } = require('../../shared/logger')
+const idGenerator = require('@mojaloop/central-services-shared').Util.id
+const generateULID = idGenerator({ type: 'ulid' })
+
+module.exports = {
+  getById: async function (params, enums, options) {
+    const settlementWindow = await SettlementWindowModel.getById(params)
+
+    if (settlementWindow) {
+      const settlementWindowContent = await SettlementWindowContentModel.getBySettlementWindowId(settlementWindow.settlementWindowId)
+
+      if (settlementWindowContent) {
+        settlementWindow.content = settlementWindowContent
+        return settlementWindow
+      } else {
+        const error = ErrorHandler.Factory.createFSPIOPError(ErrorHandler.Enums.FSPIOPErrorCodes.INTERNAL_SERVER_ERROR, `No records for settlementWidowContentId : ${params.settlementWindowId} found`)
+        logger.error(error)
+        throw error
+      }
+    } else {
+      const error = ErrorHandler.Factory.createFSPIOPError(ErrorHandler.Enums.FSPIOPErrorCodes.INTERNAL_SERVER_ERROR, `No record for settlementWindowId: ${params.settlementWindowId} found`)
+      logger.error(error)
+      throw error
+    }
+  },
+
+  getByParams: async function (params, enums) {
+    // 4 filters - at least one should be used
+    if (hasFilters(params.query) && Object.keys(params.query).length < 6) {
+      const settlementWindows = await SettlementWindowModel.getByParams(params, enums)
+      if (settlementWindows && settlementWindows.length > 0) {
+        for (const settlementWindow of settlementWindows) {
+          const settlementWindowContent = await SettlementWindowContentModel.getBySettlementWindowId(settlementWindow.settlementWindowId)
+          if (settlementWindowContent) {
+            settlementWindow.content = settlementWindowContent
+          } else {
+            const error = ErrorHandler.Factory.createFSPIOPError(ErrorHandler.Enums.FSPIOPErrorCodes.INTERNAL_SERVER_ERROR, `No records for settlementWidowContentId : ${settlementWindow.settlementWindowId} found`)
+            logger.error(error)
+            throw error
+          }
+        }
+        return settlementWindows
+      } else {
+        const error = ErrorHandler.Factory.createFSPIOPError(ErrorHandler.Enums.FSPIOPErrorCodes.VALIDATION_ERROR, `settlementWindow by filters: ${JSON.stringify(params.query).replace(/"/g, '')} not found`)
+        logger.error(error)
+        throw error
+      }
+    } else {
+      const error = ErrorHandler.Factory.createFSPIOPError(ErrorHandler.Enums.FSPIOPErrorCodes.VALIDATION_ERROR, 'Use at least one parameter: participantId, state, fromDateTime, toDateTime, currency')
+      logger.error(error)
+      throw error
+    }
+  },
+
+  process: async function (params, enums) {
+    const settlementWindowId = await SettlementWindowModel.process(params, enums)
+    const messageId = generateULID()
+    const eventId = generateULID()
+    const state = StreamingProtocol.createEventState(Enum.Events.EventStatus.SUCCESS.status, Enum.Events.EventStatus.SUCCESS.code, Enum.Events.EventStatus.SUCCESS.description)
+    const event = StreamingProtocol.createEventMetadata(Enum.Events.Event.Type.DEFERRED_SETTLEMENT, Enum.Events.Event.Action.CLOSE, state)
+    const metadata = StreamingProtocol.createMetadata(eventId, event)
+    const messageProtocol = StreamingProtocol.createMessage(messageId, Config.HUB_NAME, Config.HUB_NAME, metadata, params.headers, params)
+    const topicConfig = KafkaUtil.createGeneralTopicConf(Config.KAFKA_CONFIG.TOPIC_TEMPLATES.GENERAL_TOPIC_TEMPLATE.TEMPLATE, Enum.Events.Event.Type.DEFERRED_SETTLEMENT, Enum.Events.Event.Action.CLOSE)
+    const kafkaConfig = KafkaUtil.getKafkaConfig(Config.KAFKA_CONFIG, Enum.Kafka.Config.PRODUCER, Enum.Events.Event.Type.DEFERRED_SETTLEMENT.toUpperCase(), Enum.Events.Event.Action.CLOSE.toUpperCase())
+    await Producer.produceMessage(messageProtocol, topicConfig, kafkaConfig)
+
+    return SettlementWindowModel.getById({ settlementWindowId }, enums)
+  },
+
+  close: async function (settlementWindowId, reason) {
+    await SettlementWindowModel.close(settlementWindowId, reason)
+    return SettlementWindowModel.getById({ settlementWindowId })
+  }
+}

package/src/settlement/domain/transactions/index.js

@@ -0,0 +1,83 @@
+/*****
+ License
+ --------------
+ Copyright © 2020-2025 Mojaloop Foundation
+ The Mojaloop files are made available by the Mojaloop 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
+ Mojaloop Foundation 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>.
+
+ * Mojaloop Foundation
+ - Name Surname <name.surname@mojaloop.io>
+
+ * ModusBox
+ - Lazola Lucas <lazola.lucas@modusbox.com>
+ --------------
+ ******/
+'use strict'
+
+const IlpPacket = require('../../models/ilpPackets/ilpPacket')
+const ErrorHandler = require('@mojaloop/central-services-error-handling')
+
+const ilpPacket = require('ilp-packet')
+const base64url = require('base64url')
+const { logger } = require('../../shared/logger')
+
+const getById = async (id) => {
+  try {
+    return await IlpPacket.getById(id)
+  } catch (err) {
+    logger.error(err)
+    throw ErrorHandler.Factory.reformatFSPIOPError(err)
+  }
+}
+
+const decodeIlpPacket = async (inputIlpPacket) => {
+  const binaryPacket = Buffer.from(inputIlpPacket, 'base64')
+
+  // Try ILPv4 first
+  try {
+    return ilpPacket.deserializeIlpPrepare(binaryPacket)
+  } catch (v4Error) {
+    logger.debug('Failed to decode as ILPv4, attempting ILPv1')
+    // Fall back to ILPv1
+    try {
+      return ilpPacket.deserializeIlpPayment(binaryPacket)
+    } catch (v1Error) {
+      logger.error('Failed to decode ILP packet as both v4 and v1', { v4Error, v1Error })
+      throw v1Error
+    }
+  }
+}
+
+/**
+ * Get the transaction object in the data field of an Ilp packet
+ *
+ * @returns {object} - Transaction Object
+ */
+const getTransactionObject = async function (inputIlpPacket) {
+  try {
+    const jsonPacket = await decodeIlpPacket(inputIlpPacket)
+    const decodedData = base64url.decode(jsonPacket.data.toString())
+    return JSON.parse(decodedData)
+  } catch (err) {
+    logger.error(err)
+    throw ErrorHandler.Factory.reformatFSPIOPError(err)
+  }
+}
+module.exports = {
+  getById,
+  getTransactionObject
+}

package/src/settlement/domain/transferSettlement/index.js

@@ -0,0 +1,57 @@
+/*****
+ License
+ --------------
+ Copyright © 2020-2025 Mojaloop Foundation
+ The Mojaloop files are made available by the Mojaloop 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
+ Mojaloop Foundation 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>.
+
+ * Mojaloop Foundation
+ - Name Surname <name.surname@mojaloop.io>
+
+ * ModusBox
+ - Deon Botha <deon.botha@modusbox.com>
+ - Lazola Lucas <lazola.lucas@modusbox.com>
+ - Claudio Viola <claudio.viola@modusbox.com>
+ --------------
+ ******/
+
+const ErrorHandler = require('@mojaloop/central-services-error-handling')
+const TransferSettlementModel = require('../../models/transferSettlement')
+const { logger } = require('../../shared/logger')
+const Enum = require('@mojaloop/central-services-shared').Enum.Settlements
+
+module.exports = {
+  processMsgFulfil: async function (transferEventId, transferEventStateStatus, trx) {
+    logger.debug(`transferSettlement::processMsgFulfil(transferEventId=${transferEventId}, transferEventStateStatus=${transferEventStateStatus}) - start`)
+    try {
+      // Get the 'GROSS' settlement model by transfer
+      const grossSettlementModel = await TransferSettlementModel.getSettlementModelByTransferId(transferEventId, Enum.settlementGranularityName.GROSS)
+      logger.debug(`transferSettlement::processMsgFulfil - result grossSettlementModel=${JSON.stringify(grossSettlementModel)}`)
+      logger.debug(`transferSettlement::processMsgFulfil - grossSettlementModel.length=${grossSettlementModel.length}`)
+      if (grossSettlementModel.length > 0) {
+        logger.debug(`transferSettlement::processMsgFulfil - updateStateChange(transferEventId=${transferEventId}, transferEventStateStatus=${transferEventStateStatus}) - start`)
+        await TransferSettlementModel.updateStateChange(transferEventId, transferEventStateStatus, trx)
+        logger.debug('transferSettlement::processMsgFulfil - updateStateChange - end')
+      }
+      logger.debug('transferSettlement::processMsgFulfil - end')
+      return true
+    } catch (err) {
+      logger.error('transferSettlement::processMsgFulfil - error!', err)
+      throw ErrorHandler.Factory.reformatFSPIOPError(err)
+    }
+  }
+}