CIP-0017: Cardano Delegation Portfolio

CIP-0017/CIP-0017.json

@@ -0,0 +1,54 @@
+{ "title": "CIP-0017 - Cardano Delegation Portfolio"
+, "$schema": "https://json-schema.org/draft-07/schema"
+, "type": "object"
+, "required":
+    [ "name"
+    , "pools"
+    ]
+, "properties":
+    { "name":
+        { "type": "string"
+        , "minLength": 1
+        }
+    , "description":
+        { "type": "string"
+        , "minLength": 1
+        }
+    , "author":
+        { "type": "string"
+        , "minLength": 1
+        }
+    , "pools":
+        { "type": "array"
+        , "minItems": 1
+        , "items":
+            { "type": "object"
+            , "required":
+                [ "id"
+                , "weight"
+                ]
+            , "properties":
+                { "id":
+                    { "type": "string"
+                    , "minLength": 56
+                    , "maxLength": 56
+                    , "contentEncoding": "base16"
+                    }
+                , "name":
+                    { "type": "string"
+                    , "minLength": 1
+                    }
+                , "ticker":
+                    { "type": "string"
+                    , "minLength": 3
+                    , "maxLength": 5
+                    }
+                , "weight":
+                    { "type": "integer"
+                    , "minimum": 1
+                    }
+                }
+            }
+        }
+    }
+}

CIP-0017/CIP-0017.md

@@ -0,0 +1,86 @@
+---
+CIP: 17
+Title: Cardano Delegation Portfolio
+Authors: Matthias Benkort <matthias.benkort@iohk.io>
+Comments-Summary: A Common format for sharing Cardano delegation portfolios
+Comments-URI: https://github.com/cardano-foundation/CIPs/wiki/Comments:CIP-0017
+Status: Active
+Type: Standards
+Created: 2020-04-02
+License: CC-BY-4.0
+---
+
+# 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](CIP-0017.json). 
+
+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
+
+```json
+{ "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

README.md

@@ -1,5 +1,6 @@
 # Cardano Improvement Proposals (CIPs)
 
+
 Cardano Improvement Proposals (CIPs) describe standards, processes; or provide general guidelines or information to the Cardano Community. It is a formal, technical communication process that exists off-chain.
 The current process is described in details in [CIP1 - "CIP Process"](./CIP-0001/CIP-0001.md).