@mojaloop/central-ledger 19.14.0 → 20.1.0

package/src/domain/participant/index.js

@@ -62,8 +62,6 @@ const ActionNotSupportedText = 'The action is not supported'
 const ParticipantAccountCurrencyMismatchText = 'The account does not match participant or currency specified'
 const ParticipantAccountMismatchText = 'Participant/account mismatch'
 const ParticipantInactiveText = 'Participant is currently set inactive'
-const ParticipantInitialPositionExistsText = 'Participant Limit or Initial Position already set'
-// const ParticipantNotFoundText = 'Participant does not exist'
 
 const create = async (payload) => {
   const log = logger.child({ payload })
@@ -213,7 +211,7 @@ const addEndpoint = async (name, payload) => {
     log.verbose('getting participant by name...')
     const participant = await ParticipantModel.getByName(name)
     participantExists(participant)
-    log.info('adding endpoint for participant', { participant })
+    log.debug('adding endpoint for participant', { participant })
     return ParticipantFacade.addEndpoint(participant.participantId, payload)
   } catch (err) {
     log.error('error adding endpoint', err)
@@ -339,8 +337,9 @@ const addLimitAndInitialPosition = async (participantName, limitAndInitialPositi
     const existingPosition = await ParticipantPositionModel.getByParticipantCurrencyId(participant.participantCurrencyId)
     const existingSettlementPosition = await ParticipantPositionModel.getByParticipantCurrencyId(settlementAccount.participantCurrencyId)
     if (existingLimit || existingPosition || existingSettlementPosition) {
-      log.warn('participant limit or initial position already set')
-      throw ErrorHandler.Factory.createInternalServerFSPIOPError(ParticipantInitialPositionExistsText)
+      const errorMessage = `Participant Limit or Initial Position already set for participant: ${participantName}.`
+      log.warn(errorMessage)
+      throw ErrorHandler.Factory.createInternalServerFSPIOPError(errorMessage)
     }
     const limitAndInitialPosition = Object.assign({}, limitAndInitialPositionObj, { name: participantName })
     if (!limitAndInitialPosition.initialPosition) {

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

@@ -284,7 +284,7 @@ const processFxPositionPrepareBin = async (
 
       resultMessages.push({ binItem, message: Utility.clone(resultMessage) })
 
-      if (changePositions) {
+      if (changePositions && participantLimit.thresholdAlarmPercentage) {
         Logger.isDebugEnabled && Logger.debug(`processFxPositionPrepareBin::limitAlarm: ${currentPosition.toNumber()} > ${liquidityCover.multiply(participantLimit.thresholdAlarmPercentage)}`)
         if (currentPosition.toNumber() > liquidityCover.multiply(participantLimit.thresholdAlarmPercentage).toNumber()) {
           limitAlarms.push(participantLimit)

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

@@ -39,6 +39,7 @@ const Config = require('../../lib/config')
 const Utility = require('@mojaloop/central-services-shared').Util
 const MLNumber = require('@mojaloop/ml-number')
 const Logger = require('../../shared/logger').logger
+const assert = require('node:assert')
 
 /**
  * @function processPositionFxTimeoutReservedBin
@@ -89,6 +90,9 @@ const processPositionFxTimeoutReservedBin = async (
         Logger.isDebugEnabled && Logger.debug(`accumulatedFxTransferStates: ${JSON.stringify(accumulatedFxTransferStates)}`)
 
         const transferAmount = fetchedReservedPositionChangesByCommitRequestIds[commitRequestId][participantAccountId].change
+        if (transferAmount === undefined) {
+          throw new Error(`transferAmount is undefined for commitRequestId: ${commitRequestId} and ${participantAccountId}`)
+        }
 
         // Construct payee notification message
         const resultMessage = _constructFxTimeoutReservedResultMessage(
@@ -167,6 +171,8 @@ const _constructFxTimeoutReservedResultMessage = (binItem, commitRequestId, coun
 }
 
 const _handleParticipantPositionChange = (runningPosition, transferAmount, commitRequestId, accumulatedPositionReservedValue) => {
+  assert(runningPosition !== undefined)
+  assert(transferAmount !== undefined)
   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))

package/src/domain/position/prepare.js

@@ -285,7 +285,7 @@ const processPositionPrepareBin = async (
 
       resultMessages.push({ binItem, message: Utility.clone(resultMessage) })
 
-      if (changePositions) {
+      if (changePositions && participantLimit.thresholdAlarmPercentage) {
         Logger.isDebugEnabled && Logger.debug(`processPositionPrepareBin::limitAlarm: ${currentPosition.toNumber()} > ${liquidityCover.multiply(participantLimit.thresholdAlarmPercentage)}`)
         if (currentPosition.toNumber() > liquidityCover.multiply(participantLimit.thresholdAlarmPercentage).toNumber()) {
           limitAlarms.push(participantLimit)

package/src/handlers/admin/handler.js

@@ -191,7 +191,7 @@ const registerTransferHandler = async () => {
  * @async
  * @description Registers all handlers in transfers
  *
- * @returns {boolean} - Returns a boolean: true if successful, or throws and error if failed
+ * @returns Promise<boolean> - Returns a boolean: true if successful, or throws and error if failed
  */
 const registerAllHandlers = async () => {
   try {

package/src/handlers/index.js

@@ -62,6 +62,9 @@ Program.command('handler') // sub-command name, coffeeType = type, required
   .option('--bulkfulfil', 'Start the Bulk Fulfil Handler')
   .option('--bulkprocessing', 'Start the Bulk Processing Handler')
   .option('--bulkget', 'Start the Bulk Get Handler')
+  .option('--deferredSettlement', 'Start the Deferred Settlement Handler.')
+  .option('--grossSettlement', 'Start the Gross Settlement Handler.')
+  .option('--rules', 'Start the rules handler.')
   // .option('--reject', 'Start the Reject Handler')
 
   // function to execute when command is uses
@@ -156,6 +159,33 @@ Program.command('handler') // sub-command name, coffeeType = type, required
       handlerList.push(handler)
     }
 
+    if (args.deferredSettlement === true) {
+      Logger.isDebugEnabled && Logger.debug('CLI: Executing --deferredSettlement')
+      const handler = {
+        type: 'deferredSettlement',
+        enabled: true
+      }
+      handlerList.push(handler)
+    }
+
+    if (args.grossSettlement === true) {
+      Logger.isDebugEnabled && Logger.debug('CLI: Executing --grossSettlement')
+      const handler = {
+        type: 'grossSettlement',
+        enabled: true
+      }
+      handlerList.push(handler)
+    }
+
+    if (args.rules === true) {
+      Logger.isDebugEnabled && Logger.debug('CLI: Executing --rules')
+      const handler = {
+        type: 'rules',
+        enabled: true
+      }
+      handlerList.push(handler)
+    }
+
     module.exports = Setup.initialize({
       service: 'handler',
       port: Config.PORT,

package/src/handlers/positions/handler.js

@@ -276,8 +276,6 @@ const positions = async (error, messages) => {
  *
  * @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 {

package/src/handlers/positions/handlerBatch.js

@@ -37,8 +37,9 @@ 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 { Kafka: { otel }, Util: { Producer, Consumer } } = require('@mojaloop/central-services-stream')
+const { Kafka } = Utility
+const { Consumer, Producer } = require('@mojaloop/central-services-stream').Util
+const otel = require('@mojaloop/central-services-stream').Kafka.otel
 const Enum = require('@mojaloop/central-services-shared').Enum
 const Metrics = require('@mojaloop/central-services-metrics')
 const Config = require('../../lib/config')
@@ -47,7 +48,7 @@ const ErrorHandler = require('@mojaloop/central-services-error-handling')
 const BatchPositionModel = require('../../models/position/batch')
 const decodePayload = require('@mojaloop/central-services-shared').Util.StreamingProtocol.decodePayload
 const { BATCHING } = require('../../shared/constants')
-
+const Logger = require('../../shared/logger').logger
 const consumerCommit = true
 const rethrow = require('../../shared/rethrow')
 
@@ -191,6 +192,7 @@ const positions = batchConfig => async (error, messages) => {
     }
     histTimerEnd({ success: true })
   } catch (err) {
+    Logger.error(`handlerBatch failed with error: ${err.message}`)
     // If Bin Processor returns failure
     // -  Rollback DB transaction
     await trx?.rollback()
@@ -220,8 +222,6 @@ const positions = batchConfig => async (error, messages) => {
  *
  * @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 {

package/src/handlers/register.js

@@ -41,13 +41,11 @@
  * @function RegisterAllHandlers
  *
  * @async
- * @description Registers all handlers by using the require-glob to retrieve all handler exports in sub directories and access the registerAllHandlers()
- * in each of them. Every handler in the sub-folders must have a registerAllHandlers() function
- * @returns {boolean} - Returns a boolean: true if successful, or throws and error if failed
+ * @description Registers all handlers in ./handlers and ../settlement/handlers.
+ * @returns {boolean} - Returns a boolean: true if successful, or throws and error if failed.
  */
 
 const Logger = require('../shared/logger').logger
-const requireGlob = require('require-glob')
 const TransferHandlers = require('./transfers/handler')
 const PositionHandlers = require('./positions/handler')
 const PositionHandlersBatch = require('./positions/handlerBatch')
@@ -55,32 +53,11 @@ const TimeoutHandlers = require('./timeouts/handler')
 const AdminHandlers = require('./admin/handler')
 const BulkHandlers = require('./bulk')
 const ErrorHandler = require('@mojaloop/central-services-error-handling')
+const DeferredSettlementHandler = require('../settlement/handlers/deferredSettlement/handler')
+const GrossSettlementHandler = require('../settlement/handlers/grossSettlement/handler')
+const RulesHandler = require('../settlement/handlers/rules/handler')
 
-const registerAllHandlers = async () => {
-  try {
-    const modules = await requireGlob(['./**/handler.js'])
-    for (const key in modules) {
-      Logger.isInfoEnabled && Logger.info(`Registering handler module[${key}]: ${JSON.stringify(modules[key])}`)
-      if (Object.prototype.hasOwnProperty.call(modules[key], 'handler')) {
-        const handlerObject = modules[key]
-        await handlerObject.handler.registerAllHandlers()
-      } else {
-        for (const subKey in modules[key]) {
-          const handlerObject = modules[key][subKey]
-          Logger.isInfoEnabled && Logger.info(` ⌙ Registering sub-handler module[${key}-${subKey}]: ${JSON.stringify(handlerObject)}`)
-          await handlerObject.handler.registerAllHandlers()
-        }
-      }
-    }
-    return true
-  } catch (err) {
-    Logger.isErrorEnabled && Logger.error(err)
-    throw ErrorHandler.Factory.reformatFSPIOPError(err)
-  }
-}
-
-module.exports = {
-  registerAllHandlers,
+const handlers = {
   transfers: {
     registerAllHandlers: TransferHandlers.registerAllHandlers,
     registerPrepareHandler: TransferHandlers.registerPrepareHandler,
@@ -104,9 +81,47 @@ module.exports = {
     registerAdminHandlers: AdminHandlers.registerAllHandlers
   },
   bulk: {
+    registerAllHandlers: BulkHandlers.registerAllHandlers,
     registerBulkPrepareHandler: BulkHandlers.registerBulkPrepareHandler,
     registerBulkFulfilHandler: BulkHandlers.registerBulkFulfilHandler,
     registerBulkProcessingHandler: BulkHandlers.registerBulkProcessingHandler,
     registerBulkGetHandler: BulkHandlers.registerGetBulkTransferHandler
+  },
+  deferredSettlement: {
+    registerAllHandlers: DeferredSettlementHandler.registerAllHandlers,
+    registerSettlementWindowHandler: DeferredSettlementHandler.registerSettlementWindowHandler
+  },
+  grossSettlement: {
+    registerAllHandlers: GrossSettlementHandler.registerAllHandlers,
+    registerTransferSettlementHandler: GrossSettlementHandler.registerTransferSettlement,
+    registerRulesHandler: RulesHandler.registerRules
+  },
+  rules: {
+    registerAllHandlers: RulesHandler.registerAllHandlers,
+    registerRulesHandler: RulesHandler.registerRules
   }
 }
+
+const registerAllHandlers = async () => {
+  try {
+    Logger.isInfoEnabled && Logger.info('registerAllHandlers() - Registering all handlers.')
+    await handlers.transfers.registerAllHandlers()
+    await handlers.positions.registerAllHandlers()
+    await handlers.timeouts.registerAllHandlers()
+    await handlers.admin.registerAdminHandlers()
+    await handlers.bulk.registerAllHandlers()
+    await handlers.deferredSettlement.registerAllHandlers()
+    await handlers.grossSettlement.registerAllHandlers()
+    await handlers.rules.registerAllHandlers()
+
+    return true
+  } catch (err) {
+    Logger.isErrorEnabled && Logger.error(err)
+    throw ErrorHandler.Factory.reformatFSPIOPError(err)
+  }
+}
+
+module.exports = {
+  registerAllHandlers,
+  ...handlers
+}

package/src/handlers/timeouts/handler.js

@@ -292,7 +292,6 @@ const _processFxForwardedTransfers = async (fxTransferForwardedList) => {
  * Processes timedOut fxTransfers
  *
  * @param {TimedOutFxTransfer[]} fxTransferTimeoutList
- * @returns {Promise<void>}
  */
 const _processFxTimedOutTransfers = async (fxTransferTimeoutList) => {
   const fspiopError = createFSPIOPTimeoutError()
@@ -380,8 +379,6 @@ const _processFxTimedOutTransfers = async (fxTransferTimeoutList) => {
   * ... called to validate/insert ...
   *
   * @param {error} error - error thrown if something fails within Cron
-  *
-  * @returns {boolean} - Returns a boolean: true if successful, or throws and error if failed
   */
 const timeout = async () => {
   if (running) return
@@ -544,7 +541,7 @@ const initializeMetrics = () => {
   *
   * @async
   * @description Registers the timeout handler by starting the timeoutJob cron
-  * @returns {boolean} - Returns a boolean: true if successful, or throws and error if failed
+  * @returns {Promise<boolean>} - Returns a boolean: true if successful, or throws and error if failed
   */
 const registerTimeoutHandler = async () => {
   try {

package/src/handlers/transfers/fx-abort.int.ts

@@ -0,0 +1,209 @@
+/*****
+ License
+ --------------
+ Copyright © 2020-2026 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>.
+
+ * TigerBeetle
+ - Lewis Daly <lewis@tigerbeetle.com>
+ --------------
+ ******/
+
+import { after, before, describe, it } from "node:test"
+import Harness from '../../testing/harness'
+import * as ApiHelpers from '../../testing/api-helpers'
+import assert from "node:assert"
+import { assertPositionDiff } from "../../testing/util"
+
+const harness = Harness.getInstance()
+let PrepareHandler: any
+let TransferHandler: any
+let PositionBatchHandler: any
+let ExternalParticipantCached: any
+let TransferFacade: any
+let FxTransferService: any
+let proxyCache: any
+
+describe('handlers/fx-abort', () => {
+  before(async () => {
+    await harness.up('BATCH')
+    await harness.setupGlobals()
+
+    // Import after bringing up the harness, so that global config is overriden.
+    TransferHandler = require('./handler')
+    PrepareHandler = require('./prepare')
+    PositionBatchHandler = require('../positions/handlerBatch')
+    TransferFacade = require('../../models/transfer/facade')
+    FxTransferService = require('../../domain/fx/index')
+    ExternalParticipantCached = require('../../models/participant/externalParticipantCached')
+    proxyCache = require('../../lib/proxyCache')
+    await proxyCache.connect()
+    await TransferHandler.registerPrepareHandler()
+    await TransferHandler.registerFulfilHandler()
+
+    // Create the hub accounts + settlement model.
+    const createHubPayload: ApiHelpers.CreateHubPayload = {
+      currencies: ['BWP', 'USD'],
+      settlementModels: [
+        {
+          name: `DEFERRED_MULTILATERAL_NET_BWP`,
+          settlementGranularity: "NET",
+          settlementInterchange: "MULTILATERAL",
+          settlementDelay: "DEFERRED",
+          currency: 'BWP',
+          requireLiquidityCheck: true,
+          ledgerAccountType: "POSITION",
+          settlementAccountType: "SETTLEMENT",
+          autoPositionReset: true
+        },
+        {
+          name: `DEFERRED_MULTILATERAL_NET_USD`,
+          settlementGranularity: "NET",
+          settlementInterchange: "MULTILATERAL",
+          settlementDelay: "DEFERRED",
+          currency: 'USD',
+          requireLiquidityCheck: true,
+          ledgerAccountType: "POSITION",
+          settlementAccountType: "SETTLEMENT",
+          autoPositionReset: true
+        }
+      ]
+    }
+    await ApiHelpers.createHub(harness, createHubPayload)
+    // Create 2 test dfsps to transfer between.
+    await ApiHelpers.createDfsp(harness, {
+      name: 'dfsp_a',
+      currencies: ['BWP'],
+      isProxy: false,
+      initialPostionsAndLimits: [{ initialPosition: 0, value: 100000 }],
+      deposits: [10000]
+    })
+    await ApiHelpers.createDfsp(harness, {
+      name: 'dfsp_b',
+      currencies: ['BWP', 'USD'],
+      isProxy: false,
+      initialPostionsAndLimits: [
+        { initialPosition: 0, value: 100000 },
+        { initialPosition: 0, value: 100000 }
+      ],
+      deposits: [10000, 10000]
+    })
+    await ApiHelpers.createDfsp(harness, {
+      name: 'dfsp_a_proxy',
+      currencies: ['BWP', 'USD'],
+      isProxy: true,
+      initialPostionsAndLimits: [
+        { initialPosition: 0, value: 100000 },
+        { initialPosition: 0, value: 100000 }
+      ],
+      deposits: [10000, 10000]
+    })
+    await ApiHelpers.createDfsp(harness, {
+      name: 'dfsp_b_proxy',
+      currencies: ['BWP', 'USD'],
+      isProxy: true,
+      initialPostionsAndLimits: [
+        { initialPosition: 0, value: 100000 },
+        { initialPosition: 0, value: 100000 }
+      ],
+      deposits: [10000, 10000]
+    })
+    await ApiHelpers.createDfsp(harness, {
+      name: 'fxp_a',
+      currencies: ['BWP', 'USD'],
+      isProxy: false,
+      initialPostionsAndLimits: [
+        { initialPosition: 0, value: 100000 },
+        { initialPosition: 0, value: 100000 }
+      ],
+      deposits: [10000, 10000]
+    })
+
+    // Set up the proxy1 currencies.
+    await proxyCache.getCache().addDfspIdToProxyMapping('external_dfsp_a', 'dfsp_a_proxy')
+    await proxyCache.getCache().addDfspIdToProxyMapping('external_dfsp_b', 'dfsp_b_proxy')
+
+    // Create payment of $100.00 USD from dfsp_a to dfsp_b with id 1000001.
+    await ApiHelpers.buildPayment()
+      .deps(harness, TransferHandler)
+      .parties('dfsp_a', 'dfsp_b')
+      .transferId('1000001')
+      .amount('1.00', 'BWP')
+      .build()
+      .prepareAndFulfil()
+  })
+
+  after(async () => {
+    await proxyCache.disconnect()
+    await harness.teardownGlobals()
+    await harness.down()
+  })
+
+  it('Aborting a transfer also aborts linked fxTransfer, all positions revert.', async () => {
+    const positionPayerPre = await ApiHelpers.getPositionAccount('dfsp_a', 'BWP')
+    const positionFxpBwpPre = await ApiHelpers.getPositionAccount('fxp_a', 'BWP')
+    const positionFxpUsdPre = await ApiHelpers.getPositionAccount('fxp_a', 'USD')
+    const positionPayeePre = await ApiHelpers.getPositionAccount('dfsp_b', 'USD')
+
+    const forex = ApiHelpers.buildForex()
+      .deps(harness, TransferHandler)
+      .commitRequestId('5000001')
+      .determiningTransferId('6000001')
+      .parties('dfsp_a', 'fxp_a')
+      .amountSource('100.00', 'BWP')
+      .amountTarget('10.00', 'USD')
+      .build()
+
+    await forex.prepare()
+    const positionPayerPostPrepare = await ApiHelpers.getPositionAccount('dfsp_a', 'BWP')
+    assertPositionDiff('payer', positionPayerPre, positionPayerPostPrepare, { posted: 100 })
+
+    await forex.fulfil()
+    const fxTransferAfterFulfil = await FxTransferService.getByIdLight('5000001')
+    assert.equal(fxTransferAfterFulfil.fxTransferState, 'RECEIVED_FULFIL_DEPENDENT')
+
+    const payment = ApiHelpers.buildPayment()
+      .deps(harness, TransferHandler)
+      .parties('fxp_a', 'dfsp_b')
+      .transferId('6000001')
+      .amount('10.00', 'USD')
+      .fx()
+      .build()
+
+    await payment.prepare()
+    // Need to do a custom fulfil here, as we expect 4 messages due to FX.
+    const mark = harness.redpandaMark()
+    await TransferHandler.fulfil(null, payment.buildMessageAbort())
+    await harness.redpandaDrain(mark, 4)
+
+    const transfer = await TransferFacade.getById('6000001')
+    assert.equal(transfer.transferState, 'ABORTED_ERROR')
+    const fxTransferAfterAbort = await FxTransferService.getByIdLight('5000001')
+    assert.equal(fxTransferAfterAbort.fxTransferState, 'ABORTED_ERROR')
+
+    // All positions reset.
+    const positionPayerPostAbort = await ApiHelpers.getPositionAccount('dfsp_a', 'BWP')
+    assertPositionDiff('payer', positionPayerPre, positionPayerPostAbort, { posted: 0 })
+    const positionFxpUsdPostAbort = await ApiHelpers.getPositionAccount('fxp_a', 'USD')
+    assertPositionDiff('payer', positionFxpUsdPre, positionFxpUsdPostAbort, { posted: 0 })
+    const positionPayeePostAbort = await ApiHelpers.getPositionAccount('dfsp_b', 'USD')
+    assertPositionDiff('payee', positionPayeePre, positionPayeePostAbort, { posted: 0 })
+    const positionFxpBwpPostAbort = await ApiHelpers.getPositionAccount('fxp_a', 'BWP')
+    assertPositionDiff('payer', positionFxpBwpPre, positionFxpBwpPostAbort, { posted: 0 })
+  })
+})