Having the meta data in the GitHub of the Cardano Foundation is a temporary solution. This extract from the “Design Specification for Delegation and Incentives in Cardano–Shelley” shows the design for the Shelley mainnet.
It can be found here: https://github.com/input-output-hk/cardano-ledger-specs/tree/master/shelley/design-spec on page 30 the following. (Latex format)
4.2 Stake Pool Metadata
The stake pool registration certificate can contain a URL (up to 64 bytes), pointing to a JSON object with the following content:
A Ticker of 3-5 characters, for a compact display of stake pools in a wallet.
A Title/Name of up to 50 characters.
A Short Textual Description
A URL to a homepage with additional information about the pool.
A list of IP addresses and/or DomainNames of public relay nodes that the stake pool operator provides to contribute to the Cardano network.
A set of tags, keywords that can be used to filter stake pools in the wallet UI. For example, a stake pool that gives their rewards to a charity might indicate this by using a “charity” tag. Other tags could specify the geographic location, or whether a pool is running on cloud infrastructure or a physcial server owned by the pool operator.
All characters in the metadata will be UTF8 encoded. The metadata is restricted to have a size of no more than 512 bytes.
The stake pool operators are responsible for serving this data at the URL provided in the stake pool registration certificate. However, wallets will not retrieve the data for each stake pool at those individual URLs. Not only would that be inefficient, it would also allow malicious actors to intentionally slow down all wallets by intentionally delaying the response of their server. Instead, metadata will be cached on metadata proxy servers.
Those proxy servers will query the metadata URLs in the stake pool registration certificates, and cache the metadata, with the pool’s sks as key. Invalidating the cache will be triggered when the content hash listed in the certificate does not match the content hash of the cached metadata. The wallet will then retrieve the metadata for pools it needs to display from one of the proxy servers, instead of having to send a request to each of the pool’s metadata URLs.
Those servers are simple, and in particular, they require relatively little trust: because of the content hash, someone running a proxy server can not display forged metadata. The worst thing they can do is filter the list of stake pools.
In order to avoid those proxy servers to become a point of centralisation of the system, we will encourage third parties (stake pools, people in the community) to run metadata proxy servers, and provide code and binaries for the proxies. Wallets should be configurable to query a number of those proxy servers.
Another function that the metadata proxy servers provide is filtering malicious entries: it is possible to embed a variety of malicious content in the metadata, and in particular via the link to the stake pool’s homepage. Should it become known that a particular pool hosts dangerous or illegal content15, maintainers of a metadata proxy can filter that entry and not provide it to wallets. This is an advantage over writing the metadata directly to the chain, in which case there would be no way to protect wallet users from visiting malicious sites directly from their wallet.
4.3 Display of Stake Pools in the Wallet
The wallet software will maintain a set of all the active stake pools. For each, it will perform a lookup of the contained sks to retrieve the corresponding metadata to display to the user.
In order for stakeholders to be able to delegate their stake to a pool, the wallet will provide a listing of stake pools, in a section of the UI called the delegation centre. In order to make it easy for users to do a rational choice when delegating, this listing will be ordered by the rewards that the user should expect from delegating to each pool. In particular, we use the non-myopic pool member rewards, Equation (3) in Section 5.6.1. Since this ordering depends not only on the costs and margin set by the stake pool operator, but also on the performance of the pool and on the amount of stake that it already has accumulated, this will promote pools that are reliable, have not yet reached saturation, and have a low cost and margin. In other words, the users selfish interest to pick a stake pool that is promising large rewards is aligned with the goal of placing the system in the hands of a number of reliable stake pool operators, and of avoiding centralisation. The influence of the stake pool operator’s pledge on the rewards provides protection against a Sybil attack on the stake pool level (Section 2.2.1).
When calculating the expected rewards, the wallet will use the best data available:
-
The cost, margin, and pledged stake will be taken from the most recent stake pool registra- tion certificate of the pool.
-
The performance of the pool will be taken as the moving average, as described in Sec- tion 5.6.5.
-
The stake of the pool, and the amount of stake that the owners of the pool contribute (in order to check whether their pledge is honoured) is taken from the current stake distribution (calculated from the current UTxO set and delegation relation on demand when the wallet performs the ordering).
-
The member stake t in Equation (3) is taken to be the stake that the user is about to delegate.For listings outside of the wallet, for informational purposes of which pools are generally desirable, we can instead divide off the factor t in Equation (3)16 and get the reward per stake delegated to a pool, assuming that the delegated stake is small enough to not push the pool over the saturation threshold.When the wallet is running and the user has delegated to a stake pool, the wallet should monitor the non-myopic rewards regularly. Should the stake pool become less favourable (by missing blocks, or even becoming inactive, or by changing its cost/margin), the wallet should notify the user, and ask them to consider changing their delegation.We had considered adding some jittering to the ordered list of stake pools, in order to prevent a situation where a slight difference in the expected rewards would lead to stakeholders all delegating to the same, slightly more preferable, pool. We decided against this, since
-
Our incentive structure will have stake pools saturating anyway.
-
Randomising the order of display makes it more difficult for stake pool operators to behave rationally when setting their cost and margin.
