Plutus.V1.Ledger.Api

Table des matières

  1. 📜 Overview

  2. 🔧 Compiler Options, Language Extensions, and Imports

  3. 🗄️ Data Structures and Type Synonyms

    • 🔤 SerializedScript (type)

    • 📊 LedgerPlutusVersion (data)

    • 🔢 ProtocolVersion (data)

    • 🧪 EvaluationError (data)

    • 🔄 VerboseMode (data)

    • 🔧 DefaultMachineParameters (type)

    • 🏗️ ScriptForExecution (newtype)

    • 🏗️ EvaluationContext (data)

  4. ⚙️ Core Functions

    • 📜 builtinsIntroducedIn

    • 🔍 builtinsAvailableIn

    • 🛠️ scriptCBORDecoder

    • ✅ isScriptWellFormed

    • ⚙️ mkTermToEvaluate

    • 🔄 unliftingModeIn

    • 🔧 toMachineParameters

    • 🛠️ mkMachineParametersFor

    • 🏗️ mkEvaluationContext

    • ✔️ assertWellFormedCostModelParams

    • 🚀 evaluateScriptRestricting

    • 🚨 evaluateScriptCounting

  5. 🤝 Typeclass Instances

  6. 📚 Glossary

1. 📜 Overview

Ce module, Plutus.ApiCommon, fournit des types et fonctions communs partagés à travers l’API du ledger Plutus :

  • Configure les ticks du simplificateur GHC pour supporter une optimisation intensive.

  • Définit des synonymes de type clés (SerializedScript, LogOutput) et des types de données (LedgerPlutusVersion, ProtocolVersion, etc.).

  • Gère la disponibilité des fonctions intégrées (builtins) en fonction de la version du protocole.

  • Implemente la décodification des scripts, la vérification de leur validité, et l’évaluation sous contraintes de coûts.

  • Construit et met en cache les contextes d’évaluation pour différents modes d’unlifting.

Tout au long du module, vous verrez des exemples de définitions de type, data, newtype, ainsi que des fonctions utilitaires annotées INLINABLE ou INLINE pour les performances on-chain.

2. 🔧 Compiler Options, Language Extensions, and Imports

OPTIONS_GHC : augmente le budget de tick du simplificateur pour éviter les interruptions lors de l’optimisation de grands modules.

Aucune pragma LANGUAGE explicite à part les pragmas INLINE/INLINABLE utilisés sur les fonctions.

Utilisation intensive des imports qualifiés (UPLC, CBOR) pour éviter les collisions de noms.

3. 🗄️ Data Structures and Type Synonyms

3.1 🔤 SerializedScript (type)

Entrées/Sorties : exactement ShortByteString, renommé pour plus de clarté.

Exemple d’utilisation :

let raw :: SerializedScript = toShort someLazyBS

3.2 📊 LedgerPlutusVersion (data)

Constructeurs : PlutusV1, PlutusV2

Exemple :

let lv = PlutusV2

3.3 🔢 ProtocolVersion (data)

Champs :

  • pvMajor : version majeure (par ex. 7)

  • pvMinor : version mineure (par ex. 0)

Exemple :

let pv = ProtocolVersion 7 0

3.4 🧪 EvaluationError (data)

Variantes : plusieurs sortes d’erreurs lors du décodage ou de l’évaluation.

Exemple :

let err = CodecError someFailure

3.5 🔄 VerboseMode (data)

Utilisation : permet d’activer ou de désactiver les logs dans les fonctions d’évaluation.

Exemple :

let mode = Verbose

3.6 🔧 DefaultMachineParameters (type)

Alias : pour le bundle de paramètres du moteur CEK.

3.7 🏗️ ScriptForExecution (newtype)

Emballage : un programme UPLC spécialisé pour l’exécution.

Exemple :

let exec = ScriptForExecution someProgram

3.8 🏗️ EvaluationContext (data)

Champs : ensembles de paramètres séparés pour l’unlifting immédiat et différé.

Exemple :

let ctx = EvaluationContext params1 params2

4. ⚙️ Core Functions

4.1 📜 builtinsIntroducedIn

Entrées : aucune (constante)

Traitement : fait la correspondance des versions à l’ensemble des builtins.

Sortie : map des builtins introduits.

Exemple :

Map.lookup (PlutusV1, ProtocolVersion 5 0) builtinsIntroducedIn

4.2 🔍 builtinsAvailableIn

Entrées : version du ledger, version du protocole

Traitement : filtre les entrées de la map <= aux entrées données, agrège les ensembles.

Sortie : ensemble des builtins disponibles.

Exemple :

builtinsAvailableIn PlutusV2 (ProtocolVersion 7 0)

4.3 🛠️ scriptCBORDecoder

Entrées : versions

Traitement : construit un décodeur Flat avec les bons builtins, décode vers ScriptForExecution.

Sortie : CBOR.Decoder s ScriptForExecution

Exemple :

CBOR.deserialiseFromBytes (scriptCBORDecoder PlutusV1 (ProtocolVersion 5 0)) bytes

4.4 ✅ isScriptWellFormed

Entrées : versions, bytes bruts

Traitement : essaie de décoder, applique isRight.

Sortie : Booléen

Exemple :

isScriptWellFormed PlutusV2 (ProtocolVersion 7 0) rawScript

4.5 ⚙️ mkTermToEvaluate

Entrées : versions, script sérialisé, arguments data

Traitement : décode via scriptCBORDecoder, vérifie le tag de version, applique les constantes, vérifie la portée.

Sortie : terme UPLC prêt pour la machine CEK

Exemple :

runExceptT $ mkTermToEvaluate PlutusV1 v1 raw args

4.6 🔄 unliftingModeIn

Entrée : version du protocole

Traitement : comparaison simple

Sortie : UnliftingMode

Exemple :

unliftingModeIn (ProtocolVersion 6 0) == UnliftingImmediate

4.7 🔧 toMachineParameters

Entrées : version du protocole, contexte

Traitement : sélectionne le champ adéquat

Sortie : paramètres

Exemple :

toMachineParameters vctxPV ctx

4.8 🛠️ mkMachineParametersFor

Entrées : mode d’unlifting, paramètres du cost model

Traitement : applique et inline mkMachineParameters

Sortie : DefaultMachineParameters

4.9 🏗️ mkEvaluationContext

Entrée : paramètres du cost model

Traitement : construit les deux ensembles de paramètres

Sortie : EvaluationContext

4.10 ✔️ assertWellFormedCostModelParams

Entrée : paramètres du cost model

Traitement : vérifie le modèle de coût par défaut

Sortie : () ou erreur

4.11 🚀 evaluateScriptRestricting

Entrées : versions, mode verbeux, contexte, budget, script, args

Traitement : mkTermToEvaluate, lance CEK avec budget restrictif, collecte les logs

Sortie : logs et soit erreur soit budget restant

Exemple :

evaluateScriptRestricting PlutusV2 v7 Verbose ctx budget raw args

4.12 🚨 evaluateScriptCounting

Entrées : versions, mode verbeux, contexte, script, args

Traitement : mkTermToEvaluate, lance CEK en mode counting, collecte les logs

Sortie : logs et soit erreur soit budget utilisé

5. 🤝 Typeclass Instances

L’implémentation explicite de Ord correspond à l’ordre dérivé.

L’instance Pretty pour ProtocolVersion affiche la version sous la forme "7.0".

L’instance Pretty pour EvaluationError fournit des messages d’erreur lisibles pour l’utilisateur via Prettyprinter.

6. 📚 Glossary

  • ShortByteString : bytestring compact optimisé pour les petites données.

  • CBOR Decoder : parseur pour les données encodées en CBOR.

  • ExBudget : budget de ressources pour l’exécution d’un script.

  • CEK machine : machine abstraite implémentant l’évaluation Plutus Core.

  • UnliftingMode : stratégie pour convertir les constantes on-chain en Haskell.

  • INLINE / INLINABLE : indications à GHC pour l’inlining, pour optimiser les performances.

  • NoThunks : classe qui prévient la présence de thunks inattendus dans les données.

  • CostModelParams : map associant le coût des builtins à des valeurs entières.

  • MonadError : monade supportant la gestion des erreurs.

PreviousPlutus.V1.Ledger.AddressNextPlutus.V1.Ledger.Bytes

Last updated