zec
/
orchard
mirror of https://github.com/zcash/orchard.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

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.
This commit is contained in:
Kyle Den Hartog 2023-11-27 12:28:19 +13:00
parent 65b78a19d0
commit 3b72305191
No known key found for this signature in database
2 changed files with 29 additions and 31 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

20
src/circuit/commit_ivk.rs
View File

@ -53,8 +53,8 @@ impl CommitIvkChip {
// - c: 240 bits, // - c: 240 bits,
// - d: 10 bits // - d: 10 bits
// //
// https://p.z.cash/orchard-0.1:commit-ivk-decompositions // https://zcash.github.io/orchard/design/circuit/commit-ivk.html#decomposition-constraints
// https://p.z.cash/orchard-0.1:commit-ivk-region-layout?partial // https://zcash.github.io/orchard/design/circuit/commit-ivk.html#region-layout
/* /*
The pieces are laid out in this configuration: 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); 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. // 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 b1_bool_check = bool_check(b_1.clone());
let d1_bool_check = bool_check(d_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) // 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. // 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 = { let ak_canonicity_checks = {
// b_1 = 1 => b_0 = 0 // b_1 = 1 => b_0 = 0
let b0_canon_check = b_1.clone() * b_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) // 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. // 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 = { let nk_canonicity_checks = {
// d_1 = 1 => d_0 = 0 // d_1 = 1 => d_0 = 0
let c0_canon_check = d_1.clone() * d_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 // We start by witnessing all of the individual pieces, and range-constraining
// the short pieces b_0, b_2, and d_0. // 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` // `a` = bits 0..=249 of `ak`
let a = MessagePiece::from_subpieces( 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 // addition constraints allows ⊥ to occur, and then during synthesis it detects
// these edge cases and raises an error (aborting proof creation). // 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 (ivk, zs) = {
let message = Message::from_pieces( let message = Message::from_pieces(
sinsemilla_chip.clone(), 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`. /// 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)] #[allow(clippy::type_complexity)]
fn ak_canonicity( fn ak_canonicity(
lookup_config: &LookupRangeCheckConfig<pallas::Base, 10>, lookup_config: &LookupRangeCheckConfig<pallas::Base, 10>,
@ -436,7 +436,7 @@ pub(in crate::circuit) mod gadgets {
/// Witnesses and decomposes the `b2c'` value we need to check the canonicity of `nk`. /// 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)] #[allow(clippy::type_complexity)]
fn nk_canonicity( fn nk_canonicity(
lookup_config: &LookupRangeCheckConfig<pallas::Base, 10>, lookup_config: &LookupRangeCheckConfig<pallas::Base, 10>,
@ -483,7 +483,7 @@ pub(in crate::circuit) mod gadgets {
impl CommitIvkConfig { impl CommitIvkConfig {
/// Assign cells for the [canonicity gate]. /// 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: The pieces are laid out in this configuration:

40
src/circuit/note_commit.rs
View File

@ -61,7 +61,7 @@ type CanonicityBounds = (
/// | b | b_0 | b_1 | 1 | /// | b | b_0 | b_1 | 1 |
/// | | b_2 | b_3 | 0 | /// | | b_2 | b_3 | 0 |
/// ///
/// <https://p.z.cash/orchard-0.1:note-commit-decomposition-b?partial> /// <https://zcash.github.io/orchard/design/circuit/note-commit.html#message-piece-decomposition>
#[derive(Clone, Debug)] #[derive(Clone, Debug)]
struct DecomposeB { struct DecomposeB {
q_notecommit_b: Selector, q_notecommit_b: Selector,
@ -206,7 +206,7 @@ impl DecomposeB {
/// | d | d_0 | d_1 | 1 | /// | d | d_0 | d_1 | 1 |
/// | | d_2 | d_3 | 0 | /// | | d_2 | d_3 | 0 |
/// ///
/// <https://p.z.cash/orchard-0.1:note-commit-decomposition-d?partial> /// <https://zcash.github.io/orchard/design/circuit/note-commit.html#message-piece-decomposition>
#[derive(Clone, Debug)] #[derive(Clone, Debug)]
struct DecomposeD { struct DecomposeD {
q_notecommit_d: Selector, q_notecommit_d: Selector,
@ -342,7 +342,7 @@ impl DecomposeD {
/// ------------------------------------ /// ------------------------------------
/// | e | e_0 | e_1 | 1 | /// | e | e_0 | e_1 | 1 |
/// ///
/// <https://p.z.cash/orchard-0.1:note-commit-decomposition-e?partial> /// <https://zcash.github.io/orchard/design/circuit/note-commit.html#message-piece-decomposition>
#[derive(Clone, Debug)] #[derive(Clone, Debug)]
struct DecomposeE { struct DecomposeE {
q_notecommit_e: Selector, q_notecommit_e: Selector,
@ -461,7 +461,7 @@ impl DecomposeE {
/// | g | g_0 | 1 | /// | g | g_0 | 1 |
/// | g_1 | g_2 | 0 | /// | g_1 | g_2 | 0 |
/// ///
/// <https://p.z.cash/orchard-0.1:note-commit-decomposition-g?partial> /// <https://zcash.github.io/orchard/design/circuit/note-commit.html#message-piece-decomposition>
#[derive(Clone, Debug)] #[derive(Clone, Debug)]
struct DecomposeG { struct DecomposeG {
q_notecommit_g: Selector, q_notecommit_g: Selector,
@ -583,7 +583,7 @@ impl DecomposeG {
/// ------------------------------------ /// ------------------------------------
/// | h | h_0 | h_1 | 1 | /// | h | h_0 | h_1 | 1 |
/// ///
/// <https://p.z.cash/orchard-0.1:note-commit-decomposition-h?partial> /// <https://zcash.github.io/orchard/design/circuit/note-commit.html#message-piece-decomposition>
#[derive(Clone, Debug)] #[derive(Clone, Debug)]
struct DecomposeH { struct DecomposeH {
q_notecommit_h: Selector, q_notecommit_h: Selector,
@ -700,7 +700,7 @@ impl DecomposeH {
/// | x(g_d) | b_0 | a | z13_a | 1 | /// | x(g_d) | b_0 | a | z13_a | 1 |
/// | | b_1 | a_prime | z13_a_prime | 0 | /// | | b_1 | a_prime | z13_a_prime | 0 |
/// ///
/// <https://p.z.cash/orchard-0.1:note-commit-canonicity-g_d?partial> /// <https://zcash.github.io/orchard/design/circuit/note-commit.html#field-element-checks>
#[derive(Clone, Debug)] #[derive(Clone, Debug)]
struct GdCanonicity { struct GdCanonicity {
q_notecommit_g_d: Selector, q_notecommit_g_d: Selector,
@ -817,7 +817,7 @@ impl GdCanonicity {
/// | x(pk_d) | b_3 | c | z13_c | 1 | /// | x(pk_d) | b_3 | c | z13_c | 1 |
/// | | d_0 | b3_c_prime | z14_b3_c_prime | 0 | /// | | d_0 | b3_c_prime | z14_b3_c_prime | 0 |
/// ///
/// <https://p.z.cash/orchard-0.1:note-commit-canonicity-pk_d?partial> /// <https://zcash.github.io/orchard/design/circuit/note-commit.html#field-element-checks>
#[derive(Clone, Debug)] #[derive(Clone, Debug)]
struct PkdCanonicity { struct PkdCanonicity {
q_notecommit_pk_d: Selector, q_notecommit_pk_d: Selector,
@ -933,7 +933,7 @@ impl PkdCanonicity {
/// ------------------------------------------------ /// ------------------------------------------------
/// | value | d_2 | d_3 | e_0 | 1 | /// | value | d_2 | d_3 | e_0 | 1 |
/// ///
/// <https://p.z.cash/orchard-0.1:note-commit-canonicity-v?partial> /// <https://zcash.github.io/orchard/design/circuit/note-commit.html#field-element-checks>
#[derive(Clone, Debug)] #[derive(Clone, Debug)]
struct ValueCanonicity { struct ValueCanonicity {
q_notecommit_value: Selector, q_notecommit_value: Selector,
@ -1011,7 +1011,7 @@ impl ValueCanonicity {
/// | rho | e_1 | f | z13_f | 1 | /// | rho | e_1 | f | z13_f | 1 |
/// | | g_0 | e1_f_prime | z14_e1_f_prime | 0 | /// | | g_0 | e1_f_prime | z14_e1_f_prime | 0 |
/// ///
/// <https://p.z.cash/orchard-0.1:note-commit-canonicity-rho?partial> /// <https://zcash.github.io/orchard/design/circuit/note-commit.html#field-element-checks>
#[derive(Clone, Debug)] #[derive(Clone, Debug)]
struct RhoCanonicity { struct RhoCanonicity {
q_notecommit_rho: Selector, q_notecommit_rho: Selector,
@ -1126,7 +1126,7 @@ impl RhoCanonicity {
/// | psi | g_1 | g_2 | z13_g | 1 | /// | psi | g_1 | g_2 | z13_g | 1 |
/// | h_0 | h_1 | g1_g2_prime | z13_g1_g2_prime | 0 | /// | h_0 | h_1 | g1_g2_prime | z13_g1_g2_prime | 0 |
/// ///
/// <https://p.z.cash/orchard-0.1:note-commit-canonicity-psi?partial> /// <https://zcash.github.io/orchard/design/circuit/note-commit.html#field-element-checks>
#[derive(Clone, Debug)] #[derive(Clone, Debug)]
struct PsiCanonicity { struct PsiCanonicity {
q_notecommit_psi: Selector, q_notecommit_psi: Selector,
@ -1297,7 +1297,7 @@ impl YCanonicity {
let z13_j_prime = meta.query_advice(advices[9], Rotation::next()); let z13_j_prime = meta.query_advice(advices[9], Rotation::next());
// Decomposition checks // 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 = { let decomposition_checks = {
// Check that k_3 is boolean // Check that k_3 is boolean
let k3_check = bool_check(k_3.clone()); 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. // 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 = { let canonicity_checks = {
iter::empty() iter::empty()
.chain(Some(("k_3 = 1 => k_2 = 0", k_2))) .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 // constraints allows ⊥ to occur, and then during synthesis it detects these edge
// cases and raises an error (aborting proof creation). // cases and raises an error (aborting proof creation).
// //
// https://p.z.cash/ZKS:action-cm-old-integrity?partial // https://zips.z.cash/protocol/nu5.pdf#concretesinsemillacommitl
// https://p.z.cash/ZKS:action-cmx-new-integrity?partial
let (cm, zs) = { let (cm, zs) = {
let message = Message::from_pieces( let message = Message::from_pieces(
chip.clone(), 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). /// A canonicity check helper used in checking x(g_d), y(g_d), and y(pk_d).
/// ///
/// Specifications: /// Specifications:
/// - [`g_d` canonicity](https://p.z.cash/orchard-0.1:note-commit-canonicity-g_d?partial) /// - [`g_d` canonicity](https://zcash.github.io/orchard/design/circuit/note-commit.html#field-element-checks)
/// - [`y` canonicity](https://p.z.cash/orchard-0.1:note-commit-canonicity-y?partial) /// - [`y` canonicity](https://zcash.github.io/orchard/design/circuit/note-commit.html#field-element-checks)
fn canon_bitshift_130( fn canon_bitshift_130(
lookup_config: &LookupRangeCheckConfig<pallas::Base, 10>, lookup_config: &LookupRangeCheckConfig<pallas::Base, 10>,
mut layouter: impl Layouter<pallas::Base>, mut layouter: impl Layouter<pallas::Base>,
@ -1812,7 +1811,7 @@ pub(in crate::circuit) mod gadgets {
/// Check canonicity of `x(pk_d)` encoding. /// 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( fn pkd_x_canonicity(
lookup_config: &LookupRangeCheckConfig<pallas::Base, 10>, lookup_config: &LookupRangeCheckConfig<pallas::Base, 10>,
mut layouter: impl Layouter<pallas::Base>, mut layouter: impl Layouter<pallas::Base>,
@ -1853,7 +1852,7 @@ pub(in crate::circuit) mod gadgets {
/// Check canonicity of `rho` encoding. /// 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( fn rho_canonicity(
lookup_config: &LookupRangeCheckConfig<pallas::Base, 10>, lookup_config: &LookupRangeCheckConfig<pallas::Base, 10>,
mut layouter: impl Layouter<pallas::Base>, mut layouter: impl Layouter<pallas::Base>,
@ -1894,7 +1893,7 @@ pub(in crate::circuit) mod gadgets {
/// Check canonicity of `psi` encoding. /// 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( fn psi_canonicity(
lookup_config: &LookupRangeCheckConfig<pallas::Base, 10>, lookup_config: &LookupRangeCheckConfig<pallas::Base, 10>,
mut layouter: impl Layouter<pallas::Base>, mut layouter: impl Layouter<pallas::Base>,
@ -1935,8 +1934,7 @@ pub(in crate::circuit) mod gadgets {
/// Also, witness the LSB and return the witnessed cell. /// Also, witness the LSB and return the witnessed cell.
/// ///
/// Specifications: /// Specifications:
/// - [`y` decomposition](https://p.z.cash/orchard-0.1:note-commit-decomposition-y?partial) /// - [`y` decomposition and `y` canonicity](https://zcash.github.io/orchard/design/circuit/note-commit.html#field-element-checks)
/// - [`y` canonicity](https://p.z.cash/orchard-0.1:note-commit-canonicity-y?partial)
fn y_canonicity( fn y_canonicity(
lookup_config: &LookupRangeCheckConfig<pallas::Base, 10>, lookup_config: &LookupRangeCheckConfig<pallas::Base, 10>,
y_canon: &YCanonicity, y_canon: &YCanonicity,