Menyiapkan Universal Ledger CLI

Universal Ledger CLI adalah antarmuka command line yang disediakan untuk tujuan eksperimen guna memfasilitasi pengiriman transaksi dan interaksi dengan jaringan Universal Ledger. Untuk kasus penggunaan produksi, sebaiknya bangun integrasi menggunakan Universal Ledger API.

Panduan ini menjelaskan cara memulai Universal Ledger CLI. Pelajari cara:

  • Mendapatkan dan menyiapkan Universal Ledger CLI.

  • Membuat dan mengelola akun menggunakan CLI.

  • Pelajari perintah lain yang tersedia di CLI.

Sebelum memulai

Untuk menyelesaikan panduan ini, Anda memerlukan hal berikut:

  • Project Google Cloud dengan Universal Ledger API diaktifkan.

  • Peran IAM seperti roles/universalledger.networkUser sehingga Anda dapat mengirimkan transaksi dan mengkueri status akun di jaringan Universal Ledger.

  • Akun Universal Ledger yang sudah ada yang dibuat untuk Anda di jaringan. Jika Anda belum memilikinya, lihat Meminta akun baru.

Menyiapkan CLI

Untuk menyederhanakan penyiapan, panduan ini telah ditulis untuk lingkungan default yang disediakan dalam sesi Cloud Shell. Anda mungkin perlu mengubah perintah ini jika ingin menggunakan CLI di lingkungan yang berbeda.

Di konsol Google Cloud , aktifkan Cloud Shell.

Aktifkan Cloud Shell

Jalankan perintah berikut untuk membuat direktori yang akan menyimpan file konfigurasi CLI.

mkdir -p ~/.config/ul-cli

Mengambil image dan mengonfigurasi alias

Jalankan setiap perintah berikut untuk mengambil image Docker ul-cli, menentukan alias untuk menjalankan biner, dan mengonfirmasi bahwa biner berfungsi:

docker pull us-central1-docker.pkg.dev/universal-ledger-artifacts/images/client/ul-cli:stable
alias ul-cli="docker run --rm -i --user $(id -u):$(id -g) \
    --volume /tmp:/tmp \
    --volume ~/.config/ul-cli:/home/.config/ul-cli \
    --volume ~/.config/gcloud:/home/.config/gcloud \
    --volume .:/workspace \
    --env HOME=/home \
    --workdir /workspace \
    us-central1-docker.pkg.dev/universal-ledger-artifacts/images/client/ul-cli:stable"
ul-cli --help

Mengonfigurasi ul-cli

Jalankan perintah berikut untuk mengonfigurasi CLI.

ul-cli config setup projects/PROJECT_ID/locations/REGION/endpoints/NETWORK_NAME

Ganti kode berikut:

  • PROJECT_ID: ID project Google Cloud tempat Universal Ledger API diaktifkan.
  • REGION: region endpoint yang ingin Anda jangkau.
  • NETWORK_NAME: nama jaringan yang ingin Anda gunakan untuk berinteraksi.

Jika Anda memerlukan bantuan untuk memilih endpoint yang sesuai, lihat Jaringan dan lokasi Universal Ledger.

Perintah ini akan membuat file konfigurasi CLI di ~/.config/ul-cli/config.yaml (di Linux dan macOS).

Mengelola akun Universal Ledger

Bagian ini menjelaskan cara mendaftarkan akun yang ada, membuat akun baru untuk diri sendiri di ledger, dan membuat akun baru untuk orang lain.

Mendaftarkan akun yang ada

Setelah akun dibuat untuk Anda oleh peserta lain di jaringan, Anda dapat menggunakan perintah berikut untuk mendaftarkan detail akun di buku alamat CLI.

ul-cli accounts register \
    --alias ACCOUNT_ALIAS \
    --account-id ACCOUNT_ID \
    --key-name ACCOUNT_KMS_KEY

Ganti kode berikut:

  • ACCOUNT_ALIAS: string pendek yang digunakan secara lokal oleh CLI untuk mengidentifikasi akun ini dalam pemanggilan perintah di masa mendatang. Misalnya: usd-operator, my-token-manager, atau test-user-account.
  • ACCOUNT_ID: ID akun Universal Ledger yang telah dibuat untuk Anda.
  • ACCOUNT_KMS_KEY: ID resource lengkap dari versi kunci Cloud KMS yang digunakan oleh akun ini. Akun harus dibuat menggunakan bagian publik dari versi kunci spesifik ini. Lihat Mengambil ID resource untuk format yang diharapkan.

Ini adalah operasi lokal yang akan mencatat detail akun dalam file konfigurasi CLI, sehingga Anda dapat menandatangani dan mengirimkan permintaan ke ledger atas nama akun ini.

Membuat akun baru untuk Anda

Akun baru dapat dibuat menggunakan subperintah ul-cli accounts create. Misalnya, untuk membuat akun pengguna baru, Anda dapat menggunakan:

ul-cli accounts create account \
    --alias NEW_ACCOUNT_ALIAS \
    --key-name NEW_ACCOUNT_KMS_KEY \
    --comment "NEW_ACCOUNT_COMMENT" \
    --roles NEW_ACCOUNT_ROLES \
    --sender ACCOUNT_MANAGER_ALIAS

Ganti kode berikut:

  • NEW_ACCOUNT_ALIAS: string pendek yang digunakan secara lokal oleh CLI untuk mengidentifikasi akun ini dalam pemanggilan perintah di masa mendatang.
  • NEW_ACCOUNT_KMS_KEY: ID resource lengkap dari versi kunci Cloud KMS yang akan digunakan oleh akun pengguna baru.
  • NEW_ACCOUNT_COMMENT: string dengan informasi relevan apa pun untuk dicatat di ledger yang terkait dengan akun pengguna baru. Ini adalah nilai buram yang disimpan di ledger, tetapi tidak ditafsirkan oleh Universal Ledger. Setelah dibuat, kolom ini tidak dapat diubah dan dapat dibaca oleh siapa pun yang memiliki akses ke jaringan.
  • NEW_ACCOUNT_ROLES: daftar Peran yang dipisahkan koma untuk ditetapkan ke akun pengguna baru. Misalnya: payer, receiver, contract-creator, atau contract-participant.
  • ACCOUNT_MANAGER_ALIAS: alias pengelola akun yang sebelumnya terdaftar atau dibuat dengan CLI.

Tindakan ini akan menandatangani dan mengirimkan transaksi CreateAccount atas nama pengelola akun yang diberikan.

Jalankan ul-cli accounts create --help untuk melihat opsi yang tersedia untuk jenis akun lain yang akan dibuat.

Membuat akun baru untuk orang lain

Untuk membuat akun bagi orang lain, minta dia untuk membagikan kunci publiknya kepada Anda dan menyimpannya dalam file. Umumnya, sebaiknya gunakan format encoding PEM untuk kunci. Misalnya, jika kunci penandatanganannya menggunakan kurva eliptis P-256 dengan ringkasan SHA256, simpan dalam file bernama pem_ec_p256_sha256.pub:

-----BEGIN PUBLIC KEY-----
MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEJ/vWkd5wgakFbVD25k8WM9Ll6We+
c8RVDS0R4G8xetsmFjfNW/ZxwWeB86IvMjxY8ZsdU9+W7BL5YM6rUB5yCQ==
-----END PUBLIC KEY-----

Kemudian, jalankan perintah berikut untuk membuat akun:

ul-cli accounts create account \
    --alias NEW_ACCOUNT_ALIAS \
    --public-key "$(cat pem_ec_p256_sha256.pub)" \
    --key-format pem_ec_p256_sha256 \
    --comment "NEW_ACCOUNT_COMMENT" \
    --roles NEW_ACCOUNT_ROLES \
    --sender ACCOUNT_MANAGER_ALIAS

Ganti kode berikut:

  • NEW_ACCOUNT_ALIAS: string pendek yang digunakan secara lokal oleh CLI untuk mengidentifikasi akun ini dalam pemanggilan perintah di masa mendatang. Namun, perhatikan bahwa karena Anda tidak memiliki kunci pribadinya, Anda tidak dapat menandatangani atau mengirimkan transaksi.
  • NEW_ACCOUNT_COMMENT: string dengan informasi relevan apa pun untuk dicatat di ledger yang terkait dengan akun pengguna baru. Ini adalah nilai buram yang disimpan di ledger, tetapi tidak ditafsirkan oleh Universal Ledger. Setelah dibuat, kolom ini tidak dapat diubah dan dapat dibaca oleh siapa pun yang memiliki akses ke jaringan.
  • NEW_ACCOUNT_ROLES: daftar Peran yang dipisahkan koma untuk ditetapkan ke akun pengguna baru. Misalnya: payer, receiver, contract-creator, atau contract-participant.
  • ACCOUNT_MANAGER_ALIAS: alias pengelola akun yang sebelumnya terdaftar atau dibuat dengan CLI.

Tindakan ini akan menandatangani dan mengirimkan transaksi CreateAccount atas nama pengelola akun yang diberikan.

Flag --public-key dan --key-format tersedia untuk semua subperintah accounts create, sehingga Anda juga dapat menggunakannya untuk membuat jenis akun lainnya. Untuk format kunci publik alternatif yang didukung, lihat KeyFormat dalam referensi API Universal Ledger.

Mencantumkan akun terkelola

Jalankan perintah berikut untuk melihat semua akun yang terdaftar secara lokal atau dibuat dengan Universal Ledger CLI:

ul-cli accounts list

Menjelajahi perintah lainnya

Gunakan flag --help untuk mempelajari semua perintah dan subperintah lain yang tersedia di Universal Ledger CLI.

Misalnya, untuk melihat perintah level teratas yang tersedia, jalankan:

ul-cli --help

Hal ini mencakup subperintah untuk mengirimkan jenis transaksi lain seperti:

  • accounts: untuk mendaftarkan atau membuat akun, dan melakukan operasi pengelolaan pada akun yang ada, seperti menambahkan atau menghapus peran, dan mengkueri detail akun.
  • contracts: untuk men-deploy, memberikan izin, dan memanggil metode pada kontrak yang dapat diprogram.
  • issuance: agar lembaga kliring dapat menambah atau mengurangi batas penerbitan pengelola token, dan untuk melakukan operasi penyelesaian.
  • tokens: bagi pengelola token untuk mencetak atau membakar token di akun pengguna.
  • wallet: agar akun pengguna dapat mentransfer sejumlah dana dari saldonya ke akun pengguna lain.

Langkah berikutnya