auction: add tables to value balance descriptions

crates/core/component/auction/src/auction/dutch/actions/end.rs

@@ -15,8 +15,17 @@ pub struct ActionDutchAuctionEnd {
 }
 
 impl ActionDutchAuctionEnd {
+    /// Compute the value balance for this action
+    ///
+    /// # Diagram
+    ///
+    ///  ┌────────────────────┬──────────────────────┐
+    ///  │      Burn (-)      │       Mint (+)       │
+    ///  ├────────────────────┼──────────────────────┤
+    ///  │ opened auction nft │  closed auction nft  │
+    ///  └────────────────────┴──────────────────────┘
     pub fn balance(&self) -> Balance {
-        let schedule_auction = Value {
+        let start_auction = Value {
             amount: 1u128.into(),
             asset_id: AuctionNft::new(self.auction_id, 0u64).asset_id(),
         };
@@ -26,7 +35,7 @@ impl ActionDutchAuctionEnd {
             asset_id: AuctionNft::new(self.auction_id, 1u64).asset_id(),
         };
 
-        Balance::from(end_auction) - Balance::from(schedule_auction)
+        Balance::from(end_auction) - Balance::from(start_auction)
     }
 }
 

crates/core/component/auction/src/auction/dutch/actions/schedule.rs

@@ -14,8 +14,15 @@ pub struct ActionDutchAuctionSchedule {
 }
 
 impl ActionDutchAuctionSchedule {
-    /// Compute a commitment to the value this action contributes to its transaction
-    /// MERGEBLOCK(erwan): add balancing table
+    /// Compute the value balance corresponding to this action:
+    ///
+    /// # Diagram
+    ///
+    ///  ┌────────────────────┬──────────────────────┐
+    ///  │      Burn (-)      │       Mint (+)       │
+    ///  ├────────────────────┼──────────────────────┤
+    ///  │    input value     │  opened auction nft  │
+    ///  └────────────────────┴──────────────────────┘                  
     pub fn balance(&self) -> Balance {
         let opened_auction_nft = AuctionNft::new(self.description.id(), 0u64);
         let opened_auction_nft_value = Value {

crates/core/component/auction/src/auction/dutch/actions/withdraw.rs

@@ -18,9 +18,29 @@ pub struct ActionDutchAuctionWithdraw {
 }
 
 impl ActionDutchAuctionWithdraw {
+    /// Compute a balance **commitment** for this action.
+    ///
+    /// # Diagram
+    ///
+    /// The value balance commitment is built from the balance:
+    ///  ┌────────────────────┬──────────────────────┐
+    ///  │      Burn (-)      │       Mint (+)       │
+    ///  ├────────────────────┼──────────────────────┤
+    ///  │    auction nft     │       auction        │
+    ///  │   with seq >= 1    │    value balance     │
+    ///  └────────────────────┼──────────────────────┤
+    ///                       │withdrawn auction nft │
+    ///                       │      with seq+1      │
+    ///                       └──────────────────────┘
+    ///
+    /// More context: [Actions and Value balance][protocol-spec]
+    /// [protocol-spec]: https://protocol.penumbra.zone/main/transactions.html#actions-and-value-balance
     pub fn balance_commitment(&self) -> balance::Commitment {
         let prev_auction_nft = Balance::from(Value {
             amount: 1u128.into(),
+            // The sequence number should always be >= 1, because we can
+            // only withdraw an auction that has ended (i.e. with sequence number `>=1`).
+            // We use a saturating operation defensively so that we don't underflow.
             asset_id: AuctionNft::new(self.auction_id, self.seq.saturating_sub(1)).asset_id(),
         })
         .commit(Fr::zero());