Add documentation for total collateral and return collateral.

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

@@ -291,7 +291,7 @@ isValidToScriptValidity (Alonzo.IsValid True) = ScriptValid
 
 -- | A representation of whether the era supports tx script validity.
 --
--- The Mary and subsequent eras support script validity.
+-- The Alonzo and subsequent eras support script validity.
 --
 data TxScriptValidity era where
   TxScriptValidityNone :: TxScriptValidity era

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

@@ -12,6 +12,12 @@ An inline datum, is a datum that exists at a transaction output. We no longer ha
 
 In the case where we are not using a reference input to reference another transaction input (at a Plutus script address), we can specify a read only reference input that is simply exposed in the Plutus script context.
 
+## What are total and return collateral?
+
+The total collateral field lets users write transactions whose collateral is evident by just looking at the tx body instead of requiring information in the UTxO. The specification of total collateral is optional. It does not change how the collateral is computed but transactions whose collateral is different than the amount specified will be invalid.
+
+Return collateral allows us to specify an output with the remainder of our collateral input(s) in the event we overcollateralize our transaction. This allows us to avoid overpaying the collateral.
+
 ### An example of using a Plutus V2 reference script
 
 Below is an example that shows how to use a reference Plutus spending script with an inline datum and a reference minting script. Here we discuss a [shell script example of how to use a reference script to spend a tx input and a reference minting script to mint tokens](../../../scripts/babbage/example-babbage-script-usage.sh). This is a step-by-step process involving:
@@ -158,7 +164,8 @@ Because we are using the `build` command, we should only note the following:
 `mint-plutus-script-v2` - This specifies the version of the reference script at the reference input.
 `mint-reference-tx-in-redeemer-file` - This is the redeemer to be used with the reference script.
 `policy-id` - Because we do not have direct access to the minting script we must specify the policy id.
-
+`tx-total-collateral` - This is the total required collateral for our transaction. This can be computed by multiplying the `collateralPercentage` and the transaction fee.
+`tx-out-return-collateral` - If our collateral inputs over collateralize our transaction, we can return the excess to ourselves via this cli option.
 
 ```bash
 cardano-cli transaction build \
@@ -169,6 +176,8 @@ cardano-cli transaction build \
   --read-only-tx-in-reference "$readonlyrefinput" \
   --tx-in "$txin1" \
   --tx-in-collateral "$txinCollateral" \
+  --tx-total-collateral 529503 \
+  --tx-out-return-collateral "$utxoaddr+$returncollateral" \
   --out-file "$WORK/test-alonzo-ref-script.body" \
   --tx-in "$plutuslockedutxotxin" \
   --spending-tx-in-reference "$plutusreferencescripttxin" \

scripts/babbage/example-babbage-script-usage.sh

@@ -10,8 +10,8 @@ export BASE="${BASE:-.}"
 export CARDANO_CLI="${CARDANO_CLI:-cardano-cli}"
 export CARDANO_NODE_SOCKET_PATH="${CARDANO_NODE_SOCKET_PATH:-example/node-spo1/node.sock}"
 export TESTNET_MAGIC="${TESTNET_MAGIC:-42}"
-export UTXO_VKEY="${UTXO_VKEY:-example/stake-delegator-keys/payment1.vkey}"
-export UTXO_SKEY="${UTXO_SKEY:-example/stake-delegator-keys/payment1.skey}"
+export UTXO_VKEY="${UTXO_VKEY:-example/utxo-keys/utxo1.vkey}"
+export UTXO_SKEY="${UTXO_SKEY:-example/utxo-keys/utxo1.skey}"
 export RESULT_FILE="${RESULT_FILE:-$WORK/result.out}"
 
 echo "Socket path: $CARDANO_NODE_SOCKET_PATH"
@@ -41,7 +41,7 @@ echo "Plutus Script Address"
 echo "$plutusspendingscriptaddr"
 mkdir -p "$WORK"
 
-utxoaddr=$($CARDANO_CLI address build --testnet-magic "$TESTNET_MAGIC" --payment-verification-key-file "$UTXO_VKEY" --stake-verification-key-file example/stake-delegator-keys/staking1.vkey)
+utxoaddr=$($CARDANO_CLI address build --testnet-magic "$TESTNET_MAGIC" --payment-verification-key-file "$UTXO_VKEY")
 
 $CARDANO_CLI query utxo --address "$utxoaddr" --cardano-mode --testnet-magic "$TESTNET_MAGIC" --out-file $WORK/utxo-1.json
 cat $WORK/utxo-1.json
@@ -103,9 +103,7 @@ $CARDANO_CLI query utxo --address "$utxoaddr" --cardano-mode --testnet-magic "$T
 
 txin1=$(jq -r 'keys[0]' $WORK/utxo-2.json)
 txinCollateral=$(jq -r 'keys[1]' $WORK/utxo-2.json)
-lovelaceattxin1=$(jq -r ".[\"$txin1\"].value.lovelace" $WORK/utxo-2.json)
-lovelaceattxindiv31=$(expr $lovelaceattxin1 / 3)
-
+suppliedCollateral=$(jq -r ".[\"$txinCollateral\"].value.lovelace" $WORK/utxo-2.json)
 
 # Get input at plutus script that we will attempt to spend
 $CARDANO_CLI query utxo --address $plutusspendingscriptaddr --testnet-magic "$TESTNET_MAGIC" --out-file $WORK/plutusutxo.json
@@ -124,16 +122,17 @@ mintingscriptrefinput=$(jq -r 'keys[0]' $WORK/minting-script-ref-input-utxo.json
 
 echo "Plutus txin"
 echo "$plutuslockedutxotxin"
-
+echo ""
 echo "Collateral"
 echo "$txinCollateral"
-
+echo "$suppliedCollateral"
+echo ""
 echo "Funding utxo"
 echo "$txin1"
-
+echo ""
 echo "Plutus reference script txin"
 echo "$plutusreferencescripttxin"
-
+echo ""
 echo "Plutus input we are trying to spend"
 echo "$plutuslockedutxotxin"
 
@@ -157,6 +156,10 @@ echo "$mintpolicyid"
 #  --tx-out "$utxoaddr+149988741087" \
 #  --fee "1000000" \
 #  --protocol-params-file "$WORK/pparams.json"
+#   --tx-out-return-collateral
+#
+returncollateral=$(expr $suppliedCollateral - 529503)
+
 
 $CARDANO_CLI transaction build \
   --babbage-era \
@@ -166,6 +169,8 @@ $CARDANO_CLI transaction build \
   --read-only-tx-in-reference  "$readonlyrefinput" \
   --tx-in "$txin1" \
   --tx-in-collateral "$txinCollateral" \
+  --tx-total-collateral 529503 \
+  --tx-out-return-collateral "$utxoaddr+$returncollateral" \
   --out-file "$WORK/test-alonzo-ref-script.body" \
   --tx-in "$plutuslockedutxotxin" \
   --spending-tx-in-reference "$plutusreferencescripttxin" \

scripts/babbage/mkfiles.sh

@@ -139,21 +139,13 @@ jq --raw-output '.protocolConsts.protocolMagic = 42' "${ROOT}/genesis/byron/gene
 
 rm "${ROOT}/genesis/byron/genesis-wrong.json"
 
+cp "${ROOT}/genesis/shelley/genesis.json" "${ROOT}/genesis/shelley/copy-genesis.json"
 
-$SED -i "${ROOT}/genesis/shelley/genesis.json" \
-    -e 's/"slotLength": 1/"slotLength": 0.1/' \
-    -e 's/"activeSlotsCoeff": 5.0e-2/"activeSlotsCoeff": 0.1/' \
-    -e 's/"securityParam": 2160/"securityParam": 10/' \
-    -e 's/"epochLength": 432000/"epochLength": 500/' \
-    -e 's/"maxLovelaceSupply": 0/"maxLovelaceSupply": 1000000000000/' \
-    -e 's/"minFeeA": 1/"minFeeA": 44/' \
-    -e 's/"minFeeB": 0/"minFeeB": 155381/' \
-    -e 's/"minUTxOValue": 0/"minUTxOValue": 1000000/' \
-    -e 's/"decentralisationParam": 1.0/"decentralisationParam": 0.7/' \
-    -e 's/"major": 0/"major": 7/' \
-    -e 's/"rho": 0.0/"rho": 0.1/' \
-    -e 's/"tau": 0.0/"tau": 0.1/' \
-    -e 's/"updateQuorum": 5/"updateQuorum": 2/'
+jq -M '. + {slotLength:0.1, securityParam:10, activeSlotsCoeff:0.1, securityParam:10, epochLength:500, maxLovelaceSupply:1000000000000, updateQuorum:2}' "${ROOT}/genesis/shelley/copy-genesis.json" > "${ROOT}/genesis/shelley/copy2-genesis.json"
+jq --raw-output '.protocolParams.protocolVersion.major = 7 | .protocolParams.minFeeA = 44 | .protocolParams.minFeeB = 155381 | .protocolParams.minUTxOValue = 1000000 | .protocolParams.decentralisationParam = 0.7 | .protocolParams.rho = 0.1 | .protocolParams.tau = 0.1' "${ROOT}/genesis/shelley/copy2-genesis.json" > "${ROOT}/genesis/shelley/genesis.json"
+
+rm "${ROOT}/genesis/shelley/copy2-genesis.json"
+rm "${ROOT}/genesis/shelley/copy-genesis.json"
 
 mv "${ROOT}/pools/vrf1.skey" "${ROOT}/node-spo1/vrf.skey"
 mv "${ROOT}/pools/vrf2.skey" "${ROOT}/node-spo2/vrf.skey"