apply Emily's suggestions

* add `PMaxTimeRangeWidth`
* several `Default` instances for testing
* a bunch of docstrings
* fix the tests/samples

agora/Agora/Governor.hs

@@ -37,13 +37,17 @@ import Agora.Proposal (
   ProposalId (ProposalId),
   ProposalThresholds,
  )
-import Agora.Proposal.Time (PProposalTimingConfig, ProposalTimingConfig)
+import Agora.Proposal.Time (
+  MaxTimeRangeWidth,
+  PMaxTimeRangeWidth,
+  PProposalTimingConfig,
+  ProposalTimingConfig,
+ )
 import Agora.SafeMoney (GTTag)
 import Agora.Utils (tclet)
 
 --------------------------------------------------------------------------------
 
-import Plutarch.Api.V1 (PPOSIXTime)
 import Plutarch.DataRepr (
   DerivePConstantViaData (..),
   PDataFields,
@@ -56,7 +60,7 @@ import Plutarch.Unsafe (punsafeCoerce)
 
 --------------------------------------------------------------------------------
 
-import Plutus.V1.Ledger.Api (POSIXTime, TxOutRef)
+import Plutus.V1.Ledger.Api (TxOutRef)
 import Plutus.V1.Ledger.Value (AssetClass (..))
 import PlutusTx qualified
 
@@ -71,7 +75,7 @@ data GovernorDatum = GovernorDatum
   , proposalTimings :: ProposalTimingConfig
   -- ^ The timing configuration for proposals.
   --   Will get copied over upon the creation of proposals.
-  , createProposalTimeRangeMaxDuration :: POSIXTime
+  , createProposalTimeRangeMaxWidth :: MaxTimeRangeWidth
   -- ^ The maximum valid duration of a transaction that creats a proposal.
   }
   deriving stock (Show, GHC.Generic)
@@ -126,7 +130,7 @@ newtype PGovernorDatum (s :: S) = PGovernorDatum
           '[ "proposalThresholds" ':= PProposalThresholds
            , "nextProposalId" ':= PProposalId
            , "proposalTimings" ':= PProposalTimingConfig
-           , "createProposalTimeRangeMaxDuration" ':= PPOSIXTime
+           , "createProposalTimeRangeMaxWidth" ':= PMaxTimeRangeWidth
            ]
       )
   }

agora/Agora/Governor/Scripts.hs

@@ -307,7 +307,7 @@ governorValidator gov =
           @'[ "proposalThresholds"
             , "nextProposalId"
             , "proposalTimings"
-            , "createProposalTimeRangeMaxDuration"
+            , "createProposalTimeRangeMaxWidth"
             ]
           oldGovernorDatum
 
@@ -347,8 +347,8 @@ governorValidator gov =
                   ( #proposalThresholds .= oldGovernorDatumF.proposalThresholds
                       .& #nextProposalId .= pdata expectedNextProposalId
                       .& #proposalTimings .= oldGovernorDatumF.proposalTimings
-                      .& #createProposalTimeRangeMaxDuration
-                        .= oldGovernorDatumF.createProposalTimeRangeMaxDuration
+                      .& #createProposalTimeRangeMaxWidth
+                        .= oldGovernorDatumF.createProposalTimeRangeMaxWidth
                   )
           tcassert "Unexpected governor state datum" $
             newGovernorDatum #== expectedNewDatum
@@ -436,7 +436,7 @@ governorValidator gov =
               expectedVotes = pemptyVotesFor # pfromData proposalOutputDatum.effects
               expectedStartingTime =
                 createProposalStartingTime
-                  # oldGovernorDatumF.createProposalTimeRangeMaxDuration
+                  # oldGovernorDatumF.createProposalTimeRangeMaxWidth
                   # txInfoF.validRange
               -- Id, thresholds and timings should be copied from the old governor state datum.
               expectedProposalOut =

agora/Agora/Proposal.hs

@@ -349,7 +349,7 @@ deriving via
   instance
     (PConstantDecl ProposalVotes)
 
--- Plutarch version of 'pemptyVotesFor'.
+-- Plutarch-level version of 'emptyVotesFor'.
 pemptyVotesFor :: forall s a. (PIsData a) => Term s (PMap PResultTag a :--> PProposalVotes)
 pemptyVotesFor =
   phoistAcyclic $

agora/Agora/Proposal/Time.hs

@@ -13,11 +13,13 @@ module Agora.Proposal.Time (
   ProposalTime (..),
   ProposalTimingConfig (..),
   ProposalStartingTime (..),
+  MaxTimeRangeWidth (..),
 
   -- * Plutarch-land
   PProposalTime (..),
   PProposalTimingConfig (..),
   PProposalStartingTime (..),
+  PMaxTimeRangeWidth (..),
 
   -- * Compute periods given config and starting time.
   createProposalStartingTime,
@@ -108,6 +110,11 @@ data ProposalTimingConfig = ProposalTimingConfig
 
 PlutusTx.makeIsDataIndexed ''ProposalTimingConfig [('ProposalTimingConfig, 0)]
 
+-- | Represents the maximum width of a 'POSIXTimeRange'.
+newtype MaxTimeRangeWidth = MaxTimeRangeWidth {getMaxWidth :: POSIXTime}
+  deriving stock (Eq, Show, Ord, GHC.Generic)
+  deriving newtype (PlutusTx.ToData, PlutusTx.FromData, PlutusTx.UnsafeFromData)
+
 --------------------------------------------------------------------------------
 
 -- | Plutarch-level version of 'ProposalTime'.
@@ -173,6 +180,17 @@ deriving via
   instance
     (PConstantDecl ProposalTimingConfig)
 
+-- | Plutarch-level version of 'MaxTimeRangeWidth'.
+newtype PMaxTimeRangeWidth (s :: S)
+  = PMaxTimeRangeWidth (Term s PPOSIXTime)
+  deriving (PlutusType, PIsData, PEq, POrd) via (DerivePNewtype PMaxTimeRangeWidth PPOSIXTime)
+
+instance PUnsafeLiftDecl PMaxTimeRangeWidth where type PLifted PMaxTimeRangeWidth = MaxTimeRangeWidth
+deriving via
+  (DerivePConstantViaNewtype MaxTimeRangeWidth PMaxTimeRangeWidth PPOSIXTime)
+  instance
+    (PConstantDecl MaxTimeRangeWidth)
+
 --------------------------------------------------------------------------------
 
 -- FIXME: Orphan instance, move this to plutarch-extra.
@@ -180,11 +198,12 @@ instance AdditiveSemigroup (Term s PPOSIXTime) where
   (punsafeCoerce @_ @_ @PInteger -> x) + (punsafeCoerce @_ @_ @PInteger -> y) = punsafeCoerce $ x + y
 
 {- | Get the starting time of a proposal, from the 'Plutus.V1.Ledger.Api.txInfoValidPeriod' field.
-     For every proposal, this is only meant to run once upon creation.
+     For every proposal, this is only meant to run once upon creation. Given time range should be
+     tight enough, meaning that the width of the time range should be less than the maximum value.
 -}
-createProposalStartingTime :: forall (s :: S). Term s (PPOSIXTime :--> PPOSIXTimeRange :--> PProposalStartingTime)
+createProposalStartingTime :: forall (s :: S). Term s (PMaxTimeRangeWidth :--> PPOSIXTimeRange :--> PProposalStartingTime)
 createProposalStartingTime = phoistAcyclic $
-  plam $ \maxDuration iv -> unTermCont $ do
+  plam $ \(pto -> maxDuration) iv -> unTermCont $ do
     currentTimeF <-
       tcont $
         pletFields @'["lowerBound", "upperBound"] $