Create new production release

.agents/skills/vortex-integration/SKILL.md

@@ -504,7 +504,7 @@ const vortex = new VortexSdk({
 });
 ```
 
-For server processes that manage their own ephemeral key storage (e.g. HSM, encrypted DB), set `storeEphemeralKeys: false` and persist via your own mechanism.
+For server processes that manage their own ephemeral key storage (e.g. HSM, encrypted DB), configure `storeEphemeralKeysCallback: async (keys, rampId) => { ... }`. The SDK calls it with the recovery material (`StoredEphemeralKey[]`: `{ address, rampId, secret, type }`) instead of writing the local file, and `storeEphemeralKeys` has no effect. A rejection aborts `registerRamp` before ephemeral-owned transactions are signed (same fail-closed contract as built-in storage). Setting only `storeEphemeralKeys: false` disables the recovery backup entirely — the secrets are not exposed anywhere else.
 
 For browser integrations, never configure `secretKey`. Resolve the current renewable Supabase token on every request:
 
@@ -519,7 +519,7 @@ const vortex = new VortexSdk({
 });
 ```
 
-If both `secretKey` and `accessTokenProvider` are configured, the SDK uses the secret key and does not call the provider. Browser ephemeral recovery currently uses plain `localStorage`; this is intentionally prototype-grade. Set `storeEphemeralKeys: false` when the integrating application owns secure recovery storage.
+If both `secretKey` and `accessTokenProvider` are configured, the SDK uses the secret key and does not call the provider. Browser ephemeral recovery currently uses plain `localStorage`; this is intentionally prototype-grade. Configure `storeEphemeralKeysCallback` when the integrating application owns secure recovery storage (or set `storeEphemeralKeys: false` to disable the backup entirely).
 
 ## REST fallback
 Use:

apps/api/src/api/controllers/brla.controller.ts

@@ -1336,7 +1336,7 @@ export const getKybAttemptStatus = async (
 
       // Queue only after proving this is still the bound attempt. A queue failure rolls
       // back the terminal state so a later poll can retry the notification.
-      await enqueueVerificationNotification(attempt, effectiveUserId, "business");
+      await enqueueVerificationNotification(attempt, effectiveUserId, "business", transaction);
       await lockedRecord.update(
         {
           lastFailureReasons: failureReason ? [failureReason] : [],

apps/api/src/api/services/avenia/avenia-customer.service.test.ts

@@ -1,17 +1,26 @@
+import { KycAttemptResult, KycAttemptStatus } from "@vortexfi/shared";
 import { afterEach, describe, expect, it, mock } from "bun:test";
 import sequelize from "../../../config/database";
+import EmailNotification from "../../../models/emailNotification.model";
 import KycCase from "../../../models/kycCase.model";
 import ProviderCustomer, { VerificationStatus } from "../../../models/providerCustomer.model";
+import { SupabaseAuthService } from "../auth";
 import { updateAveniaKycOutcomeForCustomer, updateAveniaKycProgressForCustomer } from "./avenia-customer.service";
 
 const originalTransaction = sequelize.transaction;
 const originalCustomerFindByPk = ProviderCustomer.findByPk;
 const originalCaseFindAll = KycCase.findAll;
+const originalNotificationFindOne = EmailNotification.findOne;
+const originalNotificationFindOrCreate = EmailNotification.findOrCreate;
+const originalGetUserLocale = SupabaseAuthService.getUserLocale;
 
 afterEach(() => {
   sequelize.transaction = originalTransaction;
   ProviderCustomer.findByPk = originalCustomerFindByPk;
   KycCase.findAll = originalCaseFindAll;
+  EmailNotification.findOne = originalNotificationFindOne;
+  EmailNotification.findOrCreate = originalNotificationFindOrCreate;
+  SupabaseAuthService.getUserLocale = originalGetUserLocale;
 });
 
 function setup(
@@ -53,6 +62,7 @@ function setup(
 
   ProviderCustomer.findByPk = mock(async () => customer) as unknown as typeof ProviderCustomer.findByPk;
   KycCase.findAll = mock(async () => [kycCase]) as unknown as typeof KycCase.findAll;
+  const transaction = { LOCK: { UPDATE: "UPDATE" } } as never;
   sequelize.transaction = mock(async callback => {
     const customerSnapshot = { status: customer.status, statusExternal: customer.statusExternal };
     const caseSnapshot = {
@@ -62,15 +72,15 @@ function setup(
       statusExternal: kycCase.statusExternal
     };
     try {
-      return await callback({ LOCK: { UPDATE: "UPDATE" } } as never);
+      return await callback(transaction);
     } catch (error) {
       Object.assign(customer, customerSnapshot);
       Object.assign(kycCase, caseSnapshot);
       throw error;
     }
   }) as unknown as typeof sequelize.transaction;
 
-  return { customer, kycCase };
+  return { customer, kycCase, transaction };
 }
 
 describe("updateAveniaKycOutcomeForCustomer", () => {
@@ -107,6 +117,41 @@ describe("updateAveniaKycOutcomeForCustomer", () => {
     expect(kycCase.rejectedAt).toBeNull();
   });
 
+  it("queues the outcome notification in the status transaction", async () => {
+    const { customer, transaction } = setup(VerificationStatus.InReview, VerificationStatus.InReview);
+    let duplicateCheckTransaction: unknown;
+    let insertTransaction: unknown;
+    EmailNotification.findOne = mock(async options => {
+      duplicateCheckTransaction = options.transaction;
+      return null;
+    }) as unknown as typeof EmailNotification.findOne;
+    EmailNotification.findOrCreate = mock(async options => {
+      insertTransaction = options.transaction;
+      return [{} as EmailNotification, true];
+    }) as unknown as typeof EmailNotification.findOrCreate;
+    SupabaseAuthService.getUserLocale = mock(async () => "en-US") as typeof SupabaseAuthService.getUserLocale;
+
+    await updateAveniaKycOutcomeForCustomer(
+      customer,
+      VerificationStatus.Approved,
+      KycAttemptStatus.COMPLETED,
+      { id: "case-1", providerCaseId: "attempt-1" },
+      {
+        attempt: {
+          id: "attempt-1",
+          result: KycAttemptResult.APPROVED,
+          status: KycAttemptStatus.COMPLETED,
+          updatedAt: "2026-08-25T12:00:00.000Z"
+        },
+        profileId: "user-1",
+        subject: "individual"
+      }
+    );
+
+    expect(duplicateCheckTransaction).toBe(transaction);
+    expect(insertTransaction).toBe(transaction);
+  });
+
   it("does not downgrade either row for a stale rejection after approval", async () => {
     const { customer, kycCase } = setup(VerificationStatus.Approved, VerificationStatus.Approved, {
       customerStatusExternal: "COMPLETED",

apps/api/src/api/services/avenia/avenia-customer.service.ts

@@ -207,7 +207,7 @@ export async function updateAveniaKycOutcomeForCustomer(
       // Queue only after the case binding was proven above. Enqueuing is idempotent on the
       // attempt id, and a queue failure rolls back the terminal state so a later poll can
       // retry the notification (parity with GET /v1/brla/kyb/attempt-status).
-      await enqueueVerificationNotification(appliedNotify.attempt, appliedNotify.profileId, appliedNotify.subject);
+      await enqueueVerificationNotification(appliedNotify.attempt, appliedNotify.profileId, appliedNotify.subject, transaction);
     }
     return lockedRecord;
   });

apps/api/src/api/services/avenia/verification-notifications.ts

@@ -1,4 +1,5 @@
 import { AveniaVerificationAttempt, KycAttemptResult, KycAttemptStatus, KycFailureReason } from "@vortexfi/shared";
+import type { Transaction } from "sequelize";
 import { NotificationProvider, NotificationType } from "../../../models/emailNotification.model";
 import { enqueueNotification } from "../email";
 import { VerificationSubject } from "../email/types";
@@ -64,25 +65,29 @@ function terminalNotificationType(attempt: NotifiableAttempt): NotificationType
 export async function enqueueVerificationNotification(
   attempt: NotifiableAttempt,
   userId: string,
-  subject: VerificationSubject
+  subject: VerificationSubject,
+  transaction?: Transaction
 ): Promise<boolean> {
   const type = terminalNotificationType(attempt);
   if (!type) {
     return false;
   }
 
-  await enqueueNotification({
-    payload: {
-      reason:
-        type === NotificationType.VerificationRejected ? (attempt.resultMessage?.slice(0, MAX_REASON_LENGTH) ?? null) : null,
-      subject,
-      updatedAt: attempt.updatedAt
+  await enqueueNotification(
+    {
+      payload: {
+        reason:
+          type === NotificationType.VerificationRejected ? (attempt.resultMessage?.slice(0, MAX_REASON_LENGTH) ?? null) : null,
+        subject,
+        updatedAt: attempt.updatedAt
+      },
+      provider: NotificationProvider.Avenia,
+      resourceId: attempt.id,
+      type,
+      userId
     },
-    provider: NotificationProvider.Avenia,
-    resourceId: attempt.id,
-    type,
-    userId
-  });
+    transaction
+  );
 
   return true;
 }

apps/api/src/api/services/email/notification.service.ts

@@ -1,4 +1,4 @@
-import { literal, Op } from "sequelize";
+import { literal, Op, type Transaction } from "sequelize";
 import sequelize from "../../../config/database";
 import logger from "../../../config/logger";
 import { config } from "../../../config/vars";
@@ -31,17 +31,21 @@ function describeKey({ provider, type, resourceId }: NotificationKey): string {
  * Records a notification to be emailed. Idempotent on the notification key:
  * enqueuing the same event twice is a no-op, so callers can fire without guarding.
  */
-export async function enqueueNotification({ userId, payload, ...key }: EnqueueParams): Promise<void> {
+export async function enqueueNotification(
+  { userId, payload, ...key }: EnqueueParams,
+  transaction?: Transaction
+): Promise<void> {
   // Duplicates are the common case (webhook replays, re-polled attempts), so check the
   // key before resolving the locale — that resolution is a Supabase admin API call.
-  if (await EmailNotification.findOne({ where: { ...key } })) {
+  if (await EmailNotification.findOne({ transaction, where: { ...key } })) {
     return;
   }
 
   const locale = await SupabaseAuthService.getUserLocale(userId);
 
   const [, created] = await EmailNotification.findOrCreate({
     defaults: { ...key, locale, payload, userId },
+    transaction,
     where: { ...key }
   });
 

apps/api/src/api/services/phases/blocks/__tests__/brl-onramp-base-cross-chain.flow.test.ts

@@ -1,11 +1,21 @@
-import { afterAll, describe, expect, it, mock } from "bun:test";
+import { afterAll, afterEach, describe, expect, it, mock } from "bun:test";
 import Big from "big.js";
-import { BrlaApiService, EPaymentMethod, EvmToken, FiatToken, Networks, RampDirection, RampPhase } from "@vortexfi/shared";
+import {
+  BrlaApiService,
+  EPaymentMethod,
+  EvmToken,
+  type EvmNetworks,
+  FiatToken,
+  Networks,
+  RampDirection,
+  RampPhase
+} from "@vortexfi/shared";
 import { config } from "../../../../../config/vars";
 import * as partnerPricingNamespace from "../../../partners/partner-pricing.service";
 
 const partnerPricingReal = { ...partnerPricingNamespace };
 const brlaApiServiceGetInstanceReal = BrlaApiService.getInstance;
+let activePricing: Awaited<ReturnType<typeof partnerPricingNamespace.findPartnerWithPricing>> = null;
 
 mock.module("../core/nabla", () => ({
   calculateNablaSwapOutput: async () => {
@@ -27,7 +37,8 @@ mock.module("../core/squidrouter", () => ({
   }),
   getEvmBridgeQuote: async ({ amountDecimal }: { amountDecimal: string }) => ({
     networkFeeUSD: "0.1",
-    outputAmountDecimal: new Big(amountDecimal)
+    outputAmountDecimal: new Big(amountDecimal),
+    outputAmountUsd: new Big(amountDecimal)
   }),
   getBridgeTargetTokenDetails: () => ({
     erc20AddressSourceChain: "0xaf88d065e77c8cC2239327C5EDb3A432268e5831"
@@ -42,9 +53,13 @@ mock.module("../../../priceFeed.service", () => ({
 }));
 
 mock.module("../../../partners/partner-pricing.service", () => ({
-  findPartnerWithPricing: async () => null
+  findPartnerWithPricing: async () => activePricing
 }));
 
+afterEach(() => {
+  activePricing = null;
+});
+
 afterAll(() => {
   BrlaApiService.getInstance = brlaApiServiceGetInstanceReal;
   mock.module("../../../partners/partner-pricing.service", () => ({ ...partnerPricingReal }));
@@ -167,7 +182,11 @@ describe("BRL cross-chain onramp flow compile-time adjacency", () => {
   });
 });
 
-function buildCtx(includeDynamicFunding = true): PhaseCtx {
+function buildCtx(
+  includeDynamicFunding = true,
+  to: EvmNetworks = Networks.Arbitrum,
+  outputCurrency: EvmToken = EvmToken.USDC
+): PhaseCtx {
   const notes: string[] = [];
   return {
     addNote: (note: string) => {
@@ -184,7 +203,7 @@ function buildCtx(includeDynamicFunding = true): PhaseCtx {
             fundingGasLimit: "21000",
             isNativeTransfer: false,
             maximumFeePerGas: "1",
-            network: Networks.Arbitrum,
+            network: to,
             programVersion: 2 as const,
             transferGasLimit: "100000"
           }
@@ -198,9 +217,9 @@ function buildCtx(includeDynamicFunding = true): PhaseCtx {
       inputAmount: "100",
       inputCurrency: FiatToken.BRL,
       network: Networks.Base,
-      outputCurrency: EvmToken.USDC,
+      outputCurrency,
       rampType: RampDirection.BUY,
-      to: Networks.Arbitrum
+      to
     }
   };
 }
@@ -235,6 +254,47 @@ describe("BRL cross-chain onramp flow simulation", () => {
       config.evmDestinationGas.dynamicFundingEnabled = originalEnabled;
     }
   });
+
+  it("keeps non-stable destination subsidy bounded in source USDC", async () => {
+    activePricing = {
+      displayName: "Vortex",
+      fiatCurrency: FiatToken.BRL,
+      id: "vortex-pricing",
+      logoUrl: null,
+      markupCurrency: EvmToken.USDC,
+      markupType: "none",
+      markupValue: 0,
+      maxDynamicDifference: 0,
+      maxSubsidy: 0.003,
+      minDynamicDifference: 0,
+      name: "vortex",
+      payoutAddressEvm: null,
+      payoutAddressSubstrate: null,
+      rampType: RampDirection.BUY,
+      targetDiscount: -0.0017,
+      vortexFeeType: "none",
+      vortexFeeValue: 0
+    };
+    BrlaApiService.getInstance = mock(() => ({
+      createPayInQuote: mock(async () => ({
+        appliedFees: [{ amount: "0.2", type: "Gas Fee" }],
+        outputAmount: "99",
+        quoteToken: "mock-quote-token"
+      }))
+    })) as unknown as typeof BrlaApiService.getInstance;
+
+    const flow = makeBrlOnrampBaseCrossChainFlow(Networks.Ethereum, EvmToken.ETH);
+    const { metadata } = await flow.simulate(buildCtx(true, Networks.Ethereum, EvmToken.ETH));
+    const subsidizePost = getBlockMetadata(metadata, SubsidizePostContext);
+    const oracleExpectedUsd = new Big("100").times("0.18").times(new Big(1).minus("0.0017"));
+
+    expect(subsidizePost.outputCurrency).toBe(EvmToken.USDC);
+    expect(Big(subsidizePost.expectedOutputAmountDecimal).lt(20)).toBe(true);
+    expect(Big(subsidizePost.subsidyAmountInOutputTokenDecimal).lte(oracleExpectedUsd.times("0.003"))).toBe(true);
+    const finalSettlement = getBlockMetadata(metadata, FinalSettlementSubsidyContext);
+    expect(finalSettlement.applied).toBe(false);
+    expect(Big(finalSettlement.expectedOutputAmountDecimal).eq(finalSettlement.actualOutputAmountDecimal)).toBe(true);
+  });
 });
 
 describe("BRL cross-chain onramp flow metadata ownership", () => {

apps/api/src/api/services/phases/blocks/__tests__/brl-onramp-base-same-chain.flow.test.ts

@@ -40,7 +40,8 @@ mock.module("../core/squidrouter", () => ({
   },
   getEvmBridgeQuote: async ({ amountDecimal }: { amountDecimal: string }) => ({
     networkFeeUSD: "0.1",
-    outputAmountDecimal: new Big(amountDecimal)
+    outputAmountDecimal: new Big(amountDecimal),
+    outputAmountUsd: new Big(amountDecimal)
   }),
   getBridgeTargetTokenDetails: (token: EvmToken) => evmTokenConfig[Networks.Base][token]
 }));

apps/api/src/api/services/phases/blocks/__tests__/eur-onramp-base-cross-chain.flow.test.ts

@@ -52,6 +52,11 @@ mock.module("../core/squidrouter", () => ({
     networkFeeUSD: "0.1",
     outputTokenDecimals: 6
   }),
+  getEvmBridgeQuote: async ({ amountDecimal }: { amountDecimal: string }) => ({
+    networkFeeUSD: "0.1",
+    outputAmountDecimal: new Big(amountDecimal),
+    outputAmountUsd: new Big(amountDecimal)
+  }),
   getBridgeTargetTokenDetails: () => ({
     erc20AddressSourceChain: "0xaf88d065e77c8cC2239327C5EDb3A432268e5831"
   })

apps/api/src/api/services/phases/blocks/__tests__/eur-onramp-base-same-chain.flow.test.ts

@@ -49,6 +49,11 @@ mock.module("../core/squidrouter", () => ({
       outputTokenDecimals: token?.decimals ?? 6
     };
   },
+  getEvmBridgeQuote: async ({ amountDecimal }: { amountDecimal: string }) => ({
+    networkFeeUSD: "0.1",
+    outputAmountDecimal: new Big(amountDecimal),
+    outputAmountUsd: new Big(amountDecimal)
+  }),
   getBridgeTargetTokenDetails: (token: EvmToken) => evmTokenConfig[Networks.Base][token]
 }));