Pasarela de criptomonedas: arquitectura, integración y pruebas de fiabilidad

Qué hace realmente una pasarela de criptomonedas

Una pasarela de criptomonedas se sitúa entre la transferencia on-chain de un cliente y su contabilidad interna. No mueve monedas por sí misma; observa la cadena, empareja transferencias con pedidos, aplica una política de confirmación y emite un evento de crédito o liquidación a su aplicación. En la analogía del pago con tarjeta, la pasarela se parece más al procesador adquirente junto con el departamento de conciliación que al formulario de pago.

Esa distinción importa para la ingeniería. Una pasarela tiene tres responsabilidades separables: detección (encontrar transacciones candidatas), atribución (decidir a qué pedido pertenece una transacción) y finalidad (decidir cuándo es seguro acreditar el pago). Cada una tiene sus propios modos de fallo, y cada una depende de una fuente de datos —normalmente un nodo o proveedor RPC— cuya consistencia debe verificar en lugar de asumir.

Esta guía cubre diseños de pasarelas autoalojadas y respaldadas por proveedores. No recomienda un proveedor de pagos específico; para la capa de nodo y endpoint subyacente a una pasarela, utilice el Asistente RPC de OnFinality para opciones concretas de proveedores y mantenga esta página como referencia metodológica.

• Detección: sondear o suscribirse a transacciones que toquen sus direcciones de depósito.
• Atribución: asignar importe, dirección, memo o ID de factura a un pedido.
• Finalidad: aplicar la profundidad de confirmación y las reglas de reorganización antes de acreditar.
• Conciliación: comparar el estado on-chain con su libro mayor de forma programada.

Supuestos y requisitos previos

Los procedimientos a continuación asumen que usted controla las direcciones de depósito (o puede derivarlas), que tiene un endpoint RPC para la cadena objetivo y que mantiene un libro mayor interno con claves de idempotencia. También asumen que puede ejecutar un pequeño proceso trabajador con almacenamiento persistente; una pasarela que solo mantiene estado en memoria perderá el rastro de los pagos pendientes al reiniciarse.

Necesita una forma de consultar bloques y transacciones (JSON-RPC eth_getBlockByNumber, eth_getLogs o el equivalente de la cadena), una tabla de base de datos para las transferencias observadas y un programador de tareas para las comprobaciones de confirmación. Si aún está eligiendo la infraestructura, la guía sobre alojamiento de nodos blockchain cubre la base operativa, y fundamentos de endpoints RPC explica los patrones de solicitud de los que depende un vigilante.

El ciclo de vida del pago y la política de confirmación

Un ciclo de vida típico es: el cliente selecciona cripto, su sistema emite una factura con una dirección e importe esperado, el cliente difunde una transferencia, su vigilante la detecta en un bloque, la transferencia acumula confirmaciones y, en un umbral, su libro mayor acredita el pedido. La liquidación a fiat o stablecoins, si la necesita, ocurre después de la acreditación y es una preocupación separada.

La profundidad de confirmación es una decisión de riesgo, no una constante. Debe depender del comportamiento de reorganización de la cadena, el tamaño del pago y su tolerancia a la reversión. Una política práctica es escalonada: los importes pequeños se acreditan con una profundidad superficial, los importes mayores con una profundidad más profunda, y cualquier cosa por encima de un umbral de tesorería espera a una revisión manual. Documente la política y codifíquela en la configuración para que pueda auditarse.

Una tabla de resultados que debería producir para su propia cadena e importes (los valores a continuación son marcadores de posición, no mediciones):

Rellene las celdas 'Por determinar' midiendo la profundidad de reorganización observada en su cadena durante un período de muestra y cronometrando la latencia de confirmación con su proveedor RPC. No copie los números de otra cadena.

Detección de transferencias con un trabajador de sondeo

El sondeo es el método de detección fiable más sencillo y el más fácil de razonar durante incidentes. El trabajador avanza un cursor bloque a bloque, obtiene cada bloque y registra las transferencias a sus direcciones. El ejemplo siguiente utiliza JSON-RPC sobre HTTP; reemplace RPC_URL con su endpoint y mantenga el cursor en almacenamiento duradero.

Ejecútelo primero contra una testnet y verifique que el cursor avanza exactamente una vez por bloque y que los reinicios se reanudan desde el cursor almacenado en lugar de desde la cabeza de la cadena.

import json, time, urllib.request

RPC_URL = "RPC_URL"
DEPOSIT_ADDRESSES = {"0xYourDepositAddress"}
CURSOR_FILE = "cursor.json"

def rpc(method, params):
    body = json.dumps({"jsonrpc":"2.0","id":1,"method":method,"params":params}).encode()
    req = urllib.request.Request(RPC_URL, data=body, headers={"Content-Type":"application/json"})
    with urllib.request.urlopen(req, timeout=15) as r:
        return json.loads(r.read())["result"]

def load_cursor():
    try:
        return json.load(open(CURSOR_FILE))["block"]
    except FileNotFoundError:
        return int(rpc("eth_blockNumber", []), 16) - 1

def save_cursor(n):
    json.dump({"block": n}, open(CURSOR_FILE, "w"))

cursor = load_cursor()
while True:
    head = int(rpc("eth_blockNumber", []), 16)
    while cursor < head:
        cursor += 1
        block = rpc("eth_getBlockByNumber", [hex(cursor), True])
        for tx in block["transactions"]:
            to = (tx.get("to") or "").lower()
            if to in {a.lower() for a in DEPOSIT_ADDRESSES}:
                print("candidate", tx["hash"], tx["value"], cursor)
        save_cursor(cursor)
    time.sleep(5)

Atribución: emparejar transferencias con pedidos

La detección sin atribución produce un flujo de transferencias que no puede acreditar. Las estrategias de atribución se dividen en tres familias: dirección de depósito única por pedido, una dirección compartida más un memo o ID de factura, y emparejamiento por importe y tiempo. Las direcciones únicas son las más robustas porque la dirección en sí es la clave; los memos solo funcionan en cadenas que los transportan de forma fiable; el emparejamiento por importe es frágil bajo carga y debería ser un respaldo, no el método principal.

Cualquiera que elija, almacene la asignación antes de mostrar la dirección al cliente y haga que la acreditación sea idempotente respecto al hash de la transacción. Un webhook duplicado o un bloque reproducido no deben acreditar dos veces.

• Dirección única por factura: atribución más sencilla, más gestión de direcciones.
• Dirección compartida con memo: menos direcciones, depende del soporte de la cartera.
• Importe y ventana temporal: el más débil, úselo solo para flujos de bajo valor.

Confirmaciones, reorganizaciones y acreditación idempotente

Una transferencia vista en el bloque N puede desaparecer si la cadena se reorganiza. Su pasarela debe tratar la detección y la acreditación como estados separados: observed, confirmed, credited y reversed. Cuando una reorganización elimina una transacción previamente observada, muévala a reversed y revierta el asiento del libro mayor solo si ya se había acreditado, y solo mediante un ajuste auditable, nunca una eliminación silenciosa.

La comprobación a continuación consulta el bloque actual y lo compara con el bloque donde se vio la transferencia. Es deliberadamente simple; los sistemas en producción también deberían verificar que la transacción sigue incluida en la cadena canónica volviendo a obtener el recibo.

async function confirmationStatus(rpcUrl, txHash, seenAtBlock, required) {
  const call = async (method, params) => {
    const res = await fetch(rpcUrl, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ jsonrpc: "2.0", id: 1, method, params })
    });
    return (await res.json()).result;
  };
  const receipt = await call("eth_getTransactionReceipt", [txHash]);
  if (!receipt) return { state: "reversed" };
  const head = parseInt(await call("eth_blockNumber", []), 16);
  const depth = head - parseInt(receipt.blockNumber, 16);
  return { state: depth >= required ? "confirmed" : "observed", depth };
}

Medición de la fiabilidad de RPC antes de confiar en una pasarela

Cada pasarela es tan consistente como el endpoint que la alimenta. Antes de enrutar pagos reales, ejecute una pasada de medición contra su endpoint RPC candidato y registre los resultados en una tabla propia. El procedimiento: envíe una secuencia fija de llamadas eth_blockNumber y eth_getBlockByNumber a un ritmo constante durante una ventana definida, registre la latencia y los códigos de error, y repita contra un segundo endpoint para comparar.

Registre como mínimo: número de solicitudes, tasa de éxito, latencia p50 y p95, respuestas de límite de velocidad y cualquier desacuerdo de altura de bloque entre endpoints. Una pasarela que ve alturas de bloque obsoletas detectará pagos de menos; una que ve alturas inconsistentes entre proveedores producirá falsas alarmas de reorganización. Si necesita un endpoint gestionado, las páginas del servicio de API RPC y precios de RPC describen las opciones comerciales, y los nodos dedicados son la elección correcta cuando necesita un rendimiento predecible para un vigilante de alto volumen.

No publique ni confíe en números que no haya medido. La tabla siguiente es la forma del resultado, no un resultado:

Conciliación y salida de verificación esperada

La conciliación compara su libro mayor con el estado on-chain de forma programada. Para cada pedido acreditado, vuelva a obtener el recibo de la transacción y confirme que el destinatario, el importe y la profundidad de confirmación siguen coincidiendo. La salida esperada de una ejecución saludable es un informe con cero diferencias inexplicables: cada pedido acreditado se asigna a una transacción canónica, cada transferencia observada pero no acreditada tiene una razón, y cada reversión tiene un ajuste contable correspondiente.

Una consulta de conciliación mínima devuelve el conjunto de pedidos acreditados cuya transacción ya no es canónica. Si ese conjunto no está vacío, su pasarela tiene un error de corrección o una laguna en la política de reorganización; investíguelo antes del siguiente ciclo de liquidación.

SELECT o.id, o.tx_hash, o.credited_at
FROM orders o
LEFT JOIN canonical_txs c ON c.tx_hash = o.tx_hash
WHERE o.status = 'credited' AND c.tx_hash IS NULL;

Solución de problemas comunes de pasarelas

La mayoría de los incidentes de pasarela se ajustan a un pequeño conjunto de patrones. Los pagos faltantes suelen significar que el cursor del vigilante se atascó, que la dirección de depósito se escribió mal o que el endpoint RPC devolvió bloques obsoletos. Los créditos duplicados suelen significar que la clave de idempotencia no se aplicó a nivel de base de datos. Las falsas alarmas de reorganización suelen significar que dos endpoints discrepan en la altura de bloque y la pasarela confió en el equivocado.

Al depurar, congele primero la acreditación y luego inspeccione el cursor, la tabla de transferencias observadas y la altura de bloque reportada por el endpoint. Compare con un segundo endpoint independiente antes de concluir que se produjo una reorganización. Para diagnósticos de endpoint más profundos, consulte la guía de RPC multicadena y el directorio de redes para el comportamiento específico de cada cadena.

• Cursor atascado: revise los registros del trabajador y el valor del cursor almacenado.
• Bloques obsoletos: compare la altura de la cabeza entre dos endpoints.
• Crédito duplicado: verifique la restricción única en el hash de la transacción.
• Alarma de reorganización: confirme que la transacción está ausente de la cadena canónica.

Limitaciones y compensaciones

Las pasarelas autoalojadas le dan control sobre la política de confirmación y la residencia de datos, pero requieren que usted opere nodos, maneje actualizaciones de cadena y construya la conciliación usted mismo. Las pasarelas respaldadas por proveedores reducen la carga operativa pero trasladan la política de finalidad y el manejo de comisiones a un tercero, lo que puede entrar en conflicto con sus requisitos de cumplimiento o tesorería.

El sondeo es simple pero añade latencia igual a su intervalo de sondeo; las suscripciones reducen la latencia pero añaden complejidad de reconexión. Las direcciones de depósito únicas mejoran la atribución pero aumentan la derivación de direcciones y la sobrecarga de monitoreo. No hay una configuración universalmente correcta; la elección correcta depende del tamaño de los pagos, el comportamiento de la cadena y cuánto riesgo operativo puede absorber.

Próximos pasos para una pasarela en producción

Comience por escribir su política de confirmación por cadena y por nivel de pago, luego implemente la detección, la atribución y la acreditación como servicios separados con límites idempotentes. Ejecute la medición de fiabilidad contra al menos dos endpoints, registre los resultados en su propia tabla y establezca umbrales de alerta sobre la tasa de éxito y el desacuerdo de altura de bloque.

Una vez que la canalización sea estable en una testnet, ensaye deliberadamente una reorganización y una caída del proveedor. Si necesita ayuda para seleccionar la capa de endpoint, el Asistente RPC puede recomendar proveedores concretos, mientras que la guía de endpoints RPC y la guía de alojamiento de nodos cubren los detalles operativos.