Review fixes + documentation fixes

cardano-api/src/Cardano/Api/Script.hs

@@ -966,7 +966,7 @@ fromShelleyScriptHash = ScriptHash
 
 
 -- ----------------------------------------------------------------------------
--- The simple native script language
+-- The simple script language
 --
 
 data SimpleScript lang where

cardano-cli/src/Cardano/CLI/Shelley/Parsers.hs

@@ -256,15 +256,13 @@ pPlutusReferenceScriptWitnessFiles witctx autoBalanceExecUnits =
   pAnyScriptLang =
     Opt.flag' (AnyScriptLanguage $ SimpleScriptLanguage SimpleScriptV1)
       (  Opt.long "simple-script-v1"
-      <> Opt.help "Specify a simple script v1 reference script."
+      <> Opt.help "Specify a simple script v1 reference script. \
+                  \See documentation at doc/reference/simple-scripts.md"
       ) <|>
     Opt.flag' (AnyScriptLanguage $ SimpleScriptLanguage SimpleScriptV2)
       (  Opt.long "simple-script-v2"
-      <> Opt.help "Specify a simple script v2 reference script."
-      ) <|>
-    Opt.flag' (AnyScriptLanguage $ PlutusScriptLanguage PlutusScriptV1)
-      (  Opt.long "plutus-script-v1"
-      <> Opt.help "Specify a plutus script v1 reference script."
+      <> Opt.help "Specify a simple script v2 reference script. \
+                  \See documentation at doc/reference/simple-scripts.md"
       ) <|>
     Opt.flag' (AnyScriptLanguage $ PlutusScriptLanguage PlutusScriptV2)
       (  Opt.long "plutus-script-v2"
@@ -2189,7 +2187,7 @@ pTxOutDatum =
 pRefScriptFp :: Parser ReferenceScriptAnyEra
 pRefScriptFp =
   ReferenceScriptAnyEra <$> Opt.strOption
-    (  Opt.long "reference-script-file"
+    (  Opt.long "tx-out-reference-script-file"
     <> Opt.metavar "FILE"
     <> Opt.help "Reference script input file."
     <> Opt.completer (Opt.bashCompleter "file")

cardano-cli/src/Cardano/CLI/Shelley/Run/Transaction.hs

@@ -273,7 +273,7 @@ renderShelleyTxCmdError err =
       "Execution units not available in the protocol parameters. This is \
       \likely due to not being in the Alonzo era"
     ShelleyTxCmdReferenceScriptsNotSupportedInEra (AnyCardanoEra era) ->
-      "Reference scripts not supported in era: " <> show era
+      "TxCmd: Reference scripts not supported in era: " <> show era
 
 renderEra :: AnyCardanoEra -> Text
 renderEra (AnyCardanoEra ByronEra)   = "Byron"
@@ -391,13 +391,18 @@ runTxBuildRaw (AnyCardanoEra era)
               metadataFiles mpparams mUpdatePropFile
               outputFormat
               (TxBodyFile fpath) = do
+    let referenceInputsWithWits = [ (input, wit)
+                                  | (_, wit@(Just (PlutusReferenceScriptWitnessFiles input _ _ _ _)))
+                                       <- inputsAndScripts
+                                  ]
+
     txBodyContent <-
       TxBodyContent
         <$> validateTxIns  era inputsAndScripts
         <*> validateTxInsCollateral
                            era inputsCollateral
         <*> validateTxInsReference
-                           era inputsAndScripts
+                           era referenceInputsWithWits
         <*> validateTxOuts era txouts
         <*> validateTxTotalCollateral era mTotCollateral
         <*> validateTxReturnCollateral era mReturnCollateral
@@ -474,14 +479,18 @@ runTxBuild (AnyCardanoEra era) (AnyConsensusModeParams cModeParams) networkId mS
       consensusMode = consensusModeOnly cModeParams
       dummyFee = Just $ Lovelace 0
       inputsThatRequireWitnessing = [input | (input,_) <- txins]
-      referenceInputs = [input | (_, Just (PlutusReferenceScriptWitnessFiles input _ _ _ _)) <- txins]
+      referenceInputsWithWits = [ (input, wit)
+                                | (_, wit@(Just (PlutusReferenceScriptWitnessFiles input _ _ _ _)))
+                                    <- txins
+                                ]
+      referenceInputs = map fst referenceInputsWithWits
   case (consensusMode, cardanoEraStyle era) of
     (CardanoMode, ShelleyBasedEra sbe) -> do
       txBodyContent <-
         TxBodyContent
           <$> validateTxIns               era txins
           <*> validateTxInsCollateral     era txinsc
-          <*> validateTxInsReference      era txins
+          <*> validateTxInsReference      era referenceInputsWithWits
           <*> validateTxOuts              era txouts
           <*> validateTxTotalCollateral   era mtotcoll
           <*> validateTxReturnCollateral  era mReturnCollateral

doc/reference/plutus/reference-script-example.md

@@ -2,16 +2,16 @@
 
 ## What is a reference script?
 
-A reference script is a script that exists at a particular transaction output. It can be used to witness, for example, a UTxO at the corresponding script address of said reference script. Why is this useful? It means we no longer have to include the script in the transaction, greatly reducing its size
+A reference script is a script that exists at a particular transaction output. It can be used to witness, for example, a UTxO at the corresponding script address of said reference script. This is useful because the script does not have to be included in the transaction anymore, which significantly reduces the transaction size.
 
 ### An example of using a Plutus V2 reference script
 
-Below is an example that shows how to use a Plutus spending script. We will walk though the [shell script example of how to use a reference script to spend a tx input](scripts/plutus/example-reference-script-usage.sh).This is a step-by-step process involving:
+Below is an example that shows how to use a Plutus spending script. Here we discuss a [shell script example of how to use a reference script to spend a tx input](scripts/plutus/example-reference-script-usage.sh). This is a step-by-step process involving:
 
 + the creation of the `Required Redeemer` Plutus txin script
 + the creation of the `Required Redeemer` Plutus script at a transaction output (creation of the reference script)
-+ sending ADA and a datum to the Plutus script address
-+ spending ADA at the Plutus script address using the Plutus reference script
++ sending ada and a datum to the Plutus script address
++ spending ada at the Plutus script address using the Plutus reference script
 
 In this example we will use the [Required Redeemer](scripts/plutus/scripts/v2/required-redeemer.plutus) Plutus spending script. In order to execute a reference Plutus spending script, we require the following:
 
@@ -47,13 +47,14 @@ cabal install cardano-node
 ./scripts/babbage/mkfiles.sh
 ```
 
-To start your babbage cluster you need to run the `example/run/all.sh` shell script.
-The remainder of this guide briefly talks about the [shell script example](scripts/plutus/example-reference-script-usage.sh) that automatically does everything for you.
+To start your babbage cluster, you need to run the `example/run/all.sh` shell script.
+The remainder of this guide provides a brief walkthrough of the [shell script example](scripts/plutus/example-reference-script-usage.sh) that automatically creates a reference script and spends the utxo at
+the reference script's corresponding script address.
 
 #### Creating a reference script at a transaction output and
-#### sending ADA to the script address (with a datum)
+#### sending ada to the script address (with a datum)
 
-In order to use a reference script we must first create said reference script at a particular address. Note you cannot create a reference script at the same correspnding script address, this will result in a failure when trying to spend the transaction input at the script address.
+In order to use a reference script, we must first create this script at a particular transaction output.
 
 ```bash
 cardano-cli transaction build \
@@ -66,13 +67,14 @@ cardano-cli transaction build \
   --tx-out "$plutusscriptaddr+$lovelace" \
   --tx-out-datum-hash "$scriptdatumhash" \
   --tx-out "$dummyaddress+$lovelaceattxindiv3" \
-  --reference-script-file "$plutusscriptinuse" \
+  --tx-out-reference-script-file "$plutusscriptinuse" \
   --protocol-params-file "$WORK/pparams.json" \
   --out-file "$WORK/create-datum-output.body"
 ```
 
-There are a couple things happening in the following `build` command.
-Firstly we are sending ADA to the plutus script address along with a datum. This is reflected in the following lines:
+The following should be noted about this build command:
+
+Firstly, we are sending ada to the plutus script address along with a datum hash. This is reflected in the following lines:
 
 ```bash
 ...
@@ -83,12 +85,12 @@ Firstly we are sending ADA to the plutus script address along with a datum. This
 
 We have seen this before in the [plutus-spending-script-example.md](doc/reference/plutus/plutus-spending-script-example.md).
 
-Secondly we are creating a reference script at an address, which cannot be the same as the reference script address, of our choosing in the following lines:
+Secondly, we are creating a reference script at a tx output:
 
 ```bash
 ...
 --tx-out "$dummyaddress+$lovelaceattxindiv3" \
---reference-script-file "$plutusscriptinuse" \
+--tx-out-reference-script-file "$plutusscriptinuse" \
 ...
 ```
 
@@ -105,14 +107,14 @@ cardano-cli transaction sign \
 ```
 
 
-#### Spending ADA at the script address
+#### Spending ada at the script address
 
-Now that there is ADA at our script address, we must construct the appropriate transaction in order to spend it.
-Because we are using the `build` command we only have to concern ourselves with the following:
+Now that there is ada at our script address, we must construct the appropriate transaction in order to spend it.
+Because we are using the `build` command, we should only note the following:
 
 `$plutusutxotxin` - This is the tx input that sits at the Plutus script address (NB: It has a datum hash).
-`tx-in-reference` -This specifies the reference input you are using to witness a transaction input.
-`plutus-script-v2`- This specifies the version of the reference script at the reference input. There are no restrictions on the type of script we can have at a reference input.
+`tx-in-reference` - This specifies the reference input you are using to witness a transaction input.
+`plutus-script-v2`- This specifies the version of the reference script at the reference input.
 `reference-tx-in-datum-file` - This is the datum to be used with the reference script.
 `reference-tx-in-redeemer-file` - This is the redeemer to be used with the reference script.
 
@@ -140,7 +142,7 @@ cardano-cli transaction sign \
   --out-file $WORK/alonzo-ref-script.tx
 ```
 
-If there is ADA at `$dummyaddress2` then the Plutus script was successfully executed. Conversely, if the Plutus script failed, the collateral input would have been consumed.
+If there is ada at `$dummyaddress2`, then the Plutus script was successfully executed. Conversely, if the Plutus script failed, the collateral input would have been consumed.
 
 You can use the [example-txin-locking-plutus-script.sh](../../../scripts/plutus/example-txin-locking-plutus-script.sh) in conjunction with [mkfiles.sh alonzo](../../../scripts/byron-to-alonzo/mkfiles.sh) script to automagically run the `AlwaysSucceeds` script.
 

scripts/plutus/example-reference-script-usage.sh

@@ -63,7 +63,7 @@ $CARDANO_CLI transaction build \
   --tx-out "$plutusscriptaddr+$lovelaceattxindiv3" \
   --tx-out-datum-hash "$scriptdatumhash" \
   --tx-out "$dummyaddress+$lovelaceattxindiv3" \
-  --reference-script-file "$plutusscriptinuse" \
+  --tx-out-reference-script-file "$plutusscriptinuse" \
   --protocol-params-file "$WORK/pparams.json" \
   --out-file "$WORK/create-datum-output.body"