Subscribers (#771)

docs/contracts/v4/concepts/05-subscribers.mdx

@@ -2,6 +2,18 @@
 title: Subscribers
 ---
 
-(TODO: talk abotu liquidity staking / subscribers)
+Subscribers, new in Uniswap v4, allow for liquidity-position owners to opt-in to a contract that receives _notifcations_.
+The new design is intended to support _liquidity mining_, additional rewards given to in-range liquidity providers. Through notification logic, position owners do not need
+to risk their liquidity position and its underlying assets. In Uniswap v3, _liquidity mining_ was supported by fully transferring the 
+liquidity position to an external contract; this old design would give the external contract full ownership and control of the liquidity position.
+
+When a position owner _subscribes_ to a contract, the contract will receive notifcations when:
+
+* The position is initially subscribed
+
+* The position increases or decreases its liquidity
+
+* The position is transferred
+
+* The position is unsubscribed
 
-(TODO: be sure to emphasize that subscribers dont have access to the capital)

docs/contracts/v4/guides/05-subscriber.mdx

@@ -2,8 +2,46 @@
 title: Subscriber
 ---
 
-(TODO: explain ISubscriber)
+# Context
 
-(TODO: unsubscribe gas limit)
+For developers looking to support custom _liquidity mining_, subscriber contracts receive notifications about a position.
+Rewards can be issued proportional to the liquidity's fee revenue, without the need of custodying the position.
 
-(TODO: explain how LP tokens need to subscribe)
+---
+
+# Guide
+
+## 1. Inherit `ISubscriber`
+
+Please see [`ISubscriber`](https://github.com/Uniswap/v4-periphery/blob/main/src/interfaces/ISubscriber.sol) for the interface definition
+
+```solidity
+import {ISubscriber} from "v4-periphery/src/interfaces/ISubscriber.sol";
+
+contract MySubscriber is ISubscriber {
+    // Implement the ISubscriber interface
+}
+```
+
+Developers should implement each function, and do proper accounting for rewards -- rewards should be proportional
+to a position's liquidity or fee-revenue.
+
+## 2. A note on `unsubscribe()`
+
+Unsubscribe has a gas limit to prevent griefing. The value is determined at deployment, and is readable via `unsubscribeGasLimit()` on `PositionManager`
+
+If `notifyUnsubscribe()` reverts, the position will still successfully unsubscribe.
+
+## 3. Opt-in to a subscriber contract
+
+To opt-in to a subscriber contract, call `subscribe()` on the `PositionManager` contract.
+
+```solidity
+import {IPositionManager} from "v4-periphery/src/interfaces/IPositionManager.sol";
+
+IPositionManager posm = IPositionManager(<address>);
+ISubscriber mySubscriber = ISubscriber(<address>);
+
+bytes memory optionalData = ...;
+posm.subscribe(tokenId, mySubscriber, optionalData);
+```