Transactions

Every write the SDK performs goes through two injectable pieces:

• TxHandler builds and signs transactions. It resolves the blockhash, injects the compute-budget instructions, compiles address lookup tables, and calls the wallet.
• A TxSender broadcasts and confirms them. Four implementations ship with the SDK, each with a different retry and confirmation model.

VelocityClient creates both for you, and you can replace either through its config:

import { VelocityClient, WhileValidTxSender, TxHandler } from "@velocity-exchange/sdk";
 
const txHandler = new TxHandler({
  connection,
  wallet,
  confirmationOptions: { commitment: "confirmed", preflightCommitment: "confirmed" },
});
 
const velocityClient = new VelocityClient({
  connection,
  wallet,
  env: "mainnet-beta",
  txHandler,
  txSender: new WhileValidTxSender({ connection, wallet, txHandler }),
  txParams: { computeUnits: 600_000, computeUnitsPrice: 0 },
});

If you pass nothing, VelocityClient builds a TxHandler from its own connection and wallet, then wraps it in a RetryTxSender. Default txParams are computeUnits: 600_000 and computeUnitsPrice: 0, so by default you pay no priority fee.

Choosing a tx sender

All four senders share the same TxSender interface (send, sendVersionedTransaction, getVersionedTransaction, sendRawTransaction, simulateTransaction, plus getTimeoutCount, getTxLandRate, getSuggestedPriorityFeeMultiplier). They differ in how the transaction reaches the cluster and how long they keep trying.

Shared constructor options:

FastSingleTxSender adds skipConfirmation (return immediately after sending), confirmInBackground (confirm without awaiting, so the returned slot is undefined), blockhashRefreshInterval (default 10,000 ms, 0 disables the loop), and blockhashCommitment (default finalized). WhileValidTxSender adds throwOnTransactionError (default true).

import { FastSingleTxSender } from "@velocity-exchange/sdk";
 
// Fire-and-forget: return as soon as the send lands, confirm in the background.
const txSender = new FastSingleTxSender({
  connection,
  wallet,
  confirmInBackground: true,
  blockhashRefreshInterval: 5_000,
  trackTxLandRate: true,
});
 
const velocityClient = new VelocityClient({ connection, wallet, txSender });

import { ForwardOnlyTxSender } from "@velocity-exchange/sdk";
 
// Submission is delegated: the SDK only confirms.
const txSender = new ForwardOnlyTxSender({
  connection,
  wallet,
  retrySleep: 5_000,
  additionalTxSenderCallbacks: [
    (base58EncodedTx) => myRelay.submit(base58EncodedTx),
  ],
});

Blockhash handling in TxHandler

TxHandler owns blockhash resolution. By default it uses a caching fetcher that reuses a recent blockhash for 2,000 ms, which collapses per-build getLatestBlockhash calls during bursts. Blockhashes stay valid on-chain far longer than that window, so this is safe.

The commitment used for blockhash fetches comes from confirmationOptions.preflightCommitment, falling back to connection.commitment, then confirmed.

import { TxHandler } from "@velocity-exchange/sdk";
 
const txHandler = new TxHandler({
  connection,
  wallet,
  confirmationOptions: { commitment: "confirmed", preflightCommitment: "confirmed" },
  config: {
    blockhashCachingEnabled: true,
    blockhashCachingConfig: { staleCacheTimeMs: 2_000 },
  },
});
 
// Build a v0 transaction from raw instructions.
const tx = await txHandler.buildTransaction({
  instructions: [ix],
  txVersion: 0,
  connection,
  fetchAllMarketLookupTableAccounts: () => velocityClient.fetchAllLookupTableAccounts(),
  txParams: { computeUnits: 400_000, computeUnitsPrice: 25_000 },
});

Compute units and priority fee params

txParams is a BaseTxParams plus a ProcessingTxParams. The base half is what ends up in the compute-budget instructions; the processing half tells the SDK how to derive those numbers.

TransactionParamProcessor

TransactionParamProcessor.process() runs the simulation pipeline. It rebuilds the transaction with the limit forced to 1,400,000 units so simulation is not constrained by an undersized budget, simulates it with replaceRecentBlockhash: true (which avoids spurious blockHashNotFound failures from an already-stale blockhash), then multiplies the measured usage by the buffer and clamps the result to 1,400,000.

Simulation failure is not fatal. getTxSimComputeUnits catches every error and returns { success: false }, and process() then leaves the original computeUnits in place. The only cases that throw are misconfiguration: useSimulatedComputeUnitsForCUPriceCalculation without useSimulatedComputeUnits, without getCUPriceFromComputeUnits, or when the simulated unit count is unavailable.

import { TransactionParamProcessor } from "@velocity-exchange/sdk";
 
// Size the limit from a simulation and derive the price from the result.
const velocityClient = new VelocityClient({
  connection,
  wallet,
  txParams: {
    computeUnits: 600_000,          // fallback if the simulation fails
    useSimulatedComputeUnits: true,
    computeUnitsBufferMultiplier: 1.2,
    lowerBoundCu: 100_000,
    useSimulatedComputeUnitsForCUPriceCalculation: true,
    getCUPriceFromComputeUnits: (computeUnits) =>
      Math.floor(priorityFeeSubscriber.getCustomStrategyResult()),
  },
});
 
// Or size one transaction directly.
const { success, computeUnits } = await TransactionParamProcessor.getTxSimComputeUnits(
  tx,
  connection,
  1.2,            // buffer multiplier, mandatory
  100_000         // optional lower bound
);

PriorityFeeCalculator

PriorityFeeCalculator is a smaller, reactive helper: it watches a sender’s timeout count and turns the priority fee on only after transactions start timing out, then latches it on for priorityFeeLatchDurationMs (default 10,000 ms). Its generateComputeBudgetWithPriorityFeeIx() converts a target total fee in micro-lamports into a per-unit price by dividing by the compute-unit limit.

import { PriorityFeeCalculator } from "@velocity-exchange/sdk";
 
const calculator = new PriorityFeeCalculator(Date.now());
 
const usePriorityFee = calculator.updatePriorityFee(
  Date.now(),
  velocityClient.txSender.getTimeoutCount()
);
 
const computeBudgetIxs = calculator.generateComputeBudgetWithPriorityFeeIx(
  600_000,        // compute unit limit
  usePriorityFee,
  1_000_000       // additional fee to pay, in micro-lamports
);

Priority fee subscribers

For a live fee estimate rather than a reactive switch, use the priorityFee module. PriorityFeeSubscriber polls one fee source on an interval (default 10,000 ms) and exposes the latest aggregate. Every value it returns is in micro-lamports per compute unit, the unit ComputeBudgetProgram.setComputeUnitPrice expects.

Fee sources

priorityFeeMethod selects the upstream API. It defaults to PriorityFeeMethod.SOLANA.

The constructor throws if you select HELIUS without a resolvable Helius URL, or SOLANA without a connection.

addresses scopes SOLANA and HELIUS sampling to the accounts your transaction will write-lock, which is what you want: it measures congestion on the markets you are trading, not the whole cluster.

Strategies

customStrategy is any object implementing PriorityFeeStrategy.calculate(samples). Five implementations ship with the SDK.

Prefer the ...OverSlots variants unless you handle the empty case yourself.

Every getter (getCustomStrategyResult, getAvgStrategyResult, getMaxStrategyResult) multiplies by priorityFeeMultiplier (default 1.0) and then clamps to maxFeeMicroLamports if you set one. All three return 0 before the first successful load(). getHeliusPriorityFeeLevel clamps but does not apply the multiplier. Both the multiplier and the clamp can be changed at runtime with updatePriorityFeeMultiplier() and updateMaxPriorityFee().

import {
  PriorityFeeSubscriber,
  PriorityFeeMethod,
  EwmaStrategy,
} from "@velocity-exchange/sdk";
 
const priorityFeeSubscriber = new PriorityFeeSubscriber({
  connection,
  frequencyMs: 5_000,
  priorityFeeMethod: PriorityFeeMethod.SOLANA,
  slotsToCheck: 50,
  addresses: [perpMarketPublicKey, userAccountPublicKey],
  customStrategy: new EwmaStrategy(25),
  priorityFeeMultiplier: 1.5,
  maxFeeMicroLamports: 1_000_000,
});
 
await priorityFeeSubscriber.subscribe();
 
// Micro-lamports per compute unit, multiplied and clamped.
const computeUnitsPrice = Math.floor(priorityFeeSubscriber.getCustomStrategyResult());
 
await priorityFeeSubscriber.unsubscribe();

load() swallows errors and logs them, so a transient RPC failure leaves the previous values in place until the next poll. Call updateAddresses() or updateMarketTypeAndIndex() to change what is sampled; both take effect on the next poll.

PriorityFeeSubscriberMap

PriorityFeeSubscriberMap fetches per-market fee levels for many markets in one request and keeps them addressable individually, rather than collapsing them into a single aggregate. It only supports the Velocity endpoint.

import { PriorityFeeSubscriberMap } from "@velocity-exchange/sdk";
 
const subscriberMap = new PriorityFeeSubscriberMap({
  velocityPriorityFeeEndpoint: "https://dlob.velocity.exchange",
  frequencyMs: 5_000,
  velocityMarkets: [
    { marketType: "perp", marketIndex: 0 },
    { marketType: "perp", marketIndex: 1 },
    { marketType: "spot", marketIndex: 2 },
  ],
});
 
await subscriberMap.subscribe();
 
// undefined until the first successful load
const fees = subscriberMap.getPriorityFees("perp", 0);
console.log(fees?.medium, fees?.veryHigh);

Reacting to poor landing

With trackTxLandRate: true, the sender records each signature and computes a rolling land rate. Feed the suggested multiplier into your compute-unit price to back off automatically under congestion:

const txSender = new RetryTxSender({
  connection,
  wallet,
  trackTxLandRate: true,
  txLandRateLookbackWindowMinutes: 10,
});
 
const landRate = txSender.getTxLandRate();                    // 0 to 1
const multiplier = txSender.getSuggestedPriorityFeeMultiplier(); // 1 to 10
const timeouts = txSender.getTimeoutCount();
 
const computeUnitsPrice = Math.floor(
  priorityFeeSubscriber.getCustomStrategyResult() * multiplier
);

Related

• Setup - creating the client and its config
• SDK Internals - subscription modes and instruction building
• Orderbook + DLOB websocket - the hosted /priorityFees and /batchPriorityFees endpoints
• Bot Architecture - production bot patterns