Skip to content

Commit 26b2778

Browse files
drskalmandrskalman
committed
- spec structure and definition of VRF.
1 parent e9782f9 commit 26b2778

File tree

7 files changed

+241
-2
lines changed

7 files changed

+241
-2
lines changed

‎Makefile

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
.PHONY: spec-build spec-watch
2+
3+
OUT_MD_FILE := ./spec/specification.md
4+
OUT_HTML_FILE := ./spec/specification.html
5+
OUT_TEX_FILE := ./spec/specification.tex
6+
OUT_PDF_FILE := ./spec/specification.pdf
7+
OUT_SPEC_DIRECTORY := ./spec/
8+
9+
# builds the specification once
10+
spec-build:
11+
cargo spec build --output-file $(OUT_MD_FILE)
12+
pandoc $(OUT_MD_FILE) --to=latex --standalone --output $(OUT_TEX_FILE)
13+
pandoc $(OUT_TEX_FILE) --to=pdf --standalone --output $(OUT_PDF_FILE)
14+
# this gives lots of error and does not compile corretly
15+
# pdftex -shell-escape -output-directory $(OUT_SPEC_DIRECTORY) \\nonstopmode\\input specification.tex
16+
17+
# watches specification-related files and rebuilds them on the fly
18+
spec-watch:
19+
cargo spec watch --output-file $(OUT_MD_FILE)
20+
21+
spec-build-html:
22+
cargo spec build --output-format respec --output-file $(OUT_HTML_FILE)

‎README.md

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,29 @@
11
# ring-vrf
22

33
Ring VRF implementation using zkSNARKs.
4+
5+
## Building the Specification document
6+
7+
The specification is built by means of [Cargo spec](https://crates.io/crates/cargo-spec) crate. To build the specification document, one can simply invoke:
8+
```
9+
$ cargo spec build
10+
```
11+
[`specification.md`](./specification.md) then shall contain the newly built specification. The specification could be easily converted to HTML by the help of `pandoc` if desired:
12+
```
13+
$ pandoc -f commonmark specification.md --standalone --output specification.html
14+
```
15+
The specification contais mathematical formula which needs to be converted to LaTeX format in order to be displayed as intended using:
16+
```
17+
$ pandoc -f commonmark specification.md --to=latex --standalone --output specification.tex
18+
```
19+
Alternatively you could simply run:
20+
```
21+
$ make spec-build
22+
```
23+
and get the specification in `./spec/specification.pdf`
24+
25+
Or run:
26+
```
27+
$ make spec-build-html
28+
```
29+
and get the specification in `./spec/specification.html`

‎Specification.toml

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
[metadata]
2+
name = "Ring VRF"
3+
description = "Ring VRF implementation using zkSNARKs."
4+
authors = ["Alistair, Jeff, Syed, Sergey"]
5+
6+
[config]
7+
template = "specification_template.md"
8+
9+
[sections]
10+
# DLEQ VRF
11+
dleq-vrf-preliminaries = "dleq_vrf/src/lib.rs"
12+
## VRF
13+
vrf = "dleq_vrf/src/vrf.rs"
14+
### VRF Keys
15+
vrf-keys = "dleq_vrf/src/keys.rs"
16+
17+
## Thin VRF
18+
19+
## Pedersen VRF
20+
21+
# Bandersnatch VRF

‎dleq_vrf/src/keys.rs

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,9 @@ use crate::{
2424
};
2525

2626

27-
/// Public key
27+
//~ #### Public key \
28+
//~ \
29+
//~ A Public key of a VRF is a point on an Elliptic Curve $E$. \
2830
#[derive(Debug,Clone,Eq,Hash,CanonicalSerialize,CanonicalDeserialize)] // Copy, PartialOrd, Ord, Hash,
2931
#[repr(transparent)]
3032
pub struct PublicKey<C: AffineRepr>(pub C);
@@ -35,6 +37,9 @@ impl<C: AffineRepr> PartialEq for PublicKey<C> {
3537
}
3638
}
3739

40+
//~ Public key is represented in Affine form and is serialized using Arkwork compressed serialized
41+
//~ format.
42+
//
3843
/// Arkworks' own serialization traits should be preferred over these.
3944
impl<C: AffineRepr> PublicKey<C> {
4045
pub fn update_digest(&self, h: &mut impl Update) {

‎dleq_vrf/src/vrf.rs

Lines changed: 22 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,20 @@
33
// Authors:
44
// - Jeffrey Burdges <jeff@web3.foundation>
55

6+
//~ ## VRF
7+
//~
8+
//~ **Definition**: A *verifiable random function with auxiliary data (VRF-AD)* can be described with three functions:
9+
//~
10+
//~ - $VRF.KeyGen: () \mapsto (pk,sk)$ where $pk$ is a public key and $sk$ is its corresponding secret key.
11+
//~ - $VRF.Sign : (sk,msg,aux) \mapsto \sigma$ takes a secret key $sk$, an input $msg$, and auxiliary data $aux$, and then returns a VRF signature $\sigma$.
12+
//~ - $VRF.Eval : (sk, msg) \mapsto Out$ takes a secret key $sk$ and an input $msg$, and then returns a VRF output $Out$.
13+
//~ - $VRF.Verify: (pk,msg,aux,\sigma)\mapsto (Out|prep)$ for a public key pk, an input msg, and auxiliary data aux, and then returns either an output $Out$ or else failure $perp$.
14+
//~
15+
//~ **Definition**: For an elliptic curve $E$ defined over finite field $F$ with large prime subgroup $G$ generated by point $g$, we call a VRF, EC-VRF is VRF-AD where $pk = sk.g$ and $VRF.Sign$ is an elliptic curve signature scheme.
16+
//~
17+
//~ All VRFs described in this specification are EC-VRF.
18+
19+
//! All VRFs expect a point on the curve as their input.
620
//! ### VRF input and output handling
721
//!
822
//! We caution that ring VRFs based upon DLEQ proofs like ours require
@@ -18,6 +32,14 @@ use crate::{Transcript,IntoTranscript,transcript::AsLabel,SecretKey};
1832

1933
use core::borrow::{Borrow}; // BorrowMut
2034

35+
//~ For input $msg$ and $aux$ auxilary date first we compute the $VRFInput$ which is a point on elliptic curve $E$ as follows:
36+
//
37+
//~ $$ VRFiput := H2C(ArkTranscript(msg, aux) $$
38+
//~
39+
//~ where
40+
//~ - $ArkTranscript$ function is described in [[ark-transcript]] section.
41+
//~ - $H2C: B \rightarrow G$ is a hash to curve function correspond to curve $E$ specified in Section [[hash-to-curve]] for the specific choice of $E$
42+
//~
2143
/// Create VRF input points
2244
///
2345
/// You select your own hash-to-curve by implementing this trait
@@ -108,7 +130,6 @@ impl<K: AffineRepr> SecretKey<K> {
108130
}
109131
}
110132

111-
112133
/// VRF pre-output, possibly unverified.
113134
#[derive(Debug,Copy,Clone,PartialEq,Eq,CanonicalSerialize,CanonicalDeserialize)] // Copy, Default, PartialOrd, Ord, Hash
114135
#[repr(transparent)]

‎spec/specification.md

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
# Ring VRF
2+
3+
## VRF
4+
5+
**Definition**: A *verifiable random function with auxiliary data (VRF-AD)* can be described with three functions:
6+
7+
- $VRF.KeyGen: () \mapsto (pk,sk)$ where $pk$ is a public key and $sk$ is its corresponding secret key.
8+
- $VRF.Sign : (sk,msg,aux) \mapsto \sigma$ takes a secret key $sk$, an input $msg$, and auxiliary data $aux$, and then returns a VRF signature $\sigma$.
9+
- $VRF.Eval : (sk, msg) \mapsto Out$ takes a secret key $sk$ and an input $msg$, and then returns a VRF output $Out$.
10+
- $VRF.Verify: (pk,msg,aux,\sigma)\mapsto (Out|prep)$ for a public key pk, an input msg, and auxiliary data aux, and then returns either an output $Out$ or else failure $perp$.
11+
12+
**Definition**: For an elliptic curve $E$ defined over finite field $F$ with large prime subgroup $G$ generated by point $g$, we call a VRF, EC-VRF is VRF-AD where $pk = sk.g$ and $VRF.Sign$ is an elliptic curve signature scheme.
13+
14+
All VRFs described in this specification are EC-VRF.
15+
For input $msg$ and $aux$ auxilary date first we compute the $VRFInput$ which is a point on elliptic curve $E$ as follows:
16+
$$ VRFiput := H2C(ArkTranscript(msg, aux) $$
17+
18+
where
19+
- $ArkTranscript$ function is described in [[ark-transcript]] section.
20+
- $H2C: B \rightarrow G$ is a hash to curve function correspond to curve $E$ specified in Section [[hash-to-curve]] for the specific choice of $E$
21+
22+
23+
24+
25+
### Preliminaries
26+
27+
28+
### VRF Key
29+
#### Public key \
30+
\
31+
A Public key of a VRF is a point on an Elliptic Curve $E$. \
32+
Public key is represented in Affine form and is serialized using Arkwork compressed serialized
33+
format.
34+
35+
36+
### VRF input
37+
38+
VRF input is an ArkTranscript. See ArkTranscript
39+
40+
#### From transcript to point
41+
42+
You need to call challenge and add b"vrf-input" to it. getting random byte (some hash?)
43+
then hash to curve it.
44+
45+
46+
## DELQ VRF
47+
### Preliminaries
48+
Implements the two relevant verifiable random functions (VRFs) with
49+
associated data (VRF-ADs) which arise from Chaum-Pedersen DLEQ proofs,
50+
polymorphic over Arkworks' elliptic curves.
51+
52+
Thin VRF aka `ThinVrf` provides a regular VRF similar but broadly superior
53+
to ["EC VRF"](https://www.ietf.org/id/draft-irtf-cfrg-vrf-15.html).
54+
Thin VRF support batch verification or half-aggregation exactly like
55+
Schnorr signatures, but which ECVRF lacks.
56+
In essence, thin VRF *is* a Schnorr signature with base point given by
57+
a pseudo-random (Fiat-Shamir) linear combination of base points, while
58+
EC VRF is two linked Schnorr signatures on distinct base points.
59+
Thin VRF should be slightly faster than EC VRF, be similarly sized on
60+
typical Edwards curves, but slightly larger on larger BLS12 curves.
61+
As a rule, new applications should always prefer thin VRF over EC VRF.
62+
63+
Pedersen VRF aka `PedersenVRF` resembles EC VRF but replaces the
64+
public key by a Pedersen commitment to the secret key, which makes the
65+
Pedersen VRF useful in anonymized ring VRFs, or perhaps group VRFs.
66+
We provide both batchable and nonbatchable forms of the Pedresen VRF.
67+
We favor the batchable form because our blinding factors enlarge our
68+
signatures anyways, making the batchable form less significant
69+
proportionally than batchable forms of EV VRF.
70+
71+
As the Pedersen VRF needs two verification equations, we support
72+
DLEQ proofs between two distinct curves provided both have the same
73+
subgroup order. Around this, we support omitting the blinding factors
74+
for cross curve DLEQ proofs, like proving public keys on G1 and G2
75+
of a BLS12 curve have the same secret key.
76+
77+
78+
79+
### Thin VRF
80+
81+
### Pedersen VRF
82+
83+
## Bandersnatch VRF
84+

‎specification_template.md

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
# Ring VRF
2+
3+
{sections.vrf}
4+
5+
6+
### Preliminaries
7+
8+
9+
### VRF Key
10+
{sections.vrf-keys}
11+
12+
### VRF input
13+
14+
VRF input is an ArkTranscript. See ArkTranscript
15+
16+
#### From transcript to point
17+
18+
You need to call challenge and add b"vrf-input" to it. getting random byte (some hash?)
19+
then hash to curve it.
20+
21+
22+
## DELQ VRF
23+
### Preliminaries
24+
Implements the two relevant verifiable random functions (VRFs) with
25+
associated data (VRF-ADs) which arise from Chaum-Pedersen DLEQ proofs,
26+
polymorphic over Arkworks' elliptic curves.
27+
28+
Thin VRF aka `ThinVrf` provides a regular VRF similar but broadly superior
29+
to ["EC VRF"](https://www.ietf.org/id/draft-irtf-cfrg-vrf-15.html).
30+
Thin VRF support batch verification or half-aggregation exactly like
31+
Schnorr signatures, but which ECVRF lacks.
32+
In essence, thin VRF *is* a Schnorr signature with base point given by
33+
a pseudo-random (Fiat-Shamir) linear combination of base points, while
34+
EC VRF is two linked Schnorr signatures on distinct base points.
35+
Thin VRF should be slightly faster than EC VRF, be similarly sized on
36+
typical Edwards curves, but slightly larger on larger BLS12 curves.
37+
As a rule, new applications should always prefer thin VRF over EC VRF.
38+
39+
Pedersen VRF aka `PedersenVRF` resembles EC VRF but replaces the
40+
public key by a Pedersen commitment to the secret key, which makes the
41+
Pedersen VRF useful in anonymized ring VRFs, or perhaps group VRFs.
42+
We provide both batchable and nonbatchable forms of the Pedresen VRF.
43+
We favor the batchable form because our blinding factors enlarge our
44+
signatures anyways, making the batchable form less significant
45+
proportionally than batchable forms of EV VRF.
46+
47+
As the Pedersen VRF needs two verification equations, we support
48+
DLEQ proofs between two distinct curves provided both have the same
49+
subgroup order. Around this, we support omitting the blinding factors
50+
for cross curve DLEQ proofs, like proving public keys on G1 and G2
51+
of a BLS12 curve have the same secret key.
52+
53+
54+
{sections.dleq-vrf-preliminaries}
55+
### Thin VRF
56+
57+
### Pedersen VRF
58+
59+
## Bandersnatch VRF
60+

0 commit comments

Comments
 (0)