add BalanceDelta reference guide with mdx formatting (#763)

docs/contracts/v4/reference/core/BalanceDelta.mdx

@@ -0,0 +1,147 @@
+---
+title: BalanceDelta
+---
+
+`BalanceDelta` is a type used in Uniswap V4 to represent the balance changes of two tokens (token0 and token1). It tightly packs the two values in a single 256 bits. It is designed to efficiently store and manipulate these balance deltas, with the upper 128 bits representing the change in token0 (`amount0`) and the lower 128 bits representing the change in token1 (`amount1`).
+
+# Purpose
+
+The main purpose of `BalanceDelta` is to keep track of the net balance changes in the two tokens of a pool after various operations such as swaps, liquidity modifications, and interactions with hooks. It provides a compact and efficient way to store and update these balance deltas throughout the execution flow of the pool.
+
+In the context of hooks, `BalanceDelta` is used to ensure that the net balance change for each token is zero after the hook's functionality is executed. This is important for maintaining the integrity of the pool's balances and ensuring that the hooks do not introduce any unexpected or unauthorized balance changes.
+
+# Type Definition
+
+```solidity
+type BalanceDelta is int256;
+```
+
+# Using Directives
+
+```solidity
+using {add as +, sub as -, eq as ==, neq as !=} for BalanceDelta global;
+using BalanceDeltaLibrary for BalanceDelta global;
+using SafeCast for int256;
+```
+
+These using directives enable arithmetic operations, equality comparisons, and library functions to be used directly on `BalanceDelta` values.
+
+# Functions
+
+## toBalanceDelta
+
+```solidity
+function toBalanceDelta(int128 amount0, int128 amount1) pure returns (BalanceDelta balanceDelta);
+```
+
+Creates a `BalanceDelta` value from two `int128` values representing `amount0` and `amount1`.
+
+| Param Name | Type    | Description                          |
+|------------|---------|--------------------------------------|
+| amount0    | int128  | The amount for the first token       |
+| amount1    | int128  | The amount for the second token      |
+
+Returns the created `BalanceDelta` value.
+
+## add
+
+```solidity
+function add(BalanceDelta a, BalanceDelta b) pure returns (BalanceDelta);
+```
+
+Adds two `BalanceDelta` values.
+
+| Param Name | Type         | Description                          |
+|------------|--------------|--------------------------------------|
+| a          | BalanceDelta | The first `BalanceDelta` value       |
+| b          | BalanceDelta | The second `BalanceDelta` value      |
+
+Returns the sum of the two `BalanceDelta` values.
+
+## sub
+
+```solidity
+function sub(BalanceDelta a, BalanceDelta b) pure returns (BalanceDelta);
+```
+
+Subtracts one `BalanceDelta` value from another.
+
+| Param Name | Type         | Description                          |
+|------------|--------------|--------------------------------------|
+| a          | BalanceDelta | The first `BalanceDelta` value       |
+| b          | BalanceDelta | The second `BalanceDelta` value      |
+
+Returns the difference of the two `BalanceDelta` values.
+
+## eq
+
+```solidity
+function eq(BalanceDelta a, BalanceDelta b) pure returns (bool);
+```
+
+Checks if two `BalanceDelta` values are equal.
+
+| Param Name | Type         | Description                          |
+|------------|--------------|--------------------------------------|
+| a          | BalanceDelta | The first `BalanceDelta` value       |
+| b          | BalanceDelta | The second `BalanceDelta` value      |
+
+Returns `true` if the values are equal, `false` otherwise.
+
+## neq
+
+```solidity
+function neq(BalanceDelta a, BalanceDelta b) pure returns (bool);
+```
+
+Checks if two `BalanceDelta` values are not equal.
+
+| Param Name | Type         | Description                          |
+|------------|--------------|--------------------------------------|
+| a          | BalanceDelta | The first `BalanceDelta` value       |
+| b          | BalanceDelta | The second `BalanceDelta` value      |
+
+Returns `true` if the values are not equal, `false` otherwise.
+
+# Library Functions
+
+## amount0
+
+```solidity
+function amount0(BalanceDelta balanceDelta) internal pure returns (int128 _amount0);
+```
+
+Extracts the `amount0` value from a `BalanceDelta`.
+
+| Param Name   | Type         | Description                          |
+|--------------|--------------|--------------------------------------|
+| balanceDelta | BalanceDelta | The `BalanceDelta` value             |
+
+Returns the extracted `amount0` value as an `int128`.
+
+## amount1
+
+```solidity
+function amount1(BalanceDelta balanceDelta) internal pure returns (int128 _amount1);
+```
+
+Extracts the `amount1` value from a `BalanceDelta`.
+
+| Param Name   | Type         | Description                          |
+|--------------|--------------|--------------------------------------|
+| balanceDelta | BalanceDelta | The `BalanceDelta` value             |
+
+Returns the extracted `amount1` value as an `int128`.
+
+# Usage in Hooks
+
+When a hook is called during a swap or liquidity modification, it can perform custom logic and interact with the pool's balances. However, to maintain the correctness of the pool's state, the hook must ensure that any balance changes it introduces are properly accounted for and net to zero at the end of its execution.
+The BalanceDelta is forwarded to the `afterSwap` & `afterAddliquidity`, `afterRemoveLiquidity` hooks.  
+
+# Usage in the Pool Library
+
+In the `Pool` library, `BalanceDelta` is used extensively to track balance changes during various operations such as swaps, liquidity modifications, and donations. The library functions `swap`, `modifyLiquidity`, and `donate` all return `BalanceDelta` values representing the net balance changes resulting from these operations.
+
+The `Pool` library uses `BalanceDelta` to efficiently update and manage the pool's balances, ensuring that the net balance changes are accurately accounted for and that the pool remains in a consistent state.
+
+By leveraging the compact representation and efficient arithmetic operations provided by `BalanceDelta`, the `Pool` library can perform complex balance calculations and updates in a gas-optimized manner, reducing the overall cost of executing pool-related operations.