refactor: flip the sign for balanceDelta (#49)

* refactor: flip the sign for balanceDelta

* chore: remove unnecessary console2.log

* chore: docs

* docs: flips omitted comments

.forge-snapshots/BinHookTest#testBurnSucceedsWithHook.snap

@@ -1 +1 @@
-182049
+181729

.forge-snapshots/BinHookTest#testDonateSucceedsWithHook.snap

@@ -1 +1 @@
-185296
+185616

.forge-snapshots/BinHookTest#testMintSucceedsWithHook.snap

@@ -1 +1 @@
-331250
+331570

.forge-snapshots/BinPoolManagerTest#testBurnNativeCurrency.snap

@@ -1 +1 @@
-138533
+138277

.forge-snapshots/BinPoolManagerTest#testGasBurnHalfBin.snap

@@ -1 +1 @@
-148635
+148315

.forge-snapshots/BinPoolManagerTest#testGasBurnNineBins.snap

@@ -1 +1 @@
-296486
+296230

.forge-snapshots/BinPoolManagerTest#testGasBurnOneBin.snap

@@ -1 +1 @@
-131743
+131487

.forge-snapshots/BinPoolManagerTest#testGasDonate.snap

@@ -1 +1 @@
-120042
+120359

.forge-snapshots/BinPoolManagerTest#testGasMintNneBins-1.snap

@@ -1 +1 @@
-977200
+977517

.forge-snapshots/BinPoolManagerTest#testGasMintNneBins-2.snap

@@ -1 +1 @@
-339390
+339707

.forge-snapshots/BinPoolManagerTest#testGasMintOneBin-1.snap

@@ -1 +1 @@
-342867
+343184

.forge-snapshots/BinPoolManagerTest#testGasMintOneBin-2.snap

@@ -1 +1 @@
-145810
+146127

.forge-snapshots/BinPoolManagerTest#testMintNativeCurrency.snap

@@ -1 +1 @@
-309383
+309700

.forge-snapshots/CLPoolManagerTest#addLiquidity_fromEmpty.snap

@@ -1 +1 @@
-362972
+362978

.forge-snapshots/CLPoolManagerTest#addLiquidity_fromNonEmpty.snap

@@ -1 +1 @@
-178140
+178146

.forge-snapshots/CLPoolManagerTest#addLiquidity_nativeToken.snap

@@ -1 +1 @@
-248255
+248182

.forge-snapshots/CLPoolManagerTest#donateBothTokens.snap

@@ -1 +1 @@
-170425
+170745

.forge-snapshots/CLPoolManagerTest#gasDonateOneToken.snap

@@ -1 +1 @@
-114348
+114589

.forge-snapshots/CLPoolManagerTest#removeLiquidity_toNonEmpty.snap

@@ -1 +1 @@
-124482
+124243

.forge-snapshots/CLPoolManagerTest#swap_againstLiquidity.snap

@@ -1 +1 @@
-141710
+141453

.forge-snapshots/CLPoolManagerTest#swap_leaveSurplusTokenInVault.snap

@@ -1 +1 @@
-175389
+174968

.forge-snapshots/CLPoolManagerTest#swap_runOutOfLiquidity.snap

@@ -1 +1 @@
-25094185
+161331

.forge-snapshots/CLPoolManagerTest#swap_simple.snap

@@ -1 +1 @@
-79576
+79416

.forge-snapshots/CLPoolManagerTest#swap_useSurplusTokenAsInput.snap

@@ -1 +1 @@
-153925
+153614

.forge-snapshots/CLPoolManagerTest#swap_withHooks.snap

@@ -1 +1 @@
-96383
+96223

.forge-snapshots/CLPoolManagerTest#swap_withNative.snap

@@ -1 +1 @@
-79579
+79419

.forge-snapshots/CLPoolManagerTest#testFuzzUpdateDynamicLPFee.snap

@@ -1 +1 @@
-32291
+29467

.forge-snapshots/SwapMathTest#SwapOneForZeroExactInCapped.snap

@@ -1 +1 @@
-2237
+2239

.forge-snapshots/SwapMathTest#SwapOneForZeroExactInPartial.snap

@@ -1 +1 @@
-3022
+3029

.forge-snapshots/SwapMathTest#SwapOneForZeroExactOutCapped.snap

@@ -1 +1 @@
-1994
+1981

.forge-snapshots/SwapMathTest#SwapOneForZeroExactOutPartial.snap

@@ -1 +1 @@
-3022
+3029

.forge-snapshots/SwapMathTest#SwapZeroForOneExactInCapped.snap

@@ -1 +1 @@
-2227
+2229

.forge-snapshots/SwapMathTest#SwapZeroForOneExactInPartial.snap

@@ -1 +1 @@
-3175
+3182

.forge-snapshots/SwapMathTest#SwapZeroForOneExactOutCapped.snap

@@ -1 +1 @@
-1984
+1971

.forge-snapshots/SwapMathTest#SwapZeroForOneExactOutPartial.snap

@@ -1 +1 @@
-3175
+3182

.forge-snapshots/VaultTest#Vault.snap

@@ -1 +1 @@
-7136
+7171

.forge-snapshots/VaultTest#lockSettledWhenAddLiquidity.snap

@@ -1 +1 @@
-81625
+81624

src/Vault.sol

@@ -102,13 +102,13 @@ contract Vault is IVault, VaultToken, Ownable {
 
     /// @inheritdoc IVault
     function take(Currency currency, address to, uint256 amount) external override isLocked {
-        SettlementGuard.accountDelta(msg.sender, currency, amount.toInt128());
+        SettlementGuard.accountDelta(msg.sender, currency, -(amount.toInt128()));
         currency.transfer(to, amount);
     }
 
     /// @inheritdoc IVault
     function mint(address to, Currency currency, uint256 amount) external override isLocked {
-        SettlementGuard.accountDelta(msg.sender, currency, amount.toInt128());
+        SettlementGuard.accountDelta(msg.sender, currency, -(amount.toInt128()));
         _mint(to, currency, amount);
     }
 
@@ -128,22 +128,21 @@ contract Vault is IVault, VaultToken, Ownable {
             paid = msg.value;
         }
 
-        // subtraction must be safe
-        SettlementGuard.accountDelta(msg.sender, currency, -(paid.toInt128()));
+        SettlementGuard.accountDelta(msg.sender, currency, paid.toInt128());
     }
 
     /// @inheritdoc IVault
     function settleFor(Currency currency, address target, uint256 amount) external isLocked {
         /// @notice settle all outstanding debt if amount is 0
-        /// It will revert if target has negative delta
-        if (amount == 0) amount = SettlementGuard.getCurrencyDelta(target, currency).toUint256();
-        SettlementGuard.accountDelta(msg.sender, currency, amount.toInt128());
-        SettlementGuard.accountDelta(target, currency, -(amount.toInt128()));
+        /// It will revert if target has positive delta
+        if (amount == 0) amount = (-SettlementGuard.getCurrencyDelta(target, currency)).toUint256();
+        SettlementGuard.accountDelta(msg.sender, currency, -(amount.toInt128()));
+        SettlementGuard.accountDelta(target, currency, amount.toInt128());
     }
 
     /// @inheritdoc IVault
     function burn(address from, Currency currency, uint256 amount) external override isLocked {
-        SettlementGuard.accountDelta(msg.sender, currency, -(amount.toInt128()));
+        SettlementGuard.accountDelta(msg.sender, currency, amount.toInt128());
         _burnFrom(from, currency, amount);
     }
 
@@ -162,14 +161,11 @@ contract Vault is IVault, VaultToken, Ownable {
         if (delta == 0) return;
 
         if (delta >= 0) {
-            reservesOfPoolManager[poolManager][currency] += uint128(delta);
+            /// @dev arithmetic underflow make sure trader can't withdraw too much from poolManager
+            reservesOfPoolManager[poolManager][currency] -= uint128(delta);
         } else {
-            /// @dev arithmetic underflow is possible in following two cases:
-            /// 1. delta == type(int128).min
-            /// This occurs when withdrawing amount is too large
-            /// 2. reservesOfPoolManager[poolManager][currency] < delta0
-            /// This occurs when insufficient balance in pool
-            reservesOfPoolManager[poolManager][currency] -= uint128(-delta);
+            /// @dev arithmetic overflow make sure trader won't deposit too much into poolManager
+            reservesOfPoolManager[poolManager][currency] += uint128(-delta);
         }
     }
 }

src/pool-bin/interfaces/IBinHooks.sol

@@ -64,7 +64,7 @@ interface IBinHooks is IHooks {
     /// @param sender The initial msg.sender for the modify position call
     /// @param key The key for the pool
     /// @param params The parameters for adding liquidity
-    /// @param delta The amount owed to the locker (negative) or owed to the pool (positive)
+    /// @param delta The amount owed to the locker (positive) or owed to the pool (negative)
     /// @param hookData Arbitrary data handed into the PoolManager by the liquidty provider to be be passed on to the hook
     /// @return bytes4 The function selector for the hook
     /// @return BalanceDelta The hook's delta in token0 and token1.
@@ -93,7 +93,7 @@ interface IBinHooks is IHooks {
     /// @param sender The initial msg.sender for the modify position call
     /// @param key The key for the pool
     /// @param params The parameters for removing liquidity
-    /// @param delta The amount owed to the locker (negative) or owed to the pool (positive)
+    /// @param delta The amount owed to the locker (positive) or owed to the pool (negative)
     /// @param hookData Arbitrary data handed into the PoolManager by the liquidty provider to be be passed on to the hook
     /// @return bytes4 The function selector for the hook
     /// @return BalanceDelta The hook's delta in token0 and token1.
@@ -126,7 +126,7 @@ interface IBinHooks is IHooks {
     /// @param key The key for the pool
     /// @param swapForY If true, indicate swap X for Y or if false, swap Y for X
     /// @param amountIn Amount of tokenX or tokenY in
-    /// @param delta The amount owed to the locker (negative) or owed to the pool (positive)
+    /// @param delta The amount owed to the locker (positive) or owed to the pool (negtive)
     /// @param hookData Arbitrary data handed into the PoolManager by the swapper to be be passed on to the hook
     /// @return bytes4 The function selector for the hook
     /// @return int128 The hook's delta in unspecified currency

src/pool-bin/interfaces/IBinPoolManager.sol

@@ -154,13 +154,14 @@ interface IBinPoolManager is IProtocolFees, IPoolManager, IExtsload {
     function initialize(PoolKey memory key, uint24 activeId, bytes calldata hookData) external;
 
     /// @notice Add liquidity to a pool
-    /// @return delta BalanceDelta, will be positive indicating how much total amt0 and amt1 liquidity added
+    /// @return delta BalanceDelta, will be negative indicating how much total amt0 and amt1 liquidity added
     /// @return mintArray Liquidity added in which ids, how much amt0, amt1 and how much liquidity added
     function mint(PoolKey memory key, IBinPoolManager.MintParams calldata params, bytes calldata hookData)
         external
         returns (BalanceDelta delta, BinPool.MintArrays memory mintArray);
 
     /// @notice Remove liquidity from a pool
+    /// @return delta BalanceDelta, will be positive indicating how much total amt0 and amt1 liquidity removed
     function burn(PoolKey memory key, IBinPoolManager.BurnParams memory params, bytes calldata hookData)
         external
         returns (BalanceDelta delta);
@@ -171,7 +172,7 @@ interface IBinPoolManager is IProtocolFees, IPoolManager, IExtsload {
         returns (BalanceDelta delta);
 
     /// @notice Donate the given currency amounts to the pool with the given pool key.
-    /// @return delta Positive amt means the caller owes the vault, while negative amt means the vault owes the caller
+    /// @return delta Negative amt means the caller owes the vault, while positive amt means the vault owes the caller
     /// @return binId The donated bin id, which is the current active bin id. if no-op happen, binId will be 0
     function donate(PoolKey memory key, uint128 amount0, uint128 amount1, bytes calldata hookData)
         external

src/pool-bin/libraries/BinHooks.sol

@@ -126,10 +126,10 @@ library BinHooks {
 
             if (hookDeltaSpecified != 0) {
                 /// @dev default overflow check make sure the swap amount is always valid
-                if (hookDeltaSpecified > 0) {
-                    amountToSwap += uint128(hookDeltaSpecified);
-                } else {
+                if (hookDeltaSpecified < 0) {
                     amountToSwap -= uint128(-hookDeltaSpecified);
+                } else {
+                    amountToSwap += uint128(hookDeltaSpecified);
                 }
             }
         }
@@ -163,9 +163,11 @@ library BinHooks {
         hookDeltaUnspecified += beforeSwapDelta.getUnspecifiedDelta();
 
         if (hookDeltaUnspecified != 0 || hookDeltaSpecified != 0) {
+            // the hookDelta is the delta added into amountIn which is in the opposite direction of the balanceDelta
+            // i.e. in a reasonable case, amountIn will basiaclly equal to "-BalanceDelta.amount0()/amount1()"
             hookDelta = swapForY
-                ? toBalanceDelta(hookDeltaSpecified, hookDeltaUnspecified)
-                : toBalanceDelta(hookDeltaUnspecified, hookDeltaSpecified);
+                ? toBalanceDelta(-hookDeltaSpecified, -hookDeltaUnspecified)
+                : toBalanceDelta(-hookDeltaUnspecified, -hookDeltaSpecified);
 
             // the caller has to pay for (or receive) the hook's delta
             swapperDelta = delta - hookDelta;

src/pool-bin/libraries/BinPool.sol

@@ -261,10 +261,10 @@ library BinPool {
 
         if (swapForY) {
             uint128 consumed = amountIn - amountsLeft.decodeX();
-            result = toBalanceDelta(consumed.safeInt128(), -(amountsOut.decodeY().safeInt128()));
+            result = toBalanceDelta(-consumed.safeInt128(), amountsOut.decodeY().safeInt128());
         } else {
             uint128 consumed = amountIn - amountsLeft.decodeY();
-            result = toBalanceDelta(-(amountsOut.decodeX().safeInt128()), consumed.safeInt128());
+            result = toBalanceDelta(amountsOut.decodeX().safeInt128(), -(consumed.safeInt128()));
         }
     }
 
@@ -303,7 +303,9 @@ library BinPool {
         compositionFee = compoFee;
 
         (uint128 x1, uint128 x2) = params.amountIn.sub(amountsLeft).decode();
-        result = toBalanceDelta(x1.safeInt128(), x2.safeInt128());
+
+        // set balanceDelta to negative (so user must settle()) from the vault
+        result = toBalanceDelta(-(x1.safeInt128()), -(x2.safeInt128()));
     }
 
     /// @notice Returns the reserves of a bin
@@ -372,8 +374,7 @@ library BinPool {
             }
         }
 
-        // set amoutsOut to negative (so user can take/mint()) from the vault
-        result = toBalanceDelta(-(amountsOut.decodeX().safeInt128()), -(amountsOut.decodeY().safeInt128()));
+        result = toBalanceDelta(amountsOut.decodeX().safeInt128(), amountsOut.decodeY().safeInt128());
     }
 
     function donate(State storage self, uint16 binStep, uint128 amount0, uint128 amount1)
@@ -391,7 +392,7 @@ library BinPool {
         binReserves.add(amountIn).getLiquidity(price);
 
         self.reserveOfBin[activeId] = binReserves.add(amountIn);
-        result = toBalanceDelta(amount0.safeInt128(), amount1.safeInt128());
+        result = toBalanceDelta(-(amount0.safeInt128()), -(amount1.safeInt128()));
     }
 
     /// @dev Helper function to mint liquidity in each bin in the liquidity configurations

src/pool-cl/interfaces/ICLHooks.sol

@@ -71,6 +71,7 @@ interface ICLHooks is IHooks {
     /// @param sender The initial msg.sender for the add liquidity call
     /// @param key The key for the pool
     /// @param params The parameters for adding liquidity
+    /// @param delta The amount owed to the locker (positive) or owed to the pool (negative)
     /// @param hookData Arbitrary data handed into the PoolManager by the liquidty provider to be be passed on to the hook
     /// @return bytes4 The function selector for the hook
     /// @return BalanceDelta The hook's delta in token0 and token1.
@@ -99,6 +100,7 @@ interface ICLHooks is IHooks {
     /// @param sender The initial msg.sender for the remove liquidity call
     /// @param key The key for the pool
     /// @param params The parameters for removing liquidity
+    /// @param delta The amount owed to the locker (positive) or owed to the pool (negative)
     /// @param hookData Arbitrary data handed into the PoolManager by the liquidty provider to be be passed on to the hook
     /// @return bytes4 The function selector for the hook
     /// @return BalanceDelta The hook's delta in token0 and token1.