Plutus: Ledger.Tx.Constraints

Plutus: Ledger.Tx.Constraints

📑 Table of Contents

  1. 🚀 Introduction

  2. 🧩 Defining Constraints

  3. 💳 Must-Pay Constraints for Specific Types of Addresses

  4. 🔧 Off-Chain Only Constraints

  5. 🔍 Queries on Constraints

  6. 🏗️ Off-Chain Transaction Generation

  7. 🔗 Combining Multiple Typed Scripts in One Transaction

  8. 📦 Lookups

  9. ⚠️ Deprecated Functions

  10. 📘 Glossary of Terms

1. 🚀 Introduction

The Ledger.Tx.Constraints module defines transaction constraints (TxConstraints), which are declarative rules for transactions.

  • Off-chain (wallet/backend): Used to build transactions (mkTx).

  • On-chain (validator): Used to verify that transactions meet rules (checkScriptContext).

This helps ensure correctness and reduces boilerplate transaction logic.

2. 🧩 Defining Constraints

Constraints express conditions like payments, signatures, datums, and validity ranges.

Examples:

  • mustPayToTheScriptWithDatumHash

  • mustSpendAtLeast

  • mustProduceAtLeast

  • mustIncludeDatumInTx

👉 These can be combined into a TxConstraints set.

3. 💳 Must-Pay Constraints for Specific Types of Addresses

🔹 Public Key Constraints

  • mustPayToPubKey

  • mustPayToPubKeyWithDatumHash

  • mustPayToPubKeyWithInlineDatum

🔹 Script Constraints

  • mustPayToOtherScriptWithDatumHash

  • mustPayToOtherScriptWithInlineDatum

🔹 Reference Script Constraints

  • mustPayToAddressWithReferenceScript

  • mustPayToAddressWithReferenceValidator

These ensure correct value locking at addresses.

4. 🔧 Off-Chain Only Constraints

Used only while constructing transactions:

  • spendUtxosFromPlutusV1Script

  • spendUtxosFromTheScript

  • spendUtxosFromPlutusV2Script

They help collect UTxOs from validators with appropriate redeemers.

5. 🔍 Queries on Constraints

Check feasibility of constraints:

  • isSatisfiable – is the constraint set achievable?

  • modifiesUtxoSet – must any satisfying transaction change the UTxO set?

Useful for contract debugging.

6. 🏗️ Off-Chain Transaction Generation

🔹 Unbalanced Transactions

Constraints produce an UnbalancedTx, which must be balanced & signed.

🔹 mkTx Function

mkTx :: Params -> ScriptLookups a 
     -> TxConstraints (RedeemerType a) (DatumType a) 
     -> Either MkTxError UnbalancedTx

🔹 Errors

Possible errors:

  • TxOutRefNotFound

  • DatumNotFound

  • DeclaredInputMismatch

7. 🔗 Combining Multiple Typed Scripts in One Transaction

SomeLookupsAndConstraints lets you merge multiple constraint sets.

  • mkSomeTx – builds a multi-script transaction.

  • mkTxWithParams – same as mkTx with parameters.

👉 Enables cross-contract workflows.

8. 📦 Lookups

ScriptLookups provide context:

  • UTxOs → unspentOutputs

  • Scripts → otherScript, plutusV2OtherScript

  • Datums → otherData

  • Keys → paymentPubKeyHash

Lookups link abstract constraints with actual ledger data.

9. ⚠️ Deprecated Functions

Old functions (to avoid):

  • mustPayToTheScript → use mustPayToTheScriptWithDatumHash

  • mustPayToAddressWithDatum → use mustPayToAddressWithDatumHash

  • mustValidateIn → use mustValidateInTimeRange

✅ Always use updated versions.

10. 📘 Glossary of Terms

  • TxConstraint – A single transaction rule.

  • TxConstraints – A collection of multiple constraints.

  • Datum – Data attached to outputs.

  • Redeemer – Data used when spending outputs.

  • UTxO – Unspent transaction output.

  • ScriptLookups – Context for resolving constraints.

  • UnbalancedTx – Draft transaction before balancing.

  • Validity Interval – Slot/time range when a tx is valid.

  • PaymentPubKeyHash – Identifies a wallet.

  • Minting Policy – Script controlling token mint/burn.

PreviousPlinth/PlutusNextPlutus.V1.Ledger.Address

Last updated