# 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 :

```haskell
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 :

```haskell
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 :

```haskell
bytes lb == originalBS
```

***

#### 4.3 🔙 fromBytes

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

Exemple :

```haskell
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 :

```haskell
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.

***
