Esegui il deployment di un contratto programmabile

Il Universal Ledger supporta contratti programmabili che possono essere implementati in una rete per automatizzare e far rispettare gli accordi tra i partecipanti interessati.

Questo tutorial mostra agli sviluppatori i passaggi necessari per sviluppare, eseguire il deployment e interagire con un contratto programmabile in una rete Universal Ledger.

Prima di iniziare

Per completare questo tutorial, avrai bisogno di:

  • Nella console Google Cloud , attiva Cloud Shell.

    Attiva Cloud Shell

  • Un account utente Universal Ledger con ROLE_CONTRACT_CREATOR. Questo account diventerà il proprietario del contratto.

  • Uno o più account utente Universal Ledger con il ROLE_CONTRACT_PARTICIPANT. Può essere lo stesso account del proprietario del contratto.

  • (Facoltativo) Configura la CLI Universal Ledger per poter firmare e inviare transazioni per conto di questi account utente.

I ruoli Universal Ledger possono essere assegnati a un account utente al momento della creazione da parte del suo Account Manager, quando viene inviata la transazione CreateAccount o modificati in un secondo momento tramite una transazione AddRoles se l'account esiste già. A scopo sperimentale, puoi anche utilizzare la CLI di Universal Ledger per gestire gli account.

Configura l'ambiente

Per semplificare la configurazione, questo tutorial è stato scritto per l'ambiente predefinito fornito in una sessione Cloud Shell. Potresti dover modificare questi comandi se utilizzi un ambiente diverso.

Il compilatore gculpyc prende il codice sorgente scritto nel linguaggio GCULpy e produce bytecode per il Universal Ledger.

Esegui ciascuno dei seguenti comandi per estrarre l'immagine Docker gculpyc, definisci un alias per l'esecuzione del file binario e verifica che funzioni.

docker pull us-docker.pkg.dev/gcul-artifacts/images/client/gculpyc:preview
alias gculpyc="docker run --rm -i --user $(id -u):$(id -g) \
    --volume .:/workspace --workdir /workspace \
    us-docker.pkg.dev/gcul-artifacts/images/client/gculpyc:preview"
gculpyc --help

Scrivere il contratto

GCULpy è il linguaggio utilizzato per scrivere i contratti per il Universal Ledger. Si tratta di un sottoinsieme di Python con tipizzazione statica, ottimizzato per una logica contrattuale chiara, verificabile e comprensibile. Questo design dà la priorità alla scrittura di codice sicuro e limita comportamenti imprevisti o non sicuri. Per maggiori dettagli, consulta il riferimento al linguaggio GCULpy.

Poiché GCULpy è un sottoinsieme rigoroso di Python, puoi continuare a utilizzare gli ambienti di sviluppo integrati (IDE) che preferisci insieme ai tuoi workflow e alle tue pratiche di sviluppo esistenti.

Ad esempio, il codice potrebbe avere il seguente aspetto:

import gcul

class Counter(gcul.Contract):
    """Example contract implementing a counter."""

    value: int

    def increment(self) -> None:
        """Increments the counter value by 1."""
        self.value += 1

Copia questo codice campione e salvalo in un file denominato counter.py.

Testare localmente

Nel prossimo futuro, gli sviluppatori avranno accesso a un ambiente di simulazione locale. Fornito come parte del modulo Python gcul, è progettato per fornire le funzionalità necessarie per simulare in modo nativo una rete Universal Ledger all'interno di un ambiente Python. In questo modo, potrai eseguire i contratti localmente e scrivere unit test utilizzando i framework di test che preferisci, garantendo l'affidabilità e la correttezza dei contratti prima del deployment.

Compila il contratto

Compila il codice sorgente del contratto precedente in bytecode utilizzando il seguente comando gculpyc:

gculpyc --source_file counter.py --output_file counter.bin

Esegui il deployment del contratto

Esegui il deployment del contratto in una rete Universal Ledger inviando una transazione CreateContract firmata da un account utente che detiene ROLE_CONTRACT_CREATOR.

Se utilizzi la CLI Universal Ledger, puoi farlo eseguendo il comando:

ul-cli contracts create \
    --alias counter-contract \
    --sender OWNER_ALIAS \
    counter.bin

Sostituisci quanto segue:

  • OWNER_ALIAS: l'alias di un account utente con il ROLE_CONTRACT_CREATOR.

Una volta finalizzata la transazione, l'output di questo comando includerà l'ID del contratto appena implementato. Ad esempio:

Contract created: 1:CTR:005XvYfiSm3913Jwv4y8HVQucStJ2Ev15Sar6A1kNNX10

Richiamare un metodo di contratto

Una volta distribuito un contratto, qualsiasi account utente con il ROLE_CONTRACT_PARTICIPANT può inviare una transazione InvokeContractMethod per richiamare uno qualsiasi dei metodi pubblici del contratto.

Se utilizzi la CLI Universal Ledger, puoi farlo eseguendo il comando:

ul-cli contracts invoke \
    --alias counter-contract \
    --method-name increment \
    --sender PARTICIPANT_ALIAS

Sostituisci quanto segue:

  • PARTICIPANT_ALIAS: l'alias di un account utente con il ROLE_CONTRACT_PARTICIPANT.

Leggere lo stato del contratto

Per concludere questo tutorial, puoi inviare una richiesta QueryAccount per leggere e verificare lo stato del contratto memorizzato nel ledger. Si tratta dello stesso metodo API utilizzato per eseguire query e recuperare i dettagli di qualsiasi account Universal Ledger.

Utilizzando l'interfaccia a riga di comando Universal Ledger, puoi eseguire:

ul-cli accounts describe --alias counter-contract

In questo modo, dovresti confermare che il valore del contatore è ora impostato su 1, producendo un output come:

Account: 1:CTR:005XvYfiSm3913Jwv4y8HVQucStJ2Ev15Sar6A1kNNX10
Contract account details:
  Owner: 1:USR:XCL:022uF6cVkTJBaa6pViqTuYqP4455jnRbRc4bWannZGg0b
  Contract fields:
    value: int64_value:1

  Balances:
    None

Passaggi successivi