From 5c18f628eafd0a115191c4077c843fc810a02426 Mon Sep 17 00:00:00 2001
From: saucepoint <saucepoint@protonmail.com>
Date: Thu, 19 Sep 2024 00:23:31 +0800
Subject: [PATCH] quick n dirty guide on subscribers

---
 docs/contracts/v4/guides/05-subscriber.mdx | 44 ++++++++++++++++++++--
 1 file changed, 41 insertions(+), 3 deletions(-)

diff --git a/docs/contracts/v4/guides/05-subscriber.mdx b/docs/contracts/v4/guides/05-subscriber.mdx
index 96c2dcba6..3d407797e 100644
--- a/docs/contracts/v4/guides/05-subscriber.mdx
+++ b/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)
\ No newline at end of file
+---
+
+# 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);
+```