Crea tu propio cliente

En esta guía, se proporcionan recomendaciones para garantizar que las implementaciones del cliente de Universal Ledger interactúen con una red de forma segura y confiable. Aprenderás a realizar estas tareas:

  • Aprovechar la topología de red para lograr una alta disponibilidad
  • Enviar transacciones y comprender los resultados de la ejecución
  • Implementar estrategias de sondeo, tiempos de espera y reintento

Topología de red y alta disponibilidad

Una red de Universal Ledger consta de varios validadores distribuidos en varias zonas y regiones, lo que garantiza una alta disponibilidad para la red en su conjunto.

  • Fallas zonales: Si falla un solo validador dentro de una zona de Cloud, otros validadores de la misma región seguirán procesando solicitudes sin problemas.

  • Interrupciones regionales: Si una región completa deja de estar disponible, los validadores de otras regiones seguirán funcionando. Para seguir enviando transacciones, es seguro que tu cliente recurra a un extremo diferente y vuelva a intentar enviar las transacciones a través de él.

Características de la ejecución de transacciones

  • Ejecución atómica: Las transacciones se completan por completo o fallan por completo. Nunca se produce una ejecución parcial de la transacción, como transferir solo una parte de los fondos solicitados debido a un saldo insuficiente. Esto incluye cadenas de transacciones, lo que te permite combinar varias transacciones arbitrarias en una sola secuencia atómica.

  • Sin reintentos automáticos: La red intenta ejecutar una transacción enviada exactamente una vez. Si falla la ejecución, el libro de contabilidad no pone en cola ni vuelve a intentar la transacción automáticamente.

  • Reenvío idempotente: Cada transacción enviada genera un ID de transacción único en función de su carga útil serializada exacta (incluidos el número de secuencia y el remitente). Si envías la misma carga útil varias veces, se produce el mismo ID de transacción. El libro de contabilidad garantiza que una transacción se ejecute como máximo una vez, lo que hace que sea seguro volver a enviar la misma carga útil de transacción a un extremo diferente si uno de ellos no está disponible.

    Para obtener más detalles, consulta la SubmitTransactionRequest página de referencia.

Latencia, sondeo y estrategia de reintento

Cuando envíes una transacción, el validador primero realizará una verificación rápida para asegurarse de que sus firmas y números de secuencia sean válidos. Si se realiza correctamente, la API de Universal Ledger responderá de inmediato con un SubmitTransactionResponse que incluye su ID de transacción asignado.

La mayoría de las transacciones se finalizan en un plazo de 3 segundos. Para verificar el estado de la transacción, sondea el QueryTransactionState método con el ID de transacción proporcionado.

  • Si el estado de la transacción sigue siendo PENDING, recupera el estado nuevamente con una estrategia de retirada exponencial. Por ejemplo, consulta en intervalos de 3 segundos, 9 segundos, 27 segundos y 60 segundos.

  • Si QueryTransactionState muestra NOT_FOUND, vuelve a enviar la transacción.

Una vez que un intento de transacción sea FINALIZED, la respuesta también incluirá un TransactionCertificate con varios detalles, como los siguientes:

  • El ID de ronda en el que se finalizó la transacción
  • El estado de ejecución (OK o fallido)
  • Eventos de transacción, incluidas las salidas de transacción

Protocolo de tiempo de espera

En el improbable caso de que una transacción permanezca en estado PENDING o NOT_FOUND después de 60 segundos, supón que el validador que entrega tus solicitudes no puede alcanzar a otros validadores de la red. Realiza los pasos que se indican a continuación:

  1. Selecciona un extremo diferente en una región de red diferente.
  2. Vuelve a enviar la misma carga útil de transacción firmada.
  3. Para que el equipo de Universal Ledger investigue el problema, envíale un correo electrónico a gcul-help@google.com.

Cuando verifiques el estado de la transacción, la respuesta podría incluir varios TransactionAttempt mensajes si enviaste la misma carga útil varias veces. Como máximo, se finalizará un intento con un estado de transacción OK, que se encuentra en TransactionEffects, mientras que otros intentos estarán pendientes o tendrán un estado fallido. Este es el comportamiento esperado. El libro de contabilidad ejecutó correctamente uno de los envíos de transacciones y rechazó, o rechazará, los reenvíos duplicados.

Coherencia de la red

  • Transacciones finalizadas: Una vez que un validador informa que una transacción se finalizó, se espera que todos los demás validadores de la misma red procesen la transacción y reproduzcan exactamente los mismos resultados. Si envías un QueryAccountRequest con el ID de ronda en el que se finalizó la transacción, como se puede encontrar en su TransactionCertificate, se obtienen resultados idénticos en todos los validadores sincronizados.

  • Transacciones no finalizadas: Debido a que las transacciones se propagan por la red de forma asíncrona, el hecho de que una transacción se informe como finalizada puede variar entre los diferentes validadores.

    Un validador que se recupera de una interrupción o que experimenta un retraso en la sincronización puede informar temporalmente una transacción finalizada como PENDING o NOT_FOUND. El estado de la transacción se resolverá una vez que el validador se ponga al día.

Responsabilidades del cliente y manejo de errores

  • Seguimiento de transacciones: Las aplicaciones cliente deben hacer un seguimiento del estado de todas las transacciones enviadas hasta que se finalicen.

  • Manejo de errores: Si falla una transacción, recupera y examina los detalles de la falla incluidos en el TransactionCertificate para activar la corrección adecuada a nivel empresarial.

¿Qué sigue?