Lineamientos de implementación del cliente

En esta guía, se proporcionan lineamientos de arquitectura y de implementación para los desarrolladores que crean clientes de la API de Universal Ledger. Aprenderás a realizar estas tareas:

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

Conéctate a un extremo de API de Universal Ledger

Las solicitudes se enrutan a través de la API de Universal Ledger a un extremo de red específico. Los extremos de red son recursos regionales de Cloud que distribuyen solicitudes a los validadores dentro de esa región. Para llegar a un extremo de red, los clientes deben conectarse al extremo de API regional (REP) que coincida con la región de Cloud en la que se encuentra ese extremo de red.

Los nombres de los extremos regionales siguen este formato:

universalledger.REGION.rep.googleapis.com

Reemplaza REGION por la región admitida en la que se encuentra tu extremo de red.

Topología de red y alta disponibilidad

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

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

  • Interrupciones regionales: Si una región entera 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 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 las cadenas de transacciones, que te permiten 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 la ejecución falla, el libro mayor 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 exactamente la misma carga útil varias veces, se produce el mismo ID de transacción. El libro mayor 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 la transacción a un extremo diferente si uno de ellos parece no estar disponible.

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

Latencia, sondeo y estrategia de reintento

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

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

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

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

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

  • Es el ID de la ronda en la que se finalizó la transacción.
  • El estado de la ejecución (correcto o con errores)
  • Eventos de transacciones, incluidos los resultados de las transacciones

Protocolo de tiempo de espera

En el caso poco probable de que una transacción permanezca en estado PENDING o NOT_FOUND después de 60 segundos, asume que el validador que entrega tus solicitudes no puede ponerse al día con otros validadores de la red. Realiza los pasos que se indican a continuación:

  1. Selecciona un extremo diferente en otra región de red.
  2. Vuelve a enviar exactamente la misma carga útil de la transacción firmada.
  3. Informa el problema con el botón "Enviar comentarios" que se encuentra en la parte superior de esta página para que el equipo de Universal Ledger lo investigue.

Cuando verifiques el estado de la transacción, la respuesta podría incluir varios mensajes TransactionAttempt 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 de error. Este es el comportamiento esperado; el libro mayor ejecutó correctamente uno de los envíos de transacciones y rechazó de forma correcta, o rechazará con el tiempo, los reenvíos duplicados.

Coherencia de la red

  • Transacciones finalizadas: Una vez que un validador informa que una transacción está finalizada, se espera que todos los demás validadores de la misma red procesen la transacción y reproduzcan exactamente los mismos resultados. Enviar un QueryAccountRequest con el ID de ronda en el que se finalizó la transacción, como se puede encontrar en su TransactionCertificate, produce 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 una transacción falla, recupera y, luego, inspecciona los detalles del error incluidos en el objeto TransactionCertificate para activar la solución adecuada a nivel empresarial.

¿Qué sigue?