Membangun klien Anda sendiri

Panduan ini memberikan rekomendasi untuk memastikan penerapan klien Universal Ledger berinteraksi dengan jaringan secara aman dan andal. Pelajari cara:

  • Memanfaatkan topologi jaringan untuk ketersediaan tinggi.
  • Mengirim transaksi dan memahami hasil eksekusi.
  • Menerapkan strategi polling, waktu tunggu, dan percobaan ulang.

Topologi jaringan dan ketersediaan tinggi

Jaringan Universal Ledger terdiri dari sejumlah validator yang didistribusikan di antara beberapa zona dan region, sehingga memastikan ketersediaan tinggi untuk jaringan secara keseluruhan.

  • Kegagalan zona: Jika satu validator gagal dalam zona Cloud, validator lain dalam region yang sama akan terus memproses permintaan dengan lancar.

  • Gangguan regional: Jika seluruh region tidak tersedia, validator di region lain akan tetap beroperasi. Untuk terus mengirim transaksi, klien Anda dapat melakukan penggantian dan mencoba mengirim ulang transaksi melalui endpoint yang berbeda.

Karakteristik eksekusi transaksi

  • Eksekusi atomik: Transaksi akan berhasil sepenuhnya atau gagal sepenuhnya. Eksekusi transaksi sebagian—seperti hanya mentransfer sebagian dana yang diminta karena saldo tidak mencukupi—tidak akan pernah terjadi. Hal ini mencakup rantai transaksi, yang memungkinkan Anda menggabungkan beberapa transaksi arbitrer ke dalam satu urutan atomik.

  • Tidak ada percobaan ulang otomatis: Jaringan mencoba mengeksekusi transaksi yang dikirimkan tepat satu kali. Jika eksekusi gagal, ledger tidak akan mengantre atau mencoba ulang transaksi secara otomatis.

  • Pengiriman ulang idempoten: Setiap transaksi yang dikirimkan akan menghasilkan ID transaksi unik berdasarkan payload serialisasi yang tepat (termasuk nomor urutan dan pengirim). Mengirimkan payload yang sama persis beberapa kali akan menghasilkan ID transaksi yang sama. Ledger memastikan transaksi dieksekusi paling banyak satu kali, sehingga aman untuk mengirim ulang payload transaksi yang sama ke endpoint yang berbeda jika salah satunya tampak tidak tersedia.

    Untuk mengetahui detail selengkapnya, lihat halaman referensi SubmitTransactionRequest.

Latensi, polling, dan strategi percobaan ulang

Saat Anda mengirimkan transaksi, validator akan terlebih dahulu melakukan pemeriksaan cepat untuk memastikan tanda tangan dan nomor urutnya valid. Jika berhasil, Universal Ledger API akan segera merespons dengan SubmitTransactionResponse yang menyertakan ID transaksi yang ditetapkan.

Sebagian besar transaksi diselesaikan dalam waktu 3 detik. Untuk memeriksa status transaksi, lakukan polling QueryTransactionState metode menggunakan ID transaksi yang diberikan.

  • Jika status transaksi masih PENDING, ambil statusnya lagi menggunakan strategi backoff eksponensial. Misalnya, kueri dengan interval 3 detik, 9 detik, 27 detik, dan 60 detik.

  • Jika QueryTransactionState menampilkan NOT_FOUND, kirim ulang transaksi.

Setelah upaya transaksi FINALIZED, respons juga akan menyertakan TransactionCertificate dengan berbagai detail seperti:

  • ID putaran saat transaksi diselesaikan.
  • Status eksekusi (OK atau gagal).
  • Peristiwa transaksi, termasuk output transaksi.

Protokol waktu tunggu

Jika transaksi tetap dalam status PENDING atau NOT_FOUND setelah 60 detik, kemungkinan validator yang melayani permintaan Anda gagal mengikuti validator lain di jaringan. Selesaikan langkah-langkah berikut:

  1. Pilih endpoint lain di region jaringan yang berbeda.
  2. Kirim ulang payload transaksi bertanda tangan yang sama persis.
  3. Laporkan masalah ini dengan mengirim email ke gcul-help@google.com agar tim Universal Ledger dapat menyelidikinya.

Saat memeriksa status transaksi, respons mungkin menyertakan beberapa TransactionAttempt pesan jika Anda mengirimkan payload yang sama beberapa kali. Paling banyak satu upaya akan diselesaikan dengan status transaksi OK, ditemukan di TransactionEffects, sedangkan upaya lainnya akan tertunda atau memiliki status gagal. Ini adalah perilaku yang diharapkan; ledger berhasil mengeksekusi salah satu pengiriman transaksi dan menolak, atau pada akhirnya akan menolak, pengiriman ulang duplikat dengan benar.

Konsistensi jaringan

  • Transaksi yang diselesaikan: Setelah transaksi dilaporkan sebagai diselesaikan oleh satu validator, semua validator lain di jaringan yang sama diharapkan akan memproses transaksi dan menghasilkan hasil yang sama persis. Mengirimkan a QueryAccountRequest menggunakan ID putaran saat transaksi diselesaikan, seperti yang dapat di temukan di TransactionCertificate, akan menghasilkan hasil yang sama pada semua validator yang disinkronkan.

  • Transaksi yang belum diselesaikan: Karena transaksi disebarkan di seluruh jaringan secara asinkron, apakah transaksi dilaporkan sebagai diselesaikan dapat bervariasi di antara validator yang berbeda.

    Validator yang pulih dari gangguan atau mengalami jeda sinkronisasi mungkin akan melaporkan transaksi yang diselesaikan sebagai PENDING atau NOT_FOUND untuk sementara. Status transaksi akan diselesaikan setelah validator mengikuti.

Tanggung jawab klien dan penanganan error

  • Pelacakan transaksi: Aplikasi klien harus melacak status semua transaksi yang dikirimkan hingga diselesaikan.

  • Penanganan error: Jika transaksi gagal, ambil dan periksa detail kegagalan yang disertakan dalam TransactionCertificate untuk memicu perbaikan tingkat bisnis yang sesuai.

Langkah berikutnya