Create new production release

.clinerules/01-general-rules.md

@@ -7,7 +7,7 @@
 
 ## Architecture Decision Records
 
-Create ADRs in /docs/adr for:
+Create ADRs in /docs/adr for:  
 
 - Major dependency changes
 - Architectural pattern changes

apps/api/.env.example

@@ -33,6 +33,10 @@ DB_SSL_CA_CERT_PATH=
 # Blockchain
 AMPLITUDE_WSS=wss://rpc-amplitude.pendulumchain.tech
 PENDULUM_WSS=wss://rpc-pendulum.prd.pendulumchain.tech
+# Optional Substrate RPC overrides. Comma-separate multiple URLs for failover.
+ASSETHUB_WSS=wss://dot-rpc.stakeworld.io/assethub
+HYDRATION_WSS=wss://rpc.hydradx.cloud
+MOONBEAM_WSS=wss://wss.api.moonbeam.network,wss://moonbeam.api.onfinality.io/public-ws,wss://moonbeam.ibp.network
 FUNDING_SECRET=your-funding-secret
 PENDULUM_FUNDING_SEED=your-pendulum-funding-seed
 MOONBEAM_EXECUTOR_PRIVATE_KEY=your-moonbeam-executor-private-key

apps/api/package.json

@@ -88,7 +88,7 @@
   "name": "vortex-backend",
   "scripts": {
     "build": "bun run swc src -d dist --strip-leading-paths",
-    "dev": "concurrently -n 'shared,backend' -c '#ffa500,007755' 'cd ../../packages/shared && bun run dev' 'NODE_ENV=development bun --watch src/index.ts'",
+    "dev": "NODE_ENV=development bun --watch src/index.ts",
     "migrate": "bun -r @swc-node/register src/database/migrator.ts",
     "migrate:revert": "bun -r @swc-node/register src/database/migrator.ts revert-all",
     "migrate:revert-last": "bun -r @swc-node/register src/database/migrator.ts revert",

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

@@ -150,8 +150,20 @@ export class AlfredpayController {
 
       const alfredpayService = AlfredpayApiService.getInstance();
 
-      const newCustomer = await alfredpayService.createCustomer(userEmail, AlfredpayCustomerType.INDIVIDUAL, country);
-      const customerId = newCustomer.customerId;
+      let customerId: string;
+      try {
+        const newCustomer = await alfredpayService.createCustomer(userEmail, AlfredpayCustomerType.INDIVIDUAL, country);
+        customerId = newCustomer.customerId;
+      } catch (error) {
+        const errorMessage = (error as Error)?.message || "";
+        if (errorMessage.includes("409") || errorMessage.includes("already registered")) {
+          logger.info("Customer already exists in Alfredpay, fetching existing customer");
+          const existingCustomer = await alfredpayService.findCustomer(userEmail, country);
+          customerId = existingCustomer.customerId;
+        } else {
+          throw error;
+        }
+      }
 
       await AlfredPayCustomer.create({
         alfredPayId: customerId,
@@ -360,7 +372,7 @@ export class AlfredpayController {
         const linkResponse = await alfredpayService.getKybRedirectLink(alfredPayCustomer.alfredPayId);
         await alfredPayCustomer.update({ status: AlfredPayStatus.Consulted });
         return res.json(linkResponse as AlfredpayGetKybRedirectLinkResponse);
-      } else if (country === "MX" || country === "CO") {
+      } else if (country === "MX" || country === "CO" || country === "AR") {
         // MX/CO use API-based (form) KYC — no redirect link needed.
         // Just reset status so the user can re-fill the form.
         await alfredPayCustomer.update({ status: AlfredPayStatus.Consulted });
@@ -399,8 +411,20 @@ export class AlfredpayController {
 
       const alfredpayService = AlfredpayApiService.getInstance();
 
-      const newCustomer = await alfredpayService.createCustomer(userEmail, type, country);
-      const customerId = newCustomer.customerId;
+      let customerId: string;
+      try {
+        const newCustomer = await alfredpayService.createCustomer(userEmail, type, country);
+        customerId = newCustomer.customerId;
+      } catch (error) {
+        const errorMessage = (error as Error)?.message || "";
+        if (errorMessage.includes("409") || errorMessage.includes("already registered")) {
+          logger.info("Business customer already exists in Alfredpay, fetching existing customer");
+          const existingCustomer = await alfredpayService.findCustomer(userEmail, country);
+          customerId = existingCustomer.customerId;
+        } else {
+          throw error;
+        }
+      }
 
       await AlfredPayCustomer.create({
         alfredPayId: customerId,
@@ -463,7 +487,7 @@ export class AlfredpayController {
 
   static async submitKycInformation(req: Request, res: Response) {
     try {
-      const { country, ...kycData } = req.body as SubmitKycInformationRequest & { country: string };
+      const { country, ...kycData } = req.body as SubmitKycInformationRequest;
       const userId = req.userId!;
 
       const alfredPayCustomer = await AlfredPayCustomer.findOne({
@@ -475,7 +499,21 @@ export class AlfredpayController {
       }
 
       const alfredpayService = AlfredpayApiService.getInstance();
-      const result = await alfredpayService.submitKycInformation(alfredPayCustomer.alfredPayId, { ...kycData, country });
+      let result: Awaited<ReturnType<typeof alfredpayService.submitKycInformation>>;
+      try {
+        result = await alfredpayService.submitKycInformation(alfredPayCustomer.alfredPayId, { ...kycData, country });
+      } catch (error) {
+        const errorMessage = (error as Error)?.message || "";
+        if (errorMessage.includes("422") && errorMessage.includes("KYC record cannot be retried")) {
+          logger.info("KYC record cannot be retried, fetching existing submission");
+          const existingSubmission = await alfredpayService.getLastKycSubmission(alfredPayCustomer.alfredPayId);
+          result = { submissionId: existingSubmission.submissionId } as Awaited<
+            ReturnType<typeof alfredpayService.submitKycInformation>
+          >;
+        } else {
+          throw error;
+        }
+      }
 
       res.json(result);
     } catch (error) {
@@ -557,7 +595,21 @@ export class AlfredpayController {
       }
 
       const alfredpayService = AlfredpayApiService.getInstance();
-      const result = await alfredpayService.submitKybInformation(alfredPayCustomer.alfredPayId, { ...kybData, country });
+      let result: Awaited<ReturnType<typeof alfredpayService.submitKybInformation>>;
+      try {
+        result = await alfredpayService.submitKybInformation(alfredPayCustomer.alfredPayId, { ...kybData, country });
+      } catch (error) {
+        const errorMessage = (error as Error)?.message || "";
+        if (errorMessage.includes("422") && errorMessage.includes("KYC record cannot be retried")) {
+          logger.info("KYB record cannot be retried, fetching existing submission");
+          const existingSubmission = await alfredpayService.getLastKybSubmission(alfredPayCustomer.alfredPayId);
+          result = { submissionId: existingSubmission.submissionId } as Awaited<
+            ReturnType<typeof alfredpayService.submitKybInformation>
+          >;
+        } else {
+          throw error;
+        }
+      }
 
       res.json(result);
     } catch (error) {
@@ -749,6 +801,11 @@ export class AlfredpayController {
           accountType: accountType ?? "",
           metadata: { accountHolderName: accountName, documentNumber, documentType }
         };
+      } else if (alfredpayFiatAccountType === AlfredpayFiatAccountType.COELSA) {
+        fiatAccountFields = {
+          accountNumber,
+          accountType: accountType ?? ""
+        };
       } else {
         // BANK_USA — external accounts need address fields inside metadata
         fiatAccountFields = isExternal

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

@@ -11,7 +11,11 @@ import { NextFunction, Request, Response } from "express";
 import httpStatus from "http-status";
 import logger from "../../config/logger";
 import { APIError } from "../errors/api-error";
-import { observeApiClientEvent } from "../observability/apiClientEvent.service";
+import {
+  buildApiClientRequestMetadata,
+  getSafeApiKeyPrefix,
+  observeApiClientEvent
+} from "../observability/apiClientEvent.service";
 import { classifyApiClientError, getErrorMessage } from "../observability/errorClassifier";
 import { getRequestDurationMs } from "../observability/requestContext";
 import quoteService from "../services/quote";
@@ -57,7 +61,7 @@ export const createQuote = async (
     });
 
     observeApiClientEvent({
-      apiKeyPrefix: getSafePublicKeyPrefix(publicApiKey),
+      apiKeyPrefix: getSafeApiKeyPrefix(publicApiKey, ["pk_"]),
       durationMs: getRequestDurationMs(req),
       httpStatus: httpStatus.CREATED,
       network,
@@ -76,7 +80,7 @@ export const createQuote = async (
   } catch (error) {
     logger.error("Error creating quote", { errorType: classifyApiClientError(error), requestId: req.requestId });
     observeQuoteFailure(req, "quote_create", error, {
-      apiKeyPrefix: getSafePublicKeyPrefix(req.body?.apiKey || req.validatedPublicKey?.apiKey),
+      apiKeyPrefix: getSafeApiKeyPrefix(req.body?.apiKey || req.validatedPublicKey?.apiKey, ["pk_"]),
       network: getNetworkFromDestination(req.body?.rampType === RampDirection.BUY ? req.body?.to : req.body?.from),
       partnerId: req.authenticatedPartner?.id || req.body?.partnerId || null,
       partnerName: req.authenticatedPartner?.name || req.validatedPublicKey?.partnerName || null,
@@ -121,7 +125,7 @@ export const createBestQuote = async (
     });
 
     observeApiClientEvent({
-      apiKeyPrefix: getSafePublicKeyPrefix(publicApiKey),
+      apiKeyPrefix: getSafeApiKeyPrefix(publicApiKey, ["pk_"]),
       durationMs: getRequestDurationMs(req),
       httpStatus: httpStatus.CREATED,
       network: quote.network,
@@ -140,7 +144,7 @@ export const createBestQuote = async (
   } catch (error) {
     logger.error("Error creating best quote", { errorType: classifyApiClientError(error), requestId: req.requestId });
     observeQuoteFailure(req, "quote_create_best", error, {
-      apiKeyPrefix: getSafePublicKeyPrefix(req.body?.apiKey || req.validatedPublicKey?.apiKey),
+      apiKeyPrefix: getSafeApiKeyPrefix(req.body?.apiKey || req.validatedPublicKey?.apiKey, ["pk_"]),
       partnerId: req.authenticatedPartner?.id || req.body?.partnerId || null,
       partnerName: req.authenticatedPartner?.name || req.validatedPublicKey?.partnerName || null,
       rampType: req.body?.rampType
@@ -194,6 +198,11 @@ export const getQuote = async (
 type QuoteOperation = "quote_create" | "quote_create_best" | "quote_get";
 
 interface ObservedQuoteRequest {
+  body?: unknown;
+  method?: string;
+  params?: unknown;
+  path?: string;
+  query?: unknown;
   requestId?: string;
   requestStartedAt?: number;
   userId?: string;
@@ -220,18 +229,34 @@ function observeQuoteFailure(
     errorMessage: getErrorMessage(error),
     errorType: classifyApiClientError(error, status),
     httpStatus: status,
+    metadata: buildQuoteRequestMetadata(req, operation),
     operation,
     requestId: req.requestId,
     status: "failure",
     userId: req.userId || null
   });
 }
 
-function getHttpStatus(error: unknown): number {
-  return error instanceof APIError ? error.status || httpStatus.INTERNAL_SERVER_ERROR : httpStatus.INTERNAL_SERVER_ERROR;
+function buildQuoteRequestMetadata(req: ObservedQuoteRequest, operation: QuoteOperation): Record<string, unknown> {
+  if (operation === "quote_get") {
+    return buildApiClientRequestMetadata(req, { paramKeys: ["id"] });
+  }
+
+  return buildApiClientRequestMetadata(req, {
+    bodyKeys: [
+      "countryCode",
+      "from",
+      "inputAmount",
+      "inputCurrency",
+      "networks",
+      "outputCurrency",
+      "partnerId",
+      "rampType",
+      "to"
+    ]
+  });
 }
 
-function getSafePublicKeyPrefix(apiKey: string | null | undefined): string | null {
-  if (!apiKey?.startsWith("pk_")) return null;
-  return apiKey.slice(0, 8);
+function getHttpStatus(error: unknown): number {
+  return error instanceof APIError ? error.status || httpStatus.INTERNAL_SERVER_ERROR : httpStatus.INTERNAL_SERVER_ERROR;
 }

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

@@ -17,7 +17,7 @@ import logger from "../../config/logger";
 import { APIError } from "../errors/api-error";
 import { enrichAdditionalDataWithClientIp } from "../helpers/clientIp";
 import { assertQuoteOwnership, assertRampOwnership } from "../middlewares/ownershipAuth";
-import { observeApiClientEvent } from "../observability/apiClientEvent.service";
+import { buildApiClientRequestMetadata, observeApiClientEvent } from "../observability/apiClientEvent.service";
 import { classifyApiClientError, getErrorMessage } from "../observability/errorClassifier";
 import { getRequestDurationMs } from "../observability/requestContext";
 import { ApiClientOperation } from "../observability/types";
@@ -288,6 +288,11 @@ interface RampObservationContext {
 
 interface ObservedRampRequest {
   authenticatedPartner?: { id: string; name: string };
+  body?: unknown;
+  method?: string;
+  params?: unknown;
+  path?: string;
+  query?: unknown;
   requestId?: string;
   requestStartedAt?: number;
   userId?: string;
@@ -325,6 +330,7 @@ function observeRampFailure(
     errorMessage: getErrorMessage(error),
     errorType: classifyApiClientError(error, status),
     httpStatus: status,
+    metadata: buildRampRequestMetadata(req, operation),
     operation,
     partnerId: req.authenticatedPartner?.id || null,
     partnerName: req.authenticatedPartner?.name || null,
@@ -334,6 +340,26 @@ function observeRampFailure(
   });
 }
 
+function buildRampRequestMetadata(req: ObservedRampRequest, operation: RampObservedOperation): Record<string, unknown> {
+  if (operation === "ramp_register") {
+    return buildApiClientRequestMetadata(req, { bodyKeys: ["quoteId", "signingAccounts", "additionalData"] });
+  }
+
+  if (operation === "ramp_update") {
+    return buildApiClientRequestMetadata(req, { bodyKeys: ["rampId", "presignedTxs", "additionalData"] });
+  }
+
+  if (operation === "ramp_start") {
+    return buildApiClientRequestMetadata(req, { bodyKeys: ["rampId"] });
+  }
+
+  if (operation === "ramp_status") {
+    return buildApiClientRequestMetadata(req, { paramKeys: ["id"], queryKeys: ["showUnsignedTxs"] });
+  }
+
+  return buildApiClientRequestMetadata(req, { paramKeys: ["id"] });
+}
+
 function getHttpStatus(error: unknown): number {
   return error instanceof APIError ? error.status || httpStatus.INTERNAL_SERVER_ERROR : httpStatus.INTERNAL_SERVER_ERROR;
 }

apps/api/src/api/errors/api-error.ts

@@ -7,6 +7,7 @@ interface APIErrorParams {
   stack?: string;
   status?: number;
   isPublic?: boolean;
+  type?: string;
 }
 
 /**
@@ -20,13 +21,14 @@ export class APIError extends ExtendableError {
    * @param {number} status - HTTP status code of error.
    * @param {boolean} isPublic - Whether the message should be visible to user or not.
    */
-  constructor({ message, errors, stack, status = httpStatus.INTERNAL_SERVER_ERROR, isPublic = false }: APIErrorParams) {
+  constructor({ message, errors, stack, status = httpStatus.INTERNAL_SERVER_ERROR, isPublic = false, type }: APIErrorParams) {
     super({
       errors,
       isPublic,
       message,
       stack,
-      status
+      status,
+      type
     });
   }
 }

apps/api/src/api/errors/extendable-error.ts

@@ -4,6 +4,7 @@ interface ExtendableErrorParams {
   status?: number;
   isPublic?: boolean;
   stack?: string;
+  type?: string;
 }
 
 /**
@@ -19,7 +20,9 @@ class ExtendableError extends Error {
 
   readonly isOperational: boolean;
 
-  constructor({ message, errors, status, isPublic = false, stack }: ExtendableErrorParams) {
+  readonly type?: string;
+
+  constructor({ message, errors, status, isPublic = false, stack, type }: ExtendableErrorParams) {
     super(message);
     this.name = this.constructor.name;
     this.message = message;
@@ -28,6 +31,7 @@ class ExtendableError extends Error {
     this.isPublic = isPublic;
     this.isOperational = true;
     this.stack = stack;
+    this.type = type;
     // Error.captureStackTrace(this, this.constructor.name);
   }
 }