Universal Ledger CLI einrichten

Die Universal Ledger-Befehlszeile ist eine Befehlszeile, 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, Integrationen stattdessen mit den Universal Ledger APIs zu erstellen.

In diesem Leitfaden werden die ersten Schritte mit der Universal Ledger-Befehlszeile beschrieben. Sie erfahren, wie Sie:

  • Rufen Sie die Universal Ledger CLI ab und richten Sie sie ein.

  • Konten mit der Befehlszeile erstellen und verwalten

  • Sehen Sie sich andere Befehle an, die in der Befehlszeile verfügbar sind.

Hinweis

Für diese Anleitung benötigen Sie Folgendes:

  • 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 bestehendes Universal Ledger-Konto, das für Sie im Netzwerk erstellt wurde. Wenn Sie noch kein Konto haben, lesen Sie den Hilfeartikel Neues Konto anfordern.

Befehlszeile einrichten

Zur Vereinfachung der Einrichtung wurde diese Anleitung für die Standardumgebung geschrieben, die in einer Cloud Shell-Sitzung bereitgestellt wird. Wenn Sie die Befehlszeile in einer anderen Umgebung verwenden möchten, müssen Sie diese Befehle möglicherweise anpassen.

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

Image abrufen und Alias konfigurieren

Führen Sie die folgenden Befehle aus, um das Docker-Image ul-cli abzurufen, einen Alias für die Ausführung der Binärdatei zu definieren und zu prüfen, ob die Binärdatei funktioniert:

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

UL-CLI konfigurieren

Führen Sie den folgenden Befehl aus, um die Befehlszeile 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 Hilfeartikel zu Universal Ledger-Netzwerken und -Standorten.

Mit diesem Befehl wird die CLI-Konfigurationsdatei unter ~/.config/ul-cli/config.yaml (unter Linux und macOS) erstellt.

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 von einem anderen Teilnehmer im Netzwerk für Sie erstellt wurde, können Sie die Kontodetails mit dem folgenden Befehl im Adressbuch der Befehlszeile 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 von der Befehlszeile lokal 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 spezifischen Schlüsselversion erstellt worden sein. Informationen zum erwarteten Format finden Sie unter ID einer Ressource abrufen.

Dies ist ein lokaler Vorgang, bei dem die Kontodetails in der CLI-Konfigurationsdatei aufgezeichnet werden. So können Sie im Namen dieses Kontos Anfragen an das Ledger signieren und 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 von der Befehlszeile lokal 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 aufgezeichnet werden sollen, der mit dem neuen Nutzerkonto verknüpft ist. Dies ist ein intransparenter Wert, der im Ledger gespeichert, aber vom Universal Ledger nicht anderweitig interpretiert wird. Nach dem Erstellen ist dieses Feld unveränderlich und kann von jedem gelesen werden, der Zugriff auf das Netzwerk hat.
  • 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 Account Managers, der zuvor mit der Befehlszeile 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 verfügbaren Optionen für andere Arten von Konten aufzurufen, 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, ihren öffentlichen Schlüssel mit Ihnen zu teilen, und speichern Sie ihn in einer Datei. Im Allgemeinen wird empfohlen, das PEM-Codierungsformat für Schlüssel zu verwenden. Wenn der Signaturschlüssel beispielsweise die elliptische Kurve P-256 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: Ein kurzer String, der von der Befehlszeile 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 aufgezeichnet werden sollen, der mit dem neuen Nutzerkonto verknüpft ist. Dies ist ein intransparenter Wert, der im Ledger gespeichert, aber vom Universal Ledger nicht anderweitig interpretiert wird. Nach dem Erstellen ist dieses Feld unveränderlich und kann von jedem gelesen werden, der Zugriff auf das Netzwerk hat.
  • 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 Account Managers, der zuvor mit der Befehlszeile 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, sodass Sie sie auch zum Erstellen anderer Arten von Konten verwenden können. Informationen zu alternativen unterstützten Formaten für öffentliche Schlüssel finden Sie unter KeyFormat in der Universal Ledger API-Referenz.

Verwaltete Konten auflisten

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

ul-cli accounts list

Weitere Befehle entdecken

Verwenden Sie das Flag --help, um alle anderen Befehle und Unterbefehle zu erkunden, die in der Universal Ledger-Befehlszeile verfügbar sind.

Führen Sie beispielsweise den folgenden Befehl aus, um die verfügbaren Befehle auf oberster Ebene aufzurufen:

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 Verwaltungsvorgängen 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: Damit kann ein Clearinghouse das Ausgabelimit eines Token-Managers erhöhen oder verringern und Abrechnungsvorgänge ausführen.
  • tokens: Damit ein Token-Manager Tokens in einem Nutzerkonto erstellen oder löschen kann.
  • wallet: Damit ein Nutzerkonto einen Betrag von seinem Guthaben auf ein anderes Nutzerkonto übertragen kann.

Nächste Schritte