fix(topup): check valid new state leaf balance

circuits/circom/processMessages.circom

@@ -401,8 +401,8 @@ template ProcessTopup(stateTreeDepth) {
     // msgType of topup command is 2
     amt <== amount * (msgType - 1); 
     index <== stateTreeIndex * (msgType - 1);
-    component validCreditBalance = LessEqThan(N_BITS);
-    // check stateIndex, if invalid index, set index and amount to zero
+
+    // check stateIndex, if invalid index, set index to zero
     component validStateLeafIndex = LessEqThan(N_BITS);
     validStateLeafIndex.in[0] <== index;
     validStateLeafIndex.in[1] <== numSignUps;
@@ -419,17 +419,27 @@ template ProcessTopup(stateTreeDepth) {
     amtMux.c[0] <== 0;
     amtMux.c[1] <== amt;
 
-    // check less than field size
+    // check new balance is valid
     signal newCreditBalance;
+    // add either 0 or the actual amount (if the state index is valid)
     newCreditBalance <== stateLeaf[STATE_LEAF_VOICE_CREDIT_BALANCE_IDX] + amtMux.out;
+
+    // we need to ensure it did not overflow (so previous must be <= new)
+    component validCreditBalance = SafeLessEqThan(N_BITS);
     validCreditBalance.in[0] <== stateLeaf[STATE_LEAF_VOICE_CREDIT_BALANCE_IDX];
     validCreditBalance.in[1] <== newCreditBalance;
 
+    // if the new one is <= the old one, then we have a valid topup
+    component creditBalanceMux = Mux1();
+    creditBalanceMux.s <== validCreditBalance.out;
+    creditBalanceMux.c[0] <== stateLeaf[STATE_LEAF_VOICE_CREDIT_BALANCE_IDX];
+    creditBalanceMux.c[1] <== newCreditBalance;
+
     // update credit voice balance
     component newStateLeafHasher = Hasher4();
     newStateLeafHasher.in[STATE_LEAF_PUB_X_IDX] <== stateLeaf[STATE_LEAF_PUB_X_IDX];
     newStateLeafHasher.in[STATE_LEAF_PUB_Y_IDX] <== stateLeaf[STATE_LEAF_PUB_Y_IDX];
-    newStateLeafHasher.in[STATE_LEAF_VOICE_CREDIT_BALANCE_IDX] <== newCreditBalance;
+    newStateLeafHasher.in[STATE_LEAF_VOICE_CREDIT_BALANCE_IDX] <== creditBalanceMux.out;
     newStateLeafHasher.in[STATE_LEAF_TIMESTAMP_IDX] <== stateLeaf[STATE_LEAF_TIMESTAMP_IDX];
 
     component stateLeafPathIndices = QuinGeneratePathIndices(stateTreeDepth);

core/ts/Poll.ts

@@ -657,6 +657,7 @@ export class Poll implements IPoll {
               const newStateLeaf = this.stateLeaves[stateIndex].copy();
               // update the voice credit balance
               newStateLeaf.voiceCreditBalance += amount;
+
               // save it
               this.stateLeaves[stateIndex] = newStateLeaf;
               // update the state tree

website/versioned_docs/version-v1.x/topup.md

@@ -0,0 +1,10 @@
+---
+title: MACI key change
+description: How key change messages work
+sidebar_label: Key change
+sidebar_position: 16
+---
+
+# Topup
+
+MACI v1.1.1 introduced the topup feature. This was developed by [chaosma](https://github.com/chaosma) and their [article](https://hackmd.io/@chaosma/rkyPfI7Iq) + the initial idea [here](https://hackmd.io/@ef-zkp/rk6uaQBrI).