PLT_768 Renamed currentTime to currentNodeClientTimeRange and renamed

currentPABSlot to currentNodeClientSlot

* Deprecated 'Plutus.Contract.Request.currentTime'

* Created 'Plutus.Contract.Request.currentNodeClientTimeRange' which
  replaces 'currentTime'

* Deprecated 'Plutus.Contract.Request.currentPABSlot'

* Created 'Plutus.Contract.Request.currentNodeClientSlot' which
  replaces 'currentPABSlot'

* Updated the plutus use case examples

* Updated the PABReq and PABResp request handlers for the emulator and
  the PAB

* Fixed a failing test case for the SealedBidAuction regarding validity
  intervals

doc/plutus/tutorials/EscrowImpl.hs

@@ -70,9 +70,9 @@ import Plutus.V1.Ledger.Api (Datum (Datum), DatumHash, ValidatorHash)
 import Plutus.V1.Ledger.Contexts (ScriptContext (ScriptContext, scriptContextTxInfo), TxInfo (txInfoValidRange))
 
 import Plutus.Contract (AsContractError (_ContractError), Contract, ContractError, Endpoint, HasEndpoint, Promise,
-                        adjustUnbalancedTx, awaitTime, currentTime, endpoint, mapError, mkTxConstraints,
-                        ownFirstPaymentPubKeyHash, promiseMap, selectList, submitUnbalancedTx, type (.\/), utxosAt,
-                        waitNSlots)
+                        adjustUnbalancedTx, awaitTime, currentNodeClientTimeRange, currentTime, endpoint, mapError,
+                        mkTxConstraints, ownFirstPaymentPubKeyHash, promiseMap, selectList, submitUnbalancedTx,
+                        type (.\/), utxosAt, waitNSlots)
 import PlutusTx qualified
 {- START imports -}
 import PlutusTx.Code qualified as PlutusTx
@@ -299,7 +299,7 @@ redeem ::
     -> Contract w s e RedeemSuccess
 redeem inst escrow = mapError (review _EscrowError) $ do
     let addr = Scripts.validatorAddress inst
-    current <- currentTime
+    current <- Haskell.snd <$> currentNodeClientTimeRange
     unspentOutputs <- utxosAt addr
     let
         valRange = Interval.to (Haskell.pred $ escrowDeadline escrow)
@@ -365,7 +365,7 @@ payRedeemRefund params vl = do
             if presentVal `geq` targetTotal params
                 then Right <$> redeem inst params
                 else do
-                    time <- currentTime
+                    time <- Haskell.snd <$> currentNodeClientTimeRange
                     if time >= escrowDeadline params
                         then Left <$> refund inst params
                         else waitNSlots 1 >> go

plutus-contract/src/Plutus/Contract.hs

@@ -27,11 +27,13 @@ module Plutus.Contract(
     , Request.isSlot
     , Request.currentSlot
     , Request.currentPABSlot
+    , Request.currentNodeClientSlot
     , Request.currentChainIndexSlot
     , Request.waitNSlots
     , Request.awaitTime
     , Request.isTime
     , Request.currentTime
+    , Request.currentNodeClientTimeRange
     , Request.waitNMilliSeconds
     -- * Endpoints
     , Request.HasEndpoint

plutus-contract/src/Plutus/Contract/Effects.hs

@@ -13,9 +13,10 @@ module Plutus.Contract.Effects( -- TODO: Move to Requests.Internal
     _AwaitTimeReq,
     _AwaitUtxoSpentReq,
     _AwaitUtxoProducedReq,
-    _CurrentPABSlotReq,
+    _CurrentNodeClientSlotReq,
     _CurrentChainIndexSlotReq,
     _CurrentTimeReq,
+    _CurrentNodeClientTimeRangeReq,
     _AwaitTxStatusChangeReq,
     _AwaitTxOutStatusChangeReq,
     _OwnContractInstanceIdReq,
@@ -47,9 +48,10 @@ module Plutus.Contract.Effects( -- TODO: Move to Requests.Internal
     _AwaitTimeResp,
     _AwaitUtxoSpentResp,
     _AwaitUtxoProducedResp,
-    _CurrentPABSlotResp,
+    _CurrentNodeClientSlotResp,
     _CurrentChainIndexSlotResp,
     _CurrentTimeResp,
+    _CurrentNodeClientTimeRangeResp,
     _AwaitTxStatusChangeResp,
     _AwaitTxStatusChangeResp',
     _AwaitTxOutStatusChangeResp,
@@ -122,9 +124,10 @@ data PABReq =
     | AwaitUtxoProducedReq Address
     | AwaitTxStatusChangeReq TxId
     | AwaitTxOutStatusChangeReq TxOutRef
-    | CurrentPABSlotReq
+    | CurrentNodeClientSlotReq
     | CurrentChainIndexSlotReq
     | CurrentTimeReq
+    | CurrentNodeClientTimeRangeReq
     | OwnContractInstanceIdReq
     | OwnAddressesReq
     | ChainIndexQueryReq ChainIndexQuery
@@ -143,9 +146,10 @@ instance Pretty PABReq where
     AwaitTimeReq s                          -> "Await time:" <+> pretty s
     AwaitUtxoSpentReq utxo                  -> "Await utxo spent:" <+> pretty utxo
     AwaitUtxoProducedReq a                  -> "Await utxo produced:" <+> pretty a
-    CurrentPABSlotReq                       -> "Current PAB slot"
+    CurrentNodeClientSlotReq                -> "Current node client slot"
     CurrentChainIndexSlotReq                -> "Current chain index slot"
     CurrentTimeReq                          -> "Current time"
+    CurrentNodeClientTimeRangeReq           -> "Current node client time range"
     AwaitTxStatusChangeReq txid             -> "Await tx status change:" <+> pretty txid
     AwaitTxOutStatusChangeReq ref           -> "Await txout status change:" <+> pretty ref
     OwnContractInstanceIdReq                -> "Own contract instance ID"
@@ -166,9 +170,10 @@ data PABResp =
     | AwaitUtxoProducedResp (NonEmpty ChainIndexTx)
     | AwaitTxStatusChangeResp TxId TxStatus
     | AwaitTxOutStatusChangeResp TxOutRef TxOutStatus
-    | CurrentPABSlotResp Slot
+    | CurrentNodeClientSlotResp Slot
     | CurrentChainIndexSlotResp Slot
     | CurrentTimeResp POSIXTime
+    | CurrentNodeClientTimeRangeResp (POSIXTime, POSIXTime)
     | OwnContractInstanceIdResp ContractInstanceId
     | OwnAddressesResp (NonEmpty Address)
     | ChainIndexQueryResp ChainIndexResponse
@@ -187,9 +192,10 @@ instance Pretty PABResp where
     AwaitTimeResp s                          -> "Time:" <+> pretty s
     AwaitUtxoSpentResp utxo                  -> "Utxo spent:" <+> pretty utxo
     AwaitUtxoProducedResp addr               -> "Utxo produced:" <+> pretty addr
-    CurrentPABSlotResp s                     -> "Current PAB slot:" <+> pretty s
+    CurrentNodeClientSlotResp s              -> "Current node client slot:" <+> pretty s
     CurrentChainIndexSlotResp s              -> "Current chain index slot:" <+> pretty s
     CurrentTimeResp s                        -> "Current time:" <+> pretty s
+    CurrentNodeClientTimeRangeResp s         -> "Current node client time range:" <+> pretty s
     AwaitTxStatusChangeResp txid status      -> "Status of" <+> pretty txid <+> "changed to" <+> pretty status
     AwaitTxOutStatusChangeResp ref status    -> "Status of" <+> pretty ref <+> "changed to" <+> pretty status
     OwnContractInstanceIdResp i              -> "Own contract instance ID:" <+> pretty i
@@ -208,9 +214,10 @@ matches a b = case (a, b) of
   (AwaitTimeReq{}, AwaitTimeResp{})                        -> True
   (AwaitUtxoSpentReq{}, AwaitUtxoSpentResp{})              -> True
   (AwaitUtxoProducedReq{}, AwaitUtxoProducedResp{})        -> True
-  (CurrentPABSlotReq, CurrentPABSlotResp{})                -> True
-  (CurrentChainIndexSlotReq, CurrentChainIndexSlotResp{})              -> True
+  (CurrentNodeClientSlotReq, CurrentNodeClientSlotResp{})  -> True
+  (CurrentChainIndexSlotReq, CurrentChainIndexSlotResp{})  -> True
   (CurrentTimeReq, CurrentTimeResp{})                      -> True
+  (CurrentNodeClientTimeRangeReq, CurrentNodeClientTimeRangeResp{}) -> True
   (AwaitTxStatusChangeReq i, AwaitTxStatusChangeResp i' _) -> i == i'
   (AwaitTxOutStatusChangeReq i, AwaitTxOutStatusChangeResp i' _) -> i == i'
   (OwnContractInstanceIdReq, OwnContractInstanceIdResp{})  -> True

plutus-contract/src/Plutus/Contract/Request.hs

@@ -22,11 +22,13 @@ module Plutus.Contract.Request(
     , isSlot
     , currentSlot
     , currentPABSlot
+    , currentNodeClientSlot
     , currentChainIndexSlot
     , waitNSlots
     , awaitTime
     , isTime
     , currentTime
+    , currentNodeClientTimeRange
     , waitNMilliSeconds
     -- ** Chain index queries
     , datumFromHash
@@ -138,7 +140,7 @@ import Plutus.V1.Ledger.Api (Address, Datum, DatumHash, MintingPolicy, MintingPo
 import PlutusTx qualified
 
 import Plutus.Contract.Effects (ActiveEndpoint (ActiveEndpoint, aeDescription, aeMetadata),
-                                PABReq (AdjustUnbalancedTxReq, AwaitSlotReq, AwaitTimeReq, AwaitTxOutStatusChangeReq, AwaitTxStatusChangeReq, AwaitUtxoProducedReq, AwaitUtxoSpentReq, BalanceTxReq, ChainIndexQueryReq, CurrentChainIndexSlotReq, CurrentPABSlotReq, CurrentTimeReq, ExposeEndpointReq, OwnAddressesReq, OwnContractInstanceIdReq, WriteBalancedTxReq, YieldUnbalancedTxReq),
+                                PABReq (AdjustUnbalancedTxReq, AwaitSlotReq, AwaitTimeReq, AwaitTxOutStatusChangeReq, AwaitTxStatusChangeReq, AwaitUtxoProducedReq, AwaitUtxoSpentReq, BalanceTxReq, ChainIndexQueryReq, CurrentChainIndexSlotReq, CurrentNodeClientSlotReq, CurrentNodeClientTimeRangeReq, CurrentTimeReq, ExposeEndpointReq, OwnAddressesReq, OwnContractInstanceIdReq, WriteBalancedTxReq, YieldUnbalancedTxReq),
                                 PABResp (ExposeEndpointResp))
 import Plutus.Contract.Effects qualified as E
 import Plutus.Contract.Logging (logDebug)
@@ -214,21 +216,31 @@ isSlot ::
 isSlot = Promise . awaitSlot
 
 -- | Get the current slot number
-{-# DEPRECATED currentSlot "It was renamed to 'currentPABSlot', this function will be removed" #-}
+{-# DEPRECATED currentSlot "Use currentNodeClientSlot instead" #-}
 currentSlot ::
     forall w s e.
     ( AsContractError e
     )
     => Contract w s e Slot
 currentSlot = currentPABSlot
 
+{-# DEPRECATED currentPABSlot "Use currentNodeClientSlot instead" #-}
 -- | Get the current slot number of PAB
 currentPABSlot ::
     forall w s e.
     ( AsContractError e
     )
     => Contract w s e Slot
-currentPABSlot = pabReq CurrentPABSlotReq E._CurrentPABSlotResp
+currentPABSlot = pabReq CurrentNodeClientSlotReq E._CurrentNodeClientSlotResp
+
+-- | Get the current slot number of the node client (the local or remote node) that the application
+-- is connected to.
+currentNodeClientSlot ::
+    forall w s e.
+    ( AsContractError e
+    )
+    => Contract w s e Slot
+currentNodeClientSlot = pabReq CurrentNodeClientSlotReq E._CurrentNodeClientSlotResp
 
 -- | Get the current node slot number querying slot number from plutus chain index to be aligned with slot at local running node
 currentChainIndexSlot ::
@@ -272,6 +284,7 @@ isTime ::
     -> Promise w s e POSIXTime
 isTime = Promise . awaitTime
 
+{-# DEPRECATED currentTime "Use currentNodeClientTimeRange instead" #-}
 -- | Get the latest time of the current slot.
 --
 -- Example: if slot length is 3s and current slot is 2, then `currentTime`
@@ -283,6 +296,17 @@ currentTime ::
     => Contract w s e POSIXTime
 currentTime = pabReq CurrentTimeReq E._CurrentTimeResp
 
+-- | Get the 'POSIXTime' range of the current slot.
+--
+-- Example: if slot length is 3s and current slot is 2, then `currentTimeRange`
+-- returns the time interval @[3, 5[@.
+currentNodeClientTimeRange ::
+    forall w s e.
+    ( AsContractError e
+    )
+    => Contract w s e (POSIXTime, POSIXTime)
+currentNodeClientTimeRange = pabReq CurrentNodeClientTimeRangeReq E._CurrentNodeClientTimeRangeResp
+
 -- | Wait for a number of milliseconds starting at the ending time of the current
 -- slot, and return the latest time we know has passed.
 --

plutus-contract/src/Plutus/Contract/Trace.hs

@@ -28,9 +28,10 @@ module Plutus.Contract.Trace
     , handleSlotNotifications
     , handleTimeNotifications
     , handleOwnAddressesQueries
-    , handleCurrentPABSlotQueries
+    , handleCurrentNodeClientSlotQueries
     , handleCurrentChainIndexSlotQueries
     , handleCurrentTimeQueries
+    , handleCurrentNodeClientTimeRangeQueries
     , handleTimeToSlotConversions
     , handleUnbalancedTransactions
     , handlePendingTransactions
@@ -117,13 +118,13 @@ handleTimeNotifications ::
 handleTimeNotifications =
     generalise (preview E._AwaitTimeReq) E.AwaitTimeResp RequestHandler.handleTimeNotifications
 
-handleCurrentPABSlotQueries ::
+handleCurrentNodeClientSlotQueries ::
     ( Member (LogObserve (LogMessage Text)) effs
     , Member NodeClientEffect effs
     )
     => RequestHandler effs PABReq PABResp
-handleCurrentPABSlotQueries =
-    generalise (preview E._CurrentPABSlotReq) E.CurrentPABSlotResp RequestHandler.handleCurrentPABSlot
+handleCurrentNodeClientSlotQueries =
+    generalise (preview E._CurrentNodeClientSlotReq) E.CurrentNodeClientSlotResp RequestHandler.handleCurrentNodeClientSlot
 
 handleCurrentChainIndexSlotQueries ::
     ( Member (LogObserve (LogMessage Text)) effs
@@ -141,6 +142,17 @@ handleCurrentTimeQueries ::
 handleCurrentTimeQueries =
     generalise (preview E._CurrentTimeReq) E.CurrentTimeResp RequestHandler.handleCurrentTime
 
+handleCurrentNodeClientTimeRangeQueries ::
+    ( Member (LogObserve (LogMessage Text)) effs
+    , Member NodeClientEffect effs
+    )
+    => RequestHandler effs PABReq PABResp
+handleCurrentNodeClientTimeRangeQueries =
+    generalise
+        (preview E._CurrentNodeClientTimeRangeReq)
+        E.CurrentNodeClientTimeRangeResp
+        RequestHandler.handleCurrentNodeClientTimeRange
+
 handleTimeToSlotConversions ::
     ( Member (LogObserve (LogMessage Text)) effs
     , Member NodeClientEffect effs

plutus-contract/src/Plutus/Contract/Trace/RequestHandler.hs

@@ -20,10 +20,11 @@ module Plutus.Contract.Trace.RequestHandler(
     , handleAdjustUnbalancedTx
     , handleOwnAddresses
     , handleSlotNotifications
-    , handleCurrentPABSlot
+    , handleCurrentNodeClientSlot
     , handleCurrentChainIndexSlot
     , handleTimeNotifications
     , handleCurrentTime
+    , handleCurrentNodeClientTimeRange
     , handleTimeToSlotConversions
     , handleUnbalancedTransactions
     , handlePendingTransactions
@@ -89,8 +90,8 @@ tryHandler' ::
     => RequestHandler effs req (f resp)
     -> [req]
     -> Eff effs (f resp)
-tryHandler' (RequestHandler h) requests =
-    foldM (\e i -> fmap (e <|>) $ fmap join $ NonDet.makeChoiceA @f $ h i) empty requests
+tryHandler' (RequestHandler h) =
+    foldM (\e i -> fmap ((e <|>) . join) $ NonDet.makeChoiceA @f $ h i) empty
 
 extract :: Alternative f => Prism' a b -> a -> f b
 extract p = maybe empty pure . preview p
@@ -159,15 +160,15 @@ handleTimeNotifications =
             guard (currentSlot >= targetSlot_)
             pure $ TimeSlot.slotToEndPOSIXTime pSlotConfig currentSlot
 
-handleCurrentPABSlot ::
+handleCurrentNodeClientSlot ::
     forall effs a.
     ( Member NodeClientEffect effs
     , Member (LogObserve (LogMessage Text)) effs
     )
     => RequestHandler effs a Slot
-handleCurrentPABSlot =
+handleCurrentNodeClientSlot =
     RequestHandler $ \_ ->
-        surroundDebug @Text "handleCurrentPABSlot" $ do
+        surroundDebug @Text "handleCurrentNodeClientSlot" $ do
             Wallet.Effects.getClientSlot
 
 handleCurrentChainIndexSlot ::
@@ -196,6 +197,21 @@ handleCurrentTime =
             Params { pSlotConfig }  <- Wallet.Effects.getClientParams
             TimeSlot.slotToEndPOSIXTime pSlotConfig <$> Wallet.Effects.getClientSlot
 
+handleCurrentNodeClientTimeRange ::
+    forall effs a.
+    ( Member NodeClientEffect effs
+    , Member (LogObserve (LogMessage Text)) effs
+    )
+    => RequestHandler effs a (POSIXTime, POSIXTime)
+handleCurrentNodeClientTimeRange =
+    RequestHandler $ \_ ->
+        surroundDebug @Text "handleCurrentNodeClientTimeRange" $ do
+            Params { pSlotConfig }  <- Wallet.Effects.getClientParams
+            nodeClientSlot <- Wallet.Effects.getClientSlot
+            pure ( TimeSlot.slotToBeginPOSIXTime pSlotConfig nodeClientSlot
+                 , TimeSlot.slotToEndPOSIXTime pSlotConfig nodeClientSlot
+                 )
+
 handleTimeToSlotConversions ::
     forall effs.
     ( Member NodeClientEffect effs

plutus-contract/src/Plutus/Trace/Emulator/ContractInstance.hs

@@ -254,10 +254,11 @@ handleBlockchainQueries =
     <> RequestHandler.handleOwnAddressesQueries
     <> RequestHandler.handleOwnInstanceIdQueries
     <> RequestHandler.handleSlotNotifications
-    <> RequestHandler.handleCurrentPABSlotQueries
+    <> RequestHandler.handleCurrentNodeClientSlotQueries
     <> RequestHandler.handleCurrentChainIndexSlotQueries
     <> RequestHandler.handleTimeNotifications
     <> RequestHandler.handleCurrentTimeQueries
+    <> RequestHandler.handleCurrentNodeClientTimeRangeQueries
     <> RequestHandler.handleTimeToSlotConversions
     <> RequestHandler.handleYieldedUnbalancedTx
     <> RequestHandler.handleAdjustUnbalancedTx

plutus-contract/test/Spec/TxConstraints/MustSatisfyAnyOf.hs

@@ -126,7 +126,7 @@ mustSatisfyAnyOfContract :: SubmitTx -> LanguageContext -> ConstraintParams
                             -> ConstraintParams -> Contract () Empty ContractError ()
 mustSatisfyAnyOfContract
     submitTxFromConstraints lc offChainConstraints onChainConstraints = do
-    now <- Con.currentTime
+    now <- snd <$> Con.currentNodeClientTimeRange
     let offChainConstraintsWithNow =
             buildConstraints (applyNowToTimeValidity offChainConstraints now)
         onChainConstraintsWithNow  = applyNowToTimeValidity onChainConstraints now

plutus-contract/test/Spec/TxConstraints/TimeValidity.hs

@@ -56,7 +56,7 @@ tests = testGroup "time validitity constraint"
 
 contract :: Contract () Empty ContractError ()
 contract = do
-    now <- Con.currentTime
+    now <- snd <$> Con.currentNodeClientTimeRange
     logInfo @String $ "now: " ++ show now
     let lookups1 = Constraints.typedValidatorLookups $ typedValidator deadline
         tx1 = Constraints.mustPayToTheScriptWithDatumInTx
@@ -76,7 +76,7 @@ contract = do
     void $ waitNSlots 2
     ledgerTx2 <- submitTxConstraintsWith @Void lookups2 tx2
     awaitTxConfirmed $ Tx.getCardanoTxId ledgerTx2
-    cSlot <- Con.currentPABSlot
+    cSlot <- Con.currentNodeClientSlot
     logInfo @String $ "Current slot: " ++ show cSlot
 
 trace :: Trace.EmulatorTrace ()
@@ -115,7 +115,7 @@ contractCardano f p = do
     let mkTx lookups constraints = either (error . show) id $ Tx.Constraints.mkTx @UnitTest p lookups constraints
     pkh <- Con.ownFirstPaymentPubKeyHash
     utxos <- Con.ownUtxos
-    now <- Con.currentTime
+    now <- snd <$> Con.currentNodeClientTimeRange
     logInfo @String $ "now: " ++ show now
     let utxoRef = fst $ head' $ Map.toList utxos
         lookups = Tx.Constraints.unspentOutputs utxos
@@ -126,7 +126,7 @@ contractCardano f p = do
     ledgerTx <- submitUnbalancedTx $ mkTx lookups tx
     awaitTxConfirmed $ Tx.getCardanoTxId ledgerTx
 
-    cSlot <- Con.currentPABSlot
+    cSlot <- Con.currentNodeClientSlot
     logInfo @String $ "Current slot: " ++ show cSlot
     let txRange = Tx.getCardanoTxValidityRange ledgerTx
     logInfo @String $ show txRange

plutus-pab/src/Plutus/PAB/Arbitrary.hs

@@ -316,7 +316,7 @@ instance Arbitrary PABReq where
     arbitrary =
         oneof
             [ AwaitSlotReq <$> arbitrary
-            , pure CurrentPABSlotReq
+            , pure CurrentNodeClientSlotReq
             , pure CurrentChainIndexSlotReq
             , pure OwnContractInstanceIdReq
             , ExposeEndpointReq <$> arbitrary