Skip to content

Commit 5acc2b7

Browse files
Mr-LeshiyMr-Leshiy
authored
docs(docs): Catalyst transaction v2 (#70)
* refactor docs * split into different docs * rename file * add cddl specs * wip * wip * wip * wip * wip * update vote_tx_v2 * update * wip * fix md and spelling * fix comments
1 parent c150746 commit 5acc2b7

File tree

9 files changed

+236
-94
lines changed

9 files changed

+236
-94
lines changed

‎docs/src/architecture/08_concepts/catalyst_voting/.pages‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,6 @@
11
title: Catalyst Voting
22
arrange:
33
- crypto.md
4-
- transaction.md
4+
- gen_vote_tx.md
5+
- jorm.md
6+
- cat_v2.md

‎docs/src/architecture/08_concepts/catalyst_voting/tx_v1.abnf‎ renamed to ‎docs/src/architecture/08_concepts/catalyst_voting/abnf/jorm.abnf‎

File renamed without changes.

‎docs/src/architecture/08_concepts/catalyst_voting/cat_v2.md‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
# Catalyst V2
2+
3+
---
4+
5+
Title: Catalyst V2 Voting Transaction
6+
7+
Status: Proposed
8+
9+
Authors:
10+
- Alex Pozhylenkov <[email protected]>
11+
12+
Created: 2024-10-24
13+
14+
---
15+
16+
## Abstract
17+
18+
This document describes a Catalyst V2 vote transaction structure.
19+
20+
## Motivation
21+
22+
## Specification
23+
24+
It is a Catalyst v2 voting transaction
25+
defined on top the ["Generalized Vote Transaction"](./gen_vote_tx.md#specification) structure.
26+
27+
Following that spec need to define a format of `choice`, `proof` and `prop_id`.
28+
29+
<!-- markdownlint-disable max-one-sentence-per-line -->
30+
!!! note
31+
32+
- If `choice` is *public* one, `proof` **must** be `null`.
33+
- If `choice` is *private* one, `proof` **must** be **not** `null`.
34+
<!-- markdownlint-disable max-one-sentence-per-line -->
35+
36+
<!-- markdownlint-disable max-one-sentence-per-line code-block-style -->
37+
??? note "vote transaction v2 definition: `vote_tx_v2.cddl`"
38+
39+
```CDDL
40+
{{ include_file('src/architecture/08_concepts/catalyst_voting/cddl/vote_tx_v2.cddl', indent=4) }}
41+
```
42+
<!-- markdownlint-enable max-one-sentence-per-line code-block-style -->
43+
44+
### Vote generation
45+
46+
To generate a cryptographically secured `private_choice` and `zk_proof` parts you can follow this [spec](./crypto.md#vote).
47+
Important to note,
48+
that as part of [*initial setup*](./crypto.md#initial-setup) of the voting procedure,
49+
the following properties are used:
50+
51+
1. Each proposal,
52+
defined by the `vote_plan_id` and `proposal_index`, defines a number of possible options.
53+
2. [ristretto255] as a backend cryptographic group.
54+
3. A commitment key $ck$ defined as a [BLAKE2b-512] hash of the `vote_plan_id` bytes.
55+
56+
## Rationale
57+
58+
## Path to Active
59+
60+
### Acceptance Criteria
61+
<!-- Describes what are the acceptance criteria whereby a proposal becomes 'Active' -->
62+
63+
### Implementation Plan
64+
<!-- A plan to meet those criteria or `N/A` if an implementation plan is not applicable. -->
65+
66+
<!-- OPTIONAL SECTIONS: see CIP-0001 > Document > Structure table -->
67+
68+
[BLAKE2b-512]: https://www.blake2.net/blake2.pdf
69+
[ristretto255]: https://ristretto.group
70+
<!-- [COSE]: https://datatracker.ietf.org/doc/rfc9052/ -->
71+
<!-- [CBOR]: https://datatracker.ietf.org/doc/rfc8949/ -->

‎docs/src/architecture/08_concepts/catalyst_voting/cddl/gen_vote_tx.cddl‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
gen-vote-tx = [
2+
tx-body,
3+
signature
4+
]
5+
6+
tx-body = [
7+
vote-type
8+
event,
9+
votes,
10+
voters-data,
11+
]
12+
13+
vote-type = UUID ; e.g. Public or Private vote
14+
event = { * event-key => any }
15+
event-key = int / text
16+
17+
votes = [+ vote]
18+
vote = [
19+
choices,
20+
proof \ null,
21+
prop-id \ null,
22+
]
23+
choices = [+ choice]
24+
choice = encoded-cbor
25+
proof = encoded-cbor
26+
prop-id = encoded-cbor
27+
28+
voters-data = encoded-cbor
29+
30+
UUID = #6.37(bytes) ; UUID type
31+
signature = #6.98(COSE_Sign) ; COSE signature

‎docs/src/architecture/08_concepts/catalyst_voting/tx_v2_cose_payload.cddl‎ renamed to ‎docs/src/architecture/08_concepts/catalyst_voting/cddl/gen_vote_tx_cose_payload.cddl‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,2 @@
1-
cose_payload = blake2b-256
1+
cose-payload = blake2b-256
22
blake2b-256 = #6.32782(bytes .size 32) ; Blake2b-256 hash bytes

‎docs/src/architecture/08_concepts/catalyst_voting/cddl/vote_tx_v2.cddl‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
vote-tx-v2 = gen-vote-tx
2+
3+
choice = #6.24(bstr(choice-data))
4+
proof = #6.24(bstr(proof-data))
5+
prop-id = #6.24(bstr(proposal))
6+
7+
choice-data = public-choice / private-choice
8+
9+
public-choice = uint
10+
private-choice = ciphertext
11+
12+
ciphertext = [group-element, group-element]
13+
group-element = bytes .size 32
14+
15+
proposal = UUID
16+
17+
proof-data = zk-proof
18+
19+
zk-proof = [[+ (announcement, ciphertext, r-response)], scalar]
20+
21+
announcement = (group-element, group-element, group-element)
22+
ciphertext = (group-element, group-element)
23+
r-response = (scalar, scalar, scalar)
24+
25+
scalar = bytes .size 32
26+
group-element = bytes .size 32
27+
28+
;# include gen_vote_tx
29+

‎docs/src/architecture/08_concepts/catalyst_voting/gen_vote_tx.md‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
# General Voting Transaction
2+
3+
---
4+
5+
Title: General Voting Transaction Structure
6+
7+
Status: Proposed
8+
9+
Authors:
10+
- Alex Pozhylenkov <[email protected]>
11+
12+
Created: 2024-09-04
13+
14+
---
15+
16+
## Abstract
17+
18+
This document defines a generalized view of the "Catalyst" voting transaction.
19+
20+
## Motivation
21+
22+
Project "Catalyst" requires a structure to keep people vote's data in the secure way, anonymous and verifiable way.
23+
24+
## Specification
25+
26+
<!-- markdownlint-disable max-one-sentence-per-line code-block-style -->
27+
??? note "vote transaction definition: `gen_vote_tx.cddl`"
28+
29+
```CDDL
30+
{{ include_file('src/architecture/08_concepts/catalyst_voting/cddl/gen_vote_tx.cddl', indent=4) }}
31+
```
32+
<!-- markdownlint-enable max-one-sentence-per-line code-block-style -->
33+
34+
`event` - a set of different identifiers which is uniquely define a particular voting event.
35+
36+
Vote:
37+
38+
* `choices` - a collection of voter choices for the proposal.
39+
* `proof` - a voter proof, could be `null`.
40+
* `prop-id` - a proposal id for which `choice` is made, could be `null`.
41+
For that case where for the `event` defined only **one** proposal,
42+
so it's redundant to provide an additional identifier for the proposal,
43+
so it could be placed `null`.
44+
45+
`voters-data` - an any additional voter's specific data.
46+
47+
### Transaction signing
48+
49+
[COSE] is used to define a transaction's signature structure.
50+
[COSE] is a flexible security protocol that supports various types of security messages.
51+
However, only `COSE Signed Data Object` or `COSE_Sign` type is used.
52+
53+
The following header must be included in the [COSE] signature.
54+
55+
`protected`:
56+
57+
* `content type`: `application/cbor`
58+
(this parameter is used to indicate the content type of the data in the payload or ciphertext fields).
59+
60+
Any other headers as `alg`, `kid` etc. could be specified of any kind and not defined by this spec.
61+
62+
#### Signature payload
63+
64+
As mentioned earlier, the content type of the [COSE] signature payload is `application/cbor`.
65+
In particular it must be a [CBOR] encoded [BLAKE2b-256] hash bytes:
66+
67+
<!-- markdownlint-disable code-block-style -->
68+
```CDDL
69+
{{ include_file('src/architecture/08_concepts/catalyst_voting/cddl/gen_vote_tx_cose_payload.cddl') }}
70+
```
71+
<!-- markdownlint-enable code-block-style -->
72+
73+
## Rationale
74+
75+
## Path to Active
76+
77+
### Acceptance Criteria
78+
<!-- Describes what are the acceptance criteria whereby a proposal becomes 'Active' -->
79+
80+
### Implementation Plan
81+
<!-- A plan to meet those criteria or `N/A` if an implementation plan is not applicable. -->
82+
83+
<!-- OPTIONAL SECTIONS: see CIP-0001 > Document > Structure table -->
84+
85+
[BLAKE2b-256]: https://www.blake2.net/blake2.pdf
86+
[COSE]: https://datatracker.ietf.org/doc/rfc9052/
87+
[CBOR]: https://datatracker.ietf.org/doc/rfc8949/

‎docs/src/architecture/08_concepts/catalyst_voting/transaction.md‎ renamed to ‎docs/src/architecture/08_concepts/catalyst_voting/jorm.md‎

Lines changed: 14 additions & 66 deletions
Original file line numberDiff line numberDiff line change
@@ -1,40 +1,37 @@
1-
# Transactions
1+
# Jörmungandr
22

33
---
44

5-
Title: Voting Transactions
5+
Title: Jörmungandr Voting Transaction
66

77
Status: Proposed
88

99
Authors:
1010
- Alex Pozhylenkov <[email protected]>
1111

12-
Created: 2024-09-04
12+
Created: 2024-10-24
1313

1414
---
1515

1616
## Abstract
1717

18-
This document describes a specification of the different versions "Catalyst" voting transaction structure.
19-
From the old one (Jörmungandr) to the newest.
18+
This document describes a definition of the original Jörmungandr `VoteCast` transaction.
2019

2120
## Motivation
2221

23-
Project "Catalyst" requires a structure to keep people vote's data in the secure way, anonymous and verifiable way.
24-
2522
## Specification
2623

27-
### v1 (Jörmungandr)
24+
An original Jörmungandr blockchain's `VoteCast` transaction structure.
2825

2926
<!-- markdownlint-disable max-one-sentence-per-line code-block-style -->
30-
??? note "V1 vote transaction definition: `tx_v1.abnf`"
27+
??? note "V1 transaction definition: `jorm.abnf`"
3128

3229
```abnf
33-
{{ include_file('src/architecture/08_concepts/catalyst_voting/tx_v1.abnf', indent=4) }}
30+
{{ include_file('src/architecture/08_concepts/catalyst_voting/abnf/jorm.abnf', indent=4) }}
3431
```
3532
<!-- markdownlint-enable max-one-sentence-per-line code-block-style -->
3633

37-
#### Example
34+
### Example
3835

3936
V1 transaction representation in hex:
4037

@@ -78,18 +75,18 @@ V1 transaction representation in hex:
7875
* legacy signature (64 byte): `e6c8aa48925e37fdab75db13aca7c4f39068e12eeb3af8fd1f342005cae5ab9a1ef5344fab2374e9436a67f57041899693d333610dfe785d329988736797950d`
7976
<!-- markdownlint-enable max-one-sentence-per-line code-block-style -->
8077

81-
#### Transaction vote generation
78+
### Vote generation
8279

8380
To generate a cryptographically secured `ENCRYPTED-VOTE` and `PROOF-VOTE` parts you can follow this [spec](./crypto.md#vote).
8481
Important to note,
8582
that as part of [*initial setup*](./crypto.md#initial-setup) of the voting procedure,
8683
the following properties are used:
8784

88-
1. Each proposal, defined by the "Vote plan id" and "Proposal index", defines a number of possible options.
85+
1. Each proposal, defined by the `VOTE-PLAN-ID` and `PROPOSAL-INDEX`, defines a number of possible options.
8986
2. [ristretto255] as a backend cryptographic group.
90-
3. A commitment key $ck$ defined as a [BLAKE2b-512] hash of the "Vote plan id" bytes.
87+
3. A commitment key $ck$ defined as a [BLAKE2b-512] hash of the `VOTE-PLAN-ID` bytes.
9188

92-
#### Transaction signing (witness generation)
89+
### Signing (witness generation)
9390

9491
Signature generated from the [BLAKE2b-256] hashed `VOTE-PAYLOAD` bytes except of the `WITNESS` part
9592
(the last part from the bytes array):
@@ -118,55 +115,6 @@ Expected witness (includes signature)
118115
```
119116
<!-- markdownlint-enable code-block-style -->
120117

121-
### v2
122-
123-
<!-- markdownlint-disable max-one-sentence-per-line code-block-style -->
124-
??? note "V2 vote transaction definition: `tx_v2.cddl`"
125-
126-
```CDDL
127-
{{ include_file('src/architecture/08_concepts/catalyst_voting/tx_v2.cddl', indent=4) }}
128-
```
129-
<!-- markdownlint-enable max-one-sentence-per-line code-block-style -->
130-
131-
`event` - a set of different identifiers which is uniquely define a particular voting event.
132-
133-
Vote:
134-
135-
* `choices` - a collection of voter choices for the proposal.
136-
* `proof` - a voter proof, could be `null`.
137-
* `prop_id` - a proposal id for which `choice` is made, could be `null`.
138-
For that case where for the `event` defined only **one** proposal,
139-
so it's redundant to provide an additional identifier for the proposal,
140-
so it could be placed `null`.
141-
142-
`voters_data` - an any additional voter's specific data.
143-
144-
#### Transaction signing
145-
146-
[COSE] is used to define a transaction's signature structure.
147-
[COSE] is a flexible security protocol that supports various types of security messages.
148-
However, only `COSE Signed Data Object` or `COSE_Sign` type is used.
149-
150-
The following header must be included in the [COSE] signature.
151-
152-
`protected`:
153-
154-
* `content type`: `application/cbor`
155-
(this parameter is used to indicate the content type of the data in the payload or ciphertext fields).
156-
157-
Any other headers as `alg`, `kid` etc. could be specified of any kind and not defined by this spec.
158-
159-
##### Signature payload
160-
161-
As mentioned earlier, the content type of the [COSE] signature payload is `application/cbor`.
162-
In particular it must be a [CBOR] encoded [BLAKE2b-256] hash bytes:
163-
164-
<!-- markdownlint-disable code-block-style -->
165-
```CDDL
166-
{{ include_file('src/architecture/08_concepts/catalyst_voting/tx_v2_cose_payload.cddl') }}
167-
```
168-
<!-- markdownlint-enable code-block-style -->
169-
170118
## Rationale
171119

172120
## Path to Active
@@ -182,5 +130,5 @@ In particular it must be a [CBOR] encoded [BLAKE2b-256] hash bytes:
182130
[BLAKE2b-256]: https://www.blake2.net/blake2.pdf
183131
[BLAKE2b-512]: https://www.blake2.net/blake2.pdf
184132
[ristretto255]: https://ristretto.group
185-
[COSE]: https://datatracker.ietf.org/doc/rfc9052/
186-
[CBOR]: https://datatracker.ietf.org/doc/rfc8949/
133+
<!-- [COSE]: https://datatracker.ietf.org/doc/rfc9052/ -->
134+
<!-- [CBOR]: https://datatracker.ietf.org/doc/rfc8949/ -->

‎docs/src/architecture/08_concepts/catalyst_voting/tx_v2.cddl‎

Lines changed: 0 additions & 26 deletions
This file was deleted.

0 commit comments

Comments
 (0)