Review changes

Author: Jimbo4350

docs/ADR-10-cardano-api-script-witness-api.md

@@ -73,12 +73,35 @@ data Witnessable thing era where
     => Voter -> Witnessable Voter era
   WitProposal :: L.ConwayEraScript era => Proposal -> Witnessable Proposal era
 
+instance Ord (Witnessable thing era) where
+  compare a b =
+    case (a, b) of
+      (WitTxIn txinA, WitTxIn txinB) -> compare txinA txinB
+      (WitTxCert (certA, _), WitTxCert (certB, _)) -> compare certA certB
+      (WitMint mintA, WitMint mintB) -> compare mintA mintB
+      (WitWithdrawal (stakeAddrA, _), WitWithdrawal (stakeAddrB, _)) -> compare stakeAddrA stakeAddrB
+      (WitVote voterA, WitVote voterB) -> compare voterA voterB
+      (WitProposal propA, WitProposal propB) -> compare propA propB
+
+type Mint = (PolicyId, AssetName, Quantity)
+
+type Withdrawal = (StakeAddress, L.Coin)
+
+type Cert = (AnyCertificate, StakeCredential)
+
+type Voter = Api.AnyVoter
+
+type Proposal = Api.AnyProposal
+
+
 data AnyWitness era where
   AnyKeyWitness :: AnyWitness era
   AnySimpleScriptWitness :: SimpleScriptOrReferenceInput era -> AnyWitness era
   AnyPlutusScriptWitness :: PlutusScriptWitness lang purpose era -> AnyWitness era
 ```
 
+NB: See `class GetPlutusScriptPurpose` to understand the purpose of the ledger constraints in `Witnessable thing era` constructor.
+
 And the upshot is once we have `[(Witnessable thing era, AnyWitness era)]` these can be uniformly treated to construct the redeemer pointer map (`Redeemers era`):
 
 ```haskell
@@ -96,6 +119,16 @@ getTxScriptWitnessesRequirements
   -> TxScriptWitnessRequirements (ShelleyLedgerEra era)
 getTxScriptWitnessesRequirements eon wits =
   obtainMonoidConstraint eon $ mconcat $ map (getTxScriptWitnessRequirements eon) wits
+
+
+obtainMonoidConstraint
+  :: AlonzoEraOnwards era
+  -> (Monoid (TxScriptWitnessRequirements (ShelleyLedgerEra era)) => a)
+  -> a
+obtainMonoidConstraint eon = case eon of
+  AlonzoEraOnwardsAlonzo -> id
+  AlonzoEraOnwardsBabbage -> id
+  AlonzoEraOnwardsConway -> id
 ```
 
 ## New `IndexedPlutusScriptWitness` types
@@ -112,7 +145,7 @@ data IndexedPlutusScriptWitness witnessable (lang :: L.Language) (purpose :: Plu
 ```
 
 We do away with `cardano-api`'s `ScriptWitnessIndex` and directly use `cardano-ledger`'s `PlutusPurpose AsIx era` which is essentially the same thing. 
-The benefit here is we get to use ledger type classes to calculate the index of the plutus script witness thing we are interested in:
+The benefit here is we get to use ledger type classes to produce the index of the plutus script witness thing we are interested in:
 
 ```haskell
 class GetPlutusScriptPurpose era where
@@ -130,6 +163,8 @@ instance GetPlutusScriptPurpose era where
   toPlutusScriptPurpose index WitProposal{} = L.mkProposingPurpose (L.AsIx index)
 ```
 
+The ledger constraints in the `Witnessable thing era` data constructors allow us to directly construct the script witness index (`PlutusPurpose AsIx era`) with the  `toPlutusScriptPurpose` class method. We no longer have to use the old api's `ScriptWitnessIndex` which is eventually converted into a `PlutusPurpose AsIx era`. This approach is more direct.
+
 This ultimately allows us to collapse all of the different index calculation functions into a single function:
 
 ```haskell
@@ -148,7 +183,10 @@ createIndexedPlutusScriptWitnesses witnessableThings =
   [ AnyIndexedPlutusScriptWitness $ createIndexedPlutusScriptWitness index thing sWit
   | (index, (thing, AnyPlutusScriptWitness sWit)) <- zip [0 ..] witnessableThings
   ]
+ where
+  enforceOrdering = List.sortBy (compare `on` fst)
 ```
+
 ## New `PlutusScriptInEra` type 
 
 
@@ -157,7 +195,23 @@ data PlutusScriptInEra (lang :: L.Language) era where
   PlutusScriptInEra :: PlutusRunnable lang -> PlutusScriptInEra lang era
 ```
 
-Why PlutusRunnable? Mainly for deserialization benefits. The deserialization of this type looks at the major protocol version and the script language to determine if indeed the script is runnable.
+Why PlutusRunnable? Mainly for deserialization benefits. The deserialization of this type looks at the major protocol version and the script language to determine if indeed the script is runnable. This is the decode CBOR instance in `cardano-ledger`: 
+
+```haskell
+instance PlutusLanguage l => DecCBOR (PlutusRunnable l) where
+  decCBOR = do
+    plutus <- decCBOR
+    pv <- getDecoderVersion
+    either (fail . show) pure $ decodePlutusRunnable pv plutus
+```
+`decodePlutusRunnable` eventually calls a deserialization function in the `plutus` repo which will fail if 
+the plutus script version you are using is not available in a given era. 
+
+A ficticious example: The plutus team introduces PlutusV4. This plutus script version can only be used in the era after Conway (Conway + 1).
+However a user tries to use a PlutusV4 script in Conway. Because we use `PlutusRunnable` to represent our plutus scripts we would get a deserialization error.
+If we stuck with `ShortByteString` to represent plutus scripts, the error would only occur at transaction submission or when using `transaction build`. 
+This is a small QOL improvement as now if your script deserializes at least you know it's valid for a particular era.
+
 
 ## New `PlutusScriptDatum` type