Extend URI scheme with single stake pool links

[rphair]

Including stake pool links with this CIP, rather than submitting a separate CIP, has been agreed upon and discussed in #25 where this new material has already been introduced and held up for comment. Therefore I've also set this CIP's date (2020-10-20) back to the earlier date of the other CIP's submission (2020-09-22).

[rphair]

@SebastienGllmt thanks for the feedback & I've done my best to accommodate all of it, and I'm happy with the resulting document.

[v-almonacid]

Good job! LGTM.

[rphair]

thanks @SebastienGllmt & @v-almonacid although with repeated rounds of editing we are gradually removing all the rationale for the stake pool links being not just implemented but expedited. The urgency for these links exists today: my opinion for sure but also that of a thousand others who could have used something like this on day one. Of course all the subjective issues, immediate problems & upcoming challenges will seem irrelevant at some point of equilibrium in the future.

In the meantime, I don't care whether the forward-thinking statements about stake pool link urgency, or the causes and cures of stake centralisation, live in the CIP or in this PR as long as others, including non-developers and outside visitors during Cardano's long upcoming expansion period, can see & confirm them... as long as it takes for all the proposed changes to be implemented as soon as possible.

So I'm going to do another round of culling my writing exactly as requested but I would like to re-post the removed subjective writing here in this PR instead. I'll try my best to consolidate all the changes above into a single commit and will post the out-takes in the comment after that, which I hope other participants in the CIP process will use to assign some priority to the stake pool part of the implementation and to this CIP as a whole.

[rphair]

Points for consideration - removed from CIP itself

Stake pool URIs will provide a convenient and popular alternative to the trend of stake centralisation, while supporting diversity and resilience in the Cardano network.

The popular choice for Cardano stake pool promotion has so far been an already saturated and heavily centralised YouTube market for stake pool promotional videos, purporting to be educational while collectively carrying rapidly obsoleted information and exploitative influences. Stake pools should also be directly supported by delegators based on relevant HTML content to create an ecosystem with relevance and accountability.

Both delegators and small pools looking to survive will inevitably rely on sources of information outside the wallet to connect delegators with pools beyond the highly contested top choices of the in-wallet ranking algorithms.

As K continues to increase, options for convenient and informed re-delegation will be more important as Ada holders face pool saturation more often.

A sudden DeFi migration to Cardano would cause a vast, sudden increase in transaction frequency and depth that the stake pool network will need to support with quality and diversity. A flow of delegation following small stake pool URIs will help maintain a number of pools sufficient to accommodate Cardano's needs during such expansion periods, by encouraging smaller operators to keep their pools operational and performant. More meaningful association between a pool's social identity and delegated stake will help ensure that pool operators are sufficiently rewarded by their own communities and other supporters.

[rphair]

all right, although it's a technical characteristic I'm moving it up into Motivation along with the other stuff that got moved there...

[rphair]

@SebastienGllmt FYI the last commit only changes one line relative to what you previously reviewed, moving it up to a better populated section... so it should be short work to review it again.

@v-almonacid Please let me know if the last little change was not what you had in mind 🙏

[v-almonacid]

Looks good!

[x3haloed]

I believe we need a URI scheme that will allow us to describe locations of addresses and transactions on Cardano (and other blockchains). I think it might be smart to use this opportunity to define the web+cardano: scheme more generally in such a way that it can be used to locate specific addresses and transactions on the blockchain. I'm personally working on a UTXO metadata project where it would be extremely useful to use URLs pointing to other transactions on the chain. The ability to initiate a payment can still be retained through the generalized design.

Ideas for how such a scheme could work have been proposed in the past. See: https://lists.linuxfoundation.org/pipermail/bitcoin-dev/2015-August/010726.html

Let me put it another way: If the Cardano blockchain is effectively an immutable transaction-log-style data store, wouldn't it be useful to have a URI scheme for describing metadata resources and their locations on the blockchain?

Please let me know if this was not the appropriate time and place to have this discussion.

[rphair]

Your idea sounds good but I can't say without being on the CIP team whether it would make more sense for all the Cardano URI Scheme extensions to be in one CIP or multiple CIPs.

With a metadata API included it could become a very long CIP... historically speaking with TCP/IP itself there ended up thousands of documents, with most of them extensions to and revisions of the same subject. That's one argument for your CIP being separate.

The only way I was able to get started originally was to submit "stake pool links" as its own CIP which attracted some attention from the developers, and thanks to @SebastienGllmt led to a private discussion to agree on the proposals being merged. In fact we are not done merging, with a "multi pool" factor to come in later, so if you tried to extend this one during the same time period we might have a concurrency problem.

As I've suggested on the forum I would try to attract his attention (or equivalent) if you can, and failing that I would draft your proposal as a CIP with its own pull request where you can keep the dialogue going (and establish a time clock), and also create your own Cardano Forum thread for community discussion & support.

[x3haloed]

Thank you for your feedback 🙏

I definitely don’t want to slow down the process and bloat this CIP. At minimum for this CIP, I do propose at least thinking about how we can avoid polluting this scheme or the global set of registered schemes in a way that limits our use of the scheme going forward or forces us to create new schemes to avoid breaking compatibility with this proposed scheme.

Even if we don’t address future uses of this scheme explicitly in this CIP, I believe it would be smart to try to plan the scheme in such a way that it can be extended in a sensible way in the future to include additional use cases.

I’ll follow your suggestion on the forum and create a new thread there to address this issue.

[rphair]

@SebastienGllmt @v-almonacid @dcoutts @admin-cf - I was wondering what was happening with this, after it was slated for approval at the last meeting I attended on 26 January, so I checked those meeting minutes today to confirm that meeting resolved to merge this PR at the 09 February (next) meeting: https://github.com/cardano-foundation/CIPs/blob/master/BiweeklyMeetings/01-26-2021.md#Update-to-CIP-0013

In the meantime (on 09 February, can't tell if this was before or after the CIP meeting) #65 came from @nicarq which substitutes one token / keyword for another (without changing behaviour) and adds a bullet point + bit of ABNF to make the URI scheme more strict (and wordy) by preventing users from abbreviating stake pool references according to the context of unambiguous field length: nicarq@dd07c91 ... plus adding himself as co-author for the trouble.

I had no idea the 09 February meeting would have ruled this as a "competing" proposal when in truth the other PR is more of an editing request than a fundamental change... yet according to the last meeting minutes it now blocks the conclusion of 3 months of delicate work to refine & integrate the long standing stake pool links proposal with Sebatien and Vicente's prior research & documentation of the payment links scheme: https://github.com/cardano-foundation/CIPs/blob/master/BiweeklyMeetings/02-09-2021.md#Update-to-CIP-0013

The URI syntax change in that PR is slightly more significant than changing stake to delegate but still the two changes together don't imply co-authorship after that degree of prior work and discussion. That particular question of "credits" I am happy to leave to Sebastien given his seniority with the CIP process. In any case I don't think it's accurate to say that the proposals are "competing" since both matters in #65 could have been more efficiently and diplomatically addressed by making a comment or two in this PR.

What's the down side of #65? I've said most of it in #65 (comment) already, with only a trivial response repeating what was said in the OP, but now that it's hanging up this proposal we've got to hash out every detail. Here's why I don't like either of those 2 changes, from the front-end, operational, and educational perspectives:

• Both changes will make URIs longer, make QR codes denser, and make the stake pool links we hope to be ubiquitous more difficult to type, remember, and use in email and other messaging platforms.
• The insistence that stake pool references will be used only for immediate delegation through a wallet is naive. Third party web sites like AdaPools will quickly latch onto any common URI standard that promotes their own integration and analysis services, especially when the URI syntax eventually includes multi-pool lists (i.e. a "portfolio" for consideration). Sebastien himself mentioned such integration goals in the 26 January meeting.
• The key values to be "enforced" (pool reference vs. ID) will be difficult to spell especially for many non-native speakers of English. They will be difficult for everyone to remember the exact phrasing of without prior examples or other references.
• As far as stake vs. delegate is concerned, my comment referenced in the 09 February meeting remains unanswered... the question of whether nouns or verbs are more appropriate (let alone enforced, since CIP-0013 | Extend URI scheme with single stake pool links [proposal of update] #65 insists upon a verb) for the authority prefix. As already noted there, the term stake is semantically and functionally accurate for a stake pool reference.

To resolve the latter question I would suggest that all editors following this issue:

• First, recognise that the payment link standard doesn't predispose a choice, because the blank authority prefix from the unmodified CIP implies both pay which is a verb and payment which is a noun.
• Now, think of the next several things (API functions) that people are likely to do in the next few years with a web+cardano:// URI, and if the majority imply verbs (like delegate) as opposed to nouns (like the shorter & more familiar stake) then maybe there's a reason to change that prefix.
• If not, or if there's no prevailing mode, then the proposed change serves no long term purpose other than making the URIs longer & more difficult to type (and misspell in favour of inflections like "delegation", etc.).

So in the interest of resolving this bureaucratic deadlock, I would first suggest going forward with this PR immediately, by either ...

• Merge this PR as it is, since it's already been edited, reviewed, and approved.
• Then @nicarq can submit the changes of CIP-0013 | Extend URI scheme with single stake pool links [proposal of update] #65 after the Extend URI scheme with single stake pool links #61 merge, so those suggestions can be given a full discussion focusing on those two issues alone. There is a good precedent for this: being exactly what Sebastien insisted that we do with my modifications when CIP-0013 hadn't been merged yet.
• Then, as one would expect in a democracy, it will be up to @nicarq to prove why these changes are important and I will be happy with whatever consensus is achieved there: a discussion from which I will happily recuse myself after linking to this single comment.
• Then the implementation would have to wait until that second PR (relative to the merged CIP-0013) fully answers the questions of the URI syntax and is itself approved & merged.

... or, if the CIP editors don't want to do that ....

• Sebastien and/or Vicente, since we need some authority to "break the tie" or cast a deciding "vote", please take all my comments above into account, then fully justify & let me know your preferences with respect to the 2 issues in CIP-0013 | Extend URI scheme with single stake pool links [proposal of update] #65 and I will edit them into this CIP.
• This should include exactly what keywords should really be used instead of the suggested ?poolhexid= and ?poolticker= which people will still be double-checking on cheat sheets and misspelling 5 years from now (and fat-fingering forever).
• At that point the implementation will be ready to proceed as soon as this PR is merged into CIP-0013.

We need one of these approaches to be selected ASAP and well before the Tuesday (23 February) meeting, so we can revise this PR accordingly or reconfirm its acceptance before that discussion. The community has been waiting for this for months and the delays are claiming a place in the public eye. If it gets hung up for another two weeks over some other PR representing a relatively trivial change, it's going to be more generally perceived as a bureaucratic stalling tactic.

[nicarq]

@rphair to give more context on why the changes. I'm one of the developers of Yoroi and I was doing the integrating for deeplink and stakepool delegation. Seba told me that there was a PR open and when I checked it, it looked almost perfect except for those two issues that I raised.

• delegate vs stake. This is not a noun vs verb. I'm proposing delegate as a verb. Users are delegating to stake pools, while stakepools are the ones staking to the protocol. The actions are different, so that's why the difference. There is also a CF blogpost about it.

• while I was coding it's easier for a developer to check on keys rather to check on rules for values to try to deduce what it is.

• regarding my name. I really don't care, but I have been parts of the talks for deeplink since the very beginning with Seba and Vicente.

[nicarq]

About the keywords that I used those are the ones that you put in the proposal, because I tried to be the less disruptive as possible. If you want to change the keywords, go ahead!

As I mentioned, it would be great that we are in sync because I'm working in the integration with Yoroi (one of the top 2 wallets) and it would be great that we follow the CIP

[rphair]

stay tuned, getting another commit & comment ready...

[rphair]

As I mentioned, it would be great that we are in sync because I'm working in the integration with Yoroi (one of the top 2 wallets) and it would be great that we follow the CIP

of course @nicarq and I'm just trying to make sure the devs can implement this as quickly and properly as possible. I'm glad we've connected, one way or another, to get everyone unanimous somehow, and it's worth a little trouble to get the support of those like you who will be doing the work. 🙏

About the keywords that I used those are the ones that you put in the proposal, because I tried to be the less disruptive as possible. If you want to change the keywords, go ahead!

That's done although I had to allow for URIs maybe becoming too long, since when multi-pool links are added (per my earlier draft before merging with Seba, with some examples: CIP-COSD-MultiPoolStakeURIscheme.md) there should be enough links supported in a single URI, within its maximum length, to include as many pools as possible in a delegation portfolio (per #25 (comment)). For single links a long, mandatory keyword doesn't matter as much, but for portfolios these keywords might be repeated over a dozen times for pool hex ID's or over a hundred times for pool tickers.

So I've edited the grammar according to the UNIX convention that longer argument names are abbreviated by single letter arguments, leaving it to the user or programmer to choose brevity vs. clarity. Notes on the revised grammar:

• ticker is used in SMASH JSON metadata so I think the option should be a literal match in the grammar.
• t is an obvious one-letter abbreviation especially since p for pool would be ambiguous.
• hexid should be future proof (?) especially since unique pool identifiers to come in the future will probably be bech32 rather than hex. (I can't find a name for this identifier in the JSON ledger dumps, but if there's something more suitable I'll change it.)
• hex is not specific enough, while ticker is because it implies an ID.
• x is a better abbreviation for a hexadecimal string than h because of the universal base prefix 0x in most compiled languages.

regarding my name. I really don't care, but I have been parts of the talks for deeplink since the very beginning with Seba and Vicente.

In that case then yes I think you should be included, unless anyone objects... I've added you to the byline as per your own PR. 😎

The actions are different, so that's why the difference. There is also a CF blogpost about it.

My final comments on stake vs. delegate, for the history books if I'm overruled in this PR discussion:

We all (i.e. all reputable SPOs) read that paper (I bookmarked it) and I fully understood what you meant in your original posting. That understanding doesn't get any better or worse no matter how many times you repeat the same statement (3 times total now). I still don't agree for reasons I've already stated above. If you are going to repeat your original statement further then please, for the benefit of the group discussion, respond to my own specific statements above & below as well.

Executive summary: Looking beyond the wallet implementations, and beyond this particular CIP + current PR, future applications exist in which these stake pool URIs will not always result in a delegation.

The background discussion began in an earlier version of my own previously separate CIP (you yourself commented on that PR), particularly this section of CIP-COSD-MultiPoolStakeURIscheme.md:

automation & integration : allowing portfolio links to be generated through novel means by a greater variety of new & third party web sites, scripts & software tools, and checking real and hypothetical portfolios for past results and anticipated performance

So a whole collection of user stories would go like this:

• A wallet delegating to one or more pools, or a web-based "dream team" multi-stake-pool delegation portfolio analyser (this premise was discussed in my 2020 Catalyst proposal for Stake Pool Links) generates a Stake Pool URI for implementation OR sharing. At this point (prior to any user "clicking") the term "delegate" is not appropriate in the URI because these stake pools & proportions may never have delegated to by any user.
• Someone receives the link, which someone else might click on to delegate to in Daedalus or Yoroi... while another user may only run some analysis of their own: measure past rewards, anticipate future rewards, diff with a user's current stake pool selections (itself a URI), correlate with other social interests, compare with other hypothetical portfolios, and create new URIs through various types of fuzzy set unions and intersections.

Through all of this manipulation and sharing I am reading, creating, clicking, and generating stake pool URIs without ever delegating to any of them, so the term delegate is either appropriate only at the very end of the process, or never... while the term stake for "stake pool reference" is appropriate at every single step of the way.

Yes, according to the Cardano Foundation the term "delegate" should always apply to the specific user-initiated process of assigning wallet funds to a stake pool... in technical writing, press releases and documentation... but that doesn't apply to these URIs because they will be more generally used.

That's why I'm never going to agree that delegate is more appropriate than stake or a reference to a stake pool or weighted set of stake pools, no matter how many times that dogma-based premise is repeated. I have further nothing to say about the issue beyond what is written here. If I'm overruled, that's it... all I'd ask of other participants besides @nicarq and me that they give a detailed reading, understanding & consideration to what I've written above.

Hopefully this last elaboration will trigger some discussion here & then in the CIP meeting (Tuesday 23 February). I don't plan to attend that meeting mainly because I've already made my entire case here.

So please let me ask @SebastienGllmt @v-almonacid @dcoutts @admin-cf, and all others who plan to attend that meeting, to fully read & understand these last two long comments in advance, as they apply to stake vs. delegate... so we can all plan to adopt whatever consensus is obtained in the meeting or ASAP afterwards. Once that consensus is achieved, if required I'll apply it with one final commit & then we should be ready to move ahead with this.

[rphair]

Actually I found a big inconsistency between one of @nicarq's changes (regarding key vs. value for the stake pool reference(s)) with respect to the multi-pool links that would be the eventual goal of this URI scheme. Backing out last commit, and will undo the review requests if possible, and will post more info within the hour in my next comment...

[rphair]

I should have caught this sooner but there's an incompatibility between @nicarq's #65 and the eventual multi-pool form of Stake Pool URIs which @SebastienGllmt is already aware of (from before our agreement to delay it until a future pull request). I've backed out the last commit I made including the grammar change that I explained above in #61 (comment).

If, as in #65, the stake pool reference were a value of a constant key (instead of a key, like it is here) it would violate two requirements of multi-pool URIs:

1. A key (poolticker, in Nicolas's PR, and ticker in my comment above) cannot have multiple values: hence, no multi-pool links at all.
2. When implemented in wallets and other applications, multi-pool links won't just be a list of pools... they'll need to be weighted with stake proportions. Since each stake proportion will need to be an arbitrary (decimal) value, the pool ticker or hex ID itself needs to be the key.

I worked out some unambiguous rules for parsing multi-pool URIs which are in the final version of #25, before it was closed in favour of this PR, in this section of the original CIP draft: CIP-COSD-MultiPoolStakeURIscheme.md > Specification):

Example, a weighted portfolio: web+cardano://stake?CRAB=30.14&MYTH=20.84&NINJA=20.04&HYPE=17.80&MARLN=16.92&KINGS=16.81&COSD=15.62&RAID3=15.32&ZOE=15.20&XORN=14.93

So the main question is: How could Nicolas's suggestion to use the stake pool as a value, rather than a key, eventually accommodate multiple pools and weighted portfolios?

My inclination is that it's impossible... but that's not a problem since the key-value pairs in the example URI string above wouldn't make the parsing or implementation more difficult. URI GET variable parsers, like the commonly used one in the PHP library which follows the old CGI conventions, return an associative array of keywords (and values, if present): so in fact the necessary data structure will be set up properly from the beginning.

None of this reasoning needs to be in this PR because there's no reason to throw an error in the wallet if the pool URI key happens to have a value which will currently be ignored (since web URLs don't do that either). But future versions of the URI scheme will use any values that are found as stake pool weights whenever there's more than one pool. If you please read the rules in that proposed Specification carefully (since nobody did this initially the last time!) you will see that there are no strings of URI keys and values that produce either unachievable or ambiguous sets of stake pool weights (see #25 (comment)).

That's the showstopper for #65 ... no means of growing into multi-pool URIs. If anyone thinks I am wrong about that please post an alternative URI syntax here and we can all compare it to the "weighted portfolio" example above which is both human- and efficiently machine-readable, error-resistant and unambiguous.

The second issue of the stake vs. delegate authority prefix may remain important to some (I've already said my piece about that). In any case we now need the other authors/devs to write what they feel about both issues here before the next CIP meeting. Rather than just discussed in conclave and then minuted, the discussion of both points needs to be here out in the open as part of the public record of the Cardano community.

[nicarq]

@rphair kudos for the effort! I know how to solve the issues (actually everything works fine with the way that I proposed it just needs to be explained how to be extended), maybe let's sync outside Github? e.g. Telegram. That way we can maintain the amount of reads to a minimum for the editors

[rphair]

sure @nicarq I've just started that off by email (can break to Telegram if it gets chatty) with these two questions, for the record (once we have full answers & agreement I'll summarise in the PR with key quotes):

---

Could you start by 1 - outlining exactly what parsing or interpretation difficulties you anticipate in using the pool names/IDs as keys? I'm accepting on faith that you & the wallet developers will have some problem with that, but I have no idea what that problem could be even after developing some URI interfaces myself.

2 - Using key/value pairs of pool/proportion can be shown easily with an indirect proof to be the densest way of representing this information. Therefore, both logically & intuitively, it's the representation least likely to produce combinations that are syntactically invalid or practically impossible. So we must establish that the alternative you're imagining will accomplish the same goals.

I've thought about this representation for months and probably so have you. So please let's make sure I understand point (1) first so I can be clear on the need for any changes at all. Then a big part of (2) will be to make sure that any URI syntax rewritten to be machine-friendly has not become user-unfriendly.

[crptmppt]

as noted in #65 - @nicarq @rphair - it would be great if either or both of you can join our next CIP meeting to discuss the current state of resolution for both those overlapping PRs.

[rphair]

@crptmppt @KtorZ @dcoutts @SebastienGllmt as it came up in today's meeting: If anyone is interested in polling the SPO community for its own preferences regarding formulation of stake pool links, I've done my best to introduce & poll the question here on the CF forum: https://forum.cardano.org/t/web-links-to-stake-pools-stake-or-delegate/49183

There's been no engagement so far, but someone seen as more officially connected might get a better response from posting something here, linking or backing this posting somehow, and/or retweeting the poll.

[SebastienGllmt]

Thought: since this PR is to extend an existing CIP (which has a competing proposal by Nico), maybe it makes sense to have this PR rename the CIP to 13-A and then have Nico submit his proposal as 13-B? It's not great to have two CIPs using the same number (maybe that breaks something in the pipeline?), but it's the best way I could think to encode the fact they're two separate extensions of the original CIP13.

[rphair]

sure @SebastienGllmt I'd be OK with that, after it's confirmed that #65 is, in fact, a competing proposal. The more crucial part 1 of the publicly presented question #65 (comment) remains publicly unanswered, so until that identified incompatibility is addressed in that PR there is still only one viable track for CIP-0013 and therefore no need to rename anything.

[rphair]

Reposting from where this issue is being discussed a bit between SPOs representing each point of view: https://forum.cardano.org/t/web-links-to-stake-pools-stake-or-delegate/49183/3

... everybody agrees with you that "delegate" is the most accurate word in DPoS for what people are doing when they open a link in their wallet UI to assign their stake to the referenced stake pool(s). The Cardano Foundation & IOG Marketing have both therefore insisted upon that terminology in their public communications.

Yet we're in a different situation here because these URIs will also send information from one computer or web app to another without a delegation ever taking place. So that issue of "trust" is of general importance but specifically irrelevant if not misleading in those cases. For instance, you're not "delegating" when you simply want to look at the expected returns of a weighted delegation portfolio, or simply sending or recording the names (and perhaps proportions) of some stake pool(s) for some other reason.

Another point raised in our last CIP meeting is that we'll soon have oracle pools in addition to stake pools. At that time //oracle will likely refer to oracle pools & operations... and perhaps other resources called literally what they are... with the exception of stake pools which might forever be called //delegate because of the business & social pressures that existed at the time.

[if I had to do it over again] "I'd spell creat with an 'e'."
Ken Thompson, creator of UNIX