Configura l'interfaccia a riga di comando Universal Ledger

L'interfaccia a riga di comando di Universal Ledger è un'interfaccia a riga di comando fornita a scopo di sperimentazione per facilitare l'invio di transazioni e l'interazione con una rete Universal Ledger. Per i casi d'uso di produzione, è consigliabile creare integrazioni utilizzando le API Universal Ledger invece.

Questa guida descrive come iniziare a utilizzare l'interfaccia a riga di comando di Universal Ledger. Scopri come:

  • Ottenere e configurare l'interfaccia a riga di comando di Universal Ledger.

  • Creare e gestire gli account utilizzando l'interfaccia a riga di comando.

  • Esplorare altri comandi disponibili nell'interfaccia a riga di comando.

Prima di iniziare

Per completare questa guida, avrai bisogno di:

  • Un Google Cloud progetto con l'API Universal Ledger abilitata.

  • Un ruolo IAM come roles/universalledger.networkUser per poter inviare transazioni ed eseguire query sullo stato degli account in una rete Universal Ledger.

  • Un account Universal Ledger esistente creato per te sulla rete. Se non ne hai già uno, consulta Richiedere un nuovo account.

Configurare l'interfaccia a riga di comando

Per semplificare la configurazione, questa guida è stata scritta per l'ambiente predefinito fornito in una sessione di Cloud Shell. Potresti dover modificare questi comandi se vuoi utilizzare l'interfaccia a riga di comando in un ambiente diverso.

Nella Google Cloud console, attiva Cloud Shell.

Attiva Cloud Shell

Esegui il comando seguente per creare una directory in cui archiviare i file di configurazione dell'interfaccia a riga di comando.

mkdir -p ~/.config/ul-cli

Esegui ciascuno dei seguenti comandi per eseguire il pull dell'immagine Docker ul-cli, definire un alias per l'esecuzione del file binario e verificare che funzioni.

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

Esegui il comando seguente per configurare l'interfaccia a riga di comando.

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

Sostituisci quanto segue:

  • PROJECT_ID: l'ID del Google Cloud progetto in cui è abilitata l'API Universal Ledger.
  • REGION: la regione dell'endpoint che vuoi raggiungere.
  • NETWORK_NAME: il nome della rete con cui vuoi interagire.

Se hai bisogno di aiuto per scegliere un endpoint adatto, consulta Reti e regioni disponibili.

Il comando precedente creerà un file in

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

con la configurazione che verrà utilizzata e gestita dall'interfaccia a riga di comando.

Gestire gli account Universal Ledger

Questa sezione spiega come registrare un account esistente, creare un nuovo account per te nel ledger e creare nuovi account per qualcun altro.

Registrare un account esistente

Dopo che un altro partecipante alla rete ha creato un account per te, puoi utilizzare il seguente comando per registrare i dettagli dell'account nella rubrica dell'interfaccia a riga di comando.

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

Sostituisci quanto segue:

  • ACCOUNT_ALIAS: una breve stringa utilizzata localmente dall'interfaccia a riga di comando per identificare questo account nelle future invocazioni dei comandi. Ad esempio: usd-operator, my-token-manager o test-user-account.
  • ACCOUNT_ID: l'ID dell'account Universal Ledger creato per te.
  • ACCOUNT_KMS_KEY: l'ID risorsa completo della versione della chiave di Cloud KMS utilizzata da questo account. L'account deve essere stato creato utilizzando la parte pubblica di questa versione della chiave specifica. Per il formato previsto, consulta Recuperare l'ID di una risorsa.

Si tratta di un'operazione locale che registrerà i dettagli dell'account nel file di configurazione dell'interfaccia a riga di comando, consentendoti di firmare e inviare richieste al ledger per conto di questo account.

Creare un nuovo account per te

È possibile creare nuovi account utilizzando il sottocomando ul-cli accounts create. Ad esempio, per creare un nuovo account utente, puoi utilizzare:

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

Sostituisci quanto segue:

  • NEW_ACCOUNT_ALIAS: una breve stringa utilizzata localmente dall'interfaccia a riga di comando per identificare questo account nelle future invocazioni dei comandi.
  • NEW_ACCOUNT_KMS_KEY: l'ID risorsa completo della versione della chiave di Cloud KMS da utilizzare per il nuovo account utente.
  • NEW_ACCOUNT_COMMENT: una stringa con tutte le informazioni pertinenti da registrare nel ledger associato al nuovo account utente. Si tratta di un valore opaco archiviato nel ledger, ma non interpretato in altro modo da Universal Ledger. Una volta creato, questo campo è immutabile e leggibile da chiunque abbia accesso alla rete.
  • NEW_ACCOUNT_ROLES: un elenco separato da virgole di ruoli da assegnare al nuovo account utente. Ad esempio: payer, receiver, contract-creator o contract-participant.
  • ACCOUNT_MANAGER_ALIAS: l'alias di un account manager registrato o creato in precedenza con l'interfaccia a riga di comando.

Verrà firmata e inviata una CreateAccount transazione per conto dell'account manager specificato.

Esegui ul-cli accounts create --help per visualizzare le opzioni disponibili per altri tipi di account da creare.

Creare un nuovo account per qualcun altro

Per creare un account per qualcun altro, chiedigli di condividere con te la sua chiave pubblica e di archiviarla in un file. In genere, è consigliabile utilizzare il formato di codifica PEM per le chiavi. Ad esempio, se la chiave di firma utilizza la curva ellittica P-256 con il digest SHA256, salvala in un file denominato pem_ec_p256_sha256.pub:

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

Quindi, esegui il comando seguente per creare l'account:

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

Sostituisci quanto segue:

  • NEW_ACCOUNT_ALIAS: una breve stringa utilizzata localmente dall'interfaccia a riga di comando per identificare questo account nelle future invocazioni dei comandi. Tieni presente, tuttavia, che non potrai firmare o inviare transazioni perché non hai la chiave privata.
  • NEW_ACCOUNT_COMMENT: una stringa con tutte le informazioni pertinenti da registrare nel ledger associato al nuovo account utente. Si tratta di un valore opaco archiviato nel ledger, ma non interpretato in altro modo da Universal Ledger. Una volta creato, questo campo è immutabile e leggibile da chiunque abbia accesso alla rete.
  • NEW_ACCOUNT_ROLES: un elenco separato da virgole di ruoli da assegnare al nuovo account utente. Ad esempio: payer, receiver, contract-creator o contract-participant.
  • ACCOUNT_MANAGER_ALIAS: l'alias di un account manager registrato o creato in precedenza con l'interfaccia a riga di comando.

Verrà firmata e inviata una CreateAccount transazione per conto dell'account manager specificato.

I flag --public-key e --key-format sono disponibili per tutti i sottocomandi accounts create, quindi puoi utilizzarli anche per creare altri tipi di account. Per i formati di chiave pubblica alternativi supportati, consulta KeyFormat nel riferimento API Universal Ledger.

Elencare gli account gestiti

Esegui il comando seguente per visualizzare tutti gli account registrati localmente o creati con l'interfaccia a riga di comando di Universal Ledger:

ul-cli accounts list

Esplorare altri comandi

Utilizza il flag --help per esplorare tutti gli altri comandi e sottocomandi disponibili nell'interfaccia a riga di comando di Universal Ledger.

Ad esempio, per visualizzare i comandi di primo livello disponibili, esegui:

ul-cli --help

Sono inclusi i sottocomandi per inviare altri tipi di transazioni, ad esempio:

  • accounts: per registrare o creare account ed eseguire operazioni di gestione sugli account esistenti, come aggiungere o rimuovere ruoli ed eseguire query sui dettagli dell'account.
  • contracts: per eseguire il deployment, concedere autorizzazioni e richiamare metodi su contratti programmabili.
  • issuance: per una stanza di compensazione per aumentare o diminuire il limite di emissione di un gestore di token ed eseguire operazioni di liquidazione.
  • tokens: per un gestore di token per coniare o bruciare token su un account utente.
  • wallet: per un account utente per trasferire un importo dal saldo a un altro account utente.

Passaggi successivi