@velocity-exchange/sdk 0.1.0 → 0.2.1

package/lib/browser/velocityClient.d.ts

@@ -1,5 +1,4 @@
 /// <reference types="node" />
-/// <reference types="bn.js" />
 /// <reference types="node" />
 /// <reference types="node" />
 /**
@@ -57,11 +56,12 @@ export declare class VelocityClient {
     program: VelocityProgram;
     provider: AnchorProvider;
     env: VelocityEnv;
-    opts?: ConfirmOptions;
+    opts: ConfirmOptions;
     useHotWalletAdmin?: boolean;
     users: Map<string, User>;
     userStats?: UserStats;
-    activeSubAccountId: number;
+    userStatsAccountPublicKey?: PublicKey;
+    activeSubAccountId: number | undefined;
     userAccountSubscriptionConfig: UserSubscriptionConfig;
     userStatsAccountSubscriptionConfig: UserStatsSubscriptionConfig;
     accountSubscriber: VelocityClientAccountSubscriber;
@@ -74,12 +74,8 @@ export declare class VelocityClient {
     mustIncludePerpMarketIndexes: Set<number>;
     mustIncludeSpotMarketIndexes: Set<number>;
     authority: PublicKey;
-    /** @deprecated use marketLookupTables */
-    marketLookupTable: PublicKey;
-    /** @deprecated use lookupTableAccounts */
-    lookupTableAccount: AddressLookupTableAccount;
     marketLookupTables: PublicKey[];
-    lookupTableAccounts: AddressLookupTableAccount[];
+    lookupTableAccounts?: AddressLookupTableAccount[];
     includeDelegates?: boolean;
     authoritySubAccountMap?: Map<string, number[]>;
     skipLoadUsers?: boolean;
@@ -111,6 +107,11 @@ export declare class VelocityClient {
      */
     forceGetStateAccount(): Promise<StateAccount>;
     getPerpMarketAccount(marketIndex: number): PerpMarketAccount | undefined;
+    /**
+     * Like {@link getPerpMarketAccount} but throws if the market is not loaded,
+     * for call sites that require a guaranteed account.
+     */
+    getPerpMarketAccountOrThrow(marketIndex: number): PerpMarketAccount;
     /**
      * Forces a fetch to rpc before returning accounts. Useful for anchor tests.
      * @param marketIndex
@@ -118,6 +119,11 @@ export declare class VelocityClient {
     forceGetPerpMarketAccount(marketIndex: number): Promise<PerpMarketAccount | undefined>;
     getPerpMarketAccounts(): PerpMarketAccount[];
     getSpotMarketAccount(marketIndex: number): SpotMarketAccount | undefined;
+    /**
+     * Like {@link getSpotMarketAccount} but throws if the market is not loaded,
+     * for call sites that require a guaranteed account.
+     */
+    getSpotMarketAccountOrThrow(marketIndex: number): SpotMarketAccount;
     /**
      * Forces a fetch to rpc before returning accounts. Useful for anchor tests.
      * @param marketIndex
@@ -126,8 +132,6 @@ export declare class VelocityClient {
     getSpotMarketAccounts(): SpotMarketAccount[];
     getQuoteSpotMarketAccount(): SpotMarketAccount;
     getOraclePriceDataAndSlot(oraclePublicKey: PublicKey, oracleSource: OracleSource): DataAndSlot<OraclePriceData> | undefined;
-    /** @deprecated use fetchAllLookupTableAccounts() */
-    fetchMarketLookupTableAccount(): Promise<AddressLookupTableAccount>;
     fetchAllLookupTableAccounts(): Promise<AddressLookupTableAccount[]>;
     private getTxVersionForNewWallet;
     /**
@@ -296,12 +300,22 @@ export declare class VelocityClient {
     getUser(subAccountId?: number, authority?: PublicKey): User;
     hasUser(subAccountId?: number, authority?: PublicKey): boolean;
     getUsers(): User[];
-    getUserStats(): UserStats;
+    getUserStats(): UserStats | undefined;
+    /**
+     * Like {@link getUserStats} but throws if there is no UserStats
+     * subscription, for call sites that require a guaranteed account.
+     */
+    getUserStatsOrThrow(): UserStats;
     fetchReferrerNameAccount(name: string): Promise<ReferrerNameAccount | undefined>;
-    userStatsAccountPublicKey: PublicKey;
     getUserStatsAccountPublicKey(): PublicKey;
     getUserAccountPublicKey(subAccountId?: number, authority?: PublicKey): Promise<PublicKey>;
     getUserAccount(subAccountId?: number, authority?: PublicKey): UserAccount | undefined;
+    /**
+     * Like {@link getUserAccount} but throws a named error instead of returning
+     * `undefined` when the account has not been loaded yet. Use at call sites
+     * that structurally require a loaded account.
+     */
+    getUserAccountOrThrow(subAccountId?: number, authority?: PublicKey): UserAccount;
     /**
      * Forces a fetch to rpc before returning accounts. Useful for anchor tests.
      * @param subAccountId
@@ -344,6 +358,8 @@ export declare class VelocityClient {
         perpMarketIndexes: number[];
         spotMarketIndexes: number[];
     }): void;
+    private cachePerpMarketSlot;
+    private cacheSpotMarketSlot;
     getRemainingAccounts(params: RemainingAccountParams): AccountMeta[];
     addPerpMarketToRemainingAccountMaps(marketIndex: number, writable: boolean, oracleAccountMap: Map<string, AccountMeta>, spotMarketAccountMap: Map<number, AccountMeta>, perpMarketAccountMap: Map<number, AccountMeta>): void;
     addSpotMarketToRemainingAccountMaps(marketIndex: number, writable: boolean, oracleAccountMap: Map<string, AccountMeta>, spotMarketAccountMap: Map<number, AccountMeta>): void;
@@ -353,7 +369,29 @@ export declare class VelocityClient {
         spotMarketAccountMap: Map<number, AccountMeta>;
         perpMarketAccountMap: Map<number, AccountMeta>;
     };
-    getOrder(orderId: number, subAccountId?: number): Order | undefined;
+    /**
+     * Look up an open order by its program-assigned order ID from the cached user account.
+     *
+     * `orderId` is the monotonically incrementing u32 counter that the program assigns at
+     * placement time — it is not known until the place instruction executes on-chain. Use
+     * {@link getOrderByUserId} when you need to look up an order by the caller-supplied
+     * `userOrderId` instead.
+     *
+     * Returns `undefined` when the order is not found (already filled, cancelled, or the
+     * account cache is stale).
+     */
+    getOrder(orderId: number | undefined, subAccountId?: number): Order | undefined;
+    /**
+     * Look up an open order by the caller-supplied `userOrderId` from the cached user account.
+     *
+     * `userOrderId` is a 1-255 slot chosen by the caller in {@link OrderParams} and is stable
+     * across the life of the order — useful when you need to reference an order before the
+     * program-assigned {@link Order.orderId} is known (e.g. immediately after placing without
+     * waiting for confirmation). Use {@link getOrder} when you have the program-assigned ID.
+     *
+     * Returns `undefined` when the order is not found (already filled, cancelled, or the
+     * account cache is stale).
+     */
     getOrderByUserId(userOrderId: number, subAccountId?: number): Order | undefined;
     /**
      * Get the associated token address for the given spot market
@@ -440,7 +478,7 @@ export declare class VelocityClient {
     initializeUserAccountAndDepositCollateral(amount: BN, userTokenAccount: PublicKey, marketIndex?: number, subAccountId?: number, name?: string, fromSubAccountId?: number, referrerInfo?: ReferrerInfo, donateAmount?: BN, txParams?: TxParams, customMaxMarginRatio?: number, poolId?: number, overrides?: {
         externalWallet?: PublicKey;
     }): Promise<[TransactionSignature, PublicKey]>;
-    initializeUserAccountForDevnet(subAccountId: number, name: string, marketIndex: number, tokenFaucet: TokenFaucet, amount: BN, referrerInfo?: ReferrerInfo, txParams?: TxParams): Promise<[TransactionSignature, PublicKey]>;
+    initializeUserAccountForDevnet(subAccountId: number | undefined, name: string | undefined, marketIndex: number, tokenFaucet: TokenFaucet, amount: BN, referrerInfo?: ReferrerInfo, txParams?: TxParams): Promise<[TransactionSignature, PublicKey]>;
     getWithdrawalIxs(amount: BN, marketIndex: number, associatedTokenAddress: PublicKey, reduceOnly?: boolean, subAccountId?: number): Promise<TransactionInstruction[]>;
     /**
      * Withdraws from a user account. If deposit doesn't already exist, creates a borrow
@@ -538,9 +576,38 @@ export declare class VelocityClient {
     getSettleExpiredMarketIx(marketIndex: number): Promise<TransactionInstruction>;
     settleExpiredMarketPoolsToRevenuePool(marketIndex: number, txParams?: TxParams): Promise<TransactionSignature>;
     getSettleExpiredMarketPoolsToRevenuePoolIx(perpMarketIndex: number): Promise<TransactionInstruction>;
+    /**
+     * Cancel an open order and broadcast the transaction.
+     *
+     * When `orderId` is `undefined` (omitted or passed explicitly), the instruction is
+     * sent with a `null` order ID and the program cancels the most recently placed order
+     * on-chain via `get_last_order_id`. This is safe to use in a composed transaction
+     * where a place instruction runs first and the assigned order ID is not yet known.
+     *
+     * Note: when `orderId` is `undefined` and `overrides.withdrawIsolatedDepositAmount`
+     * is also provided, `getOrder` will return `undefined` (the ID is unknown client-side),
+     * causing the withdraw path to throw — supply an explicit `orderId` in that case.
+     *
+     * @see {@link getCancelOrderIx} to obtain the instruction without sending.
+     */
     cancelOrder(orderId?: number, txParams?: TxParams, subAccountId?: number, overrides?: {
         withdrawIsolatedDepositAmount?: BN;
     }): Promise<TransactionSignature>;
+    /**
+     * Build a `cancelOrder` instruction for the given order.
+     *
+     * When `orderId` is `undefined` (omitted or passed explicitly), the instruction is
+     * built with a `null` order ID (`orderId ?? null`). The program interprets a `null`
+     * ID as "cancel the user's most recently placed order" (via `get_last_order_id`
+     * on-chain). This is useful when composing a multi-instruction transaction where a
+     * place instruction precedes the cancel and the program-assigned order ID is not yet
+     * known at build time.
+     *
+     * When `orderId` is supplied, only that specific order is cancelled.
+     *
+     * @see {@link cancelOrder} to send the transaction directly.
+     * @see {@link getCancelOrderByUserIdIx} to cancel by the caller-supplied `userOrderId`.
+     */
     getCancelOrderIx(orderId?: number, subAccountId?: number): Promise<TransactionInstruction>;
     cancelOrderByUserId(userOrderId: number, txParams?: TxParams, subAccountId?: number): Promise<TransactionSignature>;
     getCancelOrderByUserIdIx(userOrderId: number, subAccountId?: number): Promise<TransactionInstruction>;
@@ -568,7 +635,7 @@ export declare class VelocityClient {
         authority?: PublicKey;
     }): Promise<TransactionInstruction>;
     cancelOrders(marketType?: MarketType, marketIndex?: number, direction?: PositionDirection, txParams?: TxParams, subAccountId?: number): Promise<TransactionSignature>;
-    getCancelOrdersIx(marketType: MarketType | null, marketIndex: number | null, direction: PositionDirection | null, subAccountId?: number): Promise<TransactionInstruction>;
+    getCancelOrdersIx(marketType: MarketType | null | undefined, marketIndex: number | null | undefined, direction: PositionDirection | null | undefined, subAccountId?: number): Promise<TransactionInstruction>;
     cancelAndPlaceOrders(cancelOrderParams: {
         marketType?: MarketType;
         marketIndex?: number;
@@ -595,7 +662,7 @@ export declare class VelocityClient {
     }>;
     getPlaceScaleOrdersIx(params: ScaleOrderParams, subAccountId?: number): Promise<TransactionInstruction>;
     fillPerpOrder(userAccountPublicKey: PublicKey, user: UserAccount, order?: Pick<Order, 'marketIndex' | 'orderId'>, makerInfo?: MakerInfo | MakerInfo[], txParams?: TxParams, fillerSubAccountId?: number, fillerAuthority?: PublicKey, hasBuilderFee?: boolean, takerEscrow?: RevenueShareEscrowAccount): Promise<TransactionSignature>;
-    getFillPerpOrderIx(userAccountPublicKey: PublicKey, userAccount: UserAccount, order: Pick<Order, 'marketIndex' | 'orderId'>, makerInfo?: MakerInfo | MakerInfo[], fillerSubAccountId?: number, isSignedMsg?: boolean, fillerAuthority?: PublicKey, hasBuilderFee?: boolean, takerEscrow?: RevenueShareEscrowAccount): Promise<TransactionInstruction>;
+    getFillPerpOrderIx(userAccountPublicKey: PublicKey, userAccount: UserAccount, order?: Pick<Order, 'marketIndex' | 'orderId'>, makerInfo?: MakerInfo | MakerInfo[], fillerSubAccountId?: number, isSignedMsg?: boolean, fillerAuthority?: PublicKey, hasBuilderFee?: boolean, takerEscrow?: RevenueShareEscrowAccount): Promise<TransactionInstruction>;
     getRevertFillIx(fillerPublicKey?: PublicKey): Promise<TransactionInstruction>;
     placeSpotOrder(_orderParams: OptionalOrderParams, _txParams?: TxParams, _subAccountId?: number): Promise<TransactionSignature>;
     preparePlaceSpotOrderTx(_orderParams: OptionalOrderParams, _txParams?: TxParams, _subAccountId?: number): Promise<void>;
@@ -739,15 +806,15 @@ export declare class VelocityClient {
     getUpdateUserOpenOrdersCountIx(userAccountPublicKey: PublicKey, userAccount: UserAccount, fillerPublicKey?: PublicKey): Promise<TransactionInstruction>;
     placeAndTakePerpOrder(orderParams: OptionalOrderParams, makerInfo?: MakerInfo | MakerInfo[], successCondition?: PlaceAndTakeOrderSuccessCondition, auctionDurationPercentage?: number, txParams?: TxParams, subAccountId?: number, takerEscrow?: RevenueShareEscrowAccount): Promise<TransactionSignature>;
     preparePlaceAndTakePerpOrderWithAdditionalOrders(orderParams: OptionalOrderParams, makerInfo?: MakerInfo | MakerInfo[], bracketOrdersParams?: OptionalOrderParams[], txParams?: TxParams, subAccountId?: number, cancelExistingOrders?: boolean, settlePnl?: boolean, exitEarlyIfSimFails?: boolean, auctionDurationPercentage?: number, optionalIxs?: TransactionInstruction[], isolatedPositionDepositAmount?: BN): Promise<{
-        placeAndTakeTx: Transaction | VersionedTransaction;
-        cancelExistingOrdersTx: Transaction | VersionedTransaction;
-        settlePnlTx: Transaction | VersionedTransaction;
-    }>;
+        placeAndTakeTx: Transaction | VersionedTransaction | undefined;
+        cancelExistingOrdersTx: Transaction | VersionedTransaction | undefined;
+        settlePnlTx: Transaction | VersionedTransaction | undefined;
+    } | null>;
     placeAndTakePerpWithAdditionalOrders(orderParams: OptionalOrderParams, makerInfo?: MakerInfo | MakerInfo[], bracketOrdersParams?: OptionalOrderParams[], txParams?: TxParams, subAccountId?: number, cancelExistingOrders?: boolean, settlePnl?: boolean, exitEarlyIfSimFails?: boolean): Promise<{
         txSig: TransactionSignature;
         signedCancelExistingOrdersTx?: Transaction;
         signedSettlePnlTx?: Transaction;
-    }>;
+    } | null>;
     getPlaceAndTakePerpOrderIx(orderParams: OptionalOrderParams, makerInfo?: MakerInfo | MakerInfo[], successCondition?: PlaceAndTakeOrderSuccessCondition, auctionDurationPercentage?: number, subAccountId?: number, overrides?: {
         authority?: PublicKey;
     }, takerEscrow?: RevenueShareEscrowAccount): Promise<TransactionInstruction>;
@@ -769,7 +836,7 @@ export declare class VelocityClient {
     };
     encodeSignedMsgOrderParamsMessage(orderParamsMessage: SignedMsgOrderParamsMessage | SignedMsgOrderParamsDelegateMessage, delegateSigner?: boolean): Buffer;
     decodeSignedMsgOrderParamsMessage(encodedMessage: Buffer, delegateSigner?: boolean): SignedMsgOrderParamsMessage | SignedMsgOrderParamsDelegateMessage;
-    signMessage(message: Uint8Array, keypair?: Keypair): Buffer;
+    signMessage(message: Uint8Array, keypair?: Keypair | undefined): Buffer;
     placeSignedMsgTakerOrder(signedSignedMsgOrderParams: SignedMsgOrderParams, marketIndex: number, takerInfo: {
         taker: PublicKey;
         takerStats: PublicKey;
@@ -1004,16 +1071,6 @@ export declare class VelocityClient {
         beginSwapIx: TransactionInstruction;
         endSwapIx: TransactionInstruction;
     }>;
-    getInsuranceFundSwapIx({ inMarketIndex, outMarketIndex, amountIn, inTokenAccount, outTokenAccount, }: {
-        inMarketIndex: number;
-        outMarketIndex: number;
-        amountIn: BN;
-        inTokenAccount: PublicKey;
-        outTokenAccount: PublicKey;
-    }): Promise<{
-        beginSwapIx: TransactionInstruction;
-        endSwapIx: TransactionInstruction;
-    }>;
     liquidateBorrowForPerpPnl(userAccountPublicKey: PublicKey, userAccount: UserAccount, perpMarketIndex: number, liabilityMarketIndex: number, maxLiabilityTransfer: BN, limitPrice?: BN, txParams?: TxParams, liquidatorSubAccountId?: number): Promise<TransactionSignature>;
     getLiquidateBorrowForPerpPnlIx(userAccountPublicKey: PublicKey, userAccount: UserAccount, perpMarketIndex: number, liabilityMarketIndex: number, maxLiabilityTransfer: BN, limitPrice?: BN, liquidatorSubAccountId?: number): Promise<TransactionInstruction>;
     liquidatePerpPnlForDeposit(userAccountPublicKey: PublicKey, userAccount: UserAccount, perpMarketIndex: number, assetMarketIndex: number, maxPnlTransfer: BN, limitPrice?: BN, txParams?: TxParams, liquidatorSubAccountId?: number): Promise<TransactionSignature>;
@@ -1087,10 +1144,10 @@ export declare class VelocityClient {
     removeInsuranceFundStake(marketIndex: number, collateralAccountPublicKey: PublicKey, txParams?: TxParams): Promise<TransactionSignature>;
     updateUserQuoteAssetInsuranceStake(authority: PublicKey, txParams?: TxParams): Promise<TransactionSignature>;
     getUpdateUserQuoteAssetInsuranceStakeIx(authority: PublicKey): Promise<TransactionInstruction>;
-    updateUserGovTokenInsuranceStake(authority: PublicKey, txParams?: TxParams): Promise<TransactionSignature>;
-    getUpdateUserGovTokenInsuranceStakeIx(authority: PublicKey): Promise<TransactionInstruction>;
     settleRevenueToInsuranceFund(spotMarketIndex: number, txParams?: TxParams): Promise<TransactionSignature>;
     getSettleRevenueToInsuranceFundIx(spotMarketIndex: number): Promise<TransactionInstruction>;
+    sweepPerpMarketFees(perpMarketIndex: number, txParams?: TxParams): Promise<TransactionSignature>;
+    getSweepPerpMarketFeesIx(perpMarketIndex: number): Promise<TransactionInstruction>;
     resolvePerpPnlDeficit(spotMarketIndex: number, perpMarketIndex: number, txParams?: TxParams): Promise<TransactionSignature>;
     getResolvePerpPnlDeficitIx(spotMarketIndex: number, perpMarketIndex: number): Promise<TransactionInstruction>;
     getDepositIntoSpotMarketRevenuePoolIx(marketIndex: number, amount: BN, userTokenAccountPublicKey: PublicKey): Promise<TransactionInstruction>;
@@ -1231,7 +1288,7 @@ export declare class VelocityClient {
      */
     sendTransaction(tx: Transaction | VersionedTransaction, additionalSigners?: Array<Signer>, opts?: ConfirmOptions, preSigned?: boolean): Promise<TxSigAndSlot>;
     buildTransaction(instructions: TransactionInstruction | TransactionInstruction[], txParams?: TxParams, txVersion?: TransactionVersion, lookupTables?: AddressLookupTableAccount[], forceVersionedTransaction?: boolean, recentBlockhash?: BlockhashWithExpiryBlockHeight, optionalIxs?: TransactionInstruction[]): Promise<Transaction | VersionedTransaction>;
-    buildBulkTransactions(instructions: (TransactionInstruction | TransactionInstruction[])[], txParams?: TxParams, txVersion?: TransactionVersion, lookupTables?: AddressLookupTableAccount[], forceVersionedTransaction?: boolean): Promise<(Transaction | VersionedTransaction)[]>;
+    buildBulkTransactions(instructions: (TransactionInstruction | TransactionInstruction[])[], txParams?: TxParams, txVersion?: TransactionVersion, lookupTables?: AddressLookupTableAccount[], forceVersionedTransaction?: boolean): Promise<(Transaction | VersionedTransaction | undefined)[]>;
     buildTransactionsMap(instructionsMap: Record<string, TransactionInstruction | TransactionInstruction[]>, txParams?: TxParams, txVersion?: TransactionVersion, lookupTables?: AddressLookupTableAccount[], forceVersionedTransaction?: boolean): Promise<MappedRecord<Record<string, TransactionInstruction | TransactionInstruction[]>, Transaction | VersionedTransaction>>;
     buildAndSignTransactionsMap(instructionsMap: Record<string, TransactionInstruction | TransactionInstruction[]>, txParams?: TxParams, txVersion?: TransactionVersion, lookupTables?: AddressLookupTableAccount[], forceVersionedTransaction?: boolean): Promise<{
         signedTxMap: Record<string, Transaction>;
@@ -1240,6 +1297,6 @@ export declare class VelocityClient {
         signedTxMap: MappedRecord<Record<string, TransactionInstruction | TransactionInstruction[]>, Transaction | VersionedTransaction>;
         signedTxData: SignedTxData[];
     }>;
-    isOrderIncreasingPosition(orderParams: OptionalOrderParams, subAccountId: number): boolean;
+    isOrderIncreasingPosition(orderParams: OptionalOrderParams, subAccountId?: number): boolean;
 }
 export {};