@velocity-exchange/sdk 0.4.0 → 0.6.1

package/lib/browser/idl/velocity.json

@@ -2,7 +2,7 @@
     "address": "vELoC1audYbSYVRXn1vPaV8Axoa9oU6BYmNGZZBDZ1P",
     "metadata": {
         "name": "velocity",
-        "version": "2.162.0",
+        "version": "2.163.0",
         "spec": "0.1.0",
         "description": "Created with Anchor"
     },
@@ -6376,6 +6376,33 @@
                 }
             ]
         },
+        {
+            "name": "reset_equity_floor_breaker",
+            "discriminator": [
+                230,
+                181,
+                202,
+                36,
+                127,
+                56,
+                56,
+                27
+            ],
+            "accounts": [
+                {
+                    "name": "admin",
+                    "signer": true
+                },
+                {
+                    "name": "state"
+                },
+                {
+                    "name": "user_stats",
+                    "writable": true
+                }
+            ],
+            "args": []
+        },
         {
             "name": "reset_perp_market_amm_oracle_twap",
             "discriminator": [
@@ -7734,6 +7761,10 @@
                 {
                     "name": "amount",
                     "type": "u64"
+                },
+                {
+                    "name": "equity_floor_delta",
+                    "type": "u64"
                 }
             ]
         },
@@ -8216,6 +8247,39 @@
                 }
             ]
         },
+        {
+            "name": "trip_equity_floor_breaker",
+            "discriminator": [
+                133,
+                184,
+                25,
+                80,
+                193,
+                52,
+                162,
+                249
+            ],
+            "accounts": [
+                {
+                    "name": "state"
+                },
+                {
+                    "name": "keeper",
+                    "docs": [
+                        "Any signer may trip the breaker; the proof is the margin calculation."
+                    ],
+                    "signer": true
+                },
+                {
+                    "name": "user"
+                },
+                {
+                    "name": "user_stats",
+                    "writable": true
+                }
+            ],
+            "args": []
+        },
         {
             "name": "update_admin",
             "discriminator": [
@@ -9431,7 +9495,10 @@
                 },
                 {
                     "name": "authority",
-                    "signer": true
+                    "signer": true,
+                    "relations": [
+                        "keeper_stats"
+                    ]
                 }
             ],
             "args": []
@@ -9605,6 +9672,38 @@
                 }
             ]
         },
+        {
+            "name": "update_perp_market_bankruptcy_if_floor_pct",
+            "discriminator": [
+                192,
+                2,
+                229,
+                220,
+                243,
+                115,
+                121,
+                84
+            ],
+            "accounts": [
+                {
+                    "name": "admin",
+                    "signer": true
+                },
+                {
+                    "name": "state"
+                },
+                {
+                    "name": "perp_market",
+                    "writable": true
+                }
+            ],
+            "args": [
+                {
+                    "name": "bankruptcy_if_floor_pct",
+                    "type": "u32"
+                }
+            ]
+        },
         {
             "name": "update_perp_market_base_spread",
             "discriminator": [
@@ -12221,6 +12320,38 @@
                 }
             ]
         },
+        {
+            "name": "update_user_equity_floor",
+            "discriminator": [
+                49,
+                87,
+                139,
+                119,
+                136,
+                239,
+                186,
+                104
+            ],
+            "accounts": [
+                {
+                    "name": "admin",
+                    "signer": true
+                },
+                {
+                    "name": "state"
+                },
+                {
+                    "name": "user",
+                    "writable": true
+                }
+            ],
+            "args": [
+                {
+                    "name": "equity_floor",
+                    "type": "u64"
+                }
+            ]
+        },
         {
             "name": "update_user_idle",
             "discriminator": [
@@ -16011,6 +16142,21 @@
             "code": 6356,
             "name": "InvalidNativePerpMarketAccount",
             "msg": "Native dispatch: supplied market account is not a Velocity perp market"
+        },
+        {
+            "code": 6357,
+            "name": "IsolatedPositionDisabled",
+            "msg": "Isolated positions are not enabled in this build"
+        },
+        {
+            "code": 6358,
+            "name": "EquityBelowFloor",
+            "msg": "Account equity is below the user-set equity floor"
+        },
+        {
+            "code": 6359,
+            "name": "InvalidEquityFloorTransfer",
+            "msg": "Invalid equity floor transfer between subaccounts"
         }
     ],
     "types": [
@@ -21026,20 +21172,21 @@
                         "type": "i8"
                     },
                     {
-                        "name": "padding",
+                        "name": "bankruptcy_if_floor_pct",
                         "docs": [
-                            "Trailing padding so `market_stats` lands at the offset Rust naturally",
-                            "computes via `repr(C)` alignment and the `(SIZE - 8) % 16 == 0`",
-                            "invariant holds. (32 bytes moved into `fee_ledger` as",
-                            "`amm_protocol_fees_received` and then `pending_amm_provision` joined",
-                            "it, keeping `market_stats` fixed.)"
+                            "Floor on the unswept IF-fee carveout, as a percentage of open-interest",
+                            "notional (PERCENTAGE_PRECISION; 0 disables). The fee sweep's IF drain",
+                            "leaves `pending_if_fee` at (at least) this floor, so a standing",
+                            "first-loss tranche is always available to `resolve_perp_bankruptcy` —",
+                            "a permissionless sweep (or the inline sweep on any pnl settle) cannot",
+                            "drain the tranche below it ahead of a bankruptcy resolution. Notional",
+                            "is valued at the market's own oracle TWAP so a manipulated spot print",
+                            "can't crush the floor. Occupies the former 4-byte trailing padding",
+                            "before `market_stats` (same offset/alignment on all targets), so",
+                            "existing accounts read 0 = disabled until the admin sets it;",
+                            "new markets initialize to `DEFAULT_BANKRUPTCY_IF_FLOOR_PCT`."
                         ],
-                        "type": {
-                            "array": [
-                                "u8",
-                                4
-                            ]
-                        }
+                        "type": "u32"
                     },
                     {
                         "name": "market_stats",
@@ -23715,7 +23862,26 @@
                         "type": {
                             "array": [
                                 "u8",
-                                14
+                                3
+                            ]
+                        }
+                    },
+                    {
+                        "name": "equity_floor",
+                        "docs": [
+                            "Minimum account equity (cross-margin total collateral) required for",
+                            "risk-increasing orders, fills, withdrawals and deposit transfers.",
+                            "Settable only by the warm/cold admin; 0 disables the check.",
+                            "precision: QUOTE_PRECISION"
+                        ],
+                        "type": "u64"
+                    },
+                    {
+                        "name": "padding2",
+                        "type": {
+                            "array": [
+                                "u8",
+                                8
                             ]
                         }
                     }
@@ -23904,12 +24070,22 @@
                         ],
                         "type": "u8"
                     },
+                    {
+                        "name": "equity_breaker_tripped",
+                        "docs": [
+                            "Set by the permissionless `trip_equity_floor_breaker` instruction when",
+                            "any of the authority's subaccounts falls below its equity floor.",
+                            "While set, every subaccount of the authority rejects risk-increasing",
+                            "fills, withdrawals and transfers out. Cleared only by the warm admin."
+                        ],
+                        "type": "u8"
+                    },
                     {
                         "name": "padding",
                         "type": {
                             "array": [
                                 "u8",
-                                63
+                                62
                             ]
                         }
                     }

package/lib/browser/orderSubscriber/OrderSubscriber.d.ts

@@ -12,6 +12,7 @@ import { WebsocketSubscription } from './WebsocketSubscription';
 import StrictEventEmitter from 'strict-event-emitter-types';
 import { EventEmitter } from 'events';
 import { grpcSubscription } from './grpcSubscription';
+export declare const USER_LAST_ACTIVE_SLOT_OFFSET = 4448;
 /**
  * OrderSubscriber — maintains a live, in-memory map of every `User` account
  * (and therefore every open order) on the program, refreshed via polling,

package/lib/browser/orderSubscriber/OrderSubscriber.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.OrderSubscriber = void 0;
+exports.OrderSubscriber = exports.USER_LAST_ACTIVE_SLOT_OFFSET = void 0;
 const memcmp_1 = require("../memcmp");
 const web3_js_1 = require("@solana/web3.js");
 const buffer_1 = require("buffer");
@@ -20,8 +20,11 @@ const numericConstants_1 = require("../constants/numericConstants");
  * was for the older 4376-byte layout; the current Velocity layout is 4496
  * bytes, shifting this field +120 bytes. With the wrong offset this read 8
  * zero-padding bytes, so the staleness guard rejected every post-load update.
+ * Exported so downstream `tryUpdateUserAccount` overrides (e.g. the keeper
+ * bots' filtered order subscriber) share the same offset instead of
+ * re-hardcoding it.
  */
-const USER_LAST_ACTIVE_SLOT_OFFSET = 4448;
+exports.USER_LAST_ACTIVE_SLOT_OFFSET = 4448;
 /**
  * OrderSubscriber — maintains a live, in-memory map of every `User` account
  * (and therefore every open order) on the program, refreshed via polling,
@@ -124,6 +127,9 @@ class OrderSubscriber {
             await this.velocityClient.connection._rpcRequest('getProgramAccounts', rpcRequestArgs);
             const rpcResponseAndContext = rpcJSONResponse.result;
             const slot = rpcResponseAndContext.context.slot;
+            if (!this.mostRecentSlot || slot > this.mostRecentSlot) {
+                this.mostRecentSlot = slot;
+            }
             for (const programAccount of rpcResponseAndContext.value) {
                 const key = programAccount.pubkey.toString();
                 this.tryUpdateUserAccount(key, 'raw', programAccount.account.data, slot);
@@ -168,7 +174,7 @@ class OrderSubscriber {
             if (dataType === 'raw') {
                 // @ts-ignore
                 const buffer = buffer_1.Buffer.from(data[0], data[1]);
-                const newLastActiveSlot = new anchor_1.BN(buffer.subarray(USER_LAST_ACTIVE_SLOT_OFFSET, USER_LAST_ACTIVE_SLOT_OFFSET + 8), undefined, 'le');
+                const newLastActiveSlot = new anchor_1.BN(buffer.subarray(exports.USER_LAST_ACTIVE_SLOT_OFFSET, exports.USER_LAST_ACTIVE_SLOT_OFFSET + 8), undefined, 'le');
                 if (slotAndUserAccount &&
                     slotAndUserAccount.userAccount.lastActiveSlot.gt(newLastActiveSlot)) {
                     return;
@@ -177,7 +183,7 @@ class OrderSubscriber {
             }
             else if (dataType === 'buffer') {
                 const buffer = data;
-                const newLastActiveSlot = new anchor_1.BN(buffer.subarray(USER_LAST_ACTIVE_SLOT_OFFSET, USER_LAST_ACTIVE_SLOT_OFFSET + 8), undefined, 'le');
+                const newLastActiveSlot = new anchor_1.BN(buffer.subarray(exports.USER_LAST_ACTIVE_SLOT_OFFSET, exports.USER_LAST_ACTIVE_SLOT_OFFSET + 8), undefined, 'le');
                 if (slotAndUserAccount &&
                     slotAndUserAccount.userAccount.lastActiveSlot.gt(newLastActiveSlot)) {
                     return;

package/lib/browser/pyth/pythLazerSubscriber.js

@@ -127,6 +127,36 @@ class PythLazerSubscriber {
         });
         // Reset allSubscribedIds to rebuild with only stable feeds
         this.allSubscribedIds = [];
+        // addMessageListener is global to the client (fires for every message,
+        // not scoped to a subscription), and each message carries its own
+        // subscriptionId — so one listener serves all subscriptions. Registering
+        // it per chunk would run every message once per chunk.
+        this.pythLazerClient.addMessageListener((message) => {
+            var _a, _b;
+            this.receivingData = true;
+            clearTimeout(this.timeoutId);
+            switch (message.type) {
+                case 'json': {
+                    if (message.value.type == 'streamUpdated') {
+                        if ((_a = message.value.solana) === null || _a === void 0 ? void 0 : _a.data) {
+                            this.feedIdChunkToPriceMessage.set(this.subscriptionIdsToFeedIdsHash.get(message.value.subscriptionId), message.value.solana.data);
+                        }
+                        if ((_b = message.value.parsed) === null || _b === void 0 ? void 0 : _b.priceFeeds) {
+                            for (const priceFeed of message.value.parsed.priceFeeds) {
+                                const price = Number(priceFeed.price) *
+                                    Math.pow(10, Number(priceFeed.exponent));
+                                this.feedIdToPrice.set(priceFeed.priceFeedId, price);
+                            }
+                        }
+                    }
+                    break;
+                }
+                default: {
+                    break;
+                }
+            }
+            this.setTimeout();
+        });
         let subscriptionId = 1;
         for (const priceFeedArray of this.priceFeedArrays) {
             const filteredFeedIds = this.filterStableFeeds(priceFeedArray.priceFeedIds);
@@ -153,33 +183,13 @@ class PythLazerSubscriber {
                     this.marketIndextoPriceFeedIdChunk.delete(marketIndex);
                 }
             }
-            this.pythLazerClient.addMessageListener((message) => {
-                var _a, _b;
-                this.receivingData = true;
-                clearTimeout(this.timeoutId);
-                switch (message.type) {
-                    case 'json': {
-                        if (message.value.type == 'streamUpdated') {
-                            if ((_a = message.value.solana) === null || _a === void 0 ? void 0 : _a.data) {
-                                this.feedIdChunkToPriceMessage.set(this.subscriptionIdsToFeedIdsHash.get(message.value.subscriptionId), message.value.solana.data);
-                            }
-                            if ((_b = message.value.parsed) === null || _b === void 0 ? void 0 : _b.priceFeeds) {
-                                for (const priceFeed of message.value.parsed.priceFeeds) {
-                                    const price = Number(priceFeed.price) *
-                                        Math.pow(10, Number(priceFeed.exponent));
-                                    this.feedIdToPrice.set(priceFeed.priceFeedId, price);
-                                }
-                            }
-                        }
-                        break;
-                    }
-                    default: {
-                        break;
-                    }
-                }
-                this.setTimeout();
-            });
-            this.pythLazerClient.send({
+            // Use subscribe() (not send()): subscribe() registers the request in
+            // the pool's subscriptions map so ResilientWebSocket replays it on
+            // every socket reconnect. send() fires once and is never replayed, so
+            // after the first heartbeat-timeout reconnect the socket streams
+            // nothing — forcing the watchdog to tear down the whole client and
+            // reopen numConnections fresh sockets. subscribe() recovers in place.
+            this.pythLazerClient.subscribe({
                 type: 'subscribe',
                 subscriptionId,
                 priceFeedIds: filteredFeedIds,

package/lib/browser/types.d.ts

@@ -1205,6 +1205,8 @@ export type PerpMarketAccount = {
     protocolLiquidationFee: number;
     /** QUOTE_PRECISION (1e6); pnl-pool retention buffer the fee-sweep leaves untouched above `max(net_user_pnl, 0)` */
     feePoolBufferTarget: BN;
+    /** PERCENTAGE_PRECISION (1e6 = 100%); fraction of OI notional (at the oracle TWAP) the sweep leaves behind in `feeLedger.pendingIfFee` as a standing bankruptcy first-loss tranche; 0 disables */
+    bankruptcyIfFloorPct: number;
     /** MARGIN_PRECISION (1e4); scales margin ratio up for large positions */
     imfFactor: number;
     /** MARGIN_PRECISION (1e4); discounts positive-unrealized-pnl asset weight for large positions */
@@ -1642,6 +1644,8 @@ export type UserStatsAccount = {
     authority: PublicKey;
     ifStakedQuoteAssetAmount: BN;
     delegatePermissions: number;
+    /** non-zero when the permissionless `tripEquityFloorBreaker` fired: every subaccount of the authority rejects risk-increasing fills, withdrawals and transfers out until the warm admin resets */
+    equityBreakerTripped: number;
 };
 /** Decoded mirror of the on-chain `User` (sub-account) zero-copy account. */
 export type UserAccount = {
@@ -1684,6 +1688,8 @@ export type UserAccount = {
     poolId: number;
     /** bitmask, see `SpecialUserStatus` */
     specialUserStatus: number;
+    /** QUOTE_PRECISION (1e6); admin-set minimum cross-margin total collateral for risk-increasing orders, fills, withdrawals and transfers; 0 = disabled */
+    equityFloor: BN;
 };
 /** A user's balance in one spot market. Decoded mirror of the on-chain `SpotPosition`. */
 export type SpotPosition = {

package/lib/browser/user.d.ts

@@ -410,6 +410,21 @@ export declare class User {
      * @returns Precision QUOTE_PRECISION (1e6).
      */
     getTotalCollateral(marginCategory?: MarginCategory, strict?: boolean, includeOpenOrders?: boolean, liquidationBuffer?: BN, perpMarketIndex?: number): BN;
+    /**
+     * True when the account has an admin-set `equityFloor` and its cross-margin
+     * total collateral is below it. While below the floor, the program rejects
+     * risk-increasing order placement and fills, withdrawals, and transfers out
+     * of the account (`EquityBelowFloor`); reduce-only activity stays allowed.
+     * Mirrors `User::is_below_equity_floor` on-chain.
+     * @param strict Use TWAP-bounded oracle pricing, matching the withdraw path. Defaults to false.
+     */
+    isBelowEquityFloor(strict?: boolean): boolean;
+    /**
+     * Cross-margin total collateral in excess of the admin-set `equityFloor`,
+     * floored at zero (QUOTE_PRECISION). Unbounded (`null`) when no floor is set.
+     * @param strict Use TWAP-bounded oracle pricing. Defaults to false.
+     */
+    getEquityAboveFloor(strict?: boolean): BN | null;
     /**
      * Builds the liquidation-buffer map to pass into margin calculations while
      * a liquidation is in progress: `'cross'` is set to the state account's
@@ -909,9 +924,11 @@ export declare class User {
     };
     /**
      * Returns the numerically-lowest (i.e. safest) contract/asset tier across
-     * the user's active positions — perp tiers from active perp positions,
-     * spot tiers only from spot **borrows** (deposits are skipped, since asset
-     * tier only restricts borrowing exposure). Defaults to `4` (the
+     * the user's active positions — perp tiers from active perp positions
+     * (skipping zero-base positions whose only exposure is positive unsettled
+     * pnl: those are claims on the pnl pool, not liabilities), spot tiers only
+     * from spot **borrows** (deposits are skipped, since asset tier only
+     * restricts borrowing exposure). Defaults to `4` (the
      * second-riskiest tier index) when the user has no positions of that kind —
      * this is a permissive default intended for callers doing tier-safety
      * comparisons (see `perpTierIsAsSafeAs` in `math/tiers`), not a claim that

package/lib/browser/user.js

@@ -898,6 +898,33 @@ class User {
         }
         return marginCalc.totalCollateral;
     }
+    /**
+     * True when the account has an admin-set `equityFloor` and its cross-margin
+     * total collateral is below it. While below the floor, the program rejects
+     * risk-increasing order placement and fills, withdrawals, and transfers out
+     * of the account (`EquityBelowFloor`); reduce-only activity stays allowed.
+     * Mirrors `User::is_below_equity_floor` on-chain.
+     * @param strict Use TWAP-bounded oracle pricing, matching the withdraw path. Defaults to false.
+     */
+    isBelowEquityFloor(strict = false) {
+        const equityFloor = this.getUserAccountOrThrow().equityFloor;
+        if (equityFloor.lte(numericConstants_1.ZERO)) {
+            return false;
+        }
+        return this.getTotalCollateral('Initial', strict).lt(equityFloor);
+    }
+    /**
+     * Cross-margin total collateral in excess of the admin-set `equityFloor`,
+     * floored at zero (QUOTE_PRECISION). Unbounded (`null`) when no floor is set.
+     * @param strict Use TWAP-bounded oracle pricing. Defaults to false.
+     */
+    getEquityAboveFloor(strict = false) {
+        const equityFloor = this.getUserAccountOrThrow().equityFloor;
+        if (equityFloor.lte(numericConstants_1.ZERO)) {
+            return null;
+        }
+        return anchor_1.BN.max(this.getTotalCollateral('Initial', strict).sub(equityFloor), numericConstants_1.ZERO);
+    }
     /**
      * Builds the liquidation-buffer map to pass into margin calculations while
      * a liquidation is in progress: `'cross'` is set to the state account's
@@ -2353,7 +2380,16 @@ class User {
         const spotMarket = this.velocityClient.getSpotMarketAccountOrThrow(marketIndex);
         // eslint-disable-next-line prefer-const
         let { borrowLimit, withdrawLimit } = (0, spotBalance_2.calculateWithdrawLimit)(spotMarket, nowTs);
-        const freeCollateral = this.getFreeCollateral();
+        // the withdraw path enforces the equity floor on post-withdraw total
+        // collateral, so equity above the floor caps free collateral here
+        const equityAboveFloor = this.getEquityAboveFloor(true);
+        if (equityAboveFloor !== null && equityAboveFloor.eq(numericConstants_1.ZERO)) {
+            return numericConstants_1.ZERO;
+        }
+        let freeCollateral = this.getFreeCollateral();
+        if (equityAboveFloor !== null) {
+            freeCollateral = anchor_1.BN.min(freeCollateral, equityAboveFloor);
+        }
         const initialMarginRequirement = this.getInitialMarginRequirement();
         const oracleData = this.getOracleDataForSpotMarket(marketIndex);
         const { numeratorScale, denominatorScale } = spotMarket.decimals > 6
@@ -2583,9 +2619,11 @@ class User {
     }
     /**
      * Returns the numerically-lowest (i.e. safest) contract/asset tier across
-     * the user's active positions — perp tiers from active perp positions,
-     * spot tiers only from spot **borrows** (deposits are skipped, since asset
-     * tier only restricts borrowing exposure). Defaults to `4` (the
+     * the user's active positions — perp tiers from active perp positions
+     * (skipping zero-base positions whose only exposure is positive unsettled
+     * pnl: those are claims on the pnl pool, not liabilities), spot tiers only
+     * from spot **borrows** (deposits are skipped, since asset tier only
+     * restricts borrowing exposure). Defaults to `4` (the
      * second-riskiest tier index) when the user has no positions of that kind —
      * this is a permissive default intended for callers doing tier-safety
      * comparisons (see `perpTierIsAsSafeAs` in `math/tiers`), not a claim that
@@ -2593,9 +2631,19 @@ class User {
      * @returns Lower `perpTier`/`spotTier` numbers indicate a safer tier; see `math/tiers` (`getPerpMarketTierNumber`/`getSpotMarketTierNumber`) for the numbering.
      */
     getSafestTiers() {
+        var _a;
         let safestPerpTier = 4;
         let safestSpotTier = 4;
         for (const perpPosition of this.getActivePerpPositions()) {
+            // a zero-base position with positive unsettled pnl is a claim on the
+            // market's pnl pool, not a liability (mirrors
+            // calculate_user_safest_position_tiers in math/margin.rs)
+            if (perpPosition.baseAssetAmount.eq(numericConstants_1.ZERO) &&
+                !(0, position_1.hasOpenOrders)(perpPosition) &&
+                !((_a = perpPosition.isolatedPositionScaledBalance) !== null && _a !== void 0 ? _a : numericConstants_1.ZERO).gt(numericConstants_1.ZERO) &&
+                perpPosition.quoteAssetAmount.gt(numericConstants_1.ZERO)) {
+                continue;
+            }
             safestPerpTier = Math.min(safestPerpTier, (0, tiers_1.getPerpMarketTierNumber)(this.velocityClient.getPerpMarketAccountOrThrow(perpPosition.marketIndex)));
         }
         for (const spotPosition of this.getActiveSpotPositions()) {