clarify migrate endpoint end-user documentation

[KtorZ]

Issue Number

#1675

Overview

The sense of 'migrate' seemed unclear to people. So this attempts to give more precisions about
what it really is about. The same description should be copied over for the Shelley equivalent.

Comments

[piotr-iohk]

Question about the corresponding cost endpoint. The description for endpoint calculate migration cost reads:

Calculate the exact cost of migrating from a Byron wallet to the specified set of addresses.

Addresses are not provided as a parameter to the cost endpoint, as they are for the migrate endpoint. (Is the cost not influenced by the number of addresses?)

[KtorZ]

Is the cost not influenced by the number of addresses?

Hmmm. No. The algorithm can be seen as two steps:

a) Construct coin selections needed to migrate funds.
b) Assign an address to each change output, cycling them if necessary.

So, the number of addresses is known, from the migration itself. It is true that in principle, the address could influence the selection, because their individual size is not known and, is not fixed in Byron. The fee estimation is using the worst-case scenario (i.e. random addresses with derivation payload) to do calculation, but Shelley addresses are much shorter. This could be a potential improvement of the algorithm / fee estimator used by the algorithm.

[piotr-iohk]

OK, but then saying:

Calculate the exact cost of migrating from a Byron wallet to the specified set of addresses.

sounds a bit awkward when you don't specify any addresses.

[paweljakubas]

@piotr-iohk you need to specify at least one address -> https://github.com/input-output-hk/cardano-wallet/blob/master/specifications/api/swagger.yaml#L416 don't you :-)

[piotr-iohk]

@paweljakubas I'm referring to calculate migration cost endpoint -> https://input-output-hk.github.io/cardano-wallet/api/edge/#operation/getByronWalletMigrationInfo

You don't specify addresses on that endpoint but the description reads:

Calculate the exact cost of migrating from a Byron wallet to the specified set of addresses.

[paweljakubas]

ah, ok. my bad. in the context of getByronWalletMigrationInfo the "to the specified set of addresses" is not needed, indeed! Agree here. It is the migration cost of whole funds in the wallet specified by wallet id.