From 02c7066873e759bca3467e56a015c3b8d352a4e0 Mon Sep 17 00:00:00 2001
From: Alexandr Kazachenko <shoom3301@gmail.com>
Date: Wed, 19 Jun 2024 22:01:20 +0600
Subject: [PATCH] docs(widget): flexible config for partner fee params (#392)

# Description

Since partner fee can be set for any trade type on any network, we
should provide an option to flexibly configurate the fee.

Now both `bps` and `recipient` have type `FlexibleConfig`.

```typescript
export type PerTradeTypeConfig<T> = Record<TradeType, T>

export type PerNetworkConfig<T> = Record<SupportedChainId, T>

export type FlexibleConfig<T> =
  | T
  | PerNetworkConfig<T>
  | PerTradeTypeConfig<T>
  | PerTradeTypeConfig<PerNetworkConfig<T>>
  | PerNetworkConfig<PerTradeTypeConfig<T>>
```
---
 docs/cow-protocol/tutorials/widget/widget.md | 106 ++++++++++++++++++-
 1 file changed, 104 insertions(+), 2 deletions(-)

diff --git a/docs/cow-protocol/tutorials/widget/widget.md b/docs/cow-protocol/tutorials/widget/widget.md
index f9ac9867..5312765b 100644
--- a/docs/cow-protocol/tutorials/widget/widget.md
+++ b/docs/cow-protocol/tutorials/widget/widget.md
@@ -69,6 +69,109 @@ const params: CowSwapWidgetParams = {
 createCowSwapWidget(widgetContainer, { params })
 ```
 
+### Flexible config
+
+Both `bps` and `recipient` can be set for different chains and different trade types (swap/limit/advanced). 
+
+Bellow you can see the `partnerFee` configuration variations:
+
+```typescript
+import {PartnerFee, SupportedChainId, TradeType} from '@cowprotocol/widget-lib'
+
+// The fee is 1% for all trades on all chains
+const a: PartnerFee = {
+    bps: 100,
+    recipient: '0x0000000000000000000000000000000000000000'
+}
+
+// Different fee per network and per trade type, same recipient for all
+const b: PartnerFee = {
+    bps: {
+        [SupportedChainId.MAINNET]: {
+            [TradeType.SWAP]: 100, [TradeType.LIMIT]: 50, [TradeType.ADVANCED]: 30,
+        },
+        [SupportedChainId.ARBITRUM_ONE]: {
+            [TradeType.SWAP]: 100, [TradeType.LIMIT]: 50, [TradeType.ADVANCED]: 30,
+        },
+        [SupportedChainId.GNOSIS_CHAIN]: {
+            [TradeType.SWAP]: 100, [TradeType.LIMIT]: 50, [TradeType.ADVANCED]: 30,
+        },
+        [SupportedChainId.SEPOLIA]: {
+            [TradeType.SWAP]: 100, [TradeType.LIMIT]: 50, [TradeType.ADVANCED]: 30,
+        },
+    },
+    recipient: '0x0000000000000000000000000000000000000000',
+}
+
+// Same fee for all, different recipient per network and per trade type
+const c: PartnerFee = {
+    bps: 100,
+    recipient: {
+        [TradeType.SWAP]: {
+            [SupportedChainId.MAINNET]: '0x...a', [SupportedChainId.ARBITRUM_ONE]: '0x...b',
+            [SupportedChainId.GNOSIS_CHAIN]: '0x...c', [SupportedChainId.SEPOLIA]: '0x...d',
+        },
+        [TradeType.LIMIT]: {
+            [SupportedChainId.MAINNET]: '0x...e', [SupportedChainId.ARBITRUM_ONE]: '0x...f',
+            [SupportedChainId.GNOSIS_CHAIN]: '0x...g', [SupportedChainId.SEPOLIA]: '0x...h',
+        },
+        [TradeType.ADVANCED]: {
+            [SupportedChainId.MAINNET]: '0x...j', [SupportedChainId.ARBITRUM_ONE]: '0x...i',
+            [SupportedChainId.GNOSIS_CHAIN]: '0x...k', [SupportedChainId.SEPOLIA]: '0x...l',
+        },
+    }
+}
+```
+
+See [FlexibleConfig](https://github.com/cowprotocol/cowswap/blob/develop/libs/widget-lib/src/types.ts) type for more information. 
+
+### Advanced configuration
+
+The `partnerFee` parameter can be set in a more advanced way using events.
+For example, you can define different fees for different assets:
+
+```typescript
+import {createCowSwapWidget, CowSwapWidgetParams, CowEventListeners, CowEvents} from '@cowprotocol/widget-lib'
+
+let updateParams = null
+
+const recipient = '0x0000000000000000000000000000000000000000'
+
+const defaultPartnerFee = { bps: 50, recipient }
+
+const params: CowSwapWidgetParams = {
+    appCode: 'YOUR_APP_ID',
+    partnerFee: defaultPartnerFee
+}
+
+const listeners: CowEventListeners = [
+    {
+        event: CowEvents.ON_CHANGE_TRADE_PARAMS,
+        handler: (event) => {
+            if (!updateParams) return
+            
+            if (event.sellToken.symbol === 'DAI') {
+                updateParams({
+                    partnerFee: { bps: 20, recipient }
+                })
+            } else if (event.sellToken.symbol === 'USDC') {
+                updateParams({
+                    partnerFee: { bps: 10, recipient }
+                })
+            } else {
+                updateParams({
+                    partnerFee: defaultPartnerFee
+                })
+            }
+        }
+    },
+]
+
+const widget = createCowSwapWidget(container, { params, listeners })
+
+updateParams = widget.updateParams
+```
+
 ### Fee BPS
 The fee in basis points (BPS). One basis point is equivalent to 0.01% (1/100th of a percent).  
 
@@ -88,8 +191,7 @@ For example, if you use a Safe as a recipient and the Safe was created on Ethere
 As a fee recipient, you can specify either string or a key-value pair in the format `chainId: recipientAddress`:
 
 ```typescript
-import type {SupportedChainId} from '@cowprotocol/cow-sdk'
-import type {CowSwapWidgetParams} from '@cowprotocol/widget-lib'
+import type {CowSwapWidgetParams, SupportedChainId} from '@cowprotocol/widget-lib'
 
 const params: CowSwapWidgetParams = {
   partnerFee: {