[CIP-0030] Adding getCollateral function to the connector API
#208
Conversation
Replaced undefined with null to be compatible with cardano-foundation#181
vsubhuman
changed the title
getCollateralUtxos function to the connector APIgetCollateral function to the connector API
|
|
||
| The main point is to allow the wallet to encapsulate all the logic required to handle, maintain, and create (possibly on-demand) the UTXOs suitable for collateral inputs. For example, whenever attempting to create a plutus-input transaction the dapp might encounter a case when the set of all user UTXOs don't have any pure entries at all, which are required for the collateral, in which case the dapp itself is forced to try and handle the creation of the suitable entries by itself. If a wallet implements this function it allows the dapp to not care whether the suitable utxos exist among all utxos, or whether they have been stored in a separate address chain (see https://github.com/cardano-foundation/CIPs/pull/104), or whether they have to be created at the moment on-demand - the wallet guarantees that the dapp will receive enough utxos to cover the requested amount, or get an error in case it is technically impossible to get collateral in the wallet (e.g. user does not have enough ADA at all). | ||
|
|
||
| The `amount` parameter is required, specified as a `string` (BigNumber) or a `number`, and the maximum allowed value must be agreed to be something like 5 ADA. Not limiting the maximum possible value might force the wallet to attempt to purify an unreasonable amount of ADA just because the dapp is doing something weird. Since by protocol the required collateral amount is always a percentage of the transaction fee, it seems that the 5 ADA limit should be enough for the foreseable future. |
There was a problem hiding this comment.
Fyi both ccvault and Flint use 5~20 ADA and I think Nami does <50 ADA
There was a problem hiding this comment.
Is that really necessary? Since the collateral is a percentage of a fee - can we imagine a transaction with a 20+ ADA fee?
There was a problem hiding this comment.
The bottom of the range (5ADA) is what is meant to make sure you have enough collateral to cover any requirement
The upper part of the range (20ADA / 50 ADA) is just because wallets wants to protect users from accidentally losing a lot of ADA due to a poorly programmed dApp and so they don't want to allow using millions of ADA as collateral. 20/50 was picked as an arbitrary cutoff point so that it's not the end of the world if you lose it.
There was a problem hiding this comment.
Sounds like it then can be just the range from 5 ADA min to 5 ADA max. I.e. if we assume 5 ADA should be enough to cover any requirements then why give dapps any idea to ever have more than that at all? 🤔
There was a problem hiding this comment.
Because the user may have a 10 ADA utxo entry by chance, and it would be a bit excessive to say to the user "sorry, you can't use your 10 ADA as collateral because it has to be exactly 5 ADA".
There was a problem hiding this comment.
Because the user may have a 10 ADA utxo entry by chance, and it would be a bit excessive to say to the user "sorry, you can't use your 10 ADA as collateral because it has to be exactly 5 ADA".
I am confused here. What will happen with the dapp call to getCollateral in case they specify they want to get 20 ADA, but there's no UTXO below 50 ADA, for example?
The whole point of what I am describing in the spec is that the amount parameter limit should be something like 5 ADA, so that DAPPS can NOT request amounts above 5 ADA. But then the wallet is free to return anything as long as it covers the amount the dapp has requested.
Example:
- Dapp requests 3 ADA
- Wallet sees there's a 10 ADA utxo
- Wallet returns the 10 ADA utxo if the wallet wants
- Dapp doesn't care and just includes it into the tx without having to think
Example 2:
- Dapp requests 3 ADA
- Wallet see there are few utxos of 1.4 ADA
- Wallet returns 3 utxos like
[1.4 , 1.4 , 1.4]total sum of 4.2 - Dapp doesn't care and just includes it into the tx without having to think
Example 3:
- Dapp requests 7 ADA
- Wallets returns an error saying that's too much and shouldn't be reasonable for a collateral
There was a problem hiding this comment.
Main goal is to ENCAPSULATE the logic as much as possible, achieving:
-
Dapps dont't have to think AT ALL - just specify the minimum total value of collateral you want to get, and don't make it too high
-
Wallets are free to implement internally anything they want, they can return a 1000 ADA if they want to, the spec doesn't care or control it, as long as it covers the amount requested by the dapp.
The main requirement is that any wallet implementing must either return non-empty array of utxo that is guaranteed to be equal or above the requested amount, OR return no utxos at all, indicating the requested amount is impossible to achieve. So a wallet must never return utxos that would sum up below the requested amount.
@SebastienGllmt what you are talking about is that Flint is returning utxos of AT LEAST 5 ADA, which will mean that it will be automatically compatible with the proposed spec, because the spec proposes that the requested amount is never above 5 ADA, which means Flint will always return same or above
Added function
getCollateralwhich is made to be symmetrical withgetUtxos. The main idea there is to allow the dapps to not care as much as possible (within the existing API in the spec) and for wallets to encapsulate the exact logic of how the collaterals are being handled in reality (whether they have opted-in to #104 or implemented some different approach).