update comments from bez's branch

PENDING.md

@@ -72,4 +72,9 @@ decoded automatically.
 * [\#3411] Include the `RequestInitChain.Time` in the block header init during
 `InitChain`.
 
+* Update the vesting specification and implementation to cap deduction from
+`DelegatedVesting` by at most `DelegatedVesting`. This accounts for the case where
+the undelegation amount may exceed the original delegation amount due to
+truncation of undelegation tokens.
+
 ### Tendermint

docs/spec/auth/05_vesting.md

@@ -276,6 +276,10 @@ func (cva ContinuousVestingAccount) TrackUndelegation(amount Coins) {
 with an excess `DV` amount, even after all its coins have vested. This is because
 undelegating free coins are prioritized.
 
+**Note**: The undelegation (bond refund) amount may exceed the delegated
+vesting (bond) amount due to the way undelegation truncates the bond refund,
+which increases the validator's exchange rate (tokens/shares) slightly.
+
 #### Keepers/Handlers
 
 ```go

x/auth/account.go

@@ -287,6 +287,10 @@ func (bva *BaseVestingAccount) trackDelegation(vestingCoins, amount sdk.Coins) {
 // by which amount the base coins need to increase. The resulting base coins are
 // returned.
 //
+// NOTE: The undelegation (bond refund) amount may exceed the delegated vesting
+// (bond) amount due to the way undelegation truncates the bond refund, which
+// increases the validator's exchange rate (tokens/shares) slightly.
+//
 // CONTRACT: The account's coins and undelegation coins must be sorted.
 func (bva *BaseVestingAccount) TrackUndelegation(amount sdk.Coins) {
 	for _, coin := range amount {
@@ -299,7 +303,7 @@ func (bva *BaseVestingAccount) TrackUndelegation(amount sdk.Coins) {
 
 		// compute x and y per the specification, where:
 		// X := min(DF, D)
-		// Y := min(D - X, DV)
+		// Y := min(DV, D - X)
 		x := sdk.MinInt(delegatedFree, coin.Amount)
 		y := sdk.MinInt(delegatedVesting, coin.Amount.Sub(x))