Increase liquidity guide

docs/contracts/v4/guides/02-manage-liquidity/02-increase-liquidity.mdx

@@ -1,3 +1,134 @@
 ---
 title: Increase Liquidity
----
+---
+
+### Context
+
+The straightforward way to increase a position's liquidity is
+to simply send the required tokens. However, as a little reminder,
+earned fees act like a credit, allowing liquidity providers to reduce
+the total amount of tokens needed for transfer or to convert fees
+into liquidity directly.
+
+### Setup
+
+See the [setup guide](./00-setup-liquidity.mdx)
+
+# Guide
+
+Below is a step-by-step guide for increasing a position's liquidity, in *Solidity*.
+
+### 1. Import and define `IPositionManager`
+
+```solidity
+import {IPositionManager} from "v4-periphery/src/interfaces/IPositionManager.sol";
+
+// inside a contract, test, or foundry script:
+IPositionManager posm = IPositionManager(<address>);
+```
+
+### 2. Encode Actions
+
+To increase a position's liquidity, the first action must be:
+
+* _increase_ operation - signals the intent of adding liquidity to a position.
+
+If increasing the liquidity requires transfers of both tokens:
+
+* _settle pair_ - pays the required token amounts for increasing liquidity.
+
+Otherwise, one of the following actions needs to be added for each token:
+
+* _close currency_ - determines if a currency should be settled or taken.
+* _clear or take_ - given a specified threshold, forfeit remainder tokens if
+below or retrieve if above.
+
+```solidity
+import {Actions} from "v4-periphery/src/libraries/Actions.sol";
+```
+
+If both tokens need to be sent:
+```solidity
+bytes memory actions = abi.encodePacked(Actions.INCREASE_LIQUIDITY, Actions.SETTLE_PAIR);
+```
+
+If converting fees to liquidity, collecting dust:
+```solidity
+bytes memory actions = abi.encodePacked(Actions.INCREASE_LIQUIDITY, Actions.CLOSE_CURRENCY, Actions.CLOSE_CURRENCY);
+```
+
+If converting fees to liquidity, forfeiting dust:
+```solidity
+bytes memory actions = abi.encodePacked(Actions.INCREASE_LIQUIDITY, Actions.CLEAR_OR_TAKE, Actions.CLEAR_OR_TAKE);
+```
+
+### 3. Encoded Parameters
+
+When settling pair:
+
+```solidity
+bytes[] memory params = new bytes[](2);
+```
+
+Otherwise:
+
+```solidity
+bytes[] memory params = new bytes[](3);
+```
+
+The `INCREASE_LIQUIDITY` action requires the following parameters:
+
+| Parameter    | Type      | Description                                                                   |
+|--------------|-----------|-------------------------------------------------------------------------------|
+| `tokenId`    | _uint256_ | position identifier                                                           |
+| `liquidity`  | _uint256_ | the amount of liquidity to add                                                |
+| `amount0Max` | _uint128_ | the maximum amount of currency0 liquidity msg.sender is willing to pay        |
+| `amount1Max` | _uint128_ | the maximum amount of currency1 liquidity msg.sender is willing to pay        |
+| `hookData`   | _bytes_   | arbitrary data that will be forwarded to hook functions                       |
+
+```solidity
+params[0] = abi.encode(tokenId, liquidity, amount0Max, amount1Max, hookData);
+```
+
+The `SETTLE_PAIR` action requires the following parameters:
+
+* `currency0` - _Currency_, one of the tokens to be paid by msg.sender
+* `currency1` - _Currency_, the other token to be paid by msg.sender
+
+In the above case, the parameter encoding is:
+
+```solidity
+params[1] = abi.encode(currency0, currency1);
+``` 
+
+The `CLOSE_CURRENCY` action requires only one `currency` parameter
+and the encoding is:
+
+```solidity
+params[1] = abi.encode(currency0)
+params[2] = abi.encode(currency1)
+```
+
+The `CLEAR_OR_TAKE` action requires one `currency` and:
+
+* `amountMax` - _uint256_, the maximum threshold for which to concede dust,
+otherwise taking the dust. 
+
+In this case, the parameter encoding is:
+
+```solidity
+params[1] = abi.encode(currency0, amount0Max);
+params[2] = abi.encode(currency1, amount1Max);
+```
+
+### 4. Submit Call
+
+The entrypoint for all liquidity operations is `modifyLiquidities()`.
+
+```solidity
+uint256 deadline = block.timestamp + 60;
+posm.modifyLiquidities(
+    abi.encode(actions, params),
+    deadline
+);
+```