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

Merge pull request #321 from zcash/protocol-rule-links 

Add protocol rule links for the Orchard circuit constraints
This commit is contained in:
str4d 2022-05-27 17:03:05 +01:00 committed by GitHub
parent 4f3f0eaa2d 07239e50a8
commit 36d263fb19
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
6 changed files with 99 additions and 26 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

19
book/src/IDENTIFIERS.json Normal file
View File

@ -0,0 +1,19 @@
{
"commit-ivk-bit-lengths": "design/circuit/commit-ivk.html#bit-length-constraints",
"commit-ivk-canonicity-ak": "design/circuit/commit-ivk.html#canonicity-ak",
"commit-ivk-canonicity-nk": "design/circuit/commit-ivk.html#canonicity-nk",
"commit-ivk-decompositions": "design/circuit/commit-ivk.html#constrain-bit-lengths",
"commit-ivk-region-layout": "design/circuit/commit-ivk.html#region-layout",
"note-commit-canonicity-g_d": "design/circuit/note-commit.html#canonicity-g_d",
"note-commit-canonicity-pk_d": "design/circuit/note-commit.html#canonicity-pk_d",
"note-commit-canonicity-psi": "design/circuit/note-commit.html#canonicity-psi",
"note-commit-canonicity-rho": "design/circuit/note-commit.html#canonicity-rho",
"note-commit-canonicity-v": "design/circuit/note-commit.html#canonicity-v",
"note-commit-canonicity-y": "design/circuit/note-commit.html#canonicity-y",
"note-commit-decomposition-b": "design/circuit/note-commit.html#decomposition-b",
"note-commit-decomposition-d": "design/circuit/note-commit.html#decomposition-d",
"note-commit-decomposition-e": "design/circuit/note-commit.html#decomposition-e",
"note-commit-decomposition-g": "design/circuit/note-commit.html#decomposition-g",
"note-commit-decomposition-h": "design/circuit/note-commit.html#decomposition-h",
"note-commit-decomposition-y": "design/circuit/note-commit.html#decomposition-y"
}

4
book/src/design/circuit/commit-ivk.md
View File

@ -146,7 +146,7 @@ $\NullifierKey$).
> - Let $x' = x + t' - t$.
> - Enforce $0 \leq x' < t'$.
### $\AuthSignPublic$ with $b_1 = 1 \implies \AuthSignPublic \geq 2^{254}$
### $\AuthSignPublic$ with $b_1 = 1 \implies \AuthSignPublic \geq 2^{254}$ <a name="canonicity-ak">
In these cases, we check that $\textsf{ak}_{0..=253} < t_\mathbb{P}$:
@ -181,7 +181,7 @@ $$
\end{array}
$$
### $\NullifierKey$ with $d_1 = 1 \implies \NullifierKey \geq 2^{254}$
### $\NullifierKey$ with $d_1 = 1 \implies \NullifierKey \geq 2^{254}$ <a name="canonicity-nk">
In these cases, we check that $\textsf{nk}_{0..=253} < t_\mathbb{P}$:

24
book/src/design/circuit/note-commit.md
View File

@ -104,7 +104,7 @@ The following helper gates are defined:
- $\ShortLookupRangeCheck{}$ is a
[short lookup range check](../decomposition.md#short-range-check).
### $b = b_0 \bconcat b_1 \bconcat b_2 \bconcat b_3$
### $b = b_0 \bconcat b_1 \bconcat b_2 \bconcat b_3$ <a name="decomposition-b">
$b$ has been constrained to be $10$ bits by the Sinsemilla hash.
#### Region layout
@ -132,7 +132,7 @@ Outside this gate, we have constrained:
- $\ShortLookupRangeCheck{b_0, 4}$
- $\ShortLookupRangeCheck{b_3, 4}$
### $d = d_0 \bconcat d_1 \bconcat d_2 \bconcat d_3$
### $d = d_0 \bconcat d_1 \bconcat d_2 \bconcat d_3$ <a name="decomposition-d">
$d$ has been constrained to be $60$ bits by the $\SinsemillaHash$.
#### Region layout
@ -161,7 +161,7 @@ Outside this gate, we have constrained:
- $d_3$ is equality-constrained to $z_{d,1}$, where the latter is the index-1 running sum
output of $\SinsemillaHash(d),$ constrained by the hash to be $50$ bits.
### $e = e_0 \bconcat e_1$
### $e = e_0 \bconcat e_1$ <a name="decomposition-e">
$e$ has been constrained to be $10$ bits by the $\SinsemillaHash$.
#### Region layout
@ -186,7 +186,7 @@ Outside this gate, we have constrained:
- $\ShortLookupRangeCheck{e_0, 6}$
- $\ShortLookupRangeCheck{e_1, 4}$
### $g = g_0 \bconcat g_1 \bconcat g_2$
### $g = g_0 \bconcat g_1 \bconcat g_2$ <a name="decomposition-g">
$g$ has been constrained to be $250$ bits by the $\SinsemillaHash$.
#### Region layout
@ -214,7 +214,7 @@ Outside this gate, we have constrained:
- $g_2$ is equality-constrained to $z_{g,1}$, where the latter is the index-1 running sum
output of $\SinsemillaHash(g),$ constrained by the hash to be 240 bits.
### $h = h_0 \bconcat h_1 \bconcat h_2$
### $h = h_0 \bconcat h_1 \bconcat h_2$ <a name="decomposition-h">
$h$ has been constrained to be $10$ bits by the $\SinsemillaHash$.
#### Region layout
@ -280,7 +280,7 @@ below are enforced if and only if the corresponding top bit is set to 1.
> - Let $x' = x + t' - t$.
> - Enforce $0 \leq x' < t'$.
### $x(\mathsf{g_d})$ with $b_1 = 1 \implies x(\mathsf{g_d}) \geq 2^{254}$
### $x(\mathsf{g_d})$ with $b_1 = 1 \implies x(\mathsf{g_d}) \geq 2^{254}$ <a name="canonicity-g_d">
Recall that $x(\mathsf{g_d}) = a + 2^{250} \cdot b_0 + 2^{254} \cdot b_1$. When the top
bit $b_1$ is set, we check that $x(\mathsf{g_d})_{0..=253} < t_\mathbb{P}$:
@ -327,7 +327,7 @@ $$
\end{array}
$$
### $x(\mathsf{pk_d})$ with $d_0 = 1 \implies x(\mathsf{pk_d}) \geq 2^{254}$
### $x(\mathsf{pk_d})$ with $d_0 = 1 \implies x(\mathsf{pk_d}) \geq 2^{254}$ <a name="canonicity-pk_d">
Recall that $x(\mathsf{pk_d}) = b_3 + 2^4 \cdot c + 2^{254} \cdot d_0$. When the top bit
$d_0$ is set, we check that $x(\mathsf{pk_d})_{0..=253} < t_\mathbb{P}$:
@ -368,7 +368,7 @@ $$
\end{array}
$$
### $\mathsf{v} = d_2 + 2^8 \cdot d_3 + 2^{58} \cdot e_0$
### $\mathsf{v} = d_2 + 2^8 \cdot d_3 + 2^{58} \cdot e_0$ <a name="canonicity-v">
#### Region layout
$$
@ -388,7 +388,7 @@ $$
\end{array}
$$
### $\rho$ with $g_0 = 1 \implies \rho \geq 2^{254}$
### $\rho$ with $g_0 = 1 \implies \rho \geq 2^{254}$ <a name="canonicity-rho">
Recall that $\rho = e_1 + 2^4 \cdot f + 2^{254} \cdot g_0$. When the top bit $g_0$ is set,
we check that $\rho_{0..=253} < t_\mathbb{P}$:
@ -429,7 +429,7 @@ $$
\end{array}
$$
### $\psi$ with $h_1 = 1 \implies \psi \geq 2^{254}$
### $\psi$ with $h_1 = 1 \implies \psi \geq 2^{254}$ <a name="canonicity-psi">
Recall that $\psi = g_1 + 2^9 \cdot g_2 + 2^{249} \cdot h_0 + 2^{254} \cdot h_1$. When the
top bit $h_1$ is set, we check that $\psi_{0..=253} < t_\mathbb{P}$:
@ -476,7 +476,7 @@ $$
\end{array}
$$
### $y$-coordinate checks
### $y$-coordinate checks <a name="decomposition-y">
Note that only the $ỹ$ LSB of the $y$-coordinates $y(\mathsf{g_d}), y(\mathsf{pk_d})$ was
input to the hash, while the other bits of the $y$-coordinate were unused. However, we
@ -523,7 +523,7 @@ $$
\end{array}
$$
### $y(\mathsf{g_d})$ with $k_3 = 1 \implies y(\mathsf{g_d}) \geq 2^{254}$
### $y(\mathsf{g_d})$ with $k_3 = 1 \implies y(\mathsf{g_d}) \geq 2^{254}$ <a name="canonicity-y">
In these cases, we check that $y(\mathsf{g_d})_{0..=253} < t_\mathbb{P}$:

22
src/circuit.rs
View File

@ -143,10 +143,10 @@ impl plonk::Circuit<pallas::Base> for Circuit {
meta.advice_column(),
];
// Constrain v_old - v_new = magnitude * sign
// Either v_old = 0, or calculated root = anchor
// Constrain v_old = 0 or enable_spends = 1.
// Constrain v_new = 0 or enable_outputs = 1.
// Constrain v_old - v_new = magnitude * sign (https://p.z.cash/ZKS:action-cv-net-integrity?partial).
// Either v_old = 0, or calculated root = anchor (https://p.z.cash/ZKS:action-merkle-path-validity?partial).
// Constrain v_old = 0 or enable_spends = 1 (https://p.z.cash/ZKS:action-enable-spend).
// Constrain v_new = 0 or enable_outputs = 1 (https://p.z.cash/ZKS:action-enable-output).
let q_orchard = meta.selector();
meta.create_gate("Orchard circuit checks", |meta| {
let q_orchard = meta.query_selector(q_orchard);
@ -389,7 +389,7 @@ impl plonk::Circuit<pallas::Base> for Circuit {
(psi_old, rho_old, cm_old, g_d_old, ak_P, nk, v_old, v_new)
};
// Merkle path validity check.
// Merkle path validity check (https://p.z.cash/ZKS:action-merkle-path-validity?partial).
let root = {
let path = self
.path
@ -404,7 +404,7 @@ impl plonk::Circuit<pallas::Base> for Circuit {
merkle_inputs.calculate_root(layouter.namespace(|| "Merkle path"), leaf)?
};
// Value commitment integrity.
// Value commitment integrity (https://p.z.cash/ZKS:action-cv-net-integrity?partial).
let v_net_magnitude_sign = {
// Witness the magnitude and sign of v_net = v_old - v_new
let v_net_magnitude_sign = {
@ -462,7 +462,7 @@ impl plonk::Circuit<pallas::Base> for Circuit {
v_net_magnitude_sign
};
// Nullifier integrity
// Nullifier integrity (https://p.z.cash/ZKS:action-nullifier-integrity).
let nf_old = {
let nf_old = gadget::derive_nullifier(
layouter.namespace(|| "nf_old = DeriveNullifier_nk(rho_old, psi_old, cm_old)"),
@ -481,7 +481,7 @@ impl plonk::Circuit<pallas::Base> for Circuit {
nf_old
};
// Spend authority
// Spend authority (https://p.z.cash/ZKS:action-spend-authority)
{
let alpha =
ScalarFixed::new(ecc_chip.clone(), layouter.namespace(|| "alpha"), self.alpha)?;
@ -501,7 +501,7 @@ impl plonk::Circuit<pallas::Base> for Circuit {
layouter.constrain_instance(rk.inner().y().cell(), config.primary, RK_Y)?;
}
// Diversified address integrity.
// Diversified address integrity (https://p.z.cash/ZKS:action-addr-integrity?partial).
let pk_d_old = {
let ivk = {
let ak = ak_P.extract_p().inner().clone();
@ -547,7 +547,7 @@ impl plonk::Circuit<pallas::Base> for Circuit {
pk_d_old
};
// Old note commitment integrity.
// Old note commitment integrity (https://p.z.cash/ZKS:action-cm-old-integrity?partial).
{
let rcm_old = ScalarFixed::new(
ecc_chip.clone(),
@ -575,7 +575,7 @@ impl plonk::Circuit<pallas::Base> for Circuit {
derived_cm_old.constrain_equal(layouter.namespace(|| "cm_old equality"), &cm_old)?;
}
// New note commitment integrity.
// New note commitment integrity (https://p.z.cash/ZKS:action-cmx-new-integrity?partial).
{
// Witness g_d_new
let g_d_new = {

17
src/circuit/commit_ivk.rs
View File

@ -52,6 +52,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
/*
The pieces are laid out in this configuration:
@ -106,6 +108,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
let b1_bool_check = bool_check(b_1.clone());
let d1_bool_check = bool_check(d_1.clone());
@ -126,6 +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
let ak_canonicity_checks = {
// b_1 = 1 => b_0 = 0
let b0_canon_check = b_1.clone() * b_0;
@ -163,6 +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
let nk_canonicity_checks = {
// d_1 = 1 => d_0 = 0
let c0_canon_check = d_1.clone() * d_0;
@ -257,6 +262,8 @@ 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
// `a` = bits 0..=249 of `ak`
let a = MessagePiece::from_subpieces(
@ -327,6 +334,8 @@ pub(in crate::circuit) mod gadgets {
// `ivk = ⊥` is handled internally to `CommitDomain::short_commit`: incomplete
// 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
let (ivk, zs) = {
let message = Message::from_pieces(
sinsemilla_chip.clone(),
@ -385,6 +394,8 @@ 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).
#[allow(clippy::type_complexity)]
fn ak_canonicity(
lookup_config: &LookupRangeCheckConfig<pallas::Base, 10>,
@ -424,6 +435,8 @@ 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).
#[allow(clippy::type_complexity)]
fn nk_canonicity(
lookup_config: &LookupRangeCheckConfig<pallas::Base, 10>,
@ -468,7 +481,9 @@ pub(in crate::circuit) mod gadgets {
}
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
/*
The pieces are laid out in this configuration:

39
src/circuit/note_commit.rs
View File

@ -59,6 +59,8 @@ type CanonicityBounds = (
/// ------------------------------------
/// | b | b_0 | b_1 | 1 |
/// | | b_2 | b_3 | 0 |
///
/// https://p.z.cash/orchard-0.1:note-commit-decomposition-b?partial
#[derive(Clone, Debug)]
struct DecomposeB {
q_notecommit_b: Selector,
@ -207,6 +209,8 @@ impl DecomposeB {
/// ------------------------------------
/// | d | d_0 | d_1 | 1 |
/// | | d_2 | d_3 | 0 |
///
/// https://p.z.cash/orchard-0.1:note-commit-decomposition-d?partial
#[derive(Clone, Debug)]
struct DecomposeD {
q_notecommit_d: Selector,
@ -346,6 +350,8 @@ impl DecomposeD {
/// | A_6 | A_7 | A_8 | q_notecommit_e |
/// ------------------------------------
/// | e | e_0 | e_1 | 1 |
///
/// https://p.z.cash/orchard-0.1:note-commit-decomposition-e?partial
#[derive(Clone, Debug)]
struct DecomposeE {
q_notecommit_e: Selector,
@ -463,6 +469,8 @@ impl DecomposeE {
/// ------------------------------
/// | g | g_0 | 1 |
/// | g_1 | g_2 | 0 |
///
/// https://p.z.cash/orchard-0.1:note-commit-decomposition-g?partial
#[derive(Clone, Debug)]
struct DecomposeG {
q_notecommit_g: Selector,
@ -588,6 +596,8 @@ impl DecomposeG {
/// | A_6 | A_7 | A_8 | q_notecommit_h |
/// ------------------------------------
/// | h | h_0 | h_1 | 1 |
///
/// https://p.z.cash/orchard-0.1:note-commit-decomposition-h?partial
#[derive(Clone, Debug)]
struct DecomposeH {
q_notecommit_h: Selector,
@ -708,6 +718,8 @@ impl DecomposeH {
/// -----------------------------------------------------------
/// | x(g_d) | b_0 | a | z13_a | 1 |
/// | | b_1 | a_prime | z13_a_prime | 0 |
///
/// https://p.z.cash/orchard-0.1:note-commit-canonicity-g_d?partial
#[derive(Clone, Debug)]
struct GdCanonicity {
q_notecommit_g_d: Selector,
@ -823,6 +835,8 @@ impl GdCanonicity {
/// -------------------------------------------------------------------
/// | x(pk_d) | b_3 | c | z13_c | 1 |
/// | | d_0 | b3_c_prime | z14_b3_c_prime | 0 |
///
/// https://p.z.cash/orchard-0.1:note-commit-canonicity-pk_d?partial
#[derive(Clone, Debug)]
struct PkdCanonicity {
q_notecommit_pk_d: Selector,
@ -937,6 +951,8 @@ impl PkdCanonicity {
/// | A_6 | A_7 | A_8 | A_9 | q_notecommit_value |
/// ------------------------------------------------
/// | value | d_2 | d_3 | e_0 | 1 |
///
/// https://p.z.cash/orchard-0.1:note-commit-canonicity-v?partial
#[derive(Clone, Debug)]
struct ValueCanonicity {
q_notecommit_value: Selector,
@ -1013,6 +1029,8 @@ impl ValueCanonicity {
/// --------------------------------------------------------------
/// | rho | e_1 | f | z13_f | 1 |
/// | | g_0 | e1_f_prime | z14_e1_f_prime | 0 |
///
/// https://p.z.cash/orchard-0.1:note-commit-canonicity-rho?partial
#[derive(Clone, Debug)]
struct RhoCanonicity {
q_notecommit_rho: Selector,
@ -1126,6 +1144,8 @@ impl RhoCanonicity {
/// ----------------------------------------------------------------
/// | psi | g_1 | g_2 | z13_g | 1 |
/// | h_0 | h_1 | g1_g2_prime | z13_g1_g2_prime | 0 |
///
/// https://p.z.cash/orchard-0.1:note-commit-canonicity-psi?partial
#[derive(Clone, Debug)]
struct PsiCanonicity {
q_notecommit_psi: Selector,
@ -1296,6 +1316,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
let decomposition_checks = {
// Check that k_3 is boolean
let k3_check = bool_check(k_3.clone());
@ -1316,6 +1337,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
let canonicity_checks = {
iter::empty()
.chain(Some(("k_3 = 1 => k_2 = 0", k_2)))
@ -1652,6 +1674,9 @@ pub(in crate::circuit) mod gadgets {
// `cm = ⊥` is handled internally to `CommitDomain::commit`: incomplete 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-cm-old-integrity?partial
// https://p.z.cash/ZKS:action-cmx-new-integrity?partial
let (cm, zs) = {
let message = Message::from_pieces(
chip.clone(),
@ -1774,6 +1799,10 @@ 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)
fn canon_bitshift_130(
lookup_config: &LookupRangeCheckConfig<pallas::Base, 10>,
mut layouter: impl Layouter<pallas::Base>,
@ -1806,6 +1835,8 @@ 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).
fn pkd_x_canonicity(
lookup_config: &LookupRangeCheckConfig<pallas::Base, 10>,
mut layouter: impl Layouter<pallas::Base>,
@ -1845,6 +1876,8 @@ pub(in crate::circuit) mod gadgets {
}
/// Check canonicity of `rho` encoding.
///
/// [Specification](https://p.z.cash/orchard-0.1:note-commit-canonicity-rho?partial).
fn rho_canonicity(
lookup_config: &LookupRangeCheckConfig<pallas::Base, 10>,
mut layouter: impl Layouter<pallas::Base>,
@ -1884,6 +1917,8 @@ pub(in crate::circuit) mod gadgets {
}
/// Check canonicity of `psi` encoding.
///
/// [Specification](https://p.z.cash/orchard-0.1:note-commit-canonicity-psi?partial).
fn psi_canonicity(
lookup_config: &LookupRangeCheckConfig<pallas::Base, 10>,
mut layouter: impl Layouter<pallas::Base>,
@ -1922,6 +1957,10 @@ pub(in crate::circuit) mod gadgets {
/// Check canonicity of y-coordinate given its LSB as a value.
/// 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)
fn y_canonicity(
lookup_config: &LookupRangeCheckConfig<pallas::Base, 10>,
y_canon: &YCanonicity,