CIP-0022 | Adjust preamble and structure w.r.t CIP-0001 (cardano-foundation#668)

* first draft remediation of CIP-0022

* fixed non canonical CIP ID

* fixed language artefact from editing implementors list

Author: rphair

CIP-0022/README.md

@@ -1,40 +1,42 @@
 ---
 CIP: 22
 Title: Pool operator verification
-Authors: Andrew Westberg <[email protected]>, Martin Lang <[email protected]>, Ola Ahlman <[email protected]>
-Comments-URI: no comments yet
 Status: Active
-Type: Informational
+Category: Tools
+Authors:
+  - Andrew Westberg <[email protected]>
+  - Martin Lang <[email protected]>
+  - Ola Ahlman <[email protected]>
+Implementors:
+  - CNCLI
+  - JorManager
+  - StakePoolOperator Scripts
+  - CNTools
+Discussions:
+  - https://github.com/cardano-foundation/CIPs/pull/102
 Created: 2021-06-21
 License: CC-BY-4.0
 ---
 
-# Abstract
+## Abstract
 
 This proposal describes a method allowing a stakepool operator to provide credentials to verify that they are the rightful manager for their stakepool.
 
-# Motivation
+## Motivation: why is this CIP necessary?
 
 Many websites such pooltool.io, adapools.org, and others need to allow pool operators special access to modify the way their pool appears on the website. SPOCRA and other organizations also have a need to allow voting on proposals and ensure that each vote cast is from a valid pool operator. Today, these sites and organizations all use different techniques for validating pool operators.
 
 pooltool.io - Validates operators by receiving 1 ada spent from the pool's registered rewards account
 
 adapools.org - Validates operators by requesting that the operator include a special generated value in their extended pool metadata json file.
 
-This proposal desires to simplify and streamline a single approach that all can reference in order to verify that a pool operator is who they say they are.
+This proposal is to simplify and streamline a single approach that all can reference in order to verify that a pool operator is who they say they are.
 
-Current Tools that have implemented it already or have plans to implement it:
-* [CNCLI](https://github.com/AndrewWestberg/cncli)
-* [JorManager](https://bitbucket.org/muamw10/jormanager/)
-* [StakePoolOperator Scripts](https://github.com/gitmachtl/scripts)
-* [CNTools](https://cardano-community.github.io/guild-operators/#/Scripts/cntools)
-
-
-# Specification
+## Specification
 
 In order to achieve the goals of this CIP, the pool operator needs to provide some credential or credentials to the validating party which cannot be spoofed. The VRF pool keys and VRF signature algorithm implemented in libsodium are chosen to build and provide this credential/signature. This signature can then be validated and the operator verified without ever exposing any of the pool's private key information. This technique is very similar to verifying that a block produced by another pool is valid. The only difference is that instead of validating the slot seed for a given pool, we're validating a pre-determined message hash.
 
-## Verification Steps:
+### Verification Steps:
 
 1. Stakepool Operator (SPO) sends their pool_id and public pool.vrf.vkey to the Validating Server (VS)
 2. VS validates that the vrf hash in the pool's registration certificate on the blockchain matches the blake2b hash of the sent vkey. Note: The VS should use the latest registration certificate on the chain for matching as the VRF is a "hot" key and can be changed at any time by the pool operator. A single point-in-time verification is sufficient to properly identify the pool operator.
@@ -43,8 +45,7 @@ In order to achieve the goals of this CIP, the pool operator needs to provide so
 5. The SPO sends this to VS as the challenge response within a 5-minute window to the VS
 6. The VS validates the signed challenge response
 
-
-## Code Example (Validating server):
+### Code Example (Validating server):
 
 ```kotlin
 // Server side, create inputs for a challenge. Store this and only allow responses
@@ -56,7 +57,7 @@ random.nextBytes(nonce)
 println("domain: $domain, nonce: ${nonce.toHexString()}")
 ```
 
-## Code Example (Pool Operator side):
+### Code Example (Pool Operator side):
 
 ```kotlin
 // Node operational VRF-Verification-Key: pool.vrf.vkey
@@ -88,7 +89,7 @@ val signature = SodiumLibrary.cryptoVrfProve(vrfSkey, challenge)
 println("signature: ${signature.toHexString()}")
 ```
 
-## Code Example (Validating server):
+### Code Example (Validating server):
 
 ```kotlin
 // Server side, verify the message based on only knowing the pool_id, public vkey, signature, and constructing
@@ -112,7 +113,7 @@ println("verification: ${verification.toHexString()}")
 println("Verification SUCCESS!")
 ```
 
-## Code Example output:
+### Code Example output:
 
 ```
 vrfSkey: adb9c97bec60189aa90d01d113e3ef405f03477d82a94f81da926c90cd46a374e0ff2371508ac339431b50af7d69cde0f120d952bb876806d3136f9a7fda4381
@@ -125,10 +126,26 @@ verification: 9ca4c7e63ba976dfbe06c7a0e6ec4aec5a5ef04b721ffc505222606dfc3d01572d
 Verification SUCCESS!
 ```
 
-# Rationale
+## Rationale: how does this CIP achieve its goals?
+
+Implementing this simplifies and commonizes the process for verifying that a pool operator is who they say they are in 3rd party systems. Having a common way of verify pool operators also allows simple integration into pool management tools.
+
+There is also some overlap with [CIP-0006](https://github.com/cardano-foundation/CIPs/blob/master/CIP-0006/README.md#extended-metadata---flexible-but-validable) and the `rawdata-sign` command although it specifies generating a new key instead of utilizing the pool's existing `vrf.skey` to sign like this proposal.
+
+## Path to Active
+
+### Acceptance Criteria
+
+- [x] Tools that have implemented, or are implementing, this proposal:
+  - [x] [CNCLI](https://github.com/AndrewWestberg/cncli)
+  - [x] [JorManager](https://bitbucket.org/muamw10/jormanager/)
+  - [x] [StakePoolOperator Scripts](https://github.com/gitmachtl/scripts)
+  - [x] [CNTools](https://cardano-community.github.io/guild-operators/#/Scripts/cntools)
+
+### Implementation Plan
 
-Implementing this simplifies and commonizes the process for verifying that a pool operator is who they say they are in 3rd party systems. Having a common way of verify pool operators also allows simple integration into pool management tools. There is also some overlap with [CIP-006](https://github.com/cardano-foundation/CIPs/blob/master/CIP-0006/CIP-0006.md#extended-metadata---flexible-but-validable) and the `rawdata-sign` command although it chooses to generate a new key instead of utilizing the pool's existing vrf.skey to sign like this proposal.
+- [x] Consensus between providers of the most popular tools and CLIs for stake pool operators that this approch is viable and desirable.
 
-# Copyright
+## Copyright
 
-This CIP is licensed under [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode)
+This CIP is licensed under [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode).