@spec build_aggressive_preset(map(), Decimal.t(), :long | :short) :: dca_preset()

Build aggressive DCA preset from user configuration or defaults.

Aggressive DCA goes with the current position direction:

• For longs: buy at higher prices (momentum trading)
• For shorts: buy at lower prices (momentum trading)

Parameters

• params: Parameters map containing DCA price and allocation configuration
• entry_price: Entry price for calculating price multipliers (Decimal)
• side: Position side (:long or :short)

Returns

List of {price_multiplier, allocation_decimal} tuples.

Examples

params = %{
  aggressive_prices: [Decimal.new("3150"), Decimal.new("3300")],
  dca_allocations: [Decimal.new("40"), Decimal.new("30")]
}

build_aggressive_preset(params, Decimal.new("3000"), :long)
#=> [{Decimal.new("1.05"), Decimal.new("0.40")}, {Decimal.new("1.10"), Decimal.new("0.30")}]

@spec build_defensive_preset(map(), Decimal.t(), :long | :short) :: dca_preset()

Build defensive DCA preset from user configuration or defaults.

Defensive DCA goes against the current position direction:

• For longs: buy at lower prices (averaging down)
• For shorts: buy at higher prices (averaging up)

Parameters

• params: Parameters map containing DCA price and allocation configuration
• entry_price: Entry price for calculating price multipliers (Decimal)
• side: Position side (:long or :short)

Returns

List of {price_multiplier, allocation_decimal} tuples.

Examples

params = %{
  defensive_prices: [Decimal.new("2850"), Decimal.new("2700")],
  dca_allocations: [Decimal.new("40"), Decimal.new("30")]
}

build_defensive_preset(params, Decimal.new("3000"), :long)
#=> [{Decimal.new("0.95"), Decimal.new("0.40")}, {Decimal.new("0.90"), Decimal.new("0.30")}]

@spec calculate_dca_ladder(dca_params()) :: dca_result() | nil

Calculates DCA ladder results if reserve is available and DCA is enabled.

Builds both defensive and aggressive DCA strategies and calculates complete ladder results with enhanced step information including safety metrics.

Parameters

• dca_params: Map or struct containing all DCA parameters:
  • params: Validated parameters map containing DCA configuration
  • position_with_tokens: Position map with tokens calculation
  • dca_reserve: Available DCA reserve amount (Decimal)
  • entry_price: Entry price for the position (Decimal)
  • ui_leverage: UI leverage setting (Decimal)
  • side: Position side (:long or :short)
  • mmr_rate: Minimum margin requirement rate (Decimal)
  • mark_buffer: Mark price buffer (Decimal)
  • aum: Total Assets Under Management (Decimal)
  • black_swan_pct: Black swan threshold as decimal (0-1)

Returns

Map with DCA ladder results, or nil if no DCA available:

• :defensive - Defensive DCA strategy results (if available)
• :aggressive - Aggressive DCA strategy results (if available)

Each strategy contains:

• :steps - List of enhanced DCA steps with safety metrics
• Other fields from Calc.dca_ladder/8 result

Examples

dca_params = %{
  params: %{
    dca_enabled: true,
    defensive_prices: [Decimal.new("2850"), Decimal.new("2700")],
    dca_allocations: [Decimal.new("30"), Decimal.new("30")]
  },
  position_with_tokens: position,
  dca_reserve: reserve,
  entry_price: entry,
  ui_leverage: leverage,
  side: :long,
  mmr_rate: mmr,
  mark_buffer: buffer,
  aum: aum,
  black_swan_pct: swan_pct
}

calculate_dca_ladder(dca_params)
#=> %{
#     defensive: %{steps: [...], final_avg_entry: ...},
#     aggressive: %{steps: [...], final_avg_entry: ...}
#   }

@spec enhance_dca_steps(
  [dca_step()],
  Decimal.t(),
  Decimal.t(),
  Decimal.t(),
  :long | :short
) ::
  [dca_step()] | {:error, atom()}

Enhance DCA steps with additional risk and portfolio metrics.

Adds leverage-to-AUM ratios and black swan safety checks to each DCA step for comprehensive risk assessment at each ladder level.

Parameters

• steps: List of DCA steps from Calc.dca_ladder/8
• aum: Total Assets Under Management (Decimal)
• black_swan_pct: Black swan threshold as decimal (0-1)
• entry_price: Entry price (Decimal)
• side: Position side (:long or :short)

Returns

Enhanced list of DCA steps with additional fields:

• :leverage_to_aum - Cumulative position size as percentage of total AUM
• :passes_black_swan - Whether this step's liquidation passes black swan test
• :black_swan_price - Black swan price level for reference

Examples

steps = [%{cumulative_notional: Decimal.new("1000"), new_liq: Decimal.new("2800"), ...}]

enhance_dca_steps(steps, Decimal.new("50000"), Decimal.new("0.15"), Decimal.new("3000"), :long)
#=> [%{..., leverage_to_aum: Decimal.new("0.02"), passes_black_swan: true, ...}]