CIP-40 Collateral outputs

[dorin100]

TODO Improvements:
1265
1266
1267

cardano-node related PR:
#3810

info
https://github.com/cardano-foundation/CIPs/pull/216/files
https://input-output.atlassian.net/browse/CAD-3415

AC1 Possible to define the total collateral amount and the collateral output

1. Build a tx with: return-collateral-tx-out, collateral inputs higher than expected, the right amount on tx-total-collateral; check that only the necessary amount is charged and the change is present on the return-collateral-tx-out specified
   • using build
   • using build-raw
2. Build a tx with collateral inputs higher than expected with the same amount on tx-total-collateral without return-collateral-tx-out defined, check that all the collateral are charged.
   • using build
   • using build-raw
3. Build a tx withtx-total-collateraldifferent than tx with collateral inputs amount (fails phase1 validation) - Expect failure PBT
   • using build
   • using build-raw
4. Build a tx with with collateral inputs higher than expected with return-collateral-tx-out defined but without tx-total-collateral defined, check that only the necessary amount is charged and the change is present on the return-collateral-tx-out specified
   • using build
   • using build-raw

AC2 collateral input can include MA which is returned on validation failure

1. When the collateral output is provided then collateral input can include MA which is returned on validation failure (the error message should be meaningful for the end-user)
   • using build
   • using build-raw

AC3 Collateral output needs to be balanced

1. Collateral output needs to be balanced according to sum(collateral_input) = sum(collateral_output) + collateral_consumed
   • using build
   • using build-raw

[catch-21]

Collateral return

• Collateral return is not related to HW wallet
• Collateral return is optional
• When collateral return is not provided then Alonzo-rules apply (collateral is ada-only and all ada is taken as fee)
• When collateral return is provided then excess ada is returned
• When collateral return is provided then collateral input can include MA which is returned on validation failure
• If return collateral doesn't satisfy minUtxo constraint then submit fails phase1 validation

Colateral total

• Collateral total is useful for HW wallets
• Collateral total is optional
• Collateral total must equal total collateral to be taken on phase2 validation failure (it'll be different depending on whether collateral return is provided)
• If collateral total value is incorrect then submit fails phase1 validation

[catch-21]

This is probably close enough related cardano-foundation/CIPs#216

[vfrsilva]

@dorin100 lets please make sure that:

1. If return collateral doesn't satisfy minUtxo constraint, then submit fails phase1 validation
   a. Is the error message meaningful?
2. If the collateral total value is incorrect, then submit fails phase1 validation
   a. Is the error message meaningful?