@velocity-exchange/sdk 0.6.1 → 0.8.0

package/lib/browser/idl/velocity.json

@@ -2,7 +2,7 @@
     "address": "vELoC1audYbSYVRXn1vPaV8Axoa9oU6BYmNGZZBDZ1P",
     "metadata": {
         "name": "velocity",
-        "version": "2.163.0",
+        "version": "2.164.0",
         "spec": "0.1.0",
         "description": "Created with Anchor"
     },
@@ -4420,6 +4420,9 @@
                     "name": "liquidator",
                     "writable": true
                 },
+                {
+                    "name": "liquidator_stats"
+                },
                 {
                     "name": "user",
                     "writable": true
@@ -6283,6 +6286,9 @@
                 52
             ],
             "accounts": [
+                {
+                    "name": "state"
+                },
                 {
                     "name": "spot_market",
                     "writable": true,
@@ -6327,6 +6333,40 @@
                         "user_stats"
                     ]
                 },
+                {
+                    "name": "spot_market_vault",
+                    "writable": true,
+                    "pda": {
+                        "seeds": [
+                            {
+                                "kind": "const",
+                                "value": [
+                                    115,
+                                    112,
+                                    111,
+                                    116,
+                                    95,
+                                    109,
+                                    97,
+                                    114,
+                                    107,
+                                    101,
+                                    116,
+                                    95,
+                                    118,
+                                    97,
+                                    117,
+                                    108,
+                                    116
+                                ]
+                            },
+                            {
+                                "kind": "arg",
+                                "path": "market_index"
+                            }
+                        ]
+                    }
+                },
                 {
                     "name": "insurance_fund_vault",
                     "writable": true,
@@ -6363,6 +6403,12 @@
                             }
                         ]
                     }
+                },
+                {
+                    "name": "velocity_signer"
+                },
+                {
+                    "name": "token_program"
                 }
             ],
             "args": [
@@ -6537,13 +6583,7 @@
                     }
                 },
                 {
-                    "name": "authority",
-                    "relations": [
-                        "user"
-                    ]
-                },
-                {
-                    "name": "user"
+                    "name": "authority"
                 },
                 {
                     "name": "payer",
@@ -8238,6 +8278,9 @@
                 {
                     "name": "user",
                     "writable": true
+                },
+                {
+                    "name": "user_stats"
                 }
             ],
             "args": [
@@ -11431,6 +11474,42 @@
             ],
             "args": []
         },
+        {
+            "name": "update_spot_market_deposit_cap",
+            "discriminator": [
+                76,
+                21,
+                179,
+                154,
+                28,
+                161,
+                174,
+                107
+            ],
+            "accounts": [
+                {
+                    "name": "admin",
+                    "signer": true
+                },
+                {
+                    "name": "state"
+                },
+                {
+                    "name": "spot_market",
+                    "writable": true
+                }
+            ],
+            "args": [
+                {
+                    "name": "deposit_guard_threshold",
+                    "type": "u64"
+                },
+                {
+                    "name": "max_deposit_bps_per_day",
+                    "type": "u16"
+                }
+            ]
+        },
         {
             "name": "update_spot_market_expiry",
             "discriminator": [
@@ -12070,6 +12149,38 @@
                 }
             ]
         },
+        {
+            "name": "update_spot_market_withdraw_circuit_breaker",
+            "discriminator": [
+                2,
+                97,
+                135,
+                97,
+                117,
+                169,
+                65,
+                223
+            ],
+            "accounts": [
+                {
+                    "name": "admin",
+                    "signer": true
+                },
+                {
+                    "name": "state"
+                },
+                {
+                    "name": "spot_market",
+                    "writable": true
+                }
+            ],
+            "args": [
+                {
+                    "name": "withdraw_circuit_breaker_bps",
+                    "type": "u16"
+                }
+            ]
+        },
         {
             "name": "update_state_max_initialize_user_fee",
             "discriminator": [
@@ -16157,6 +16268,31 @@
             "code": 6359,
             "name": "InvalidEquityFloorTransfer",
             "msg": "Invalid equity floor transfer between subaccounts"
+        },
+        {
+            "code": 6360,
+            "name": "IFDepositMintsZeroShares",
+            "msg": "Insurance fund deposit would mint zero shares"
+        },
+        {
+            "code": 6361,
+            "name": "LiquidationWorsensAccountHealth",
+            "msg": "Liquidation would worsen the account's margin shortage"
+        },
+        {
+            "code": 6362,
+            "name": "PerpBankruptcyMustPrecedeSpot",
+            "msg": "Perp bankruptcies must be resolved before spot bankruptcies"
+        },
+        {
+            "code": 6363,
+            "name": "InvalidRevenueShareRecipient",
+            "msg": "Revenue share recipient user must be sub_account_id 0"
+        },
+        {
+            "code": 6364,
+            "name": "DailyDepositLimit",
+            "msg": "Spot market daily deposit limit hit"
         }
     ],
     "types": [
@@ -21204,19 +21340,24 @@
                         }
                     },
                     {
-                        "name": "_padding_align_amm",
+                        "name": "pending_revenue_share",
                         "docs": [
-                            "8 bytes of explicit padding so MarketStats (216 bytes) plus this",
-                            "padding equals 224 bytes — the offset Rust naturally inserts to",
-                            "16-align AMM's leading u128. Making it explicit keeps the IDL byte",
-                            "layout aligned with `repr(C)`."
+                            "Aggregate accrued builder/referrer revenue-share owed out of this",
+                            "market's `pnl_pool` but not yet paid: incremented as builder and",
+                            "referrer fees accrue on fills (mirrors the per-order",
+                            "`RevenueShareOrder.fees_accrued` writes) and decremented as",
+                            "`sweep_completed_revenue_share_for_market` pays them. The",
+                            "permissionless fee sweep reserves it (like `max(net_user_pnl, 0)` and",
+                            "the floored IF tranche) so a protocol-fee drain can't move the tokens",
+                            "backing already-owed revenue share out of the pnl pool and leave those",
+                            "claims temporarily unpayable. precision: QUOTE_PRECISION.",
+                            "",
+                            "Occupies the 8 bytes Rust naturally inserts to 16-align AMM's leading",
+                            "u128 (formerly explicit `_padding_align_amm`): a u64 at the same",
+                            "8-aligned offset keeps every downstream byte offset and the total size",
+                            "unchanged, so legacy accounts read 0 (nothing owed) until fees accrue."
                         ],
-                        "type": {
-                            "array": [
-                                "u8",
-                                8
-                            ]
-                        }
+                        "type": "u64"
                     },
                     {
                         "name": "amm",
@@ -22998,15 +23139,44 @@
                     {
                         "name": "_padding_align_pfp",
                         "docs": [
-                            "Aligns `protocol_fee_pool`'s leading u128 to a 16-byte struct offset so",
-                            "host (x86_64, align 16) and SBF (align 8) layouts agree. Do not reorder."
+                            "Explicit filler carved from the alignment gap before `protocol_fee_pool`",
+                            "(which must stay at struct offset 752 so host/SBF layouts agree and the",
+                            "borsh/IDL packed offset matches). The gap is 13 bytes; the three",
+                            "configurable-limit fields below plus this 1-byte filler fill it exactly,",
+                            "so `protocol_fee_pool` and every field after it keep their offsets and the",
+                            "account size is unchanged. Reads 0 on markets created before these fields",
+                            "existed. Every byte is explicit so no implicit `#[repr(C)]` pad desyncs",
+                            "off-chain borsh decoders. Do not reorder or resize."
                         ],
-                        "type": {
-                            "array": [
-                                "u8",
-                                8
-                            ]
-                        }
+                        "type": "u8"
+                    },
+                    {
+                        "name": "withdraw_circuit_breaker_bps",
+                        "docs": [
+                            "Daily withdraw circuit-breaker size: the max fraction of the 24h deposit",
+                            "TWAP that may be withdrawn per 24h window. `0` is treated as the default",
+                            "(2500 bps = 25%) so markets created before this field existed keep prior",
+                            "behavior. precision: basis points (10_000 = 100%)"
+                        ],
+                        "type": "u16"
+                    },
+                    {
+                        "name": "max_deposit_bps_per_day",
+                        "docs": [
+                            "Daily deposit rate limit: the max fraction above the 24h deposit TWAP that",
+                            "resulting deposits may reach per 24h window. Disabled when `0`.",
+                            "precision: basis points (10_000 = 100%)"
+                        ],
+                        "type": "u16"
+                    },
+                    {
+                        "name": "deposit_guard_threshold",
+                        "docs": [
+                            "No deposit rate limit when resulting deposits are below this threshold.",
+                            "Mirrors `withdraw_guard_threshold` on the deposit side.",
+                            "precision: token mint precision"
+                        ],
+                        "type": "u64"
                     },
                     {
                         "name": "protocol_fee_pool",
@@ -23042,13 +23212,33 @@
                         "type": "u32"
                     },
                     {
-                        "name": "padding",
-                        "type": {
-                            "array": [
-                                "u8",
-                                8
-                            ]
-                        }
+                        "name": "if_last_settle_vault_amount",
+                        "docs": [
+                            "Donation-proof accounted balance of the insurance-fund vault. It is moved",
+                            "by the same signed delta as the real SPL vault on *every* instruction that",
+                            "moves the vault, so it stays a faithful shadow of the vault minus raw",
+                            "donations. Inflows grow it: staker deposits (`add_insurance_fund_stake`)",
+                            "and settled revenue (`settle_revenue_to_insurance_fund`). Outflows/draws",
+                            "shrink it (saturating at 0): staker withdrawals",
+                            "(`remove_insurance_fund_stake`) and every IF draw that covers a loss —",
+                            "`resolve_perp_pnl_deficit`, `resolve_perp_bankruptcy`,",
+                            "`resolve_spot_bankruptcy`. The one movement deliberately *excluded* is a",
+                            "raw SPL transfer straight into the vault: it runs no instruction, so it",
+                            "never enters this balance — that is exactly the donation the shadow must",
+                            "not see. Consumed by the per-period revenue-settle APR cap in",
+                            "`settle_revenue_to_insurance_fund`, sized off `min(live_if_vault, this)`,",
+                            "so a donation spiked into the live vault right before a settle cannot",
+                            "inflate the cap while legitimate stakes and real settled revenue (which",
+                            "this balance tracks) still do. (The unstake-cancel share forfeiture is",
+                            "donation-proofed differently — by withdraw-and-restake at the active share",
+                            "price — and does *not* read this field.) Repurposed from trailing padding —",
+                            "layout/size unchanged; `0` means \"uninitialized\" (existing account",
+                            "pre-upgrade, or an accounted balance legitimately drained to empty — an",
+                            "empty IF vault has no user shares, so this is safe), and is seeded from the",
+                            "live balance on the next add/settle and treated as \"fall back to live\" by",
+                            "the consumers."
+                        ],
+                        "type": "u64"
                     }
                 ]
             }

package/lib/browser/math/amm.d.ts

@@ -29,7 +29,7 @@ export declare function calculatePegFromTargetPrice(targetPrice: BN, baseAssetRe
  *   available to spend, QUOTE_PRECISION (1e6); `checkLowerBound` tells the caller whether it
  *   must still verify the repeg doesn't push `totalFeeMinusDistributions` negative.
  */
-export declare function calculateOptimalPegAndBudget(amm: AMM, mmOraclePriceData: MMOraclePriceData): [BN, BN, BN, boolean];
+export declare function calculateOptimalPegAndBudget(amm: AMM, mmOraclePriceData: Pick<MMOraclePriceData, 'price'>): [BN, BN, BN, boolean];
 /**
  * Determines the full curve update (repeg cost, K scale factor, new peg) for `amm` against
  * the current oracle price, mirroring the "use full budget peg" fallback path of `adjust_amm`
@@ -46,7 +46,7 @@ export declare function calculateOptimalPegAndBudget(amm: AMM, mmOraclePriceData
  *   `calculateUpdatedAMM` whether it must still verify affordability against
  *   `totalFeeMinusDistributions`.
  */
-export declare function calculateNewAmm(amm: AMM, mmOraclePriceData: MMOraclePriceData): [BN, BN, BN, BN, boolean];
+export declare function calculateNewAmm(amm: AMM, mmOraclePriceData: Pick<MMOraclePriceData, 'price'>): [BN, BN, BN, BN, boolean];
 /**
  * Returns a copy of `amm` with its curve (peg, reserves, sqrtK) repegged/updated to the
  * current oracle price, or `amm` unchanged if no update applies. Mirrors the program's
@@ -63,7 +63,7 @@ export declare function calculateNewAmm(amm: AMM, mmOraclePriceData: MMOraclePri
  * @param mmOraclePriceData Current MM oracle price data; omit to skip the update entirely.
  * @returns Updated `AMM` (new object), or the original `amm` reference if no update applies or the affordability gate rejects it.
  */
-export declare function calculateUpdatedAMM(amm: AMM, mmOraclePriceData?: MMOraclePriceData): AMM;
+export declare function calculateUpdatedAMM(amm: AMM, mmOraclePriceData?: Pick<MMOraclePriceData, 'price'>): AMM;
 /**
  * Repegs `amm` to the current oracle price (`calculateUpdatedAMM`) and returns the
  * one-sided spread reserves (bid reserves for `short`, ask reserves for `long`) plus the
@@ -76,7 +76,7 @@ export declare function calculateUpdatedAMM(amm: AMM, mmOraclePriceData?: MMOrac
  * @param latestSlot Current slot, forwarded for reference-price-offset smoothing.
  * @returns `baseAssetReserve`/`quoteAssetReserve` for the requested side (AMM_RESERVE_PRECISION, 1e9), and the post-update `sqrtK`/`newPeg` (AMM_RESERVE_PRECISION 1e9 / PEG_PRECISION 1e6).
  */
-export declare function calculateUpdatedAMMSpreadReserves(amm: AMM, marketStats: MarketStats, direction: PositionDirection, mmOraclePriceData?: MMOraclePriceData, latestSlot?: BN): {
+export declare function calculateUpdatedAMMSpreadReserves(amm: AMM, marketStats: MarketStats, direction: PositionDirection, mmOraclePriceData?: Pick<MMOraclePriceData, 'price' | 'confidence'>, latestSlot?: BN): {
     baseAssetReserve: BN;
     quoteAssetReserve: BN;
     sqrtK: BN;
@@ -92,7 +92,7 @@ export declare function calculateUpdatedAMMSpreadReserves(amm: AMM, marketStats:
  * @param latestSlot Current slot, forwarded for reference-price-offset smoothing.
  * @returns `[bidPrice, askPrice]`, both PRICE_PRECISION (1e6).
  */
-export declare function calculateBidAskPrice(amm: AMM, marketStats: MarketStats, mmOraclePriceData?: MMOraclePriceData, withUpdate?: boolean, latestSlot?: BN): [BN, BN];
+export declare function calculateBidAskPrice(amm: AMM, marketStats: MarketStats, mmOraclePriceData?: Pick<MMOraclePriceData, 'price' | 'confidence'>, withUpdate?: boolean, latestSlot?: BN): [BN, BN];
 /**
  * Computes the constant-product price implied by a pair of AMM reserves and a peg multiplier:
  * `quoteAssetReserves * pegMultiplier / baseAssetReserves`, converted to `PRICE_PRECISION`.
@@ -338,7 +338,7 @@ export declare function calculateSpreadBN(baseSpread: number, lastOracleReserveP
  * @throws if `oraclePriceData` is omitted while `baseSpread` and `curveUpdateIntensity` are both nonzero.
  * @returns `[longSpread, shortSpread]`, both BID_ASK_SPREAD_PRECISION (1e6) fraction-of-price units.
  */
-export declare function calculateSpread(amm: AMM, marketStats: MarketStats, oraclePriceData?: OraclePriceData, now?: BN, reservePrice?: BN): [number, number];
+export declare function calculateSpread(amm: AMM, marketStats: MarketStats, oraclePriceData?: Pick<OraclePriceData, 'price' | 'confidence'>, now?: BN, reservePrice?: BN): [number, number];
 /**
  * Computes the AMM's one-sided bid and ask reserves — the reserves a long (ask side) or short
  * (bid side) trade would actually execute against — by combining `calculateSpread`'s
@@ -357,7 +357,7 @@ export declare function calculateSpread(amm: AMM, marketStats: MarketStats, orac
  * @param latestSlot Current slot; required for reference-price-offset smoothing to take effect (treated as 0 slots elapsed if omitted).
  * @returns `[bidReserves, askReserves]`, each `{ baseAssetReserve, quoteAssetReserve }` in AMM_RESERVE_PRECISION (1e9).
  */
-export declare function calculateSpreadReserves(amm: AMM, marketStats: MarketStats, mmOraclePriceData?: MMOraclePriceData, now?: BN, latestSlot?: BN): {
+export declare function calculateSpreadReserves(amm: AMM, marketStats: MarketStats, mmOraclePriceData?: Pick<MMOraclePriceData, 'price' | 'confidence'>, now?: BN, latestSlot?: BN): {
     baseAssetReserve: BN;
     quoteAssetReserve: BN;
 }[];
@@ -407,7 +407,7 @@ export declare function calculateTerminalPrice(market: PerpMarketAccount): BN;
  * @param now Current unix timestamp (seconds), forwarded to `calculateSpreadReserves`.
  * @returns `[baseAssetAmount, direction]`: `baseAssetAmount` is AMM_RESERVE_PRECISION (1e9), zero if the trade size would round to nothing.
  */
-export declare function calculateMaxBaseAssetAmountToTrade(amm: AMM, marketStats: MarketStats, limit_price: BN, direction: PositionDirection, mmOraclePriceData: MMOraclePriceData, now?: BN): [BN, PositionDirection];
+export declare function calculateMaxBaseAssetAmountToTrade(amm: AMM, marketStats: MarketStats, limit_price: BN, direction: PositionDirection, mmOraclePriceData: Pick<MMOraclePriceData, 'price' | 'confidence'>, now?: BN): [BN, PositionDirection];
 /**
  * Converts a quote-asset AMM reserve amount into the actual quote asset amount swapped
  * (applying the peg multiplier), rounding by 1 in the direction that favors the AMM when

package/lib/browser/math/funding.d.ts

@@ -26,7 +26,7 @@ import { MMOraclePriceData, OraclePriceData } from '../oracles/types';
  *     straight-line interpolation; `lowerboundEst` further scales the spread down by the
  *     fraction of the current funding period that has elapsed since the last update.
  */
-export declare function calculateAllEstimatedFundingRate(market: PerpMarketAccount, mmOraclePriceData?: MMOraclePriceData, oraclePriceData?: OraclePriceData, markPrice?: BN, now?: BN): [BN, BN, BN, BN, BN];
+export declare function calculateAllEstimatedFundingRate(market: PerpMarketAccount, mmOraclePriceData?: Pick<MMOraclePriceData, 'price' | 'confidence'>, oraclePriceData?: Pick<OraclePriceData, 'price'>, markPrice?: BN, now?: BN): [BN, BN, BN, BN, BN];
 /**
  * Calculates estimated funding rates in human-readable form (plain JS `number` percentages,
  * not BN), including a plain-English summary sentence. Values pass through floating-point
@@ -68,7 +68,7 @@ export declare function calculateLongShortFundingRate(market: PerpMarketAccount,
  * @param now Current unix timestamp (seconds); defaults to wall-clock time.
  * @returns `[markTwapLive, oracleTwapLive, longFundingRateEst, shortFundingRateEst]` — TWAPs in PRICE_PRECISION (1e6), rate estimates in the same scale as `calculateAllEstimatedFundingRate`.
  */
-export declare function calculateLongShortFundingRateAndLiveTwaps(market: PerpMarketAccount, mmOraclePriceData?: MMOraclePriceData, oraclePriceData?: OraclePriceData, markPrice?: BN, now?: BN): [BN, BN, BN, BN];
+export declare function calculateLongShortFundingRateAndLiveTwaps(market: PerpMarketAccount, mmOraclePriceData?: MMOraclePriceData, oraclePriceData?: Pick<OraclePriceData, 'price'>, markPrice?: BN, now?: BN): [BN, BN, BN, BN];
 /**
  * Estimated quote pool available to top up the smaller side's funding payment shortfall:
  * one-third of the AMM's own retained equity (`totalFeeMinusDistributions`), floored at

package/lib/browser/math/liquidation.d.ts

@@ -85,6 +85,37 @@ export declare function calculatePerpIfFee(marginShortage: BN, userBaseAssetAmou
  *   `liabilityLiquidationMultiplier` is zero.
  */
 export declare function calculateSpotIfFee(marginShortage: BN, tokenAmount: BN, assetWeight: number, assetLiquidationMultiplier: number, liabilityWeight: number, liabilityLiquidationMultiplier: number, liabilityDecimals: number, liabilityPrice: BN, maxIfFee: number): number;
+/**
+ * User-protective price at which a collateral (deposit) asset is seized when its oracle is
+ * margin-invalid (`StaleForMargin`/`TooUncertain`) but still acceptable for
+ * `VelocityAction::Liquidate`, mirroring `calculate_user_protective_asset_price` in
+ * `programs/velocity/src/math/liquidation.rs`. The program sizes the asset-conversion leg
+ * of spot and pnl-vs-spot liquidations (and the swap-liquidation worst-case price) with this
+ * instead of the raw oracle price whenever the deposit oracle fails the margin-calc validity
+ * gate — a stale or uncertain oracle can make an account liquidatable but cannot cheapen its
+ * collateral. Pass the result as `assetPrice` to `calculateAssetTransferForLiabilityTransfer`
+ * to predict on-chain transfer amounts in that case.
+ * @param oraclePrice Raw oracle price of the asset, PRICE_PRECISION (1e6).
+ * @param oracleConfidence Oracle confidence interval, PRICE_PRECISION (1e6).
+ * @param lastOraclePriceTwap5Min The asset spot market's `historicalOracleData.lastOraclePriceTwap5Min`, PRICE_PRECISION (1e6).
+ * @returns `max(oraclePrice, lastOraclePriceTwap5Min, oraclePrice + oracleConfidence)`, PRICE_PRECISION (1e6).
+ */
+export declare function calculateUserProtectiveAssetPrice(oraclePrice: BN, oracleConfidence: BN, lastOraclePriceTwap5Min: BN): BN;
+/**
+ * Liability-side counterpart of `calculateUserProtectiveAssetPrice`, mirroring
+ * `calculate_user_protective_liability_price` in
+ * `programs/velocity/src/math/liquidation.rs`. When the borrow (liability) oracle is
+ * margin-invalid, the program prices the repayment leg of spot and pnl-vs-spot liquidations
+ * (and the swap-liquidation worst-case price) at this instead of the raw oracle price, so an
+ * inflated stale/uncertain debt price cannot cheapen the collateral (or pnl) exchanged for
+ * it. Pass the result as `liabilityPrice` to `calculateAssetTransferForLiabilityTransfer` to
+ * predict on-chain transfer amounts in that case.
+ * @param oraclePrice Raw oracle price of the liability, PRICE_PRECISION (1e6).
+ * @param oracleConfidence Oracle confidence interval, PRICE_PRECISION (1e6).
+ * @param lastOraclePriceTwap5Min The liability spot market's `historicalOracleData.lastOraclePriceTwap5Min`, PRICE_PRECISION (1e6).
+ * @returns `min(oraclePrice, lastOraclePriceTwap5Min, oraclePrice - oracleConfidence)`, floored at 1, PRICE_PRECISION (1e6).
+ */
+export declare function calculateUserProtectiveLiabilityPrice(oraclePrice: BN, oracleConfidence: BN, lastOraclePriceTwap5Min: BN): BN;
 /**
  * Calculates how much of a liquidated user's collateral asset a liquidator receives in
  * exchange for repaying `liabilityAmount` of a liability, mirroring
@@ -97,11 +128,15 @@ export declare function calculateSpotIfFee(marginShortage: BN, tokenAmount: BN,
  * @param assetAmount User's available balance of the asset being transferred, asset spot market's own token precision.
  * @param assetLiquidationMultiplier Liquidation-time discount multiplier on the asset side, LIQUIDATION_FEE_PRECISION (1e6).
  * @param assetDecimals Asset spot market's token decimals.
- * @param assetPrice Oracle price of the asset, PRICE_PRECISION (1e6).
+ * @param assetPrice Oracle price of the asset, PRICE_PRECISION (1e6). When the asset oracle
+ *   is margin-invalid, the program prices the seizure protectively — pass
+ *   `calculateUserProtectiveAssetPrice(...)` instead of the raw oracle price to match.
  * @param liabilityAmount Liability amount being repaid, liability spot market's own token precision.
  * @param liabilityLiquidationMultiplier Liquidation-time premium multiplier on the liability side, LIQUIDATION_FEE_PRECISION (1e6).
  * @param liabilityDecimals Liability spot market's token decimals.
- * @param liabilityPrice Oracle price of the liability asset, PRICE_PRECISION (1e6).
+ * @param liabilityPrice Oracle price of the liability asset, PRICE_PRECISION (1e6). When the
+ *   liability oracle is margin-invalid, the program prices the repayment protectively — pass
+ *   `calculateUserProtectiveLiabilityPrice(...)` instead of the raw oracle price to match.
  * @returns Asset amount to transfer to the liquidator, asset spot market's own token precision (floored at 1).
  */
 export declare function calculateAssetTransferForLiabilityTransfer(assetAmount: BN, assetLiquidationMultiplier: number, assetDecimals: number, assetPrice: BN, liabilityAmount: BN, liabilityLiquidationMultiplier: number, liabilityDecimals: number, liabilityPrice: BN): BN | undefined;

package/lib/browser/math/liquidation.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getMarginShortage = exports.calculateMaxPctToLiquidate = exports.calculateAssetTransferForLiabilityTransfer = exports.calculateSpotIfFee = exports.calculatePerpIfFee = exports.calculateLiabilityTransferToCoverMarginShortage = exports.calculateBaseAssetAmountToCoverMarginShortage = void 0;
+exports.getMarginShortage = exports.calculateMaxPctToLiquidate = exports.calculateAssetTransferForLiabilityTransfer = exports.calculateUserProtectiveLiabilityPrice = exports.calculateUserProtectiveAssetPrice = exports.calculateSpotIfFee = exports.calculatePerpIfFee = exports.calculateLiabilityTransferToCoverMarginShortage = exports.calculateBaseAssetAmountToCoverMarginShortage = void 0;
 const anchor_1 = require("../isomorphic/anchor");
 const numericConstants_1 = require("../constants/numericConstants");
 /**
@@ -188,6 +188,43 @@ function calculateSpotIfFee(marginShortage, tokenAmount, assetWeight, assetLiqui
     return anchor_1.BN.min(new anchor_1.BN(maxIfFee), impliedIfFee).toNumber();
 }
 exports.calculateSpotIfFee = calculateSpotIfFee;
+/**
+ * User-protective price at which a collateral (deposit) asset is seized when its oracle is
+ * margin-invalid (`StaleForMargin`/`TooUncertain`) but still acceptable for
+ * `VelocityAction::Liquidate`, mirroring `calculate_user_protective_asset_price` in
+ * `programs/velocity/src/math/liquidation.rs`. The program sizes the asset-conversion leg
+ * of spot and pnl-vs-spot liquidations (and the swap-liquidation worst-case price) with this
+ * instead of the raw oracle price whenever the deposit oracle fails the margin-calc validity
+ * gate — a stale or uncertain oracle can make an account liquidatable but cannot cheapen its
+ * collateral. Pass the result as `assetPrice` to `calculateAssetTransferForLiabilityTransfer`
+ * to predict on-chain transfer amounts in that case.
+ * @param oraclePrice Raw oracle price of the asset, PRICE_PRECISION (1e6).
+ * @param oracleConfidence Oracle confidence interval, PRICE_PRECISION (1e6).
+ * @param lastOraclePriceTwap5Min The asset spot market's `historicalOracleData.lastOraclePriceTwap5Min`, PRICE_PRECISION (1e6).
+ * @returns `max(oraclePrice, lastOraclePriceTwap5Min, oraclePrice + oracleConfidence)`, PRICE_PRECISION (1e6).
+ */
+function calculateUserProtectiveAssetPrice(oraclePrice, oracleConfidence, lastOraclePriceTwap5Min) {
+    return anchor_1.BN.max(anchor_1.BN.max(oraclePrice, lastOraclePriceTwap5Min), oraclePrice.add(oracleConfidence));
+}
+exports.calculateUserProtectiveAssetPrice = calculateUserProtectiveAssetPrice;
+/**
+ * Liability-side counterpart of `calculateUserProtectiveAssetPrice`, mirroring
+ * `calculate_user_protective_liability_price` in
+ * `programs/velocity/src/math/liquidation.rs`. When the borrow (liability) oracle is
+ * margin-invalid, the program prices the repayment leg of spot and pnl-vs-spot liquidations
+ * (and the swap-liquidation worst-case price) at this instead of the raw oracle price, so an
+ * inflated stale/uncertain debt price cannot cheapen the collateral (or pnl) exchanged for
+ * it. Pass the result as `liabilityPrice` to `calculateAssetTransferForLiabilityTransfer` to
+ * predict on-chain transfer amounts in that case.
+ * @param oraclePrice Raw oracle price of the liability, PRICE_PRECISION (1e6).
+ * @param oracleConfidence Oracle confidence interval, PRICE_PRECISION (1e6).
+ * @param lastOraclePriceTwap5Min The liability spot market's `historicalOracleData.lastOraclePriceTwap5Min`, PRICE_PRECISION (1e6).
+ * @returns `min(oraclePrice, lastOraclePriceTwap5Min, oraclePrice - oracleConfidence)`, floored at 1, PRICE_PRECISION (1e6).
+ */
+function calculateUserProtectiveLiabilityPrice(oraclePrice, oracleConfidence, lastOraclePriceTwap5Min) {
+    return anchor_1.BN.max(anchor_1.BN.min(anchor_1.BN.min(oraclePrice, lastOraclePriceTwap5Min), oraclePrice.sub(oracleConfidence)), numericConstants_1.ONE);
+}
+exports.calculateUserProtectiveLiabilityPrice = calculateUserProtectiveLiabilityPrice;
 /**
  * Calculates how much of a liquidated user's collateral asset a liquidator receives in
  * exchange for repaying `liabilityAmount` of a liability, mirroring
@@ -200,11 +237,15 @@ exports.calculateSpotIfFee = calculateSpotIfFee;
  * @param assetAmount User's available balance of the asset being transferred, asset spot market's own token precision.
  * @param assetLiquidationMultiplier Liquidation-time discount multiplier on the asset side, LIQUIDATION_FEE_PRECISION (1e6).
  * @param assetDecimals Asset spot market's token decimals.
- * @param assetPrice Oracle price of the asset, PRICE_PRECISION (1e6).
+ * @param assetPrice Oracle price of the asset, PRICE_PRECISION (1e6). When the asset oracle
+ *   is margin-invalid, the program prices the seizure protectively — pass
+ *   `calculateUserProtectiveAssetPrice(...)` instead of the raw oracle price to match.
  * @param liabilityAmount Liability amount being repaid, liability spot market's own token precision.
  * @param liabilityLiquidationMultiplier Liquidation-time premium multiplier on the liability side, LIQUIDATION_FEE_PRECISION (1e6).
  * @param liabilityDecimals Liability spot market's token decimals.
- * @param liabilityPrice Oracle price of the liability asset, PRICE_PRECISION (1e6).
+ * @param liabilityPrice Oracle price of the liability asset, PRICE_PRECISION (1e6). When the
+ *   liability oracle is margin-invalid, the program prices the repayment protectively — pass
+ *   `calculateUserProtectiveLiabilityPrice(...)` instead of the raw oracle price to match.
  * @returns Asset amount to transfer to the liquidator, asset spot market's own token precision (floored at 1).
  */
 function calculateAssetTransferForLiabilityTransfer(assetAmount, assetLiquidationMultiplier, assetDecimals, assetPrice, liabilityAmount, liabilityLiquidationMultiplier, liabilityDecimals, liabilityPrice) {

package/lib/browser/math/market.d.ts

@@ -141,10 +141,11 @@ export declare function calculateNetUserPnlImbalance(perpMarket: PerpMarketAccou
 /**
  * Calculates the price used to evaluate trigger (stop/take-profit) orders for a perp market,
  * mirroring the Rust `get_trigger_price`. When `useMedianPrice` is true, the trigger price is the
- * median of three candidates — the last fill price (or oracle price if there's been no fill), the
- * oracle price adjusted by the implied funding basis, and the oracle price adjusted by the 5min
- * mark/oracle TWAP basis — then clamped to within a contract-tier-dependent band around the raw
- * oracle price (tier A/B: 20bps, tier C: 100bps, others: 250bps) via `clampTriggerPrice`. This
+ * median of three candidates — the last fill price (or oracle price if there's been no fill or the
+ * last fill is older than `TRIGGER_PRICE_LAST_FILL_MAX_AGE`), the oracle price adjusted by the
+ * implied funding basis, and the oracle price adjusted by the 5min mark/oracle TWAP basis — then
+ * clamped to within a contract-tier-dependent band around the raw oracle price (tier A/B: 20bps,
+ * tier C: 100bps, others: 250bps) via `clampTriggerPrice`. This
  * resists a single manipulated print (last fill or a momentary oracle/mark divergence) from
  * triggering orders it shouldn't. When `useMedianPrice` is false, the raw oracle price is used
  * directly with no smoothing.