refactor(core): onhance fee calculation algorithm and structure

Author: esaugomez31

core/api/src/app/wallets/get-on-chain-fee.ts

@@ -171,7 +171,7 @@ export const getMinerFeeAndPaymentFlow = async <
   })
   if (minerFee instanceof Error) return minerFee
 
-  return builder.withMinerFee(minerFee)
+  return builder.withMinerFee(minerFee, speed)
 }
 
 export const getOnChainFeeForBtcWallet = async <S extends WalletCurrency>(

core/api/src/domain/payments/index.types.d.ts

@@ -328,6 +328,7 @@ type OPFBWithAmount<S extends WalletCurrency, R extends WalletCurrency> = {
 type OPFBWithConversion<S extends WalletCurrency, R extends WalletCurrency> = {
   withMinerFee(
     minerFee: BtcPaymentAmount,
+    speed: PayoutSpeed,
   ): Promise<OnChainPaymentFlow<S, R> | ValidationError | DealerPriceServiceError>
   withoutMinerFee(): Promise<
     OnChainPaymentFlow<S, R> | ValidationError | DealerPriceServiceError

core/api/src/domain/payments/onchain-payment-flow-builder.ts

@@ -13,23 +13,17 @@ import { getFeesConfig } from "@/config"
 import {
   AmountCalculator,
   ONE_CENT,
-  paymentAmountFromNumber,
   ValidationError,
   WalletCurrency,
   ZERO_BANK_FEE,
 } from "@/domain/shared"
 import { LessThanDustThresholdError, SelfPaymentError } from "@/domain/errors"
 import { OnChainFees, PaymentInitiationMethod, SettlementMethod } from "@/domain/wallets"
-import { ImbalanceCalculator } from "@/domain/ledger/imbalance-calculator"
 
 const calc = AmountCalculator()
 const feeConfig = getFeesConfig()
 const onChainFees = OnChainFees({
-  feeRatioAsBasisPoints: feeConfig.withdrawRatioAsBasisPoints,
-  thresholdImbalance: {
-    amount: BigInt(feeConfig.withdrawThreshold),
-    currency: WalletCurrency.Btc,
-  },
+  onchain: feeConfig.onchain,
 })
 
 export const OnChainPaymentFlowBuilder = <S extends WalletCurrency>(
@@ -431,6 +425,7 @@ const OPFBWithConversion = <S extends WalletCurrency, R extends WalletCurrency>(
 
   const withMinerFee = async (
     minerFee: BtcPaymentAmount,
+    speed: PayoutSpeed,
   ): Promise<OnChainPaymentFlow<S, R> | ValidationError | DealerPriceServiceError> => {
     const state = await stateFromPromise(statePromise)
     if (state instanceof Error) return state
@@ -441,35 +436,11 @@ const OPFBWithConversion = <S extends WalletCurrency, R extends WalletCurrency>(
     })
     if (priceRatio instanceof Error) return priceRatio
 
-    const minBankFee = paymentAmountFromNumber({
-      amount: state.senderWithdrawFee || feeConfig.withdrawDefaultMin,
-      currency: WalletCurrency.Btc,
-    })
-    if (minBankFee instanceof Error) return minBankFee
-
-    const imbalanceCalculator = ImbalanceCalculator({
-      method: feeConfig.withdrawMethod,
-      netInVolumeAmountLightningFn: state.netInVolumeAmountLightningFn,
-      netInVolumeAmountOnChainFn: state.netInVolumeAmountOnChainFn,
-      sinceDaysAgo: feeConfig.withdrawDaysLookback,
-    })
-    const imbalanceForWallet = await imbalanceCalculator.getSwapOutImbalanceAmount<S>({
-      id: state.senderWalletId,
-      currency: state.senderWalletCurrency,
-      accountId: state.senderAccountId,
-    })
-    if (imbalanceForWallet instanceof Error) return imbalanceForWallet
-
-    const imbalance =
-      imbalanceForWallet.currency === WalletCurrency.Btc
-        ? (imbalanceForWallet as BtcPaymentAmount)
-        : priceRatio.convertFromUsd(imbalanceForWallet as UsdPaymentAmount)
-
     const feeAmounts = onChainFees.withdrawalFee({
       minerFee,
       amount: state.btcProposedAmount,
-      minBankFee,
-      imbalance,
+      speed,
+      feeRate: 5,
     })
 
     // Calculate amounts & fees

core/api/src/domain/wallets/index.types.d.ts

@@ -204,15 +204,14 @@ type DepositFeeCalculator = {
 }
 
 type OnchainWithdrawalConfig = {
-  thresholdImbalance: BtcPaymentAmount
-  feeRatioAsBasisPoints: bigint
+  onchain: OnchainFeesConfig
 }
 
 type OnChainWithdrawalFeeArgs = {
   minerFee: BtcPaymentAmount
-  minBankFee: BtcPaymentAmount
-  imbalance: BtcPaymentAmount
   amount: BtcPaymentAmount
+  speed: PayoutSpeed
+  feeRate: number
 }
 
 type WithdrawalFeePriceMethod =
@@ -250,3 +249,29 @@ type PaymentInputValidator = {
     args: ValidatePaymentInputArgs<T>,
   ) => Promise<ValidatePaymentInputRet<T> | ValidationError | RepositoryError>
 }
+
+interface TransactionSpecification {
+  readonly inputCount: number
+  readonly outputCount: number
+}
+
+type InputCountCalculator = (amount: number) => number
+type TransactionSizeCalculator = (spec: TransactionSpecification) => number
+type DecayRateCalculator = (amount: number, params: FeeDecayCurveParameters) => number
+type CostToBankCalculator = (
+  amount: number,
+  speed: PayoutSpeed,
+  feeRate: number,
+) => number
+type DynamicRateCalculator = (
+  amount: number,
+  speed: PayoutSpeed,
+  feeRate: number,
+) => number
+type BaseMultiplierCalculator = (speed: PayoutSpeed, feeRate: number) => number
+
+interface FeeDecayCurveParameters {
+  readonly minRate: number
+  readonly maxRate: number
+  readonly divisor: number
+}

core/api/src/domain/wallets/withdrawal-fee-calculator.ts

@@ -1,38 +1,139 @@
-import { AmountCalculator, ZERO_CENTS, ZERO_SATS } from "@/domain/shared"
+import { PayoutSpeed } from "@/domain/bitcoin/onchain"
+import { AmountCalculator, WalletCurrency, ZERO_CENTS, ZERO_SATS } from "@/domain/shared"
 
 const calc = AmountCalculator()
 
 export const OnChainFees = ({
-  thresholdImbalance,
-  feeRatioAsBasisPoints,
+  onchain,
 }: OnchainWithdrawalConfig): OnChainFeeCalculator => {
   const withdrawalFee = ({
     minerFee,
     amount,
-    minBankFee,
-    imbalance,
+    speed,
+    feeRate,
   }: {
     minerFee: BtcPaymentAmount
     amount: BtcPaymentAmount
     minBankFee: BtcPaymentAmount
-    imbalance: BtcPaymentAmount
+    speed: PayoutSpeed
+    feeRate: number
   }) => {
-    const amountWithImbalanceCalcs = {
-      amount: imbalance.amount - thresholdImbalance.amount + amount.amount,
-      currency: amount.currency,
+    const satoshis = Number(amount.amount)
+
+    const dynamicRate = calculateDynamicFeeRate(satoshis, speed, feeRate)
+    const baseMultiplier = calculateBaseMultiplier(speed, feeRate)
+    const bankCost = calculateCostToBank(satoshis, speed, feeRate)
+
+    const bankFee: BtcPaymentAmount = {
+      amount: BigInt(Math.round(satoshis * dynamicRate + bankCost * baseMultiplier)),
+      currency: WalletCurrency.Btc,
     }
-    const baseAmount = calc.max(calc.min(amountWithImbalanceCalcs, amount), ZERO_SATS)
-    const bankFee = calc.max(
-      minBankFee,
-      calc.mulBasisPoints(baseAmount, feeRatioAsBasisPoints),
-    )
 
     return {
       totalFee: calc.add(bankFee, minerFee),
       bankFee,
     }
   }
 
+  const createThresholdBasedCalculator =
+    (
+      thresholds: readonly { max: number; count: number }[],
+      defaultCount: number,
+    ): InputCountCalculator =>
+    (amount: number) => {
+      const threshold = thresholds.find(({ max }) => amount < max)
+      return threshold?.count ?? defaultCount
+    }
+
+  const calculateRegularInputCount: InputCountCalculator = createThresholdBasedCalculator(
+    onchain.thresholds.regular,
+    onchain.thresholds.defaults.regular,
+  )
+
+  const calculateBatchInputCount: InputCountCalculator = createThresholdBasedCalculator(
+    onchain.thresholds.batch,
+    onchain.thresholds.defaults.batch,
+  )
+
+  const calculateTransactionSize: TransactionSizeCalculator = (spec) => {
+    const { baseSize, inputSize, outputSize } = onchain.transaction
+    return baseSize + spec.inputCount * inputSize + spec.outputCount * outputSize
+  }
+
+  const calculateExponentialDecay = (
+    amount: number,
+    minRate: number,
+    maxRate: number,
+    threshold: number,
+    minAmount: number,
+    exponentialFactor: number,
+  ): number => {
+    const span = threshold - minAmount
+    const exponent = -((amount - minAmount) / span) * exponentialFactor
+    return minRate + (maxRate - minRate) * Math.exp(exponent)
+  }
+
+  const calculateDecayRate: DecayRateCalculator = (amount, params) => {
+    const { threshold, minSats, exponentialFactor } = onchain.decayConstants
+    const { minRate, maxRate, divisor } = params
+
+    if (amount < threshold) {
+      return calculateExponentialDecay(
+        amount,
+        minRate,
+        maxRate,
+        threshold,
+        minSats,
+        exponentialFactor,
+      )
+    }
+
+    return divisor / amount
+  }
+
+  const calculateNormalizedFactor = (feeRate: number): number => {
+    const { min, max } = onchain.decayConstants.networkFeeRange
+    return (feeRate - min) / (max - min)
+  }
+
+  const calculateDynamicFeeRate: DynamicRateCalculator = (amount, speed, feeRate) => {
+    const { targetRate, ...decayParams } = onchain.decay[speed]
+    const decay = calculateDecayRate(amount, decayParams)
+    const normalizedFactor = calculateNormalizedFactor(feeRate)
+    return decay + normalizedFactor * (targetRate - decay)
+  }
+
+  const calculateBaseMultiplier: BaseMultiplierCalculator = (speed, feeRate) => {
+    const { factors, offsets } = onchain.multiplier
+    return factors[speed] / feeRate + offsets[speed]
+  }
+
+  const createTransactionSpec = (
+    amount: number,
+    speed: PayoutSpeed,
+  ): TransactionSpecification => {
+    const { outputs } = onchain.transaction
+
+    if (speed === PayoutSpeed.Slow) {
+      return {
+        inputCount: calculateBatchInputCount(amount),
+        outputCount: outputs.batch,
+      }
+    }
+
+    return {
+      inputCount: calculateRegularInputCount(amount),
+      outputCount: outputs.regular,
+    }
+  }
+
+  const calculateCostToBank: CostToBankCalculator = (amount, speed, feeRate) => {
+    const spec = createTransactionSpec(amount, speed)
+    const size = calculateTransactionSize(spec)
+
+    return speed === PayoutSpeed.Slow ? Math.round((size * feeRate) / 10) : size * feeRate
+  }
+
   return {
     withdrawalFee,
     intraLedgerFees: () => ({