@velocity-exchange/sdk 0.8.0 → 0.10.0

package/lib/node/equityFloorManager.js

@@ -0,0 +1,283 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EquityFloorManager = exports.planFloorMoves = exports.allocateEquityFloors = void 0;
+const anchor_1 = require("./isomorphic/anchor");
+const numericConstants_1 = require("./constants/numericConstants");
+const numericConstants_2 = require("./constants/numericConstants");
+const margin_1 = require("./math/margin");
+/**
+ * Splits `totalFloor` across subaccounts proportionally to their equity,
+ * clamped so every allocation is backed (`floor_i <= max(0, equity_i -
+ * buffer_i)`), with the clamped remainder water-filled into subaccounts that
+ * still have capacity. Entries in `pinned` keep their current floor and
+ * receive none of the remainder (used for breached subaccounts, which cannot
+ * shed floor on-chain). Returns `null` when no backed allocation exists, i.e.
+ * the pool's equity cannot cover `totalFloor` plus buffers.
+ */
+function allocateEquityFloors(totalFloor, subaccounts, pinned = []) {
+    const n = subaccounts.length;
+    const targets = new Array(n).fill(numericConstants_1.ZERO);
+    let remaining = totalFloor;
+    for (let i = 0; i < n; i++) {
+        if (pinned[i]) {
+            targets[i] = subaccounts[i].currentFloor;
+            remaining = remaining.sub(subaccounts[i].currentFloor);
+        }
+    }
+    if (remaining.isNeg()) {
+        // pinned floors alone exceed the total: nothing to allocate elsewhere
+        return null;
+    }
+    const free = [...Array(n).keys()].filter((i) => !pinned[i]);
+    const caps = subaccounts.map((s, i) => pinned[i] ? numericConstants_1.ZERO : anchor_1.BN.max(s.equity.sub(s.buffer), numericConstants_1.ZERO));
+    const totalCap = free.reduce((sum, i) => sum.add(caps[i]), numericConstants_1.ZERO);
+    if (totalCap.lt(remaining)) {
+        return null;
+    }
+    const totalFreeEquity = free.reduce((sum, i) => sum.add(anchor_1.BN.max(subaccounts[i].equity, numericConstants_1.ZERO)), numericConstants_1.ZERO);
+    // proportional-to-equity first pass (floor division), clamped to capacity
+    let assigned = numericConstants_1.ZERO;
+    for (const i of free) {
+        const share = totalFreeEquity.gt(numericConstants_1.ZERO)
+            ? remaining.mul(anchor_1.BN.max(subaccounts[i].equity, numericConstants_1.ZERO)).div(totalFreeEquity)
+            : numericConstants_1.ZERO;
+        targets[i] = anchor_1.BN.min(share, caps[i]);
+        assigned = assigned.add(targets[i]);
+    }
+    // water-fill the rounding/clamping remainder into leftover capacity
+    let leftover = remaining.sub(assigned);
+    for (const i of free) {
+        if (leftover.lte(numericConstants_1.ZERO)) {
+            break;
+        }
+        const slack = caps[i].sub(targets[i]);
+        const add = anchor_1.BN.min(slack, leftover);
+        targets[i] = targets[i].add(add);
+        leftover = leftover.sub(add);
+    }
+    if (leftover.gt(numericConstants_1.ZERO)) {
+        return null;
+    }
+    return targets;
+}
+exports.allocateEquityFloors = allocateEquityFloors;
+/**
+ * Turns a current → target floor split into concrete moves, greedily matching
+ * surpluses against deficits. The moves conserve the floor sum by
+ * construction and each one only ever sheds floor from a subaccount whose
+ * floor is above its target.
+ */
+function planFloorMoves(subAccountIds, current, target) {
+    const surpluses = [];
+    const deficits = [];
+    for (let i = 0; i < current.length; i++) {
+        const diff = current[i].sub(target[i]);
+        if (diff.gt(numericConstants_1.ZERO)) {
+            surpluses.push({ index: i, amount: diff });
+        }
+        else if (diff.lt(numericConstants_1.ZERO)) {
+            deficits.push({ index: i, amount: diff.neg() });
+        }
+    }
+    const moves = [];
+    let s = 0;
+    let d = 0;
+    while (s < surpluses.length && d < deficits.length) {
+        const delta = anchor_1.BN.min(surpluses[s].amount, deficits[d].amount);
+        moves.push({
+            fromSubAccountId: subAccountIds[surpluses[s].index],
+            toSubAccountId: subAccountIds[deficits[d].index],
+            equityFloorDelta: delta,
+        });
+        surpluses[s].amount = surpluses[s].amount.sub(delta);
+        deficits[d].amount = deficits[d].amount.sub(delta);
+        if (surpluses[s].amount.isZero()) {
+            s++;
+        }
+        if (deficits[d].amount.isZero()) {
+            d++;
+        }
+    }
+    return moves;
+}
+exports.planFloorMoves = planFloorMoves;
+const LEVEL_SEVERITY = {
+    breached: 4,
+    critical: 3,
+    warning: 2,
+    healthy: 1,
+    disabled: 0,
+};
+/**
+ * See the module doc. All reads use the subaccounts already subscribed on the
+ * wrapped `VelocityClient` (the delegate's client, whose `authority` is the
+ * subaccounts' owner); all writes go through `transferDepositByDelegate`.
+ */
+class EquityFloorManager {
+    constructor(velocityClient, config = {}) {
+        var _a;
+        this.velocityClient = velocityClient;
+        this.subAccountIds = config.subAccountIds;
+        this.collateralHaircut = (_a = config.collateralHaircut) !== null && _a !== void 0 ? _a : numericConstants_1.QUOTE_PRECISION;
+    }
+    getManagedUsers() {
+        const authority = this.velocityClient.authority;
+        let users = this.velocityClient
+            .getUsers()
+            .filter((user) => user.getUserAccountOrThrow().authority.equals(authority));
+        if (this.subAccountIds !== undefined) {
+            const wanted = new Set(this.subAccountIds);
+            users = users.filter((user) => wanted.has(user.getUserAccountOrThrow().subAccountId));
+        }
+        return users.sort((a, b) => a.getUserAccountOrThrow().subAccountId -
+            b.getUserAccountOrThrow().subAccountId);
+    }
+    getSubaccountStatus(user) {
+        const userAccount = user.getUserAccountOrThrow();
+        const equity = user.getNetUsdValue();
+        const bufferedFloor = userAccount.equityFloor.add(userAccount.equityFloorBuffer);
+        return {
+            subAccountId: userAccount.subAccountId,
+            equity,
+            equityFloor: userAccount.equityFloor,
+            equityFloorBuffer: userAccount.equityFloorBuffer,
+            bufferedFloor,
+            headroom: equity.sub(userAccount.equityFloor),
+            bufferedHeadroom: equity.sub(bufferedFloor),
+            level: (0, margin_1.getEquityFloorLevel)(equity, userAccount.equityFloor, userAccount.equityFloorBuffer),
+        };
+    }
+    /** Full authority-wide standing: aggregates, worst level, per-subaccount detail. */
+    getStatus() {
+        var _a, _b, _c;
+        const subaccounts = this.getManagedUsers().map((user) => this.getSubaccountStatus(user));
+        const totalEquity = subaccounts.reduce((s, u) => s.add(u.equity), numericConstants_1.ZERO);
+        const totalFloor = subaccounts.reduce((s, u) => s.add(u.equityFloor), numericConstants_1.ZERO);
+        const totalBuffer = subaccounts.reduce((s, u) => s.add(u.equityFloorBuffer), numericConstants_1.ZERO);
+        const level = subaccounts.reduce((worst, u) => LEVEL_SEVERITY[u.level] > LEVEL_SEVERITY[worst] ? u.level : worst, 'disabled');
+        return {
+            authority: this.velocityClient.authority,
+            breakerTripped: ((_c = (_b = (_a = this.velocityClient.getUserStats()) === null || _a === void 0 ? void 0 : _a.getAccount()) === null || _b === void 0 ? void 0 : _b.equityBreakerTripped) !== null && _c !== void 0 ? _c : 0) !== 0,
+            totalEquity,
+            totalFloor,
+            totalBuffer,
+            totalBufferedHeadroom: totalEquity.sub(totalFloor).sub(totalBuffer),
+            level,
+            subaccounts,
+        };
+    }
+    /**
+     * The most quote that can leave `subAccountId` to the outside (a
+     * withdrawal, which cannot move floor): equity above the buffered floor,
+     * less the haircut. Floor constraint only — the withdrawal itself is still
+     * subject to margin and borrow limits.
+     */
+    getMaxWithdrawable(subAccountId) {
+        const status = this.getSubaccountStatus(this.velocityClient.getUser(subAccountId, this.velocityClient.authority));
+        if (status.equityFloor.lte(numericConstants_1.ZERO)) {
+            return status.equity;
+        }
+        return anchor_1.BN.max(status.bufferedHeadroom.sub(this.collateralHaircut), numericConstants_1.ZERO);
+    }
+    /**
+     * The most quote that can move from one subaccount to another when the
+     * transfer carries floor with it. Because floor travels with the funds
+     * (capped at the floor the debited side holds, after which its check
+     * disables entirely), this is normally the debited side's whole equity —
+     * bounded by what the credited side's equity can back. Floor constraint
+     * only; margin and borrow limits still apply on top.
+     */
+    getMaxQuoteTransferable(fromSubAccountId, toSubAccountId) {
+        const from = this.getSubaccountStatus(this.velocityClient.getUser(fromSubAccountId, this.velocityClient.authority));
+        const to = this.getSubaccountStatus(this.velocityClient.getUser(toSubAccountId, this.velocityClient.authority));
+        const haircut = this.collateralHaircut;
+        // how much floor the credited side can absorb beyond what the incoming
+        // funds themselves back: its own buffered headroom (delta <= amount
+        // keeps it backed; beyond that it eats into existing headroom)
+        const toSlack = anchor_1.BN.max(to.bufferedHeadroom.sub(haircut), numericConstants_1.ZERO);
+        if (from.equityFloor.lte(numericConstants_1.ZERO)) {
+            return anchor_1.BN.max(from.equity.sub(haircut), numericConstants_1.ZERO);
+        }
+        // shedding the entire floor disables the debited side's check; possible
+        // only if the credited side can absorb floor faster than the funds back
+        // it, i.e. it has slack of its own
+        const fullShedViable = from.equity
+            .sub(from.bufferedFloor)
+            .add(from.equityFloor)
+            .add(toSlack);
+        // without full shed: amount <= excess + floor (auto delta caps at floor)
+        const partialShedMax = anchor_1.BN.max(from.bufferedHeadroom, numericConstants_1.ZERO).add(from.equityFloor);
+        const floorwiseMax = anchor_1.BN.min(anchor_1.BN.max(fullShedViable, partialShedMax), from.equity);
+        return anchor_1.BN.max(floorwiseMax.sub(haircut), numericConstants_1.ZERO);
+    }
+    /**
+     * Resolves a quote transfer into the exact instruction parameters,
+     * padding the auto floor delta by the haircut so onchain pricing dust
+     * cannot fail it. The padded delta never exceeds the amount or the
+     * debited side's floor, so the credited side stays backed whenever it was
+     * before.
+     */
+    planQuoteTransfer(amount, fromSubAccountId, toSubAccountId) {
+        const fromUser = this.velocityClient.getUser(fromSubAccountId, this.velocityClient.authority);
+        const fromAccount = fromUser.getUserAccountOrThrow();
+        const equityFloorDelta = (0, margin_1.calculateEquityFloorAutoDelta)(amount, fromUser.getNetUsdValue().sub(this.collateralHaircut), fromAccount.equityFloor, fromAccount.equityFloorBuffer);
+        return {
+            amount,
+            marketIndex: numericConstants_2.QUOTE_SPOT_MARKET_INDEX,
+            fromSubAccountId,
+            toSubAccountId,
+            equityFloorDelta: anchor_1.BN.min(equityFloorDelta, amount),
+        };
+    }
+    /** Plans and submits a quote transfer between two subaccounts in one call. */
+    async transferQuote(amount, fromSubAccountId, toSubAccountId, txParams) {
+        const plan = this.planQuoteTransfer(amount, fromSubAccountId, toSubAccountId);
+        return this.velocityClient.transferDepositByDelegate(plan.amount, plan.marketIndex, plan.fromSubAccountId, plan.toSubAccountId, plan.equityFloorDelta, txParams);
+    }
+    /**
+     * Plans the floor-only moves (zero-amount transfers) that re-split the
+     * total floor proportionally to where the equity currently sits, so every
+     * subaccount ends with the same relative headroom. Breached subaccounts
+     * (below their raw floor) cannot shed floor on-chain, so their floor is
+     * pinned in place and the rest is allocated around them. Throws when the
+     * pool's equity cannot back the total floor plus buffers — at that point
+     * no split works and equity must be deposited (or the admin must lower
+     * the floor). Each onchain move also carries a proportional share of the
+     * debited side's buffer, so buffers drift toward the same split as the
+     * floors; the plan sizes against current buffers and the haircut absorbs
+     * the drift dust, but a move can still revert if a credited side cannot
+     * back the buffer share it receives.
+     */
+    planFloorRebalance() {
+        const subaccounts = this.getManagedUsers().map((user) => this.getSubaccountStatus(user));
+        if (subaccounts.length < 2) {
+            return [];
+        }
+        const totalFloor = subaccounts.reduce((sum, u) => sum.add(u.equityFloor), numericConstants_1.ZERO);
+        if (totalFloor.lte(numericConstants_1.ZERO)) {
+            return [];
+        }
+        const pinned = subaccounts.map((u) => u.level === 'breached');
+        const targets = allocateEquityFloors(totalFloor, subaccounts.map((u) => ({
+            equity: anchor_1.BN.max(u.equity.sub(this.collateralHaircut), numericConstants_1.ZERO),
+            buffer: u.equityFloorBuffer,
+            currentFloor: u.equityFloor,
+        })), pinned);
+        if (targets === null) {
+            throw new Error('no backed floor split exists: total equity cannot cover the total floor plus buffers; deposit equity or have the admin lower the floor');
+        }
+        return planFloorMoves(subaccounts.map((u) => u.subAccountId), subaccounts.map((u) => u.equityFloor), targets);
+    }
+    /**
+     * Executes `planFloorRebalance` serially. Safe to run at any time; a
+     * no-op when the split already matches the equity distribution.
+     */
+    async rebalanceFloors(txParams) {
+        const sigs = [];
+        for (const move of this.planFloorRebalance()) {
+            sigs.push(await this.velocityClient.transferDepositByDelegate(numericConstants_1.ZERO, numericConstants_2.QUOTE_SPOT_MARKET_INDEX, move.fromSubAccountId, move.toSubAccountId, move.equityFloorDelta, txParams));
+        }
+        return sigs;
+    }
+}
+exports.EquityFloorManager = EquityFloorManager;

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

@@ -12466,6 +12466,10 @@ export type Velocity = {
                 {
                     "name": "equityFloor";
                     "type": "u64";
+                },
+                {
+                    "name": "equityFloorBuffer";
+                    "type": "u64";
                 }
             ];
         },
@@ -12887,6 +12891,63 @@ export type Velocity = {
             ];
             "args": [];
         },
+        {
+            "name": "updateUserVaultOwned";
+            "docs": [
+                "Mark a User as vault-owned (its authority is a vault PDA and its equity",
+                "prices vault depositor shares). Set-only and authority-gated: only the",
+                "User's authority may call it, and it is CPI'd by the vaults program at",
+                "vault init. A vault-owned User is skipped by the revenue-share sweep so a",
+                "builder/referral reward can never enter vault NAV (OtterSec #91/#92/#93)."
+            ];
+            "discriminator": [
+                50,
+                156,
+                218,
+                143,
+                216,
+                94,
+                68,
+                93
+            ];
+            "accounts": [
+                {
+                    "name": "user";
+                    "writable": true;
+                    "pda": {
+                        "seeds": [
+                            {
+                                "kind": "const";
+                                "value": [
+                                    117,
+                                    115,
+                                    101,
+                                    114
+                                ];
+                            },
+                            {
+                                "kind": "account";
+                                "path": "authority";
+                            },
+                            {
+                                "kind": "arg";
+                                "path": "subAccountId";
+                            }
+                        ];
+                    };
+                },
+                {
+                    "name": "authority";
+                    "signer": true;
+                }
+            ];
+            "args": [
+                {
+                    "name": "subAccountId";
+                    "type": "u16";
+                }
+            ];
+        },
         {
             "name": "updateWarmAdmin";
             "discriminator": [
@@ -16299,6 +16360,16 @@ export type Velocity = {
             "code": 6364;
             "name": "dailyDepositLimit";
             "msg": "Spot market daily deposit limit hit";
+        },
+        {
+            "code": 6365;
+            "name": "reservedSpotMarketName";
+            "msg": "The name 'USDT' is reserved for the quote spot market (index 0)";
+        },
+        {
+            "code": 6366;
+            "name": "cannotModifyBuilderOrder";
+            "msg": "Cannot modify a builder-coded order; cancel and re-place instead";
         }
     ];
     "types": [
@@ -24065,21 +24136,25 @@ export type Velocity = {
                     {
                         "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.",
+                            "Minimum account net equity (unweighted assets plus perp pnl minus",
+                            "spot liabilities, see `calculate_user_equity`). Below this the",
+                            "permissionless breaker can trip. Risk-increasing orders, fills,",
+                            "withdrawals and deposit transfers must clear `equity_floor +",
+                            "equity_floor_buffer`. Settable only by the warm/cold admin; 0 disables",
+                            "both checks.",
                             "precision: QUOTE_PRECISION"
                         ];
                         "type": "u64";
                     },
                     {
-                        "name": "padding2";
-                        "type": {
-                            "array": [
-                                "u8",
-                                8
-                            ];
-                        };
+                        "name": "equityFloorBuffer";
+                        "docs": [
+                            "Extra headroom above `equity_floor` required by risk-increasing",
+                            "actions, so an account cannot legally end an action at the trip",
+                            "threshold. No effect while `equity_floor` is 0.",
+                            "precision: QUOTE_PRECISION"
+                        ];
+                        "type": "u64";
                     }
                 ];
             };