Merge pull request #417 from daira/improve-doc-for-fixed-base-constants

Improve documentation for fixed-base constants

Cargo.toml

@@ -4,7 +4,7 @@ version = "0.7.0"
 authors = [
     "Sean Bowe <sean@electriccoin.co>",
     "Jack Grigg <jack@electriccoin.co>",
-    "Daira Emma Hopwood <daira@jacaranda.org>",
+    "Daira-Emma Hopwood <daira@jacaranda.org>",
     "Ying Tong Lai",
     "Kris Nuttycombe <kris@electriccoin.co>",
 ]

src/constants/fixed_bases/commit_ivk_r.rs

@@ -1,7 +1,7 @@
 use group::ff::PrimeField;
 use pasta_curves::{arithmetic::CurveAffine, pallas};
 
-/// Generator used in SinsemillaCommit randomness for IVK commitment
+/// Generator used in SinsemillaCommit randomness for IVK commitment.
 pub const GENERATOR: ([u8; 32], [u8; 32]) = (
     [
         24, 161, 248, 95, 110, 72, 35, 152, 199, 237, 26, 211, 226, 127, 149, 2, 72, 137, 128, 64,
@@ -13,7 +13,8 @@ pub const GENERATOR: ([u8; 32], [u8; 32]) = (
     ],
 );
 
-/// Full-width z-values for GENERATOR
+/// Full-width z-values for GENERATOR.
+/// These can be reproduced by [`halo2_gadgets::ecc::chip::constants::find_zs_and_us`].
 pub const Z: [u64; super::NUM_WINDOWS] = [
     18172, 17390, 61749, 65182, 33835, 155942, 26189, 52444, 40096, 139582, 99218, 20669, 291337,
     12465, 132211, 75527, 68003, 95835, 237325, 21348, 35494, 215451, 49456, 6332, 99036, 224845,
@@ -24,7 +25,8 @@ pub const Z: [u64; super::NUM_WINDOWS] = [
     7870, 143575, 13058, 27070, 30734, 41157, 2955,
 ];
 
-/// Full-width u-values for GENERATOR
+/// Full-width u-values for GENERATOR.
+/// These can be reproduced by [`halo2_gadgets::ecc::chip::constants::find_zs_and_us`].
 pub const U: [[[u8; 32]; super::H]; super::NUM_WINDOWS] = [
     [
         [

src/constants/fixed_bases/note_commit_r.rs

@@ -1,7 +1,7 @@
 use group::ff::PrimeField;
 use pasta_curves::{arithmetic::CurveAffine, pallas};
 
-/// Generator used in SinsemillaCommit randomness for note commitment
+/// Generator used in SinsemillaCommit randomness for note commitment.
 pub const GENERATOR: ([u8; 32], [u8; 32]) = (
     [
         19, 110, 252, 15, 72, 44, 2, 44, 124, 164, 20, 252, 92, 197, 158, 35, 242, 61, 111, 147,
@@ -13,7 +13,8 @@ pub const GENERATOR: ([u8; 32], [u8; 32]) = (
     ],
 );
 
-/// Full-width z-values for GENERATOR
+/// Full-width z-values for GENERATOR.
+/// These can be reproduced by [`halo2_gadgets::ecc::chip::constants::find_zs_and_us`].
 pub const Z: [u64; super::NUM_WINDOWS] = [
     253356, 149209, 114903, 10575, 6973, 30969, 55415, 206450, 18453, 24528, 13099, 213949, 29959,
     49929, 80867, 17465, 43715, 80241, 55983, 132629, 66101, 24136, 31372, 107975, 161748, 24107,
@@ -24,7 +25,8 @@ pub const Z: [u64; super::NUM_WINDOWS] = [
     41201, 40964, 8563, 36035, 6334, 176,
 ];
 
-/// Full-width u-values for GENERATOR
+/// Full-width u-values for GENERATOR.
+/// These can be reproduced by [`halo2_gadgets::ecc::chip::constants::find_zs_and_us`].
 pub const U: [[[u8; 32]; super::H]; super::NUM_WINDOWS] = [
     [
         [

src/constants/fixed_bases/nullifier_k.rs

@@ -1,6 +1,7 @@
 use group::ff::PrimeField;
 use pasta_curves::{arithmetic::CurveAffine, pallas};
 
+/// Generator used as $\mathcal{K}^{\mathsf{Orchard}}$ in DeriveNullifier.
 pub const GENERATOR: ([u8; 32], [u8; 32]) = (
     [
         117, 202, 71, 228, 167, 106, 111, 211, 155, 219, 181, 204, 146, 177, 126, 94, 207, 201,
@@ -12,7 +13,8 @@ pub const GENERATOR: ([u8; 32], [u8; 32]) = (
     ],
 );
 
-/// Full-width z-values for GENERATOR
+/// Full-width z-values for GENERATOR.
+/// These can be reproduced by [`halo2_gadgets::ecc::chip::constants::find_zs_and_us`].
 pub const Z: [u64; super::NUM_WINDOWS] = [
     34374, 173069, 40776, 220066, 45494, 37762, 5245, 11979, 33386, 238556, 128731, 12128, 89982,
     85351, 9804, 12820, 80455, 100009, 24382, 17854, 26367, 7067, 102106, 64293, 114999, 172304,
@@ -24,6 +26,7 @@ pub const Z: [u64; super::NUM_WINDOWS] = [
 ];
 
 /// Full-width u-values for GENERATOR
+/// These can be reproduced by [`halo2_gadgets::ecc::chip::constants::find_zs_and_us`].
 pub const U: [[[u8; 32]; super::H]; super::NUM_WINDOWS] = [
     [
         [

src/constants/fixed_bases/spend_auth_g.rs

@@ -1,8 +1,7 @@
 use group::ff::PrimeField;
 use pasta_curves::{arithmetic::CurveAffine, pallas};
 
-/// The value commitment is used to check balance between inputs and outputs. The value is
-/// placed over this generator.
+/// Generator used as $\mathcal{G}^{\mathsf{Orchard}}$ in Spend authorization signatures.
 pub const GENERATOR: ([u8; 32], [u8; 32]) = (
     [
         99, 201, 117, 184, 132, 114, 26, 141, 12, 161, 112, 123, 227, 12, 127, 12, 95, 68, 95, 62,
@@ -14,7 +13,8 @@ pub const GENERATOR: ([u8; 32], [u8; 32]) = (
     ],
 );
 
-/// Full-width z-values for GENERATOR
+/// Full-width z-values for GENERATOR.
+/// These can be reproduced by [`halo2_gadgets::ecc::chip::constants::find_zs_and_us`].
 pub const Z: [u64; super::NUM_WINDOWS] = [
     49707, 15701, 45931, 163127, 41654, 212130, 34473, 25205, 4118, 10240, 12264, 22866, 203610,
     18808, 13851, 62448, 62380, 94497, 39496, 73216, 32037, 32774, 61690, 39173, 74580, 84678,
@@ -25,7 +25,8 @@ pub const Z: [u64; super::NUM_WINDOWS] = [
     100797, 80349, 87315, 77372, 96572, 18965,
 ];
 
-/// Full-width u-values for GENERATOR
+/// Full-width u-values for GENERATOR.
+/// These can be reproduced by [`halo2_gadgets::ecc::chip::constants::find_zs_and_us`].
 pub const U: [[[u8; 32]; super::H]; super::NUM_WINDOWS] = [
     [
         [

src/constants/fixed_bases/value_commit_r.rs

@@ -1,8 +1,8 @@
 use group::ff::PrimeField;
 use pasta_curves::{arithmetic::CurveAffine, pallas};
 
-/// The value commitment is used to check balance between inputs and outputs. The value is
-/// placed over this generator.
+/// The value commitment is a homomorphic Pedersen commitment used to check balance between inputs
+/// and outputs. This is its randomness base, $\mathcal{R}^{\mathsf{Orchard}}$.
 pub const GENERATOR: ([u8; 32], [u8; 32]) = (
     [
         145, 90, 60, 136, 104, 198, 195, 14, 47, 128, 144, 238, 69, 215, 110, 64, 72, 32, 141, 234,
@@ -14,7 +14,8 @@ pub const GENERATOR: ([u8; 32], [u8; 32]) = (
     ],
 );
 
-/// Full-width z-values for GENERATOR
+/// Full-width z-values for GENERATOR.
+/// These can be reproduced by [`halo2_gadgets::ecc::chip::constants::find_zs_and_us`].
 pub const Z: [u64; super::NUM_WINDOWS] = [
     181916, 22148, 340526, 80718, 104958, 86894, 43381, 1060, 82130, 4741, 55897, 4304, 114469,
     20503, 25001, 62408, 52978, 35893, 72071, 154369, 67304, 7299, 27960, 42929, 51869, 89967,
@@ -25,7 +26,8 @@ pub const Z: [u64; super::NUM_WINDOWS] = [
     22632, 163228, 12997, 4461, 32320, 13430,
 ];
 
-/// Full-width u-values for GENERATOR
+/// Full-width u-values for GENERATOR.
+/// These can be reproduced by [`halo2_gadgets::ecc::chip::constants::find_zs_and_us`].
 pub const U: [[[u8; 32]; super::H]; super::NUM_WINDOWS] = [
     [
         [

src/constants/fixed_bases/value_commit_v.rs

@@ -1,8 +1,8 @@
 use group::ff::PrimeField;
 use pasta_curves::{arithmetic::CurveAffine, pallas};
 
-/// The value commitment is used to check balance between inputs and outputs. The value is
-/// placed over this generator.
+/// The value commitment is a homomorphic Pedersen commitment used to check balance between inputs
+/// and outputs. This is its value base, $\mathcal{V}^{\mathsf{Orchard}}$.
 pub const GENERATOR: ([u8; 32], [u8; 32]) = (
     [
         103, 67, 249, 58, 110, 189, 167, 42, 140, 124, 90, 43, 127, 163, 4, 254, 50, 178, 155, 79,
@@ -14,13 +14,15 @@ pub const GENERATOR: ([u8; 32], [u8; 32]) = (
     ],
 );
 
-/// Short signed z-values for GENERATOR
+/// Short signed z-values for GENERATOR.
+/// These can be reproduced by [`halo2_gadgets::ecc::chip::constants::find_zs_and_us`].
 pub const Z_SHORT: [u64; super::NUM_WINDOWS_SHORT] = [
     163547, 76040, 88852, 128479, 54088, 89871, 39598, 144309, 43471, 102492, 741, 55288, 33756,
     77312, 12095, 48253, 45718, 202901, 33132, 71081, 152108, 169712,
 ];
 
-/// Short signed u-values for GENERATOR
+/// Short signed u-values for GENERATOR.
+/// These can be reproduced by [`halo2_gadgets::ecc::chip::constants::find_zs_and_us`].
 pub const U_SHORT: [[[u8; 32]; super::H]; super::NUM_WINDOWS_SHORT] = [
     [
         [