diff --git a/agora-specs/Sample/Effect/TreasuryWithdrawal.hs b/agora-specs/Sample/Effect/TreasuryWithdrawal.hs index f698f77..2b3e731 100644 --- a/agora-specs/Sample/Effect/TreasuryWithdrawal.hs +++ b/agora-specs/Sample/Effect/TreasuryWithdrawal.hs @@ -87,6 +87,7 @@ inputGAT = , txOutDatumHash = Just (DatumHash "") } +-- | Create an input given the index of the treasury and the 'Value' at this input. inputTreasury :: Int -> Value -> TxInInfo inputTreasury indx val = TxInInfo @@ -97,6 +98,7 @@ inputTreasury indx val = , txOutDatumHash = Just (DatumHash "") } +-- | Create a input given the index of the user and the 'Value' at this input. inputUser :: Int -> Value -> TxInInfo inputUser indx val = TxInInfo @@ -107,6 +109,7 @@ inputUser indx val = , txOutDatumHash = Just (DatumHash "") } +-- | Create a input representing the collateral given by a user. inputCollateral :: Int -> TxInInfo inputCollateral indx = TxInInfo -- Initiator @@ -117,6 +120,7 @@ inputCollateral indx = , txOutDatumHash = Just (DatumHash "") } +-- | Create an output at the nth treasury with the given 'Value'. outputTreasury :: Int -> Value -> TxOut outputTreasury indx val = TxOut @@ -125,6 +129,7 @@ outputTreasury indx val = , txOutDatumHash = Nothing } +-- | Create an output at the nth user with the given 'Value'. outputUser :: Int -> Value -> TxOut outputUser indx val = TxOut @@ -133,6 +138,7 @@ outputUser indx val = , txOutDatumHash = Nothing } +-- | Create a list of the outputs that are required as encoded in 'TreasuryWithdrawalDatum'. buildReceiversOutputFromDatum :: TreasuryWithdrawalDatum -> [TxOut] buildReceiversOutputFromDatum (TreasuryWithdrawalDatum xs _) = f <$> xs where @@ -147,7 +153,7 @@ buildReceiversOutputFromDatum (TreasuryWithdrawalDatum xs _) = f <$> xs validator :: Validator validator = mkValidator $ treasuryWithdrawalValidator currSymbol --- | 'TokenName' that represents the hash of the 'Stake' validator. +-- | 'TokenName' that represents the hash of the 'Agora.Stake.Stake' validator. validatorHashTN :: TokenName validatorHashTN = let ValidatorHash vh = validatorHash validator in TokenName vh diff --git a/agora-specs/Spec/AuthorityToken.hs b/agora-specs/Spec/AuthorityToken.hs index f09c9bc..6fa6756 100644 --- a/agora-specs/Spec/AuthorityToken.hs +++ b/agora-specs/Spec/AuthorityToken.hs @@ -69,6 +69,7 @@ singleAuthorityTokenBurnedTest mint outs = perror in compile s +-- | The SpecificationTree exported by this module. specs :: [SpecificationTree] specs = [ -- This is better suited for plutarch-test diff --git a/agora-specs/Spec/Governor.hs b/agora-specs/Spec/Governor.hs index 2cf0f9c..ca5f5d5 100644 --- a/agora-specs/Spec/Governor.hs +++ b/agora-specs/Spec/Governor.hs @@ -28,6 +28,7 @@ import Test.Specification ( -------------------------------------------------------------------------------- +-- | The SpecificationTree exported by this module. specs :: [SpecificationTree] specs = [ group diff --git a/agora-specs/Spec/Stake.hs b/agora-specs/Spec/Stake.hs index c91cfab..169ad3f 100644 --- a/agora-specs/Spec/Stake.hs +++ b/agora-specs/Spec/Stake.hs @@ -34,6 +34,7 @@ import Test.Util (toDatum) -------------------------------------------------------------------------------- +-- | The SpecificationTree exported by this module. specs :: [SpecificationTree] specs = [ group diff --git a/agora-testlib/Test/Util.hs b/agora-testlib/Test/Util.hs index 030ae28..96baaa1 100644 --- a/agora-testlib/Test/Util.hs +++ b/agora-testlib/Test/Util.hs @@ -34,11 +34,11 @@ import PlutusTx.Ord qualified as PlutusTx -------------------------------------------------------------------------------- -{- | Create a pair from data for use in 'txInfoData'. +{- | Create a pair from data for use in 'Plutus.V1.Ledger.Contexts.txInfoData'. Example: @ - myTxInfo { 'txInfoData' = ['datumPair' myDatum] } + myTxInfo { 'Plutus.V1.Ledger.Contexts.txInfoData' = ['datumPair' myDatum] } @ -} datumPair :: PlutusTx.ToData a => a -> (DatumHash, Datum) diff --git a/agora/Agora/Governor.hs b/agora/Agora/Governor.hs index 0c5e5d7..f93414f 100644 --- a/agora/Agora/Governor.hs +++ b/agora/Agora/Governor.hs @@ -183,6 +183,7 @@ getNextProposalId (ProposalId pid) = ProposalId $ pid + 1 -------------------------------------------------------------------------------- +-- | Check whether a particular 'PGovernorDatum' is well-formed. governorDatumValid :: Term s (PGovernorDatum :--> PBool) governorDatumValid = phoistAcyclic $ plam $ \datum -> unTermCont $ do diff --git a/agora/Agora/Governor/Scripts.hs b/agora/Agora/Governor/Scripts.hs index e42c28c..e8e7d52 100644 --- a/agora/Agora/Governor/Scripts.hs +++ b/agora/Agora/Governor/Scripts.hs @@ -203,15 +203,15 @@ governorPolicy gov = - The UTXO which holds the GST must be spent. - The GST always stays at the validator's address. - - The new state UTXO has a valid datum of type 'GovernorDatum'. + - The new state UTXO has a valid datum of type 'Agora.Governor.GovernorDatum'. == Creating a Proposal - When the redeemer is 'CreateProposal', the script will check: + When the redeemer is 'Agora.Governor.CreateProposal', the script will check: - For governor's state datum: - * 'nextProposalId' is advanced. + * 'Agora.Governor.nextProposalId' is advanced. * Nothing is changed other that that. - Exactly one stake (the "input stake") must be provided in the input: @@ -236,7 +236,7 @@ governorPolicy gov = == Minting GATs - When the redeemer is 'MintGATs', the script will check: + When the redeemer is 'Agora.Governor.MintGATs', the script will check: - Governor's state is not changed. - Exactly only one proposal is in the inputs. Let's call this the /input proposal/. @@ -272,7 +272,7 @@ governorPolicy gov = == Changing the State - Redeemer 'MutateGovernor' allows the state datum to be changed by an external effect. + Redeemer 'Agora.Governor.MutateGovernor' allows the state datum to be changed by an external effect. In this case, the script will check diff --git a/agora/Agora/Proposal.hs b/agora/Agora/Proposal.hs index 7c893a5..0c58053 100644 --- a/agora/Agora/Proposal.hs +++ b/agora/Agora/Proposal.hs @@ -352,7 +352,7 @@ deriving via instance (PConstantDecl ProposalVotes) --- Plutarch-level version of 'emptyVotesFor'. +-- | Plutarch-level version of 'emptyVotesFor'. pemptyVotesFor :: forall s a. (PIsData a) => Term s (PMap PResultTag a :--> PProposalVotes) pemptyVotesFor = phoistAcyclic $ @@ -451,7 +451,7 @@ proposalDatumValid proposal = , ptraceIfFalse "Proposal votes and effects are compatible with each other" $ pkeysEqual # datum.effects # pto (pfromData datum.votes) ] -{- Find the winner result tag, given the votes, the quorum the "neutral" result tag. +{- | Find the winner result tag, given the votes, the quorum the "neutral" result tag. The winner should be unambiguous, meaning that if two options have the same highest votes, the "neutral" option will be the winner. diff --git a/agora/Agora/Proposal/Time.hs b/agora/Agora/Proposal/Time.hs index c524546..704ca9e 100644 --- a/agora/Agora/Proposal/Time.hs +++ b/agora/Agora/Proposal/Time.hs @@ -83,7 +83,7 @@ data ProposalTimingConfig = ProposalTimingConfig PlutusTx.makeIsDataIndexed ''ProposalTimingConfig [('ProposalTimingConfig, 0)] --- | Represents the maximum width of a 'POSIXTimeRange'. +-- | Represents the maximum width of a 'Plutus.V1.Ledger.Time.POSIXTimeRange'. newtype MaxTimeRangeWidth = MaxTimeRangeWidth {getMaxWidth :: POSIXTime} deriving stock (Eq, Show, Ord, GHC.Generic) deriving newtype (PlutusTx.ToData, PlutusTx.FromData, PlutusTx.UnsafeFromData) @@ -101,15 +101,19 @@ newtype MaxTimeRangeWidth = MaxTimeRangeWidth {getMaxWidth :: POSIXTime} determine if we are able to perform certain actions, we need to know what time it roughly is, compared to when the proposal was created. - 'ProposalTime' represents "the time according to the proposal". + 'PProposalTime' represents "the time according to the proposal". Its representation is opaque, and doesn't matter. - Various functions work simply on 'ProposalTime' and 'ProposalTimingConfig'. + Various functions work simply on 'PProposalTime' and 'ProposalTimingConfig'. In particular, 'currentProposalTime' is useful for extracting the time from the 'Plutus.V1.Ledger.Api.txInfoValidPeriod' field of 'Plutus.V1.Ledger.Api.TxInfo'. We avoid 'PPOSIXTimeRange' where we can in order to save on operations. + + Note: 'PProposalTime' doesn't need a Haskell-level equivalent because it + is only used in scripts, and does not go in datums. It is also scott-encoded + which is more efficient in usage. -} data PProposalTime (s :: S) = PProposalTime { lowerBound :: Term s PPOSIXTime diff --git a/agora/Agora/Utils.hs b/agora/Agora/Utils.hs index 5a9b17b..e939ead 100644 --- a/agora/Agora/Utils.hs +++ b/agora/Agora/Utils.hs @@ -687,5 +687,6 @@ mustBePDJust = phoistAcyclic $ PDJust ((pfield @"_0" #) -> v) -> v _ -> ptraceError emsg +-- | Create an 'Address' from a given 'ValidatorHash' with no 'Plutus.V1.Ledger.Credential.StakingCredential'. validatorHashToAddress :: ValidatorHash -> Address validatorHashToAddress vh = Address (ScriptCredential vh) Nothing