Plutus.V1.Ledger.Bytes

Table des matières

1. 📜 Overview

2. 🔧 LANGUAGE EXTENSIONS AND IMPORTS

3. 🗄️ Data Structures and Type Synonyms

   • 🏗️ LedgerBytes (newtype)

4. ⚙️ Functions

   • 🧩 fromHex

   • 📦 bytes

   • 🔙 fromBytes

   • 🔤 encodeByteString

5. 🤝 Typeclass Instances

6. 📚 Glossary

---

1 📜 Overview

Le module Plutus.V1.Ledger.Bytes fournit des utilitaires pour travailler avec des séquences d’octets brutes dans du code Plutus, aussi bien on-chain qu’off-chain :

• Définit un wrapper LedgerBytes autour de BuiltinByteString, sans coût additionnel.

• Permet de parser des littéraux hexadécimaux en LedgerBytes.

• Convertit entre ByteString Haskell et LedgerBytes.

• Encode des octets en texte hexadécimal pour l’affichage.

• Dérive des instances pour la sérialisation on-chain et le pretty printing.

Ce tutoriel détaille les pragmas du langage/imports, le newtype, les fonctions principales, les instances, et finit par un glossaire.

---

2 🔧 LANGUAGE EXTENSIONS AND IMPORTS

Pragmas LANGUAGE :

DataKinds, DeriveAnyClass, DeriveGeneric, DerivingStrategies, DerivingVia, GeneralizedNewtypeDeriving, FlexibleContexts, FlexibleInstances, OverloadedStrings, TemplateHaskell, TypeApplications

L’option -Wno-orphans supprime les avertissements pour les instances orphelines.

OPTIONS_GHC : aucune alerte additionnelle pour les instances orphelines.

Imports principaux :

• ByteString et Base16 pour les opérations sur les bytes bruts et hexadécimaux

• Data.Word pour la manipulation de Word8

• PlutusTx, PlutusTx.Lift, et PlutusTx.Prelude pour le lifting et la manipulation d’octets on-chain

• Prettyprinter.Extras pour dériver Pretty via PrettyShow

---

3 🗄️ Data Structures and Type Synonyms

3.1 🏗️ LedgerBytes (newtype)

Entrées : encapsule un BuiltinByteString (type on-chain)

Dérivations :

• Eq, Ord, Generic via stock

• newtype deriving pour les conversions on-chain ToData, FromData, égalité, etc.

• NFData pour l’évaluation profonde

• Pretty via PrettyShow générique pour l’affichage

Exemple :

let lb = LedgerBytes (P.toBuiltin someBS)
print lb  -- utilise PrettyShow pour afficher en hexadécimal

---

4 ⚙️ Functions

4.1 🧩 fromHex

Entrées : ByteString brut représentant des chiffres hexadécimaux

Traitement :

• Découpe la chaîne en paires de chiffres hexadécimaux (“nybbles”)

• Convertit chaque paire en Word8

• Emballe le tout en ByteString puis en LedgerBytes

Sortie : Either String LedgerBytes

Exemples :

fromHex "a6b4" == Right (LedgerBytes <builtin 0xa6b4>)
fromHex "zz" == Left "not a hexit: z"

---

4.2 📦 bytes

Entrée : LedgerBytes

Traitement : désemballe et convertit depuis BuiltinByteString

Sortie : ByteString Haskell

Exemple :

bytes lb == originalBS

---

4.3 🔙 fromBytes

Entrées/Sorties : conversion sans coût vers la forme on-chain

Exemple :

fromBytes someBS == LedgerBytes (P.toBuiltin someBS)

---

4.4 🔤 encodeByteString

Entrée : ByteString brut

Traitement : encode en Base16, puis décode en texte UTF8

Sortie : texte hexadécimal (Text)

Exemple :

encodeByteString "\x0a\x6b" == "0a6b"

---

5 🤝 Typeclass Instances

Permet d’interpréter des littéraux de chaînes (ex: "a6b4") directement comme des LedgerBytes.

Rend LedgerBytes affichable sous forme de chaîne hexadécimale pour le debug et les logs.

Génère une instance Lift pour l’inclusion on-chain dans du code PlutusTx grâce à Template Haskell.

---

6 📚 Glossary

• BuiltinByteString : représentation Plutus on-chain des octets bruts.

• Word8 : entier non signé sur 8 bits.

• Hexit : un chiffre hexadécimal (0–9, a–f).

• Base16 : encodage hexadécimal pour ByteString.

• unsafeFromEither : utilitaire qui déclenche une erreur si le Either est Left.

• PrettyShow : dérive Pretty à partir de l’implémentation Show.

• makeLift : Template Haskell pour le lifting de valeurs on-chain.

---