apply Emily's suggestions

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

agora-sample/Sample/Effect/GovernorMutation.hs

@@ -11,14 +11,22 @@ module Sample.Effect.GovernorMutation (
   mkEffectDatum,
 ) where
 
+--------------------------------------------------------------------------------
+
 import Agora.Effect.GovernorMutation (
   MutateGovernorDatum (..),
   mutateGovernorValidator,
  )
 import Agora.Governor (GovernorDatum (..))
 import Agora.Proposal (ProposalId (..), ProposalThresholds (..))
+
+--------------------------------------------------------------------------------
+
 import Plutarch.Api.V1 (mkValidator, validatorHash)
 import Plutarch.SafeMoney (Tagged (Tagged))
+
+--------------------------------------------------------------------------------
+
 import Plutus.V1.Ledger.Address (scriptHashAddress)
 import Plutus.V1.Ledger.Api (
   Address,
@@ -35,11 +43,12 @@ import Plutus.V1.Ledger.Api (
 import Plutus.V1.Ledger.Api qualified as Interval
 import Plutus.V1.Ledger.Value (AssetClass, assetClass)
 import Plutus.V1.Ledger.Value qualified as Value
+
+--------------------------------------------------------------------------------
+
 import Sample.Shared (
   authorityTokenSymbol,
-  defaultCreateProposalTimeRangeMaxDuration,
   defaultProposalThresholds,
-  defaultProposalTimingConfig,
   govAssetClass,
   govValidatorAddress,
   governor,
@@ -48,6 +57,12 @@ import Sample.Shared (
  )
 import Test.Util (datumPair, toDatumHash)
 
+--------------------------------------------------------------------------------
+
+import Data.Default.Class (Default (def))
+
+--------------------------------------------------------------------------------
+
 -- | The effect validator instance.
 effectValidator :: Validator
 effectValidator = mkValidator $ mutateGovernorValidator governor
@@ -103,8 +118,8 @@ mkEffectTxInfo newGovDatum =
         GovernorDatum
           { proposalThresholds = defaultProposalThresholds
           , nextProposalId = ProposalId 0
-          , proposalTimings = defaultProposalTimingConfig
-          , createProposalTimeRangeMaxDuration = defaultCreateProposalTimeRangeMaxDuration
+          , proposalTimings = def
+          , createProposalTimeRangeMaxWidth = def
           }
       governorInputDatum :: Datum
       governorInputDatum = Datum $ toBuiltinData governorInputDatum'
@@ -165,8 +180,8 @@ validNewGovernorDatum =
   GovernorDatum
     { proposalThresholds = defaultProposalThresholds
     , nextProposalId = ProposalId 42
-    , proposalTimings = defaultProposalTimingConfig
-    , createProposalTimeRangeMaxDuration = defaultCreateProposalTimeRangeMaxDuration
+    , proposalTimings = def
+    , createProposalTimeRangeMaxWidth = def
     }
 
 invalidNewGovernorDatum :: GovernorDatum
@@ -177,6 +192,6 @@ invalidNewGovernorDatum =
           { countVoting = Tagged (-1)
           }
     , nextProposalId = ProposalId 42
-    , proposalTimings = defaultProposalTimingConfig
-    , createProposalTimeRangeMaxDuration = defaultCreateProposalTimeRangeMaxDuration
+    , proposalTimings = def
+    , createProposalTimeRangeMaxWidth = def
     }

agora-sample/Sample/Governor.hs

@@ -56,6 +56,10 @@ import Agora.Proposal (
   emptyVotesFor,
  )
 import Agora.Proposal qualified as P
+import Agora.Proposal.Time (
+  ProposalStartingTime (ProposalStartingTime),
+  ProposalTimingConfig (..),
+ )
 import Agora.Stake (
   ProposalLock (..),
   Stake (..),
@@ -64,15 +68,9 @@ import Agora.Stake (
 
 --------------------------------------------------------------------------------
 
-import Agora.Proposal.Time (
-  ProposalStartingTime (ProposalStartingTime),
-  ProposalTimingConfig (..),
- )
 import Sample.Shared (
   authorityTokenSymbol,
-  defaultCreateProposalTimeRangeMaxDuration,
   defaultProposalThresholds,
-  defaultProposalTimingConfig,
   govAssetClass,
   govSymbol,
   govValidatorAddress,
@@ -91,6 +89,10 @@ import Test.Util (closedBoundedInterval, datumPair, toDatumHash)
 
 --------------------------------------------------------------------------------
 
+import Data.Default.Class (Default (def))
+
+--------------------------------------------------------------------------------
+
 {- | A valid 'ScriptContext' for minting GST.
 
     - Only the minting policy will be ran in the transaction.
@@ -119,8 +121,8 @@ mintGST =
         GovernorDatum
           { proposalThresholds = defaultProposalThresholds
           , nextProposalId = ProposalId 0
-          , proposalTimings = defaultProposalTimingConfig
-          , createProposalTimeRangeMaxDuration = defaultCreateProposalTimeRangeMaxDuration
+          , proposalTimings = def
+          , createProposalTimeRangeMaxWidth = def
           }
       governorOutputDatum :: Datum
       governorOutputDatum = Datum $ toBuiltinData governorOutputDatum'
@@ -214,8 +216,8 @@ createProposal =
         GovernorDatum
           { proposalThresholds = defaultProposalThresholds
           , nextProposalId = thisProposalId
-          , proposalTimings = defaultProposalTimingConfig
-          , createProposalTimeRangeMaxDuration = defaultCreateProposalTimeRangeMaxDuration
+          , proposalTimings = def
+          , createProposalTimeRangeMaxWidth = def
           }
       governorInputDatum :: Datum
       governorInputDatum = Datum $ toBuiltinData governorInputDatum'
@@ -245,7 +247,7 @@ createProposal =
                 , cosigners = [signer]
                 , thresholds = defaultProposalThresholds
                 , votes = emptyVotesFor effects
-                , timingConfig = defaultProposalTimingConfig
+                , timingConfig = def
                 , startingTime = proposalStartingTimeFromTimeRange validTimeRange
                 }
           )
@@ -392,8 +394,8 @@ mintGATs =
         GovernorDatum
           { proposalThresholds = defaultProposalThresholds
           , nextProposalId = ProposalId 5
-          , proposalTimings = defaultProposalTimingConfig
-          , createProposalTimeRangeMaxDuration = defaultCreateProposalTimeRangeMaxDuration
+          , proposalTimings = def
+          , createProposalTimeRangeMaxWidth = def
           }
       governorInputDatum :: Datum
       governorInputDatum = Datum $ toBuiltinData governorInputDatum'
@@ -428,7 +430,7 @@ mintGATs =
           , cosigners = [signer, signer2]
           , thresholds = defaultProposalThresholds
           , votes = proposalVotes
-          , timingConfig = defaultProposalTimingConfig
+          , timingConfig = def
           , startingTime = ProposalStartingTime 10
           }
       proposalInputDatum :: Datum
@@ -485,8 +487,8 @@ mintGATs =
       --
       validTimeRange =
         closedBoundedInterval
-          (defaultProposalTimingConfig.lockingTime + 11)
-          (defaultProposalTimingConfig.executingTime - 11)
+          ((def :: ProposalTimingConfig).lockingTime + 11)
+          ((def :: ProposalTimingConfig).executingTime - 11)
    in ScriptContext
         { scriptContextTxInfo =
             TxInfo
@@ -587,8 +589,8 @@ mutateState =
         GovernorDatum
           { proposalThresholds = defaultProposalThresholds
           , nextProposalId = ProposalId 5
-          , proposalTimings = defaultProposalTimingConfig
-          , createProposalTimeRangeMaxDuration = defaultCreateProposalTimeRangeMaxDuration
+          , proposalTimings = def
+          , createProposalTimeRangeMaxWidth = def
           }
       governorInputDatum :: Datum
       governorInputDatum = Datum $ toBuiltinData governorInputDatum'

agora-sample/Sample/Proposal.hs

@@ -16,9 +16,14 @@ module Sample.Proposal (
 ) where
 
 --------------------------------------------------------------------------------
+
 import Plutarch.Api.V1 (
   validatorHash,
  )
+import Plutarch.SafeMoney (Tagged (Tagged), untag)
+
+--------------------------------------------------------------------------------
+
 import Plutus.V1.Ledger.Api (
   Address (Address),
   Credential (ScriptCredential),
@@ -34,6 +39,7 @@ import Plutus.V1.Ledger.Api (
   TxOutRef (TxOutRef),
  )
 import Plutus.V1.Ledger.Value qualified as Value
+import PlutusTx.AssocMap qualified as AssocMap
 
 --------------------------------------------------------------------------------
 
@@ -51,13 +57,18 @@ import Agora.Proposal (
  )
 import Agora.Proposal.Time (ProposalStartingTime (ProposalStartingTime), ProposalTimingConfig (..))
 import Agora.Stake (ProposalLock (ProposalLock), Stake (..), StakeDatum (..))
-import Plutarch.SafeMoney (Tagged (Tagged), untag)
-import PlutusTx.AssocMap qualified as AssocMap
+
+--------------------------------------------------------------------------------
+
 import Sample.Shared
 import Test.Util (closedBoundedInterval, datumPair, toDatumHash, updateMap)
 
 --------------------------------------------------------------------------------
 
+import Data.Default.Class (Default (def))
+
+--------------------------------------------------------------------------------
+
 -- | This script context should be a valid transaction.
 proposalCreation :: ScriptContext
 proposalCreation =
@@ -78,7 +89,7 @@ proposalCreation =
                 , cosigners = [signer]
                 , thresholds = defaultProposalThresholds
                 , votes = emptyVotesFor effects
-                , timingConfig = defaultProposalTimingConfig
+                , timingConfig = def
                 , startingTime = proposalStartingTimeFromTimeRange validTimeRange
                 }
           )
@@ -90,8 +101,8 @@ proposalCreation =
               GovernorDatum
                 { proposalThresholds = defaultProposalThresholds
                 , nextProposalId = ProposalId 0
-                , proposalTimings = defaultProposalTimingConfig
-                , createProposalTimeRangeMaxDuration = defaultCreateProposalTimeRangeMaxDuration
+                , proposalTimings = def
+                , createProposalTimeRangeMaxWidth = def
                 }
           )
       govAfter :: Datum
@@ -101,8 +112,8 @@ proposalCreation =
               GovernorDatum
                 { proposalThresholds = defaultProposalThresholds
                 , nextProposalId = ProposalId 1
-                , proposalTimings = defaultProposalTimingConfig
-                , createProposalTimeRangeMaxDuration = defaultCreateProposalTimeRangeMaxDuration
+                , proposalTimings = def
+                , createProposalTimeRangeMaxWidth = def
                 }
           )
 
@@ -179,7 +190,7 @@ cosignProposal newSigners =
           , cosigners = [signer]
           , thresholds = defaultProposalThresholds
           , votes = emptyVotesFor effects
-          , timingConfig = defaultProposalTimingConfig
+          , timingConfig = def
           , startingTime = ProposalStartingTime 0
           }
       stakeDatum :: StakeDatum
@@ -190,7 +201,7 @@ cosignProposal newSigners =
       validTimeRange =
         closedBoundedInterval
           10
-          (defaultProposalTimingConfig.draftTime - 10)
+          ((def :: ProposalTimingConfig).draftTime - 10)
    in TxInfo
         { txInfoInputs =
             [ TxInInfo
@@ -300,7 +311,7 @@ voteOnProposal params =
           , cosigners = [stakeOwner]
           , thresholds = defaultProposalThresholds
           , votes = ProposalVotes initialVotes
-          , timingConfig = defaultProposalTimingConfig
+          , timingConfig = def
           , startingTime = ProposalStartingTime 0
           }
       proposalInputDatum :: Datum
@@ -389,7 +400,9 @@ voteOnProposal params =
       ---
 
       validTimeRange =
-        closedBoundedInterval (defaultProposalTimingConfig.draftTime + 1) (defaultProposalTimingConfig.votingTime - 1)
+        closedBoundedInterval
+          ((def :: ProposalTimingConfig).draftTime + 1)
+          ((def :: ProposalTimingConfig).votingTime - 1)
    in TxInfo
         { txInfoInputs =
             [ TxInInfo proposalRef proposalInput

agora-sample/Sample/Shared.hs

@@ -1,3 +1,5 @@
+{-# OPTIONS_GHC -Wno-orphans #-}
+
 {- |
 Module     : Sample.Shared
 Maintainer : emi@haskell.fyi
@@ -36,8 +38,6 @@ module Sample.Shared (
   proposalPolicySymbol,
   proposalValidatorHash,
   proposalValidatorAddress,
-  defaultProposalTimingConfig,
-  defaultCreateProposalTimeRangeMaxDuration,
   proposalStartingTimeFromTimeRange,
 
   -- ** Authority
@@ -78,12 +78,14 @@ import Agora.Proposal (
   ProposalThresholds (..),
  )
 import Agora.Proposal.Time (
+  MaxTimeRangeWidth (..),
   ProposalStartingTime (ProposalStartingTime),
   ProposalTimingConfig (..),
  )
 import Agora.Stake (Stake (..))
 import Agora.Treasury (treasuryValidator)
 import Agora.Utils (validatorHashToTokenName)
+import Data.Default.Class (Default (..))
 import Plutarch.Api.V1 (
   mintingPolicySymbol,
   mkMintingPolicy,
@@ -100,7 +102,6 @@ import Plutus.V1.Ledger.Api (
   Interval (..),
   LowerBound (..),
   MintingPolicy (..),
-  POSIXTime,
   POSIXTimeRange,
   PubKeyHash,
   TxOutRef (TxOutRef),
@@ -197,18 +198,27 @@ authorityToken = authorityTokenFromGovernor governor
 authorityTokenSymbol :: CurrencySymbol
 authorityTokenSymbol = authorityTokenSymbolFromGovernor governor
 
-defaultProposalTimingConfig :: ProposalTimingConfig
-defaultProposalTimingConfig =
-  ProposalTimingConfig
-    { draftTime = 50
-    , votingTime = 1000
-    , lockingTime = 2000
-    , executingTime = 3000
-    }
+{- | Default value of 'Agora.Governor.GovernorDatum.proposalTimings'.
+     For testing purpose only.
+-}
+instance Default ProposalTimingConfig where
+  def =
+    ProposalTimingConfig
+      { draftTime = 50
+      , votingTime = 1000
+      , lockingTime = 2000
+      , executingTime = 3000
+      }
 
-defaultCreateProposalTimeRangeMaxDuration :: POSIXTime
-defaultCreateProposalTimeRangeMaxDuration = 10
+{- | Default value of 'Agora.Governor.GovernorDatum.createProposalTimeRangeMaxWidth'.
+     For testing purpose only.
+-}
+instance Default MaxTimeRangeWidth where
+  def = MaxTimeRangeWidth 10
 
+{- | Get the starting time of a proposal, given a closed finite time range.
+     Tightness of the time range is not checked. See 'Agora.Proposal.Time.createProposalStartingTime'.
+-}
 proposalStartingTimeFromTimeRange :: POSIXTimeRange -> ProposalStartingTime
 proposalStartingTimeFromTimeRange
   (Interval (LowerBound (Finite l) True) (UpperBound (Finite u) True)) =