From 551f09e0ac6c751fcf4e4f3d6b08c1f167b7a07b Mon Sep 17 00:00:00 2001 From: Ruslan Dudin Date: Fri, 4 Feb 2022 10:50:14 +0300 Subject: [PATCH 1/6] Adding `getCollateralUtxos` function --- CIP-0030/README.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/CIP-0030/README.md b/CIP-0030/README.md index e706d1ab0..a2e85fce5 100644 --- a/CIP-0030/README.md +++ b/CIP-0030/README.md @@ -197,6 +197,16 @@ Errors: `APIError`, `PaginateError` If `amount` is `undefined`, this shall return a list of all UTXOs (unspent transaction outputs) controlled by the wallet. If `amount` is not `undefined`, this request shall be limited to just the UTXOs that are required to reach the combined ADA/multiasset value target specified in `amount`, and if this cannot be attained, `undefined` shall be returned. The results can be further paginated by `paginate` if it is not `undefined`. +### api.getCollateralUtxos(amount: cbor\): Promise\ + +Errors: `APIError` + +The `amount` is required. This shall return a list of all UTXOs (unspent transaction outputs) controlled by the wallet that are required to reach the combined ADA value target specified in `amount` **AND** the best suitable to be used as collateral inputs for transactions with plutus script inputs. If this cannot be attained, `undefined` shall be returned. + +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. + ### api.getBalance(): Promise\> Errors: `APIError` From 17998d9ab841c9ee54f05fa3baded22eef0fbcde Mon Sep 17 00:00:00 2001 From: Ruslan Dudin Date: Fri, 4 Feb 2022 11:03:11 +0300 Subject: [PATCH 2/6] Changed undefined return to null Replaced undefined with null to be compatible with https://github.com/cardano-foundation/CIPs/pull/181 --- CIP-0030/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CIP-0030/README.md b/CIP-0030/README.md index a2e85fce5..9019384f7 100644 --- a/CIP-0030/README.md +++ b/CIP-0030/README.md @@ -197,11 +197,11 @@ Errors: `APIError`, `PaginateError` If `amount` is `undefined`, this shall return a list of all UTXOs (unspent transaction outputs) controlled by the wallet. If `amount` is not `undefined`, this request shall be limited to just the UTXOs that are required to reach the combined ADA/multiasset value target specified in `amount`, and if this cannot be attained, `undefined` shall be returned. The results can be further paginated by `paginate` if it is not `undefined`. -### api.getCollateralUtxos(amount: cbor\): Promise\ +### api.getCollateralUtxos(amount: cbor\): Promise\ Errors: `APIError` -The `amount` is required. This shall return a list of all UTXOs (unspent transaction outputs) controlled by the wallet that are required to reach the combined ADA value target specified in `amount` **AND** the best suitable to be used as collateral inputs for transactions with plutus script inputs. If this cannot be attained, `undefined` shall be returned. +The `amount` is required. This shall return a list of all UTXOs (unspent transaction outputs) controlled by the wallet that are required to reach the combined ADA value target specified in `amount` **AND** the best suitable to be used as collateral inputs for transactions with plutus script inputs. If this cannot be attained, `null` shall be returned. 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). From 950a63900ac04feafef300fe713041892de3c8a8 Mon Sep 17 00:00:00 2001 From: Ruslan Dudin Date: Tue, 8 Feb 2022 21:56:06 +0300 Subject: [PATCH 3/6] Updated the spec to rename the function and change the arguments to an object --- CIP-0030/README.md | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/CIP-0030/README.md b/CIP-0030/README.md index 9019384f7..89e7d86da 100644 --- a/CIP-0030/README.md +++ b/CIP-0030/README.md @@ -197,11 +197,18 @@ Errors: `APIError`, `PaginateError` If `amount` is `undefined`, this shall return a list of all UTXOs (unspent transaction outputs) controlled by the wallet. If `amount` is not `undefined`, this request shall be limited to just the UTXOs that are required to reach the combined ADA/multiasset value target specified in `amount`, and if this cannot be attained, `undefined` shall be returned. The results can be further paginated by `paginate` if it is not `undefined`. -### api.getCollateralUtxos(amount: cbor\): Promise\ +### api.getCollateral(params: { amount: cbor\ }): Promise\ Errors: `APIError` -The `amount` is required. This shall return a list of all UTXOs (unspent transaction outputs) controlled by the wallet that are required to reach the combined ADA value target specified in `amount` **AND** the best suitable to be used as collateral inputs for transactions with plutus script inputs. If this cannot be attained, `null` shall be returned. +The function takes a required object with parameters. With a single **required** parameter for now: `amount`. (**NOTE:** some wallets may be ignoring the amount parameter, in which case it might be possible to call the function without it, but this behavior is not recommended!). Reasons why the `amount` parameter is required: +1. Dapps must be incentivised to understand what they are doing with the collateral, in case they decide to handle it manually. +2. Depending on the specific wallet implementation, requesting more collateral than necessarily might worsen the user experience with that dapp, requiring the wallet to make explicit wallet reorganisation when it is not necessary and can be avoided. +3. If dapps don't understand how much collateral they actually need to make their transactions work - they are placing more user funds than necessary in risk. + +So requiring the `amount` parameter would be a by-spec behavior for a wallet. Not requiring it is possible, but not specified, so dapps should not rely on that and the behavior is not recommended. + +This shall return a list of all UTXOs (unspent transaction outputs) controlled by the wallet that are required to reach the combined ADA value target specified in `amount` **AND** the best suitable to be used as collateral inputs for transactions with plutus script inputs. If this cannot be attained, `null` shall be returned. 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). From d735e0d7827930a1d2a567e32df7576d433a320b Mon Sep 17 00:00:00 2001 From: Ruslan Dudin Date: Tue, 8 Feb 2022 22:13:20 +0300 Subject: [PATCH 4/6] Fixing wording --- CIP-0030/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CIP-0030/README.md b/CIP-0030/README.md index 89e7d86da..a8e5e0583 100644 --- a/CIP-0030/README.md +++ b/CIP-0030/README.md @@ -202,7 +202,7 @@ If `amount` is `undefined`, this shall return a list of all UTXOs (unspent trans Errors: `APIError` The function takes a required object with parameters. With a single **required** parameter for now: `amount`. (**NOTE:** some wallets may be ignoring the amount parameter, in which case it might be possible to call the function without it, but this behavior is not recommended!). Reasons why the `amount` parameter is required: -1. Dapps must be incentivised to understand what they are doing with the collateral, in case they decide to handle it manually. +1. Dapps must be motivated to understand what they are doing with the collateral, in case they decide to handle it manually. 2. Depending on the specific wallet implementation, requesting more collateral than necessarily might worsen the user experience with that dapp, requiring the wallet to make explicit wallet reorganisation when it is not necessary and can be avoided. 3. If dapps don't understand how much collateral they actually need to make their transactions work - they are placing more user funds than necessary in risk. From 0c0ecdf1ddd9713b265e587c634f75904be2d30a Mon Sep 17 00:00:00 2001 From: Ruslan Dudin Date: Tue, 15 Feb 2022 15:33:29 +0300 Subject: [PATCH 5/6] Update README.md --- CIP-0030/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CIP-0030/README.md b/CIP-0030/README.md index a8e5e0583..c6e1dbc0c 100644 --- a/CIP-0030/README.md +++ b/CIP-0030/README.md @@ -208,7 +208,7 @@ The function takes a required object with parameters. With a single **required** So requiring the `amount` parameter would be a by-spec behavior for a wallet. Not requiring it is possible, but not specified, so dapps should not rely on that and the behavior is not recommended. -This shall return a list of all UTXOs (unspent transaction outputs) controlled by the wallet that are required to reach the combined ADA value target specified in `amount` **AND** the best suitable to be used as collateral inputs for transactions with plutus script inputs. If this cannot be attained, `null` shall be returned. +This shall return a list of all UTXOs (unspent transaction outputs) controlled by the wallet that are required to reach the combined ADA value target specified in `amount` **AND** the best suitable to be used as collateral inputs for transactions with plutus script inputs. If this cannot be attained, an error message with an explanation of the blocking problem shall be returned. 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). From de5c2e076694a43af560fbb06b8c44c5f287416a Mon Sep 17 00:00:00 2001 From: Ruslan Dudin Date: Sat, 19 Feb 2022 15:32:43 +0300 Subject: [PATCH 6/6] Tried to clarify the description a bit more --- CIP-0030/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CIP-0030/README.md b/CIP-0030/README.md index c6e1dbc0c..82a6f65da 100644 --- a/CIP-0030/README.md +++ b/CIP-0030/README.md @@ -208,7 +208,7 @@ The function takes a required object with parameters. With a single **required** So requiring the `amount` parameter would be a by-spec behavior for a wallet. Not requiring it is possible, but not specified, so dapps should not rely on that and the behavior is not recommended. -This shall return a list of all UTXOs (unspent transaction outputs) controlled by the wallet that are required to reach the combined ADA value target specified in `amount` **AND** the best suitable to be used as collateral inputs for transactions with plutus script inputs. If this cannot be attained, an error message with an explanation of the blocking problem shall be returned. +This shall return a list of one or more UTXOs (unspent transaction outputs) controlled by the wallet that are required to reach **AT LEAST** the combined ADA value target specified in `amount` **AND** the best suitable to be used as collateral inputs for transactions with plutus script inputs (pure ADA-only utxos). If this cannot be attained, an error message with an explanation of the blocking problem shall be returned. **NOTE:** wallets are free to return utxos that add up to a **greater** total ADA value than requested in the `amount` parameter, but wallets must never return any result where utxos would sum up to a smaller total ADA value, instead in a case like that an error message must be returned. 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).