Arquitectura de pasarela de pago de moneda estable

Descripción general de la arquitectura:

Una pasarela de pago de moneda estable tiene cinco capas principales: (1) la capa de intención de pago que crea y administra direcciones de depósito por pago, (2) la capa de monitoreo de la cadena que vigila la cadena de bloques en busca de transferencias entrantes, (3) el motor de confirmación que valida los recibos y desencadena eventos, (4) el libro mayor que registra todos los estados de pago y (5) la capa de liquidación que maneja la gestión de tesorería y la rampa de salida.

Esta guía se centra en el diseño del sistema detrás de una puerta de enlace de producción de moneda estable: no solo qué componentes existen, sino también cómo se conectan, dónde ocurren las fallas y qué decisiones de diseño son importantes para la confiabilidad a escala.

Capa de intención de pago

Una intención de pago se crea cuando un pagador inicia un pago. Almacena: la cantidad esperada, la moneda estable y la cadena, la dirección de depósito asignada, el tiempo de vencimiento y la orden descendente o la referencia de la factura.

Derivación de dirección de depósito

Las direcciones de depósito se derivan de una billetera HD que utiliza BIP-44. La semilla maestra se almacena en un administrador de secretos (AWS Secrets Manager, Vault). A cada intención de pago se le asigna un índice de ruta de derivación único. La puerta de enlace almacena: índice de derivación, monto esperado, moneda estable, cadena, vencimiento y estado de pago.

En las cadenas EVM, la misma dirección derivada funciona en todas las cadenas compatibles con EVM. Una única billetera HD puede servir a Base, Ethereum, Polygon y Arbitrum con índices de direcciones separados por intención.

Caducidad y reutilización de direcciones

Las direcciones de depósito no deben reutilizarse entre intentos de pago. Después del vencimiento o del pago exitoso, la dirección se desactiva en la capa de monitoreo. Si llega un pago atrasado a una dirección vencida, la puerta de enlace lo registra como no coincidente para su revisión manual.

Capa de monitoreo de cadena

La capa de monitoreo de la cadena vigila la cadena de bloques en busca de eventos de transferencia ERC-20 (o equivalente) a cualquier dirección de depósito activa. El diseño debe manejar: alto volumen de eventos (en cadenas ocupadas), detección en tiempo real, reorganizaciones de cadenas y monitoreo en múltiples cadenas simultáneamente.

EVM Monitoreo de cadena

Subscribe to ERC-20 Transfer events from the stablecoin contract address using WebSocket RPC (Alchemy, QuickNode). Filter by the to address matching any active deposit address. Use a bloom filter or database index on active addresses for O(1) lookup.

Fallback: poll for recent Transfer events every N seconds using eth_getLogs. WebSocket subscriptions are preferred but can drop connections — the polling fallback ensures no missed events.

Monitoreo Tron TRC-20

TronGrid API proporciona el historial de transacciones de una dirección. Sondee el historial de transferencias de TRC-20 para cada dirección de depósito activa utilizando TronGrid REST API. Las suscripciones a WebSocket son menos confiables en Tron: el sondeo es el enfoque estándar.

Solana SPL Monitoreo de tokens

Solana uses Associated Token Accounts (ATAs) — each wallet address has a corresponding ATA for each SPL token. Monitor the USDC ATA corresponding to each deposit address using WebSocket account subscriptions or polling getSignaturesForAddress.

Motor de confirmación

El motor de confirmación valida las transferencias detectadas y emite eventos de pago. Responsabilidades clave:

Verificación de la profundidad del bloque: Espera hasta que la transacción alcance la profundidad de confirmación requerida antes de emitir un evento confirmado.

Validación de importe: Compara la cantidad recibida con la esperada. Maneja pagos insuficientes (marcar para revisión manual o rechazo según la tolerancia del producto) y pagos excesivos (crédito del monto total, marcar exceso).

Manejo de reorganización de cadena: Si una transacción detectada previamente se elimina en una reorganización de la cadena, revierta el evento de pago_detectado y vuelva a ingresar al estado pendiente. Utilice una profundidad de confirmación breve adecuada al riesgo de reorganización de la cadena.

Idempotencia: Se almacena cada hash de transacción confirmada. La repetición del mismo evento de confirmación no es operativa.

Diseño de libro mayor

El libro de pagos es el registro autorizado de toda la actividad de pagos de monedas estables. Debe ser solo para agregar (sin actualizaciones, solo inserciones) y tener origen en eventos: cada transición de estado (creada, detectada, confirmada, caducada, barrida) es una entrada del libro mayor.

Evento	gatillo	Acción aguas abajo
pago.creado	Intención de pago creada	Dirección de devolución de depósito al pagador
pago.detectado	Transferencia vista en cadena, pendiente	Notificar al pagador; mostrar estado pendiente
pago.confirmado	Confirmaciones requeridas alcanzadas	Activar pedido/suscripción; activar webhook
pago.caducado	Pasó el tiempo de vencimiento, no hay pago	Liberar dirección de depósito; notificar al pagador
pago.mal pagado	Cantidad menor a la esperada	Marcar para revisión; manipulación específica del producto
pago.barrido	Fondos arrastrados a la billetera del tesoro	Actualizar registro de barrido; reducir el saldo de direcciones

Gestión de Barrido y Tesorería

La billetera de tesorería debe ser multifirma (por ejemplo, Safe/Gnosis Safe) para implementaciones de producción; las operaciones críticas de tesorería requieren múltiples firmantes.

Financiación del gas: Cada dirección de depósito necesita un token nativo (ETH, TRX, etc.) para cubrir la tarifa de gas de la transacción de barrido. La puerta de enlace mantiene un servicio de financiación de gas que recarga las direcciones de depósito antes de realizar el barrido.

Gatillo de barrido: Activado por umbral de saldo, cronograma o manualmente. Los barridos por lotes reducen el costo total del gas.

Confirmación de barrido: La transacción de barrido se monitorea hasta su confirmación. Si tiene éxito, se registra el evento del libro mayor de barrido.

Arquitectura de integración fuera de la rampa

La rampa de salida convierte la moneda estable mantenida en la billetera del tesoro en moneda fiduciaria. El patrón de integración:

Cuenta de proveedor de rampa de salida: El proveedor de salida (Bridge, Coinbase Prime, etc.) proporciona una dirección de destino de la moneda estable. El envío de USDC a esta dirección activa una liquidación fiduciaria a la cuenta bancaria configurada.

Instrucción de transferencia: La puerta de enlace construye y firma una transferencia desde la billetera del tesoro a la dirección de salida. Esto requiere acceso a la clave de firma de la billetera de tesorería; generalmente requiere aprobación de firmas múltiples.

Confirmación de liquidación: Los proveedores de salida envían webhooks o proporcionan APIs para confirmar la liquidación fiduciaria. La puerta de enlace registra el evento de liquidación fiduciaria contra la transferencia de salida.

Consideraciones de producción

Decisiones de arquitectura que son importantes para la confiabilidad de la producción:

Ejecute conexiones de nodo RPC redundantes (Alchemy primario + respaldo QuickNode): las fallas únicas RPC no deberían causar pagos atrasados
Cola de eventos (Kafka, SQS o Redis Streams) entre el monitoreo de la cadena y el motor de confirmación: desacopla la ingesta del procesamiento y permite la reproducción
Transacciones de la base de datos en torno a las escrituras del libro mayor: el evento de confirmación y la acción posterior deben confirmarse o revertirse.
Cola de mensajes fallidos para entregas fallidas de webhooks: reintento con retroceso exponencial, alerta sobre fallas repetidas
Monitoreo y alertas sobre: retraso en el monitoreo de la cadena, pagos no igualados, fallas en el barrido, demoras en la liquidación fuera de la rampa
Separe la gestión de claves de firma de la lógica de la aplicación de puerta de enlace: las operaciones de tesorería deberían requerir aprobación de firmas múltiples

Preguntas frecuentes

¿La puerta de enlace debería ser un servicio independiente o estar integrada en la aplicación principal?

Se prefiere encarecidamente un servicio de puerta de enlace independiente para la producción. Aísla la lógica de firma y monitoreo de la cadena de la aplicación principal, se puede implementar y escalar de forma independiente y tiene un límite de seguridad claro. La pasarela publica eventos de pago; la aplicación principal los consume.

¿Cómo manejo a los usuarios que envían una cantidad incorrecta o una moneda estable incorrecta?

Las transferencias incorrectas de monedas estables (por ejemplo, DAI en lugar de USDC) a la dirección de depósito se registran como no coincidentes y se ponen en cola para revisión manual. Los pagos insuficientes se marcan: el producto define si se aceptan pagos parciales, se rechazan o se solicita al pagador que recargue. Los pagos en exceso se pueden acreditar en su totalidad y el exceso se reembolsa en la cadena.

¿Qué sucede si el nodo RPC deja de funcionar?

La capa de monitoreo debe ejecutarse con proveedores RPC redundantes. Si todo falla, la puerta de enlace entra en un estado degradado: las nuevas confirmaciones de pago se retrasan pero no se pierden. Cuando se restablezca la conectividad, reproduzca desde el último bloque confirmado para detectar cualquier evento de transferencia perdido. La cola de eventos entre el monitoreo y el motor de confirmación garantiza que no se eliminen eventos durante interrupciones breves.

¿Cómo escala esta arquitectura a un gran volumen?

Escalado horizontal de trabajadores de monitoreo de cadena (un trabajador por cadena o fragmento de cadena). La cola de eventos absorbe el volumen de ráfagas. El motor de confirmación escala horizontalmente siempre que las escrituras del libro mayor sean idempotentes. Derivación de direcciones y escala de búsqueda con un índice de base de datos adecuado en direcciones activas. El cuello de botella suele ser RPC límites de velocidad: planifique puntos finales RPC dedicados a escala.

Resumen de arquitectura

Cinco capas: intención de pago (gestión de direcciones), monitoreo de cadena, motor de confirmación, libro mayor y liquidación (barrido + rampa de salida).

La derivación de billetera HD proporciona direcciones de depósito únicas y deterministas sin almacenar claves privadas por dirección.

La cola de eventos entre el motor de monitoreo y confirmación es fundamental para la confiabilidad y la reproducción.

El libro mayor debe ser de solo anexos y debe tener origen en eventos: cada transición de estado es un registro, no una actualización.

La integración de rampa de salida y firma múltiple de tesorería son los componentes operativamente sensibles: diseño con controles de firma adecuados.