ADR 9: Support return and total collateral when building transactions
In Babbage era (available after the Vasil HF), Cardano transactions will contain new collateral related fields: “return collateral” and “total collateral” collateral. Return collateral (also called “collateral output”) and total collateral are detailed in CIP-40.
In summary, return collateral is a special output (basically of type
TxOut) that becomes available in case there is a failed phase-2 validation.
In addition, we have the new total collateral field which explicitly says how much collateral (in lovelace) is going to be actually consumed in the case of phase-2 validation failure.
We will add the
txTotalCollateralfields in the Ledger.Tx.Internal.Tx data type.
We will modify the
Wallet.Emulator.Wallet.handleBalancefunction in plutus-contract to set the correct return and total collateral for an
Either CardanoBuildTx EmulatorTx). In either type of transaction, we would compute the
txTotalCollateralwhile estimating the fee with the formula
quot (txfee txb * (collateralPercent pp)) * 100and then set
txReturnCollateralwith the formula
sum collateralInputs - txTotalCollateral.
As the user would want to pay the least amount of collateral, we made the decision to modify the balancing algorithm to automatically set the return collateral to the highest possible value.
The main alternative would have been to add a new constraint such as
MustReturnCollateral TxOut in the constraints library to allow the users to specify the return collateral themselves.
However, as explained in the Argument section, users would always want to pay the least amount of collateral.
Therefore we don’t expect the need to set the return collateral manually.