Add documentation about VoteCast transaction structure (#141)

This PR is a port of the following one
input-output-hk/chain-libs#836

Author: minikin

src/chain-libs/chain-impl-mockchain/doc/format.abnf

@@ -44,6 +44,12 @@ FRAGMENT-SPEC    = %x00 INITIAL
                  / %x07 POOL-UPDATE
                  / %x08 UPDATE-PROPOSAL
                  / %x09 UPDATE-VOTE
+                 / %x0a VOTE-PLAN
+                 / %x0b VOTE-CAST
+                 / %x0c VOTE-TALLY
+                 / %x0d MINT-TOKEN
+                 / %x0e EVM
+                 / %x0f EVM-MAPPING
 
 ; ####################
 ; FRAGMENT only present in genesis block
@@ -139,6 +145,52 @@ CHANGES           = SIZE-ELEMENT-16BIT ; number of changes
 
 PROPOSAL-ID       = FRAGMENT-ID
 
+
+; ####################
+; FRAGMENT Vote plan, vote cast, vote tally
+; ####################
+
+VOTE-PLAN         = PLAN-CERT IOW ED25519-SIGNATURE
+VOTE-CAST         = CAST-CERT IOW
+VOTE-TALLY        = TALLY-CERT IOW
+
+PLAN-CERT         = VOTE-START VOTE-END COMMITTE-END PROPOSALS PAYLOAD-TYPE
+
+VOTE-START        = BLOCK-DATE
+VOTE-END          = BLOCK-DATE
+COMMITTE-END      = BLOCK-DATE
+PROPOSALS         = SIZE-ELEMENT-8BIT *PROPOSAL-ELEMENT 
+PROPOSAL-ELEMENT  = TODO
+
+CAST-CERT         = VOTE-PLAN-ID PROPOSAL-INDEX CAST-PAYLOAD
+PROPOSAL-INDEX    = U8
+CAST-PAYLOAD      = %x01 CHOICE; Public payload
+                   / %x02 ENCRYPTED-VOTE PROOF-VOTE ; Private payload
+CHOICE            = U8
+ENCRYPTED-VOTE    = SIZE-ELEMENT-8BIT *CYPHERTEXT
+CYPHERTEXT        = E1 E2 
+PROOF-VOTE        = SIZE-ELEMENT-8BIT *ANNOUNCEMENT *CYPHERTEXT *R-RESPONSE SCALAR ; size of the *ANNOUNCEMENT, *CYPHERTEXT, *R-RESPONSE are equal to SIZE-ELEMENT-8BIT value
+ANNOUNCEMENT      = I A B
+R-RESPONSE        = 3 * SCALAR
+I                 = GROUP-ELEMENT
+A                 = GROUP-ELEMENT
+B                 = GROUP-ELEMENT
+E1                = GROUP-ELEMENT
+E2                = GROUP-ELEMENT
+
+TALLY-CERT        = VOTE-PLAN-ID TALLY-PAYLOAD
+TALLY-PAYLOAD     = %x01 ; Public payload
+                   / %x02 PRIVATE-TALLY ; Private payload       
+PRIVATE-TALLY     = SIZE-ELEMENT-8BIT *TALLY-ELEMENT
+TALLY-ELEMENT     = MEMBERS-SIZE OPTIONS-SIZE *MEMBER-ELEMENT *OPTION-ELEMENT
+MEMBERS-SIZE      = SIZE-ELEMENT-8BIT
+OPTIONS-SIZE      = SIZE-ELEMENT-8BIT
+MEMBER-ELEMENT    = *SHARE-ELEMENT ; size is equal to the OPTIONS-SIZE value
+SHARE-ELEMENT     = SIZE-ELEMENT-64BIT SIZE-ELEMENT-65BIT
+OPTION-ELEMENT    = U64
+
+VOTE-PLAN-ID = 32OCTET
+
 ; ####################
 ; TRANSACTION CONSTRUCTION
 ;
@@ -151,7 +203,7 @@ IOW               = BLOCK-DATE        ; end validity of this IOW
                     *INPUT            ; as many as indicated in the number of inputs
                     *OUTPUT           ; sa many as indicated in the number of outputs
                     *WITNESS          ; as many as indicated in the number of inputs
-INPUT             = INPUT-UTXO / INPUT_ACCOUNT
+INPUT             = INPUT-UTXO / INPUT-ACCOUNT
 INPUT-UTXO        = IDX VALUE FRAGMENT-ID
 INPUT-ACCOUNT     = %xff VALUE UNTAG-ACCOUNT-ID
 IDX               = %x00-fe
@@ -218,3 +270,9 @@ U8                = OCTET   ; unsigned integer 8 bit
 U16               = 2OCTET ; unsigned integer 16 bit (BE)
 U32               = 4OCTET ; unsigned integer 32 bit (BE)
 U64               = 8OCTET ; unsigned integer 64 bit (BE)
+SIZE-BYTES-32BYTE = 32OCTET ; unsigned integer 256 bit (32 bytes) (BE)
+SIZE-BYTES-64BYTE = 64OCTET ; unsigned integer 512 bit (64 bytes) (BE)
+SIZE-BYTES-65BYTE = 65OCTET ; unsigned integer 520 bit (65 bytes) (BE)
+SCALAR            = SIZE-BYTES-32BYTE
+GROUP-ELEMENT     = SIZE-BYTES-32BYTE ; ristretto255 backend (build with the feature=ristretto255, it is enabled by default)
+                  / SIZE-BYTES-65BYTE ; p256k1 backend (build with the feature=p256k1)

src/chain-libs/chain-impl-mockchain/doc/format.md

@@ -304,6 +304,69 @@ message, `VoterId` is an ed25519 extended public key, and `Signature`
 is a signature by the corresponding secret key over `ProposalId |
 VoterId`.
 
+## Type 11: Vote Cast
+
+VoteCast message is used to vote for a particular voting event.
+
+VoteCast transaction should have only 1 input, 0 output and 1 witness (signature).
+
+Full fragment representation in hex:
+```
+0000037e000b36ad42885189a0ac3438cdb57bc8ac7f6542e05a59d1f2e4d1d38194c9d4ac7b000203f6639bdbc9235103825a9f025eae5cff3bd9c9dcc0f5a4b286909744746c8b6fb0018773d3b4308344d2e90599cd03749658561787eab714b542a5ccaf078846f6639bdbc9235103825a9f025eae5cff3bd9c9dcc0f5a4b286909744746c8b6fc8f58976fc0e951ba284a24f3fc190d914ae53aebcc523e7a4a330c8655b4908f6639bdbc9235103825a9f025eae5cff3bd9c9dcc0f5a4b286909744746c8b6fb0018773d3b4308344d2e90599cd03749658561787eab714b542a5ccaf078846021c76d0a50054ef7205cb95c1fd3f928f224fab8a8d70feaf4f5db90630c3845a06df2f11c881e396318bd8f9e9f135c2477e923c3decfd6be5466d6166fb3c702edd0d1d0a201fb8c51a91d01328da257971ca78cc566d4b518cb2cd261f96644067a7359a745fe239db8e73059883aece4d506be71c1262b137e295ce5f8a0aac22c1d8d343e5c8b5be652573b85cba8f4dcb46cfa4aafd8d59974e2eb65f480cf85ab522e23203c4f2faa9f95ebc0cd75b04f04fef5d4001d349d1307bb5570af4a91d8af4a489297a3f5255c1e12948787271275c50386ab2ef3980d882228e5f3c82d386e6a4ccf7663df5f6bbd9cbbadd6b2fea2668a8bf5603be29546152902a35fc44aae80d9dcd85fad6cde5b47a6bdc6257c5937f8de877d5ca0356ee9f12a061e03b99ab9dfea56295485cb5ce38cd37f56c396949f58b0627f455d26e4c5ff0bc61ab0ff05ffa07880d0e5c540bc45b527e8e85bb1da469935e0d3ada75d7d41d785d67d1d0732d7d6cbb12b23bfc21dfb4bbe3d933eaa1e5190a85d6e028706ab18d262375dd22a7c1a0e7efa11851ea29b4c92739aaabfee40353453ece16bda2f4a2c2f86e6b37f6de92dc45dba2eb811413c4af2c89f5fc0859718d7cd9888cd8d813da2e93726484ea5ce5be8ecf1e1490b874bd897ccd0cbc33db0a1751f813683724b7f5cf750f2497953607d1e82fb5d1429cbfd7a40ccbdba04fb648203c91e0809e497e80e9fad7895b844ba6da6ac690c7ce49c10e00000000000000000100ff00000000000000036d2ac8ddbf6eaac95401f91baca7f068e3c237386d7c9a271f5187ed909155870200000000e6c8aa48925e37fdab75db13aca7c4f39068e12eeb3af8fd1f342005cae5ab9a1ef5344fab2374e9436a67f57041899693d333610dfe785d329988736797950d
+```
+1. Fragment size (u32): `0000037e`
+2. `00`
+3. Fragment id tag (u8): `0b` == `11` (it is equal to VoteCast tag)
+4. Vote plan id (32 byte hash): `36ad42885189a0ac3438cdb57bc8ac7f6542e05a59d1f2e4d1d38194c9d4ac7b`
+5. Proposal index (u8): `00`
+6. Payload type tag (u8): `02`
+7. Encrypted vote: 
+`03|f6639bdbc9235103825a9f025eae5cff3bd9c9dcc0f5a4b286909744746c8b6f|b0018773d3b4308344d2e90599cd03749658561787eab714b542a5ccaf078846|f6639bdbc9235103825a9f025eae5cff3bd9c9dcc0f5a4b286909744746c8b6f|c8f58976fc0e951ba284a24f3fc190d914ae53aebcc523e7a4a330c8655b4908|f6639bdbc9235103825a9f025eae5cff3bd9c9dcc0f5a4b286909744746c8b6f|b0018773d3b4308344d2e90599cd03749658561787eab714b542a5ccaf078846`
+    - size (u8): `03` 
+    - ciphertext (group element (32 byte), group element (32 byte)): `f6639bdbc9235103825a9f025eae5cff3bd9c9dcc0f5a4b286909744746c8b6f|b0018773d3b4308344d2e90599cd03749658561787eab714b542a5ccaf078846|f6639bdbc9235103825a9f025eae5cff3bd9c9dcc0f5a4b286909744746c8b6f|c8f58976fc0e951ba284a24f3fc190d914ae53aebcc523e7a4a330c8655b4908|f6639bdbc9235103825a9f025eae5cff3bd9c9dcc0f5a4b286909744746c8b6f|b0018773d3b4308344d2e90599cd03749658561787eab714b542a5ccaf078846`
+8. Proof: `02|1c76d0a50054ef7205cb95c1fd3f928f224fab8a8d70feaf4f5db90630c3845a|06df2f11c881e396318bd8f9e9f135c2477e923c3decfd6be5466d6166fb3c70|2edd0d1d0a201fb8c51a91d01328da257971ca78cc566d4b518cb2cd261f9664|4067a7359a745fe239db8e73059883aece4d506be71c1262b137e295ce5f8a0a|ac22c1d8d343e5c8b5be652573b85cba8f4dcb46cfa4aafd8d59974e2eb65f48|0cf85ab522e23203c4f2faa9f95ebc0cd75b04f04fef5d4001d349d1307bb557|0af4a91d8af4a489297a3f5255c1e12948787271275c50386ab2ef3980d88222|8e5f3c82d386e6a4ccf7663df5f6bbd9cbbadd6b2fea2668a8bf5603be295461|52902a35fc44aae80d9dcd85fad6cde5b47a6bdc6257c5937f8de877d5ca0356|ee9f12a061e03b99ab9dfea56295485cb5ce38cd37f56c396949f58b0627f455|d26e4c5ff0bc61ab0ff05ffa07880d0e5c540bc45b527e8e85bb1da469935e0d|3ada75d7d41d785d67d1d0732d7d6cbb12b23bfc21dfb4bbe3d933eaa1e5190a|85d6e028706ab18d262375dd22a7c1a0e7efa11851ea29b4c92739aaabfee403|53453ece16bda2f4a2c2f86e6b37f6de92dc45dba2eb811413c4af2c89f5fc08|59718d7cd9888cd8d813da2e93726484ea5ce5be8ecf1e1490b874bd897ccd0c|bc33db0a1751f813683724b7f5cf750f2497953607d1e82fb5d1429cbfd7a40c|cbdba04fb648203c91e0809e497e80e9fad7895b844ba6da6ac690c7ce49c10e`
+    - size (u8): `02`
+    - announcements (group element (32 byte), group element (32 byte), group element (32 byte)): `1c76d0a50054ef7205cb95c1fd3f928f224fab8a8d70feaf4f5db90630c3845a|06df2f11c881e396318bd8f9e9f135c2477e923c3decfd6be5466d6166fb3c70|2edd0d1d0a201fb8c51a91d01328da257971ca78cc566d4b518cb2cd261f9664|4067a7359a745fe239db8e73059883aece4d506be71c1262b137e295ce5f8a0a|ac22c1d8d343e5c8b5be652573b85cba8f4dcb46cfa4aafd8d59974e2eb65f48|0cf85ab522e23203c4f2faa9f95ebc0cd75b04f04fef5d4001d349d1307bb557`
+    - ciphertext (group element (32 byte), group element (32 byte)): `0af4a91d8af4a489297a3f5255c1e12948787271275c50386ab2ef3980d88222|8e5f3c82d386e6a4ccf7663df5f6bbd9cbbadd6b2fea2668a8bf5603be295461|52902a35fc44aae80d9dcd85fad6cde5b47a6bdc6257c5937f8de877d5ca0356|ee9f12a061e03b99ab9dfea56295485cb5ce38cd37f56c396949f58b0627f455`
+    - response randomness (scalar (32 byte), scalar (32 byte), scalar (32 byte)): `d26e4c5ff0bc61ab0ff05ffa07880d0e5c540bc45b527e8e85bb1da469935e0d|3ada75d7d41d785d67d1d0732d7d6cbb12b23bfc21dfb4bbe3d933eaa1e5190a|85d6e028706ab18d262375dd22a7c1a0e7efa11851ea29b4c92739aaabfee403|53453ece16bda2f4a2c2f86e6b37f6de92dc45dba2eb811413c4af2c89f5fc08|59718d7cd9888cd8d813da2e93726484ea5ce5be8ecf1e1490b874bd897ccd0c|bc33db0a1751f813683724b7f5cf750f2497953607d1e82fb5d1429cbfd7a40c`
+    - scalar (32 byte): `cbdba04fb648203c91e0809e497e80e9fad7895b844ba6da6ac690c7ce49c10e`
+9. IOW stand for Inputs-Outputs-Witnesses: `00000000000000000100ff00000000000000036d2ac8ddbf6eaac95401f91baca7f068e3c237386d7c9a271f5187ed909155870200000000e6c8aa48925e37fdab75db13aca7c4f39068e12eeb3af8fd1f342005cae5ab9a1ef5344fab2374e9436a67f57041899693d333610dfe785d329988736797950d`
+    - block date (epoch (u32), slot (u32)): `00000000|00000000`
+    - number of inputs and witnesses (u8): `01`
+    - number of outputs (u8): `00`
+    - Inputs
+    1. 
+        - index or accout (u8): `ff` (index)
+        - value (u64): `0000000000000003`
+        - input pointer (32 byte): `6d2ac8ddbf6eaac95401f91baca7f068e3c237386d7c9a271f5187ed90915587`
+    - Witnesses
+    1. 
+        - witness type tag (u8): `02`
+        - nonce (u32): `00000000`
+        - legacy signature (64 byte): `e6c8aa48925e37fdab75db13aca7c4f39068e12eeb3af8fd1f342005cae5ab9a1ef5344fab2374e9436a67f57041899693d333610dfe785d329988736797950d`
+
+Signing valid VoteCast fragment example (witness generation).
+
+
+Transaction data to sign:
+```
+36ad42885189a0ac3438cdb57bc8ac7f6542e05a59d1f2e4d1d38194c9d4ac7b000203f6639bdbc9235103825a9f025eae5cff3bd9c9dcc0f5a4b286909744746c8b6fb0018773d3b4308344d2e90599cd03749658561787eab714b542a5ccaf078846f6639bdbc9235103825a9f025eae5cff3bd9c9dcc0f5a4b286909744746c8b6fc8f58976fc0e951ba284a24f3fc190d914ae53aebcc523e7a4a330c8655b4908f6639bdbc9235103825a9f025eae5cff3bd9c9dcc0f5a4b286909744746c8b6fb0018773d3b4308344d2e90599cd03749658561787eab714b542a5ccaf078846021c76d0a50054ef7205cb95c1fd3f928f224fab8a8d70feaf4f5db90630c3845a06df2f11c881e396318bd8f9e9f135c2477e923c3decfd6be5466d6166fb3c702edd0d1d0a201fb8c51a91d01328da257971ca78cc566d4b518cb2cd261f96644067a7359a745fe239db8e73059883aece4d506be71c1262b137e295ce5f8a0aac22c1d8d343e5c8b5be652573b85cba8f4dcb46cfa4aafd8d59974e2eb65f480cf85ab522e23203c4f2faa9f95ebc0cd75b04f04fef5d4001d349d1307bb5570af4a91d8af4a489297a3f5255c1e12948787271275c50386ab2ef3980d882228e5f3c82d386e6a4ccf7663df5f6bbd9cbbadd6b2fea2668a8bf5603be29546152902a35fc44aae80d9dcd85fad6cde5b47a6bdc6257c5937f8de877d5ca0356ee9f12a061e03b99ab9dfea56295485cb5ce38cd37f56c396949f58b0627f455d26e4c5ff0bc61ab0ff05ffa07880d0e5c540bc45b527e8e85bb1da469935e0d3ada75d7d41d785d67d1d0732d7d6cbb12b23bfc21dfb4bbe3d933eaa1e5190a85d6e028706ab18d262375dd22a7c1a0e7efa11851ea29b4c92739aaabfee40353453ece16bda2f4a2c2f86e6b37f6de92dc45dba2eb811413c4af2c89f5fc0859718d7cd9888cd8d813da2e93726484ea5ce5be8ecf1e1490b874bd897ccd0cbc33db0a1751f813683724b7f5cf750f2497953607d1e82fb5d1429cbfd7a40ccbdba04fb648203c91e0809e497e80e9fad7895b844ba6da6ac690c7ce49c10e00000000000000000100ff00000000000000036d2ac8ddbf6eaac95401f91baca7f068e3c237386d7c9a271f5187ed90915587
+```
+It consists of (detailed representation you can see below):
+1. Vote plan id
+2. Proposal index 
+3. Payload type tag
+4. Encrypted vote
+5. Proof
+6. Inputs
+
+`blake2b256` hash of the transaction data to sign equals to `f51473df863be3e0383ce5a8da79c7ff51b3d98dadbbefbf9f042e8601901269`
+
+Expected witness (includes signature)
+```
+0200000000e6c8aa48925e37fdab75db13aca7c4f39068e12eeb3af8fd1f342005cae5ab9a1ef5344fab2374e9436a67f57041899693d333610dfe785d329988736797950d
+```
+
 ## Shared formats
 
 Delegation Type has 3 different encodings:

src/chain-libs/chain-impl-mockchain/src/fragment/mod.rs

@@ -209,7 +209,7 @@ impl Serialize for Fragment {
                 Fragment::UpdateProposal(proposal) => proposal.serialized_size(),
                 Fragment::UpdateVote(vote) => vote.serialized_size(),
                 Fragment::VotePlan(vote_plan) => vote_plan.serialized_size(),
-                Fragment::VoteCast(vote_plan) => vote_plan.serialized_size(),
+                Fragment::VoteCast(vote_cast) => vote_cast.serialized_size(),
                 Fragment::VoteTally(vote_tally) => vote_tally.serialized_size(),
                 Fragment::MintToken(mint_token) => mint_token.serialized_size(),
                 Fragment::Evm(deployment) => deployment.serialized_size(),