@velocity-exchange/sdk 0.4.0 → 0.6.1

package/README.md

@@ -40,7 +40,7 @@ The below is a light overview of using Solana and Velocity's typescript sdk. If
 # Generate a keypair
 solana-keygen new
 
-# Get the pubkey for the new wallet (You will need to send USDC to this address to Deposit into Velocity (only on mainnet - devnet has a faucet for USDC))
+# Get the pubkey for the new wallet (You will need to send the quote asset to this address to Deposit into Velocity (only on mainnet - devnet has a faucet for the quote asset))
 solana address
 
 # Put the private key into your .env to be used by your bot
@@ -210,12 +210,12 @@ const main = async () => {
 			provider.wallet.publicKey.toString()
 		);
 
-		//// Create a Velocity V1 account by Depositing some USDC ($10,000 in this case)
+		//// Create a Velocity V1 account by Depositing some quote asset ($10,000 in this case)
 		const depositAmount = new BN(10000).mul(QUOTE_PRECISION);
 		await velocityClient.initializeUserAccountAndDepositCollateral(
 			depositAmount,
 			await getTokenAddress(
-				usdcTokenAddress.toString(),
+				quoteTokenAddress.toString(),
 				provider.wallet.publicKey.toString()
 			)
 		);

package/lib/browser/adminClient.d.ts

@@ -1533,6 +1533,23 @@ export declare class AdminClient extends VelocityClient {
      * @returns The unsigned `updatePerpMarketFeePoolBufferTarget` instruction.
      */
     getUpdatePerpMarketFeePoolBufferTargetIx(perpMarketIndex: number, feePoolBufferTarget: BN): Promise<TransactionInstruction>;
+    /**
+     * Sets the fraction of open-interest notional the streaming fee sweep must leave behind in
+     * `feeLedger.pendingIfFee` as a standing bankruptcy tranche (notional valued at the market's
+     * oracle TWAP). The permissionless sweep cannot drain the tranche below this floor, so a
+     * sweep front-running a `resolvePerpBankruptcy` cannot strip the first-loss coverage up to
+     * the floor. New markets initialize to 10 bps; 0 disables. Requires warm admin (`check_warm`).
+     * @param perpMarketIndex - Perp market to update.
+     * @param bankruptcyIfFloorPct - Floor as PERCENTAGE_PRECISION (1e6 = 100%; 1000 = 10 bps); max 1e6.
+     * @returns Transaction signature.
+     */
+    updatePerpMarketBankruptcyIfFloorPct(perpMarketIndex: number, bankruptcyIfFloorPct: number): Promise<TransactionSignature>;
+    /**
+     * Builds the `updatePerpMarketBankruptcyIfFloorPct` instruction without sending it. See
+     * `updatePerpMarketBankruptcyIfFloorPct`.
+     * @returns The unsigned `updatePerpMarketBankruptcyIfFloorPct` instruction.
+     */
+    getUpdatePerpMarketBankruptcyIfFloorPctIx(perpMarketIndex: number, bankruptcyIfFloorPct: number): Promise<TransactionInstruction>;
     /**
      * Scales a spot market's taker fee and maker rebate up or down by a percentage of the base
      * fee tier. Requires warm admin (`check_warm`). Throws `DefaultError` on-chain if
@@ -2462,6 +2479,41 @@ export declare class AdminClient extends VelocityClient {
      * @returns The unsigned `updateSpecialUserStatus` instruction.
      */
     getUpdateSpecialUserStatusIx(userAccountPublicKey: PublicKey, status: number): Promise<TransactionInstruction>;
+    /**
+     * Sets a `User` account's `equityFloor`: the minimum cross-margin total
+     * collateral (QUOTE_PRECISION) the account must keep. Below the floor the
+     * program rejects risk-increasing order placement and fills, withdrawals,
+     * and deposit/position transfers out of the account; reduce-only activity
+     * stays allowed. Requires warm admin (`check_warm`); the account's
+     * authority and delegate cannot change it. Pass `0` to disable.
+     * @param userAccountPublicKey - `User` PDA to update.
+     * @param equityFloor - New floor, QUOTE_PRECISION; `0` disables.
+     * @param txParams - Optional transaction-building overrides.
+     * @returns Transaction signature.
+     */
+    updateUserEquityFloor(userAccountPublicKey: PublicKey, equityFloor: BN, txParams?: TxParams): Promise<TransactionSignature>;
+    /**
+     * Builds the `updateUserEquityFloor` instruction without sending it. See
+     * `updateUserEquityFloor`.
+     * @returns The unsigned `updateUserEquityFloor` instruction.
+     */
+    getUpdateUserEquityFloorIx(userAccountPublicKey: PublicKey, equityFloor: BN): Promise<TransactionInstruction>;
+    /**
+     * Clears the authority-wide equity floor breaker set by the permissionless
+     * `tripEquityFloorBreaker` keeper instruction, unfreezing all of the
+     * authority's subaccounts. Requires warm admin (`check_warm`); intended to
+     * be called after a human has reviewed why the breaker fired.
+     * @param userStatsPublicKey - `UserStats` PDA of the authority to unfreeze.
+     * @param txParams - Optional transaction-building overrides.
+     * @returns Transaction signature.
+     */
+    resetEquityFloorBreaker(userStatsPublicKey: PublicKey, txParams?: TxParams): Promise<TransactionSignature>;
+    /**
+     * Builds the `resetEquityFloorBreaker` instruction without sending it. See
+     * `resetEquityFloorBreaker`.
+     * @returns The unsigned `resetEquityFloorBreaker` instruction.
+     */
+    getResetEquityFloorBreakerIx(userStatsPublicKey: PublicKey): Promise<TransactionInstruction>;
     /**
      * Rotates `state.warmAdmin`, the operational (multisig+timelock) tier that can
      * rotate every hot-role key (`updateHotAdmin`). Cold-only: the `UpdateWarmAdmin`

package/lib/browser/adminClient.js

@@ -3015,6 +3015,38 @@ class AdminClient extends velocityClient_1.VelocityClient {
             },
         });
     }
+    /**
+     * Sets the fraction of open-interest notional the streaming fee sweep must leave behind in
+     * `feeLedger.pendingIfFee` as a standing bankruptcy tranche (notional valued at the market's
+     * oracle TWAP). The permissionless sweep cannot drain the tranche below this floor, so a
+     * sweep front-running a `resolvePerpBankruptcy` cannot strip the first-loss coverage up to
+     * the floor. New markets initialize to 10 bps; 0 disables. Requires warm admin (`check_warm`).
+     * @param perpMarketIndex - Perp market to update.
+     * @param bankruptcyIfFloorPct - Floor as PERCENTAGE_PRECISION (1e6 = 100%; 1000 = 10 bps); max 1e6.
+     * @returns Transaction signature.
+     */
+    async updatePerpMarketBankruptcyIfFloorPct(perpMarketIndex, bankruptcyIfFloorPct) {
+        const updatePerpMarketBankruptcyIfFloorPctIx = await this.getUpdatePerpMarketBankruptcyIfFloorPctIx(perpMarketIndex, bankruptcyIfFloorPct);
+        const tx = await this.buildTransaction(updatePerpMarketBankruptcyIfFloorPctIx);
+        const { txSig } = await this.sendTransaction(tx, [], this.opts);
+        return txSig;
+    }
+    /**
+     * Builds the `updatePerpMarketBankruptcyIfFloorPct` instruction without sending it. See
+     * `updatePerpMarketBankruptcyIfFloorPct`.
+     * @returns The unsigned `updatePerpMarketBankruptcyIfFloorPct` instruction.
+     */
+    async getUpdatePerpMarketBankruptcyIfFloorPctIx(perpMarketIndex, bankruptcyIfFloorPct) {
+        return await this.program.instruction.updatePerpMarketBankruptcyIfFloorPct(bankruptcyIfFloorPct, {
+            accounts: {
+                admin: this.isSubscribed
+                    ? this.getStateAccount().coldAdmin
+                    : this.wallet.publicKey,
+                state: await this.getStatePublicKey(),
+                perpMarket: await (0, pda_1.getPerpMarketPublicKey)(this.program.programId, perpMarketIndex),
+            },
+        });
+    }
     /**
      * Scales a spot market's taker fee and maker rebate up or down by a percentage of the base
      * fee tier. Requires warm admin (`check_warm`). Throws `DefaultError` on-chain if
@@ -4853,6 +4885,71 @@ class AdminClient extends velocityClient_1.VelocityClient {
             },
         });
     }
+    /**
+     * Sets a `User` account's `equityFloor`: the minimum cross-margin total
+     * collateral (QUOTE_PRECISION) the account must keep. Below the floor the
+     * program rejects risk-increasing order placement and fills, withdrawals,
+     * and deposit/position transfers out of the account; reduce-only activity
+     * stays allowed. Requires warm admin (`check_warm`); the account's
+     * authority and delegate cannot change it. Pass `0` to disable.
+     * @param userAccountPublicKey - `User` PDA to update.
+     * @param equityFloor - New floor, QUOTE_PRECISION; `0` disables.
+     * @param txParams - Optional transaction-building overrides.
+     * @returns Transaction signature.
+     */
+    async updateUserEquityFloor(userAccountPublicKey, equityFloor, txParams) {
+        const ix = await this.getUpdateUserEquityFloorIx(userAccountPublicKey, equityFloor);
+        const tx = await this.buildTransaction(ix, txParams);
+        const { txSig } = await this.sendTransaction(tx, [], this.opts);
+        return txSig;
+    }
+    /**
+     * Builds the `updateUserEquityFloor` instruction without sending it. See
+     * `updateUserEquityFloor`.
+     * @returns The unsigned `updateUserEquityFloor` instruction.
+     */
+    async getUpdateUserEquityFloorIx(userAccountPublicKey, equityFloor) {
+        return this.program.instruction.updateUserEquityFloor(equityFloor, {
+            accounts: {
+                admin: this.useHotWalletAdmin
+                    ? this.wallet.publicKey
+                    : this.getStateAccount().coldAdmin,
+                state: await this.getStatePublicKey(),
+                user: userAccountPublicKey,
+            },
+        });
+    }
+    /**
+     * Clears the authority-wide equity floor breaker set by the permissionless
+     * `tripEquityFloorBreaker` keeper instruction, unfreezing all of the
+     * authority's subaccounts. Requires warm admin (`check_warm`); intended to
+     * be called after a human has reviewed why the breaker fired.
+     * @param userStatsPublicKey - `UserStats` PDA of the authority to unfreeze.
+     * @param txParams - Optional transaction-building overrides.
+     * @returns Transaction signature.
+     */
+    async resetEquityFloorBreaker(userStatsPublicKey, txParams) {
+        const ix = await this.getResetEquityFloorBreakerIx(userStatsPublicKey);
+        const tx = await this.buildTransaction(ix, txParams);
+        const { txSig } = await this.sendTransaction(tx, [], this.opts);
+        return txSig;
+    }
+    /**
+     * Builds the `resetEquityFloorBreaker` instruction without sending it. See
+     * `resetEquityFloorBreaker`.
+     * @returns The unsigned `resetEquityFloorBreaker` instruction.
+     */
+    async getResetEquityFloorBreakerIx(userStatsPublicKey) {
+        return this.program.instruction.resetEquityFloorBreaker({
+            accounts: {
+                admin: this.useHotWalletAdmin
+                    ? this.wallet.publicKey
+                    : this.getStateAccount().coldAdmin,
+                state: await this.getStatePublicKey(),
+                userStats: userStatsPublicKey,
+            },
+        });
+    }
     // ----- Tiered admin authority -----
     //
     // `state.coldAdmin` is the root. `state.warmAdmin` is rotated by cold; each

package/lib/browser/config.js

@@ -31,7 +31,7 @@ exports.configs = {
         ENV: 'devnet',
         PYTH_ORACLE_MAPPING_ADDRESS: 'BmA9Z6FjioHJPpjT39QazZyhDRUdZy2ezwx4GiDdE2u2',
         VELOCITY_PROGRAM_ID: exports.VELOCITY_DEVNET_PROGRAM_ID,
-        JIT_PROXY_PROGRAM_ID: 'J1TnP8zvVxbtF5KFp5xRmWuvG9McnhzmBd9XGfCyuxFP',
+        JIT_PROXY_PROGRAM_ID: 'J1TPRoXCtGuMcWiWFE6RB9eZU8U35PBMETCwNQLCNPhQ',
         QUOTE_MINT_ADDRESS: 'GqmEqYsy8EyvofDpmtFxK8zhYrgWgNokAtYoduQdL7v6',
         V2_ALPHA_TICKET_MINT_ADDRESS: 'DeEiGWfCMP9psnLGkxGrBBMEAW5Jv8bBGMN8DCtFRCyB',
         PERP_MARKETS: perpMarkets_1.DevnetPerpMarkets,
@@ -46,7 +46,7 @@ exports.configs = {
         ENV: 'mainnet-beta',
         PYTH_ORACLE_MAPPING_ADDRESS: 'AHtgzX45WTKfkPG53L6WYhGEXwQkN1BVknET3sVsLL8J',
         VELOCITY_PROGRAM_ID: exports.VELOCITY_PROGRAM_ID,
-        JIT_PROXY_PROGRAM_ID: 'J1TnP8zvVxbtF5KFp5xRmWuvG9McnhzmBd9XGfCyuxFP',
+        JIT_PROXY_PROGRAM_ID: 'J1TPRoXCtGuMcWiWFE6RB9eZU8U35PBMETCwNQLCNPhQ',
         // Relaunch quote market (spot 0) is USDT — see
         // deploy-scripts/params/relaunch-spot-markets.json.
         QUOTE_MINT_ADDRESS: 'Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB',
@@ -54,11 +54,10 @@ exports.configs = {
         PERP_MARKETS: perpMarkets_1.MainnetPerpMarkets,
         SPOT_MARKETS: spotMarkets_1.MainnetSpotMarkets,
         /** @deprecated use MARKET_LOOKUP_TABLES */
-        MARKET_LOOKUP_TABLE: 'Fpys8GRa5RBWfyeN7AaDUwFGD1zkDCA4z3t4CJLV8dfL',
-        MARKET_LOOKUP_TABLES: [
-            'Fpys8GRa5RBWfyeN7AaDUwFGD1zkDCA4z3t4CJLV8dfL',
-            'EiWSskK5HXnBTptiS5DH6gpAJRVNQ3cAhTKBGaiaysAb',
-        ],
+        MARKET_LOOKUP_TABLE: '4E971nER9Jn4JjT8mKEX1nvkfg8Qycp7zNEcCq2nT8ZY',
+        // Relaunch LUT: state, signer, spot markets 0-1 (oracle/mint/vault/IF
+        // vault), perp markets 0-3 with oracles, token/ATA/system programs.
+        MARKET_LOOKUP_TABLES: ['4E971nER9Jn4JjT8mKEX1nvkfg8Qycp7zNEcCq2nT8ZY'],
         VELOCITY_ORACLE_RECEIVER_ID: exports.VELOCITY_ORACLE_RECEIVER_ID,
         SB_ON_DEMAND_PID: exports.SB_ON_DEMAND_MAINNET_PID,
     },

package/lib/browser/constants/numericConstants.d.ts

@@ -106,7 +106,7 @@ export declare const FIVE_MINUTE: BN;
 export declare const ONE_HOUR: BN;
 /** 31,536,000 seconds (365 days). */
 export declare const ONE_YEAR: BN;
-/** Market index of the protocol's quote spot market (USDC on mainnet). */
+/** Market index of the protocol's quote spot market (the protocol's quote asset on mainnet). */
 export declare const QUOTE_SPOT_MARKET_INDEX = 0;
 /** 1e9 (`LAMPORTS_PER_SOL`); token-mint precision for wrapped SOL spot markets. */
 export declare const LAMPORTS_PRECISION: BN;

package/lib/browser/constants/numericConstants.js

@@ -111,7 +111,7 @@ exports.FIVE_MINUTE = new anchor_1.BN(60 * 5);
 exports.ONE_HOUR = new anchor_1.BN(60 * 60);
 /** 31,536,000 seconds (365 days). */
 exports.ONE_YEAR = new anchor_1.BN(31536000);
-/** Market index of the protocol's quote spot market (USDC on mainnet). */
+/** Market index of the protocol's quote spot market (the protocol's quote asset on mainnet). */
 exports.QUOTE_SPOT_MARKET_INDEX = 0;
 /** 1e9 (`LAMPORTS_PER_SOL`); token-mint precision for wrapped SOL spot markets. */
 exports.LAMPORTS_PRECISION = new anchor_1.BN(web3_js_1.LAMPORTS_PER_SOL);

package/lib/browser/decode/user.js

@@ -333,7 +333,10 @@ function decodeUser(buffer) {
     offset += 1;
     const specialUserStatus = buffer.readUInt8(offset);
     offset += 1;
-    offset += 14; // padding
+    offset += 3; // padding
+    const equityFloor = readUnsignedBigInt64LE(buffer, offset);
+    offset += 8;
+    offset += 8; // padding2
     return {
         authority,
         delegate,
@@ -362,6 +365,7 @@ function decodeUser(buffer) {
         hasOpenAuction,
         poolId,
         specialUserStatus,
+        equityFloor,
     };
 }
 exports.decodeUser = decodeUser;

package/lib/browser/idl/velocity.d.ts

@@ -8,7 +8,7 @@ export type Velocity = {
     "address": "vELoC1audYbSYVRXn1vPaV8Axoa9oU6BYmNGZZBDZ1P";
     "metadata": {
         "name": "velocity";
-        "version": "2.162.0";
+        "version": "2.163.0";
         "spec": "0.1.0";
         "description": "Created with Anchor";
     };
@@ -6382,6 +6382,33 @@ export type Velocity = {
                 }
             ];
         },
+        {
+            "name": "resetEquityFloorBreaker";
+            "discriminator": [
+                230,
+                181,
+                202,
+                36,
+                127,
+                56,
+                56,
+                27
+            ];
+            "accounts": [
+                {
+                    "name": "admin";
+                    "signer": true;
+                },
+                {
+                    "name": "state";
+                },
+                {
+                    "name": "userStats";
+                    "writable": true;
+                }
+            ];
+            "args": [];
+        },
         {
             "name": "resetPerpMarketAmmOracleTwap";
             "discriminator": [
@@ -7740,6 +7767,10 @@ export type Velocity = {
                 {
                     "name": "amount";
                     "type": "u64";
+                },
+                {
+                    "name": "equityFloorDelta";
+                    "type": "u64";
                 }
             ];
         },
@@ -8222,6 +8253,39 @@ export type Velocity = {
                 }
             ];
         },
+        {
+            "name": "tripEquityFloorBreaker";
+            "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": "userStats";
+                    "writable": true;
+                }
+            ];
+            "args": [];
+        },
         {
             "name": "updateAdmin";
             "discriminator": [
@@ -9438,6 +9502,9 @@ export type Velocity = {
                 {
                     "name": "authority";
                     "signer": true;
+                    "relations": [
+                        "keeperStats"
+                    ];
                 }
             ];
             "args": [];
@@ -9611,6 +9678,38 @@ export type Velocity = {
                 }
             ];
         },
+        {
+            "name": "updatePerpMarketBankruptcyIfFloorPct";
+            "discriminator": [
+                192,
+                2,
+                229,
+                220,
+                243,
+                115,
+                121,
+                84
+            ];
+            "accounts": [
+                {
+                    "name": "admin";
+                    "signer": true;
+                },
+                {
+                    "name": "state";
+                },
+                {
+                    "name": "perpMarket";
+                    "writable": true;
+                }
+            ];
+            "args": [
+                {
+                    "name": "bankruptcyIfFloorPct";
+                    "type": "u32";
+                }
+            ];
+        },
         {
             "name": "updatePerpMarketBaseSpread";
             "discriminator": [
@@ -12227,6 +12326,38 @@ export type Velocity = {
                 }
             ];
         },
+        {
+            "name": "updateUserEquityFloor";
+            "discriminator": [
+                49,
+                87,
+                139,
+                119,
+                136,
+                239,
+                186,
+                104
+            ];
+            "accounts": [
+                {
+                    "name": "admin";
+                    "signer": true;
+                },
+                {
+                    "name": "state";
+                },
+                {
+                    "name": "user";
+                    "writable": true;
+                }
+            ];
+            "args": [
+                {
+                    "name": "equityFloor";
+                    "type": "u64";
+                }
+            ];
+        },
         {
             "name": "updateUserIdle";
             "discriminator": [
@@ -16017,6 +16148,21 @@ export type Velocity = {
             "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": [
@@ -21032,20 +21178,21 @@ export type Velocity = {
                         "type": "i8";
                     },
                     {
-                        "name": "padding";
+                        "name": "bankruptcyIfFloorPct";
                         "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": "marketStats";
@@ -23721,7 +23868,26 @@ export type Velocity = {
                         "type": {
                             "array": [
                                 "u8",
-                                14
+                                3
+                            ];
+                        };
+                    },
+                    {
+                        "name": "equityFloor";
+                        "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
                             ];
                         };
                     }
@@ -23910,12 +24076,22 @@ export type Velocity = {
                         ];
                         "type": "u8";
                     },
+                    {
+                        "name": "equityBreakerTripped";
+                        "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
                             ];
                         };
                     }