Reference-priced forwarder swaps with whole-deposit settlement and an automatic refund path

apps/api/src/api/controllers/admin/moneriumB2b.controller.test.ts

@@ -5,6 +5,10 @@ import KycCase from "../../../models/kycCase.model";
 import ManagedProfile from "../../../models/managedProfile.model";
 import ManagedProfileManager from "../../../models/managedProfileManager.model";
 import MoneriumAccount, { MoneriumAccountStatus } from "../../../models/moneriumAccount.model";
+import MoneriumConversionExecution, {
+  MoneriumConversionExecutionStatus
+} from "../../../models/moneriumConversionExecution.model";
+import MoneriumFiatDeposit, { MoneriumFiatDepositStatus } from "../../../models/moneriumFiatDeposit.model";
 import ProviderCustomer, { VerificationStatus } from "../../../models/providerCustomer.model";
 import User from "../../../models/user.model";
 import { resetTestDatabase, setupTestDatabase } from "../../../test-utils/db";
@@ -17,7 +21,6 @@ const ADMIN_HEADERS = { Authorization: "Bearer test-admin-secret", "Content-Type
 
 const FORWARDER = "0x1111111111111111111111111111111111111111";
 const DESTINATION = "0x2222222222222222222222222222222222222222";
-const FALLBACK = "0x3333333333333333333333333333333333333333";
 const FACTORY = "0x4444444444444444444444444444444444444444";
 
 describe("monerium b2b account mapping admin route", () => {
@@ -68,7 +71,6 @@ describe("monerium b2b account mapping admin route", () => {
       contactEmail: "ops@client.example.com",
       destination: DESTINATION,
       externalSubjectId: "client-1",
-      fallbackAddress: FALLBACK,
       forwarderAddress: FORWARDER,
       managerProfileId,
       moneriumProfileId: "0b8e7c2a-8f4e-4d43-9f2b-2f9f3c1d5a6e",
@@ -122,9 +124,9 @@ describe("monerium b2b account mapping admin route", () => {
     const row = await MoneriumAccount.findByPk(account.accountId);
     expect(row).toMatchObject({
       destination: DESTINATION,
-      fallbackAddress: FALLBACK,
-      feeBps: 0,
+      floorPpm: 1500,
       forwarderAddress: FORWARDER,
+      targetPpm: 1250,
       vortexProfileId: account.profileId
     });
   });
@@ -149,8 +151,6 @@ describe("monerium b2b account mapping admin route", () => {
     const managerProfileId = await createManager();
     await MoneriumAccount.create({
       destination: DESTINATION,
-      fallbackAddress: FALLBACK,
-      feeBps: 0,
       forwarderAddress: FORWARDER,
       profileId: "0b8e7c2a-8f4e-4d43-9f2b-2f9f3c1d5a6e"
     });
@@ -191,8 +191,8 @@ describe("monerium b2b account mapping admin route", () => {
     );
     expect(differentSubject.status).toBe(409);
 
-    // Same everything, different feeBps: divergence, not a silent idempotent replay.
-    const differentFee = await post(validBody(managerProfileId, { feeBps: 25 }));
+    // Same everything, different fee policy: divergence, not a silent idempotent replay.
+    const differentFee = await post(validBody(managerProfileId, { targetPpm: 1_000 }));
     expect(differentFee.status).toBe(409);
 
     expect(await MoneriumAccount.count()).toBe(1);
@@ -206,17 +206,25 @@ describe("monerium b2b account mapping admin route", () => {
     const expected = {
       destination: DESTINATION.toLowerCase(),
       factory: FACTORY.toLowerCase(),
-      fallbackAddress: FALLBACK.toLowerCase(),
-      feeBps: 0
+      floorPpm: 1500,
+      targetPpm: 1250
+    };
+    const matching = {
+      destination: DESTINATION,
+      factory: FACTORY,
+      floorPpm: 1500,
+      isForwarder: true,
+      targetPpm: 1250
     };
-    const matching = { destination: DESTINATION, factory: FACTORY, fallbackAddress: FALLBACK, feeBps: 0, isForwarder: true };
 
     expect(forwarderConfigMismatch(expected, matching)).toBeNull();
     expect(forwarderConfigMismatch(expected, { ...matching, factory: FORWARDER })).toContain("trusted factory");
     expect(forwarderConfigMismatch(expected, { ...matching, isForwarder: false })).toContain("not a clone");
-    expect(forwarderConfigMismatch(expected, { ...matching, destination: FALLBACK })).toContain("destination");
-    expect(forwarderConfigMismatch(expected, { ...matching, fallbackAddress: DESTINATION })).toContain("fallbackAddress");
-    expect(forwarderConfigMismatch(expected, { ...matching, feeBps: 30 })).toContain("feeBps");
+    expect(
+      forwarderConfigMismatch(expected, { ...matching, destination: "0x3333333333333333333333333333333333333333" })
+    ).toContain("destination");
+    expect(forwarderConfigMismatch(expected, { ...matching, targetPpm: 1_000 })).toContain("targetPpm");
+    expect(forwarderConfigMismatch(expected, { ...matching, floorPpm: 2_000 })).toContain("floorPpm");
   });
 
   it("rejects invalid input and unknown managers", async () => {
@@ -225,10 +233,11 @@ describe("monerium b2b account mapping admin route", () => {
     for (const overrides of [
       { forwarderAddress: "not-an-address" },
       { destination: "0x12345" },
-      { fallbackAddress: "" },
       { moneriumProfileId: "not-a-uuid" },
-      { feeBps: 3.5 },
-      { feeBps: -1 },
+      { targetPpm: 3.5 },
+      { floorPpm: -1 },
+      { floorPpm: 10_001 },
+      { floorPpm: 1_000, targetPpm: 1_200 },
       { externalSubjectId: "" },
       { contactEmail: "not-an-email" }
     ]) {
@@ -291,6 +300,64 @@ describe("monerium b2b account mapping admin route", () => {
     expect((await patchStatus(crypto.randomUUID(), "active")).status).toBe(404);
   });
 
+  it("marks a settling deposit for recovery and lets an operator close or retry it", async () => {
+    const managerProfileId = await createManager();
+    const created = await post(validBody(managerProfileId));
+    const { account } = (await created.json()) as { account: { accountId: string } };
+    const deposit = await MoneriumFiatDeposit.create({
+      accountId: account.accountId,
+      amountRaw: "100000000000000000000",
+      blockNumber: 100,
+      chainId: 11155111,
+      currency: "eur",
+      logIndex: 1,
+      moneriumOrderId: "order-1",
+      status: MoneriumFiatDepositStatus.Converting,
+      txHash: "0xmint"
+    });
+    const recover = (depositId: string) =>
+      fetch(`${baseUrl}/deposits/${depositId}/recover`, { headers: ADMIN_HEADERS, method: "POST" });
+    const patchStatus = (depositId: string, status: unknown) =>
+      fetch(`${baseUrl}/deposits/${depositId}/status`, {
+        body: JSON.stringify({ status }),
+        headers: ADMIN_HEADERS,
+        method: "PATCH"
+      });
+
+    // A pending keeper transaction must settle first: the amounts to recover depend on it.
+    const pending = await MoneriumConversionExecution.create({
+      accountId: account.accountId,
+      depositId: deposit.id,
+      destination: DESTINATION,
+      eureInRaw: "60000000000000000000",
+      status: MoneriumConversionExecutionStatus.Pending
+    });
+    const blocked = await recover(deposit.id);
+    expect(blocked.status).toBe(409);
+    expect(await blocked.json()).toMatchObject({ error: { message: expect.stringContaining("pending execution") } });
+    await pending.update({ status: MoneriumConversionExecutionStatus.Failed });
+
+    const marked = await recover(deposit.id);
+    expect(marked.status).toBe(200);
+    expect(await marked.json()).toMatchObject({ deposit: { depositId: deposit.id, status: "recovering" } });
+    expect((await MoneriumFiatDeposit.findByPk(deposit.id))?.status).toBe(MoneriumFiatDepositStatus.Recovering);
+
+    // Forward-only: a recovering deposit cannot be marked again, but closes or retries.
+    expect((await recover(deposit.id)).status).toBe(409);
+    expect((await patchStatus(deposit.id, "forwarded")).status).toBe(400);
+    const failed = await patchStatus(deposit.id, "recovery_failed");
+    expect(failed.status).toBe(200);
+    const retried = await patchStatus(deposit.id, "recovering");
+    expect(retried.status).toBe(200);
+    const refunded = await patchStatus(deposit.id, "refunded");
+    expect(refunded.status).toBe(200);
+    expect((await patchStatus(deposit.id, "recovering")).status).toBe(409);
+    expect((await MoneriumFiatDeposit.findByPk(deposit.id))?.status).toBe(MoneriumFiatDepositStatus.Refunded);
+
+    expect((await recover(crypto.randomUUID())).status).toBe(404);
+    expect((await recover("not-a-uuid")).status).toBe(400);
+  });
+
   it("refuses managers not allowed to provision business customers", async () => {
     const profile = await createTestUser();
     await ManagedProfileManager.create({

apps/api/src/api/controllers/admin/moneriumB2b.controller.ts

@@ -2,8 +2,11 @@ import { Request, Response } from "express";
 import httpStatus from "http-status";
 import logger from "../../../config/logger";
 import MoneriumAccount, { MoneriumAccountStatus } from "../../../models/moneriumAccount.model";
+import MoneriumFiatDeposit, { MoneriumFiatDepositStatus } from "../../../models/moneriumFiatDeposit.model";
 import { ManagedProfileProvisioningError } from "../../services/managed-profile-provisioning.service";
 import { MoneriumB2bProvisioningError, provisionMoneriumB2bAccount } from "../../services/monerium-b2b/account-provisioning";
+import { markDepositForRecovery } from "../../services/monerium-b2b/conversion-executor";
+import { isForwardTransition, withForwarderLock } from "../../services/monerium-b2b/deposit-processor";
 
 const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 
@@ -13,11 +16,11 @@ export async function postMoneriumB2bAccount(req: Request, res: Response): Promi
       contactEmail,
       destination,
       externalSubjectId,
-      fallbackAddress,
-      feeBps,
+      floorPpm,
       forwarderAddress,
       managerProfileId,
-      moneriumProfileId
+      moneriumProfileId,
+      targetPpm
     } = req.body ?? {};
     if (
       typeof managerProfileId !== "string" ||
@@ -29,14 +32,14 @@ export async function postMoneriumB2bAccount(req: Request, res: Response): Promi
       typeof contactEmail !== "string" ||
       typeof forwarderAddress !== "string" ||
       typeof destination !== "string" ||
-      typeof fallbackAddress !== "string" ||
-      (feeBps !== undefined && typeof feeBps !== "number")
+      (targetPpm !== undefined && typeof targetPpm !== "number") ||
+      (floorPpm !== undefined && typeof floorPpm !== "number")
     ) {
       res.status(httpStatus.BAD_REQUEST).json({
         error: {
           code: "MONERIUM_B2B_INVALID_INPUT",
           message:
-            "managerProfileId (UUID), moneriumProfileId, externalSubjectId (1-255 characters), contactEmail, forwarderAddress, destination, and fallbackAddress are required; feeBps must be a number when present",
+            "managerProfileId (UUID), moneriumProfileId, externalSubjectId (1-255 characters), contactEmail, forwarderAddress, and destination are required; targetPpm and floorPpm must be numbers when present",
           status: httpStatus.BAD_REQUEST
         }
       });
@@ -47,11 +50,11 @@ export async function postMoneriumB2bAccount(req: Request, res: Response): Promi
       contactEmail,
       destination,
       externalSubjectId,
-      fallbackAddress,
-      feeBps,
+      floorPpm,
       forwarderAddress,
       managerProfileId,
-      moneriumProfileId
+      moneriumProfileId,
+      targetPpm
     });
     res.status(result.created ? httpStatus.CREATED : httpStatus.OK).json({ account: result });
   } catch (error) {
@@ -150,3 +153,112 @@ export async function patchMoneriumB2bAccountStatus(req: Request<{ accountId: st
     });
   }
 }
+
+/**
+ * POST /v1/admin/monerium-b2b/deposits/:depositId/recover — marks a settling deposit for
+ * the refund path (runbook §2.7). The keeper moves its unconverted EURe and converted
+ * USDC to the recovery wallet once the clone's batch has been open for RECOVERY_DELAY;
+ * the bank refund itself follows the runbook until it is automated.
+ */
+export async function postMoneriumB2bDepositRecovery(req: Request<{ depositId: string }>, res: Response): Promise<void> {
+  try {
+    if (!UUID_PATTERN.test(req.params.depositId)) {
+      res.status(httpStatus.BAD_REQUEST).json({
+        error: { code: "MONERIUM_B2B_INVALID_INPUT", message: "depositId must be a UUID", status: httpStatus.BAD_REQUEST }
+      });
+      return;
+    }
+    const refusal = await markDepositForRecovery(req.params.depositId);
+    if (refusal === "deposit not found") {
+      res.status(httpStatus.NOT_FOUND).json({
+        error: { code: "MONERIUM_B2B_DEPOSIT_NOT_FOUND", message: "Monerium deposit not found", status: httpStatus.NOT_FOUND }
+      });
+      return;
+    }
+    if (refusal) {
+      res.status(httpStatus.CONFLICT).json({
+        error: { code: "MONERIUM_B2B_INVALID_STATUS_TRANSITION", message: refusal, status: httpStatus.CONFLICT }
+      });
+      return;
+    }
+    res
+      .status(httpStatus.OK)
+      .json({ deposit: { depositId: req.params.depositId, status: MoneriumFiatDepositStatus.Recovering } });
+  } catch (error) {
+    logger.error("Error marking Monerium B2B deposit for recovery:", error);
+    res.status(httpStatus.INTERNAL_SERVER_ERROR).json({
+      error: {
+        code: "INTERNAL_SERVER_ERROR",
+        message: "Failed to mark the deposit for recovery",
+        status: httpStatus.INTERNAL_SERVER_ERROR
+      }
+    });
+  }
+}
+
+const OPERATOR_DEPOSIT_STATUSES: readonly string[] = [
+  MoneriumFiatDepositStatus.Refunded,
+  MoneriumFiatDepositStatus.RecoveryFailed,
+  MoneriumFiatDepositStatus.Recovering
+];
+
+/**
+ * PATCH /v1/admin/monerium-b2b/deposits/:depositId/status — closes or retries a
+ * recovery by hand: `refunded` once the bank refund went out, `recovery_failed` when it
+ * cannot, `recovering` to retry a failed one. Forward-only like every deposit transition.
+ */
+export async function patchMoneriumB2bDepositStatus(req: Request<{ depositId: string }>, res: Response): Promise<void> {
+  try {
+    const { status } = req.body ?? {};
+    if (!UUID_PATTERN.test(req.params.depositId) || typeof status !== "string" || !OPERATOR_DEPOSIT_STATUSES.includes(status)) {
+      res.status(httpStatus.BAD_REQUEST).json({
+        error: {
+          code: "MONERIUM_B2B_INVALID_INPUT",
+          message: `depositId must be a UUID and status must be one of ${OPERATOR_DEPOSIT_STATUSES.join(", ")}`,
+          status: httpStatus.BAD_REQUEST
+        }
+      });
+      return;
+    }
+    const deposit = await MoneriumFiatDeposit.findByPk(req.params.depositId);
+    if (!deposit) {
+      res.status(httpStatus.NOT_FOUND).json({
+        error: { code: "MONERIUM_B2B_DEPOSIT_NOT_FOUND", message: "Monerium deposit not found", status: httpStatus.NOT_FOUND }
+      });
+      return;
+    }
+    const account = await MoneriumAccount.findByPk(deposit.accountId);
+    if (!account) {
+      res.status(httpStatus.NOT_FOUND).json({
+        error: { code: "MONERIUM_B2B_ACCOUNT_NOT_FOUND", message: "Monerium account not found", status: httpStatus.NOT_FOUND }
+      });
+      return;
+    }
+    const targetStatus = status as MoneriumFiatDepositStatus;
+    const outcome = await withForwarderLock(account.forwarderAddress, async transaction => {
+      const current = await MoneriumFiatDeposit.findByPk(deposit.id, { transaction });
+      if (!current) return "missing";
+      if (targetStatus === current.status) return "same";
+      if (!isForwardTransition(current.status, targetStatus))
+        return `Monerium deposit cannot transition from ${current.status} to ${targetStatus}`;
+      await current.update({ status: targetStatus }, { transaction });
+      return "updated";
+    });
+    if (outcome !== "updated" && outcome !== "same") {
+      res.status(httpStatus.CONFLICT).json({
+        error: { code: "MONERIUM_B2B_INVALID_STATUS_TRANSITION", message: outcome, status: httpStatus.CONFLICT }
+      });
+      return;
+    }
+    res.status(httpStatus.OK).json({ deposit: { depositId: deposit.id, status: targetStatus } });
+  } catch (error) {
+    logger.error("Error updating Monerium B2B deposit status:", error);
+    res.status(httpStatus.INTERNAL_SERVER_ERROR).json({
+      error: {
+        code: "INTERNAL_SERVER_ERROR",
+        message: "Failed to update Monerium B2B deposit status",
+        status: httpStatus.INTERNAL_SERVER_ERROR
+      }
+    });
+  }
+}