@velocity-exchange/sdk 0.0.1

package/src/jupiter/jupiterClient.ts

@@ -0,0 +1,482 @@
+import {
+	AddressLookupTableAccount,
+	Connection,
+	PublicKey,
+	TransactionInstruction,
+	TransactionMessage,
+	VersionedTransaction,
+} from '@solana/web3.js';
+import fetch 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> {
+		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: autoSlippage ? maxAutoSlippageBps.toString() : '0',
+			autoSlippageCollisionUsdValue: autoSlippage
+				? usdEstimate.toString()
+				: '0',
+			...(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);
+
+		const transactionMessage = TransactionMessage.decompile(message, {
+			addressLookupTableAccounts: lookupTables,
+		});
+		return {
+			transactionMessage,
+			lookupTables,
+		};
+	}
+
+	async getLookupTable(
+		accountKey: PublicKey
+	): Promise<AddressLookupTableAccount> {
+		if (this.lookupTableCahce.has(accountKey.toString())) {
+			return this.lookupTableCahce.get(accountKey.toString());
+		}
+
+		return (await this.connection.getAddressLookupTable(accountKey)).value;
+	}
+
+	/**
+	 * 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

@@ -0,0 +1,24 @@
+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

@@ -0,0 +1,138 @@
+## 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/drift/src/state/margin_calculation.rs` field-for-field.
+- The inputs and ordering mirror `calculate_margin_requirement_and_total_collateral_and_liability_info` in `programs/drift/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.