@velocity-exchange/sdk 0.3.0 → 0.6.0

package/src/jupiter/jupiterClient.ts

@@ -1,502 +0,0 @@
-import {
-	AddressLookupTableAccount,
-	Connection,
-	PublicKey,
-	TransactionInstruction,
-	TransactionMessage,
-	VersionedTransaction,
-} from '@solana/web3.js';
-import fetch, { RequestInit } from 'node-fetch';
-import { BN } from '../isomorphic/anchor';
-import { SwapMode } from '../swap/UnifiedSwapClient';
-
-export interface MarketInfo {
-	id: string;
-	inAmount: number;
-	inputMint: string;
-	label: string;
-	lpFee: Fee;
-	notEnoughLiquidity: boolean;
-	outAmount: number;
-	outputMint: string;
-	platformFee: Fee;
-	priceImpactPct: number;
-}
-
-export interface Fee {
-	amount: number;
-	mint: string;
-	pct: number;
-}
-
-export interface Route {
-	amount: number;
-	inAmount: number;
-	marketInfos: MarketInfo[];
-	otherAmountThreshold: number;
-	outAmount: number;
-	priceImpactPct: number;
-	slippageBps: number;
-	swapMode: SwapMode;
-}
-
-/**
- *
- * @export
- * @interface RoutePlanStep
- */
-export interface RoutePlanStep {
-	/**
-	 *
-	 * @type {SwapInfo}
-	 * @memberof RoutePlanStep
-	 */
-	swapInfo: SwapInfo;
-	/**
-	 *
-	 * @type {number}
-	 * @memberof RoutePlanStep
-	 */
-	percent: number;
-}
-
-export interface SwapInfo {
-	/**
-	 *
-	 * @type {string}
-	 * @memberof SwapInfo
-	 */
-	ammKey: string;
-	/**
-	 *
-	 * @type {string}
-	 * @memberof SwapInfo
-	 */
-	label?: string;
-	/**
-	 *
-	 * @type {string}
-	 * @memberof SwapInfo
-	 */
-	inputMint: string;
-	/**
-	 *
-	 * @type {string}
-	 * @memberof SwapInfo
-	 */
-	outputMint: string;
-	/**
-	 *
-	 * @type {string}
-	 * @memberof SwapInfo
-	 */
-	inAmount: string;
-	/**
-	 *
-	 * @type {string}
-	 * @memberof SwapInfo
-	 */
-	outAmount: string;
-	/**
-	 *
-	 * @type {string}
-	 * @memberof SwapInfo
-	 */
-	feeAmount: string;
-	/**
-	 *
-	 * @type {string}
-	 * @memberof SwapInfo
-	 */
-	feeMint: string;
-}
-
-/**
- *
- * @export
- * @interface PlatformFee
- */
-export interface PlatformFee {
-	/**
-	 *
-	 * @type {string}
-	 * @memberof PlatformFee
-	 */
-	amount?: string;
-	/**
-	 *
-	 * @type {number}
-	 * @memberof PlatformFee
-	 */
-	feeBps?: number;
-}
-
-/**
- *
- * @export
- * @interface QuoteResponse
- */
-export interface QuoteResponse {
-	/**
-	 *
-	 * @type {string}
-	 * @memberof QuoteResponse
-	 */
-	inputMint: string;
-	/**
-	 *
-	 * @type {string}
-	 * @memberof QuoteResponse
-	 */
-	inAmount: string;
-	/**
-	 *
-	 * @type {string}
-	 * @memberof QuoteResponse
-	 */
-	outputMint: string;
-	/**
-	 *
-	 * @type {string}
-	 * @memberof QuoteResponse
-	 */
-	outAmount: string;
-	/**
-	 *
-	 * @type {string}
-	 * @memberof QuoteResponse
-	 */
-	otherAmountThreshold: string;
-	/**
-	 *
-	 * @type {SwapMode}
-	 * @memberof QuoteResponse
-	 */
-	swapMode: SwapMode;
-	/**
-	 *
-	 * @type {number}
-	 * @memberof QuoteResponse
-	 */
-	slippageBps: number;
-	/**
-	 *
-	 * @type {PlatformFee}
-	 * @memberof QuoteResponse
-	 */
-	platformFee?: PlatformFee;
-	/**
-	 *
-	 * @type {string}
-	 * @memberof QuoteResponse
-	 */
-	priceImpactPct: string;
-	/**
-	 *
-	 * @type {Array<RoutePlanStep>}
-	 * @memberof QuoteResponse
-	 */
-	routePlan: Array<RoutePlanStep>;
-	/**
-	 *
-	 * @type {number}
-	 * @memberof QuoteResponse
-	 */
-	contextSlot?: number;
-	/**
-	 *
-	 * @type {number}
-	 * @memberof QuoteResponse
-	 */
-	timeTaken?: number;
-	/**
-	 *
-	 * @type {string}
-	 * @memberof QuoteResponse
-	 */
-	error?: string;
-	/**
-	 *
-	 * @type {string}
-	 * @memberof QuoteResponse
-	 */
-	errorCode?: string;
-}
-
-export const RECOMMENDED_JUPITER_API_VERSION = '/v1';
-/** @deprecated Use RECOMMENDED_JUPITER_API instead. lite-api.jup.ag requires migration to api.jup.ag with API key. */
-export const LEGACY_JUPITER_API = 'https://lite-api.jup.ag/swap';
-export const RECOMMENDED_JUPITER_API = 'https://api.jup.ag/swap';
-
-export class JupiterClient {
-	url: string;
-	connection: Connection;
-	lookupTableCahce = new Map<string, AddressLookupTableAccount>();
-	private apiKey?: string;
-
-	/**
-	 * Create a Jupiter client
-	 * @param connection - Solana connection
-	 * @param url - Optional custom API URL. Defaults to https://api.jup.ag/swap
-	 * @param apiKey - API key for Jupiter API. Required for api.jup.ag (free tier available at https://portal.jup.ag)
-	 */
-	constructor({
-		connection,
-		url,
-		apiKey,
-	}: {
-		connection: Connection;
-		url?: string;
-		apiKey?: string;
-	}) {
-		this.connection = connection;
-		this.url = url ?? RECOMMENDED_JUPITER_API;
-		this.apiKey = apiKey;
-	}
-
-	/**
-	 * Get the headers for API requests, including API key if configured
-	 */
-	private getHeaders(contentType?: string): Record<string, string> {
-		const headers: Record<string, string> = {};
-		if (contentType) {
-			headers['Content-Type'] = contentType;
-		}
-		if (this.apiKey) {
-			headers['x-api-key'] = this.apiKey;
-		}
-		return headers;
-	}
-
-	/**
-	 * Get routes for a swap
-	 * @param inputMint the mint of the input token
-	 * @param outputMint the mint of the output token
-	 * @param amount the amount of the input token
-	 * @param slippageBps the slippage tolerance in basis points
-	 * @param swapMode the swap mode (ExactIn or ExactOut)
-	 * @param onlyDirectRoutes whether to only return direct routes
-	 */
-	public async getQuote({
-		inputMint,
-		outputMint,
-		amount,
-		maxAccounts = 50, // 50 is an estimated amount with buffer
-		slippageBps = 50,
-		swapMode = 'ExactIn',
-		onlyDirectRoutes = false,
-		excludeDexes,
-		autoSlippage = false,
-		maxAutoSlippageBps,
-		usdEstimate,
-	}: {
-		inputMint: PublicKey;
-		outputMint: PublicKey;
-		amount: BN;
-		maxAccounts?: number;
-		slippageBps?: number;
-		swapMode?: SwapMode;
-		onlyDirectRoutes?: boolean;
-		excludeDexes?: string[];
-		autoSlippage?: boolean;
-		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(),
-			amount: amount.toString(),
-			slippageBps: autoSlippage ? '0' : slippageBps.toString(),
-			swapMode,
-			onlyDirectRoutes: onlyDirectRoutes.toString(),
-			maxAccounts: maxAccounts.toString(),
-			autoSlippage: autoSlippage.toString(),
-			maxAutoSlippageBps: maxAutoSlippageBpsParam,
-			autoSlippageCollisionUsdValue: autoSlippageCollisionUsdValueParam,
-			...(excludeDexes && { excludeDexes: excludeDexes.join(',') }),
-		});
-		if (swapMode === 'ExactOut') {
-			params.delete('maxAccounts');
-		}
-		const apiVersionParam =
-			this.url === RECOMMENDED_JUPITER_API || this.url === LEGACY_JUPITER_API
-				? RECOMMENDED_JUPITER_API_VERSION
-				: '';
-		const headers = this.getHeaders();
-		const fetchOptions: RequestInit =
-			Object.keys(headers).length > 0 ? { headers } : {};
-		const quote = await (
-			await fetch(
-				`${this.url}${apiVersionParam}/quote?${params.toString()}`,
-				fetchOptions
-			)
-		).json();
-		return quote as QuoteResponse;
-	}
-
-	/**
-	 * Get a swap transaction for quote
-	 * @param quoteResponse quote to perform swap
-	 * @param userPublicKey the signer's wallet public key
-	 * @param slippageBps the slippage tolerance in basis points
-	 */
-	public async getSwap({
-		quote,
-		userPublicKey,
-		slippageBps = 50,
-	}: {
-		quote: QuoteResponse;
-		userPublicKey: PublicKey;
-		slippageBps?: number;
-	}): Promise<VersionedTransaction> {
-		if (!quote) {
-			throw new Error('Jupiter swap quote not provided. Please try again.');
-		}
-
-		const apiVersionParam =
-			this.url === RECOMMENDED_JUPITER_API || this.url === LEGACY_JUPITER_API
-				? RECOMMENDED_JUPITER_API_VERSION
-				: '';
-		const resp = await (
-			await fetch(`${this.url}${apiVersionParam}/swap`, {
-				method: 'POST',
-				headers: this.getHeaders('application/json'),
-				body: JSON.stringify({
-					quoteResponse: quote,
-					userPublicKey,
-					slippageBps,
-				}),
-			})
-		).json();
-		if (!('swapTransaction' in resp)) {
-			throw new Error(
-				`swapTransaction not found, error from Jupiter: ${resp.error} ${
-					', ' + (resp.message ?? '')
-				}`
-			);
-		}
-		const { swapTransaction } = resp;
-
-		try {
-			const swapTransactionBuf = Buffer.from(swapTransaction, 'base64');
-			return VersionedTransaction.deserialize(swapTransactionBuf);
-		} catch (err) {
-			throw new Error(
-				'Something went wrong with creating the Jupiter swap transaction. Please try again.'
-			);
-		}
-	}
-
-	/**
-	 * Get the transaction message and lookup tables for a transaction
-	 * @param transaction
-	 */
-	public async getTransactionMessageAndLookupTables({
-		transaction,
-	}: {
-		transaction: VersionedTransaction;
-	}): Promise<{
-		transactionMessage: TransactionMessage;
-		lookupTables: AddressLookupTableAccount[];
-	}> {
-		const message = transaction.message;
-
-		const lookupTables = (
-			await Promise.all(
-				message.addressTableLookups.map(async (lookup) => {
-					return await this.getLookupTable(lookup.accountKey);
-				})
-			)
-		).filter(
-			(lookup): lookup is AddressLookupTableAccount => lookup !== undefined
-		);
-
-		const transactionMessage = TransactionMessage.decompile(message, {
-			addressLookupTableAccounts: lookupTables,
-		});
-		return {
-			transactionMessage,
-			lookupTables,
-		};
-	}
-
-	async getLookupTable(
-		accountKey: PublicKey
-	): Promise<AddressLookupTableAccount | undefined> {
-		const cached = this.lookupTableCahce.get(accountKey.toString());
-		if (cached !== undefined) {
-			return cached;
-		}
-
-		return (
-			(await this.connection.getAddressLookupTable(accountKey)).value ??
-			undefined
-		);
-	}
-
-	/**
-	 * Get the jupiter instructions from transaction by filtering out instructions to compute budget and associated token programs
-	 * @param transactionMessage the transaction message
-	 * @param inputMint the input mint
-	 * @param outputMint the output mint
-	 */
-	public getJupiterInstructions({
-		transactionMessage,
-		inputMint,
-		outputMint,
-	}: {
-		transactionMessage: TransactionMessage;
-		inputMint: PublicKey;
-		outputMint: PublicKey;
-	}): TransactionInstruction[] {
-		return transactionMessage.instructions.filter((instruction) => {
-			if (
-				instruction.programId.toString() ===
-				'ComputeBudget111111111111111111111111111111'
-			) {
-				return false;
-			}
-
-			if (
-				instruction.programId.toString() ===
-				'TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA'
-			) {
-				return false;
-			}
-
-			if (
-				instruction.programId.toString() === '11111111111111111111111111111111'
-			) {
-				return false;
-			}
-
-			if (
-				instruction.programId.toString() ===
-				'ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL'
-			) {
-				const mint = instruction.keys[3].pubkey;
-				if (mint.equals(inputMint) || mint.equals(outputMint)) {
-					return false;
-				}
-			}
-
-			return true;
-		});
-	}
-}

package/src/keypair.ts

@@ -1,24 +0,0 @@
-import fs from 'fs';
-import bs58 from 'bs58';
-import { Keypair } from '@solana/web3.js';
-
-export function loadKeypair(privateKey: string): Keypair {
-	// try to load privateKey as a filepath
-	let loadedKey: Uint8Array;
-	if (fs.existsSync(privateKey)) {
-		privateKey = fs.readFileSync(privateKey).toString();
-	}
-
-	if (privateKey.includes('[') && privateKey.includes(']')) {
-		loadedKey = Uint8Array.from(JSON.parse(privateKey));
-	} else if (privateKey.includes(',')) {
-		loadedKey = Uint8Array.from(
-			privateKey.split(',').map((val) => Number(val))
-		);
-	} else {
-		privateKey = privateKey.replace(/\s/g, '');
-		loadedKey = new Uint8Array(bs58.decode(privateKey));
-	}
-
-	return Keypair.fromSecretKey(Uint8Array.from(loadedKey));
-}

package/src/margin/README.md

@@ -1,138 +0,0 @@
-## Margin Calculation Snapshot (SDK)
-
-This document describes the single-source-of-truth margin engine in the SDK that mirrors the on-chain `MarginCalculation` and related semantics. The goal is to compute an immutable snapshot in one pass and have existing `User` getters delegate to it, eliminating duplicative work across getters and UI hooks while maintaining parity with the program.
-
-### Alignment with on-chain
-
-- The SDK snapshot shape mirrors `programs/velocity/src/state/margin_calculation.rs` field-for-field.
-- The inputs and ordering mirror `calculate_margin_requirement_and_total_collateral_and_liability_info` in `programs/velocity/src/math/margin.rs`.
-- Isolated positions are represented as `isolatedMarginCalculations` keyed by perp `marketIndex`, matching program logic.
-
-### Core SDK types (shape parity)
-
-```ts
-// Types reflect on-chain names and numeric signs
-import { MarketType } from './types';
-
-export type MarginCategory = 'Initial' | 'Maintenance' | 'Fill';
-
-export type MarginCalculationMode =
-  | { type: 'Standard' }
-  | { type: 'Liquidation' };
-
-export class MarketIdentifier {
-  marketType: MarketType;
-  marketIndex: number;
-
-  static spot(marketIndex: number): MarketIdentifier;
-  static perp(marketIndex: number): MarketIdentifier;
-  equals(other: MarketIdentifier | undefined): boolean;
-}
-
-export class MarginContext {
-  marginType: MarginCategory;
-  mode: MarginCalculationMode;
-  strict: boolean;
-  ignoreInvalidDepositOracles: boolean;
-  isolatedMarginBuffers: Map<number, BN>;
-  crossMarginBuffer: BN;
-
-  // Factory methods
-  static standard(marginType: MarginCategory): MarginContext;
-  static liquidation(
-    crossMarginBuffer: BN,
-    isolatedMarginBuffers: Map<number, BN>
-  ): MarginContext;
-
-  // Builder methods (return this for chaining)
-  strictMode(strict: boolean): this;
-  ignoreInvalidDeposits(ignore: boolean): this;
-  setCrossMarginBuffer(crossMarginBuffer: BN): this;
-  setIsolatedMarginBuffers(isolatedMarginBuffers: Map<number, BN>): this;
-  setIsolatedMarginBuffer(marketIndex: number, isolatedMarginBuffer: BN): this;
-}
-
-export class IsolatedMarginCalculation {
-  marginRequirement: BN;             // u128
-  totalCollateral: BN;               // i128 (deposit + pnl)
-  totalCollateralBuffer: BN;         // i128
-  marginRequirementPlusBuffer: BN;   // u128
-
-  getTotalCollateralPlusBuffer(): BN;
-  meetsMarginRequirement(): boolean;
-  meetsMarginRequirementWithBuffer(): boolean;
-  marginShortage(): BN;
-}
-
-export class MarginCalculation {
-  context: MarginContext;
-
-  totalCollateral: BN;               // i128
-  totalCollateralBuffer: BN;         // i128
-  marginRequirement: BN;             // u128
-  marginRequirementPlusBuffer: BN;   // u128
-
-  isolatedMarginCalculations: Map<number, IsolatedMarginCalculation>;
-
-  totalPerpLiabilityValue: BN;       // u128
-
-  // Cross margin helpers
-  getCrossTotalCollateralPlusBuffer(): BN;
-  meetsCrossMarginRequirement(): boolean;
-  meetsCrossMarginRequirementWithBuffer(): boolean;
-  getCrossFreeCollateral(): BN;
-
-  // Combined (cross + isolated) helpers
-  meetsMarginRequirement(): boolean;
-  meetsMarginRequirementWithBuffer(): boolean;
-
-  // Isolated margin helpers
-  getIsolatedFreeCollateral(marketIndex: number): BN;
-  getIsolatedMarginCalculation(marketIndex: number): IsolatedMarginCalculation | undefined;
-  hasIsolatedMarginCalculation(marketIndex: number): boolean;
-}
-```
-
-### Computation model (on-demand)
-
-- The SDK computes the snapshot on-demand when `getMarginCalculation(...)` is called.
-- No event-driven recomputation by default (oracle prices can change every slot; recomputing every update would be wasteful).
-- Callers (UI/bots) decide polling frequency (e.g., UI can refresh every ~1s on active trade forms).
-
-### User integration
-
-`User` class provides the primary entrypoint:
-
-```ts
-public getMarginCalculation(
-  marginCategory: MarginCategory = 'Initial',
-  opts?: {
-    strict?: boolean;                              // mirror StrictOraclePrice application
-    includeOpenOrders?: boolean;                   // include open orders in margin calc
-    liquidationBufferMap?: Map<number | 'cross', BN>; // margin buffer for liquidation mode
-  }
-): MarginCalculation;
-```
-
-Existing getters delegate to the snapshot to avoid duplicate work:
-- `getTotalCollateral()` → `snapshot.totalCollateral`
-- `getMarginRequirement(mode)` → `snapshot.marginRequirement`
-- `getFreeCollateral()` → `snapshot.getCrossFreeCollateral()`
-- Per-market isolated FC → `snapshot.getIsolatedFreeCollateral(marketIndex)`
-
-### UI compatibility
-
-- All existing `User` getters remain and delegate to the snapshot, so current UI keeps working without call-site changes.
-- New consumers can call `user.getMarginCalculation()` to access isolated breakdowns via `isolatedMarginCalculations`.
-
-### Testing and parity
-
-- Golden tests comparing SDK snapshot against program outputs (cross and isolated, edge cases).
-- Keep math/rounding identical to program (ordering, buffers, funding, open-order IM, oracle strictness).
-
-### Migration plan (brief)
-
-1. Implement `types` and `engine` with strict parity; land behind a feature flag.
-2. Add `user.getMarginCalculation()` and delegate legacy getters.
-3. Optionally update UI hooks to read richer fields; not required for compatibility.
-4. Expand parity tests; enable by default after validation.