Skip to content

Commit b90913b

Browse files
oveddanclaude
oveddan
and
claude
authored
update docs to reflect new fees (#1394)
* format changelogs * Improve coins changelog formatting and update rewards documentation - Enhanced coins changelog with clear before/after fee structure tables - Updated rewards documentation to reflect unified 2.2.0 fee structure - Added comparison tables showing pre-2.2.0 vs current reward distribution - Updated terminology from "Create Referral" to "Platform Referral" throughout - Consolidated reward information to single source of truth in rewards.mdx - Removed duplicate and outdated percentage information from hook.mdx, earning-referral-rewards.mdx, and architecture.mdx - Added changelog management documentation to CLAUDE.md 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <[email protected]> * Add clarification about fee structure migration for existing coins - Added warning callout explaining that existing coins keep original fee structure - Clarified that migration to 2.2.0+ hooks adopts new unified fee structure - Added reference to liquidity migration documentation - Ensures users understand fee changes only apply after voluntary migration 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <[email protected]> --------- Co-authored-by: Claude <[email protected]>
1 parent 7aa98c7 commit b90913b

File tree

7 files changed

+140
-122
lines changed

7 files changed

+140
-122
lines changed

‎CLAUDE.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -268,6 +268,33 @@ Before working with the documentation, build the packages that are imported:
268268
pnpm dev
269269
```
270270

271+
### Changelog Management
272+
273+
**IMPORTANT**: Never directly edit changelog files in the `docs/pages/changelogs/` directory. These files are automatically generated.
274+
275+
**Changelog Source and Generation:**
276+
277+
- **Source files**: Individual package `CHANGELOG.md` files (e.g., `packages/coins/CHANGELOG.md`)
278+
- **Generated files**: Documentation changelog files (e.g., `docs/pages/changelogs/coins.mdx`)
279+
- **Generation script**: `docs/scripts/copy-changelogs.ts`
280+
281+
**The generation script automatically:**
282+
- Copies changelog content from package directories to docs
283+
- Removes the first line (package title)
284+
- Adds proper documentation titles (e.g., "Coins Changelog")
285+
- Converts commit hashes to GitHub links
286+
- Processes multiple package changelogs (coins, coins-sdk, protocol-deployments, etc.)
287+
288+
**Automatic Updates:**
289+
- Changelogs are automatically copied to docs during the version update process
290+
- When `pnpm update-version` runs, it automatically calls `pnpm docs:copy-changelogs`
291+
- This ensures documentation changelogs stay in sync with package changelogs
292+
293+
**Manual Updates (if needed):**
294+
1. Edit the source `CHANGELOG.md` file in the relevant package directory
295+
2. Run `pnpm docs:copy-changelogs` from root directory to manually sync
296+
3. The documentation changelog will be updated
297+
271298
### Common Build Issues
272299

273300
#### Missing TypeScript Dependencies

‎docs/pages/changelogs/coins.mdx‎

Lines changed: 24 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -17,42 +17,34 @@
1717

1818
- [adf98059](https://github.com/ourzora/zora-protocol/commit/adf98059): Adds platform referral and trade referral functionality to creator coins, and unifies the fee structure between content and creator coins with a simplified 1% total fee.
1919

20-
**New Features:**
20+
## New Features:
2121

2222
- Platform referral and trade referral functionality for creator coins (previously only supported on content coins)
2323
- Unified fee structure: Both content and creator coins use identical 1% fee distribution
2424

25-
**Fee Structure Changes:**
26-
27-
**Before (Content Coins - 3% total fee):**
28-
| Recipient | % of Market Rewards | % of Total Fees |
29-
| --------------- | ------------------- | --------------- |
30-
| Creator | 50% | 33.33% |
31-
| Create Referral | 15% | 10% |
32-
| Trade Referral | 15% | 10% |
33-
| Doppler | 5% | 3.33% |
34-
| Protocol | 15% | 10% |
35-
| --------------- | ------------------- | --------------- |
36-
| LP Rewards | - | 33.33% |
37-
38-
**Before (Creator Coins - 3% total fee):**
39-
| Recipient | % of Market Rewards | % of Total Fees |
40-
| --------------- | ------------------- | --------------- |
41-
| Creator | 50% | 33.33% |
42-
| Protocol | 50% | 33.33% |
43-
| --------------- | ------------------- | --------------- |
44-
| LP Rewards | - | 33.33% |
45-
46-
**After (All Coins - 1% total fee):**
47-
| Recipient | % of Market Rewards | % of Total Fee |
48-
| ----------------- | ------------------- | -------------- |
49-
| Creator | 62.5% | 50% |
50-
| Platform Referral | 25% | 20% |
51-
| Trade Referral | 5% | 4% |
52-
| Doppler | 1.25% | 1% |
53-
| Protocol | 6.25% | 5% |
54-
| ----------------- | ------------------- | -------------- |
55-
| LP Rewards | - | 20% |
25+
### Fee Changes - Content Coins
26+
27+
| Recipient | Before (3% total fee) | After (1% total fee) |
28+
| ----------------- | --------------------- | -------------------- |
29+
| | % of Fee | % of Fee |
30+
| Creator | 33.33% | 50% |
31+
| Platform Referral | 10% | 20% |
32+
| Trade Referral | 10% | 4% |
33+
| Doppler | 3.33% | 1% |
34+
| Protocol | 10% | 5% |
35+
| LP Rewards | 33.33% | 20% |
36+
37+
### Fee Changes - Creator Coins
38+
39+
| Recipient | Before (3% total fee) | After (1% total fee) |
40+
| ----------------- | --------------------- | -------------------- |
41+
| | % of Fee | % of Fee |
42+
| Creator | 33.33% | 50% |
43+
| Platform Referral | - | 20% |
44+
| Trade Referral | - | 4% |
45+
| Doppler | - | 1% |
46+
| Protocol | 33.33% | 5% |
47+
| LP Rewards | 33.33% | 20% |
5648

5749
**Implementation Changes:**
5850

‎docs/pages/coins/contracts/architecture.mdx‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -139,12 +139,12 @@ The protocol uses an inheritance-based hook architecture:
139139

140140
**ContentCoinHook & CreatorCoinHook**
141141
- Inherit from `BaseZoraV4CoinHook` but override reward distribution
142-
- ContentCoinHook: Distributes rewards to create referral, trade referral, creator, protocol, and Doppler
143-
- CreatorCoinHook: Distributes rewards to creator and protocol only
142+
- ContentCoinHook: Distributes rewards to platform referral, trade referral, creator, protocol, and Doppler
143+
- CreatorCoinHook: Uses the same unified reward structure as ContentCoinHook (as of v2.2.0)
144144

145145
Core shared functionality:
146146
- Collects trading fees from liquidity positions
147-
- Splits fees between LP rewards (33.33%) and market rewards (66.67%)
147+
- Splits fees between LP rewards and market rewards
148148
- Converts fees to backing currency via multi-hop swaps
149149
- Distributes rewards based on coin-specific methodology
150150

‎docs/pages/coins/contracts/earning-referral-rewards.mdx‎

Lines changed: 8 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ For the easiest implementation, use the Zora SDK:
1212

1313
There are two types of referral rewards available to developers:
1414

15-
### Create Referral Rewards
15+
### Platform Referral Rewards
1616
- **Set once** during coin creation
1717
- **Earns from all future trades** for the coin's entire lifespan
1818
- **Sticky** - permanently associated with the coin
@@ -24,24 +24,18 @@ There are two types of referral rewards available to developers:
2424

2525
### Reward Percentages
2626

27-
The reward distribution varies by coin type:
27+
**For detailed reward percentages and distribution breakdown, see [Coin Rewards](/coins/contracts/rewards).**
2828

29-
#### Content Coins - Developer Earnings from Swaps
30-
| Recipient | % of Market Rewards | % of Total Fees |
31-
| ----------------- | ------------------- | --------------- |
32-
| **Create Referral** | **15%** | **10%** |
33-
| **Trade Referral** | **15%** | **10%** |
34-
| Creator | 50% | 33.33% |
35-
| Protocol | 15% | 10% |
36-
| Doppler | 5% | 3.33% |
29+
Both Content Coins and Creator Coins now offer the same referral reward structure (as of version 2.2.0):
3730

38-
#### Creator Coins - No Developer Rewards Available
31+
- **Platform Referral**: 20% of total fees (25% of market rewards)
32+
- **Trade Referral**: 4% of total fees (5% of market rewards)
3933

40-
**Creator Coins do not offer referral rewards to developers.**
34+
This unified structure means developers can earn referral rewards from **both coin types**.
4135

4236
## Technical Implementation
4337

44-
### Create Referral Setup
38+
### Platform Referral Setup
4539

4640
Set the `platformReferrer` parameter when creating coins to earn from all future trades. This address is permanently set for the coin's entire lifespan:
4741

@@ -54,7 +48,7 @@ address coin = factory.deploy(
5448
name,
5549
symbol,
5650
poolConfig,
57-
YOUR_PLATFORM_ADDRESS, // 🎯 This address earns create referral rewards
51+
YOUR_PLATFORM_ADDRESS, // 🎯 This address earns platform referral rewards
5852
postDeployHook,
5953
postDeployHookData,
6054
coinSalt

‎docs/pages/coins/contracts/hook.mdx‎

Lines changed: 10 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -107,28 +107,16 @@ On every swap, the hooks automatically:
107107

108108
## Reward Distribution
109109

110-
The hooks automatically implement different reward distribution logic for different coin types:
110+
The hooks automatically implement different reward distribution logic for different coin types.
111111

112-
### Content Coins
112+
**For detailed reward percentages and distribution breakdown, see [Coin Rewards](/coins/contracts/rewards).**
113113

114-
**Total Fee Split**: 33.33% reminted as LP rewards, 66.67% distributed as market rewards
114+
### Key Differences
115115

116-
**Market Rewards Distribution**:
117-
- **Creator**: 50% (5000 BPS)
118-
- **Create Referral**: 15% (1500 BPS)
119-
- **Trade Referral**: 15% (1500 BPS)
120-
- **Doppler**: 5% (500 BPS)
121-
- **Protocol**: ~15% (remaining)
116+
- **Content Coins**: Support platform referral, trade referral, and Doppler rewards in addition to creator and protocol rewards
117+
- **Creator Coins**: Unified structure with the same reward distribution as Content Coins (as of version 2.2.0)
122118

123-
### Creator Coins
124-
125-
**Total Fee Split**: 33.33% reminted as LP rewards, 66.67% distributed as market rewards
126-
127-
**Market Rewards Distribution**:
128-
- **Creator**: 50% (5000 BPS)
129-
- **Protocol**: 50% (remaining)
130-
131-
*Note: Creator Coins do not have referral or Doppler rewards*
119+
**Fee Split**: A portion of collected fees is reminted as LP rewards to maintain liquidity, while the remainder is distributed as market rewards to stakeholders.
132120

133121
## Multi-Hop Reward Swapping
134122

@@ -227,10 +215,10 @@ Emitted when market rewards are distributed from collected fees, showing exact a
227215
- **coin**: The coin contract that generated the rewards
228216
- **currency**: The currency in which rewards are paid out
229217
- **payoutRecipient**: The creator's reward recipient address
230-
- **platformReferrer**: Address receiving platform referral rewards (Content Coins only)
231-
- **tradeReferrer**: Address receiving trade referral rewards (Content Coins only)
218+
- **platformReferrer**: Address receiving platform referral rewards
219+
- **tradeReferrer**: Address receiving trade referral rewards
232220
- **protocolRewardRecipient**: Protocol treasury address
233-
- **dopplerRecipient**: Doppler rewards recipient (Content Coins only)
221+
- **dopplerRecipient**: Doppler rewards recipient
234222
- **marketRewards**: Detailed breakdown of reward amounts for each recipient
235223

236224
### LpReward Event
@@ -252,5 +240,5 @@ Emitted when liquidity provider rewards are reminted back into the pool:
252240
- **tick**: The current pool tick when the reward was reminted
253241
- **liquidity**: The amount of liquidity reminted back into the pool
254242

255-
This event tracks the 33.33% portion of collected fees that are automatically reminted as liquidity rather than distributed as market rewards.
243+
This event tracks the portion of collected fees that are automatically reminted as liquidity rather than distributed as market rewards.
256244

‎docs/pages/coins/contracts/rewards.mdx‎

Lines changed: 44 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -48,30 +48,55 @@ These positions are essentially **locked and burned** - they don't earn future f
4848

4949
### Market Reward Distribution
5050

51-
The remaining 66.67% of collected fees becomes "market rewards" and is distributed differently based on coin type.
51+
The remaining portion of collected fees becomes "market rewards" and is distributed to stakeholders.
5252

53-
### V4 Market Reward Distribution
53+
### V4 Market Reward Distribution (Current - Since 2.2.0)
5454

55-
The market rewards (66.67% of total fees) are distributed differently based on coin type:
55+
<Callout type="info">
56+
As of version 2.2.0, the fee structure has been unified with a total fee of 1% on pools (was 3% previously) and consistent distribution across both coin types.
57+
All coins with hooks on version 2.2.0 or higher use the unified fee structure.
58+
</Callout>
59+
60+
<Callout type="warning">
61+
**Existing Coins**: Coins deployed before version 2.2.0 continue to use their original fee structure unless the coin owner migrates their liquidity to a 2.2.0+ hook. Migration to newer hooks adopts the new unified fee structure automatically.
62+
63+
For information on liquidity migration, see [Liquidity Migration](/coins/contracts/liquidity-migration).
64+
</Callout>
65+
66+
#### Content Coins & Creator Coins (1% total fee on pools)
67+
| Recipient | % of Market Rewards | % of Total Fees |
68+
| ----------------- | ------------------- | --------------- |
69+
| Creator | 62.5% | 50% |
70+
| Platform Referral | 25% | 20% |
71+
| Trade Referral | 5% | 4% |
72+
| Doppler | 1.25% | 1% |
73+
| Protocol | 6.25% | 5% |
74+
| ----------------- | ------------------- | --------------- |
75+
| LP Rewards | - | 20% |
76+
77+
### Fee Structure Comparison (Pre-2.2.0 vs Current)
5678

5779
#### Content Coins
58-
| Recipient | % of Market Rewards | % of Total Fees |
59-
| --------------- | ------------------- | --------------- |
60-
| Creator | 50% | 33.33% |
61-
| Create Referral | 15% | 10% |
62-
| Trade Referral | 15% | 10% |
63-
| Doppler | 5% | 3.33% |
64-
| Protocol | 15% | 10% |
65-
| --------------- | ------------------- | --------------- |
66-
| LP Rewards | - | 33.33% |
80+
| Recipient | Before (Pre-2.2.0) (3% total fee) | After (2.2.0 and later) (1% total fee) |
81+
| ----------------- | --------------------- | -------------------- |
82+
| | % of Fee | % of Fee |
83+
| Creator | 33.33% | 50% |
84+
| Platform Referral | 10% | 20% |
85+
| Trade Referral | 10% | 4% |
86+
| Doppler | 3.33% | 1% |
87+
| Protocol | 10% | 5% |
88+
| LP Rewards | 33.33% | 20% |
6789

6890
#### Creator Coins
69-
| Recipient | % of Market Rewards | % of Total Fees |
70-
| --------------- | ------------------- | --------------- |
71-
| Creator | 50% | 33.33% |
72-
| Protocol | 50% | 33.33% |
73-
| --------------- | ------------------- | --------------- |
74-
| LP Rewards | - | 33.33% |
91+
| Recipient | Before (3% total fee) | After (1% total fee) |
92+
| ----------------- | --------------------- | -------------------- |
93+
| | % of Fee | % of Fee |
94+
| Creator | 33.33% | 50% |
95+
| Platform Referral | - | 20% |
96+
| Trade Referral | - | 4% |
97+
| Doppler | - | 1% |
98+
| Protocol | 33.33% | 5% |
99+
| LP Rewards | 33.33% | 20% |
75100

76101
### Multi-Hop Currency Conversion
77102

@@ -110,7 +135,7 @@ Content Coin Trading → Fees Collected → Multi-hop Swap → All Recipients Re
110135

111136
**Trade Referral**: The platform or address that referred a specific trade/swap of a coin. In V4, this is passed through hook data and can trigger referral rewards.
112137

113-
**Create Referral**: The platform that referred the creator to deploy the coin. This is set at coin creation time and earns a percentage of all trading fees.
138+
**Platform Referral**: The platform that referred the creator to deploy the coin. This is set at coin creation time and earns a percentage of all trading fees. (Previously called "Create Referral" in versions prior to 2.2.0)
114139

115140
**Creator/Payout Recipient**: The address designated to receive creator rewards from trading activity. This can be updated by coin owners.
116141

‎packages/coins/CHANGELOG.md‎

Lines changed: 24 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -16,42 +16,34 @@
1616

1717
- adf98059: Adds platform referral and trade referral functionality to creator coins, and unifies the fee structure between content and creator coins with a simplified 1% total fee.
1818

19-
**New Features:**
19+
## New Features:
2020

2121
- Platform referral and trade referral functionality for creator coins (previously only supported on content coins)
2222
- Unified fee structure: Both content and creator coins use identical 1% fee distribution
2323

24-
**Fee Structure Changes:**
25-
26-
**Before (Content Coins - 3% total fee):**
27-
| Recipient | % of Market Rewards | % of Total Fees |
28-
| --------------- | ------------------- | --------------- |
29-
| Creator | 50% | 33.33% |
30-
| Create Referral | 15% | 10% |
31-
| Trade Referral | 15% | 10% |
32-
| Doppler | 5% | 3.33% |
33-
| Protocol | 15% | 10% |
34-
| --------------- | ------------------- | --------------- |
35-
| LP Rewards | - | 33.33% |
36-
37-
**Before (Creator Coins - 3% total fee):**
38-
| Recipient | % of Market Rewards | % of Total Fees |
39-
| --------------- | ------------------- | --------------- |
40-
| Creator | 50% | 33.33% |
41-
| Protocol | 50% | 33.33% |
42-
| --------------- | ------------------- | --------------- |
43-
| LP Rewards | - | 33.33% |
44-
45-
**After (All Coins - 1% total fee):**
46-
| Recipient | % of Market Rewards | % of Total Fee |
47-
| ----------------- | ------------------- | -------------- |
48-
| Creator | 62.5% | 50% |
49-
| Platform Referral | 25% | 20% |
50-
| Trade Referral | 5% | 4% |
51-
| Doppler | 1.25% | 1% |
52-
| Protocol | 6.25% | 5% |
53-
| ----------------- | ------------------- | -------------- |
54-
| LP Rewards | - | 20% |
24+
### Fee Changes - Content Coins
25+
26+
| Recipient | Before (3% total fee) | After (1% total fee) |
27+
| ----------------- | --------------------- | -------------------- |
28+
| | % of Fee | % of Fee |
29+
| Creator | 33.33% | 50% |
30+
| Platform Referral | 10% | 20% |
31+
| Trade Referral | 10% | 4% |
32+
| Doppler | 3.33% | 1% |
33+
| Protocol | 10% | 5% |
34+
| LP Rewards | 33.33% | 20% |
35+
36+
### Fee Changes - Creator Coins
37+
38+
| Recipient | Before (3% total fee) | After (1% total fee) |
39+
| ----------------- | --------------------- | -------------------- |
40+
| | % of Fee | % of Fee |
41+
| Creator | 33.33% | 50% |
42+
| Platform Referral | - | 20% |
43+
| Trade Referral | - | 4% |
44+
| Doppler | - | 1% |
45+
| Protocol | 33.33% | 5% |
46+
| LP Rewards | 33.33% | 20% |
5547

5648
**Implementation Changes:**
5749

0 commit comments

Comments
 (0)