Panduan penerapan klien

Panduan ini memberikan pedoman arsitektur dan implementasi bagi developer yang membangun klien Universal Ledger API. Pelajari cara:

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

Menghubungkan ke endpoint API Universal Ledger

Permintaan dirutekan melalui Universal Ledger API ke endpoint jaringan tertentu. Endpoint jaringan adalah resource Cloud regional yang mendistribusikan permintaan ke validator dalam region tersebut. Untuk menjangkau endpoint jaringan, klien harus terhubung ke endpoint API regional (REP) yang cocok dengan region Cloud tempat endpoint jaringan tersebut berada.

Nama endpoint regional mengikuti format berikut:

universalledger.REGION.rep.googleapis.com

Ganti REGION dengan wilayah yang didukung tempat endpoint jaringan Anda berada.

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.

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

Karakteristik eksekusi transaksi

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

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

  • Pengiriman ulang idempoten: Setiap transaksi yang dikirimkan menghasilkan ID transaksi unik berdasarkan payload yang diserialisasi secara tepat (termasuk nomor urut dan pengirim). Mengirimkan payload yang sama persis beberapa kali akan menghasilkan ID transaksi yang sama. Ledger memastikan transaksi dieksekusi maksimal sekali, 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.

Strategi latensi, polling, dan percobaan ulang

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

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

  • Jika status transaksi masih PENDING, ambil status lagi menggunakan strategi backoff eksponensial. Misalnya, buat 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 tempat transaksi diselesaikan.
  • Status eksekusi (Oke atau gagal).
  • Peristiwa transaksi, termasuk output transaksi apa pun.

Protokol waktu tunggu

Jika transaksi tetap dalam status PENDING atau NOT_FOUND setelah 60 detik, asumsikan bahwa validator yang melayani permintaan Anda gagal mengikuti validator lain dalam 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 menggunakan tombol 'Kirim masukan' di bagian atas halaman ini agar tim Universal Ledger dapat menyelidikinya.

Saat memeriksa status transaksi, respons mungkin menyertakan beberapa pesan TransactionAttempt jika Anda mengirimkan payload yang sama beberapa kali. Maksimal satu upaya akan diselesaikan dengan status transaksi OK, yang 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 dengan benar, atau pada akhirnya akan menolak, pengiriman ulang yang duplikat.

Konsistensi jaringan

  • Transaksi yang diselesaikan: Setelah transaksi dilaporkan sebagai selesai oleh satu validator, semua validator lain di jaringan yang sama diharapkan pada akhirnya akan memproses transaksi dan mereproduksi hasil yang sama persis. Mengirimkan QueryAccountRequest menggunakan ID putaran tempat transaksi diselesaikan, seperti yang dapat ditemukan di TransactionCertificate, akan memberikan hasil yang sama pada semua validator yang disinkronkan.

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

    Validator yang pulih dari pemadaman layanan atau mengalami jeda sinkronisasi mungkin melaporkan transaksi yang telah diselesaikan sebagai PENDING atau NOT_FOUND untuk sementara. Status transaksi akan diselesaikan setelah validator mengejar ketertinggalan.

Tanggung jawab klien dan penanganan error

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

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

Langkah berikutnya