Déployer un contrat programmable

Universal Ledger est compatible avec les contrats programmables qui peuvent être déployés dans un réseau pour automatiser et appliquer des accords entre les participants intéressés.

Ce tutoriel explique aux développeurs les étapes nécessaires pour développer, déployer et interagir avec un contrat programmable dans un réseau Universal Ledger.

Avant de commencer

Pour suivre ce tutoriel, vous devez disposer des éléments suivants :

Les rôles Universal Ledger peuvent être attribués à un compte utilisateur lors de sa création par leur gestionnaire de compte, au moment de l'envoi de sa CreateAccount ou ultérieurement via une AddRoles si le compte existe déjà. À des fins d'expérimentation, vous pouvez également utiliser la CLI Universal Ledger pour gérer les comptes.

Configurer votre environnement

Pour simplifier la configuration, ce tutoriel a été écrit pour l'environnement par défaut fourni dans une session Cloud Shell. Vous devrez peut-être modifier ces commandes si vous utilisez un autre environnement.

Le compilateur gculpyc prend le code source écrit dans le langage GCULpy et produit du bytecode pour Universal Ledger.

Exécutez chacune des commandes suivantes pour extraire l'image Docker gculpyc, définir un alias pour exécuter le binaire et confirmer que le binaire fonctionne.

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

Rédiger votre contrat

GCULpy est le langage utilisé pour écrire des contrats pour Universal Ledger. Il s'agit d'un sous-ensemble de Python à typage statique, optimisé pour une logique de contrat claire, auditable et compréhensible. Cette conception donne la priorité à l'écriture de code sécurisé et limite les comportements inattendus ou dangereux. Pour en savoir plus, consultez la documentation de référence sur le langage GCULpy.

Étant donné que GCULpy est un sous-ensemble strict de Python, vous pouvez continuer à utiliser vos environnements de développement intégrés (IDE) préférés, ainsi que vos workflows et pratiques de développement existants.

Par exemple, votre code peut se présenter comme suit :

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

Copiez cet exemple de code et enregistrez-le dans un fichier nommé counter.py.

Tester en local

Dans un avenir proche, les développeurs auront accès à un environnement de simulation local. Fourni dans le cadre du module Python gcul, il est conçu pour fournir les fonctionnalités nécessaires à la simulation native d'un réseau Universal Ledger dans un environnement Python. Vous pourrez ainsi exécuter des contrats en local et écrire des tests unitaires à l'aide de vos frameworks de test préférés, ce qui vous permettra de garantir la fiabilité et l'exactitude de vos contrats avant le déploiement.

Compiler le contrat

Compilez le code source du contrat précédent en bytecode à l'aide de la commande gculpyc suivante :

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

Déployer le contrat

Déployez le contrat sur un réseau Universal Ledger en envoyant une CreateContract signée par un compte utilisateur détenant le ROLE_CONTRACT_CREATOR.

Si vous utilisez la CLI Universal Ledger, vous pouvez le faire en exécutant la commande suivante :

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

Remplacez les éléments suivants :

  • OWNER_ALIAS: alias d'un compte utilisateur avec le rôle ROLE_CONTRACT_CREATOR.

Une fois la transaction finalisée, le résultat de cette commande inclura l'ID du contrat nouvellement déployé. Exemple :

Contract created: 1:CTR:005XvYfiSm3913Jwv4y8HVQucStJ2Ev15Sar6A1kNNX10

Appeler une méthode de contrat

Une fois qu'un contrat est déployé, n'importe quel compte utilisateur avec le ROLE_CONTRACT_PARTICIPANT peut envoyer une InvokeContractMethod transaction pour appeler l'une des méthodes publiques du contrat.

Si vous utilisez la CLI Universal Ledger, vous pouvez le faire en exécutant la commande suivante :

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

Remplacez les éléments suivants :

  • PARTICIPANT_ALIAS: alias d'un compte utilisateur avec le rôle ROLE_CONTRACT_PARTICIPANT.

Lire l'état du contrat

Pour conclure ce tutoriel, vous pouvez envoyer une QueryAccount pour lire et vérifier l'état du contrat stocké dans le registre. Il s'agit de la même méthode API que celle utilisée pour interroger et récupérer les détails de n'importe quel compte Universal Ledger.

À l'aide de la CLI Universal Ledger, vous pouvez exécuter la commande suivante :

ul-cli accounts describe --alias counter-contract

Cela devrait confirmer que la valeur du compteur est désormais définie sur 1, ce qui génère un résultat tel que :

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

  Balances:
    None

Étape suivante