Account Model

Velocity is a Solana program that manages user accounts, positions, orders, and markets. This page is the field-level reference for the accounts it owns: what each one holds, how it is addressed, and where the layout differs from what a reader porting an older integration would expect. The Velocity SDK wraps all of it, so read this when a decoded value does not mean what it appeared to.

Core accounts

Four account types carry essentially all the state an integration reads: one global State, one account per market, one per subaccount, and one per wallet.

State account

There is exactly one State account per deployment, and almost every instruction loads it to apply protocol-level rules. It holds:

• Oracle guards: Stale price thresholds and validity checks (oracleGuardRails)
• Fee structures: Separate default fee tiers for perpetual and spot markets
• Admin controls: A tiered cold / warm / hot admin key model, plus protocol fee treasuries
• Solvency status: Bitflag gating bankruptcy and deficit-resolution instructions independently of the withdraw-pause flags
• Feature flags: exchangeStatus, featureBitFlags, lpPoolFeatureBitFlags
• Slot duration: slotDurationMs, pendingSlotDurationMs, and slotDurationEffectiveSlot, covered in Slot duration

interface StateAccount {
  coldAdmin: PublicKey;
  warmAdmin: PublicKey;
  pauseAdmin: PublicKey;
  hotFeeWithdraw: PublicKey;
  // ...additional narrowly-scoped hot* keys
  protocolFeeRecipientPerp: PublicKey;
  protocolFeeRecipientSpot: PublicKey;
  exchangeStatus: number;              // bitmask, see ExchangeStatus
  whitelistMint: PublicKey;
  discountMint: PublicKey;
  oracleGuardRails: OracleGuardRails;
  numberOfAuthorities: BN;
  numberOfSubAccounts: BN;
  numberOfMarkets: number;
  numberOfSpotMarkets: number;
  minPerpAuctionDuration: number;      // legacy 400ms slot-duration units, decode with millisFromStoredUnits
  defaultMarketOrderTimeInForce: number; // seconds
  defaultSpotAuctionDuration: number;  // slots
  liquidationMarginBufferRatio: number; // MARGIN_PRECISION (1e4)
  settlementDuration: number;          // seconds
  maxNumberOfSubAccounts: number;
  signer: PublicKey;
  signerNonce: number;
  perpFeeStructure: FeeStructure;
  spotFeeStructure: FeeStructure;
  initialPctToLiquidate: number;       // LIQUIDATION_PCT_PRECISION (1e4)
  liquidationDuration: number;         // legacy 400ms slot-duration units, decode with millisFromStoredUnits
  maxInitializeUserFee: number;
  featureBitFlags: number;             // bitmask, see FeatureBitFlags
  lpPoolFeatureBitFlags: number;
  solvencyStatus: number;              // bitmask, see SolvencyStatus
  slotDurationMs: number;              // u16; 0 = unset, resolves to the 400ms baseline
  pendingSlotDurationMs: number;       // u16; 0 = nothing staged
  slotDurationEffectiveSlot: BN;       // u64; slot the staged value takes effect
}

Market accounts

One account per market, in two flavours. Both are addressed by a numeric market index (market 0, market 1, and so on) rather than by name, and the SDK caches them after subscription so a lookup by index costs nothing.

PerpMarketAccount

One per perp market, 1560 bytes onchain. It carries:

• AMM state (amm): Base/quote reserves and liquidity parameters for the constant-product vAMM
• Oracle fields: oracle, oracleSource live at the top level of PerpMarketAccount (moved off amm.* when the AMM was decoupled)
• Market stats (marketStats): mark/oracle TWAPs, volume, and MM-oracle snapshot, shared across makers
• Hedge config (hedgeConfig): this market's relationship to its hedging Velocity liquidity pool (poolId, status, pausedOperations, exchangeFeeExclusionScalar, feeTransferScalar), replacing the earlier flat lp* LP-share fields
• Fee ledger (feeLedger): consolidated fee-split accounting (pending protocol/IF/AMM carveouts) from the fee redesign
• Risk parameters: marginRatioInitial / marginRatioMaintenance (MARGIN_PRECISION, 1e4), imfFactor, contractTier
• Market status: status: MarketStatus (see the discriminant note below)

interface PerpMarketAccount {
  status: MarketStatus;
  contractType: ContractType;
  contractTier: ContractTier;
  marketIndex: number;
  pubkey: PublicKey;
  name: number[];
  amm: AMM;
  marketStats: MarketStats;
  marginRatioInitial: number;        // MARGIN_PRECISION (1e4)
  marginRatioMaintenance: number;    // MARGIN_PRECISION (1e4)
  pnlPool: PoolBalance;
  protocolFeePool: PoolBalance;
  feeLedger: FeeLedger;
  liquidatorFee: number;             // LIQUIDATION_FEE_PRECISION (1e6)
  ifLiquidationFee: number;
  protocolLiquidationFee: number;
  feePoolBufferTarget: BN;           // QUOTE_PRECISION (1e6)
  imfFactor: number;
  unrealizedPnlImfFactor: number;
  unrealizedPnlMaxImbalance: BN;
  unrealizedPnlInitialAssetWeight: number;
  unrealizedPnlMaintenanceAssetWeight: number;
  insuranceClaim: { /* revenue withdraw caps and used insurance */ };
  quoteSpotMarketIndex: number;
  feeAdjustment: number;
  pausedOperations: number;          // bitmask, see PerpOperation
  poolId: number;
  hedgeConfig: {
    poolId: number;
    status: number;
    pausedOperations: number;
    exchangeFeeExclusionScalar: number;
    feeTransferScalar: number;
  };
  oracle: PublicKey;
  oracleSource: OracleSource;
  baseAssetAmountLong: BN;           // BASE_PRECISION (1e9)
  baseAssetAmountShort: BN;
  fundingClampThreshold: number;     // BPS_PRECISION (1e4)
  fundingRampSlope: number;          // PERCENTAGE_PRECISION (1e6)
  orderStepSize: BN;
  orderTickSize: BN;
}

SpotMarketAccount

One per spot market, 1064 bytes onchain. A spot market is both a collateral type and a lending pool, so the account carries both sets of parameters:

• Interest rates: Dynamic deposit/borrow rates based on utilization
• Insurance fund (insuranceFund): Now 100% staker-owned: totalFactor/userFactor were replaced by a single ifFeeFactor (the carveout of deposit-interest gains routed to stakers); there is no protocol-owned IF share anymore
• Protocol fee pool (protocolFeePool): Withdrawable protocol fee claim in this market's token
• Oracle integration: Price feeds for the spot asset (Pyth, Pyth Lazer; legacy pull oracles and Switchboard are deprecated, see below)
• Asset/liability weights: Collateral weights for risk calculations

interface SpotMarketAccount {
  status: MarketStatus;
  assetTier: AssetTier;
  name: number[];
  marketIndex: number;
  pubkey: PublicKey;
  mint: PublicKey;
  vault: PublicKey;
  oracle: PublicKey;
  oracleSource: OracleSource;
  historicalOracleData: HistoricalOracleData;
  historicalIndexData: HistoricalIndexData;
  insuranceFund: {
    vault: PublicKey;
    totalShares: BN;
    userShares: BN;
    ifFeeFactor: number;            // 1e6, the insurance-fund carveout share
  };
  revenuePool: PoolBalance;
  protocolFeePool: PoolBalance;
  ifLiquidationFee: number;
  protocolLiquidationFee: number;
  protocolFeeFactor: number;
  decimals: number;
  optimalUtilization: number;
  optimalBorrowRate: number;
  maxBorrowRate: number;
  cumulativeDepositInterest: BN;
  cumulativeBorrowInterest: BN;
  depositBalance: BN;               // SPOT_MARKET_BALANCE_PRECISION (1e9) scaled balance
  borrowBalance: BN;
  maxTokenDeposits: BN;
  initialAssetWeight: number;       // SPOT_MARKET_WEIGHT_PRECISION (1e4)
  maintenanceAssetWeight: number;
  initialLiabilityWeight: number;
  maintenanceLiabilityWeight: number;
  liquidatorFee: number;
  imfFactor: number;
  withdrawGuardThreshold: BN;
}

User accounts

UserAccount

One per subaccount, 4496 bytes onchain, holding all of that subaccount's trading state:

• Perp positions: Market index, base amount, quote entry, last funding index
• Spot positions: Deposits and borrows per market
• Open orders: Up to 32 active orders per user, stored inline
• Special/status bitmasks: status (UserStatus), specialUserStatus (SpecialUserStatus, e.g. VammHedger)
• Permissions: Delegate address and access controls

interface UserAccount {
  authority: PublicKey;
  delegate: PublicKey;
  name: number[];
  subAccountId: number;
  spotPositions: SpotPosition[];
  perpPositions: PerpPosition[];
  orders: Order[];
  status: number;                    // bitmask, see UserStatus
  nextLiquidationId: number;
  nextOrderId: number;
  maxMarginRatio: number;            // MARGIN_PRECISION (1e4); 0 = use market defaults
  settledPerpPnl: BN;                // QUOTE_PRECISION (1e6)
  totalDeposits: BN;
  totalWithdraws: BN;
  totalSocialLoss: BN;
  cumulativePerpFunding: BN;
  cumulativeSpotFees: BN;
  liquidationMarginFreed: BN;
  lastActiveSlot: BN;
  isMarginTradingEnabled: boolean;
  idle: boolean;
  openOrders: number;
  hasOpenOrder: boolean;
  openAuctions: number;
  hasOpenAuction: boolean;
  poolId: number;
  specialUserStatus: number;         // bitmask, see SpecialUserStatus
}

UserStatsAccount

One per wallet, aggregating across every subaccount that wallet owns. Fee tiering reads it, so it is the account that decides the tier a wallet trades at:

• Fee tracking: fees.totalFeePaid / totalFeeRebate / totalTokenDiscount / totalRefereeDiscount
• Volume metrics: makerVolume30D / takerVolume30D / fillerVolume30D (rolling 30-day windows)
• Referral data: referrer, referrerStatus (bitmask, ReferrerStatus, now including BuilderReferral)
• Delegate permissions: delegatePermissions (gates transferDepositByDelegate)

interface UserStatsAccount {
  numberOfSubAccounts: number;
  numberOfSubAccountsCreated: number;
  makerVolume30D: BN;                // QUOTE_PRECISION (1e6)
  takerVolume30D: BN;
  fillerVolume30D: BN;
  lastMakerVolume30DTs: BN;
  lastTakerVolume30DTs: BN;
  lastFillerVolume30DTs: BN;
  fees: {
    totalFeePaid: BN;
    totalFeeRebate: BN;
    totalTokenDiscount: BN;
    totalRefereeDiscount: BN;
  };
  referrer: PublicKey;
  referrerStatus: number;            // bitmask, see ReferrerStatus
  disableUpdatePerpBidAskTwap: number;
  pausedOperations: number;          // bitmask, see UserStatsPausedOperation
  authority: PublicKey;
  ifStakedQuoteAssetAmount: BN;
  delegatePermissions: number;
}

Each wallet can hold multiple subaccounts, numbered 0, 1, 2, and so on, each with its own collateral and its own liquidation risk. Cross-margin is shared within one subaccount, never across them; see Cross-margin and subaccounts.

Order accounting

Orders live inside the UserAccount itself rather than in separate accounts, which is why the per-user cap is a fixed 32 and why placing an order does not create rent-paying state. Each order carries:

• Market identification: Market index and type (perp/spot)
• Order parameters: Type (limit, market, oracle, trigger), direction, base amount, price
• Order IDs: System order ID (orderId) and user-defined order ID (userOrderId)
• Flags: postOnly, reduceOnly, and immediateOrCancel are their own boolean fields on Order, not bits. bitFlags is a separate bitmask holding the OrderBitFlag values: SignedMessage (1), OracleTriggerMarket (2), SafeTriggerOrder (4), NewTriggerReduceOnly (8), HasBuilder (16, order attaches a builder fee)
• Auction settings: JIT auction parameters (auctionStartPrice, auctionEndPrice, auctionDuration). auctionDuration is not a slot count: it stores wall-clock units of 400ms, so 10 is 4 seconds whatever the live slot duration is, and get_auction_duration clamps the sanitized value to between 1 and 180 units (0.4s to 72s). Decode it with millisFromStoredUnits, never with the live slot duration. See Slot duration.

A fully filled order has its status set to Filled rather than being zeroed, so it stays readable in the array until a later order takes the slot. Only orders with status == Open count against the cap: the program picks the first slot whose status is anything else, so a Filled or Canceled entry is free space. Reading 32 non-empty entries therefore does not mean 32 live orders, and MaxNumberOfOrders is raised only when all 32 are Open.

interface Order {
  status: OrderStatus;
  orderType: OrderType;
  marketType: MarketType;
  slot: BN;
  orderId: number;
  userOrderId: number;
  marketIndex: number;
  price: BN;                        // PRICE_PRECISION (1e6)
  baseAssetAmount: BN;               // BASE_PRECISION (1e9) for perp
  baseAssetAmountFilled: BN;
  quoteAssetAmountFilled: BN;        // QUOTE_PRECISION (1e6)
  direction: PositionDirection;
  reduceOnly: boolean;
  triggerPrice: BN;
  triggerCondition: OrderTriggerCondition;
  existingPositionDirection: PositionDirection;
  postOnly: boolean;
  immediateOrCancel: boolean;
  oraclePriceOffset: BN;             // i64 offset from oracle price
  auctionDuration: number;
  auctionStartPrice: BN;
  auctionEndPrice: BN;
  maxTs: BN;
  bitFlags: number;                  // bitmask, see OrderBitFlag
  postedSlotTail: number;
}

PDAs (Program Derived Addresses)

Velocity extensively uses PDAs for deterministic address generation, derived from the following seeds:

State:              ["velocity_state"]
User:               ["user", authority, subAccountId as u16 LE]
UserStats:          ["user_stats", authority]
PerpMarket:         ["perp_market", marketIndex as u16 LE]
SpotMarket:         ["spot_market", marketIndex as u16 LE]
SpotMarketVault:    ["spot_market_vault", marketIndex as u16 LE]
InsuranceFundVault: ["insurance_fund_vault", marketIndex as u16 LE]
InsuranceFundStake: ["insurance_fund_stake", authority, marketIndex as u16 LE]
ReferrerName:       ["referrer_name", name]

Derive these with the SDK rather than by hand: getUserAccountPublicKey(), getPerpMarketPublicKey(), and getSpotMarketPublicKey() from @velocity-exchange/sdk all run offchain and cost no RPC call. A derived address depends on the program ID as well as the seeds, so an address computed against a different deployment is a different account even where the seeds match exactly. See Program and vault addresses.

Account relationships

State (1)
  ├── PerpMarket[0..N]
  ├── SpotMarket[0..M]
  └── Insurance Fund (100% staker-owned)

Wallet
  ├── UserStats (1 per wallet)
  └── User[0..N] (subaccounts)
        ├── PerpPosition[0..8]
        ├── SpotPosition[0..8]
        └── Order[0..32]

How an instruction touches these accounts

Every instruction follows the same shape. Taking placePerpOrder as the example, the program loads the accounts the transaction passed, validates their ownership and PDA derivation, loads and validates the oracle price, applies the protocol rules from State, writes the change into UserAccount, updates market state where the change requires it (AMM, funding), and emits an event log for offchain indexers.

The account list itself is not fixed. Because a margin check has to price every market the account touches, most instructions take oracle, market, and user accounts through Solana's "remaining accounts" tail rather than through named slots, so one instruction handles an account with one position and an account with eight. Callers rarely build that list by hand: VelocityClient assembles it internally, and VelocityCore.remainingAccounts.getRemainingAccounts() does the same thing on the stateless path that has no subscription. See Reading Data.

Account sizes can grow

Every account above is a fixed-size, zero-copy struct, so new fields normally go into reserved padding: the size and every field offset stay put. When a struct genuinely runs out of padding, it grows, and existing accounts are physically resized onchain by the extend_account instruction.

extend_account reads the target account's discriminator, resolves 8 + size_of::<T>() for that type from the deployed program, transfers the rent shortfall from a payer, and grows the account data. The runtime zero-fills the new tail, so newly added fields read as zero until code writes them. It is:

• Grow-only. The target size is compiled in, so the instruction cannot shrink an account or inflate one to an arbitrary size.
• Idempotent. An account already at or beyond target size is a success no-op, so cranking twice is harmless.
• Permissioned. It requires the AccountExtension hot role (or the warm/cold admin). Extension never corrupts contents, but growing accounts costs every reader bandwidth, so the timing is the protocol's decision.
• Zero-copy only. Supported types include User, UserStats, ReferrerName, PerpMarket, SpotMarket, State, InsuranceFundStake, PrelaunchOracle, PythLazerOracle, RevenueShare, LPPool, and Constituent. Anything else fails with InvalidAccountExtension. Borsh accounts (SignedMsgUserOrders, RevenueShareEscrow, the LP-pool mapping accounts) version their layouts or ship dedicated resize instructions instead, and are deliberately rejected.

The sizes quoted on this page (PerpMarket 1560 bytes, SpotMarket 1064, User 4496) are the sizes the current program compiles in, not permanent constants. The TypeScript SDK is already length-tolerant: Anchor's borsh coder and the custom decodeUser fast path both read start-relative offsets, so an extended account decodes unchanged. See Reading Data for the decode paths.

MarketStatus discriminants

MarketStatus is stored directly in PerpMarket.status / SpotMarket.status. The discriminants are:

Always decode against the SDK's velocity.json IDL rather than a hardcoded enum. When porting a raw decoder from an earlier program version, see the migration guide for the discriminants it replaced.