protocol spec: describe bounds checking in circuits

docs/protocol/src/protocol/action_descriptions/delegator_vote.md

@@ -6,23 +6,23 @@ Each delegator vote contains an DelegatorVoteBody and a zk-SNARK delegator vote
 
 The delegator vote proof demonstrates the properties enumerated below for the following private witnesses known by the prover:
 
-* Note amount $v$ (interpreted as an $\mathbb F_q$) and asset `ID` $\isin \mathbb G$
+* Note amount $v$ (interpreted as an $\mathbb F_q$ and constrained to fit in 128 bits) and asset `ID` $\isin \mathbb F_q$
 * Note blinding factor $rcm \isin \mathbb F_q$ used to blind the note commitment
 * Address associated with the note being spent, consisting of diversified basepoint $B_d \isin \mathbb G$,
 transmission key $pk_d \isin \mathbb G$, and clue key $\mathsf{ck_d} \isin \mathbb F_q$
 * Note commitment $cm \isin \mathbb F_q$
 * Spend authorization randomizer used for generating the randomized spend authorization key $\alpha \isin \mathbb F_r$
 * Spend authorization key $ak \isin \mathbb G$
 * Nullifier deriving key $nk \isin \mathbb F_q$
-* Merkle proof of inclusion for the note commitment, consisting of a position `pos` and an authentication path consisting of 72 $\mathbb F_q$ elements (3 siblings each per 24 levels)
+* Merkle proof of inclusion for the note commitment, consisting of a position `pos`, constrained to fit in 48 bits, and an authentication path consisting of 72 $\mathbb F_q$ elements (3 siblings each per 24 levels)
 
 And the corresponding public inputs:
 
 * Merkle anchor $\isin \mathbb F_q$ of the state commitment tree
 * Balance commitment $cv \isin G$ to the value balance
-* Nullifier $nf$ of the note to be spent
+* Nullifier $nf \isin F_q$ of the note to be spent
 * Randomized verification key $rk \isin \mathbb G$
-* The start position `start_pos` of the proposal being voted on
+* The start position `start_pos` of the proposal being voted on, constrained to fit in 48 bits
 
 ### Start Position Verification
 

docs/protocol/src/protocol/action_descriptions/outputs.md

@@ -10,7 +10,7 @@ $epk = [esk] B_d$
 
 The output proof demonstrates the properties enumerated below for the private witnesses known by the prover:
 
-* Note amount $v$ (interpreted as an $\mathbb F_q$) and asset `ID` $\isin \mathbb G$
+* Note amount $v$ (interpreted as an $\mathbb F_q$, constrained to fit in 128 bits) and asset `ID` $\isin \mathbb F_q$
 * Blinding factor $rcm \isin \mathbb F_q$ used to blind the note commitment
 * Diversified basepoint $B_d \isin \mathbb G$ corresponding to the address
 * Transmission key $pk_d \isin \mathbb G$ corresponding to the address

docs/protocol/src/protocol/action_descriptions/spend.md

@@ -6,7 +6,7 @@ Each spend contains an SpendBody and a zk-SNARK spend proof.
 
 The spend proof demonstrates the properties enumerated below for the following private witnesses known by the prover:
 
-* Note amount $v$ (interpreted as an $\mathbb F_q$) and asset `ID` $\isin \mathbb G$
+* Note amount $v$ (interpreted as an $\mathbb F_q$, constrained to fit in 128 bits) and asset `ID` $\isin \mathbb F_q$
 * Note blinding factor $rcm \isin \mathbb F_q$ used to blind the note commitment
 * Address associated with the note being spent, consisting of diversified basepoint $B_d \isin \mathbb G$,
 transmission key $pk_d \isin \mathbb G$, and clue key $\mathsf{ck_d} \isin \mathbb F_q$
@@ -15,13 +15,13 @@ transmission key $pk_d \isin \mathbb G$, and clue key $\mathsf{ck_d} \isin \math
 * Spend authorization randomizer used for generating the randomized spend authorization key $\alpha \isin \mathbb F_r$
 * Spend authorization key $ak \isin \mathbb G$
 * Nullifier deriving key $nk \isin \mathbb F_q$
-* Merkle proof of inclusion for the note commitment, consisting of a position `pos` and an authentication path consisting of 72 $\mathbb F_q$ elements (3 siblings each per 24 levels)
+* Merkle proof of inclusion for the note commitment, consisting of a position `pos` constrained to fit in 48 bits, and an authentication path consisting of 72 $\mathbb F_q$ elements (3 siblings each per 24 levels)
 
 And the corresponding public inputs:
 
 * Merkle anchor $\isin \mathbb F_q$ of the state commitment tree
 * Balance commitment $cv \isin G$ to the value balance
-* Nullifier $nf$ of the note to be spent
+* Nullifier $nf \isin F_q$ of the note to be spent
 * Randomized verification key $rk \isin \mathbb G$
 
 ### Note Commitment Integrity

docs/protocol/src/protocol/action_descriptions/swap.md

@@ -7,11 +7,10 @@ Each swap contains a SwapBody and a zk-SNARK swap proof.
 The swap proof demonstrates the properties enumerated below for the private witnesses known by the prover:
 
 * Swap plaintext which consists of:
-  * Trading pair, which consists of two asset IDs  $ID_1, ID_2 \isin \mathbb F_q$ with asset-specific generators $G_1, G_2 \isin \mathbb G$
-  * Fee value which consists of an amount $v_f$ interpreted as an $\mathbb F_q$ and
- an asset ID $ID_{v_f} \isin \mathbb F_q$ with asset-specific generator $G_{v_f} \isin \mathbb G$
-  * Input amount of the first asset $v_1$ interpreted as an $\mathbb F_q$
-  * Input amount of the second asset $v_2$ interpreted as an $\mathbb F_q$
+  * Trading pair, which consists of two asset IDs  $ID_1, ID_2 \isin \mathbb F_q$
+  * Fee value which consists of an amount $v_f$ interpreted as an $\mathbb F_q$ constrained to fit in 128 bits, and an asset ID $ID_{v_f} \isin \mathbb F_q$
+  * Input amount of the first asset $v_1$ interpreted as an $\mathbb F_q$ constrained to fit in 128 bits
+  * Input amount of the second asset $v_2$ interpreted as an $\mathbb F_q$ constrained to fit in 128 bits
   * `Rseed`, interpreted as an $\mathbb F_q$
   * Diversified basepoint $B_d \isin \mathbb G$ corresponding to the claim address
   * Transmission key $pk_d \isin \mathbb G$ corresponding to the claim address
@@ -42,12 +41,12 @@ The zk-SNARK certifies that the public input fee commitment $cv_f$ was derived f
 
 $cv_f = [-v_f] G_{v_f} + [\widetilde{v_f}] G_{\widetilde{v}}$
 
-where $G_{\widetilde{v}}$ is a constant generator and $G_{v_f}$ is an asset-specific generator point derived in-circuit as described in [Value Commitments](../../protocol/value_commitments.md).
+where $G_{\widetilde{v}}$ is a constant generator and $G_{v_f}$ is an asset-specific generator point derived in-circuit from the asset ID $ID_{v_f}$ as described in [Value Commitments](../../protocol/value_commitments.md).
 
 ### Balance Commitment Integrity
 
 The zk-SNARK certifies that the total public input balance commitment $cv$ was derived from the witnessed values as:
 
 $cv = [-v_1] G_1 + [-v_2] G_2 + cv_f$
 
-where the first two terms are from the input amounts and assets, with the corresponding asset-specific generates derived in-circuit as described in [Value Commitments](../../protocol/value_commitments.md), and $cv_f$ is the fee commitment.
+where the first two terms are from the input amounts and assets, with the corresponding asset-specific generators $G_1, G_2$ derived in-circuit as described in [Value Commitments](../../protocol/value_commitments.md), and $cv_f$ is the fee commitment.

docs/protocol/src/protocol/action_descriptions/swap_claim.md

@@ -8,33 +8,31 @@ The swap claim proof demonstrates the properties enumerated below for the privat
 
 * Swap plaintext corresponding to the swap being claimed. This consists of:
   * Trading pair, which consists of two asset IDs $ID_1, ID_2 \isin \mathbb F_q$
-  * Fee value which consists of an amount $v_f$ interpreted as an $\mathbb F_q$ and
- an asset ID $ID_{v_f} \isin \mathbb F_q$
-  * Input amount $\Delta_{1i}$ of the first asset interpreted as an $\mathbb F_q$
-  * Input amount $\Delta_{2i}$ of the second asset interpreted as an $\mathbb F_q$
+  * Fee value which consists of an amount $v_f$ interpreted as an $\mathbb F_q$ constrained to fit in 128 bits and an asset ID $ID_{v_f} \isin \mathbb F_q$
+  * Input amount $\Delta_{1i}$ of the first asset interpreted as an $\mathbb F_q$ constrained to fit in 128 bits
+  * Input amount $\Delta_{2i}$ of the second asset interpreted as an $\mathbb F_q$ constrained to fit in 128 bits
   * `Rseed`, interpreted as an $\mathbb F_q$
   * Diversified basepoint $B_d \isin \mathbb G$ corresponding to the claim address
   * Transmission key $pk_d \isin \mathbb G$ corresponding to the claim address
   * Clue key $\mathsf{ck_d} \isin \mathbb F_q$ corresponding to the claim address
 * Swap commitment $scm \isin \mathbb F_q$
-* Merkle proof of inclusion for the swap commitment, consisting of a position `pos` and an authentication path consisting of 72 $\mathbb F_q$ elements (3 siblings each per 24 levels)
+* Merkle proof of inclusion for the swap commitment, consisting of a position `pos` constrained to fit in 48 bits and an authentication path consisting of 72 $\mathbb F_q$ elements (3 siblings each per 24 levels)
 * Nullifier deriving key $nk \isin \mathbb F_q$
-* Output amount $\Lambda_{1i}$ of the first asset interpreted as an $\mathbb F_q$
-* Output amount $\Lambda_{2i}$ of the second asset interpreted as an $\mathbb F_q$
+* Output amount $\Lambda_{1i}$ of the first asset interpreted as an $\mathbb F_q$ constrained to fit in 128 bits
+* Output amount $\Lambda_{2i}$ of the second asset interpreted as an $\mathbb F_q$ constrained to fit in 128 bits
 * Note blinding factor $rcm_1 \isin \mathbb F_q$ used to blind the first output note commitment
 * Note blinding factor $rcm_2 \isin \mathbb F_q$ used to blind the second output note commitment
 
 And the corresponding public inputs:
 
 * Merkle anchor $\isin \mathbb F_q$ of the state commitment tree
-* Nullifier $nf$ corresponding to the swap
-* Fee to claim the outputs which consists of an amount $v_f$ interpreted as an $\mathbb F_q$ and
- an asset ID $G_{v_f} \isin \mathbb G$
+* Nullifier $nf \isin F_q$ corresponding to the swap
+* Fee to claim the outputs which consists of an amount $v_f$ interpreted as an $\mathbb F_q$ constrained to fit in 128 bits and an asset ID $ID_{v_f} \isin \mathbb F_q$
 * The batch swap output data, which consists of:
   * trading pair, which consists of two asset IDs $ID_{pi1}, ID_{pi2} \isin \mathbb F_q$
   * 128-bit fixed point values (represented in circuit as four 64-bit (Boolean constraint) limbs) for the batched inputs $\Delta_1, \Delta_2$, outputs $\Lambda_1, \Lambda_2$, and the unfilled quantities $U_1, U_2$
-  * block height $h \isin \mathbb F_q$
-  * starting height of the epoch $h_e \isin \mathbb F_q$
+  * block height $h \isin \mathbb F_q$ constrained to fit in 64 bits
+  * starting height of the epoch $h_e \isin \mathbb F_q$ constrained to fit in 64 bits
 * Note commitment of the first output note $cm_1 \isin \mathbb F_q$
 * Note commitment of the second output note $cm_2 \isin \mathbb F_q$
 
@@ -44,7 +42,7 @@ The zk-SNARK certifies that the witnessed swap commitment $scm$ was derived as:
 
 $scm_{inner} = hash_4(ds, (ID_1, ID_2, \Delta_1, \Delta_2))$
 
-$scm = hash_7(ds, (rseed, v_f, G_{v_f}, B_d, pk_d, \mathsf{ck_d}, scm_{inner}))$.
+$scm = hash_7(ds, (rseed, v_f, ID_{v_f}, B_d, pk_d, \mathsf{ck_d}, scm_{inner}))$.
 
 using the above witnessed values and where `ds` is a constant domain separator:
 

docs/protocol/src/protocol/action_descriptions/undelegate_claim.md

@@ -8,15 +8,15 @@ First we describe the convert circuit, and then the undelegate claim proof.
 
 The convert circuit demonstrates the properties enumerated below for the private witnesses known by the prover:
 
-* Input amount $v_i$ interpreted as an $\mathbb F_q$
+* Input amount $v_i$ interpreted as an $\mathbb F_q$ and constrained to fit in 128 bits
 * Balance blinding factor $\widetilde{v} \isin \mathbb F_r$ used to blind the balance commitment
 
 And the corresponding public inputs:
 
 * Balance commitment $cv \isin G$ to the value balance
 * Rate $p$, a 128-bit fixed point value, represented in circuit as four 64-bit (Boolean constraint) limbs
-* Asset ID $ID_i \isin \mathbb G$ of the input (source) amount
-* Asset ID $ID_t \isin \mathbb G$ of the target amount
+* Asset ID $ID_i \isin \mathbb F_q$ of the input (source) amount
+* Asset ID $ID_t \isin \mathbb F_q$ of the target amount
 
 ### Balance Commitment Integrity
 
@@ -41,5 +41,5 @@ The undelegate claim proof uses the convert circuit statements above where:
 
 * The input amount $v_i$ is set to the unbonding amount
 * The rate is set to the Penalty $p$
-* Asset `ID` $G_i$ is the unbonding token asset ID
-* Asset `ID` $G_t$ is the staking token asset ID
+* Asset `ID` $ID_i$ is the unbonding token asset ID
+* Asset `ID` $ID_t$ is the staking token asset ID