CIP-0040? | Collateral output (#216)

* added work from PR#25 to support single stake pool links as well

* for brevity

* for clarity

* response to first round of editing by co-author

* second round of co-author edits

* reclassified wallet integration as Motivation rather than Rationale

* 2 of 3 changes from @nicarq via PR 65

* undone most recent commit (removing PR65 suggestions)

* undone most recent commit (removing PR65 suggestions)

* Collateral output CIP

* rename file

* Include self-contained balancing requirement

* Add Andre to the CIP

* pre merge changes, attempt as 3rd party

Co-authored-by: rphair <rphair@cosd.com>

CIP-0040/README.md

@@ -0,0 +1,64 @@
+---
+CIP: 40
+Title: Explicit Collateral Output
+Authors: Sebastien Guillemot <seba@dcspark.io>, Jared Corduan <jared.corduan@iohk.io>, Andre Knispel <andre.knispel@iohk.io>
+Status: Proposed
+Type: Standards
+Created: 2022-02-10
+License: CC-BY-4.0
+---
+
+# Abstract
+
+This document describes adding a new output type to transactions called Collateral Outputs
+
+# Motivation
+
+As of Alonzo, transactions that call Plutus smart contracts are required to put up collateral to cover the potential cost of smart contract execution failure. Inputs used as collateral have the following properties:
+
+1. Cannot contain any tokens (only ADA)
+2. Cannot be a script address
+3. Must be a UTXO input
+4. Must be at least some percentage of the fee in the tx (concrete percentage decided by a protocol parameter)
+5. Can be the same UTXO entry as used in non-collateral tx input
+6. Is consumed entirely (no change) if the contract execution fails during phase 2 validation
+7. Is not consumed if phase phase 2 validation succeeds
+
+Additionally, there cannot be more than *maxColInputs* (protocol parameter) inputs and the inputs have to cover a percentage of the fee defined by *collateralPercent* (protocol parameter)
+
+However,
+
+- Restriction #1 is problematic because hardcore dApp users rarely have UTXO entries that do not contain any tokens. To combat this, wallets have created a special wallet-dependent "collateral" UTXO to reserve for usage of collateral for dApps which is not a great UX. 
+- Restriction #6 is problematic because wallets want to protect users from signing transactions with large collateral as they cannot verify whether or not the transaction will fail when submitted (especially true for hardware wallets)
+
+# Specification
+
+If phrase-2 verification fails, we can send outputs to a special output marked as the collateral output.
+
+There are two ways to create collateral outputs
+
+1. Add collateral outputs as a new field inside the transaction. This change is similar to how collateral inputs were created a new field
+2. Change the definition of outputs as `TxOut = Addr × Value × DataHash? × Source?` where source (optional for backwards compatibility) is an enum `0 = regular output, 1 = collateral output`.
+
+Option #1 provides the best backwards compatibility because we don't expect phase-2 validation to be a common occurrence and so wallets that (due to not being updated) never check collateral outputs will still in the overwhelming majority of cases return the correct result.
+
+Additionally, this requires updating the collateral requirement.
+
+If no collateral output is specified (and therefore no tokens are in the collateral input), then we keep the old definition
+
+```
+ubalance (collateral txb ◁ utxo) ≥ quot (txfee txb * (collateralPercent pp)) 100
+```
+
+However, if collateral output is specified, then
+1. Each collateral output needs to satisfy the same minimum ADA requirement as regular outputs
+2. Collateral output needs to be balanced according to `sum(collateral_input) = sum(collateral_output) + collateral_consumed`
+Where `collateral_consumed` is equal to the old formula (`quot (txfee txb * (collateralPercent pp)) 100`). Note that when collateral is consumed, any certificate, etc. in the transaction is ignored so they have no impact on the change calculation.
+
+## Self-contained balancing
+
+Some use-cases like hardware wallets, who do not have access to the content of the collateral inputs, cannot easily check if the collateral is balanced. Similar to how we specify an explicit fee as part of the transaction body to tackle this problem, the transaction body also needs a new field that explicitly specified how much collateral will be consumed in the case of phase-2 validation failure.
+
+## Copyright
+
+This CIP is licensed under [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode)

README.md

@@ -55,6 +55,7 @@ The entire process is described in greater detail in [CIP1 - "CIP Process"](./CI
 | 34 | [Chain ID Registry](./CIP-0034/) | Draft |
 | 35 | [Plutus Core Evolution](./CIP-0035) | Active |
 | 36 | [Catalyst/Voltaire Registration Transaction Metadata Format](./CIP-0036) | Proposed | 
+| 40 | [Collateral Output](https://github.com/cardano-foundation/CIPs/pull/216) | 
 | 42 | [New Plutus Builtin: serialiseBuiltinData](./CIP-0042) | Proposed | 
 | 52 | [Cardano Audit Best Practice Guidelines](./CIP-0052) | Proposed |  
 | 1852 | [HD (Hierarchy for Deterministic) Wallets for Cardano](./CIP-1852/) | Active |
@@ -75,7 +76,6 @@ Below are listed tentative CIPs still under discussion with the community. Discu
 | 37? | [Dynamic Saturation Based on Pledge](https://github.com/cardano-foundation/CIPs/pull/163) |
 | 38? | [On-Chain Token Metadata Standard](https://github.com/cardano-foundation/CIPs/pull/137) | 
 | 39? | [Smart Contract Software Licenses](https://github.com/cardano-foundation/CIPs/pull/185) |
-| 40? | [Collateral Output](https://github.com/cardano-foundation/CIPs/pull/216) | 
 | 41? | [Collateral Rewards](https://github.com/cardano-foundation/CIPs/pull/217) | 
 | 44? | [Additional Factors For NFT Market Verification](https://github.com/cardano-foundation/CIPs/pull/226) | 
 | 45? | [Decentralization: Using Pledge as a Bidding Param](https://github.com/cardano-foundation/CIPs/pull/229) |