GITBOOK-406: Damir's May 21 changes

Author: damir-bajramovic

docs/SUMMARY.md

@@ -53,21 +53,12 @@
     * [Authentication](dln-the-debridge-liquidity-network-protocol/integration-guidelines/interacting-with-the-api/authentication.md)
     * [Creating an Order](dln-the-debridge-liquidity-network-protocol/integration-guidelines/interacting-with-the-api/creating-an-order/README.md)
       * [Quick Start](dln-the-debridge-liquidity-network-protocol/integration-guidelines/interacting-with-the-api/creating-an-order/quick-start.md)
-      * [Reserve Assets](dln-the-debridge-liquidity-network-protocol/integration-guidelines/interacting-with-the-api/creating-an-order/reserve-assets.md)
-      * [Bridging Reserve Assets](dln-the-debridge-liquidity-network-protocol/integration-guidelines/interacting-with-the-api/creating-an-order/bridging-reserve-assets.md)
-      * [Bridging non-reserve assets](dln-the-debridge-liquidity-network-protocol/integration-guidelines/interacting-with-the-api/creating-an-order/bridging-non-reserve-assets.md)
       * [API Parameters](dln-the-debridge-liquidity-network-protocol/integration-guidelines/interacting-with-the-api/creating-an-order/api-parameters/README.md)
         * [Estimation-Only](dln-the-debridge-liquidity-network-protocol/integration-guidelines/interacting-with-the-api/creating-an-order/api-parameters/estimation-only.md)
         * [prependOperatingExpenses](dln-the-debridge-liquidity-network-protocol/integration-guidelines/interacting-with-the-api/creating-an-order/api-parameters/prependoperatingexpenses.md)
       * [API Response](dln-the-debridge-liquidity-network-protocol/integration-guidelines/interacting-with-the-api/creating-an-order/api-response/README.md)
         * [JSON Example](dln-the-debridge-liquidity-network-protocol/integration-guidelines/interacting-with-the-api/creating-an-order/api-response/json-example.md)
       * [Refreshing Estimates](dln-the-debridge-liquidity-network-protocol/integration-guidelines/interacting-with-the-api/creating-an-order/refreshing-estimates.md)
-      * [Fees and operating expenses](dln-the-debridge-liquidity-network-protocol/integration-guidelines/interacting-with-the-api/creating-an-order/fees-and-operating-expenses.md)
-      * [Order Fulfillment](dln-the-debridge-liquidity-network-protocol/integration-guidelines/interacting-with-the-api/creating-an-order/order-fulfillment/README.md)
-        * [Detecting the Order](dln-the-debridge-liquidity-network-protocol/integration-guidelines/interacting-with-the-api/creating-an-order/order-fulfillment/detecting-the-order.md)
-        * [Fulfilling the Order](dln-the-debridge-liquidity-network-protocol/integration-guidelines/interacting-with-the-api/creating-an-order/order-fulfillment/fulfilling-the-order/README.md)
-          * [Pre-Fill-Swap](dln-the-debridge-liquidity-network-protocol/integration-guidelines/interacting-with-the-api/creating-an-order/order-fulfillment/fulfilling-the-order/pre-fill-swap.md)
-        * [Claiming the Order](dln-the-debridge-liquidity-network-protocol/integration-guidelines/interacting-with-the-api/creating-an-order/order-fulfillment/claiming-the-order.md)
     * [Tracking Order Status](dln-the-debridge-liquidity-network-protocol/integration-guidelines/interacting-with-the-api/tracking-order-status/README.md)
       * [Order States](dln-the-debridge-liquidity-network-protocol/integration-guidelines/interacting-with-the-api/tracking-order-status/order-states.md)
     * [Requesting Order Creation Transaction](dln-the-debridge-liquidity-network-protocol/integration-guidelines/interacting-with-the-api/requesting-order-creation-transaction.md)
@@ -76,12 +67,22 @@
     * [Submitting an Order Creation Transaction](dln-the-debridge-liquidity-network-protocol/integration-guidelines/interacting-with-the-api/submitting-an-order-creation-transaction.md)
     * [Tracking a Status of the Order](dln-the-debridge-liquidity-network-protocol/integration-guidelines/interacting-with-the-api/tracking-a-status-of-the-order.md)
     * [Cancelling the Order](dln-the-debridge-liquidity-network-protocol/integration-guidelines/interacting-with-the-api/cancelling-the-order.md)
-    * [Affiliate fees](dln-the-debridge-liquidity-network-protocol/integration-guidelines/interacting-with-the-api/affiliate-fees.md)
   * [deBridge Widget](dln-the-debridge-liquidity-network-protocol/integration-guidelines/debridge-widget.md)
   * [Interacting with smart contracts](dln-the-debridge-liquidity-network-protocol/integration-guidelines/interacting-with-smart-contracts/README.md)
     * [Placing orders](dln-the-debridge-liquidity-network-protocol/integration-guidelines/interacting-with-smart-contracts/placing-orders.md)
     * [Filling orders](dln-the-debridge-liquidity-network-protocol/integration-guidelines/interacting-with-smart-contracts/filling-orders.md)
-    * [Withdrawing Affiliate Fees](dln-the-debridge-liquidity-network-protocol/integration-guidelines/interacting-with-smart-contracts/withdrawing-affiliate-fees.md)
+  * [Under the Hood](dln-the-debridge-liquidity-network-protocol/integration-guidelines/under-the-hood/README.md)
+    * [Reserve Assets](dln-the-debridge-liquidity-network-protocol/integration-guidelines/under-the-hood/reserve-assets.md)
+    * [Bridging Reserve Assets](dln-the-debridge-liquidity-network-protocol/integration-guidelines/under-the-hood/bridging-reserve-assets.md)
+    * [Bridging Non-Reserve Assets](dln-the-debridge-liquidity-network-protocol/integration-guidelines/under-the-hood/bridging-non-reserve-assets.md)
+    * [Order Fulfillment](dln-the-debridge-liquidity-network-protocol/integration-guidelines/under-the-hood/order-fulfillment/README.md)
+      * [Detecting the Order](dln-the-debridge-liquidity-network-protocol/integration-guidelines/under-the-hood/order-fulfillment/detecting-the-order.md)
+      * [Fulfilling the Order](dln-the-debridge-liquidity-network-protocol/integration-guidelines/under-the-hood/order-fulfillment/fulfilling-the-order/README.md)
+        * [Pre-Fill-Swap](dln-the-debridge-liquidity-network-protocol/integration-guidelines/under-the-hood/order-fulfillment/fulfilling-the-order/pre-fill-swap.md)
+      * [Claiming the Order](dln-the-debridge-liquidity-network-protocol/integration-guidelines/under-the-hood/order-fulfillment/claiming-the-order.md)
+  * [Affiliate fees](dln-the-debridge-liquidity-network-protocol/integration-guidelines/affiliate-fees/README.md)
+    * [Withdrawing Affiliate Fees](dln-the-debridge-liquidity-network-protocol/integration-guidelines/affiliate-fees/withdrawing-affiliate-fees.md)
+  * [Fees and operating expenses](dln-the-debridge-liquidity-network-protocol/integration-guidelines/fees-and-operating-expenses.md)
 * [Interacting with the deBridge App](dln-the-debridge-liquidity-network-protocol/interacting-with-the-debridge-app/README.md)
   * [Custom Linking](dln-the-debridge-liquidity-network-protocol/interacting-with-the-debridge-app/custom-linking.md)
 * [Protocol specs](dln-the-debridge-liquidity-network-protocol/protocol-specs/README.md)

docs/dln-the-debridge-liquidity-network-protocol/integration-guidelines/affiliate-fees/README.md

@@ -0,0 +1,37 @@
+---
+description: >-
+  Describes how to configure and receive affiliate fees for both cross-chain and
+  same-chain swaps. Includes platform-specific handling for EVM and Solana.
+---
+
+# Affiliate fees
+
+### Affiliate Fees
+
+Affiliate fees can be earned through both cross-chain and same-chain swaps by including the appropriate parameters in the request. This allows integrators to monetize swap activity within their applications.
+
+### Cross-Chain Affiliate Fees <a href="#cross-chain-affiliate-fees" id="cross-chain-affiliate-fees"></a>
+
+To enable affiliate fees for cross-chain swaps, the following [parameters](../interacting-with-the-api/creating-an-order/api-parameters/#affiliate-fee-parameters) must be included when creating an order:
+
+* **`affiliateFeePercent`**: The percentage of the _order input amount_ allocated as the affiliate fee.
+* **`affiliateFeeRecipient`**: The address or public key of the affiliate fee beneficiary. This must be:
+  * A public key on **Solana**
+  * A wallet address on **EVM chains**
+
+Affiliate fees become available once an order reaches the `ClaimedUnlock` [state](../interacting-with-the-api/tracking-order-status/order-states.md).&#x20;
+
+* On **EVM chains**, the affiliate fee is [automatically transferred to the specified recipient when a solver claims the order](../under-the-hood/order-fulfillment/claiming-the-order.md)
+* On **Solana**, the fee must be withdrawn manually. Further details on withdrawing affiliate fees are provided [here](withdrawing-affiliate-fees.md).
+
+### Same-Chain Affiliate Fees <a href="#single-chain-affiliate-fees" id="single-chain-affiliate-fees"></a>
+
+The deBridge Widget also supports affiliate fee collection for same-chain swaps. These swaps use the same `affiliateFeePercent` and `affiliateFeeRecipient` [parameters](../interacting-with-the-api/creating-an-order/api-parameters/#affiliate-fee-parameters), with **Solana** requiring additional configuration.
+
+#### Solana
+
+For same-chain swaps on Solana:
+
+* The `affiliateFeeRecipient` must be a **Jupiter referral key**.
+* Referral keys can be generated at [https://referral.jup.ag/dashboard](https://referral.jup.ag/dashboard).
+* Earned fees can be claimed via the [Jupiter Referral Dashboard](https://referral.jup.ag/dashboard).

docs/dln-the-debridge-liquidity-network-protocol/integration-guidelines/affiliate-fees/withdrawing-affiliate-fees.md

@@ -0,0 +1,61 @@
+# Withdrawing Affiliate Fees
+
+Affiliate fees can be specified by any integration using the [DLN API ](../interacting-with-the-api/)or the [deBridge Widget](../debridge-widget.md). The fees are free to be distributed to the designated beneficiary once [liquidity is unlocked by a solver from a fulfilled order](../under-the-hood/order-fulfillment/claiming-the-order.md)—typically within a few hours after the order execution.
+
+**EVM chains**
+
+On EVM chains, affiliate fees are automatically transferred to the specified beneficiary address as part of the transaction in which the solver unlocks liquidity. No additional action is required.
+
+**Solana**
+
+On Solana, affiliate fees must be claimed manually by the beneficiary. This is done by invoking the `withdrawAffiliateFee` method of the DLN program. A complete working example for claiming affiliate fees in bulk is available [here](https://github.com/debridge-finance/api-integrator-example/blob/master/src/scripts/affiliates/sol-batch-withdraw.ts). 
+
+Simplified example snippet:
+
+```typescript
+import { Solana } from "@debridge-finance/dln-client"
+import { Connection, PublicKey, clusterApiUrl } from "@solana/web3.js";
+
+function findAssociatedTokenAddress(wallet: PublicKey, tokenMint: PublicKey)
+    : [PublicKey, number] {
+    return PublicKey.findProgramAddressSync(
+        [wallet.toBytes(), 
+        new PublicKey("TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA").toBytes(), 
+        tokenMint.toBytes()], 
+        new PublicKey("ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL")
+    );
+}
+
+const solanaClient = new Solana.DlnClient(
+    // Replace with dedicated RPC for production
+    new Connection(clusterApiUrl("mainnet-beta")), 
+    new PublicKey("src5qyZHqTqecJV4aY6Cb6zDZLMDzrDKKezs22MPHr4"), 
+    new PublicKey("dst5MGcFPoBeREFAA5E3tU5ij8m5uVYwkzkSAbsLbNo"), 
+    new PublicKey("DEbrdGj3HsRsAzx6uH4MKyREKxVAfBydijLUF3ygsFfh"), 
+    new PublicKey("DeSetTwWhjZq6Pz9Kfdo1KoS5NqtsM6G8ERbX4SSCSft"),
+)
+
+type Order = {
+    orderId: string;
+    beneficiary: PublicKey;
+    giveToken: PublicKey;
+}
+
+// Load the order using known data or fetch via transaction hash
+// const order = await solanaClient.getOrderFromTransaction(
+//     { giveChain: ChainId.Solana, txHash: "CREATE_TX_HASH" }
+// );
+const order: Order = { /* order data */ };
+
+// Build and send the withdraw transaction
+const [associatedTokenAddress] = findAssociatedTokenAddress(
+    order.beneficiary, 
+    order.giveToken
+);
+const tx = await solanaClient.source.withdrawAffiliateFee(
+    order.orderId, 
+    order.beneficiary, 
+    associatedTokenAddress
+);
+// Send the transaction...
+```

…-an-order/fees-and-operating-expenses.md …uidelines/fees-and-operating-expenses.mddocs/dln-the-debridge-liquidity-network-protocol/integration-guidelines/interacting-with-the-api/creating-an-order/fees-and-operating-expenses.md renamed to docs/dln-the-debridge-liquidity-network-protocol/integration-guidelines/fees-and-operating-expenses.md docs/dln-the-debridge-liquidity-network-protocol/integration-guidelines/interacting-with-the-api/creating-an-order/fees-and-operating-expenses.md renamed to docs/dln-the-debridge-liquidity-network-protocol/integration-guidelines/fees-and-operating-expenses.md

@@ -2,7 +2,7 @@
 
 The spread between the give-offer (i.e., the assets being sold) and the take-offer (i.e., the assets being purchased) must be large enough to incentivize solvers to fulfill the order. In addition to aligning with current market rates, the spread should be sufficient to cover all associated fees and operational expenses, including:
 
-* [Affiliate fee](../affiliate-fees.md) (optional)
-* [DLN protocol fee](../../../../the-debridge-messaging-protocol/fees-and-supported-chains.md)
+* [Affiliate fee](affiliate-fees/) (optional)
+* [DLN protocol fee](../../the-debridge-messaging-protocol/fees-and-supported-chains.md)
 * **Taker’s margin fee** – a small percentage markup over the market rate, serving as the solver’s direct profit for assuming market risk and committing capital
-* **Operating costs incurred by the solver** – including gas fees for executing [the swap on the destination chain](order-fulfillment/fulfilling-the-order/pre-fill-swap.md) and for [claiming the locked assets on the source chain](order-fulfillment/fulfilling-the-order/)
+* **Operating costs incurred by the solver** – including gas fees for executing [the swap on the destination chain](under-the-hood/order-fulfillment/fulfilling-the-order/pre-fill-swap.md) and for [claiming the locked assets on the source chain](under-the-hood/order-fulfillment/fulfilling-the-order/)