Skip to content

verification.md

Latest commit

 

History

History
149 lines (92 loc) · 5.09 KB

verification.md

File metadata and controls

149 lines (92 loc) · 5.09 KB

Verification Methodology

This document describes how each component of the Flash Risk Engine was verified against on-chain and reference implementation sources.

Program ID

Status: Verified

The program ID FLASH6Lo6h3iasJKWDs2F8TkW2UKf3s15C8PMGuVfgBn was cross-checked from three independent sources:

  1. flash-trade/flash-trade-sdk -> SDK/src/PoolConfig.json -> "programId"
  2. flash-trade/flash-trade-sdk -> SDK/src/idl/perpetuals.json -> "address"
  3. flash-trade/flash-sdk-rust -> programs/flash-read/src/lib.rs -> declare_id! (mainnet feature)

All three sources resolve to the same address.

IDL Account Layouts

Status: Verified

Account struct definitions in src/types.ts match the canonical IDL (perpetuals.json v15.1.0) field-by-field:

  • Position -- 17 fields, matching IDL types.Position
  • Custody -- 21 fields, matching IDL types.Custody
  • Market -- 12 fields, matching IDL types.Market
  • Pool -- 28 fields, matching IDL types.Pool
  • CustomOracle -- 7 fields, matching IDL types.CustomOracle

The IDL is downloaded from the official Flash Trade SDK repository via scripts/setup.sh, which verifies the program address is present in the downloaded file.

Precision Constants

Status: Verified

Constant Value Verified Against
BPS_DECIMALS 4 flash-sdk-rust impl Perpetuals, TS SDK constants/index.ts
RATE_DECIMALS 9 flash-sdk-rust impl Perpetuals, TS SDK constants/index.ts
USD_DECIMALS 6 flash-sdk-rust impl Perpetuals, TS SDK constants/index.ts
ORACLE_EXPONENT_SCALE -9 flash-sdk-rust top-level constant
BORROW_RATE_PERIOD_SECS 3600 flash-perpetuals custody.rs get_cumulative_interest

PnL Computation

Status: Verified

The computePnl function matches pool.rs -> fn get_pnl_usd (lines ~575-707):

  • Long profit: size_usd * max(0, exit_price - entry_price) / entry_price
  • Long loss: size_usd * max(0, entry_price - exit_price) / entry_price
  • Short profit/loss: reversed
  • Profit cap: min(profit, locked_value_usd)

Verified by comparing the formula structure, variable names, and order of operations with the Rust source.

Leverage Computation

Status: Verified

The computeLeverage function matches pool.rs -> fn get_leverage:

leverage = size_usd * BPS_POWER / margin_usd

The zero-margin sentinel (returning MAX_SAFE_INTEGER) is a TypeScript equivalent of the Rust checked_div returning an error.

Liquidation Condition

Status: Verified

The isLiquidatable function matches pool.rs -> fn check_leverage:

liquidatable = current_leverage > max_leverage

This is the exact condition checked by liquidate.rs before executing a liquidation.

Borrow Rate (Kink Model)

Status: Verified

The computeBorrowRate function matches custody.rs -> fn update_borrow_rate:

  • Below optimal: linear interpolation with slope1
  • Above optimal: slope1 + interpolation with slope2
  • Zero optimal utilization: returns base_rate only

The formula structure, branching logic, and variable relationships match the Rust source.

Lock Fee Accumulation

Status: Verified

The getCumulativeLockFee function matches custody.rs -> fn get_cumulative_interest:

  • Uses ceiling division: (a + b - 1) / b
  • Divisor is 3600 (hourly rate)
  • No accumulation when curtime <= lastUpdate

Oracle Price Range

Status: Verified

The getOraclePriceRange function matches flash-sdk-rust -> impl OraclePrice -> fn fetch_from_oracle:

  • Divergence calculation: |spot - ema| * BPS_POWER / ema
  • Low divergence: min = max = spot
  • High divergence: min = spot - conf, max = spot + conf

Close Fee

Status: Verified

close_fee_usd = size_usd * close_position_fee / RATE_POWER

Matches the flat-rate computation in pool.rs.

Liquidation Price

Status: Partial

The liquidation price formula is derived from the liquidation condition (not directly implemented in Rust as a standalone function). The derivation is mathematically correct given the assumptions:

  • Interest and close fee are estimated at current values (not recalculated at the hypothetical liquidation time)
  • Uses maxLeverage exclusively (ignores maxDegenLeverage)

Production's flash-compute library may compute liquidation price differently, accounting for dynamic fee recalculation.

Items Not Verified

The following are present in on-chain position accounts but their settlement/usage logic is not in the reference implementation:

Field Status Reason
price_impact_usd Not verified Production program closed-source
degen_size_usd Not verified Threshold selection logic closed-source
unsettled_value_usd Not verified Settlement logic closed-source
unsettled_fees_usd Not verified Settlement logic closed-source
Lazer oracle feeds Not verified Integration closed-source

These fields exist on PositionAccount and are deserialized correctly, but the engine does not incorporate them into risk computations because the exact usage logic is unknown.