@velocity-exchange/sdk 0.1.0 → 0.2.1

package/src/index.ts

@@ -107,13 +107,11 @@ export * from './tx/fastSingleTxSender';
 export * from './tx/retryTxSender';
 export * from './tx/whileValidTxSender';
 export * from './tx/priorityFeeCalculator';
-export * from './tx/forwardOnlyTxSender';
 export * from './tx/types';
 export * from './tx/txHandler';
 export * from './tx/txParamProcessor';
 export * from './util/computeUnits';
 export * from './util/digest';
-export * from './util/tps';
 export * from './util/promiseTimeout';
 export * from './math/spotBalance';
 export * from './velocityClientConfig';

package/src/jupiter/jupiterClient.ts

@@ -6,7 +6,7 @@ import {
 	TransactionMessage,
 	VersionedTransaction,
 } from '@solana/web3.js';
-import fetch from 'node-fetch';
+import fetch, { RequestInit } from 'node-fetch';
 import { BN } from '../isomorphic/anchor';
 import { SwapMode } from '../swap/UnifiedSwapClient';
 
@@ -302,6 +302,22 @@ export class JupiterClient {
 		maxAutoSlippageBps?: number;
 		usdEstimate?: number;
 	}): Promise<QuoteResponse> {
+		if (autoSlippage && maxAutoSlippageBps === undefined) {
+			throw new Error(
+				'JupiterClient.getQuote: maxAutoSlippageBps is required when autoSlippage is enabled'
+			);
+		}
+		if (autoSlippage && usdEstimate === undefined) {
+			throw new Error(
+				'JupiterClient.getQuote: usdEstimate is required when autoSlippage is enabled'
+			);
+		}
+		const maxAutoSlippageBpsParam =
+			autoSlippage && maxAutoSlippageBps !== undefined
+				? maxAutoSlippageBps.toString()
+				: '0';
+		const autoSlippageCollisionUsdValueParam =
+			autoSlippage && usdEstimate !== undefined ? usdEstimate.toString() : '0';
 		const params = new URLSearchParams({
 			inputMint: inputMint.toString(),
 			outputMint: outputMint.toString(),
@@ -311,10 +327,8 @@ export class JupiterClient {
 			onlyDirectRoutes: onlyDirectRoutes.toString(),
 			maxAccounts: maxAccounts.toString(),
 			autoSlippage: autoSlippage.toString(),
-			maxAutoSlippageBps: autoSlippage ? maxAutoSlippageBps.toString() : '0',
-			autoSlippageCollisionUsdValue: autoSlippage
-				? usdEstimate.toString()
-				: '0',
+			maxAutoSlippageBps: maxAutoSlippageBpsParam,
+			autoSlippageCollisionUsdValue: autoSlippageCollisionUsdValueParam,
 			...(excludeDexes && { excludeDexes: excludeDexes.join(',') }),
 		});
 		if (swapMode === 'ExactOut') {
@@ -409,7 +423,9 @@ export class JupiterClient {
 					return await this.getLookupTable(lookup.accountKey);
 				})
 			)
-		).filter((lookup) => lookup);
+		).filter(
+			(lookup): lookup is AddressLookupTableAccount => lookup !== undefined
+		);
 
 		const transactionMessage = TransactionMessage.decompile(message, {
 			addressLookupTableAccounts: lookupTables,
@@ -422,12 +438,16 @@ export class JupiterClient {
 
 	async getLookupTable(
 		accountKey: PublicKey
-	): Promise<AddressLookupTableAccount> {
-		if (this.lookupTableCahce.has(accountKey.toString())) {
-			return this.lookupTableCahce.get(accountKey.toString());
+	): Promise<AddressLookupTableAccount | undefined> {
+		const cached = this.lookupTableCahce.get(accountKey.toString());
+		if (cached !== undefined) {
+			return cached;
 		}
 
-		return (await this.connection.getAddressLookupTable(accountKey)).value;
+		return (
+			(await this.connection.getAddressLookupTable(accountKey)).value ??
+			undefined
+		);
 	}
 
 	/**

package/src/marginCalculation.ts

@@ -48,6 +48,7 @@ export class MarginContext {
 		this.strict = false;
 		this.ignoreInvalidDepositOracles = false;
 		this.isolatedMarginBuffers = new Map();
+		this.crossMarginBuffer = ZERO;
 	}
 
 	static standard(marginType: MarginCategory): MarginContext {

package/src/marinade/index.ts

@@ -11,10 +11,19 @@ const marinadeFinanceProgramId = new PublicKey(
 	'MarBmsSgKXdrN1egZf5sqe1TMai9K1rChYNDJgjq7aD'
 );
 
+// The Marinade SDK is built against anchor 0.29 (3-arg `new Program`), so the
+// provider is typed against the anchor29 shim. Callers hold an anchor 1.0
+// AnchorProvider, which is runtime-compatible but nominally distinct — accept it
+// loosely and narrow at the construction boundary rather than leaking the cast to
+// every call site.
 export function getMarinadeFinanceProgram(
-	provider: AnchorProvider
+	provider: unknown
 ): Program<MarinadeFinance> {
-	return new Program<MarinadeFinance>(IDL, marinadeFinanceProgramId, provider);
+	return new Program<MarinadeFinance>(
+		IDL,
+		marinadeFinanceProgramId,
+		provider as AnchorProvider
+	);
 }
 
 export function getMarinadeDepositIx({

package/src/math/amm.ts

@@ -8,11 +8,11 @@ import {
 	ONE,
 	AMM_TO_QUOTE_PRECISION_RATIO,
 	QUOTE_PRECISION,
-	MARGIN_PRECISION,
 	PRICE_DIV_PEG,
 	PERCENTAGE_PRECISION,
 	DEFAULT_REVENUE_SINCE_LAST_FUNDING_SPREAD_RETREAT,
 	FUNDING_RATE_BUFFER_PRECISION,
+	FUNDING_RATE_OFFSET_PERCENTAGE,
 	TWO,
 } from '../constants/numericConstants';
 import {
@@ -53,7 +53,6 @@ export function calculatePegFromTargetPrice(
 
 export function calculateOptimalPegAndBudget(
 	amm: AMM,
-	totalExchangeFee: BN,
 	mmOraclePriceData: MMOraclePriceData
 ): [BN, BN, BN, boolean] {
 	const reservePriceBefore = calculatePrice(
@@ -69,8 +68,9 @@ export function calculateOptimalPegAndBudget(
 	);
 	const prePegCost = calculateRepegCost(amm, newPeg);
 
-	const totalFeeLB = totalExchangeFee.div(new BN(2));
-	const budget = BN.max(ZERO, amm.totalFeeMinusDistributions.sub(totalFeeLB));
+	// no protocol floor post-isolation: tfmd contains only the AMM's own
+	// equity and is fully spendable on the repeg
+	const budget = BN.max(ZERO, amm.totalFeeMinusDistributions);
 
 	let checkLowerBound = true;
 	if (budget.lt(prePegCost)) {
@@ -103,9 +103,9 @@ export function calculateOptimalPegAndBudget(
 			checkLowerBound = false;
 
 			return [newTargetPrice, newOptimalPeg, newBudget, false];
-		} else if (
-			amm.totalFeeMinusDistributions.lt(totalExchangeFee.div(new BN(2)))
-		) {
+		} else if (budget.eq(ZERO)) {
+			// mirrors the program: budget = max(0, tfmd), so a zero budget
+			// means the AMM has no equity to spend (no floor post-isolation)
 			checkLowerBound = false;
 		}
 	}
@@ -115,14 +115,13 @@ export function calculateOptimalPegAndBudget(
 
 export function calculateNewAmm(
 	amm: AMM,
-	totalExchangeFee: BN,
 	mmOraclePriceData: MMOraclePriceData
 ): [BN, BN, BN, BN] {
 	let pKNumer = new BN(1);
 	let pKDenom = new BN(1);
 
 	const [targetPrice, _newPeg, budget, _checkLowerBound] =
-		calculateOptimalPegAndBudget(amm, totalExchangeFee, mmOraclePriceData);
+		calculateOptimalPegAndBudget(amm, mmOraclePriceData);
 	let prePegCost = calculateRepegCost(amm, _newPeg);
 	let newPeg = _newPeg;
 
@@ -158,8 +157,7 @@ export function calculateNewAmm(
 
 export function calculateUpdatedAMM(
 	amm: AMM,
-	totalExchangeFee: BN,
-	mmOraclePriceData: MMOraclePriceData
+	mmOraclePriceData?: MMOraclePriceData
 ): AMM {
 	if (amm.curveUpdateIntensity == 0 || mmOraclePriceData === undefined) {
 		return amm;
@@ -167,7 +165,6 @@ export function calculateUpdatedAMM(
 	const newAmm = Object.assign({}, amm);
 	const [prepegCost, pKNumer, pKDenom, newPeg] = calculateNewAmm(
 		amm,
-		totalExchangeFee,
 		mmOraclePriceData
 	);
 
@@ -201,12 +198,11 @@ export function calculateUpdatedAMM(
 export function calculateUpdatedAMMSpreadReserves(
 	amm: AMM,
 	marketStats: MarketStats,
-	totalExchangeFee: BN,
 	direction: PositionDirection,
-	mmOraclePriceData: MMOraclePriceData,
+	mmOraclePriceData?: MMOraclePriceData,
 	latestSlot?: BN
 ): { baseAssetReserve: BN; quoteAssetReserve: BN; sqrtK: BN; newPeg: BN } {
-	const newAmm = calculateUpdatedAMM(amm, totalExchangeFee, mmOraclePriceData);
+	const newAmm = calculateUpdatedAMM(amm, mmOraclePriceData);
 	const [shortReserves, longReserves] = calculateSpreadReserves(
 		newAmm,
 		marketStats,
@@ -232,14 +228,13 @@ export function calculateUpdatedAMMSpreadReserves(
 export function calculateBidAskPrice(
 	amm: AMM,
 	marketStats: MarketStats,
-	totalExchangeFee: BN,
-	mmOraclePriceData: MMOraclePriceData,
+	mmOraclePriceData?: MMOraclePriceData,
 	withUpdate = true,
 	latestSlot?: BN
 ): [BN, BN] {
 	let newAmm: AMM;
 	if (withUpdate) {
-		newAmm = calculateUpdatedAMM(amm, totalExchangeFee, mmOraclePriceData);
+		newAmm = calculateUpdatedAMM(amm, mmOraclePriceData);
 	} else {
 		newAmm = amm;
 	}
@@ -557,14 +552,6 @@ export function calculateEffectiveLeverage(
 	return effectiveLeverage;
 }
 
-export function calculateMaxSpread(marginRatioInitial: number): number {
-	const maxTargetSpread: number = new BN(marginRatioInitial)
-		.mul(BID_ASK_SPREAD_PRECISION.div(MARGIN_PRECISION))
-		.toNumber();
-
-	return maxTargetSpread;
-}
-
 export function calculateVolSpreadBN(
 	lastOracleConfPct: BN,
 	reservePrice: BN,
@@ -614,6 +601,81 @@ export function calculateVolSpreadBN(
 	return [longVolSpread, shortVolSpread];
 }
 
+/**
+ * Funding bias β(f) (BID_ASK_SPREAD_PRECISION): bounded multiplier for the
+ * paying-side spread while the vAMM is paying funding. Mirrors the program's
+ * `calculate_spread_funding_bias_scale`.
+ *
+ *   ρ(f) = clamp(|f| / f_ref, 0, 1),  f_ref = FUNDING_RATE_OFFSET_PERCENTAGE
+ *   β(f) = 1 + s * ρ(f),              s = fundingBiasSensitivity / 100
+ *
+ * f = 24h avg funding rate normalized to a daily fraction of the oracle twap
+ * captured at the last funding update. The vAMM pays when f * q < 0
+ * (q = baseAssetAmountWithAmm). Returns 1x when the vAMM receives funding or
+ * s = 0.
+ */
+export function calculateSpreadFundingBiasScale(
+	baseAssetAmountWithAmm: BN,
+	last24HAvgFundingRate: BN,
+	lastFundingOracleTwap: BN,
+	fundingBiasSensitivity: number
+): number {
+	const one = BID_ASK_SPREAD_PRECISION.toNumber();
+	if (fundingBiasSensitivity === 0 || lastFundingOracleTwap.lte(ZERO)) {
+		return one;
+	}
+
+	// f: daily funding rate as a fraction of price, FUNDING_RATE_PRECISION
+	const fNorm = last24HAvgFundingRate
+		.mul(PRICE_PRECISION)
+		.div(lastFundingOracleTwap)
+		.muln(24);
+
+	// f * q >= 0: vAMM receives (or rate/inventory is zero), β = 1
+	if (fNorm.isZero() || baseAssetAmountWithAmm.isZero()) {
+		return one;
+	}
+	if (fNorm.isNeg() === baseAssetAmountWithAmm.isNeg()) {
+		return one;
+	}
+
+	// ρ = clamp(|f| / f_ref, 0, 1), PERCENTAGE_PRECISION
+	const ramp = BN.min(
+		fNorm.abs().mul(PERCENTAGE_PRECISION).div(FUNDING_RATE_OFFSET_PERCENTAGE),
+		PERCENTAGE_PRECISION
+	).toNumber();
+
+	// β = 1 + s * ρ
+	return one + Math.floor((fundingBiasSensitivity * ramp) / 100);
+}
+
+export interface SpreadTerms {
+	longVolSpread: number;
+	shortVolSpread: number;
+	longSpreadwPS: number;
+	shortSpreadwPS: number;
+	maxTargetSpread: number;
+	inventorySpreadScale: number;
+	longSpreadwInvScale: number;
+	shortSpreadwInvScale: number;
+	effectiveLeverage: number;
+	effectiveLeverageCapped: number;
+	longSpreadwEL: number;
+	shortSpreadwEL: number;
+	revenueRetreatAmount: number;
+	halfRevenueRetreatAmount: number;
+	longSpreadwRevRetreat: number;
+	shortSpreadwRevRetreat: number;
+	fundingBiasScale: number;
+	longSpreadwFundingBias: number;
+	shortSpreadwFundingBias: number;
+	longSpreadwOffsetShrink: number;
+	shortSpreadwOffsetShrink: number;
+	totalSpread: number;
+	longSpread: number;
+	shortSpread: number;
+}
+
 export function calculateSpreadBN(
 	baseSpread: number,
 	lastOracleReservePriceSpreadPct: BN,
@@ -635,8 +697,63 @@ export function calculateSpreadBN(
 	shortIntensity: BN,
 	volume24H: BN,
 	ammInventorySpreadAdjustment: number,
+	last24HAvgFundingRate?: BN,
+	lastFundingOracleTwap?: BN,
+	fundingBiasSensitivity?: number,
+	returnTerms?: false
+): [number, number];
+export function calculateSpreadBN(
+	baseSpread: number,
+	lastOracleReservePriceSpreadPct: BN,
+	lastOracleConfPct: BN,
+	maxSpread: number,
+	quoteAssetReserve: BN,
+	terminalQuoteAssetReserve: BN,
+	pegMultiplier: BN,
+	baseAssetAmountWithAmm: BN,
+	reservePrice: BN,
+	totalFeeMinusDistributions: BN,
+	netRevenueSinceLastFunding: BN,
+	baseAssetReserve: BN,
+	minBaseAssetReserve: BN,
+	maxBaseAssetReserve: BN,
+	markStd: BN,
+	oracleStd: BN,
+	longIntensity: BN,
+	shortIntensity: BN,
+	volume24H: BN,
+	ammInventorySpreadAdjustment: number,
+	last24HAvgFundingRate: BN,
+	lastFundingOracleTwap: BN,
+	fundingBiasSensitivity: number,
+	returnTerms: true
+): SpreadTerms;
+export function calculateSpreadBN(
+	baseSpread: number,
+	lastOracleReservePriceSpreadPct: BN,
+	lastOracleConfPct: BN,
+	maxSpread: number,
+	quoteAssetReserve: BN,
+	terminalQuoteAssetReserve: BN,
+	pegMultiplier: BN,
+	baseAssetAmountWithAmm: BN,
+	reservePrice: BN,
+	totalFeeMinusDistributions: BN,
+	netRevenueSinceLastFunding: BN,
+	baseAssetReserve: BN,
+	minBaseAssetReserve: BN,
+	maxBaseAssetReserve: BN,
+	markStd: BN,
+	oracleStd: BN,
+	longIntensity: BN,
+	shortIntensity: BN,
+	volume24H: BN,
+	ammInventorySpreadAdjustment: number,
+	last24HAvgFundingRate: BN = ZERO,
+	lastFundingOracleTwap: BN = ZERO,
+	fundingBiasSensitivity = 0,
 	returnTerms = false
-) {
+): [number, number] | SpreadTerms {
 	assert(Number.isInteger(baseSpread));
 	assert(Number.isInteger(maxSpread));
 
@@ -657,6 +774,9 @@ export function calculateSpreadBN(
 		halfRevenueRetreatAmount: 0,
 		longSpreadwRevRetreat: 0,
 		shortSpreadwRevRetreat: 0,
+		fundingBiasScale: 0,
+		longSpreadwFundingBias: 0,
+		shortSpreadwFundingBias: 0,
 		longSpreadwOffsetShrink: 0,
 		shortSpreadwOffsetShrink: 0,
 		totalSpread: 0,
@@ -803,6 +923,32 @@ export function calculateSpreadBN(
 	spreadTerms.longSpreadwRevRetreat = longSpread;
 	spreadTerms.shortSpreadwRevRetreat = shortSpread;
 
+	// funding bias: w_pay = min(w_max, (w_0 * σ(q) * λ(q) + r(q)) * β(f)).
+	// β multiplies the fully built paying side only, selected by sign(q)
+	// (the same side σ widens); the max-spread cap below still bounds it.
+	// β = 1 when the vAMM receives.
+	const fundingBiasScale = calculateSpreadFundingBiasScale(
+		baseAssetAmountWithAmm,
+		last24HAvgFundingRate,
+		lastFundingOracleTwap,
+		fundingBiasSensitivity
+	);
+	const spreadPrecision = BID_ASK_SPREAD_PRECISION.toNumber();
+	if (fundingBiasScale > spreadPrecision) {
+		if (baseAssetAmountWithAmm.gt(ZERO)) {
+			longSpread = Math.floor(
+				(longSpread * fundingBiasScale) / spreadPrecision
+			);
+		} else if (baseAssetAmountWithAmm.lt(ZERO)) {
+			shortSpread = Math.floor(
+				(shortSpread * fundingBiasScale) / spreadPrecision
+			);
+		}
+	}
+	spreadTerms.fundingBiasScale = fundingBiasScale;
+	spreadTerms.longSpreadwFundingBias = longSpread;
+	spreadTerms.shortSpreadwFundingBias = shortSpread;
+
 	if (ammInventorySpreadAdjustment < 0) {
 		const adjustment = Math.abs(ammInventorySpreadAdjustment);
 
@@ -856,7 +1002,7 @@ export function calculateSpreadBN(
 export function calculateSpread(
 	amm: AMM,
 	marketStats: MarketStats,
-	oraclePriceData: OraclePriceData,
+	oraclePriceData?: OraclePriceData,
 	now?: BN,
 	reservePrice?: BN
 ): [number, number] {
@@ -864,6 +1010,12 @@ export function calculateSpread(
 		return [amm.baseSpread / 2, amm.baseSpread / 2];
 	}
 
+	if (!oraclePriceData) {
+		throw new Error(
+			'calculateSpread: oraclePriceData is required when baseSpread and curveUpdateIntensity are nonzero'
+		);
+	}
+
 	if (!reservePrice) {
 		reservePrice = calculatePrice(
 			amm.baseAssetReserve,
@@ -911,7 +1063,10 @@ export function calculateSpread(
 		marketStats.longIntensityVolume,
 		marketStats.shortIntensityVolume,
 		marketStats.volume24H,
-		amm.ammInventorySpreadAdjustment
+		amm.ammInventorySpreadAdjustment,
+		marketStats.last24HAvgFundingRate,
+		marketStats.lastFundingOracleTwap,
+		amm.fundingBiasSensitivity
 	);
 	let longSpread = spreads[0];
 	let shortSpread = spreads[1];
@@ -942,7 +1097,7 @@ export function calculateSpread(
 export function calculateSpreadReserves(
 	amm: AMM,
 	marketStats: MarketStats,
-	mmOraclePriceData: MMOraclePriceData,
+	mmOraclePriceData?: MMOraclePriceData,
 	now?: BN,
 	latestSlot?: BN
 ) {
@@ -951,8 +1106,8 @@ export function calculateSpreadReserves(
 		direction: PositionDirection,
 		amm: AMM
 	): {
-		baseAssetReserve;
-		quoteAssetReserve;
+		baseAssetReserve: BN;
+		quoteAssetReserve: BN;
 	} {
 		if (spread === 0) {
 			return {
@@ -1181,7 +1336,7 @@ export function calculateMaxBaseAssetAmountToTrade(
 	marketStats: MarketStats,
 	limit_price: BN,
 	direction: PositionDirection,
-	mmOraclePriceData?: MMOraclePriceData,
+	mmOraclePriceData: MMOraclePriceData,
 	now?: BN
 ): [BN, PositionDirection] {
 	const invariant = amm.sqrtK.mul(amm.sqrtK);

package/src/math/bankruptcy.ts

@@ -4,7 +4,7 @@ import { isVariant } from '../types';
 import { User } from '../user';
 
 export function isUserBankrupt(user: User): boolean {
-	const userAccount = user.getUserAccount();
+	const userAccount = user.getUserAccountOrThrow();
 	let hasLiability = false;
 	for (const position of userAccount.spotPositions) {
 		if (position.scaledBalance.gt(ZERO)) {

package/src/math/funding.ts

@@ -41,7 +41,6 @@ function calculateLiveMarkTwap(
 		const [bid, ask] = calculateBidAskPrice(
 			market.amm,
 			market.marketStats,
-			market.totalExchangeFee,
 			mmOraclePriceData
 		);
 		markPrice = bid.add(ask).div(new BN(2));
@@ -156,6 +155,11 @@ export function calculateAllEstimatedFundingRate(
 		now,
 		market.marketStats.fundingPeriod
 	);
+	if (!oraclePriceData) {
+		throw new Error(
+			'calculateAllEstimatedFundingRate: oraclePriceData is required for an initialized market'
+		);
+	}
 	const liveOracleTwap = calculateLiveOracleTwap(
 		market.marketStats.historicalOracleData,
 		oraclePriceData,
@@ -427,13 +431,10 @@ export function calculateLongShortFundingRateAndLiveTwaps(
  */
 export function calculateFundingPool(market: PerpMarketAccount): BN {
 	// todo
-	const totalFeeLB = market.totalExchangeFee.div(new BN(2));
+	// no protocol floor post-isolation: 1/3 of the AMM's own equity
 	const feePool = BN.max(
 		ZERO,
-		market.amm.totalFeeMinusDistributions
-			.sub(totalFeeLB)
-			.mul(new BN(1))
-			.div(new BN(3))
+		market.amm.totalFeeMinusDistributions.mul(new BN(1)).div(new BN(3))
 	);
 	return feePool;
 }

package/src/math/insurance.ts

@@ -6,7 +6,7 @@ import { SpotBalanceType, SpotMarketAccount } from '../types';
 export function nextRevenuePoolSettleApr(
 	spotMarket: SpotMarketAccount,
 	vaultBalance: BN, // vault token amount
-	amount?: BN // delta token amount
+	amount: BN // delta token amount
 ): number {
 	const MAX_APR = new BN(10).mul(PERCENTAGE_PRECISION); // 1000% APR
 
@@ -18,13 +18,11 @@ export function nextRevenuePoolSettleApr(
 	);
 
 	const payoutRatio = 0.1;
-	const ratioForStakers =
-		spotMarket.insuranceFund.totalFactor > 0 &&
-		spotMarket.insuranceFund.userFactor > 0 &&
-		spotMarket.insuranceFund.revenueSettlePeriod.gt(ZERO)
-			? spotMarket.insuranceFund.userFactor /
-			  spotMarket.insuranceFund.totalFactor
-			: 0;
+	// the insurance fund is 100% staker-owned: every settled token accrues to
+	// stakers as share-price appreciation (no protocol split)
+	const ratioForStakers = spotMarket.insuranceFund.revenueSettlePeriod.gt(ZERO)
+		? 1
+		: 0;
 
 	// Settle periods from on-chain data:
 	const revSettlePeriod =