spec: describe convert circuit

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

@@ -76,7 +76,7 @@ where $B_{SpendAuth}$ is the conventional `decaf377` basepoint as described in [
 
 ### Merkle auth path verification
 
-The zk-SNARK certifies that for non-zero values[^1] $v \ne 0$, the witnessed Merkle authentication path is a valid Merkle path to the provided public anchor. For notes with non-zero values $v \ne 0$, the note can be unrooted from the tree to allow for dummy spends to pass stateless verification. Dummy spends may be added for metadata resistance (e.g. to ensure there are two spends and two outputs in each transaction).
+The zk-SNARK certifies that for non-zero values[^1] $v \ne 0$, the witnessed Merkle authentication path is a valid Merkle path to the provided public anchor. Only for notes with non-zero values $v \ne 0$, the note is unrooted from the state commitment tree to allow for these "dummy" spends to pass stateless verification. Dummy spends may be added for metadata resistance (e.g. to ensure there are two spends and two outputs in each transaction).
 
 ### Diversified Base is not Identity
 

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

@@ -1,19 +1,22 @@
 # Undelegate Claim Descriptions
 
-Each undelegate claim contains a UndelegateClaimBody and a zk-SNARK undelegate claim proof.
+Each undelegate claim contains a UndelegateClaimBody and a zk-SNARK undelegate claim proof. The undelegate claim proof is implemented as an instance of a generic convert circuit which converts a private amount of one input asset into a target asset, given a public conversion rate.
 
-## Undelegate Claim zk-SNARK Statements
+First we describe the convert circuit, and then the undelegate claim proof.
 
-The undelegate claim proof demonstrates the properties enumerated below for the private witnesses known by the prover:
+## Convert zk-SNARK Statements
 
-* Unbonding amount $v_u$ interpreted as an $\mathbb F_q$
+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$
 * 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
-* Penalty $p$ interpreted as an $\mathbb F_q$
-* Unbonding asset ID $G_u \isin \mathbb G$
+* 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
 
 ### Balance Commitment Integrity
 
@@ -23,14 +26,20 @@ $cv = v_e + [\widetilde{v}] G_{\widetilde{v}}$
 
 where $G_{\widetilde{v}}$ is a constant generator.
 
-$v_e$ is the expected balance computed from the penalty $p$, the unbonding
-amount $v_u$ and the unbonding asset ID $G_u$:
+$v_e$ is the expected balance computed from the public conversion rate $p$ and the input
+amount $v_i$:
+
+$v_e = [-v_i] G_{v_i} + [p * v_i] G_{v_t}$
+
+where $G_{v_i}$ is the asset-specific generator corresponding to the input
+token with asset ID $ID_i$ and $G_{v_t}$ is the asset-specific generator corresponding to the
+target token with asset ID $ID_t$. Both these asset-specific bases are derived in-circuit as described in [Value Commitments](../../protocol/value_commitments.md).
 
-$v_e = [-v_u] G_{v_u} + v_p G_{v_s}$
+## Undelegate Claim
 
-where $G_{v_u}$ is the asset-specific generator corresponding to the unbonding
-token and $G_{v_s}$ is the asset-specific generator corresponding to the
-staking token. $v_u$ is the unbonding amount, and $v_p$ is the penalized amount,
-computed by applying the penalty $p$ to the unbonding amount:
+The undelegate claim proof uses the convert circuit statements above where:
 
-$v_p = v_u * (100,000,000 - p) / 100,000,000$
+* 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