Universal Ledger CLI einrichten

Die Universal Ledger-Befehlszeile ist eine Befehlszeilenschnittstelle, die zu Testzwecken bereitgestellt wird, um das Senden von Transaktionen und die Interaktion mit einem Universal Ledger-Netzwerk zu erleichtern. Für Produktionsanwendungsfälle wird empfohlen, stattdessen Integrationen mit den Universal Ledger-APIs zu erstellen.

In diesem Leitfaden wird beschrieben, wie Sie mit der Universal Ledger CLI beginnen. Sie erfahren, wie Sie:

  • Universal Ledger CLI herunterladen und einrichten

  • Konten mit der CLI erstellen und verwalten

  • Weitere in der CLI verfügbare Befehle

Hinweis

Für diese Anleitung ist Folgendes erforderlich:

  • Ein Google Cloud -Projekt mit aktivierter Universal Ledger API.

  • Eine IAM-Rolle wie roles/universalledger.networkUser, damit Sie Transaktionen senden und den Status von Konten in einem Universal Ledger-Netzwerk abfragen können.

  • Ein vorhandenes Universal Ledger-Konto, das für Sie im Netzwerk erstellt wurde. Wenn Sie noch keines haben, lesen Sie den Abschnitt Neues Konto anfordern.

CLI einrichten

Um die Einrichtung zu vereinfachen, wurde diese Anleitung für die Standardumgebung geschrieben, die in einer Cloud Shell-Sitzung bereitgestellt wird. Möglicherweise müssen Sie diese Befehle ändern, wenn Sie die CLI in einer anderen Umgebung verwenden möchten.

Aktivieren Sie Cloud Shell in der Google Cloud Console.

Cloud Shell aktivieren

Führen Sie den folgenden Befehl aus, um ein Verzeichnis für die CLI-Konfigurationsdateien zu erstellen.

mkdir -p ~/.config/ul-cli

Führen Sie die folgenden Befehle aus, um das ul-cli-Docker-Image abzurufen, einen Alias für die Ausführung der Binärdatei zu definieren und zu bestätigen, dass die Binärdatei funktioniert.

docker pull us-docker.pkg.dev/gcul-artifacts/images/client/ul-cli:latest
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-docker.pkg.dev/gcul-artifacts/images/client/ul-cli:latest"
ul-cli --help

Führen Sie den folgenden Befehl aus, um die CLI zu konfigurieren.

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

Ersetzen Sie Folgendes:

  • PROJECT_ID: die ID des Google Cloud Projekts, in dem die Universal Ledger API aktiviert ist.
  • REGION: die Region des Endpunkts, den Sie erreichen möchten.
  • NETWORK_NAME: Der Name des Netzwerks, mit dem Sie interagieren möchten.

Wenn Sie Hilfe bei der Auswahl eines geeigneten Endpunkts benötigen, lesen Sie den Abschnitt Verfügbare Netzwerke und Regionen.

Mit dem vorherigen Befehl wird eine Datei unter

~/.config/ul-cli/config.yaml

mit der Konfiguration, die von der CLI verwendet und verwaltet wird.

Universal Ledger-Konten verwalten

In diesem Abschnitt wird erläutert, wie Sie ein vorhandenes Konto registrieren, ein neues Konto für sich selbst im Ledger erstellen und neue Konten für andere erstellen.

Vorhandenes Konto registrieren

Sobald ein Konto für Sie von einem anderen Teilnehmer im Netzwerk erstellt wurde, können Sie mit dem folgenden Befehl die Kontodetails im Adressbuch der CLI registrieren.

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

Ersetzen Sie Folgendes:

  • ACCOUNT_ALIAS: Ein kurzer String, der lokal von der CLI verwendet wird, um dieses Konto bei zukünftigen Befehlsaufrufen zu identifizieren. Beispiel: usd-operator, my-token-manager oder test-user-account.
  • ACCOUNT_ID: die ID des Universal Ledger-Kontos, das für Sie erstellt wurde.
  • ACCOUNT_KMS_KEY: Die vollständige Ressourcen-ID der Cloud KMS-Schlüsselversion, die von diesem Konto verwendet wird. Das Konto muss mit dem öffentlichen Teil dieser bestimmten Schlüsselversion erstellt worden sein. Das erwartete Format finden Sie unter Ressourcen-ID abrufen.

Dies ist ein lokaler Vorgang, bei dem die Kontodetails in der CLI-Konfigurationsdatei aufgezeichnet werden. So können Sie Anfragen im Namen dieses Kontos signieren und an das Ledger senden.

Ein neues Konto für Sie erstellen

Neue Konten können mit dem Unterbefehl ul-cli accounts create erstellt werden. Wenn Sie beispielsweise ein neues Nutzerkonto erstellen möchten, können Sie Folgendes verwenden:

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

Ersetzen Sie Folgendes:

  • NEW_ACCOUNT_ALIAS: Ein kurzer String, der lokal von der CLI verwendet wird, um dieses Konto bei zukünftigen Befehlsaufrufen zu identifizieren.
  • NEW_ACCOUNT_KMS_KEY: Die vollständige Ressourcen-ID der Cloud KMS-Schlüsselversion, die vom neuen Nutzerkonto verwendet werden soll.
  • NEW_ACCOUNT_COMMENT: ein String mit allen relevanten Informationen, die im Ledger für das neue Nutzerkonto aufgezeichnet werden sollen. Dies ist ein undurchsichtiger Wert, der im Ledger gespeichert, aber nicht anderweitig vom Universal Ledger interpretiert wird. Nachdem dieses Feld erstellt wurde, ist es unveränderlich und kann von jedem mit Zugriff auf das Netzwerk gelesen werden.
  • NEW_ACCOUNT_ROLES: eine durch Kommas getrennte Liste von Rollen, die dem neuen Nutzerkonto zugewiesen werden sollen. Beispiel: payer, receiver, contract-creator oder contract-participant.
  • ACCOUNT_MANAGER_ALIAS: Der Alias eines Kontomanagers, der zuvor mit der CLI registriert oder erstellt wurde.

Dadurch wird eine CreateAccount-Transaktion im Namen des angegebenen Account Managers signiert und gesendet.

Führen Sie ul-cli accounts create --help aus, um die Optionen für andere Arten von Konten zu sehen, die Sie erstellen können.

Neues Konto für eine andere Person erstellen

Wenn Sie ein Konto für eine andere Person erstellen möchten, bitten Sie sie, Ihnen ihren öffentlichen Schlüssel zu senden und in einer Datei zu speichern. Im Allgemeinen wird empfohlen, das PEM-Codierungsformat für Schlüssel zu verwenden. Wenn der Signaturschlüssel beispielsweise die P-256-Elliptische-Kurve mit SHA256-Digest verwendet, speichern Sie ihn in einer Datei mit dem Namen pem_ec_p256_sha256.pub:

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

Führen Sie dann den folgenden Befehl aus, um das Konto zu erstellen:

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

Ersetzen Sie Folgendes:

  • NEW_ACCOUNT_ALIAS: Eine kurze Zeichenfolge, die von der CLI lokal verwendet wird, um dieses Konto bei zukünftigen Befehlsaufrufen zu identifizieren. Da Sie jedoch nicht über den privaten Schlüssel verfügen, können Sie keine Transaktionen signieren oder senden.
  • NEW_ACCOUNT_COMMENT: ein String mit allen relevanten Informationen, die im Ledger für das neue Nutzerkonto aufgezeichnet werden sollen. Dies ist ein undurchsichtiger Wert, der im Ledger gespeichert, aber nicht anderweitig vom Universal Ledger interpretiert wird. Nachdem dieses Feld erstellt wurde, ist es unveränderlich und kann von jedem mit Zugriff auf das Netzwerk gelesen werden.
  • NEW_ACCOUNT_ROLES: eine durch Kommas getrennte Liste von Rollen, die dem neuen Nutzerkonto zugewiesen werden sollen. Beispiel: payer, receiver, contract-creator oder contract-participant.
  • ACCOUNT_MANAGER_ALIAS: Der Alias eines Kontomanagers, der zuvor mit der CLI registriert oder erstellt wurde.

Dadurch wird eine CreateAccount-Transaktion im Namen des angegebenen Account Managers signiert und gesendet.

Die Flags --public-key und --key-format sind für alle accounts create-Unterbefehle verfügbar. Sie können damit also auch andere Arten von Konten erstellen. Informationen zu alternativen unterstützten Formaten für öffentliche Schlüssel finden Sie in der Universal Ledger API-Referenz unter KeyFormat.

Verwaltete Konten auflisten

Führen Sie den folgenden Befehl aus, um alle Konten aufzurufen, die lokal registriert oder mit der Universal Ledger CLI erstellt wurden:

ul-cli accounts list

Weitere Befehle ausprobieren

Mit dem Flag --help können Sie alle anderen Befehle und Unterbefehle auf der Universal Ledger CLI aufrufen.

Wenn Sie beispielsweise die verfügbaren Befehle der obersten Ebene aufrufen möchten, führen Sie folgenden Befehl aus:

ul-cli --help

Dazu gehören Unterbefehle zum Senden anderer Arten von Transaktionen, z. B.:

  • accounts: zum Registrieren oder Erstellen von Konten und zum Ausführen von Verwaltungsaufgaben für vorhandene Konten, z. B. zum Hinzufügen oder Entfernen von Rollen und zum Abfragen von Kontodetails.
  • contracts: zum Bereitstellen, Erteilen von Berechtigungen und Aufrufen von Methoden für programmierbare Verträge.
  • issuance: für ein Clearinghouse, um das Ausgabelimit eines Token-Managers zu erhöhen oder zu senken und Abrechnungsvorgänge auszuführen.
  • tokens: Damit ein Token-Manager Tokens für ein Nutzerkonto prägen oder verbrennen kann.
  • wallet: Damit ein Nutzerkonto einen Betrag von seinem Guthaben auf ein anderes Nutzerkonto übertragen kann.

Nächste Schritte