CIP-0017: Cardano Delegation Portfolio

[KtorZ]

Abstract

This document details a common format for sharing Cardano delegation portfolio across various tools and wallets.

Motivation

Stakeholders have indicated the desire to split their stake in various sizes and delegate to n pools from a single wallet/mnemonic. Albeit there are no monetary incentive for users to do this, the desire to drive decentralisation is sufficiently prevalent to justify it. Furthermore, stakeholders want to introduce a certain social element to this activity by sharing their delegation portfolio with other stakeholders. This specification should help to standardize the representation of portfolios across tools for more interoperability.

Specification

Overview

We'll use JSON as a data format for it is commonly used and supported across many programming languages, and is also relatively readable on itself. Portfolios should abide by the JSON schema given in appendix.

At minima, a portfolio should cover a list of delegation choices (pools and weights) and have a human-readable name for easier identification.

Weights

For each pool, we demand a weight which can capture a certain stake proportion within the portfolio. The value is an integer, and relative to other weights in the portfolio. For example, a portfolio with two pools and respective weights of 1 and 2 means that we expect users to assign twice more stake to the second pool than the first. Fundamentally, this means that for every 3 Ada, 1 Ada should go to the first pool, and 2 Ada should go to the second. Note that this is equivalent to having weights of 10/20 or 14 / 28. Weights are ultimately interpreted as fractions.

Portfolios which treat all stake pools equally should use the same weight (e.g. 1) for each pool.

Rationale

1. JSON is widely used, widely supported and quite lightweight. Makes for a reasonable choice of data format.

2. Using JSON schema for validation is quite common when dealing with JSON and it's usually sufficiently precise to enable good interoperability.

3. The portfolio should only capture information that are not subject to radical change. That is, stake pools parameters like pledge or fees are excluded since they can be changed fairly easily using on-chain certificate updates.

4. The JSON schema doesn't enforce any additionalProperties: false for neither the top-level object definition nor each stake pool objects. This allows for open extension of the objects with custom fields at the discretion of applications implementing this standard. The semantic of well-known properties specified in this document is however fixed.

5. Since the portfolio format isn't immediately user-facing, we favor base16 over bech32 for the pool id's encoding for there's better support and tooling for the former.

Backwards Compatibility

Adafolio (https://adafolio.com)

The format used by Adafolio share a lot of similarities with the proposed format in this CIP. In order to power its frontend user interface, Adafolio contains however several fields which we consider too volatile and unnecessary to the definition of a portfolio. This doesn't preclude the format used by Adafolio as a valid portfolio format (see also point (4). in the rationale above).

The only point of incompatibility regards the pool_id field (in Adafolio) vs the id field (in this proposal) which we deem more consistent with regards to other field.

Reference Implementation(s)

Examples

{ "name": "Metal 🤘"
, "description": "Pools supporting Metal music across the world."
, "pools": 
  [ { "id": "d59123f4dce7c62fa74bd37a759c7ba665dbabeb28f08b4e5d4802ca"
    , "name": "Dark Tranquility"
    , "ticker": "DARK"
    , "weight": 42
    }
  , { "id": "5f3833027fe8c8d63bc5e75960d9a22df52e41bdf62af5b689663c50"
    , "ticker": "NITRO"
    , "weight": 14
    }
  , { "id": "a16abb03d87b86f30bb743aad2e2504b126286fe744d3d2f6a0b4aec"
    , "name": "Loudness"
    , "ticker": "LOUD"
    , "weight": 37
    }
  , { "id": "9f9bdee3e053e3102815b778db5ef8d55393f7ae83b36f906f4c3a47"
    , "weight": 25
    }
  ]
}

Copyright

CC-BY-4.0

[wrmarchetto]

Adafolio developer here! We are very excited to see this CIP submitted. We're happy to make any changes necessary to our portfolio JSON format to accommodate this specification, and we fully support what has been proposed here (for whatever that's worth). Our current JSON definition was only intended to be a placeholder until a spec was defined. If our involvement in any part of the implementation or testing of this feature would be helpful, please feel free to contact us!

[rphair]

@KtorZ @wrmarchetto it's nice to see all this stuff finally coming together. Last September with #25 > Rationale I published a heap of use cases and was imagining a whole range of sites like Adafolio, with both curated & crowdsourced portfolios and some means of ranking, classifying and/or analysing them.

Crowdsourced portfolios could be even more finely distributed through the Internet as URIs, in addition to being an easy link to wallets & other apps without the generating web site having to generate a JSON file and properly dispose that additional content from the web server. JSON in turn will provide stability, verification, and a product of pool set size * precision that the URIs cannot. It will be great for users & devs to have both options.

Since the multi-pool aspect of that originally written CIP is now published as #86 I would be really happy for both your review & comment, since there are likely to be common elements between the two resulting CIPs.

[rphair]

comments on CIP draft itself

... split their stake in various sizes and delegate to n pools ... Albeit there are no monetary incentive for users to do this, the desire to drive decentralisation is sufficiently prevalent to justify it.

It is true this is necessary for decentralisation, but not true about the lack of monetary incentive. For a vivid example, compare the following portfolio analyses (figures from the day of this posting) and also note the "High Performance" bar could be set even higher and still include a dependable pool set size:

• All Pools (Stake Pools: 2476): Current ROS: 3.22%
• Large Pools (Stake Pools: 383): Current ROS: 5.03%
• High Performance (Pools: 582): Current ROS: 5.40%

It might even help the proposal to replace that statement with its opposite: e.g. that monetary incentives exist to maximise a user's delegation rewards by selecting portfolios based on performance, especially while contemporary pool ranking algorithms in the wallets continue not to do this.

"weight": { "type": "integer", "minimum": 1 }

Some users & developers will require decimals as the stake pool weights in order to build portfolios that match the following real world values (at some given time), without having to normalise the order of magnitude or suffer round-off error:

• ada balances in wallets
• measured rewards from wallets or staking tools
• percentage or ratio performance measurements (e.g. lifetime ROA, period ROA) from third parties

A security consideration suggested for URI delegation portfolios will also be applicable to JSON portfolios:

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).

One possible solution is to scale all the pool weights so that the largest is 1, which obfuscates any literal ada or lovelace balance in the wallet which could also be publicly visible & link a portfolio creator's identity to their wallet (this was suggested here last year = "When exporting proportions").

[KtorZ]

@rphair Thanks for your extended comment(s)! Only going through it now and, I do agree about the framing w.r.t to the monetary incentive. It is true that for stakeholders with large enough stake, there's a monetary incentive to delegate to multiple pools. I'll rephrase that.

On the topic of decimals in weights now. The weights are purposely plain integers because of all the complication coming with floating arithmetic and float number parsing with IEEE-754 compliant systems. Using weights as such really defines them as ratio of two numbers which can always be represented without ambiguity.
Furthermore, I (firmly) opposed introducing decimals here because it only gives an illusion of precision. At the very end, one can only delegate the stake associated with a UTxO. So, the delegation distribution is only as precise as the available UTxO allows it to be. If a wallet has 2 UTxO of 10 and 100 Ada, there's no way you can achieve a 50/50 distribution anyway. Weights are therefore only a best effort and being extra precise about them is simply pointless. They are stretched goals for wallets to asymptotically approach, nothing more.

I'll make that clearer in the specification because it may not be obvious to the reader.

[rphair]

Just let me repeat first for the record & for new visitors that I have never suggested using floating point notation for the stake pool weights. And as you know there is no more ambiguity with decimal ratios than there is with integer ratios.

So remaining question is why the precision of either representation is likely to be real rather than a false suggestion. Foremost we should include @SebastienGllmt since the last information I've seen presented to the public about multi-pool delegation options, in this interview with him, suggested out of a number of approaches that precise staking ratios implemented in the protocol itself would be "cleaner" and "better" than having to "juggle UTxO's around" (I'm quoting from memory) or to go on as you say above with only rough approximations of the portfolio proportions: https://www.youtube.com/watch?v=H_Map7ncsWc

If Sebastien's or anyone's road map for delegation portfolio support has been developed or confirmed anywhere else since then, we should link to it here. Until then we have to assume that precision of multiple significant figures will eventually be supported in the protocol and therefore:

1. has to be supported in the URI standard.

2. An assumption of "crude" approximation for stake ratios cannot be used to disqualify the need for decimals, or anyone's preference for using them, in either the JSON or URI formulations of a delegation portfolio standard.

Since I've heard the "better way" of protocol ratio staking scheduled as a "long way off" in meetings and private discussions and then used as a justification for the multi- Stake Pool URI proposal being slow-tracked, it would be a double standard for the developers not to see "ratio staking" as the preferred method. But if an earlier "crude" implementation with one-time UTxO balancing (and then allowing "drift") is what it takes to get these portfolios implemented sooner in the wallets, then other portfolio advocates & I would be happy to see it. Yet since those wallets will eventually move to protocol-supported precise stake ratios (until proven otherwise), the URI & JSON portfolio standards need to include precision support from the beginning, by whatever means users and developers choose to implement that precision (while avoiding the tricky & ambiguous floats).

The final arguments for enforcing integers might be of the "it's cleaner" variety (cleaner parsing, simpler variable types, etc.). I don't see that it would be cleaner overall in terms of the user, since people have already been seeing decimal values and proportions in Cardano since Day 1. Foremost example: the 6 figures of lovelace on top of the whole number ada, now part of the Cardano community's conditioning for years.

• So since they will be using decimals in the JSON files and URIs anyway (as a front-end / UX designer I can tell you users will instinctively push that envelope, no matter what it says in the standard) then you'd just have a messier job on your hands with lots of syntax errors or warnings... or disclaimers about why you have to drop the fractions, even for numbers close to zero for which the decimal may be a huge part of the whole... i.e. what is "simpler" in this case may not overall be easier.

[crptmppt]

This was again discussed at the last Editor meeting (22), please refer to the notes to catchup on the conversation.
This tentative CIP is scheduled to be discussed further at the next public meeting this Tuesday, thank you for attending as feasible to broaden/continue the conversation.

[crptmppt]

This was discussed at the last Editor meeting (23), please refer to the notes.
An outreach is in progress towards the community/SPOs to gather preferences and open the conversation.
@rphair is to connect through a SPO dev townhall (likely June 10th) while a broader "CIP-themed" SPO call is tentatively scheduled for June 24th. (the next CIP Editors meeting after that should be Editors meeting 26 on July 6th.

[crptmppt]

Discussed at last Editors meeting (24) - see notes. (conversation might be ahead of meeting notes at this point, this is a reference)

The conversation was further opened up with two SPO meeting.
(Adding this PR as a "Discussion" for tomorrow's CIP Editors Meeting (25 - in contrast to PR86 in the hope of consolidating)

[crptmppt]

2021?

[crptmppt]

6/29 Editors meeting (25) discussed this PR - see notes. (conversation might be ahead of meeting notes at this point, this is a reference)

=> PR is now in 'Last Check': it will get another look at next week's meeting (26) and should be merged in after that - consider attending the meeting if relevant to you.