PlutusTx.Prelude

📌 Table of Contents

1. 🔍 What & Why — PlutusTx.Prelude

2. 🧠 Typeclass Landscape

3. 🧩 Monads — Sequencing Computations

4. 🔧 Standard Functions & Tuples

5. 🛠️ Tracing & Errors

6. ☑️ Unit Type

7. ✍️ Strings — BuiltinString

8. ✅ Booleans

9. 🔢 Integers

10. 🧭 Maybe & Either

11. 📦 ByteStrings — BuiltinByteString

12. 🔐 Cryptography: Hashes & Signatures

13. 🧱 Builtin Types: Data, List, Pair

14. 🔄 To/From Data Conversion

15. ➗ Rational Numbers

16. 🧮 BLS12-381 Primitives

17. 🔁 Builtin ↔ High-Level Conversion

18. 🧪 Code Examples

19. ✅ Best Practices

20. 📘 Glossary of Terms

---

1️⃣ 🔍 What & Why — PlutusTx.Prelude

PlutusTx.Prelude is a safe, deterministic alternative to Haskell's standard Prelude, designed for Plutus on-chain code.

✅ You must use it for code that’s compiled with the Plutus Tx compiler:

{-# LANGUAGE NoImplicitPrelude #-}
import PlutusTx.Prelude

---

2️⃣ 🧠 Typeclass Landscape

These typeclasses are available in PlutusTx.Prelude:

• Equality & Ordering: Eq, Ord, Enum

• Algebraic: Semigroup, Monoid, Numeric, Lattice

• Functional: Function, Functor, Applicative, Monad

No IO, no laziness, and only total, deterministic behavior.

---

3️⃣ 🧩 Monads — Sequencing Computations

Operator	Purpose
(>>=)	Bind with result
(=<<)	Flipped bind
(>>)	Sequence without result
return	Wrap value in monad

Example:

do a <- getValue
   useValue a
-- is same as:
getValue >>= useValue

---

4️⃣ 🔧 Standard Functions & Tuples

Tuples, pairs, and general-purpose functions are exported from PlutusTx.Base. Use only those exposed by PlutusTx.Prelude.

---

5️⃣ 🛠️ Tracing & Errors

Function	Behavior
error	Fails validation
check	Aborts if input is False

{-# INLINABLE isPositive #-}
isPositive :: Integer -> BuiltinUnit
isPositive n = check (n > 0)

---

6️⃣ ☑️ Unit Type

• BuiltinUnit = on-chain equivalent of ()

• Common return type for validations

---

7️⃣ ✍️ Strings — BuiltinString

Function	Description
emptyString	""
appendString	Concatenation
equalsString	Equality check
encodeUtf8 / decodeUtf8	Convert to/from BuiltinByteString

⚠️ Use BuiltinString, not Text or String.

---

8️⃣ ✅ Booleans

Works just like Haskell:

not :: Bool -> Bool
(&&), (||) :: Bool -> Bool -> Bool

---

9️⃣ 🔢 Integers

Only Integer (arbitrary precision) is supported:

➗ Division Functions

Function	Behavior
divide	Floor division
modulo	Positive modulo
quotient	Toward-zero division
remainder	Sign of dividend

Other

even, odd :: Integer -> Bool
expMod    :: Integer -> Integer -> Integer -> Integer

---

🔟 🧭 Maybe & Either

Use:

• Maybe for optional values (e.g., Just, Nothing)

• Either for tagged error types (Left, Right)

Both are supported on-chain.

---

1️⃣1️⃣ 📦 ByteStrings — BuiltinByteString

🧰 General

Function	Description
appendByteString	Concatenate
consByteString	Add byte at front
sliceByteString	Substring by index/range
indexByteString	Byte at index
lengthOfByteString	Length of byte string

🧠 Bit Ops (CIP-122/123)

• andByteString, orByteString, xorByteString

• readBit, writeBits, replicateByte

• countSetBits, findFirstSetBit

• rotateByteString, shiftByteString

---

1️⃣2️⃣ 🔐 Cryptography: Hashes & Signatures

🔑 Hash Functions

sha2_256, sha3_256, blake2b_224, blake2b_256
keccak_256, ripemd_160 :: BuiltinByteString -> BuiltinByteString

✍️ Signature Verification

verifyEd25519Signature
verifyEcdsaSecp256k1Signature
verifySchnorrSecp256k1Signature

⚠️ Validate formats: byte length, endianess, and encoding.

---

1️⃣3️⃣ 🧱 Builtin Types

Type	Description
BuiltinData	Opaque on-chain Data
BuiltinList	Optimized list
BuiltinPair	Tuple-type

---

1️⃣4️⃣ 🔄 To/From Data Conversion

Class	Function	Purpose
ToData	toBuiltinData	Serialize to Data
FromData	fromBuiltinData → Maybe	Safe deserialize
UnsafeFromData	unsafeFromBuiltinData	Fast, unsafe decode

✅ Use FromData for safety. ⚠️ Use UnsafeFromData only when input is guaranteed.

---

1️⃣5️⃣ ➗ Rational Numbers

Function	Description
ratio	Safe constructor (Maybe Rational)
unsafeRatio	Constructor (throws on /0)
fromInteger	Converts Integer to Rational
round	Rounds to nearest Integer

---

1️⃣6️⃣ 🧮 BLS12-381 Primitives

Use for pairing-based crypto.

Type	Usage
BuiltinBLS12_381_G1_Element	Group G1
BuiltinBLS12_381_G2_Element	Group G2
BuiltinBLS12_381_MlResult	Miller loop result

Use:

• bls12_381_G?_scalarMul, add, neg

• bls12_381_hashToGroup, compress, uncompress

• bls12_381_finalVerify to validate pairings.

---

1️⃣7️⃣ 🔁 Builtin ↔ High-Level Conversion

🧰 Helpers

fromBuiltin, toBuiltin
fromOpaque, toOpaque

🧮 CIP-121 (Integer ↔ ByteString)

integerToByteString :: ByteOrder -> Integer -> Integer -> BuiltinByteString
byteStringToInteger :: ByteOrder -> BuiltinByteString -> Integer

---

1️⃣8️⃣ 🧪 Code Examples

{-# INLINABLE validatePositive #-}
validatePositive :: Integer -> BuiltinUnit
validatePositive n = check (n > 0)

{-# INLINABLE decodeAmount #-}
decodeAmount :: BuiltinData -> Maybe Integer
decodeAmount d = fromBuiltinData d

{-# INLINABLE maskedBytes #-}
maskedBytes :: BuiltinByteString -> BuiltinByteString
maskedBytes bs = andByteString False bs (replicateByte 32 0xff)

---

1️⃣9️⃣ ✅ Best Practices

Do ✅	Don’t 🚫
Use PlutusTx.Prelude	Import default Prelude
Prefer FromData	Blindly use UnsafeFromData
Use Builtin* types	Use standard types like Text, Int
Add NoImplicitPrelude	Mix Prelude and Plutus Prelude
Validate bitwise lengths	Assume formatting is correct

---

2️⃣0️⃣ 📘 Glossary of Terms

Term	Definition
Builtin*	Types used on-chain in Plutus (e.g. BuiltinString, BuiltinData)
check	Aborts execution when condition is False
error	Immediate validation failure
CIP-121	Spec for Integer <-> ByteString encoding
CIP-122/123	Bit-level and byte-wise logic specs
FromData / ToData	Safe serialization/deserialization to/from on-chain Data
UnsafeFromData	Faster decode, unsafe if shape is wrong
MlResult	Miller loop result for BLS12-381
NoImplicitPrelude	Compiler flag to disable default Prelude import
PlutusTx	Module for writing Template Haskell for Plutus Core
Lift	Typeclass to lift Haskell values into Plutus Core

---