@mojaloop/central-ledger 19.14.0 → 20.1.0

package/src/models/transfer/facade.int.ts

@@ -0,0 +1,139 @@
+/*****
+ 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 { Snapshot } from "../../testing/snapshot"
+import * as ApiHelpers from '../../testing/api-helpers'
+
+import TransferHandler from '../../handlers/transfers/handler'
+
+const harness = Harness.getInstance()
+import TransferFacade from "./facade"
+
+
+describe('models/tranfer/facade', () => {
+  before(async () => {
+    await harness.up()
+    await harness.setupGlobals()
+
+    await TransferHandler.registerPrepareHandler()
+    await TransferHandler.registerFulfilHandler()
+
+    // Create the hub accounts + settlement model.
+    const createHubPayload: ApiHelpers.CreateHubPayload = {
+      currencies: ['USD'],
+      settlementModels: [{
+        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: ['USD'],
+      isProxy: false,
+      initialPostionsAndLimits: [
+        {
+          initialPosition: 0,
+          value: 100000
+        }
+      ],
+      deposits: [10000]
+    })
+    await ApiHelpers.createDfsp(harness, {
+      name: 'dfsp_b',
+      currencies: ['USD'],
+      isProxy: false,
+      initialPostionsAndLimits: [
+        {
+          initialPosition: 0,
+          value: 100000
+        }
+      ],
+      deposits: [10000]
+    })
+
+    // 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')
+      .build()
+      .prepareAndFulfil()
+  })
+
+  after(async () => {
+    await harness.teardownGlobals()
+    await harness.down()
+  })
+
+  it('getById() - gets one transfer.', async () => {
+    const transfer = await TransferFacade.getById('1000001')
+    Snapshot.from(`{
+      "transferId": "1000001",
+      "amount": "100.0000",
+      "currencyId": "USD",
+      "ilpCondition": :ignore
+      "expirationDate": :ignore
+      "createdDate": :ignore
+      "currency": "USD",
+      "payerParticipantCurrencyId": 3,
+      "payerAmount": "100.0000",
+      "payerParticipantId": 2,
+      "payerFsp": "dfsp_a",
+      "payerIsProxy": 0,
+      "payeeParticipantCurrencyId": null,
+      "payeeAmount": "-100.0000",
+      "payeeParticipantId": 3,
+      "payeeFsp": "dfsp_b",
+      "payeeIsProxy": 0,
+      "transferStateChangeId": 12,
+      "transferState": "COMMITTED",
+      "reason": null,
+      "completedTimestamp": :ignore
+      "transferStateEnumeration": "COMMITTED",
+      "transferStateDescription": "The switch has successfully performed the transfer.",
+      "ilpPacket": :ignore
+      "condition": :ignore
+      "fulfilment": :ignore
+      "errorCode": null,
+      "errorDescription": null,
+      "externalPayerName": null,
+      "externalPayeeName": null,
+      "extensionList": [],
+      "isTransferReadModel": true
+    }`).checkUnwrap(transfer)
+  })
+})

package/src/models/transfer/facade.js

@@ -188,6 +188,7 @@ const getByIdLight = async (id) => {
 }
 
 const getAll = async () => {
+  logger.error('TransferFacade.getAll() has been broken for some time. Are we even using it?')
   try {
     return await Db.from('transfer').query(async (builder) => {
       const transferResultList = await builder
@@ -549,7 +550,7 @@ const saveTransferPrepared = async (payload, stateReason = null, hasPassedValida
         'facade_saveTransferPrepared_transaction - Metrics for transfer model',
         ['success', 'queryName']
       ).startTimer()
-      return await knex.transaction(async (trx) => {
+      const result = await knex.transaction(async (trx) => {
         try {
           await knex('transfer').transacting(trx).insert(transferRecord)
           await knex('transferParticipant').transacting(trx).insert(payerTransferParticipantRecord)
@@ -575,6 +576,10 @@ const saveTransferPrepared = async (payload, stateReason = null, hasPassedValida
           rethrow.rethrowDatabaseError(err)
         }
       })
+      // The inner timer above stops inside the transaction callback, i.e. before Knex
+      // issues COMMIT. This outer one stops after it, so the commit cost is measured.
+      histTimerSaveTransferPreparedEnd({ success: true, queryName: 'transfer_model_facade_saveTransferPrepared' })
+      return result
     } else {
       const histTimerSaveTransferNoValidationEnd = Metrics.getHistogram(
         'model_transfer',
@@ -938,8 +943,8 @@ const _getFxTransferList = async (knex, tableName = 'fxTransferTimeout', transac
  *  Returns the list of transfers/fxTransfers that have timed out
  *
  * @returns {Promise<{
- *    transferTimeoutList: TimedOutTransfer,
- *    fxTransferTimeoutList: TimedOutFxTransfer
+ *    transferTimeoutList: Array<TimedOutTransfer>
+ *    fxTransferTimeoutList: Array<TimedOutFxTransfer>
  * }>}
  */
 const timeoutExpireReserved = async (segmentId, intervalMin, intervalMax, fxSegmentId, fxIntervalMin, fxIntervalMax) => {

package/src/models/transfer/transferDuplicateCheck.js

@@ -55,7 +55,7 @@ const getTransferDuplicateCheck = async (transferId) => {
   ).startTimer()
   Logger.isDebugEnabled && Logger.debug(`get transferDuplicateCheck (transferId=${transferId})`)
   try {
-    const result = Db.from('transferDuplicateCheck').findOne({ transferId })
+    const result = await Db.from('transferDuplicateCheck').findOne({ transferId })
     histTimerGetTransferDuplicateCheckEnd({ success: true, queryName: 'transferDuplicateCheck_getTransferDuplicateCheck' })
     return result
   } catch (err) {
@@ -84,7 +84,7 @@ const saveTransferDuplicateCheck = async (transferId, hash) => {
   ).startTimer()
   Logger.isDebugEnabled && Logger.debug(`save transferDuplicateCheck (transferId=${transferId}, hash=${hash})`)
   try {
-    const result = Db.from('transferDuplicateCheck').insert({ transferId, hash })
+    const result = await Db.from('transferDuplicateCheck').insert({ transferId, hash })
     histTimerSaveTransferDuplicateCheckEnd({ success: true, queryName: 'transferDuplicateCheck_saveTransferDuplicateCheck' })
     return result
   } catch (err) {

package/src/models/transfer/transferError.int.ts

@@ -0,0 +1,112 @@
+/*****
+ 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 { Snapshot } from "../../testing/snapshot"
+import * as ApiHelpers from '../../testing/api-helpers'
+
+import TransferHandler from '../../handlers/transfers/handler'
+const harness = Harness.getInstance()
+const TransferError = require('./transferError')
+
+describe('models/tranfer/transferError', () => {
+  before(async () => {
+    await harness.up()
+    await harness.setupGlobals()
+
+    await TransferHandler.registerPrepareHandler()
+    await TransferHandler.registerFulfilHandler()
+
+    // Create the hub accounts + settlement model.
+    const createHubPayload: ApiHelpers.CreateHubPayload = {
+      currencies: ['USD'],
+      settlementModels: [{
+        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: ['USD'],
+      isProxy: false,
+      initialPostionsAndLimits: [
+        {
+          initialPosition: 0,
+          value: 100000
+        }
+      ],
+      deposits: [10000]
+    })
+    await ApiHelpers.createDfsp(harness, {
+      name: 'dfsp_b',
+      currencies: ['USD'],
+      isProxy: false,
+      initialPostionsAndLimits: [
+        {
+          initialPosition: 0,
+          value: 100000
+        }
+      ],
+      deposits: [10000]
+    })
+  })
+
+  after(async () => {
+    await harness.teardownGlobals()
+    await harness.down()
+  })
+
+  it('insert() is called on a failed payment.', async () => {
+    // Create payment which will liquidity check.
+    await ApiHelpers.buildPayment()
+      .deps(harness, TransferHandler)
+      .parties('dfsp_a', 'dfsp_b')
+      .transferId('1000001')
+      .amount('10001.00')
+      .build()
+      .prepare()
+
+    // Look up the transferErrors table.
+    const transferError = await TransferError.getByTransferId('1000001')
+    Snapshot.from(`{
+      "transferId": "1000001",
+      "transferStateChangeId": 10,
+      "errorCode": "4001",
+      "errorDescription": "Payer FSP insufficient liquidity",
+      "createdDate": :ignore
+    }`).checkUnwrap(transferError)
+  })
+})

package/src/models/transfer/transferExtension.int.ts

@@ -0,0 +1,137 @@
+/*****
+ 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 { Snapshot } from "../../testing/snapshot"
+import * as ApiHelpers from '../../testing/api-helpers'
+
+import TransferHandler from '../../handlers/transfers/handler'
+const harness = Harness.getInstance()
+const TransferExtension = require('./transferExtension')
+
+describe('models/tranfer/transferExtension', () => {
+  before(async () => {
+    await harness.up()
+    await harness.setupGlobals()
+
+    await TransferHandler.registerPrepareHandler()
+    await TransferHandler.registerFulfilHandler()
+
+    // Create the hub accounts + settlement model.
+    const createHubPayload: ApiHelpers.CreateHubPayload = {
+      currencies: ['USD'],
+      settlementModels: [{
+        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: ['USD'],
+      isProxy: false,
+      initialPostionsAndLimits: [
+        {
+          initialPosition: 0,
+          value: 100000
+        }
+      ],
+      deposits: [10000]
+    })
+    await ApiHelpers.createDfsp(harness, {
+      name: 'dfsp_b',
+      currencies: ['USD'],
+      isProxy: false,
+      initialPostionsAndLimits: [
+        {
+          initialPosition: 0,
+          value: 100000
+        }
+      ],
+      deposits: [10000]
+    })
+
+    await ApiHelpers.buildPayment()
+      .deps(harness, TransferHandler)
+      .parties('dfsp_a', 'dfsp_b')
+      .transferId('5000001')
+      .amount('1.50')
+      .build()
+      .prepareAndFulfil()
+  })
+
+  after(async () => {
+    await harness.teardownGlobals()
+    await harness.down()
+  })
+
+  it('saveTransferExtension() and getByTransferId()', async () => {
+    await TransferExtension.saveTransferExtension({
+      transferId: '5000001',
+      key: 'key_1',
+      value: 'value_1',
+      createdDate: new Date(),
+    })
+
+    const result = await TransferExtension.getByTransferId('5000001')
+    Snapshot.from(`[
+        {
+          "transferExtensionId": 3,
+          "transferId": "5000001",
+          "key": "key_1",
+          "value": "value_1",
+          "isFulfilment": 0,
+          "isError": 0,
+          "createdDate": :ignore
+        }
+      ]`).checkUnwrap(result)
+  })
+
+  it('saveTransferExtension() without a transferId fails', { expectFailure: true }, async () => {
+    await TransferExtension.saveTransferExtension({
+      key: 'key_1',
+      value: 'value_1',
+      createdDate: new Date(),
+    })
+  })
+
+  it('saveTransferExtension() without a value fails', { expectFailure: true }, async () => {
+    await TransferExtension.saveTransferExtension({
+      transferId: '5000001',
+      key: 'key_1',
+      createdDate: new Date(),
+    })
+  })
+})

package/src/models/transfer/transferStateChange.int.ts

@@ -0,0 +1,117 @@
+/*****
+ 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 { Snapshot } from "../../testing/snapshot"
+import * as ApiHelpers from '../../testing/api-helpers'
+
+import TransferHandler from '../../handlers/transfers/handler'
+const harness = Harness.getInstance()
+const TransferStateChange = require('./transferStateChange')
+
+describe('models/tranfer/transferExtension', () => {
+  before(async () => {
+    await harness.up()
+    await harness.setupGlobals()
+
+    await TransferHandler.registerPrepareHandler()
+    await TransferHandler.registerFulfilHandler()
+
+    // Create the hub accounts + settlement model.
+    const createHubPayload: ApiHelpers.CreateHubPayload = {
+      currencies: ['USD'],
+      settlementModels: [{
+        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: ['USD'],
+      isProxy: false,
+      initialPostionsAndLimits: [
+        {
+          initialPosition: 0,
+          value: 100000
+        }
+      ],
+      deposits: [10000]
+    })
+    await ApiHelpers.createDfsp(harness, {
+      name: 'dfsp_b',
+      currencies: ['USD'],
+      isProxy: false,
+      initialPostionsAndLimits: [
+        {
+          initialPosition: 0,
+          value: 100000
+        }
+      ],
+      deposits: [10000]
+    })
+
+    await ApiHelpers.buildPayment()
+      .deps(harness, TransferHandler)
+      .parties('dfsp_a', 'dfsp_b')
+      .transferId('5000001')
+      .amount('1.50')
+      .build()
+      .prepareAndFulfil()
+  })
+
+  after(async () => {
+    await harness.teardownGlobals()
+    await harness.down()
+  })
+
+  it('getByTransferId()', async () => {
+    const stateChange = await TransferStateChange.getByTransferId('5000001')
+    Snapshot.from(`{
+      "transferStateChangeId": 12,
+      "transferId": "5000001",
+      "transferStateId": "COMMITTED",
+      "reason": null,
+      "createdDate": :ignore
+    }`).checkUnwrap(stateChange)
+  })
+
+  it('getByTransferId()', async () => {
+    const latest = await TransferStateChange.getLatest()
+    Snapshot.from(`{
+      "transferStateChangeId": 12
+    }`).checkUnwrap(latest)
+  })
+})

package/{seeds → src/seeds}/participant.js

@@ -28,7 +28,7 @@
  ******/
 
 'use strict'
-const Config = require('../src/lib/config')
+const Config = require('../lib/config')
 
 const participant = [
   {

package/{seeds → src/seeds}/settlementInterchange.js

@@ -1,3 +1,4 @@
+/* istanbul ignore next */
 /*****
  License
  --------------

package/src/settlement/api/handlerRoutes.js

@@ -0,0 +1,71 @@
+/*****
+ 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>.
+
+ * Mojaloop Foundation
+ - Name Surname <name.surname@mojaloop.io>
+
+ * ModusBox
+ - Georgi Georgiev <georgi.georgiev@modusbox.com>
+ --------------
+ ******/
+'use strict'
+
+const OpenapiBackend = require('@mojaloop/central-services-shared').Util.OpenapiBackend
+const Path = require('path')
+const Handlers = require('./handlers')
+const { getBasePath, handleRequest, assertHandlersRegistered } = require('./openapiRouting')
+
+/**
+ * Handlers monitoring API Routes
+ *
+ * @param {object} api OpenAPIBackend instance
+ */
+const APIRoutes = (api) => {
+  const basePath = getBasePath(api)
+  return [
+    {
+      method: 'GET',
+      path: `${basePath}/health`,
+      handler: (req, h) => handleRequest(api, req, h),
+      config: {
+        id: 'handlers getHealth',
+        tags: ['api', 'getHealth'],
+        description: 'GET health'
+      }
+    }
+  ]
+}
+
+module.exports = {
+  plugin: {
+    name: 'settlement handler api routes',
+    register: async function (server) {
+      const api = await OpenapiBackend.initialise(Path.resolve(process.cwd(), 'src/settlement/interface/swagger-handler.json'), {
+        getHealth: Handlers.getHealth,
+        validationFail: Handlers.validationFail,
+        notFound: Handlers.notFound,
+        methodNotAllowed: Handlers.methodNotAllowed
+      })
+      assertHandlersRegistered(api)
+      server.route(APIRoutes(api))
+    }
+  }
+}

package/src/settlement/api/handlers/health.js

@@ -0,0 +1,10 @@
+'use strict'
+
+// Reuse the existing health handler from central-ledger.
+// We should remove this separate health check altogether, we need to update the Golden path
+// tests first.
+const { getHealth } = require('../../../api/root/handler')
+
+module.exports = {
+  get: (context, request, h) => getHealth(request, h)
+}