OC evidenced promise

Author: simonredfern

obp-api/src/main/scala/code/api/v7_0_0/Http4s700.scala

@@ -3487,7 +3487,7 @@ object Http4s700 {
       "Attach Open Corridor Promise Evidence",
       """Attach on-chain promise evidence to a PENDING OPEN_CORRIDOR_PROMISE Transaction Request.
         |
-        |Called by the bank's own Bank Node (machine-to-machine) after it has written the Promise commitment to the blockchain. The body carries the transaction hash of the on-chain write plus the commit–reveal evidence: the `commitment` (the hash written on-chain), the `salt`, and the `preimage`. OBP-API stores these as Transaction Request attributes and later relays them to the beneficiary bank inside the `obp_credit_notification` message, enabling the beneficiary to verify `SHA-256(salt ‖ preimage)` against the on-chain commitment without the originating bank's cooperation.
+        |Called by the bank's own Bank Node (machine-to-machine) after it has written the Promise commitment to the blockchain. The body carries the transaction hash of the on-chain write plus the commit–reveal evidence: the `commitment` (the hash written on-chain), the `salt`, and the `preimage`. OBP-API stores these as Transaction Request attributes and immediately relays them to the beneficiary bank inside the `obp_credit_notification` message (enqueued to the transactional outbox on the first successful attach), enabling the beneficiary to verify `SHA-256(salt ‖ preimage)` against the on-chain commitment without the originating bank's cooperation — and to credit its customer ahead of settlement on the strength of that verified promise.
         |
         |The evidence fields are opaque strings to OBP-API — they are stored and relayed verbatim, never parsed.
         |
@@ -3608,6 +3608,7 @@ object Http4s700 {
     )
     val createAccountResponseExampleV700 = JSONFactory700.CreateAccountResponseJsonV700(
       account_id = "8ca8a7e4-6d02-40e3-a129-0b2bf89de9f0",
+      bank_id = "gh.29.uk",
       user_id = "9ca9a7e4-6d02-40e3-a129-0b2bf89de9b1",
       label = "My Account",
       product_code = "OPEN_CORRIDOR",
@@ -3836,11 +3837,13 @@ object Http4s700 {
         |
         |Computes `net = SUM(PENDING A→B promises) − SUM(PENDING B→A promises)`, mints one internal OPEN_CORRIDOR_SETTLEMENT Transaction Request between the pair's settlement accounts whose execution posts ONE net Transaction (debtor's outgoing settlement account → creditor's incoming), records that Transaction's id on each covered promise in the `settled_by_transaction_ids` attribute (and the settlement TR's id in `settled_by_transaction_request_id`), and sets the covered promises to COMPLETED. N promises collapse into one settlement — that compression is the netting.
         |
-        |In the same database transaction, the Interface C messages are written to the transactional outbox: one `obp_credit_notification` per covered promise to its beneficiary bank (relaying the commit–reveal evidence triplet), and one `obp_settlement_instruction` for the net amount to the debtor bank. The outbox relay publishes them and records each bank's reply.
+        |Only promises whose on-chain evidence has been attached are covered: an unevidenced promise generated no credit notification and no beneficiary payout, so netting it would move value for a payment nobody delivered — it stays PENDING for a later cycle.
+        |
+        |In the same database transaction, the Interface C messages are written to the transactional outbox: one `obp_settlement_advice` per beneficiary bank listing the covered promise ids it already paid out against (credit notifications travel at promise-report-back time, not here), and one `obp_settlement_instruction` for the net amount to the debtor bank. The outbox relay publishes them and records each bank's reply.
         |
         |NOTE: the posted net Transaction deliberately does not mirror any single covered promise — it can differ in direction, amount and accounts. Reconciliation must follow the `settled_by_transaction_ids` linkage, never assume the Transaction matches the promise body.
         |
-        |A trigger for a pair with no PENDING promises is a no-op. When the flows offset exactly (net zero) the promises are discharged with no Transaction posted and no settlement instruction sent — the credit notifications still go out.
+        |A trigger for a pair with no PENDING evidenced promises is a no-op. When the flows offset exactly (net zero) the promises are discharged with no Transaction posted and no settlement instruction sent — the settlement advices still go out.
         |
         |`net_amount` is always the absolute value; direction is carried by `debtor_bank_id` → `creditor_bank_id` (assigned from the sign of the net). Either bank in the pair may trigger settlement — the role is checked at the URL's BANK_ID, and who ends up debtor is decided by the net, not by who called.
         |
@@ -3857,7 +3860,7 @@ object Http4s700 {
         currency = "KES",
         net_amount = "2500.00",
         covered_transaction_request_ids = List("4050046c-63b3-4868-8a22-14b4181d33a6"),
-        credit_notifications_enqueued = 3,
+        settlement_advices_enqueued = 1,
         settlement_instructions_enqueued = 1
       ),
       List($AuthenticatedUserIsRequired, UserHasMissingRoles, OpenCorridorDisabled, InvalidJsonFormat, InvalidJsonValue,
@@ -3896,7 +3899,7 @@ object Http4s700 {
         |* `ledger_status` — the OBP-side OPEN_CORRIDOR_SETTLEMENT Transaction Request (COMPLETED at settle time: netting, promise discharge and the net ledger Transaction are done).
         |* `settlement_status` — the value leg on the rail, as last reported by the debtor bank's node: `NET_ZERO` (nothing to move), `INSTRUCTED` (no node reply yet), `SETTLING` / `SUBMITTED` (in flight, with `settlement_depth` = confirmation depth when reported), `FINAL` (node reported finality), `ERROR` (non-retryable node error; operator reconciliation — see the message's `last_error`).
         |
-        |`messages` lists the settlement's Interface C outbox rows (credit notifications and the settlement instruction) with their delivery state.
+        |`messages` lists the settlement's Interface C outbox rows (settlement advices and the settlement instruction) with their delivery state.
         |
         |Requires `open_corridor_enabled=true` on this instance and the `CanSettleOpenCorridor` role at BANK_ID.
         |

obp-api/src/main/scala/code/api/v7_0_0/JSONFactory7.0.0.scala

@@ -1132,6 +1132,7 @@ object JSONFactory700 extends MdcLoggable with code.api.util.CustomJsonFormats {
 
   case class CreateAccountResponseJsonV700(
     account_id: String,
+    bank_id: String,
     user_id: String,
     label: String,
     product_code: String,
@@ -1148,6 +1149,7 @@ object JSONFactory700 extends MdcLoggable with code.api.util.CustomJsonFormats {
   ): CreateAccountResponseJsonV700 =
     CreateAccountResponseJsonV700(
       account_id = account.accountId.value,
+      bank_id = account.bankId.value,
       user_id = userId,
       label = account.label,
       product_code = account.accountType,
@@ -1212,7 +1214,7 @@ object JSONFactory700 extends MdcLoggable with code.api.util.CustomJsonFormats {
     currency: String,
     net_amount: String,
     covered_transaction_request_ids: List[String],
-    credit_notifications_enqueued: Int,
+    settlement_advices_enqueued: Int,
     settlement_instructions_enqueued: Int
   )
 

obp-api/src/main/scala/code/bankconnectors/opencorridor/OpenCorridorProcessor.scala

@@ -8,9 +8,12 @@ import code.api.util.{APIUtil, CallContext, NewStyle}
 import code.api.v7_0_0.JSONFactory700.{OpenCorridorPromiseJsonV700, PostOpenCorridorPromiseJsonV700, TransactionRequestBodyOpenCorridorJsonV700}
 import code.util.Helper
 import com.openbankproject.commons.ExecutionContext.Implicits.global
+import com.openbankproject.commons.dto.{OpenCorridorMoneyValue, OpenCorridorOriginator, OutBoundOpenCorridorCreditNotification}
 import com.openbankproject.commons.model._
 import com.openbankproject.commons.model.enums.ChallengeType.OBP_TRANSACTION_REQUEST_CHALLENGE
 import com.openbankproject.commons.model.enums.{TransactionRequestAttributeType, TransactionRequestStatus, TransactionRequestTypes}
+import code.transactionrequests.MappedTransactionRequest
+import net.liftweb.mapper.By
 
 import java.util.Date
 import org.json4s.native.Serialization.write
@@ -187,6 +190,11 @@ object OpenCorridorProcessor {
           NewStyle.function.createTransactionRequestAttributes(
             bankId, transactionRequestId, attributes, isPersonal = false, callContext
           ) map { case (_, callContext) =>
+            // First attach only (idempotent redeliveries skip this branch): the
+            // promise now exists on-chain, so the beneficiary bank gets its
+            // evidence-bearing credit notification immediately — the promise is
+            // what gives it the confidence to pay out ahead of settlement.
+            enqueueCreditNotification(transactionRequestId, submittedEvidence)
             (buildPromiseJson(tr, submittedEvidence, user.userId, reportedAt), callContext)
           }
         } else {
@@ -198,6 +206,36 @@ object OpenCorridorProcessor {
     } yield (promiseJson, callContext)
   }
 
+  private implicit val wireFormats: Formats = Serialization.formats(NoTypeHints)
+
+  /** Build and enqueue the `obp_credit_notification` for a promise whose evidence
+    * was just attached. The outbox row's correlation id is the promise TR id
+    * (settlement-scoped messages use the settlement id there instead). */
+  private def enqueueCreditNotification(
+    transactionRequestId: TransactionRequestId,
+    evidence: Map[String, String]
+  ): Unit =
+    MappedTransactionRequest
+      .find(By(MappedTransactionRequest.mTransactionRequestId, transactionRequestId.value))
+      .foreach { row =>
+        val wireBody = OutBoundOpenCorridorCreditNotification(
+          transaction_request_id = transactionRequestId.value,
+          value = OpenCorridorMoneyValue(row.mBody_Value_Currency.get, row.mBody_Value_Amount.get),
+          description = Option(row.mBody_Description.get).filter(_.nonEmpty),
+          originator = Option(row.mOriginator_Name.get).filter(_.nonEmpty).map(name =>
+            OpenCorridorOriginator(name, Option(row.mOriginator_Address.get).filter(_.nonEmpty))),
+          netting_snapshot_id = None,
+          promise_id = evidence.get(PromiseAttributeTxHash),
+          promise_blockchain = evidence.get(PromiseAttributeBlockchain),
+          promise_commitment = evidence.get(PromiseAttributeCommitment),
+          promise_salt = evidence.get(PromiseAttributeSalt),
+          promise_preimage = evidence.get(PromiseAttributePreimage)
+        )
+        OpenCorridorOutbox.enqueue(
+          transactionRequestId.value, "obp_credit_notification", row.mTo_BankId.get,
+          Serialization.write(wireBody))
+      }
+
   private def buildPromiseJson(
     tr: TransactionRequest,
     evidence: Map[String, String],

obp-api/src/main/scala/code/bankconnectors/opencorridor/OpenCorridorSettlement.scala

@@ -85,6 +85,13 @@ object OpenCorridorSettlement extends MdcLoggable {
           if (DoobieTransactionRequestQueries.lockTransactionRequest(trId).isEmpty) {
             logger.warn(s"Open Corridor settle: could not lock promise TR $trId — skipping")
             None
+          } else if (!hasPromiseEvidence(trId)) {
+            // No on-chain evidence yet means the beneficiary bank was never
+            // notified and never paid out — netting it would move value between
+            // banks for a payment nobody delivered. It stays PENDING for a
+            // later cycle, once the originating node reports back.
+            logger.info(s"Open Corridor settle: promise TR $trId has no on-chain evidence yet — skipping")
+            None
           } else {
             MappedTransactionRequest.find(By(MappedTransactionRequest.mTransactionRequestId, trId))
               .filter(_.mStatus.get == TransactionRequestStatus.PENDING.toString)
@@ -103,7 +110,7 @@ object OpenCorridorSettlement extends MdcLoggable {
             currency = currency,
             net_amount = "0",
             covered_transaction_request_ids = Nil,
-            credit_notifications_enqueued = 0,
+            settlement_advices_enqueued = 0,
             settlement_instructions_enqueued = 0
           ), callContext))
         } else {
@@ -222,12 +229,23 @@ object OpenCorridorSettlement extends MdcLoggable {
       })
 
       // Enqueue the Interface C messages in this same DB transaction (the outbox).
-      creditNotifications <- Future.sequence(covered.map(row => buildCreditNotification(row, callContext)))
-      _ <- Future {
-        creditNotifications.foreach { case (beneficiaryBankId, wireBody) =>
+      // Credit notifications went to each beneficiary at promise-report-back time
+      // (OpenCorridorProcessor); settlement sends each beneficiary an advice so
+      // its already-paid-out credits get marked settled.
+      settlementAdviceCount <- Future {
+        covered.groupBy(_.mTo_BankId.get).map { case (beneficiaryBankId, rows) =>
+          val advice = OutBoundOpenCorridorSettlementAdvice(
+            settlement_id = settlementTrId,
+            currency = currency,
+            net_amount = netAbs.toString(),
+            debtor_bank_id = debtorBankId,
+            creditor_bank_id = creditorBankId,
+            covered_transaction_request_ids = rows.map(_.mTransactionRequestId.get),
+            idempotency_key = settlementTrId
+          )
           OpenCorridorOutbox.enqueue(
-            settlementTrId, "obp_credit_notification", beneficiaryBankId, Serialization.write(wireBody))
-        }
+            settlementTrId, "obp_settlement_advice", beneficiaryBankId, Serialization.write(advice))
+        }.size
       }
       settlementInstructionCount <- Future {
         if (netAbs > 0) {
@@ -259,12 +277,20 @@ object OpenCorridorSettlement extends MdcLoggable {
         currency = currency,
         net_amount = netAbs.toString(),
         covered_transaction_request_ids = covered.map(_.mTransactionRequestId.get),
-        credit_notifications_enqueued = creditNotifications.size,
+        settlement_advices_enqueued = settlementAdviceCount,
         settlement_instructions_enqueued = settlementInstructionCount
       ), callContext)
     }
   }
 
+  /** True once the promise's on-chain evidence was attached (report-back done) —
+    * the precondition for the beneficiary having been notified and paid out. */
+  private def hasPromiseEvidence(trId: String): Boolean =
+    TransactionRequestAttribute.find(
+      By(TransactionRequestAttribute.Name, OpenCorridorProcessor.PromiseAttributeCommitment),
+      By(TransactionRequestAttribute.TransactionRequestId, trId)
+    ).isDefined
+
   /**
    * The GET view of one settlement (the resource minted by settlePair).
    *
@@ -347,31 +373,4 @@ object OpenCorridorSettlement extends MdcLoggable {
 
   /** Build the credit notification for one covered promise, addressed to its
     * beneficiary (to-side) bank, relaying the §5.1 evidence attributes verbatim. */
-  private def buildCreditNotification(
-    row: MappedTransactionRequest,
-    callContext: Option[CallContext]
-  ): Future[(String, OutBoundOpenCorridorCreditNotification)] = {
-    val promiseTrId = TransactionRequestId(row.mTransactionRequestId.get)
-    for {
-      (attributes, _) <- NewStyle.function.getTransactionRequestAttributes(
-        BankId(row.mFrom_BankId.get), promiseTrId, callContext)
-    } yield {
-      def attr(name: String): Option[String] =
-        attributes.find(_.name == name).map(_.value).filter(_.nonEmpty)
-      val wireBody = OutBoundOpenCorridorCreditNotification(
-        transaction_request_id = promiseTrId.value,
-        value = OpenCorridorMoneyValue(row.mBody_Value_Currency.get, row.mBody_Value_Amount.get),
-        description = Option(row.mBody_Description.get).filter(_.nonEmpty),
-        originator = Option(row.mOriginator_Name.get).filter(_.nonEmpty).map(name =>
-          OpenCorridorOriginator(name, Option(row.mOriginator_Address.get).filter(_.nonEmpty))),
-        netting_snapshot_id = None,
-        promise_id = attr(OpenCorridorProcessor.PromiseAttributeTxHash),
-        promise_blockchain = attr(OpenCorridorProcessor.PromiseAttributeBlockchain),
-        promise_commitment = attr(OpenCorridorProcessor.PromiseAttributeCommitment),
-        promise_salt = attr(OpenCorridorProcessor.PromiseAttributeSalt),
-        promise_preimage = attr(OpenCorridorProcessor.PromiseAttributePreimage)
-      )
-      (row.mTo_BankId.get, wireBody)
-    }
-  }
 }