@velocity-exchange/sdk 0.1.0 → 0.2.1

package/src/auctionSubscriber/auctionSubscriber.ts

@@ -14,7 +14,7 @@ export class AuctionSubscriber {
 	private resubOpts?: ResubOpts;
 
 	eventEmitter: StrictEventEmitter<EventEmitter, AuctionSubscriberEvents>;
-	private subscriber: WebSocketProgramAccountSubscriber<UserAccount>;
+	private subscriber?: WebSocketProgramAccountSubscriber<UserAccount>;
 
 	constructor({
 		velocityClient,
@@ -24,14 +24,15 @@ export class AuctionSubscriber {
 	}: AuctionSubscriberConfig) {
 		// Type-system guarantees at least one of the two is supplied.
 		this.velocityClient = velocityClient!;
-		this.opts = opts || this.velocityClient.opts;
+		this.opts = opts || this.velocityClient.opts || {};
 		this.eventEmitter = new EventEmitter();
 		this.resubOpts = { resubTimeoutMs, logResubMessages };
 	}
 
 	public async subscribe() {
-		if (!this.subscriber) {
-			this.subscriber = new WebSocketProgramAccountSubscriber<UserAccount>(
+		let subscriber = this.subscriber;
+		if (!subscriber) {
+			subscriber = new WebSocketProgramAccountSubscriber<UserAccount>(
 				'AuctionSubscriber',
 				'user',
 				this.velocityClient.program,
@@ -46,9 +47,10 @@ export class AuctionSubscriber {
 				},
 				this.resubOpts
 			);
+			this.subscriber = subscriber;
 		}
 
-		await this.subscriber.subscribe(
+		await subscriber.subscribe(
 			(accountId: PublicKey, data: UserAccount, context: Context) => {
 				this.eventEmitter.emit(
 					'onAccountUpdate',

package/src/auctionSubscriber/auctionSubscriberGrpc.ts

@@ -16,7 +16,7 @@ export class AuctionSubscriberGrpc {
 	private grpcConfigs?: GrpcConfigs;
 
 	eventEmitter: StrictEventEmitter<EventEmitter, AuctionSubscriberEvents>;
-	private subscriber: WebSocketProgramAccountSubscriber<UserAccount>;
+	private subscriber?: WebSocketProgramAccountSubscriber<UserAccount>;
 
 	constructor({
 		velocityClient,
@@ -27,15 +27,21 @@ export class AuctionSubscriberGrpc {
 	}: AuctionSubscriberConfig) {
 		// Type-system guarantees at least one of the two is supplied.
 		this.velocityClient = velocityClient!;
-		this.opts = opts || this.velocityClient.opts;
+		this.opts = opts || this.velocityClient.opts || {};
 		this.eventEmitter = new EventEmitter();
 		this.resubOpts = { resubTimeoutMs, logResubMessages };
 		this.grpcConfigs = grpcConfigs;
 	}
 
 	public async subscribe() {
-		if (!this.subscriber) {
-			this.subscriber = await grpcProgramAccountSubscriber.create<UserAccount>(
+		let subscriber = this.subscriber;
+		if (!subscriber) {
+			if (!this.grpcConfigs) {
+				throw new Error(
+					'grpcConfigs must be provided to use AuctionSubscriberGrpc'
+				);
+			}
+			subscriber = await grpcProgramAccountSubscriber.create<UserAccount>(
 				this.grpcConfigs,
 				'AuctionSubscriber',
 				'user',
@@ -50,9 +56,10 @@ export class AuctionSubscriberGrpc {
 				},
 				this.resubOpts
 			);
+			this.subscriber = subscriber;
 		}
 
-		await this.subscriber.subscribe(
+		await subscriber.subscribe(
 			(accountId: PublicKey, data: UserAccount, context: Context) => {
 				this.eventEmitter.emit(
 					'onAccountUpdate',

package/src/bankrun/bankrunConnection.ts

@@ -43,7 +43,7 @@ export type Connection = SolanaConnection | BankrunConnection;
 
 type BankrunTransactionMetaNormalized = {
 	logMessages: string[];
-	err: TransactionError;
+	err: TransactionError | null;
 };
 
 type BankrunTransactionRespose = {
@@ -159,7 +159,15 @@ export class BankrunConnection {
 		TransactionSignature,
 		BanksTransactionResultWithMeta
 	> = new Map();
-	private clock: Clock;
+	private _clock?: Clock;
+	private get clock(): Clock {
+		if (!this._clock) {
+			throw new Error(
+				'BankrunConnection: clock accessed before updateSlotAndClock()'
+			);
+		}
+		return this._clock;
+	}
 
 	private nextClientSubscriptionId = 0;
 	private onLogCallbacks = new Map<number, LogsCallback>();
@@ -190,13 +198,32 @@ export class BankrunConnection {
 
 	async getTokenAccount(publicKey: PublicKey): Promise<Account> {
 		const info = await this.getAccountInfo(publicKey);
+		if (info === null) {
+			throw new Error(`Account not found: ${publicKey.toBase58()}`);
+		}
 		return unpackAccount(publicKey, info, info.owner);
 	}
 
+	// Mirrors the drift-vaults bankrun helper: returns the decoded SPL token
+	// Account (with .amount), not web3.js's { value: { amount } } shape. The
+	// vaults tests read `.amount` off the result directly.
+	async getTokenAccountBalance(
+		publicKey: PublicKey,
+		_commitment?: Commitment
+	): Promise<Account> {
+		return this.getTokenAccount(publicKey);
+	}
+
+	// SOL lamport balance, straight off the BanksClient. Returns a bigint like
+	// the drift-vaults bankrun helper (callers wrap with Number()).
+	async getBalance(publicKey: PublicKey): Promise<bigint> {
+		return this._banksClient.getBalance(publicKey);
+	}
+
 	async getMultipleAccountsInfo(
 		publicKeys: PublicKey[],
 		_commitmentOrConfig?: Commitment
-	): Promise<AccountInfo<Buffer>[]> {
+	): Promise<(AccountInfo<Buffer> | null)[]> {
 		const accountInfos = [];
 
 		for (const publicKey of publicKeys) {
@@ -225,7 +252,17 @@ export class BankrunConnection {
 		// eslint-disable-next-line @typescript-eslint/explicit-module-boundary-types
 		_options?: any
 	): Promise<TransactionSignature> {
-		const tx = Transaction.from(rawTransaction);
+		// Raw bytes may encode either a legacy or a versioned (v0) transaction.
+		// sendTransaction handles both, but they must be deserialized with the
+		// matching type: legacy parses with Transaction.from, versioned needs
+		// VersionedTransaction.deserialize. Versioned-tx clients (e.g. the vaults
+		// VaultClient) always send v0, so fall back when the legacy parse throws.
+		let tx: Transaction | VersionedTransaction;
+		try {
+			tx = Transaction.from(rawTransaction);
+		} catch (e) {
+			tx = VersionedTransaction.deserialize(rawTransaction as Uint8Array);
+		}
 		const signature = await this.sendTransaction(tx);
 		return signature;
 	}
@@ -246,9 +283,18 @@ export class BankrunConnection {
 			: await internal.tryProcessLegacyTransaction(serialized);
 		const banksTransactionMeta = new BanksTransactionResultWithMeta(inner);
 
-		const signature = isVersioned
-			? bs58.encode((tx as VersionedTransaction).signatures[0])
-			: bs58.encode((tx as Transaction).signatures[0].signature);
+		let signature: string;
+		if (isVersioned) {
+			signature = bs58.encode((tx as VersionedTransaction).signatures[0]);
+		} else {
+			const legacySignature = (tx as Transaction).signatures[0].signature;
+			if (legacySignature === null) {
+				throw new Error(
+					'BankrunConnection: transaction is missing its first signature'
+				);
+			}
+			signature = bs58.encode(legacySignature);
+		}
 
 		if (banksTransactionMeta.result) {
 			if (
@@ -273,9 +319,14 @@ export class BankrunConnection {
 		}
 		let finalizedCount = 0;
 		while (finalizedCount < 10) {
-			const signatureStatus = (await this.getSignatureStatus(signature)).value
-				.confirmationStatus;
-			if (signatureStatus.toString() == '"finalized"') {
+			const statusValue = (await this.getSignatureStatus(signature)).value;
+			if (statusValue === null) {
+				throw new Error(
+					`BankrunConnection: no signature status for ${signature}`
+				);
+			}
+			const signatureStatus = statusValue.confirmationStatus;
+			if (signatureStatus?.toString() == '"finalized"') {
 				finalizedCount += 1;
 			}
 		}
@@ -291,14 +342,16 @@ export class BankrunConnection {
 		if (this.onLogCallbacks.size > 0) {
 			const transaction = await this.getTransaction(signature);
 
-			const context = { slot: transaction.slot };
-			const logs = {
-				logs: transaction.meta.logMessages,
-				err: transaction.meta.err,
-				signature,
-			};
-			for (const logCallback of this.onLogCallbacks.values()) {
-				logCallback(logs, context);
+			if (transaction !== null) {
+				const context = { slot: transaction.slot };
+				const logs = {
+					logs: transaction.meta.logMessages,
+					err: transaction.meta.err,
+					signature,
+				};
+				for (const logCallback of this.onLogCallbacks.values()) {
+					logCallback(logs, context);
+				}
 			}
 		}
 
@@ -307,6 +360,9 @@ export class BankrunConnection {
 			callback,
 		] of this.onAccountChangeCallbacks.values()) {
 			const accountInfo = await this.getParsedAccountInfo(publicKey);
+			if (accountInfo.value === null) {
+				continue;
+			}
 			callback(accountInfo.value, accountInfo.context);
 		}
 
@@ -326,7 +382,7 @@ export class BankrunConnection {
 			currentClock.unixTimestamp + BigInt(1)
 		);
 		this.context.setClock(newClock);
-		this.clock = newClock;
+		this._clock = newClock;
 	}
 
 	getTime(): number {
@@ -335,7 +391,7 @@ export class BankrunConnection {
 
 	async getParsedAccountInfo(
 		publicKey: PublicKey
-	): Promise<RpcResponseAndContext<AccountInfo<Buffer>>> {
+	): Promise<RpcResponseAndContext<null | AccountInfo<Buffer>>> {
 		const accountInfoBytes = await this._banksClient.getAccount(publicKey);
 		if (accountInfoBytes === null) {
 			return {
@@ -360,6 +416,9 @@ export class BankrunConnection {
 		const blockhashAndBlockheight = await this._banksClient.getLatestBlockhash(
 			commitment
 		);
+		if (blockhashAndBlockheight === null) {
+			throw new Error('Failed to get latest blockhash');
+		}
 		return {
 			blockhash: blockhashAndBlockheight[0],
 			lastValidBlockHeight: Number(blockhashAndBlockheight[1]),
@@ -427,6 +486,9 @@ export class BankrunConnection {
 		const transactionStatus = await this._banksClient.getTransactionStatus(
 			signature
 		);
+		if (transactionStatus === null) {
+			throw new Error(`tx has no status: ${signature}`);
+		}
 		if (txMeta.meta === null) {
 			throw new Error(`tx has no meta: ${JSON.stringify(txMeta)}`);
 		}
@@ -440,24 +502,27 @@ export class BankrunConnection {
 		};
 	}
 
-	findComputeUnitConsumption(signature: string): bigint {
+	private getTransactionMetaOrThrow(
+		signature: string
+	): NonNullable<BanksTransactionResultWithMeta['meta']> {
 		const txMeta = this.transactionToMeta.get(
 			signature as TransactionSignature
 		);
 		if (txMeta === undefined) {
 			throw new Error('Transaction not found');
 		}
-		return txMeta.meta.computeUnitsConsumed;
+		if (txMeta.meta === null) {
+			throw new Error(`tx has no meta: ${JSON.stringify(txMeta)}`);
+		}
+		return txMeta.meta;
+	}
+
+	findComputeUnitConsumption(signature: string): bigint {
+		return this.getTransactionMetaOrThrow(signature).computeUnitsConsumed;
 	}
 
 	printTxLogs(signature: string): void {
-		const txMeta = this.transactionToMeta.get(
-			signature as TransactionSignature
-		);
-		if (txMeta === undefined) {
-			throw new Error('Transaction not found');
-		}
-		console.log(txMeta.meta.logMessages);
+		console.log(this.getTransactionMetaOrThrow(signature).logMessages);
 	}
 
 	async simulateTransaction(
@@ -467,22 +532,27 @@ export class BankrunConnection {
 		const simulationResult = await this._banksClient.simulateTransaction(
 			transaction
 		);
-		const returnDataProgramId =
-			simulationResult.meta?.returnData?.programId.toBase58();
-		const returnDataNormalized = Buffer.from(
-			simulationResult.meta?.returnData?.data
-		).toString('base64');
-		const returnData: TransactionReturnData = {
-			programId: returnDataProgramId,
-			data: [returnDataNormalized, 'base64'],
-		};
+		const meta = simulationResult.meta;
+		if (meta === null) {
+			throw new Error('BankrunConnection: simulation returned no meta');
+		}
+		let returnData: TransactionReturnData | undefined;
+		if (meta.returnData !== null) {
+			const returnDataNormalized = Buffer.from(meta.returnData.data).toString(
+				'base64'
+			);
+			returnData = {
+				programId: meta.returnData.programId.toBase58(),
+				data: [returnDataNormalized, 'base64'],
+			};
+		}
 		return {
 			context: { slot: Number(await this._banksClient.getSlot()) },
 			value: {
 				err: simulationResult.result,
-				logs: simulationResult.meta.logMessages,
+				logs: meta.logMessages,
 				accounts: undefined,
-				unitsConsumed: Number(simulationResult.meta.computeUnitsConsumed),
+				unitsConsumed: Number(meta.computeUnitsConsumed),
 				returnData,
 			},
 		};

package/src/blockhashSubscriber/BlockhashSubscriber.ts

@@ -9,7 +9,7 @@ import { BlockhashSubscriberConfig } from './types';
 export class BlockhashSubscriber {
 	private connection: Connection;
 	private isSubscribed = false;
-	private latestBlockHeight: number;
+	private latestBlockHeight: number | undefined;
 	private latestBlockHeightContext: Context | undefined;
 	private blockhashes: Array<BlockhashWithExpiryBlockHeight> = [];
 	private updateBlockhashIntervalId: ReturnType<typeof setTimeout> | undefined;
@@ -31,7 +31,7 @@ export class BlockhashSubscriber {
 		return this.blockhashes.length;
 	}
 
-	getLatestBlockHeight(): number {
+	getLatestBlockHeight(): number | undefined {
 		return this.latestBlockHeight;
 	}
 
@@ -67,9 +67,10 @@ export class BlockhashSubscriber {
 	}
 
 	pruneBlockhashes() {
-		if (this.latestBlockHeight) {
+		if (this.latestBlockHeight !== undefined) {
+			const latestBlockHeight = this.latestBlockHeight;
 			this.blockhashes = this.blockhashes.filter(
-				(blockhash) => blockhash.lastValidBlockHeight > this.latestBlockHeight!
+				(blockhash) => blockhash.lastValidBlockHeight > latestBlockHeight
 			);
 		}
 	}

package/src/clock/clockSubscriber.ts

@@ -14,17 +14,17 @@ export interface ClockSubscriberEvent {
 }
 
 export class ClockSubscriber {
-	private _latestSlot: number;
-	private _currentTs: number;
-	private subscriptionId: number;
+	private _latestSlot?: number;
+	private _currentTs?: number;
+	private subscriptionId?: number;
 	commitment: Commitment;
 	eventEmitter: StrictEventEmitter<EventEmitter, ClockSubscriberEvent>;
 
-	public get latestSlot(): number {
+	public get latestSlot(): number | undefined {
 		return this._latestSlot;
 	}
 
-	public get currentTs(): number {
+	public get currentTs(): number | undefined {
 		return this._currentTs;
 	}
 
@@ -41,7 +41,7 @@ export class ClockSubscriber {
 		this.eventEmitter = new EventEmitter();
 		this.resubTimeoutMs = config?.resubTimeoutMs;
 		this.commitment = config?.commitment || 'confirmed';
-		if (this.resubTimeoutMs < 1000) {
+		if (this.resubTimeoutMs !== undefined && this.resubTimeoutMs < 1000) {
 			console.log(
 				'resubTimeoutMs should be at least 1000ms to avoid spamming resub'
 			);
@@ -63,12 +63,13 @@ export class ClockSubscriber {
 						this.setTimeout();
 					}
 					this._latestSlot = context.slot;
-					this._currentTs = new BN(
+					const currentTs = new BN(
 						acctInfo.data.subarray(32, 39),
 						undefined,
 						'le'
 					).toNumber();
-					this.eventEmitter.emit('clockUpdate', this.currentTs);
+					this._currentTs = currentTs;
+					this.eventEmitter.emit('clockUpdate', currentTs);
 				}
 			},
 			this.commitment
@@ -98,7 +99,7 @@ export class ClockSubscriber {
 		}, this.resubTimeoutMs);
 	}
 
-	public getUnixTs(): number {
+	public getUnixTs(): number | undefined {
 		return this.currentTs;
 	}
 

package/src/config.ts

@@ -49,8 +49,9 @@ export const VELOCITY_DEVNET_PROGRAM_ID =
 export const VELOCITY_ORACLE_RECEIVER_ID =
 	'G6EoTTTgpkNBtVXo96EQp2m6uwwVh2Kt6YidjkmQqoha';
 
-export const PTYH_LAZER_PROGRAM_ID =
+export const PYTH_LAZER_PROGRAM_ID =
 	'pytd2yyk641x7ak7mkaasSJVXh6YYZnC7wTmtgAyxPt';
+
 export const SB_ON_DEMAND_DEVNET_PID = new PublicKey(
 	'Aio4gaXjXzJNVLtzwtNVmSqGKpANtXhybbkhtAC94ji2'
 );
@@ -137,9 +138,13 @@ export function getMarketsAndOraclesForSubscription(
 	oracleInfos: OracleInfo[];
 } {
 	const perpMarketsToUse =
-		perpMarkets?.length > 0 ? perpMarkets : PerpMarkets[env];
+		perpMarkets !== undefined && perpMarkets.length > 0
+			? perpMarkets
+			: PerpMarkets[env];
 	const spotMarketsToUse =
-		spotMarkets?.length > 0 ? spotMarkets : SpotMarkets[env];
+		spotMarkets !== undefined && spotMarkets.length > 0
+			? spotMarkets
+			: SpotMarkets[env];
 
 	const perpMarketIndexes = [];
 	const spotMarketIndexes = [];

package/src/constants/index.ts

@@ -1,9 +1,8 @@
 /**
  * Protocol constants: numeric precision bases, market indices, transaction size limits,
- * insurance fund parameters, and perp/spot market config arrays.
+ * and perp/spot market config arrays.
  * Import specific submodules to avoid pulling in unused market lists.
  */
-export * from './insuranceFund';
 export * from './numericConstants';
 export * from './perpMarkets';
 export * from './spotMarkets';

package/src/constants/numericConstants.ts

@@ -1,6 +1,5 @@
 import { LAMPORTS_PER_SOL } from '@solana/web3.js';
 import { BN } from '../isomorphic/anchor';
-import { BigNum } from '../factory/bigNum';
 
 export const ZERO = new BN(0);
 export const ONE = new BN(1);
@@ -85,6 +84,9 @@ export const MARGIN_PRECISION = TEN_THOUSAND;
 export const BID_ASK_SPREAD_PRECISION = new BN(1000000); // 10^6
 export const LIQUIDATION_PCT_PRECISION = TEN_THOUSAND;
 export const FUNDING_RATE_OFFSET_DENOMINATOR = new BN(3333);
+export const FUNDING_RATE_OFFSET_PERCENTAGE = FUNDING_RATE_PRECISION.div(
+	FUNDING_RATE_OFFSET_DENOMINATOR
+);
 export const FUNDING_RATE_CLAMP_DENOMINATOR = new BN(2000);
 export const PRICE_TIMES_AMM_TO_QUOTE_PRECISION_RATIO = PRICE_PRECISION.mul(
 	AMM_TO_QUOTE_PRECISION_RATIO
@@ -95,7 +97,6 @@ export const ONE_HOUR = new BN(60 * 60);
 export const ONE_YEAR = new BN(31536000);
 
 export const QUOTE_SPOT_MARKET_INDEX = 0;
-export const GOV_SPOT_MARKET_INDEX = 15;
 
 export const LAMPORTS_PRECISION = new BN(LAMPORTS_PER_SOL);
 export const LAMPORTS_EXP = new BN(Math.log10(LAMPORTS_PER_SOL));
@@ -115,5 +116,8 @@ export const DUST_POSITION_SIZE = QUOTE_PRECISION.divn(100); // Dust position is
 export const GET_MULTIPLE_ACCOUNTS_CHUNK_SIZE = 99;
 
 // integer constants
-export const MAX_I64 = BigNum.fromPrint('9223372036854775807').val;
-export const MIN_I64 = BigNum.fromPrint('-9223372036854775808').val;
+// Built with `BN` directly (not `BigNum.fromPrint`) to avoid a module-load
+// circular dependency: `bigNum.ts` imports `ZERO` from this file, so importing
+// `bigNum.ts` first leaves `BigNum` undefined while this module body evaluates.
+export const MAX_I64 = new BN('9223372036854775807');
+export const MIN_I64 = new BN('-9223372036854775808');

package/src/constituentMap/constituentMap.ts

@@ -98,6 +98,12 @@ export class ConstituentMap implements ConstituentMapInterface {
 					config.subscriptionConfig.commitment,
 					this.getFilters()
 				);
+		} else {
+			throw new Error(
+				`ConstituentMap: unsupported subscriptionConfig type: ${
+					(config.subscriptionConfig as { type: string }).type
+				}`
+			);
 		}
 
 		// Listen for account updates from the subscriber
@@ -184,7 +190,8 @@ export class ConstituentMap implements ConstituentMapInterface {
 			);
 			await Promise.all(promises);
 		} catch (error) {
-			console.log(`ConstituentMap.sync() error: ${error.message}`);
+			const message = error instanceof Error ? error.message : String(error);
+			console.log(`ConstituentMap.sync() error: ${message}`);
 		}
 	}
 

package/src/constituentMap/pollingConstituentAccountSubscriber.ts

@@ -63,10 +63,12 @@ export class PollingConstituentAccountSubscriber
 			await this.constituentMap.sync();
 			this.eventEmitter.emit('update');
 		} catch (error) {
+			const normalizedError =
+				error instanceof Error ? error : new Error(String(error));
 			console.log(
-				`PollingConstituentAccountSubscriber.sync() error: ${error.message}`
+				`PollingConstituentAccountSubscriber.sync() error: ${normalizedError.message}`
 			);
-			this.eventEmitter.emit('error', error);
+			this.eventEmitter.emit('error', normalizedError);
 		}
 	}
 

package/src/constituentMap/webSocketConstituentAccountSubscriber.ts

@@ -21,7 +21,15 @@ export class WebSocketConstituentAccountSubscriber
 	program: VelocityProgram;
 	eventEmitter: StrictEventEmitter<EventEmitter, ConstituentAccountEvents>;
 
-	constituentDataAccountSubscriber: WebSocketProgramAccountSubscriber<ConstituentAccount>;
+	private _constituentDataAccountSubscriber?: WebSocketProgramAccountSubscriber<ConstituentAccount>;
+	private get constituentDataAccountSubscriber(): WebSocketProgramAccountSubscriber<ConstituentAccount> {
+		if (!this._constituentDataAccountSubscriber) {
+			throw new Error(
+				'WebSocketConstituentAccountSubscriber: constituentDataAccountSubscriber accessed before subscribe()'
+			);
+		}
+		return this._constituentDataAccountSubscriber;
+	}
 	constituentMap: ConstituentMap;
 	private additionalFilters?: MemcmpFilter[];
 
@@ -45,7 +53,7 @@ export class WebSocketConstituentAccountSubscriber
 		if (this.isSubscribed) {
 			return true;
 		}
-		this.constituentDataAccountSubscriber =
+		this._constituentDataAccountSubscriber =
 			new WebSocketProgramAccountSubscriber<ConstituentAccount>(
 				'LpPoolConstituent',
 				'constituent',
@@ -85,10 +93,11 @@ export class WebSocketConstituentAccountSubscriber
 			await this.constituentMap.sync();
 			this.eventEmitter.emit('update');
 		} catch (error) {
+			const err = error instanceof Error ? error : new Error(String(error));
 			console.log(
-				`WebSocketConstituentAccountSubscriber.sync() error: ${error.message}`
+				`WebSocketConstituentAccountSubscriber.sync() error: ${err.message}`
 			);
-			this.eventEmitter.emit('error', error);
+			this.eventEmitter.emit('error', err);
 		}
 	}
 

package/src/core/instructions/perpOrders.ts

@@ -82,6 +82,20 @@ export async function buildPlaceAndMakePerpOrderInstruction(args: {
 	);
 }
 
+/**
+ * Build a raw `cancelOrder` instruction.
+ *
+ * Pass `orderId: null` to cancel the user's most recently placed order. The program
+ * resolves a `null` ID on-chain via `get_last_order_id`, which makes this safe to use
+ * in a multi-instruction transaction where a place instruction precedes the cancel and
+ * the program-assigned order ID is not yet known at build time — e.g.:
+ *
+ *   [placePerpOrder] → [cancelOrder(orderId: null)]
+ *
+ * The on-chain `order_id` counter is a monotonically incrementing u32 on the user
+ * account, so `get_last_order_id` reliably points to the order placed in the preceding
+ * instruction of the same transaction.
+ */
 export async function buildCancelOrderInstruction(args: {
 	program: VelocityProgram;
 	orderId: number | null;

package/src/core/remainingAccounts.ts

@@ -25,11 +25,11 @@ export type RemainingAccountsContext = {
 
 	/** Used to resolve user's last slot for cache invalidation. */
 	getUserAccountAndSlot: (
-		subAccountId: number,
+		subAccountId: number | undefined,
 		authority: PublicKey
 	) => { slot: number } | undefined;
 
-	activeSubAccountId: number;
+	activeSubAccountId: number | undefined;
 	authority: PublicKey;
 
 	/** Mutable caches + forced-market sets (owned by caller). */
@@ -57,7 +57,7 @@ export function getRemainingAccounts(
 		)?.slot;
 
 		for (const [marketIndex, slot] of ctx.perpMarketLastSlotCache.entries()) {
-			if (slot > lastUserSlot) {
+			if (lastUserSlot !== undefined && slot > lastUserSlot) {
 				addPerpMarketToRemainingAccountMaps(
 					ctx,
 					marketIndex,
@@ -72,7 +72,7 @@ export function getRemainingAccounts(
 		}
 
 		for (const [marketIndex, slot] of ctx.spotMarketLastSlotCache.entries()) {
-			if (slot > lastUserSlot) {
+			if (lastUserSlot !== undefined && slot > lastUserSlot) {
 				addSpotMarketToRemainingAccountMaps(
 					ctx,
 					marketIndex,