Add transient state library reference description with mdx formatting (…

…#757)

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

@@ -0,0 +1,132 @@
+---
+title: Transient State Library
+---
+
+The `TransientStateLibrary` is a crucial component of Uniswap V4, providing utility functions for managing transient state in the PoolManager contract. This library handles operations related to reserves, delta counts, and locking state, which are essential for the efficient and secure operation of the Uniswap V4 protocol.
+
+# Key Concepts
+
+## Transient Storage
+
+Uniswap V4 uses transient storage to optimize gas costs and improve efficiency. Transient storage, introduced in EIP-1153, is a way to store data that is only needed for the duration of a transaction, without persisting it to the blockchain's state trie. This is achieved using the `TLOAD` and `TSTORE` opcodes.
+
+Key points about transient storage in Uniswap V4:
+
+1. **PoolManager and** `exttload`: Instead of exposing custom getters for transient storage, the PoolManager implements an `exttload` (external tload) function. This function serves as an external wrapper for the `TLOAD` opcode, providing a standardized interface for accessing transient storage.
+2. **TransientStateLibrary's Role:** The `TransientStateLibrary` acts as an intermediary, making calls to the PoolManager's `exttload` function to access transient storage. This abstraction simplifies the interaction with transient storage for other parts of the Uniswap V4 ecosystem.
+3. **Standardization:** By channeling all transient storage access through the PoolManager's `exttload` function, Uniswap V4 ensures a consistent and controlled approach to managing transient data across the protocol.
+
+Common operations that involve transient state include:
+
+- Checking reserves (`getReserves`)
+- Verifying currency deltas (`currencyDelta`)
+- Syncing currency states (`sync`)
+- Settling currency balances (`settle`)
+
+This architecture allows Uniswap V4 to benefit from the gas efficiency of transient storage while maintaining a clean and standardized interface for interacting with this temporary data.
+
+# Functions
+
+## getReserves
+
+```solidity
+function getReserves(IPoolManager manager, Currency currency) internal view returns (uint256)
+```
+
+Retrieves the reserves of a specific currency from the PoolManager's transient storage.
+
+| Param Name | Type         | Description                                      |
+|------------|--------------|--------------------------------------------------|
+| manager    | IPoolManager | The PoolManager contract instance                 |
+| currency   | Currency     | The currency for which to fetch reserves          |
+
+**Returns:**
+- `uint256`: The amount of reserves for the specified currency
+
+**Notes:**
+- Returns `0` if the reserves are not synced
+- Returns `type(uint256).max` if the reserves are synced but the value is `0`
+
+## getNonzeroDeltaCount
+
+```solidity
+function getNonzeroDeltaCount(IPoolManager manager) internal view returns (uint256)
+```
+
+Retrieves the count of nonzero deltas that must be zeroed out before the contract can be locked.
+
+| Param Name | Type         | Description                          |
+|------------|--------------|--------------------------------------|
+| manager    | IPoolManager | The PoolManager contract instance    |
+
+**Returns:**
+
+- `uint256`: The number of nonzero deltas
+
+## currencyDelta
+
+```solidity
+function currencyDelta(IPoolManager manager, address caller_, Currency currency) internal view returns (int256)
+```
+
+Fetches the current delta for a specific caller and currency from the PoolManager's transient storage.
+
+| Param Name | Type         | Description                                      |
+|------------|--------------|--------------------------------------------------|
+| manager    | IPoolManager | The PoolManager contract instance                 |
+| caller_    | address      | The address of the caller                         |
+| currency   | Currency     | The currency for which to lookup the delta        |
+
+**Returns:**
+
+- `int256`: The delta value for the specified caller and currency
+
+**Notes:**
+
+- A **negative** delta indicates an amount that must be **paid or settled** by the caller. In other words, a negative delta means the caller owes that amount and needs to pay or settle it.
+- A **positive** delta indicates an amount that is owed to the caller. This delta amount must be **taken or claimed** by the caller.
+
+## isUnlocked
+
+```solidity
+function isUnlocked(IPoolManager manager) internal view returns (bool)
+```
+
+Checks if the PoolManager contract is currently unlocked.
+
+| Param Name | Type         | Description                          |
+|------------|--------------|--------------------------------------|
+| manager    | IPoolManager | The PoolManager contract instance    |
+
+**Returns:**
+
+- `bool`: `true` if the contract is unlocked, `false` otherwise
+
+# Usage and Importance
+
+The `TransientStateLibrary` plays a critical role in Uniswap V4's operation:
+
+1. **Gas Optimization:** By using transient storage, the library helps reduce gas costs associated with state changes that are only relevant within a single transaction. This is particularly important for multi-hop transactions, where internal net balances (deltas) are updated instead of making token transfers for each hop.
+2. **Security:** The library provides functions to check the lock state and manage deltas, which are crucial for maintaining the integrity of the protocol during operations. The use of transient storage also allows for more efficient implementation of security measures compared to V3's reentrancy guards.
+3. **Flexibility:** The library allows for efficient management of currency-specific data, such as reserves and deltas, which is essential for Uniswap V4's multi-currency pools.
+4. **Encapsulation:** By centralizing these utility functions in a library, the code promotes better organization and reusability across the Uniswap V4 codebase.
+
+# Integration with PoolManager
+
+The `TransientStateLibrary` is designed to work closely with the `PoolManager` contract. The `TransientStateLibrary` can be easily integrated with the `PoolManager` contract using the `using` keyword for syntactic sugar. This allows you to call the library functions as if they were methods of the `IPoolManager` instance. Here's an example:
+
+```solidity
+import {IPoolManager} from "v4-core/src/interfaces/IPoolManager.sol";
+import {TransientStateLibrary} from "v4-core/src/libraries/TransientStateLibrary.sol";
+
+contract Example {
+    using TransientStateLibrary for IPoolManager;
+
+    function example() external {
+        int256 delta = manager.currencyDelta(address(this), currency);
+        // Use the delta value...
+    }
+}
+```
+
+In this example, the `using TransientStateLibrary for IPoolManager;` statement allows you to call `currencyDelta` directly on the `manager` instance, making your code more readable and concise.