Add new interim governance commands: {create, answer, verify}-poll

[Jimbo4350]

Original PR by @KtorZ: 5050

The Cardano Foundation proposes a mechanism for polling Cardano stake pool operators on specific topics. Polls are done on-chain through transaction metadata and authenticated through stake pool credentials (either VRF public key similar to what's described in CIP-0022 or Ed25519 cold key).

The goal is to gather opinions on governance matters such as protocol parameters updates. This standard is meant to be an inclusive interim solution while the work on a larger governance framework such as CIP-1694 continues.

See proposed CIP for details.

---

This commits adds three new commands:

• create-poll: For the current governing entities, as a means to create new polls.

• answer-poll: For participants who want to answer a given poll.

• verify-poll: For anyone who seek to verify a poll entry (e.g. explorers)

The commands are built to fit and play nicely within the cardano-cli. The poll and answers structures are based on transaction metadata and require to be embedded in an actual transaction. The added commands however only works from metadata and raw "GovernancePoll" envelopes.

---

Tutorial

Pre-requisites

Here's a quick tutorial on how to interactively submit an answer to an SPO
survey. To start, you must have received a valid survey in the form of a JSON
files properly constructed using the create-poll command. The file should
look roughly like the following:

poll.json

{
    "type": "GovernancePoll",
    "description": "An on-chain poll for SPOs: Pineapples on pizza?",
    "cborHex": "a1185ea2007450696e656170706c6573206f6e2070697a7a613f018263796573626e6f"
}

Warning

Surveys will be make 'official' using a signature from the genesis delegate
key; the signature is however not present in metadata but used as extra
signatory on the originating transaction.

Creating answer

From there, you can create a metadata entry to answer the survey using the
governance answer-poll command as such:

$ cardano-cli governance answer-poll --poll-file poll.json --signing-key-file key.secret

Note that:

1. The key specified as --signing-key-file can/must be either a VRF secret
   key or a stake pool cold private key (Ed25519) in the JSON/Text-Envelope
   usual format expected by the cardano-cli. Here are an example of each:

   VRF key

   {
       "type": "VrfSigningKey_PraosVRF",
       "description": "VRF Signing Key",
       "cborHex": "5840b23fa897c1fc869d081e4818ea0ac533c1efaccb888cb57d8a40f6582783045d2dc2fa217af8b52251c4cdf538fa106cbf0b5beac3e74d05f97ceb33c0147a2c"
   }

   Cold key

   {
       "type": "StakePoolSigningKey_ed25519",
       "description": "Stake Pool Operator Signing Key",
       "cborHex": "58201d298ffa1544da0a5b2ea544728fc1ba7d2ae7c60e1d37da03895019740dd00a"
   }

2. This command will prompt you to answer interactively. If you do not wish to
   be prompt interactively, you can use --answer with the index of the
   answer.

Running this command will display the survey in a human-readable form, and
prompt you for an answer, as shown below:

An on-chain poll for SPOs: Pineapples on pizza?
[0] Yes
[1] No

Please indicate an answer (by index): _

You can proceed by typing one of the possible answer index (here, 0 or 1)
and a newline. This will print witnessed metadata in the form of a JSON
detailed schema that shall then be posted on-chain in any transaction: the
easiest being to build a simple transaction to yourself carrying the metadata.

Here's an example of metadata using a VRF key and choosing the answer 0:

answer.json

{
  "94": {
    "map": [
      {
        "k": { "int": 2 },
        "v": { "bytes": "c9a077a1098d73498d17e9ea27045af820c311ced91f8c2bb9b5c7f446379063" }
      },
      {
        "k": { "int": 3 },
        "v": { "int": 0 }
      },
      {
        "k": { "int": 4 },
        "v": {
          "list": [
            { "bytes": "2dc2fa217af8b52251c4cdf538fa106cbf0b5beac3e74d05f97ceb33c0147a2c" },
            {
              "list": [
                { "bytes": "3606afd8d437a69a0c94ebff7fe57638bdb54bd03193c3c830808187a5d740222ab26fa3f1b7df8b22e846196dda1ee16d4d6e64c062129e07273ec36c06f453" },
                { "bytes": "06c46025c18deaa04aa45913e1c91906" }
              ]
            }
          ]
        }
      }
    ]
  }
}

Publishing answer

From there, you can use the transaction build command to create a transaction
to post on-chain. You'll need a signing key associated to a UTxO with enough
funds to carry the transaction (~0.2 Ada should you make a basic transaction to
yourself).

Assuming you have saved metadata produced from the previous step in a file
called answer.json, the command for building the transaction shall look like:

$ cardano-cli transaction build \
    --babbage-era \
    --cardano-mode \
    --mainnet \
    --tx-in ...#... \
    --change-address addr1... \
    --metadata-json-file answer.json \
    --json-metadata-detailed-schema \
    --out-file answer.tx

You'll need to fill-in --tx-in & --change-address with their corresponding
values. From there, you can sign answer.tx and submit the result as usual. If
everything goes well, the cardano-cli should display a transaction id that you
can track on-chain to ensure your reply to the survey was properly published.

Verifying Answers

Finally, it's possible to verify answers seen on-chain using the governance verify-poll command. What 'verify' means here is two-folds:

• It checks that an answer is valid within the context of a given survey
• It controls the witness (i.e. proof or signature) provided with it

Assuming you still have the original poll.json file, and some witnessed
metadata (as provided by the governance answer-poll command, and as found in
transactions on-chain) as answer.json, you can verify its validity via:

$ cardano-cli governance verify-poll --poll-file poll.json --metadata-file answer.json

On success, this should outputs:

Ok.

Otherwise, the command will formulate an issue with the answer and/or poll.

Commit split context: #5050 (comment)

[dcoutts]

For what it's worth, I'm not happy with the CIP design, but that's a separate issue I suppose.

cardano-foundation/CIPs#496 (review)

One comment below about fishy behaviour in the VRF verification.

[dcoutts]

This is fishy. It's at minimum being unreasonably cozy with the implementation, rather than relying on the class interface.

[KtorZ]

Yes this is a slight abuse of the interface because the current class API requires the Output (the undefined term here) without making any use of it since it is actually irrelevant to the verification process. Since in this scenario we do not even care about the outputs (as you're rightfully pointing out in the CIP's comment), I didn't feel like bothering end-users with them either just for the sake of satisfying an interface that's arguably not restrictive enough.