Make AlfredPay sell discounts executable

apps/api/src/api/services/phases/blocks/README.md

@@ -592,6 +592,16 @@ Unmapped cases fail at quote resolution; there is no alternate engine:
    `EUR_ONRAMP_BASE_SAME_CHAIN_SWAP` with one Base-built same-chain Squid swap
    immediately before destination transfer. No same-chain variant includes
    Squid pay, backups, or final settlement.
+9. **AlfredPay SELL reconciliation stays block-owned.** `AlfredpayOfframp`
+   derives the fiat target from the exact Vortex reference snapshot, requests
+   AlfredPay's executable exact-output terms, and caps the raw settlement top-up.
+   It does not add a cross-reading subsidy block or make the provider rate a
+   global price source. `finalSettlementSubsidy` consumes the persisted provider
+   input and quoted bridge output without recalculating quote economics or exceeding
+   the persisted subsidy. Provider orders remain bound to those persisted terms; if
+   an expired order cannot be replaced
+   without degrading them, execution pauses before the single-use provider transfer
+   and leaves the funds on the client-custodied Polygon ephemeral for reconciliation.
 
 ### Runtime ownership
 

apps/api/src/api/services/phases/blocks/__tests__/alfredpay-offramp.registration.test.ts

@@ -1,6 +1,8 @@
 import { describe, expect, it, mock } from "bun:test";
 import {
   AlfredpayFeeType,
+  AlfredpayChain,
+  AlfredpayOfframpStatus,
   AlfredpayOnChainCurrency,
   type EvmNetworks,
   EvmToken,
@@ -10,6 +12,8 @@ import {
 import { registerAlfredpayOfframp } from "../phases/alfredpay-offramp/registration";
 import type { AlfredpayOfframpMetadata } from "../phases/alfredpay-offramp/simulation";
 
+const safeExpiration = new Date(Date.now() + 10 * 60_000).toISOString();
+
 const metadata: AlfredpayOfframpMetadata = {
   adjustedDifference: "0",
   adjustedTargetDiscount: "0",
@@ -69,14 +73,27 @@ describe("Alfredpay offramp registration", () => {
   it("refreshes exact quotes, creates the order, and updates only provider identity metadata", async () => {
     const service = {
       createOfframp: mock(async () => ({
+        chain: AlfredpayChain.MATIC,
+        customerId: "customer-1",
         depositAddress: "0x5555555555555555555555555555555555555555",
+        expiration: safeExpiration,
+        fiatAccountId: "fiat-1",
+        fromAmount: "99",
+        fromCurrency: AlfredpayOnChainCurrency.USDT,
+        status: AlfredpayOfframpStatus.CREATED,
+        toAmount: "1980",
+        toCurrency: FiatToken.MXN,
         transactionId: "transaction-1"
       })),
       createOfframpQuote: mock(async () => ({
-        expiration: "2026-01-01T00:01:00Z",
+        chain: AlfredpayChain.MATIC,
+        expiration: safeExpiration,
         fees: [{ amount: "1", currency: "MXN" }],
+        fromAmount: "99",
+        fromCurrency: AlfredpayOnChainCurrency.USDT,
         quoteId: "quote-new",
-        toAmount: "1980"
+        toAmount: "1980",
+        toCurrency: FiatToken.MXN
       }))
     } as never;
     const result = await registerAlfredpayOfframp(context(), {
@@ -85,7 +102,7 @@ describe("Alfredpay offramp registration", () => {
     });
     expect(result.metadata).toEqual({
       ...metadata,
-      expirationDate: new Date("2026-01-01T00:01:00Z"),
+      expirationDate: new Date(safeExpiration),
       quoteId: "quote-new"
     });
     expect(result.facts).toEqual({
@@ -97,20 +114,229 @@ describe("Alfredpay offramp registration", () => {
     });
   });
 
-  it("hard-fails on refreshed amount drift before creating an order", async () => {
+  it("hard-fails on refreshed output drift before creating an order", async () => {
+    const createOrder = mock(async () => ({}));
+    const service = {
+      createOfframp: createOrder,
+      createOfframpQuote: mock(async () => ({
+        chain: AlfredpayChain.MATIC,
+        expiration: safeExpiration,
+        fees: [{ amount: "1", currency: "MXN" }],
+        fromAmount: "99",
+        fromCurrency: AlfredpayOnChainCurrency.USDT,
+        quoteId: "quote-new",
+        toAmount: "1979",
+        toCurrency: FiatToken.MXN
+      }))
+    } as never;
+    await expect(
+      registerAlfredpayOfframp(context(), { resolveCustomerId: async () => "customer-1", service })
+    ).rejects.toThrow("drifted");
+    expect(createOrder).not.toHaveBeenCalled();
+  });
+
+  it("hard-fails on refreshed input drift before creating an order", async () => {
+    const createOrder = mock(async () => ({}));
+    const service = {
+      createOfframp: createOrder,
+      createOfframpQuote: mock(async () => ({
+        chain: AlfredpayChain.MATIC,
+        expiration: safeExpiration,
+        fees: [{ amount: "1", currency: "MXN" }],
+        fromAmount: "98.999999",
+        fromCurrency: AlfredpayOnChainCurrency.USDT,
+        quoteId: "quote-new",
+        toAmount: "1980",
+        toCurrency: FiatToken.MXN
+      }))
+    } as never;
+    await expect(
+      registerAlfredpayOfframp(context(), { resolveCustomerId: async () => "customer-1", service })
+    ).rejects.toThrow("drifted");
+    expect(createOrder).not.toHaveBeenCalled();
+  });
+
+  it("hard-fails on refreshed currency drift before creating an order", async () => {
     const createOrder = mock(async () => ({}));
     const service = {
       createOfframp: createOrder,
       createOfframpQuote: mock(async () => ({
-        expiration: "2026-01-01T00:01:00Z",
+        chain: AlfredpayChain.MATIC,
+        expiration: safeExpiration,
         fees: [{ amount: "1", currency: "MXN" }],
+        fromAmount: "99",
+        fromCurrency: AlfredpayOnChainCurrency.USDT,
         quoteId: "quote-new",
-        toAmount: "1979"
+        toAmount: "1980",
+        toCurrency: FiatToken.COP
       }))
     } as never;
     await expect(
       registerAlfredpayOfframp(context(), { resolveCustomerId: async () => "customer-1", service })
     ).rejects.toThrow("drifted");
     expect(createOrder).not.toHaveBeenCalled();
   });
+
+  it("rejects a refreshed quote that cannot safely survive registration and signing", async () => {
+    const createOrder = mock(async () => ({}));
+    const service = {
+      createOfframp: createOrder,
+      createOfframpQuote: mock(async () => ({
+        chain: AlfredpayChain.MATIC,
+        expiration: new Date(Date.now() + 5_000).toISOString(),
+        fees: [{ amount: "1", currency: "MXN" }],
+        fromAmount: "99",
+        fromCurrency: AlfredpayOnChainCurrency.USDT,
+        quoteId: "quote-near-expiry",
+        toAmount: "1980",
+        toCurrency: FiatToken.MXN
+      }))
+    } as never;
+
+    await expect(
+      registerAlfredpayOfframp(context(), { resolveCustomerId: async () => "customer-1", service })
+    ).rejects.toThrow("drifted");
+    expect(createOrder).not.toHaveBeenCalled();
+  });
+
+  it("fails closed when the created order is not bound to the refreshed quote", async () => {
+    const createOrder = mock(async () => ({
+      chain: AlfredpayChain.MATIC,
+      customerId: "customer-1",
+      depositAddress: "0x5555555555555555555555555555555555555555",
+      expiration: safeExpiration,
+      fiatAccountId: "fiat-1",
+      fromAmount: "99",
+      fromCurrency: AlfredpayOnChainCurrency.USDT,
+      status: AlfredpayOfframpStatus.CREATED,
+      toAmount: "1979",
+      toCurrency: FiatToken.MXN,
+      transactionId: "transaction-drifted"
+    }));
+    const service = {
+      createOfframp: createOrder,
+      createOfframpQuote: mock(async () => ({
+        chain: AlfredpayChain.MATIC,
+        expiration: safeExpiration,
+        fees: [{ amount: "1", currency: "MXN" }],
+        fromAmount: "99",
+        fromCurrency: AlfredpayOnChainCurrency.USDT,
+        quoteId: "quote-new",
+        toAmount: "1980",
+        toCurrency: FiatToken.MXN
+      }))
+    } as never;
+
+    await expect(
+      registerAlfredpayOfframp(context(), { resolveCustomerId: async () => "customer-1", service })
+    ).rejects.toThrow("Created Alfredpay offramp order drifted");
+    expect(createOrder).toHaveBeenCalledTimes(1);
+  });
+
+  it("fails closed when the created order cannot safely outlive broadcast and indexing", async () => {
+    const createOrder = mock(async () => ({
+      chain: AlfredpayChain.MATIC,
+      customerId: "customer-1",
+      depositAddress: "0x5555555555555555555555555555555555555555",
+      expiration: new Date(Date.now() + 30_000).toISOString(),
+      fiatAccountId: "fiat-1",
+      fromAmount: "99",
+      fromCurrency: AlfredpayOnChainCurrency.USDT,
+      status: AlfredpayOfframpStatus.CREATED,
+      toAmount: "1980",
+      toCurrency: FiatToken.MXN,
+      transactionId: "transaction-near-expiry"
+    }));
+    const service = {
+      createOfframp: createOrder,
+      createOfframpQuote: mock(async () => ({
+        chain: AlfredpayChain.MATIC,
+        expiration: safeExpiration,
+        fees: [{ amount: "1", currency: "MXN" }],
+        fromAmount: "99",
+        fromCurrency: AlfredpayOnChainCurrency.USDT,
+        quoteId: "quote-new",
+        toAmount: "1980",
+        toCurrency: FiatToken.MXN
+      }))
+    } as never;
+
+    await expect(
+      registerAlfredpayOfframp(context(), { resolveCustomerId: async () => "customer-1", service })
+    ).rejects.toThrow("Created Alfredpay offramp order drifted");
+    expect(createOrder).toHaveBeenCalledTimes(1);
+  });
+
+  it("accepts a usable short-lived provider quote when the created order has safe execution lifetime", async () => {
+    const createOrder = mock(async () => ({
+      chain: AlfredpayChain.MATIC,
+      customerId: "customer-1",
+      depositAddress: "0x5555555555555555555555555555555555555555",
+      expiration: safeExpiration,
+      fiatAccountId: "fiat-1",
+      fromAmount: "99",
+      fromCurrency: AlfredpayOnChainCurrency.USDT,
+      status: AlfredpayOfframpStatus.CREATED,
+      toAmount: "1980",
+      toCurrency: FiatToken.MXN,
+      transactionId: "transaction-short-quote"
+    }));
+    const service = {
+      createOfframp: createOrder,
+      createOfframpQuote: mock(async () => ({
+        chain: AlfredpayChain.MATIC,
+        expiration: new Date(Date.now() + 30_000).toISOString(),
+        fees: [{ amount: "1", currency: "MXN" }],
+        fromAmount: "99",
+        fromCurrency: AlfredpayOnChainCurrency.USDT,
+        quoteId: "quote-short-lived",
+        toAmount: "1980",
+        toCurrency: FiatToken.MXN
+      }))
+    } as never;
+
+    const result = await registerAlfredpayOfframp(context(), {
+      resolveCustomerId: async () => "customer-1",
+      service
+    });
+
+    expect(result.facts.alfredpayTransactionId).toBe("transaction-short-quote");
+    expect(createOrder).toHaveBeenCalledTimes(1);
+  });
+
+  it("rejects created-order responses whose lifecycle is not CREATED", async () => {
+    for (const status of [AlfredpayOfframpStatus.FAILED, AlfredpayOfframpStatus.FIAT_TRANSFER_COMPLETED]) {
+      const createOrder = mock(async () => ({
+        chain: AlfredpayChain.MATIC,
+        customerId: "customer-1",
+        depositAddress: "0x5555555555555555555555555555555555555555",
+        expiration: safeExpiration,
+        fiatAccountId: "fiat-1",
+        fromAmount: "99",
+        fromCurrency: AlfredpayOnChainCurrency.USDT,
+        status,
+        toAmount: "1980",
+        toCurrency: FiatToken.MXN,
+        transactionId: `transaction-${status}`
+      }));
+      const service = {
+        createOfframp: createOrder,
+        createOfframpQuote: mock(async () => ({
+          chain: AlfredpayChain.MATIC,
+          expiration: safeExpiration,
+          fees: [{ amount: "1", currency: "MXN" }],
+          fromAmount: "99",
+          fromCurrency: AlfredpayOnChainCurrency.USDT,
+          quoteId: "quote-new",
+          toAmount: "1980",
+          toCurrency: FiatToken.MXN
+        }))
+      } as never;
+
+      await expect(
+        registerAlfredpayOfframp(context(), { resolveCustomerId: async () => "customer-1", service })
+      ).rejects.toThrow("Created Alfredpay offramp order drifted");
+      expect(createOrder).toHaveBeenCalledTimes(1);
+    }
+  });
 });