Plutus : Slot and Time Ranges

Here is the updated tutorial with:

📘 Plutus : Slot and Time Ranges

📑 Table of Contents

  1. Introduction

  2. Slot vs POSIXTime

  3. POSIXTimeRange and Interval

  4. ScriptContext Time Checks

  5. Off-Chain Slot Conversions

  6. Full Example: Deadline Validator

  7. Glossary

  8. References

1. 🧭 Introduction

Time-sensitive logic is common in Plutus smart contracts. You often need to:

  • Enforce deadlines

  • Allow scheduled unlocks

  • Handle auction close times

Plutus uses POSIXTime and Interval POSIXTime (a.k.a. POSIXTimeRange) to model time. You do not check Slot directly on-chain—it's for off-chain conversion.

2. 🧮 Slot vs POSIXTime

Term
Description
Used In

Slot

Blockchain slot number (SlotNo)

Off-chain

POSIXTime

Unix time in milliseconds

On-chain

To use real time on-chain, you write Plutus validators in terms of POSIXTime. Slot-related logic is done off-chain.

📄 Off-chain conversion: Ledger.TimeSlot

slotToBeginPOSIXTime :: Slot -> POSIXTime

3. 📐 POSIXTimeRange and Interval

📌 Definition

On-chain time constraints are represented as:

type POSIXTimeRange = Interval POSIXTime

This lets you express “when” a transaction is valid.

📄 Docs:

🛠 Common Constructors

Constructor
Meaning

always

Infinite range (no bounds)

from t

Time ≥ t

to t

Time ≤ t

interval a b

Between a and b inclusive

🧪 Example

deadline :: POSIXTime
deadline = 1660000000

validRange = to deadline  -- Valid before or at the deadline

4. 🧾 ScriptContext Time Checks

The transaction’s valid range is pulled from the context:

txInfoValidRange :: TxInfo -> POSIXTimeRange
scriptContextTxInfo :: ScriptContext -> TxInfo

✅ Check if TX is before deadline:

{-# INLINABLE validateBeforeDeadline #-}
validateBeforeDeadline :: POSIXTime -> () -> ScriptContext -> Bool
validateBeforeDeadline deadline _ ctx =
    contains (to deadline) (txInfoValidRange $ scriptContextTxInfo ctx)

5. 🔁 Off-Chain Slot Conversions

To convert between slot numbers and real time (POSIX), use:

slotToPOSIXTime      :: Slot -> POSIXTime
slotToBeginPOSIXTime :: Slot -> POSIXTime
slotToEndPOSIXTime   :: Slot -> POSIXTime

This is useful when:

  • You know the deadline in slots

  • You're building the transaction off-chain

📄 Module: Ledger.TimeSlot

6. ✅ Full Example: Validator with Deadline

{-# INLINABLE mkValidator #-}
mkValidator :: POSIXTime -> () -> ScriptContext -> Bool
mkValidator deadline _ ctx =
    traceIfFalse "deadline passed" withinRange
  where
    info = scriptContextTxInfo ctx
    withinRange = contains (to deadline) (txInfoValidRange info)

📌 This validator:

  • Accepts a POSIXTime as deadline

  • Fails if the transaction is after that time

7. 📚 Glossary

Term
Meaning

Slot

A unit of blockchain time (e.g., one block every 1 sec)

POSIXTime

Unix time in milliseconds (standard time format)

Interval a

A range with lower and upper bounds of type a

POSIXTimeRange

A type alias: Interval POSIXTime

ScriptContext

All on-chain data available to the validator

TxInfo

Contains TX metadata, inputs, outputs, range, signers, etc.

txInfoValidRange

Time range the transaction declares itself valid for

contains

Checks whether one interval is completely within another

8. 🔗 References

PreviousPlutus.V1.Ledger.EvaluationContextNextPlutus.V1.Ledger.Examples

Last updated