@drift-labs/sdk 2.149.1 → 2.150.0-alpha.0

package/src/idl/drift.json

@@ -652,6 +652,163 @@
         }
       ]
     },
+    {
+      "name": "depositIntoIsolatedPerpPosition",
+      "accounts": [
+        {
+          "name": "state",
+          "isMut": false,
+          "isSigner": false
+        },
+        {
+          "name": "user",
+          "isMut": true,
+          "isSigner": false
+        },
+        {
+          "name": "userStats",
+          "isMut": true,
+          "isSigner": false
+        },
+        {
+          "name": "authority",
+          "isMut": false,
+          "isSigner": true
+        },
+        {
+          "name": "spotMarketVault",
+          "isMut": true,
+          "isSigner": false
+        },
+        {
+          "name": "userTokenAccount",
+          "isMut": true,
+          "isSigner": false
+        },
+        {
+          "name": "tokenProgram",
+          "isMut": false,
+          "isSigner": false
+        }
+      ],
+      "args": [
+        {
+          "name": "spotMarketIndex",
+          "type": "u16"
+        },
+        {
+          "name": "perpMarketIndex",
+          "type": "u16"
+        },
+        {
+          "name": "amount",
+          "type": "u64"
+        }
+      ]
+    },
+    {
+      "name": "transferIsolatedPerpPositionDeposit",
+      "accounts": [
+        {
+          "name": "user",
+          "isMut": true,
+          "isSigner": false
+        },
+        {
+          "name": "userStats",
+          "isMut": true,
+          "isSigner": false
+        },
+        {
+          "name": "authority",
+          "isMut": false,
+          "isSigner": true
+        },
+        {
+          "name": "state",
+          "isMut": false,
+          "isSigner": false
+        },
+        {
+          "name": "spotMarketVault",
+          "isMut": false,
+          "isSigner": false
+        }
+      ],
+      "args": [
+        {
+          "name": "spotMarketIndex",
+          "type": "u16"
+        },
+        {
+          "name": "perpMarketIndex",
+          "type": "u16"
+        },
+        {
+          "name": "amount",
+          "type": "i64"
+        }
+      ]
+    },
+    {
+      "name": "withdrawFromIsolatedPerpPosition",
+      "accounts": [
+        {
+          "name": "state",
+          "isMut": false,
+          "isSigner": false
+        },
+        {
+          "name": "user",
+          "isMut": true,
+          "isSigner": false
+        },
+        {
+          "name": "userStats",
+          "isMut": true,
+          "isSigner": false
+        },
+        {
+          "name": "authority",
+          "isMut": false,
+          "isSigner": true
+        },
+        {
+          "name": "spotMarketVault",
+          "isMut": true,
+          "isSigner": false
+        },
+        {
+          "name": "driftSigner",
+          "isMut": false,
+          "isSigner": false
+        },
+        {
+          "name": "userTokenAccount",
+          "isMut": true,
+          "isSigner": false
+        },
+        {
+          "name": "tokenProgram",
+          "isMut": false,
+          "isSigner": false
+        }
+      ],
+      "args": [
+        {
+          "name": "spotMarketIndex",
+          "type": "u16"
+        },
+        {
+          "name": "perpMarketIndex",
+          "type": "u16"
+        },
+        {
+          "name": "amount",
+          "type": "u64"
+        }
+      ]
+    },
     {
       "name": "placePerpOrder",
       "accounts": [
@@ -14412,13 +14569,13 @@
             "type": "u64"
           },
           {
-            "name": "lastBaseAssetAmountPerLp",
+            "name": "isolatedPositionScaledBalance",
             "docs": [
               "The last base asset amount per lp the amm had",
               "Used to settle the users lp position",
-              "precision: BASE_PRECISION"
+              "precision: SPOT_BALANCE_PRECISION"
             ],
-            "type": "i64"
+            "type": "u64"
           },
           {
             "name": "lastQuoteAssetAmountPerLp",
@@ -14457,8 +14614,8 @@
             "type": "u8"
           },
           {
-            "name": "perLpBase",
-            "type": "i8"
+            "name": "positionFlag",
+            "type": "u8"
           }
         ]
       }
@@ -15138,6 +15295,17 @@
         ]
       }
     },
+    {
+      "name": "LiquidationBitFlag",
+      "type": {
+        "kind": "enum",
+        "variants": [
+          {
+            "name": "IsolatedPosition"
+          }
+        ]
+      }
+    },
     {
       "name": "SettlePnlExplanation",
       "type": {
@@ -15267,13 +15435,7 @@
         "kind": "enum",
         "variants": [
           {
-            "name": "Standard",
-            "fields": [
-              {
-                "name": "trackOpenOrdersFraction",
-                "type": "bool"
-              }
-            ]
+            "name": "Standard"
           },
           {
             "name": "Liquidation",
@@ -15434,6 +15596,9 @@
           },
           {
             "name": "AmmImmediateFill"
+          },
+          {
+            "name": "SettleRevPool"
           }
         ]
       }
@@ -15912,6 +16077,23 @@
         ]
       }
     },
+    {
+      "name": "PositionFlag",
+      "type": {
+        "kind": "enum",
+        "variants": [
+          {
+            "name": "IsolatedPosition"
+          },
+          {
+            "name": "BeingLiquidated"
+          },
+          {
+            "name": "Bankrupt"
+          }
+        ]
+      }
+    },
     {
       "name": "ReferrerStatus",
       "type": {
@@ -16131,6 +16313,18 @@
             "option": "publicKey"
           },
           "index": false
+        },
+        {
+          "name": "signer",
+          "type": {
+            "option": "publicKey"
+          },
+          "index": false
+        },
+        {
+          "name": "userTokenAmountAfter",
+          "type": "i128",
+          "index": false
         }
       ]
     },
@@ -16876,6 +17070,11 @@
             "defined": "SpotBankruptcyRecord"
           },
           "index": false
+        },
+        {
+          "name": "bitFlags",
+          "type": "u8",
+          "index": false
         }
       ]
     },
@@ -18312,8 +18511,8 @@
     },
     {
       "code": 6094,
-      "name": "CantUpdatePoolBalanceType",
-      "msg": "CantUpdatePoolBalanceType"
+      "name": "CantUpdateSpotBalanceType",
+      "msg": "CantUpdateSpotBalanceType"
     },
     {
       "code": 6095,
@@ -19427,41 +19626,46 @@
     },
     {
       "code": 6317,
+      "name": "InvalidIsolatedPerpMarket",
+      "msg": "Invalid Isolated Perp Market"
+    },
+    {
+      "code": 6318,
       "name": "InvalidRevenueShareResize",
       "msg": "Invalid RevenueShare resize"
     },
     {
-      "code": 6318,
+      "code": 6319,
       "name": "BuilderRevoked",
       "msg": "Builder has been revoked"
     },
     {
-      "code": 6319,
+      "code": 6320,
       "name": "InvalidBuilderFee",
       "msg": "Builder fee is greater than max fee bps"
     },
     {
-      "code": 6320,
+      "code": 6321,
       "name": "RevenueShareEscrowAuthorityMismatch",
       "msg": "RevenueShareEscrow authority mismatch"
     },
     {
-      "code": 6321,
+      "code": 6322,
       "name": "RevenueShareEscrowOrdersAccountFull",
       "msg": "RevenueShareEscrow has too many active orders"
     },
     {
-      "code": 6322,
+      "code": 6323,
       "name": "InvalidRevenueShareAccount",
       "msg": "Invalid RevenueShareAccount"
     },
     {
-      "code": 6323,
+      "code": 6324,
       "name": "CannotRevokeBuilderWithOpenOrders",
       "msg": "Cannot revoke builder with open orders"
     },
     {
-      "code": 6324,
+      "code": 6325,
       "name": "UnableToLoadRevenueShareAccount",
       "msg": "Unable to load builder account"
     },
@@ -19566,4 +19770,4 @@
       "msg": "MarketIndexNotFoundAmmCache"
     }
   ]
-}
+}

package/src/margin/README.md

@@ -0,0 +1,143 @@
+## Margin Calculation Snapshot (SDK)
+
+This document describes the single-source-of-truth margin engine in the SDK that mirrors the on-chain `MarginCalculation` and related semantics. The goal is to compute an immutable snapshot in one pass and have existing `User` getters delegate to it, eliminating duplicative work across getters and UI hooks while maintaining parity with the program.
+
+### Alignment with on-chain
+
+- The SDK snapshot shape mirrors `programs/drift/src/state/margin_calculation.rs` field-for-field.
+- The inputs and ordering mirror `calculate_margin_requirement_and_total_collateral_and_liability_info` in `programs/drift/src/math/margin.rs`.
+- Isolated positions are represented as `isolated_margin_calculations` keyed by perp `market_index`, matching program logic.
+
+### Core SDK types (shape parity)
+
+```ts
+// Types reflect on-chain names and numeric signs
+export type MarginRequirementType = 'Initial' | 'Fill' | 'Maintenance';
+export type MarketType = 'Spot' | 'Perp';
+
+export type MarketIdentifier = {
+  marketType: MarketType;
+  marketIndex: number; // u16
+};
+
+export type MarginCalculationMode =
+  | { kind: 'Standard' }
+  | { kind: 'Liquidation'; marketToTrackMarginRequirement?: MarketIdentifier };
+
+export type MarginContext = {
+  marginType: MarginRequirementType;
+  mode: MarginCalculationMode;
+  strict: boolean;
+  ignoreInvalidDepositOracles: boolean;
+  marginBuffer: BN;                  // u128
+  fuelBonusNumerator: number;       // i64
+  fuelBonus: number;                 // u64
+  fuelPerpDelta?: { marketIndex: number; delta: BN };      // (u16, i64)
+  fuelSpotDeltas: Array<{ marketIndex: number; delta: BN }>; // up to 2 entries
+  marginRatioOverride?: number;     // u32
+};
+
+export type IsolatedMarginCalculation = {
+  marginRequirement: BN;             // u128
+  totalCollateral: BN;               // i128
+  totalCollateralBuffer: BN;        // i128
+  marginRequirementPlusBuffer: BN; // u128
+};
+
+export type MarginCalculation = {
+  context: MarginContext;
+
+  totalCollateral: BN;               // i128
+  totalCollateralBuffer: BN;        // i128
+  marginRequirement: BN;             // u128
+  marginRequirementPlusBuffer: BN; // u128
+
+  isolatedMarginCalculations: Map<number, IsolatedMarginCalculation>; // BTreeMap<u16,_>
+
+  numSpotLiabilities: number;       // u8
+  numPerpLiabilities: number;       // u8
+  allDepositOraclesValid: boolean;
+  allLiabilityOraclesValid: boolean;
+  withPerpIsolatedLiability: boolean;
+  withSpotIsolatedLiability: boolean;
+
+  totalSpotAssetValue: BN;         // i128
+  totalSpotLiabilityValue: BN;     // u128
+  totalPerpLiabilityValue: BN;     // u128
+  totalPerpPnl: BN;                 // i128
+
+  trackedMarketMarginRequirement: BN; // u128
+  fuelDeposits: number;              // u32
+  fuelBorrows: number;               // u32
+  fuelPositions: number;             // u32
+};
+```
+
+### Engine API
+
+```ts
+// Pure computation, no I/O; uses data already cached in the client/subscribers
+export function computeMarginCalculation(user: User, context: MarginContext): MarginCalculation;
+
+// Helpers that mirror on-chain semantics
+export function meets_margin_requirement(calc: MarginCalculation): boolean;
+export function meets_margin_requirement_with_buffer(calc: MarginCalculation): boolean;
+export function get_cross_free_collateral(calc: MarginCalculation): BN;
+export function get_isolated_free_collateral(calc: MarginCalculation, marketIndex: number): BN;
+export function cross_margin_shortage(calc: MarginCalculation): BN; // requires buffer mode
+export function isolated_margin_shortage(calc: MarginCalculation, marketIndex: number): BN; // requires buffer mode
+```
+
+### Computation model (on-demand)
+
+- The SDK computes the snapshot on-demand when `getMarginCalculation(...)` is called.
+- No event-driven recomputation by default (oracle prices can change every slot; recomputing every update would be wasteful).
+- Callers (UI/bots) decide polling frequency (e.g., UI can refresh every ~1s on active trade forms).
+
+### User integration
+
+- Add `user.getMarginCalculation(margin_type = 'Initial', overrides?: Partial<MarginContext>)`.
+- Existing getters delegate to the snapshot to avoid duplicate work:
+  - `getTotalCollateral()` → `snapshot.total_collateral`
+  - `getMarginRequirement(mode)` → `snapshot.margin_requirement`
+  - `getFreeCollateral()` → `get_cross_free_collateral(snapshot)`
+  - Per-market isolated FC → `get_isolated_free_collateral(snapshot, marketIndex)`
+
+Suggested `User` API surface (non-breaking):
+
+```ts
+// Primary entrypoint
+getMarginCalculation(
+  marginType: 'Initial' | 'Maintenance' | 'Fill' = 'Initial',
+  contextOverrides?: Partial<MarginContext>
+): MarginCalculation;
+
+// Optional conveniences for consumers
+getIsolatedMarginCalculation(
+  marketIndex: number,
+  marginType: 'Initial' | 'Maintenance' | 'Fill' = 'Initial',
+  contextOverrides?: Partial<MarginContext>
+): IsolatedMarginCalculation | undefined;
+
+// Cross views can continue to use helpers on the snapshot:
+// get_cross_free_collateral(snapshot), meets_margin_requirement(snapshot), etc.
+```
+
+### UI compatibility
+
+- All existing `User` getters remain and delegate to the snapshot, so current UI keeps working without call-site changes.
+- New consumers can call `user.getMarginCalculation()` to access isolated breakdowns.
+
+### Testing and parity
+
+- Golden tests comparing SDK snapshot against program outputs (cross and isolated, edge cases).
+- Keep math/rounding identical to program (ordering, buffers, funding, open-order IM, oracle strictness).
+
+### Migration plan (brief)
+
+1. Implement `types` and `engine` with strict parity; land behind a feature flag.
+2. Add `user.getMarginCalculation()` and delegate legacy getters.
+3. Optionally update UI hooks to read richer fields; not required for compatibility.
+4. Expand parity tests; enable by default after validation.
+
+

package/src/math/margin.ts

@@ -166,21 +166,20 @@ export function calculateWorstCasePerpLiabilityValue(
 	perpPosition: PerpPosition,
 	perpMarket: PerpMarketAccount,
 	oraclePrice: BN,
-	includeOpenOrders = true
+	includeOpenOrders: boolean = true
 ): { worstCaseBaseAssetAmount: BN; worstCaseLiabilityValue: BN } {
 	const isPredictionMarket = isVariant(perpMarket.contractType, 'prediction');
-
+	// return early if no open orders required
 	if (!includeOpenOrders) {
 		return {
 			worstCaseBaseAssetAmount: perpPosition.baseAssetAmount,
 			worstCaseLiabilityValue: calculatePerpLiabilityValue(
 				perpPosition.baseAssetAmount,
 				oraclePrice,
-				isPredictionMarket
+				isVariant(perpMarket.contractType, 'prediction')
 			),
 		};
 	}
-
 	const allBids = perpPosition.baseAssetAmount.add(perpPosition.openBids);
 	const allAsks = perpPosition.baseAssetAmount.add(perpPosition.openAsks);
 

package/src/math/position.ts

@@ -14,6 +14,7 @@ import {
 	PositionDirection,
 	PerpPosition,
 	SpotMarketAccount,
+	PositionFlag,
 } from '../types';
 import {
 	calculateUpdatedAMM,
@@ -127,7 +128,6 @@ export function calculatePositionPNL(
 
 	if (withFunding) {
 		const fundingRatePnL = calculateUnsettledFundingPnl(market, perpPosition);
-
 		pnl = pnl.add(fundingRatePnL);
 	}
 
@@ -244,7 +244,17 @@ export function positionIsAvailable(position: PerpPosition): boolean {
 		position.baseAssetAmount.eq(ZERO) &&
 		position.openOrders === 0 &&
 		position.quoteAssetAmount.eq(ZERO) &&
-		position.lpShares.eq(ZERO)
+		position.lpShares.eq(ZERO) &&
+		position.isolatedPositionScaledBalance.eq(ZERO) &&
+		!positionIsBeingLiquidated(position)
+	);
+}
+
+export function positionIsBeingLiquidated(position: PerpPosition): boolean {
+	return (
+		(position.positionFlag &
+			(PositionFlag.BeingLiquidated | PositionFlag.Bankruptcy)) >
+		0
 	);
 }
 

package/src/math/spotBalance.ts

@@ -68,7 +68,6 @@ export function getTokenAmount(
 	balanceType: SpotBalanceType
 ): BN {
 	const precisionDecrease = TEN.pow(new BN(19 - spotMarket.decimals));
-
 	if (isVariant(balanceType, 'deposit')) {
 		return balanceAmount
 			.mul(spotMarket.cumulativeDepositInterest)

package/src/types.ts

@@ -585,6 +585,10 @@ export type SpotBankruptcyRecord = {
 	ifPayment: BN;
 };
 
+export class LiquidationBitFlag {
+	static readonly IsolatedPosition = 1;
+}
+
 export type SettlePnlRecord = {
 	ts: BN;
 	user: PublicKey;
@@ -1137,16 +1141,10 @@ export type PerpPosition = {
 	lastBaseAssetAmountPerLp: BN;
 	lastQuoteAssetAmountPerLp: BN;
 	perLpBase: number;
-	isolatedPositionScaledBalance: BN;
 	positionFlag: number;
+	isolatedPositionScaledBalance: BN;
 };
 
-export class PositionFlag {
-	static readonly IsolatedPosition = 1;
-	static readonly BeingLiquidated = 2;
-	static readonly Bankruptcy = 4;
-}
-
 export type UserStatsAccount = {
 	numberOfSubAccounts: number;
 	numberOfSubAccountsCreated: number;
@@ -1297,6 +1295,12 @@ export class OrderParamsBitFlag {
 	static readonly UpdateHighLeverageMode = 2;
 }
 
+export class PositionFlag {
+	static readonly IsolatedPosition = 1;
+	static readonly BeingLiquidated = 2;
+	static readonly Bankruptcy = 4;
+}
+
 export type NecessaryOrderParams = {
 	orderType: OrderType;
 	marketIndex: number;
@@ -1308,6 +1312,10 @@ export type OptionalOrderParams = {
 	[Property in keyof OrderParams]?: OrderParams[Property];
 } & NecessaryOrderParams;
 
+export type PerpOrderIsolatedExtras = {
+	isolatedPositionDepositAmount?: BN;
+};
+
 export type ModifyOrderParams = {
 	[Property in keyof OrderParams]?: OrderParams[Property] | null;
 } & { policy?: ModifyOrderPolicy };