Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Extend URI scheme for delegation portfolio links #86

Merged
merged 14 commits into from
Jul 29, 2021
Merged

Extend URI scheme for delegation portfolio links #86

Changes from 13 commits
Commits
Show all changes
14 commits
Select commit Hold shift + click to select a range
b4c7280
added work from PR#25 to support single stake pool links as well
rphair Jan 17, 2021
b24d0ef
for brevity
rphair Jan 17, 2021
235ad40
for clarity
rphair Jan 17, 2021
75faa8f
response to first round of editing by co-author
rphair Jan 18, 2021
0389fa1
second round of co-author edits
rphair Jan 18, 2021
adbee6f
reclassified wallet integration as Motivation rather than Rationale
rphair Jan 18, 2021
176b5c0
2 of 3 changes from @nicarq via PR 65
rphair Feb 20, 2021
20f35f6
undone most recent commit (removing PR65 suggestions)
rphair Feb 20, 2021
f43d28c
Merge branch 'master' of github.com:rphair/CIPs
rphair Feb 20, 2021
85c4b77
undone most recent commit (removing PR65 suggestions)
rphair Feb 20, 2021
db81cb6
Merge remote-tracking branch 'upstream/master'
rphair Apr 12, 2021
389fd6c
added remaining multi pool components of PR#25 plus further writing
rphair Apr 12, 2021
42805c6
added current PR link as a Comments-URI
rphair Apr 13, 2021
26ee25b
first round of editing from developer feedback
rphair May 11, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 33 additions & 7 deletions CIP-0013/CIP-0013.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ Comments-URI:
- https://forum.cardano.org/t/cip-cardano-payment-uri-scheme/41457
- https://github.com/cardano-foundation/CIPs/pull/25
- https://github.com/cardano-foundation/CIPs/pull/61
- https://github.com/cardano-foundation/CIPs/pull/86
- https://forum.cardano.org/t/cip-stake-uri-scheme-for-pools-delegation-portfolios/40594
Status: Draft
Type: Informational
Expand All @@ -16,7 +17,7 @@ License: CC-BY-4.0

# Abstract

This proposal describes a basic URI scheme to handle Ada transfers and links to stake pools.
This proposal describes a basic URI scheme to handle Ada transfers and links to single stake pools or weighted lists of multiple pools.

# Motivation

Expand All @@ -34,10 +35,12 @@ Stake pool URIs will provide an additional means for small pools to acquire dele

Interfaces that connect delegators with pools beyond the highly contested top choices of the in-wallet ranking algorithms are important to avoid saturation and maintain decentralization.

Larger pools and collectives can also use these URIs to link to a family of pools they own to avoid any one of their pools becoming saturated.
Larger pools and collectives can also use these URIs to link to, and spread delegation between, a family of pools they own to avoid any one of their pools becoming saturated.

Pool links allow for interfaces to initiate delegation transactions without requiring any code modifications to the wallets themselves.

URIs for weighted stake pool lists provide alternatives to using a JSON file to implement *delegation portfolios* in a way that may better suit certain platforms, applications, or social contexts.

# Specification

The core implementation should follow the [BIP-21](https://github.com/bitcoin/bips/blob/master/bip-0021.mediawiki) standard (with `bitcoin:` replaced with `web+cardano:`)
Expand All @@ -50,6 +53,7 @@ Examples:
```
<a href="web+cardano:Ae2tdPwUPEZ76BjmWDTS7poTekAvNqBjgfthF92pSLSDVpRVnLP7meaFhVd">Donate</a>
<a href="web+cardano://stake?c94e6fe1123bf111b77b57994bcd836af8ba2b3aa72cfcefbec2d3d4">Stake with us</a>
<a href="web+cardano://stake?POOL1=3.14159&POOL2=2.71828">Split between our 2 related pools</a>
<a href="web+cardano://stake?COSD">Choose our least saturated pool</a>
```

Expand All @@ -64,9 +68,9 @@ Examples:
This is an initial, simplified protocol definition for fast implementation; it only requires:

* for a payment URI (authority unspecified), an address and an optional amount parameter;
* for a stake pool URI (authority = `stake`), a single stake pool reference.
* for a stake pool URI (authority = `stake`), a weighted list of one or more stake pools.

As discussed above, these rules are likely to evolve in time in order to support additional features, including multiple stake pool references (in proportions defining a "portfolio") and other unique capabilities of the Cardano blockchain.
As discussed above, these rules are likely to evolve in order to support other capabilities of the Cardano blockchain.

```
cardanourn = "web+cardano:" (paymentref | stakepoolref)
Expand All @@ -75,10 +79,15 @@ paymentref = cardanoaddress [ "?" amountparam ]
cardanoaddress = *(base58 | bech32)
amountparam = "amount=" *digit [ "." *digit ]

stakepoolref = "//stake?" stakepool
stakepoolref = "//stake" stakequery
stakequery = ( "?" stakepoolpair) *( "&" stakepoolpair)
stakepoolpair = stakepool [ "=" proportion]

stakepool = poolhexid | poolticker
poolhexid = 56HEXDIG
poolticker = 3*5UNICODE

proportion = *digit [ "." *digit ]
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If anything, it'd be good to have CIP-0017 & this extension aligned; Please see the comment on CIP-0017 about decimals

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

thanks, addressed here: #82 (comment)

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@rphair (thanks for your comment on the CIP-0017). I acknowledge your points but I do not necessarily agree with all your statements (although, I do concur that some of my points are skewed / biased towards a certain view as a wallet maintainer).

I'd like to understand what is your main argument for wanting decimals in here? From one of your previous comment, it sounded very speculative to me 😶

@rphair: Some users & developers will require decimals as the stake pool weights in order to build portfolios that match the following real world values [...]

Note that re-reading some of your comments, I think there is maybe a misunderstanding (?) on the purpose of the portfolio definition. The proposal from CIP-0017 and I believe, this one here are not about extending the protocol in any ways to support multi-delegation. This is unlikely to happen anytime soon and is a whole different discussion.

Hence this is about sharing a financial portfolio with other stakeholders, and let them know what works well. It is not about capturing the state of a wallet, but rather to give some recipes and recommendations about delegation choices.

```

### Payment URI queries
Expand All @@ -89,13 +98,21 @@ The amount parameter must follow the [same rules](https://github.com/bitcoin/bip

For brevity, essential in many Internet contexts, `poolticker` must be supported here in addition to the unambiguous `poolhexid`.

When there is more than one pool registered with the specified `poolTicker` (whether for pool groups which have the same ticker for all pools, or for separate pools using the same ticker), the choice to which pool to finally delegate is left to the user through the wallet UI.
When there is more than one pool registered with any of the specified `poolticker` parameters (whether for pool groups which have the same ticker for all pools, or for separate pools using the same ticker), the choice to which pool(s) to finally delegate is left to the user through the wallet UI.

#### Interpretation of `proportion`:

* If only one stake pool is specified, any proportion is meaningless and ignored.
* If all stake pools have a numerical proportion, each component of the resulting stake distribution will have the same ratio as the provided `proportion` to the sum of all the propotions.
* If none of the proportions are given, all proportions are assumed to be equal.
* If some of the proportions are missing, any missing proportions are set to the average of all those specified explicitly.
* If a stake pool is mentioned multiple times, those proportions as determined above are added together.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The three last points seem to me to be invalid URLs / portfolios definitions. To be valid, a portfolio should always define all proportions for all pools, and each pool should only appear once.
Having multiple default cases and parsing behavior would only render parsing downstream more complex. I don't see the rationale for allowing this?


### Handling stake pool links

The wallet UI should always confirm the exact delegation choice even when it is unambiguous from the URI. When the user has multiple wallets, the wallet UI must select which wallet(s) the user will be delegating from.

These yet unsupported parameters in the URI query string should (by preference of the wallet UI designers) *either* be ignored *or* generate a warning message, to avoid leading the user to believe they are implementing a currently unsupported but perhaps popularly referenced multi-pool delegation list:
If, during a wallet or other application's development process, it is still only able to support single pool links, these parameters in the URI query string should (by preference of the wallet UI designers) *either* be ignored *or* generate a warning message, to avoid leading the user to believe they are implementing a currently unsupported but perhaps popularly referenced multi-pool delegation list:

* any value for the first URI query argument;
* any URI query argument beyond the first.
Expand All @@ -104,13 +121,20 @@ These yet unsupported parameters in the URI query string should (by preference o

1. For payment links, we cannot prompt the user to send the funds right away as they may not be fully aware of the URI they clicked or were redirected to. Instead, it may be better to simply pre-populate fields in a transaction.
2. For either payment or staking links, we should be wary of people who disguise links as actually opening up a phishing website that LOOKS like that corresponding part of the wallet UI.
3. If wallets *create* stake pool links, the actual ada or lovelace balance should not be used literally as the `proportion` figure, to avoid revealing the identity of the wallet owner who is creating the portfolio (e.g. the proportions could be scaled to normalise the largest to `1`).

# Rationale

## Why not use Universal links, deep links and other non-protocol-based Solution

An alternative solution to the original problem described above is to use standard URL links in combination with a routing backend system. The routing system is used to redirect to the app's URI. The advantage of this scheme is that it allows to provide a fallback mechanism to handle the case when no application implementing the protocol is installed (for instance, by redirecting to the App Store or Google Play). This is the approach behind iOS Universal Links and Android App Links. In general, it provides a better user experience but requires a centralized system which makes it unsuitable for as a multi-app standard.

## How URI delegation portfolio links supplement use of JSON files for the same purpose

URIs facilitate the "social element" of delegated staking and pool promotion through a socially familiar, easily accessible, and less centralised convention for sharing stake pool references and potential delegation portfolios without having to construct or host a JSON file.

The processing of a JSON file delivered by a web server will depend highly on a user's platform and might not even be seen by the wallet application at all. With a properly associated `web+cardano:` protocol, developers and users have another option available in case JSON files are not delivered properly to the wallet application.

## Read More

https://developer.mozilla.org/en-US/docs/Web/API/Navigator/registerProtocolHandler
Expand All @@ -126,3 +150,5 @@ https://developer.apple.com/documentation/uikit/core_app/allowing_apps_and_websi
https://en.wikipedia.org/wiki/Augmented_Backus%E2%80%93Naur_form

https://tools.ietf.org/html/draft-seantek-unicode-in-abnf-00

https://github.com/cardano-foundation/CIPs/pull/82