I was asking to myself in which scenarios do I have to add a collateral when consuming an UTXO in a Script Address. I have just read the basics, but do you know if there is minimum needed in each collateral UTXO ? from the protocol parameters it appears to be as well that there is a maximum of collateral utxos, Do i need to provide one always even if the amount of ADA that I am sending is high enough to cover any any fee related to the execution of the scripts? ... I guess the answer for the second is affirmative but i would appreciate any insights about it.
Also I would appreciate any additional info about the cardano.getCollateral() endpoint of the NamiWallet.
Whenever a script is evaluated in a transaction, a collateral is needed. It is collected by the validating stake pool in case the transaction passes the first stage validation process but then fails because one of the script UTxOs cannot be validated (see: here). The collateral is not related to the transaction fees. Both need to be satisfied by the transaction: fees need to be covered and collateral provided.
The collateral is a special field of the transaction and needs to contain at least one UTxO. This UTxO can be one of the input UTxOs of the transaction. Nami wallet asks the user to generate a specially designated UTxO which is then never used as input UTxO so that it can always be used as collateral. I don't know of any constraints other than that this UTxO must contain the minimum Ada value (which is always satisfied as it wouldn't exist in the wallet otherwise). The value of the collateral determines the script execution budget. So the higher its Ada value the lower the risk that the transaction fails because script execution was aborted.
Consuming a UTXO at a script address requires phase-2 script validation, therefore it always requires collateral. Without collateral, such transactions will be rejected during phase-1 validation. (ref. IOHK no-surprises blog post)
There is no minimum Ada required per collateral UTXO, but every UTXO available in your wallet will have at least the min ADA constraint that was in effect when the UTXO was created. (see protocol parameters)
You are correct, the protocol parameters currently stipulate a maximum of 3 collateral UTXOs.
Yes, you must always provide collateral inputs if phase-2 validation will be triggered. You can use the same UTXOs for spending, fees, and collateral as long as the UTXO contains enough ADA to cover the spending and fees or the collateral, whichever is higher. In your example, where you're Input UTXO is only needed to pay the Tx fee (since you're consuming a UTXO at a script address), the collateral would have to be at least 150% of the calculated fee (per protocol parametercollateral_percentage=150). So, a single UTXO containing at least 1.5x the calculated fee could be provided as both the Tx input and Collateral input.
I can't speak to the getCollateral() endpoint of the Nami Wallet, but it's important to understand why Nami's requires a designated UTXO for collateral. It's probably a matter of convenience for them, but it's a matter of safety and readiness for you. Collateral UTXOs must only contain ADA, with no other native tokens. By having users explicitly create an internally designated Collateral UTXO up front and reserving it for that purpose, you're assured that you will have a valid UTXO readily available for script interactions. Without it, you could end up in a situation where you're unable to interact with a script because all your UTXOs with sufficient collateral happen to also have non-ADA tokens attached. If the script you're trying to interact with is time sensitive (e.g., a sudden NFT bargain), the time required to reshuffle funds to create a collateral-qualified UTXO could be the deal breaker.
Some important related considerations:
Collateral is NOT an execution budget, as it's not used for paying as much as is needed for execution and then getting the rest in change. Instead, it's more like collateral against potential damages. That is, against the damage caused to the validators if you send them an unprocessable transaction. If the transaction isn't valid, the fee component of the transaction is also potentially invalid, so collateral is a separate guarantee that validators will be compensated for processing 'phase-2 invalid' or 'failed' transactions. While it is not an execution budget, there are protocal parameter limitations on execution memory and steps per transaction. If any such protocol limits are exceeded, transaction processing will terminate and (I believe) the validator keeps the collateral and marks the transaction as 'phase-2 invalid'.
re. my reference to 'safety' in item 5: Per the No-Surprises blog post, "the total balance in the UTXOs corresponding to these specially marked [collateral] inputs is the transaction's collateral amount". Then in the very next paragraph it says "good news! It is permitted to use the same inputs for both collateral and regular, since only one of the two sets ever gets [spent]". Ironically, that is NOT good news! Because if you happen to have only one UTXO in your wallet containing your entire HODLing fortune, and you use that as both Tx Input and Collateral Input on a contract (that perhaps wasn't very well tested), you risk losing it ALL! It seems unfair, really... on a failed phase-2 validation only 150% of the base fee should be extracted from the UTXO, and the remainder should be returned to the change address, but every reference I've found so far seem to suggest collateral forfeiture is all-or-none. Note:If anyone has an authoritative source either supported or debunking all-or-none collateral forfeiture, please edit this portion of the answer.