Arquitectura de una pasarela cripto: aceptar pagos on-chain de forma fiable

Alcance y respuesta directa

Una pasarela cripto es un procesador de pagos para valor on-chain: genera una dirección de depósito o una factura, monitoriza la cadena en busca de una transferencia coincidente, aplica una política de confirmación y notifica al comercio un pago liquidado. Algunas pasarelas también convierten a stablecoins o fiat y gestionan pagos salientes, pero el núcleo irreducible es la detección, más la política de finalidad, más la conciliación.

Este artículo cubre el lado de la ingeniería: cómo funciona la detección, cómo integrarla sin acreditar dos veces y cómo verificar que tu pasarela ve realmente lo que ve la cadena. La selección de proveedor y la elección de endpoint quedan deliberadamente fuera de alcance; para recomendaciones concretas de endpoints usa RPC Assistant, y para contexto a nivel de red consulta la guía de endpoints RPC multicadena.

• En alcance: derivación de direcciones, detección de eventos, profundidad de confirmación, manejo de reorganizaciones, idempotencia, conciliación.
• Fuera de alcance: licencias, adquirencia de tarjetas, tratamiento fiscal y precios de proveedores.
• Suposición: controlas un sistema de pedidos y puedes llamar a un endpoint RPC o a una API de pasarela.

Requisitos previos y supuestos

Los procedimientos siguientes asumen que tienes un endpoint RPC para la cadena objetivo, una base de datos con una restricción única sobre identificadores de transacción y un ejecutor de tareas que puede hacer polling o suscribirse. También asumen que tratas la pasarela como entrada no confiable: cada pago acreditado debe poder verificarse de forma independiente contra los datos de la cadena.

Si ejecutas tu propia infraestructura, un nodo dedicado elimina los efectos de vecinos ruidosos en las consultas de logs; consulta opciones de nodo dedicado. Si dependes de un endpoint alojado, confirma sus límites de tasa y profundidad de archivo antes de diseñar un backfill, y revisa precios de RPC para que la frecuencia de polling no se convierta en un coste sorpresa.

Modelo mental: factura, vigilante, libro mayor

Separa la pasarela en tres componentes. El servicio de facturación crea una intención de pago con un importe, un activo, una caducidad y una dirección de depósito. El vigilante lee bloques y extrae transferencias que tocan cualquier dirección de tu conjunto activo. El libro mayor registra una máquina de estados por pago: creado, visto, confirmado, acreditado o expirado.

El vigilante nunca debe escribir directamente en el estado acreditado del libro mayor. Emite observaciones; un paso de política separado decide si una observación satisface la regla de confirmación. Esta separación te permite cambiar la profundidad de confirmación por activo sin reescribir la detección, y hace que reproducir el historial sea seguro.

La estrategia de direcciones importa. Una dirección única por factura hace que el emparejamiento sea trivial pero multiplica la gestión de claves. Una dirección compartida requiere emparejar por importe y memo, lo cual es frágil cuando dos clientes pagan el mismo importe. La mayoría de las pasarelas en producción usan direcciones únicas derivadas de HD y almacenan el índice de derivación junto a la factura.

• Servicio de facturación: intención, importe, activo, caducidad, dirección.
• Vigilante: escaneo de bloques o suscripción a logs, filtrado por direcciones activas.
• Política: profundidad de confirmación, tolerancia de valor, respuesta a reorganizaciones.
• Libro mayor: transiciones de estado idempotentes con clave (hash de transacción, índice de log).

Mecánica de detección: bloques, logs y transferencias nativas

Las transferencias de tokens en cadenas EVM suelen aparecer como logs de eventos, por lo que un vigilante puede filtrar por el contrato del token y el topic de transferencia en lugar de escanear cada transacción. Las transferencias nativas no emiten logs, así que requieren inspección a nivel de bloque o un método del proveedor que devuelva cambios de saldo. En cadenas basadas en cuentas sin logs, generalmente comparas saldos o usas el índice de transacciones del nodo.

El polling es más sencillo de operar que las suscripciones y más fácil de hacer reanudable: almacena el último número de bloque completamente procesado y continúa desde ahí. Las suscripciones reducen la latencia pero deben tratarse como pistas, porque una conexión caída pierde eventos silenciosamente. Un diseño robusto usa suscripciones para la velocidad y un barrido periódico de rangos de bloques para la completitud.

curl -s RPC_URL \
  -H 'content-type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "eth_getLogs",
    "params": [{
      "fromBlock": "0x0",
      "toBlock": "latest",
      "address": "TOKEN_CONTRACT_ADDRESS",
      "topics": [
        "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
        null,
        "0x000000000000000000000000YOUR_DEPOSIT_ADDRESS"
      ]
    }]
  }'

Verificación ejecutable de un único pago

Antes de confiar en cualquier webhook de pasarela, verifica tú mismo la transacción subyacente. El script siguiente obtiene una transacción y su recibo, comprueba el destinatario y el valor, e imprime un veredicto. Sustituye los marcadores de posición; nunca confirmes claves reales.

Ejecútalo contra la misma cadena que la pasarela afirma usar. Una discrepancia entre la red reportada por la pasarela y la cadena que devuelve tu RPC es una de las causas más comunes de acreditaciones fantasma.

import json, urllib.request

RPC_URL = "RPC_URL"
TX_HASH = "0xTRANSACTION_HASH"
EXPECTED_TO = "0xDEPOSIT_ADDRESS".lower()
EXPECTED_WEI = 10**16  # 0.01 native unit

def rpc(method, params):
    req = urllib.request.Request(
        RPC_URL,
        data=json.dumps({"jsonrpc":"2.0","id":1,"method":method,"params":params}).encode(),
        headers={"content-type":"application/json"},
    )
    with urllib.request.urlopen(req, timeout=15) as r:
        body = json.load(r)
    if "error" in body:
        raise RuntimeError(body["error"])
    return body["result"]

tx = rpc("eth_getTransactionByHash", [TX_HASH])
receipt = rpc("eth_getTransactionReceipt", [TX_HASH])

if tx is None or receipt is None:
    print("NOT_FOUND: gateway may be reporting a different chain")
else:
    ok_to = (tx.get("to") or "").lower() == EXPECTED_TO
    ok_value = int(tx["value"], 16) >= EXPECTED_WEI
    ok_status = int(receipt["status"], 16) == 1
    print({"to_ok": ok_to, "value_ok": ok_value, "success": ok_status,
           "block": int(receipt["blockNumber"], 16)})

Política de confirmación y manejo de reorganizaciones

Un recuento de confirmaciones es un dial de riesgo, no una garantía. La profundidad correcta depende del comportamiento de reorganización observado en la cadena, el valor en juego y tu tolerancia a retrasar el cumplimiento. Las reglas de finalidad documentadas varían según la red: algunas cadenas exponen una etiqueta de bloque finalizado explícita, otras dependen de una profundidad probabilística. Usa la etiqueta explícita donde exista y una profundidad medida donde no.

Cuando una reorganización invalida una transferencia vista previamente, tu libro mayor debe poder mover un pago hacia atrás de confirmado a visto. Eso significa que la acreditación debe ser reversible hasta un umbral de finalidad, o que el cumplimiento debe retrasarse hasta cruzar el umbral. Nunca elimines la observación; añade una corrección para que las auditorías puedan reconstruir lo ocurrido.

• Almacena el hash de bloque con cada observación para poder detectar cambios de padre.
• Ante una discrepancia de hash en la misma altura, retrocede al último ancestro común y reescanea.
• Mantén una tabla de confirmaciones por activo en configuración, no en el código.
• Registra la versión de la política que produjo cada decisión de acreditación.

Idempotencia y conciliación

Las pasarelas reintentan webhooks, y las cadenas ocasionalmente muestran la misma transferencia tanto por una suscripción como por un barrido. La única defensa duradera es una restricción única sobre (chain_id, tx_hash, log_index) en la tabla de observaciones, más una máquina de estados que rechace transiciones ilegales. Un manejador de webhooks debe buscar la observación, no crear una nueva acreditación.

La conciliación es una tarea programada que compara tu libro mayor con el estado de la cadena para cada pago en un estado no terminal más antiguo que un umbral. La salida es una tabla que revisas, no una mutación automática. Un informe de conciliación útil tiene una fila por pago con columnas para el estado de la pasarela, el estado de la cadena, la profundidad de confirmación y la diferencia entre el valor esperado y el observado.

CREATE TABLE observations (
  chain_id      INTEGER NOT NULL,
  tx_hash       TEXT    NOT NULL,
  log_index     INTEGER NOT NULL,
  invoice_id    TEXT    NOT NULL,
  block_number  BIGINT  NOT NULL,
  block_hash    TEXT    NOT NULL,
  value_wei     NUMERIC NOT NULL,
  seen_at       TIMESTAMPTZ NOT NULL DEFAULT now(),
  PRIMARY KEY (chain_id, tx_hash, log_index)
);

INSERT INTO observations (chain_id, tx_hash, log_index, invoice_id, block_number, block_hash, value_wei)
VALUES ($1, $2, $3, $4, $5, $6, $7)
ON CONFLICT (chain_id, tx_hash, log_index) DO NOTHING;

Procedimiento de tabla de resultados para tus propias mediciones

No adoptes profundidades de confirmación de publicaciones de blog, incluida esta. Mídelas. Ejecuta el siguiente procedimiento para cada activo que aceptes y registra los resultados en una tabla con estas columnas: activo, cadena, ventana de observación, reorganizaciones observadas a profundidad N, reorganizaciones observadas a profundidad N+1, tiempo mediano hasta profundidad N y tiempo p95 hasta profundidad N.

Procedimiento: (1) ejecuta un vigilante que almacene el hash de bloque por altura durante al menos 30 días; (2) cada noche, compara los hashes almacenados con la cadena canónica y cuenta las discrepancias por profundidad; (3) calcula el tiempo hasta la profundidad a partir de las marcas de tiempo de los bloques; (4) elige la profundidad más pequeña donde las reorganizaciones observadas sean cero en toda la ventana, luego añade un margen para el nivel de valor. Publica la tabla internamente y revísala trimestralmente. Los números son tuyos; el método es el entregable.

Solución de problemas comunes de pasarelas

La mayoría de los incidentes caen en un conjunto pequeño de patrones. Recórrelos en orden, porque una discrepancia de cadena invalida todas las comprobaciones posteriores.

Si la pasarela reporta un pago que tu RPC no encuentra, confirma primero el chain ID, luego el formato del hash de transacción. Si el pago existe pero el destinatario difiere, comprueba si la pasarela usó un contrato de reenvío. Si el importe es corto, verifica si el remitente pagó las comisiones de red con cargo al importe transferido en una cadena donde eso es posible. Si un pago se acredita dos veces, inspecciona el manejador de webhooks en busca de una restricción única faltante en lugar de culpar a la pasarela.

• Discrepancia de cadena: compara eth_chainId en ambos lados.
• Logs faltantes: confirma la dirección del contrato del token y el hash del topic.
• Vigilante desactualizado: compara el último bloque procesado almacenado con la cabeza de la cadena.
• Límite de tasa: agrupa las consultas de logs por rango de bloques y retrocede ante respuestas 429.
• Desfase de reloj: compara las marcas de tiempo de la pasarela con las de los bloques antes de asumir latencia.

Limitaciones y compensaciones

Las direcciones únicas mejoran el emparejamiento pero aumentan la superficie de gestión de claves y el coste de despliegue on-chain si usas contratos de reenvío. Las direcciones compartidas reducen el coste pero trasladan la complejidad al emparejamiento por importe y memos. El polling es más simple y reanudable pero añade latencia; las suscripciones son más rápidas pero requieren un barrido de completitud.

También hay una advertencia de medición: la latencia de tu vigilante está limitada por el retraso de cabeza de tu proveedor RPC, que no controlas y que varía según la carga de la red. Trata la latencia observada como una propiedad de todo el camino, no solo de la pasarela. Para características de fiabilidad a nivel de endpoint, consulta RPC Assistant en lugar de asumir un comportamiento uniforme entre proveedores.

Próximos pasos

Empieza instrumentando antes de optimizar: registra cada observación con el hash de bloque y la versión de la política, luego ejecuta la tarea de conciliación durante dos semanas y revisa el informe. Una vez que la línea base sea estable, ajusta la profundidad de confirmación por activo usando tu propia tabla, y solo entonces considera mejoras de latencia como las suscripciones.

Para el lado de la infraestructura, revisa cómo funciona el alojamiento de nodos blockchain y la guía de endpoints RPC para alinear tu vigilante con una fuente de datos fiable. Si estás eligiendo entre infraestructura alojada y autooperada, la descripción general del servicio API y la lista de redes describen lo disponible por cadena. Para la pregunta concreta de qué endpoint usar para una red dada, pregunta a RPC Assistant; esa decisión es específica del proveedor y queda fuera del alcance de esta metodología.