Add Fees (#1764)

* fee update

* add fee onto delivery fee

* fee refactor

* remove dynamic imports

* removed useless imports

* fee refactor

* better summaries

* breakdowns

* better breakdowns

* update l2s

* removing older fee fields that are unused

* remove older fields

* review fixes

* add back mock fees

* check reserves

* fixes

* fixes for v2 from parachain

* more balance checks

* remove hydration from v2 chains

Author: alistair-singh

web/packages/api/src/feeSchedule.ts

@@ -0,0 +1,45 @@
+type FeeBand = {
+    lowerUsd: bigint
+    upperUsd: bigint
+    numerator: bigint
+    denominator: bigint
+}
+
+const MAX_USD = 999_999_999_999n
+
+const FEE_SCHEDULE: FeeBand[] = [
+    { lowerUsd: 0n, upperUsd: 100n, numerator: 16n, denominator: 10_000n },
+    { lowerUsd: 100n, upperUsd: 1_000n, numerator: 14n, denominator: 10_000n },
+    { lowerUsd: 1_000n, upperUsd: 10_000n, numerator: 12n, denominator: 10_000n },
+    { lowerUsd: 10_000n, upperUsd: 100_000n, numerator: 10n, denominator: 10_000n },
+    { lowerUsd: 100_000n, upperUsd: 1_000_000n, numerator: 8n, denominator: 10_000n },
+    { lowerUsd: 1_000_000n, upperUsd: MAX_USD, numerator: 6n, denominator: 10_000n },
+]
+
+export type VolumeFeeParams = {
+    txValueUsd: bigint
+    ethToUsdNumerator: bigint
+    ethToUsdDenominator: bigint
+}
+
+export function lookupFeeRatio(txValueUsd: bigint): { numerator: bigint; denominator: bigint } {
+    for (const band of FEE_SCHEDULE) {
+        if (txValueUsd >= band.lowerUsd && txValueUsd < band.upperUsd) {
+            return { numerator: band.numerator, denominator: band.denominator }
+        }
+    }
+    return { numerator: 6n, denominator: 10_000n }
+}
+
+export function calculateVolumeTipInWei(params: VolumeFeeParams): bigint {
+    if (params.txValueUsd < 0n) throw new Error("txValueUsd must be >= 0")
+    if (params.ethToUsdNumerator <= 0n || params.ethToUsdDenominator <= 0n) {
+        throw new Error("ethToUsdNumerator and ethToUsdDenominator must be > 0")
+    }
+    const { numerator: feeNum, denominator: feeDen } = lookupFeeRatio(params.txValueUsd)
+    const WEI = 1_000_000_000_000_000_000n
+    return (
+        (params.txValueUsd * feeNum * WEI * params.ethToUsdDenominator) /
+        (feeDen * params.ethToUsdNumerator)
+    )
+}

web/packages/api/src/fees.ts

@@ -0,0 +1,66 @@
+import type { DeliveryFee, FeeAsset, FeeItem } from "./types/fee"
+
+export function addBreakdown<K extends string>(
+    breakdown: DeliveryFee<K>["breakdown"],
+    key: K,
+    asset: FeeAsset,
+): void {
+    if (asset.amount === 0n) return
+    const bucket = (breakdown as Record<string, FeeAsset[]>)[key] ?? []
+    ;(breakdown as Record<string, FeeAsset[]>)[key] = bucket
+    bucket.push(asset)
+}
+
+export function computeTotals(summary: FeeItem[]): FeeAsset[] {
+    const totals = new Map<string, bigint>()
+    for (const item of summary) {
+        totals.set(item.symbol, (totals.get(item.symbol) ?? 0n) + item.amount)
+    }
+    return [...totals.entries()].map(([symbol, amount]) => ({ symbol, amount }))
+}
+
+export function findInBreakdown<K extends string>(
+    breakdown: DeliveryFee<K>["breakdown"],
+    key: K,
+    symbol: string,
+): bigint {
+    const entries = ((breakdown as Record<string, FeeAsset[]>)[key] ?? []).filter(
+        (a) => a.symbol === symbol,
+    )
+    if (entries.length === 0) {
+        throw new Error(`Fee breakdown missing entry: key="${key}" symbol="${symbol}"`)
+    }
+    return entries.reduce((acc, a) => acc + a.amount, 0n)
+}
+
+export function findInBreakdownOrZero<K extends string>(
+    breakdown: DeliveryFee<K>["breakdown"],
+    key: K,
+    symbol: string,
+): bigint {
+    return ((breakdown as Record<string, FeeAsset[]>)[key] ?? [])
+        .filter((a) => a.symbol === symbol)
+        .reduce((acc, a) => acc + a.amount, 0n)
+}
+
+export function findTotal<K extends string>(fee: DeliveryFee<K>, symbol: string): bigint {
+    const total = fee.totals.find((t) => t.symbol === symbol)
+    if (total === undefined) {
+        throw new Error(`Fee totals missing symbol: "${symbol}"`)
+    }
+    return total.amount
+}
+
+export function findTotalOrUndefined<K extends string>(
+    fee: DeliveryFee<K>,
+    symbol: string,
+): bigint | undefined {
+    return fee.totals.find((t) => t.symbol === symbol)?.amount
+}
+
+export function findTotalOrZero<K extends string>(
+    fee: DeliveryFee<K>,
+    symbol: string,
+): bigint {
+    return fee.totals.find((t) => t.symbol === symbol)?.amount ?? 0n
+}

web/packages/api/src/forInterParachain.ts

@@ -19,6 +19,7 @@ import {
     TransferRoute,
 } from "@snowbridge/base-types"
 import { ensureValidationSuccess, padFeeByPercentage } from "./utils"
+import { addBreakdown, computeTotals, findTotal } from "./fees"
 import { resolveBeneficiary } from "./crypto"
 import { Context } from "."
 import { buildMessageId } from "./toEthereum_v2"
@@ -152,11 +153,19 @@ export class InterParachainTransfer<T extends EthereumProviderTypes>
             options?.padFeeByPercentage ?? 33n,
         )
 
+        const totalFeeInDot = deliveryFee + executionFee
+
+        const breakdown: DeliveryFee["breakdown"] = {}
+        addBreakdown(breakdown, "assetHubDelivery", { amount: deliveryFee, symbol: "DOT" })
+        addBreakdown(breakdown, "destinationExecution", { amount: executionFee, symbol: "DOT" })
+
+        const summary = [{ description: "Transfer fee", amount: totalFeeInDot, symbol: "DOT" }]
+
         return {
             kind: "polkadot->polkadot",
-            deliveryFee,
-            executionFee,
-            totalFeeInDot: deliveryFee + executionFee,
+            breakdown,
+            summary,
+            totals: computeTotals(summary),
         }
     }
 
@@ -197,7 +206,7 @@ export class InterParachainTransfer<T extends EthereumProviderTypes>
             beneficiaryAccount,
             messageId,
             amount,
-            fee.totalFeeInDot,
+            findTotal(fee, "DOT"),
             source.parachainId === this.info.registry.assetHubParaId
                 ? "LocalReserve"
                 : "DestinationReserve",

web/packages/api/src/forKusama.ts

@@ -35,6 +35,11 @@ import {
 import { CallDryRunEffects, XcmDryRunApiError, XcmDryRunEffects } from "@polkadot/types/interfaces"
 import { Result } from "@polkadot/types"
 import { ensureValidationSuccess, padFeeByPercentage, u32ToLeBytes } from "./utils"
+import { addBreakdown, computeTotals, findInBreakdown, findInBreakdownOrZero, findTotal } from "./fees"
+import {
+    checkDotKsmPoolLiquidityForKusamaToPolkadot,
+    checkKsmDotPoolLiquidityForPolkadotToKusama,
+} from "./poolReserves"
 import { resolveBeneficiary } from "./crypto"
 import { TransferInterface as KusamaTransferInterface } from "./transfers/forKusama/transferInterface"
 import { Context } from "."
@@ -264,13 +269,33 @@ export class KusamaTransfer<T extends EthereumProviderTypes> implements KusamaTr
         totalXcmBridgeFee = padFeeByPercentage(totalXcmBridgeFee, 33n)
 
         let totalFee = totalXcmBridgeFee + bridgeHubDeliveryFee + destinationFee
+        const sourceSymbol = this.#direction() === Direction.ToPolkadot ? "KSM" : "DOT"
+        // destNativeSymbol is the asset coming OUT of the destination AH swap
+        // (DOT for kusama→polkadot, KSM for polkadot→kusama).
+        const destNativeSymbol = this.#direction() === Direction.ToPolkadot ? "DOT" : "KSM"
+
+        const breakdown: DeliveryFee["breakdown"] = {}
+        addBreakdown(breakdown, "xcmBridge", { amount: totalXcmBridgeFee, symbol: sourceSymbol })
+        addBreakdown(breakdown, "bridgeHubDelivery", {
+            amount: bridgeHubDeliveryFee,
+            symbol: sourceSymbol,
+        })
+        addBreakdown(breakdown, "destinationExecution", {
+            amount: destinationFee,
+            symbol: sourceSymbol,
+        })
+        addBreakdown(breakdown, "destinationExecution", {
+            amount: destinationFeeInDestNative,
+            symbol: destNativeSymbol,
+        })
+
+        const summary = [{ description: "Bridge fee", amount: totalFee, symbol: sourceSymbol }]
 
         return {
             kind: this.from.kind === "kusama" ? "kusama->polkadot" : "polkadot->kusama",
-            xcmBridgeFee: totalXcmBridgeFee,
-            destinationFee,
-            bridgeHubDeliveryFee,
-            totalFeeInNative: totalFee,
+            breakdown,
+            summary,
+            totals: computeTotals(summary),
         }
     }
 
@@ -327,7 +352,11 @@ export class KusamaTransfer<T extends EthereumProviderTypes> implements KusamaTr
                 tokenLocationOnSource,
                 beneficiaryAddressHex,
                 amount,
-                fee.destinationFee,
+                findInBreakdown(
+                    fee.breakdown,
+                    "destinationExecution",
+                    fee.kind === "kusama->polkadot" ? "KSM" : "DOT",
+                ),
                 messageId,
             )
         } else {
@@ -337,7 +366,11 @@ export class KusamaTransfer<T extends EthereumProviderTypes> implements KusamaTr
                 tokenLocationOnSource,
                 beneficiaryAddressHex,
                 amount,
-                fee.destinationFee,
+                findInBreakdown(
+                    fee.breakdown,
+                    "destinationExecution",
+                    fee.kind === "kusama->polkadot" ? "KSM" : "DOT",
+                ),
                 messageId,
             )
         }
@@ -440,7 +473,10 @@ export class KusamaTransfer<T extends EthereumProviderTypes> implements KusamaTr
         const paymentInfo = await tx.paymentInfo(sourceAccountHex)
         const sourceExecutionFee = paymentInfo["partialFee"].toBigInt()
 
-        if (sourceExecutionFee + fee.totalFeeInNative > nativeBalance) {
+        if (
+            sourceExecutionFee + findTotal(fee, fee.kind === "kusama->polkadot" ? "KSM" : "DOT") >
+            nativeBalance
+        ) {
             logs.push({
                 kind: ValidationKind.Error,
                 reason: ValidationReason.InsufficientFee,
@@ -455,7 +491,11 @@ export class KusamaTransfer<T extends EthereumProviderTypes> implements KusamaTr
         if (this.#direction() == Direction.ToPolkadot) {
             destAssetHubXCM = buildKusamaToPolkadotDestAssetHubXCM(
                 destAssetHub.registry,
-                fee.destinationFee,
+                findInBreakdown(
+                    fee.breakdown,
+                    "destinationExecution",
+                    fee.kind === "kusama->polkadot" ? "KSM" : "DOT",
+                ),
                 registry.assetHubParaId,
                 tokenLocation,
                 transfer.input.amount,
@@ -465,7 +505,11 @@ export class KusamaTransfer<T extends EthereumProviderTypes> implements KusamaTr
         } else {
             destAssetHubXCM = buildPolkadotToKusamaDestAssetHubXCM(
                 destAssetHub.registry,
-                fee.destinationFee,
+                findInBreakdown(
+                    fee.breakdown,
+                    "destinationExecution",
+                    fee.kind === "kusama->polkadot" ? "KSM" : "DOT",
+                ),
                 registry.assetHubParaId,
                 tokenLocation,
                 transfer.input.amount,
@@ -512,6 +556,53 @@ export class KusamaTransfer<T extends EthereumProviderTypes> implements KusamaTr
             }
         }
 
+        const destAssetHubImpl = await this.context.paraImplementation(destAssetHub)
+        if (this.#direction() === Direction.ToPolkadot) {
+            const requiredDotOut = findInBreakdownOrZero(
+                fee.breakdown,
+                "destinationExecution",
+                "DOT",
+            )
+            if (requiredDotOut > 0n) {
+                const reserveCheck = await checkDotKsmPoolLiquidityForKusamaToPolkadot(
+                    destAssetHubImpl,
+                    requiredDotOut,
+                )
+                if (!reserveCheck.ok) {
+                    logs.push({
+                        kind: ValidationKind.Error,
+                        reason: ValidationReason.InsufficientPoolReserves,
+                        message:
+                            reserveCheck.reason === "pool-missing"
+                                ? `${reserveCheck.pool} pool does not exist on Asset Hub.`
+                                : `${reserveCheck.pool} pool on Asset Hub has insufficient liquidity (need ${reserveCheck.requiredOut}, have ${reserveCheck.reserveOut}).`,
+                    })
+                }
+            }
+        } else {
+            const requiredKsmOut = findInBreakdownOrZero(
+                fee.breakdown,
+                "destinationExecution",
+                "KSM",
+            )
+            if (requiredKsmOut > 0n) {
+                const reserveCheck = await checkKsmDotPoolLiquidityForPolkadotToKusama(
+                    destAssetHubImpl,
+                    requiredKsmOut,
+                )
+                if (!reserveCheck.ok) {
+                    logs.push({
+                        kind: ValidationKind.Error,
+                        reason: ValidationReason.InsufficientPoolReserves,
+                        message:
+                            reserveCheck.reason === "pool-missing"
+                                ? `${reserveCheck.pool} pool does not exist on Asset Hub.`
+                                : `${reserveCheck.pool} pool on Asset Hub has insufficient liquidity (need ${reserveCheck.requiredOut}, have ${reserveCheck.reserveOut}).`,
+                    })
+                }
+            }
+        }
+
         const success = logs.find((l) => l.kind === ValidationKind.Error) === undefined
 
         return {

web/packages/api/src/index.ts

@@ -58,6 +58,17 @@ export * as toEthereumV2 from "./types/toEthereum"
 export * as toEthereumFromEVMV2 from "./types/toEthereumEvm"
 export * as forInterParachain from "./types/forInterParachain"
 export * as forKusama from "./types/forKusama"
+export type { VolumeFeeParams } from "./feeSchedule"
+export type {
+    FeeAsset,
+    FeeItem,
+    ToPolkadotFeeKey,
+    L2ToPolkadotFeeKey,
+    ToEthereumFeeKey,
+    InterParachainFeeKey,
+    KusamaFeeKey,
+    V1ToPolkadotFeeKey,
+} from "./types/fee"
 export * as utils from "./utils"
 export * as status from "./status"
 export * as assetsV2 from "./assets_v2"

web/packages/api/src/parachains/acala.ts

@@ -77,4 +77,11 @@ export class AcalaParachain extends ParachainBase {
     ): Promise<bigint> {
         throw Error(`${this.specName} does not support.`)
     }
+
+    getAssetHubPoolReserves(
+        _asset1: any,
+        _asset2: any,
+    ): Promise<{ reserve1: bigint; reserve2: bigint } | null> {
+        return Promise.resolve(null)
+    }
 }

web/packages/api/src/parachains/assethub.ts

@@ -1,4 +1,4 @@
-import { AssetMap, PNAMap } from "@snowbridge/base-types"
+import { AssetMap, FeeEstimateError, PNAMap } from "@snowbridge/base-types"
 import { ParachainBase } from "./parachainBase"
 import { getTokenFromLocation, ROCOCO_GENESIS, WESTEND_GENESIS } from "../xcmBuilder"
 import { DOT_LOCATION } from "../assets_v2"
@@ -197,11 +197,7 @@ export class AssetHubParachain extends ParachainBase {
         )
         const asset2Balance = result.toPrimitive() as any
         if (asset2Balance == null) {
-            throw Error(
-                `No pool set up in asset conversion pallet for '${JSON.stringify(
-                    asset1,
-                )}' and '${JSON.stringify(asset2)}'.`,
-            )
+            throw FeeEstimateError.couldNotSwap(asset1, asset2)
         }
         return BigInt(asset2Balance)
     }
@@ -219,14 +215,20 @@ export class AssetHubParachain extends ParachainBase {
         )
         const asset1Balance = result.toPrimitive() as any
         if (asset1Balance == null) {
-            throw Error(
-                `No pool set up in asset conversion pallet for '${JSON.stringify(
-                    asset1,
-                )}' and '${JSON.stringify(asset2)}'.`,
-            )
+            throw FeeEstimateError.couldNotSwap(asset1, asset2)
         }
         return BigInt(asset1Balance)
     }
+
+    async getAssetHubPoolReserves(
+        asset1: any,
+        asset2: any,
+    ): Promise<{ reserve1: bigint; reserve2: bigint } | null> {
+        const result = await this.provider.call.assetConversionApi.getReserves(asset1, asset2)
+        const reserves = result.toPrimitive() as [string | number, string | number] | null
+        if (reserves == null) return null
+        return { reserve1: BigInt(reserves[0]), reserve2: BigInt(reserves[1]) }
+    }
 }
 
 // Currently, the bridgeable assets are limited to KSM, DOT, native assets on AH