Plutus 102: Datum and Redeemer

Plutus validators are functions that have three inputs and return a boolean. The three inputs are the datum, the redeemer and the script context.

validator :: Datum -> Redeemer -> ScriptCxt -> Bool

The script context is the easiest to understand. As we covered in Plutus 101, smart contracts are executed implicitly when UTxOs at script addresses are used as inputs in a transactions. The script context provides information about the pending transaction, along with which input triggered the validation.

The datum and redeemer are user input, but crucially they are different users' input. Somewhat confusingly, they are provided by the same user.

If you remember from Plutus 101, there are two types of users for a Plutus segue. The user that creates the first transaction is the "locker". The user the creates the second transaction is the "unlocker". The datum is the locker's input. The redeemer is the unlocker's input.

Using these different names, we get a somewhat clearer sense of how validators work:

validator :: LockerInput -> UnlockerInput -> ScriptCxt -> Bool

To imagine how these inputs are used, consider a swap situation. The locker, locks assets at a script address and provides a datum that describes how they would like to be paid. Then the unlocker uses the UTxO as input, and passes in a redeemer explaining how they would like to paid. The validator looks at the two users inputs and the script context to make sure the inputs and outputs are consistent with what is requested by the users. If they are, it returns "true" and performs the swap. Otherwise the transaction fails.

The Rub

This conceptual understanding of datum as the locker's input and the redeemer as unlocker's input, is very useful when designing validators. However, it is not how Plutus transactions are actually constructed. In reality, the locker sends a datum hash when locking assets at a script address. The unlocker must send the redeemer and the full datum, such that it matches the hash the locker used when locking assets.

So the unlocker must send both inputs, the locker's input and their own. Because the locker set the hash during locking, the unlocker is not able to send any datum. It must be the datum the locker chose. However, there is no on-chain mechanism to propagate the lockers choice to the validator. The unlocker must discover through a custom off-chain process what datum the locker used, otherwise unlocking is impossible.

Recap

• There are three pieces of input to a Plutus validator: datum, redeemer and script context.

• The datum is the locker's input, the redeemer is the unlocker's input.

• The locker sends a datum hash when locking.

• The unlocker must be made aware of the datum the locker used to make the hash.

• The unlocker must send the datum matching the hash and the any redemeer when unlocking.