@velocity-exchange/sdk 0.2.5 → 0.4.0

package/src/wallet.ts

@@ -7,14 +7,30 @@ import {
 import { IWallet, IVersionedWallet } from './types';
 import nacl from 'tweetnacl';
 
+/**
+ * Local-keypair implementation of `IWallet`/`IVersionedWallet` that signs directly with an
+ * in-memory `Keypair` (no external wallet/RPC round-trip). Suitable for keeper bots, scripts, and
+ * tests; not for browser dapps holding user funds.
+ */
 export class Wallet implements IWallet, IVersionedWallet {
 	constructor(readonly payer: Keypair) {}
 
+	/**
+	 * Partially signs a legacy `Transaction` with this wallet's keypair, leaving any other
+	 * required signatures untouched.
+	 * @param tx - Transaction to sign; mutated in place.
+	 * @returns The same transaction instance, now signed by `payer`.
+	 */
 	async signTransaction(tx: Transaction): Promise<Transaction> {
 		tx.partialSign(this.payer);
 		return tx;
 	}
 
+	/**
+	 * Signs a `VersionedTransaction` with this wallet's keypair.
+	 * @param tx - Transaction to sign; mutated in place.
+	 * @returns The same transaction instance, now signed by `payer`.
+	 */
 	async signVersionedTransaction(
 		tx: VersionedTransaction
 	): Promise<VersionedTransaction> {
@@ -22,6 +38,11 @@ export class Wallet implements IWallet, IVersionedWallet {
 		return tx;
 	}
 
+	/**
+	 * Partially signs a batch of legacy `Transaction`s with this wallet's keypair.
+	 * @param txs - Transactions to sign; each is mutated in place.
+	 * @returns The same transaction instances, now signed by `payer`.
+	 */
 	async signAllTransactions(txs: Transaction[]): Promise<Transaction[]> {
 		return txs.map((t) => {
 			t.partialSign(this.payer);
@@ -29,6 +50,11 @@ export class Wallet implements IWallet, IVersionedWallet {
 		});
 	}
 
+	/**
+	 * Signs a batch of `VersionedTransaction`s with this wallet's keypair.
+	 * @param txs - Transactions to sign; each is mutated in place.
+	 * @returns The same transaction instances, now signed by `payer`.
+	 */
 	async signAllVersionedTransactions(
 		txs: VersionedTransaction[]
 	): Promise<VersionedTransaction[]> {
@@ -38,16 +64,27 @@ export class Wallet implements IWallet, IVersionedWallet {
 		});
 	}
 
+	/** The wallet's public key, i.e. `payer.publicKey`. */
 	get publicKey(): PublicKey {
 		return this.payer.publicKey;
 	}
 }
 
+/**
+ * `Wallet` variant that additionally supports raw message signing (`signMessage`), needed for
+ * flows like swift/signed-message orders that sign an ed25519 payload outside of a transaction.
+ */
 export class WalletV2 extends Wallet {
 	constructor(readonly payer: Keypair) {
 		super(payer);
 	}
 
+	/**
+	 * Signs an arbitrary message with this wallet's ed25519 secret key (detached signature, not a
+	 * transaction).
+	 * @param message - Raw bytes to sign.
+	 * @returns The 64-byte detached ed25519 signature.
+	 */
 	async signMessage(message: Uint8Array): Promise<Uint8Array> {
 		return Buffer.from(nacl.sign.detached(message, this.payer.secretKey));
 	}

package/tests/VelocityCore/builder_escrow.test.ts

@@ -0,0 +1,121 @@
+import { describe, expect, test } from 'bun:test';
+import { Keypair, PublicKey } from '@solana/web3.js';
+import { VelocityClient } from '../../src/velocityClient';
+import { ReferrerMap } from '../../src/userMap/referrerMap';
+import { getRevenueShareEscrowAccountPublicKey } from '../../src/addresses/pda';
+import { RevenueShareEscrowAccount } from '../../src/types';
+
+// `getTakerEscrowAccountMeta` decides whether a perp fill must carry the taker's
+// RevenueShareEscrow account. It only reads `this.program.programId`, so we can
+// exercise the decision with a minimal `this` instead of a full client.
+// Regression guard for: a referred taker (escrow initialized with a referrer)
+// whose order carries no builder code must still get the escrow attached, else
+// the program rejects the fill with UnableToLoadRevenueShareAccount.
+const getTakerEscrowAccountMeta = (VelocityClient.prototype as any)
+	.getTakerEscrowAccountMeta as (
+	takerAuthority: PublicKey,
+	orderHasBuilder: boolean,
+	takerEscrow?: RevenueShareEscrowAccount,
+	takerIsReferred?: boolean
+) => { pubkey: PublicKey; isWritable: boolean; isSigner: boolean } | undefined;
+
+const programId = Keypair.generate().publicKey;
+const ctx = { program: { programId } };
+const escrow = (
+	authority: PublicKey,
+	referrer: PublicKey
+): RevenueShareEscrowAccount =>
+	({ authority, referrer }) as unknown as RevenueShareEscrowAccount;
+
+describe('getTakerEscrowAccountMeta (fill escrow attachment)', () => {
+	test('takerIsReferred, order without builder -> escrow attached', () => {
+		const authority = Keypair.generate().publicKey;
+		const meta = getTakerEscrowAccountMeta.call(
+			ctx,
+			authority,
+			false,
+			undefined,
+			true
+		);
+		expect(meta).toBeDefined();
+		expect(
+			meta!.pubkey.equals(
+				getRevenueShareEscrowAccountPublicKey(programId, authority)
+			)
+		).toBe(true);
+		expect(meta!.isWritable).toBe(true);
+	});
+
+	test('not referred, order without builder -> no escrow', () => {
+		const authority = Keypair.generate().publicKey;
+		expect(
+			getTakerEscrowAccountMeta.call(ctx, authority, false, undefined, false)
+		).toBeUndefined();
+	});
+
+	test('builder-code order attaches escrow (no referral signal needed)', () => {
+		const authority = Keypair.generate().publicKey;
+		const meta = getTakerEscrowAccountMeta.call(
+			ctx,
+			authority,
+			true,
+			undefined
+		);
+		expect(meta).toBeDefined();
+		expect(
+			meta!.pubkey.equals(
+				getRevenueShareEscrowAccountPublicKey(programId, authority)
+			)
+		).toBe(true);
+	});
+
+	test('decoded escrow with a referrer still attaches (back-compat)', () => {
+		const authority = Keypair.generate().publicKey;
+		const meta = getTakerEscrowAccountMeta.call(
+			ctx,
+			authority,
+			false,
+			escrow(authority, Keypair.generate().publicKey)
+		);
+		expect(meta).toBeDefined();
+	});
+
+	test('escrow belonging to a different authority is rejected', () => {
+		const authority = Keypair.generate().publicKey;
+		const wrong = escrow(
+			Keypair.generate().publicKey,
+			Keypair.generate().publicKey
+		);
+		expect(() =>
+			getTakerEscrowAccountMeta.call(ctx, authority, false, wrong)
+		).toThrow();
+	});
+});
+
+// Guards the referral bit ReferrerMap reads out of the taker's UserStats — the
+// signal the fillers pass to getFillPerpOrderIx. Locks the `referrer_status`
+// byte offset (188) and the BuilderReferral bit (0b100).
+describe('ReferrerMap.mustGetIsBuilderReferral', () => {
+	const REFERRER_STATUS_OFFSET = 188;
+	const statsBuffer = (referrerStatus: number): Buffer => {
+		const buf = Buffer.alloc(REFERRER_STATUS_OFFSET + 8);
+		buf[REFERRER_STATUS_OFFSET] = referrerStatus;
+		return buf;
+	};
+	const fakeClient = (buf: Buffer | null) =>
+		({
+			program: { programId: Keypair.generate().publicKey },
+			connection: { getAccountInfo: async () => (buf ? { data: buf } : null) },
+		}) as any;
+	const authority = () => Keypair.generate().publicKey.toBase58();
+
+	test('BuilderReferral bit set -> true', async () => {
+		const map = new ReferrerMap(fakeClient(statsBuffer(0b100)));
+		expect(await map.mustGetIsBuilderReferral(authority())).toBe(true);
+	});
+
+	test('IsReferred without BuilderReferral -> false', async () => {
+		const map = new ReferrerMap(fakeClient(statsBuffer(0b010)));
+		expect(await map.mustGetIsBuilderReferral(authority())).toBe(false);
+	});
+});

package/tests/amm/test.ts

@@ -34,6 +34,9 @@ import {
 	getNewOracleConfPct,
 	MMOraclePriceData,
 	OraclePriceData,
+	calculateAmmReservesAfterSwap,
+	getSwapDirection,
+	PositionDirection,
 	// calculateReservePrice,
 } from '../../src';
 import { mockPerpMarkets } from '../dlob/helpers';
@@ -2297,4 +2300,103 @@ describe('AMM Tests', () => {
 		assert(openAsks.eq(new BN(-9)));
 		assert(totalAskSize.eq(ZERO));
 	});
+
+	it('Reference Price Offset accounts for oracle twap slow floor term', () => {
+		// day-premium leg before averaging: 100000/1000*24 = 2400, then the
+		// program subtracts oracleTwapSlow.abs()/FUNDING_RATE_OFFSET_DENOMINATOR
+		// (500000/3333 = 150) => 2250. Without that term the average would be
+		// 1800 instead of 1750.
+		const reservePrice = PRICE_PRECISION;
+		const last24hAvgFundingRate = new BN(100000);
+		const liquidityFraction = new BN(2);
+		const oracleTwapFast = new BN(500000);
+		const markTwapFast = oracleTwapFast.add(new BN(1000));
+		const oracleTwapSlow = new BN(500000);
+		const markTwapSlow = oracleTwapSlow.add(new BN(2000));
+		const maxOffsetPct = 100000;
+
+		const referencePriceOffset = calculateReferencePriceOffset(
+			reservePrice,
+			last24hAvgFundingRate,
+			liquidityFraction,
+			oracleTwapFast,
+			markTwapFast,
+			oracleTwapSlow,
+			markTwapSlow,
+			maxOffsetPct
+		);
+
+		assert(referencePriceOffset.eq(new BN(1750)));
+	});
+
+	it('calculateUpdatedAMM is a passthrough when the repeg debit fails the affordability floor', () => {
+		const myMockPerpMarkets = _.cloneDeep(mockPerpMarkets);
+		const mockMarket1 = myMockPerpMarkets[0];
+		const mockAmm = mockMarket1.amm;
+
+		mockAmm.baseAssetReserve = new BN(1000).mul(BASE_PRECISION);
+		mockAmm.quoteAssetReserve = new BN(1000).mul(BASE_PRECISION);
+		mockAmm.sqrtK = new BN(1000).mul(BASE_PRECISION);
+		mockAmm.pegMultiplier = new BN(10).mul(PEG_PRECISION);
+		mockAmm.baseAssetAmountWithAmm = new BN(100).mul(BASE_PRECISION);
+		mockAmm.curveUpdateIntensity = 100;
+		mockAmm.maxSpread = 25000;
+		// tiny positive equity: any positive repeg cost blows through it
+		mockAmm.totalFeeMinusDistributions = new BN(10);
+		mockAmm.netRevenueSinceLastFunding = new BN(0);
+
+		const directionToClose = mockAmm.baseAssetAmountWithAmm.gt(ZERO)
+			? PositionDirection.SHORT
+			: PositionDirection.LONG;
+		const [terminalQuoteAssetReserve] = calculateAmmReservesAfterSwap(
+			mockAmm,
+			'base',
+			mockAmm.baseAssetAmountWithAmm.abs(),
+			getSwapDirection('base', directionToClose)
+		);
+		mockAmm.terminalQuoteAssetReserve = terminalQuoteAssetReserve;
+
+		// a 1% oracle move is well inside half of maxSpread (1.25%), so the
+		// optimal-peg/budget calc doesn't take the large-price-gap escape
+		// hatch that would otherwise clear checkLowerBound
+		const mmOraclePriceData: MMOraclePriceData = {
+			price: new BN(101).mul(PRICE_PRECISION).divn(10),
+			slot: new BN(0),
+			confidence: new BN(1),
+			hasSufficientNumberOfDataPoints: true,
+			isMMOracleActive: true,
+		} as MMOraclePriceData;
+
+		const updatedAmm = calculateUpdatedAMM(mockAmm, mmOraclePriceData);
+
+		assert(updatedAmm.pegMultiplier.eq(mockAmm.pegMultiplier));
+		assert(updatedAmm.baseAssetReserve.eq(mockAmm.baseAssetReserve));
+		assert(updatedAmm.quoteAssetReserve.eq(mockAmm.quoteAssetReserve));
+		assert(updatedAmm.sqrtK.eq(mockAmm.sqrtK));
+		assert(
+			updatedAmm.totalFeeMinusDistributions.eq(
+				mockAmm.totalFeeMinusDistributions
+			)
+		);
+	});
+
+	it('calculateUpdatedAMM is a passthrough when the oracle price is non-positive', () => {
+		const myMockPerpMarkets = _.cloneDeep(mockPerpMarkets);
+		const mockMarket1 = myMockPerpMarkets[0];
+		const mockAmm = mockMarket1.amm;
+		mockAmm.curveUpdateIntensity = 100;
+
+		const mmOraclePriceData: MMOraclePriceData = {
+			price: ZERO,
+			slot: new BN(0),
+			confidence: new BN(1),
+			hasSufficientNumberOfDataPoints: true,
+			isMMOracleActive: true,
+		} as MMOraclePriceData;
+
+		const updatedAmm = calculateUpdatedAMM(mockAmm, mmOraclePriceData);
+		assert(updatedAmm.pegMultiplier.eq(mockAmm.pegMultiplier));
+		assert(updatedAmm.baseAssetReserve.eq(mockAmm.baseAssetReserve));
+		assert(updatedAmm.quoteAssetReserve.eq(mockAmm.quoteAssetReserve));
+	});
 });

package/tests/builder/builderFee.test.ts

@@ -0,0 +1,42 @@
+import { BN, QUOTE_PRECISION, calculateBuilderFee } from '../../src';
+import { assert } from '../../src/assert/assert';
+
+// Pins the exact denominator/rounding from
+// `programs/velocity/src/math/fees.rs`:
+//   builder_fee = quote_asset_amount * builder_fee_tenth_bps / 100_000
+describe('calculateBuilderFee', () => {
+	it('matches the program formula for a round tenth-bps value', () => {
+		const quoteAssetAmount = new BN(1_000).mul(QUOTE_PRECISION);
+		const builderFeeTenthBps = 10; // 10 tenth-bps == 1 bp == 0.01%
+
+		const builderFee = calculateBuilderFee(
+			quoteAssetAmount,
+			builderFeeTenthBps
+		);
+
+		// 1000 * 1e6 * 10 / 100_000 = 100_000 (= 0.1 * 1e6, i.e. $0.10)
+		assert(builderFee.eq(new BN(100_000)));
+	});
+
+	it('floors (integer division), matching safe_div', () => {
+		// quote * bps not evenly divisible by 100_000
+		const quoteAssetAmount = new BN(333);
+		const builderFeeTenthBps = 7;
+
+		const builderFee = calculateBuilderFee(
+			quoteAssetAmount,
+			builderFeeTenthBps
+		);
+
+		// 333 * 7 = 2331; 2331 / 100_000 = 0 (floored)
+		assert(builderFee.eq(new BN(0)));
+	});
+
+	it('scales linearly with quoteAssetAmount', () => {
+		const builderFeeTenthBps = 250; // 25 bps
+		const small = calculateBuilderFee(new BN(1_000_000), builderFeeTenthBps);
+		const large = calculateBuilderFee(new BN(10_000_000), builderFeeTenthBps);
+
+		assert(large.eq(small.muln(10)));
+	});
+});

package/tests/dlob/helpers.ts

@@ -560,6 +560,7 @@ export const mockStateAccount: StateAccount = {
 	protocolFeeRecipientSpot: PublicKey.default,
 	featureBitFlags: 0,
 	lpPoolFeatureBitFlags: 0,
+	solvencyStatus: 0,
 	defaultMarketOrderTimeInForce: 0,
 	defaultSpotAuctionDuration: 0,
 	discountMint: PublicKey.default,