Déployer un contrat programmable

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

Ce tutoriel présente 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 aurez besoin des éléments suivants :

  • Dans la console Google Cloud , activez Cloud Shell.

    Activer Cloud Shell

  • Un compte utilisateur Universal Ledger avec le rôle ROLE_CONTRACT_CREATOR. Ce compte deviendra le titulaire du contrat.

  • Un ou plusieurs comptes utilisateur Universal Ledger avec le rôle ROLE_CONTRACT_PARTICIPANT. Il peut s'agir du même compte que celui du propriétaire du contrat.

  • (Facultatif) Configurez la CLI Universal Ledger pour pouvoir signer et envoyer des transactions au nom de ces comptes utilisateur.

Les rôles Universal Ledger peuvent être attribués à un compte utilisateur lors de sa création par son gestionnaire de compte, au moment de l'envoi de sa transaction CreateAccount, ou modifiés ultérieurement via une transaction 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 un bytecode pour le Universal Ledger.

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

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

Rédiger votre contrat

GCULpy est le langage utilisé pour rédiger des contrats pour le Universal Ledger. Il s'agit d'un sous-ensemble de Python typé de manière statique, optimisé pour une logique de contrat claire, auditable et compréhensible. Cette conception privilégie 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.

Comme 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 pourrait ressembler à ceci :

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 module Python gcul, il est conçu pour fournir les fonctionnalités nécessaires pour simuler de manière native un réseau Universal Ledger dans un environnement Python. Vous pourrez ainsi exécuter des contrats localement 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 leur 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 transaction CreateContract signée par un compte utilisateur détenant le ROLE_CONTRACT_CREATOR.

Si vous utilisez la CLI Universal Ledger, vous pouvez exécuter 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 inclut 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é, tout compte utilisateur disposant de l'autorisation ROLE_CONTRACT_PARTICIPANT peut envoyer une transaction InvokeContractMethod pour appeler l'une des méthodes publiques du contrat.

Si vous utilisez la CLI Universal Ledger, vous pouvez exécuter 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 requête 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 produit 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

Étapes suivantes