Esegui il deployment di un contratto programmabile

Universal Ledger supporta contratti programmabili che possono essere implementati in una rete per automatizzare e applicare 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 il ruolo ROLE_CONTRACT_CREATOR. Questo account diventerà il proprietario del contratto.

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

  • Facoltativamente, configura l'interfaccia a riga di comando di Universal Ledger per poter firmare e inviare transazioni per conto di questi account utente.

I ruoli di Universal Ledger possono essere assegnati a un account utente quando viene creato dall'account manager, al momento dell'invio della transazione CreateAccount, oppure modificati in un secondo momento tramite una transazione AddRoles se l'account esiste già. A scopo di sperimentazione, puoi anche utilizzare l'interfaccia a riga di comando 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 di Cloud Shell. Se utilizzi un ambiente diverso, potresti dover modificare questi comandi.

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

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

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

Scrivi il tuo contratto

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

Poiché GCULpy è un sottoinsieme rigoroso di Python, puoi continuare a utilizzare i tuoi ambienti di sviluppo integrati (IDE) preferiti insieme ai flussi di lavoro e alle 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.

Esegui test in locale

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 test delle unità 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 su una rete Universal Ledger inviando una transazione CreateContract firmata da un account utente che detiene ROLE_CONTRACT_CREATOR.

Se utilizzi l'interfaccia a riga di comando di Universal Ledger, puoi farlo eseguendo il comando:

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

Sostituisci quanto segue:

  • OWNER_ALIAS ROLE_CONTRACT_CREATOR

Al termine della transazione, l'output di questo comando includerà l'ID del contratto di cui è stato appena eseguito il deployment. Ad esempio:

Contract created: 1:CTR:005XvYfiSm3913Jwv4y8HVQucStJ2Ev15Sar6A1kNNX10

Richiama un metodo del contratto

Una volta eseguito il deployment di un contratto, qualsiasi account utente con il ruolo ROLE_CONTRACT_PARTICIPANT può inviare una transazione InvokeContractMethod per richiamare uno dei metodi pubblici nel contratto.

Se utilizzi l'interfaccia a riga di comando di 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 ROLE_CONTRACT_PARTICIPANT

Leggi lo stato del contratto

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

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

ul-cli accounts describe --alias counter-contract

Questo dovrebbe 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