Configura l'interfaccia a riga di comando Universal Ledger

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

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

  • Ottieni e configura l'interfaccia a riga di comando Universal Ledger.

  • Crea e gestisci gli account utilizzando l'interfaccia a riga di comando.

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

Prima di iniziare

Per completare questa guida, devi disporre di quanto segue:

  • Un progetto Google Cloud 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 Richiedi un nuovo account.

Configura 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 console Google Cloud , attiva Cloud Shell.

Attiva Cloud Shell

Esegui questo comando per creare una directory in cui conservare i file di configurazione dell'interfaccia a riga di comando.

mkdir -p ~/.config/ul-cli

Esegui il pull dell'immagine e configura l'alias

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 il file binario funzioni:

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

Configura ul-cli

Esegui questo comando 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 progetto Google Cloud 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 località di Universal Ledger.

Questo comando crea il file di configurazione dell'interfaccia a riga di comando in ~/.config/ul-cli/config.yaml (su Linux e macOS).

Gestisci gli account Universal Ledger

Questa sezione spiega come registrare un account esistente, creare un nuovo account per te nel registro e creare nuovi account per un'altra persona.

Registra un account esistente

Una volta 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 stringa breve utilizzata localmente dall'interfaccia a riga di comando per identificare questo account nelle chiamate future dei comandi. Ad esempio: usd-operator, my-token-manager o test-user-account.
  • ACCOUNT_ID: l'ID dell'account Universal Ledger che è stato creato per te.
  • ACCOUNT_KMS_KEY: l'ID risorsa completo della versione della chiave 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 Recupero dell'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 stringa breve utilizzata localmente dall'interfaccia a riga di comando per identificare questo account nelle chiamate future dei comandi.
  • NEW_ACCOUNT_KMS_KEY: l'ID risorsa completo della versione della chiave Cloud KMS che verrà utilizzata dal 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 che viene archiviato nel ledger, ma non interpretato in altro modo dal 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.

In questo modo, verrà firmata e inviata una transazione CreateAccount per conto dell'account manager specificato.

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

Crea un nuovo account per un'altra persona

Per creare un account per un'altra persona, chiedile di condividere con te la sua chiave pubblica e di memorizzarla in un file. In genere, si consiglia di utilizzare il formato di codifica PEM per le chiavi. Ad esempio, se la chiave di firma utilizza la curva ellittica P-256 con digest SHA256, salvala in un file denominato pem_ec_p256_sha256.pub:

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

Poi, esegui questo comando 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 stringa breve utilizzata localmente dall'interfaccia a riga di comando per identificare questo account nelle chiamate future dei comandi. Tuttavia, tieni presente che, poiché non disponi della chiave privata, non puoi firmare o inviare transazioni.
  • 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 che viene archiviato nel ledger, ma non interpretato in altro modo dal 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.

In questo modo, verrà firmata e inviata una transazione CreateAccount 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 formati di chiave pubblica supportati alternativi, consulta KeyFormat nel riferimento API Universal Ledger.

Elenca gli account gestiti

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

ul-cli accounts list

Esplora 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 comandi secondari per inviare altri tipi di transazioni, ad esempio:

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

Passaggi successivi