From 3b7230519116bdbf29eb0c85a8c68c3b6dd8eec0 Mon Sep 17 00:00:00 2001 From: Kyle Den Hartog Date: Mon, 27 Nov 2023 12:28:19 +1300 Subject: [PATCH] update links to orchard design documents It wasn't clear where within the protocol specification each of these specific implementation details were defined and stated. However, the orchard design docs had some great detail as to the purpose of this, so this was where I decided to link to. In cases where it was referencing Action commitments the protocol spec seemed like the best place to link to instead. --- src/circuit/commit_ivk.rs | 20 +++++++++---------- src/circuit/note_commit.rs | 40 ++++++++++++++++++-------------------- 2 files changed, 29 insertions(+), 31 deletions(-) diff --git a/src/circuit/commit_ivk.rs b/src/circuit/commit_ivk.rs index fb0dd62b..0fb03a40 100644 --- a/src/circuit/commit_ivk.rs +++ b/src/circuit/commit_ivk.rs @@ -53,8 +53,8 @@ impl CommitIvkChip { // - c: 240 bits, // - d: 10 bits // - // https://p.z.cash/orchard-0.1:commit-ivk-decompositions - // https://p.z.cash/orchard-0.1:commit-ivk-region-layout?partial + // https://zcash.github.io/orchard/design/circuit/commit-ivk.html#decomposition-constraints + // https://zcash.github.io/orchard/design/circuit/commit-ivk.html#region-layout /* The pieces are laid out in this configuration: @@ -110,7 +110,7 @@ impl CommitIvkChip { let d_decomposition_check = d_whole - (d_0.clone() + d_1.clone() * two_pow_9); // Check `b_1` and `d_1` are each a single-bit value. - // https://p.z.cash/orchard-0.1:commit-ivk-bit-lengths?partial + // https://zcash.github.io/orchard/design/circuit/commit-ivk.html#bit-length-constraints let b1_bool_check = bool_check(b_1.clone()); let d1_bool_check = bool_check(d_1.clone()); @@ -129,7 +129,7 @@ impl CommitIvkChip { // ak = a (250 bits) || b_0 (4 bits) || b_1 (1 bit) // The `ak` canonicity checks are enforced if and only if `b_1` = 1. - // https://p.z.cash/orchard-0.1:commit-ivk-canonicity-ak?partial + // https://zcash.github.io/orchard/design/circuit/commit-ivk.html#canonicity-checks let ak_canonicity_checks = { // b_1 = 1 => b_0 = 0 let b0_canon_check = b_1.clone() * b_0; @@ -167,7 +167,7 @@ impl CommitIvkChip { // nk = b_2 (5 bits) || c (240 bits) || d_0 (9 bits) || d_1 (1 bit) // The `nk` canonicity checks are enforced if and only if `d_1` = 1. - // https://p.z.cash/orchard-0.1:commit-ivk-canonicity-nk?partial + // https://zcash.github.io/orchard/design/circuit/commit-ivk.html#canonicity-checks let nk_canonicity_checks = { // d_1 = 1 => d_0 = 0 let c0_canon_check = d_1.clone() * d_0; @@ -263,7 +263,7 @@ pub(in crate::circuit) mod gadgets { // We start by witnessing all of the individual pieces, and range-constraining // the short pieces b_0, b_2, and d_0. // - // https://p.z.cash/orchard-0.1:commit-ivk-bit-lengths?partial + // https://zcash.github.io/orchard/design/circuit/commit-ivk.html // `a` = bits 0..=249 of `ak` let a = MessagePiece::from_subpieces( @@ -335,7 +335,7 @@ pub(in crate::circuit) mod gadgets { // addition constraints allows ⊥ to occur, and then during synthesis it detects // these edge cases and raises an error (aborting proof creation). // - // https://p.z.cash/ZKS:action-addr-integrity?partial + // https://zips.z.cash/protocol/nu5.pdf#concretesinsemillacommit let (ivk, zs) = { let message = Message::from_pieces( sinsemilla_chip.clone(), @@ -395,7 +395,7 @@ pub(in crate::circuit) mod gadgets { /// Witnesses and decomposes the `a'` value we need to check the canonicity of `ak`. /// - /// [Specification](https://p.z.cash/orchard-0.1:commit-ivk-canonicity-ak?partial). + /// [Specification](https://zcash.github.io/orchard/design/circuit/commit-ivk.html#canonicity-checks). #[allow(clippy::type_complexity)] fn ak_canonicity( lookup_config: &LookupRangeCheckConfig, @@ -436,7 +436,7 @@ pub(in crate::circuit) mod gadgets { /// Witnesses and decomposes the `b2c'` value we need to check the canonicity of `nk`. /// - /// [Specification](https://p.z.cash/orchard-0.1:commit-ivk-canonicity-nk?partial). + /// [Specification](https://zcash.github.io/orchard/design/circuit/commit-ivk.html#canonicity-checks). #[allow(clippy::type_complexity)] fn nk_canonicity( lookup_config: &LookupRangeCheckConfig, @@ -483,7 +483,7 @@ pub(in crate::circuit) mod gadgets { impl CommitIvkConfig { /// Assign cells for the [canonicity gate]. /// - /// [canonicity gate]: https://p.z.cash/orchard-0.1:commit-ivk-region-layout?partial + /// [canonicity gate]: https://zcash.github.io/orchard/design/circuit/commit-ivk.html#region-layout /* The pieces are laid out in this configuration: diff --git a/src/circuit/note_commit.rs b/src/circuit/note_commit.rs index 9daa685f..f929271b 100644 --- a/src/circuit/note_commit.rs +++ b/src/circuit/note_commit.rs @@ -61,7 +61,7 @@ type CanonicityBounds = ( /// | b | b_0 | b_1 | 1 | /// | | b_2 | b_3 | 0 | /// -/// +/// #[derive(Clone, Debug)] struct DecomposeB { q_notecommit_b: Selector, @@ -206,7 +206,7 @@ impl DecomposeB { /// | d | d_0 | d_1 | 1 | /// | | d_2 | d_3 | 0 | /// -/// +/// #[derive(Clone, Debug)] struct DecomposeD { q_notecommit_d: Selector, @@ -342,7 +342,7 @@ impl DecomposeD { /// ------------------------------------ /// | e | e_0 | e_1 | 1 | /// -/// +/// #[derive(Clone, Debug)] struct DecomposeE { q_notecommit_e: Selector, @@ -461,7 +461,7 @@ impl DecomposeE { /// | g | g_0 | 1 | /// | g_1 | g_2 | 0 | /// -/// +/// #[derive(Clone, Debug)] struct DecomposeG { q_notecommit_g: Selector, @@ -583,7 +583,7 @@ impl DecomposeG { /// ------------------------------------ /// | h | h_0 | h_1 | 1 | /// -/// +/// #[derive(Clone, Debug)] struct DecomposeH { q_notecommit_h: Selector, @@ -700,7 +700,7 @@ impl DecomposeH { /// | x(g_d) | b_0 | a | z13_a | 1 | /// | | b_1 | a_prime | z13_a_prime | 0 | /// -/// +/// #[derive(Clone, Debug)] struct GdCanonicity { q_notecommit_g_d: Selector, @@ -817,7 +817,7 @@ impl GdCanonicity { /// | x(pk_d) | b_3 | c | z13_c | 1 | /// | | d_0 | b3_c_prime | z14_b3_c_prime | 0 | /// -/// +/// #[derive(Clone, Debug)] struct PkdCanonicity { q_notecommit_pk_d: Selector, @@ -933,7 +933,7 @@ impl PkdCanonicity { /// ------------------------------------------------ /// | value | d_2 | d_3 | e_0 | 1 | /// -/// +/// #[derive(Clone, Debug)] struct ValueCanonicity { q_notecommit_value: Selector, @@ -1011,7 +1011,7 @@ impl ValueCanonicity { /// | rho | e_1 | f | z13_f | 1 | /// | | g_0 | e1_f_prime | z14_e1_f_prime | 0 | /// -/// +/// #[derive(Clone, Debug)] struct RhoCanonicity { q_notecommit_rho: Selector, @@ -1126,7 +1126,7 @@ impl RhoCanonicity { /// | psi | g_1 | g_2 | z13_g | 1 | /// | h_0 | h_1 | g1_g2_prime | z13_g1_g2_prime | 0 | /// -/// +/// #[derive(Clone, Debug)] struct PsiCanonicity { q_notecommit_psi: Selector, @@ -1297,7 +1297,7 @@ impl YCanonicity { let z13_j_prime = meta.query_advice(advices[9], Rotation::next()); // Decomposition checks - // https://p.z.cash/orchard-0.1:note-commit-decomposition-y?partial + // https://zcash.github.io/orchard/design/circuit/note-commit.html#field-element-checks let decomposition_checks = { // Check that k_3 is boolean let k3_check = bool_check(k_3.clone()); @@ -1318,7 +1318,7 @@ impl YCanonicity { }; // Canonicity checks. These are enforced if and only if k_3 = 1. - // https://p.z.cash/orchard-0.1:note-commit-canonicity-y?partial + // https://zcash.github.io/orchard/design/circuit/note-commit.html#field-element-checks let canonicity_checks = { iter::empty() .chain(Some(("k_3 = 1 => k_2 = 0", k_2))) @@ -1651,8 +1651,7 @@ pub(in crate::circuit) mod gadgets { // constraints allows ⊥ to occur, and then during synthesis it detects these edge // cases and raises an error (aborting proof creation). // - // https://p.z.cash/ZKS:action-cm-old-integrity?partial - // https://p.z.cash/ZKS:action-cmx-new-integrity?partial + // https://zips.z.cash/protocol/nu5.pdf#concretesinsemillacommitl let (cm, zs) = { let message = Message::from_pieces( chip.clone(), @@ -1777,8 +1776,8 @@ pub(in crate::circuit) mod gadgets { /// A canonicity check helper used in checking x(g_d), y(g_d), and y(pk_d). /// /// Specifications: - /// - [`g_d` canonicity](https://p.z.cash/orchard-0.1:note-commit-canonicity-g_d?partial) - /// - [`y` canonicity](https://p.z.cash/orchard-0.1:note-commit-canonicity-y?partial) + /// - [`g_d` canonicity](https://zcash.github.io/orchard/design/circuit/note-commit.html#field-element-checks) + /// - [`y` canonicity](https://zcash.github.io/orchard/design/circuit/note-commit.html#field-element-checks) fn canon_bitshift_130( lookup_config: &LookupRangeCheckConfig, mut layouter: impl Layouter, @@ -1812,7 +1811,7 @@ pub(in crate::circuit) mod gadgets { /// Check canonicity of `x(pk_d)` encoding. /// - /// [Specification](https://p.z.cash/orchard-0.1:note-commit-canonicity-pk_d?partial). + /// [Specification](https://zcash.github.io/orchard/design/circuit/note-commit.html#field-element-checks). fn pkd_x_canonicity( lookup_config: &LookupRangeCheckConfig, mut layouter: impl Layouter, @@ -1853,7 +1852,7 @@ pub(in crate::circuit) mod gadgets { /// Check canonicity of `rho` encoding. /// - /// [Specification](https://p.z.cash/orchard-0.1:note-commit-canonicity-rho?partial). + /// [Specification](https://zcash.github.io/orchard/design/circuit/note-commit.html#field-element-checks). fn rho_canonicity( lookup_config: &LookupRangeCheckConfig, mut layouter: impl Layouter, @@ -1894,7 +1893,7 @@ pub(in crate::circuit) mod gadgets { /// Check canonicity of `psi` encoding. /// - /// [Specification](https://p.z.cash/orchard-0.1:note-commit-canonicity-psi?partial). + /// [Specification](https://zcash.github.io/orchard/design/circuit/note-commit.html#field-element-checks). fn psi_canonicity( lookup_config: &LookupRangeCheckConfig, mut layouter: impl Layouter, @@ -1935,8 +1934,7 @@ pub(in crate::circuit) mod gadgets { /// Also, witness the LSB and return the witnessed cell. /// /// Specifications: - /// - [`y` decomposition](https://p.z.cash/orchard-0.1:note-commit-decomposition-y?partial) - /// - [`y` canonicity](https://p.z.cash/orchard-0.1:note-commit-canonicity-y?partial) + /// - [`y` decomposition and `y` canonicity](https://zcash.github.io/orchard/design/circuit/note-commit.html#field-element-checks) fn y_canonicity( lookup_config: &LookupRangeCheckConfig, y_canon: &YCanonicity,