@velocity-exchange/sdk 0.8.0 → 0.9.0

package/lib/node/equityFloorManager.d.ts

@@ -0,0 +1,151 @@
+/**
+ * Maker-facing abstraction over the per-subaccount equity floor. The on-chain
+ * checks are deliberately per-subaccount (each check reads only the one User
+ * account already loaded in the hot path), which leaves the burden of placing
+ * floor where the equity is on the delegate. This module removes that burden:
+ * it treats an authority's subaccounts as one pool, plans quote transfers with
+ * the exact floor delta they must carry, computes how much can leave a
+ * subaccount, and rebalances the floor split to match where the equity
+ * actually sits — so a delegate never has to reason about floor placement to
+ * stay clear of the breaker.
+ */
+import { PublicKey } from '@solana/web3.js';
+import { TransactionSignature } from '@solana/web3.js';
+import { BN } from './isomorphic/anchor';
+import { EquityFloorLevel } from './math/margin';
+import { VelocityClient } from './velocityClient';
+import { TxParams } from './types';
+/** One subaccount's standing relative to its floor. All BN values QUOTE_PRECISION. */
+export type SubaccountFloorStatus = {
+    subAccountId: number;
+    /** Cross-margin total collateral, strict (TWAP-bounded) pricing — what the on-chain checks see. */
+    equity: BN;
+    equityFloor: BN;
+    equityFloorBuffer: BN;
+    /** `equityFloor + equityFloorBuffer`: what risk-increasing actions must clear. */
+    bufferedFloor: BN;
+    /** `equity - equityFloor`; negative means the breaker can trip on this subaccount. */
+    headroom: BN;
+    /** `equity - bufferedFloor`; negative means risk-increasing actions are rejecting. */
+    bufferedHeadroom: BN;
+    level: EquityFloorLevel;
+};
+/** Authority-wide standing: aggregates plus the per-subaccount breakdown. */
+export type EquityFloorStatus = {
+    authority: PublicKey;
+    breakerTripped: boolean;
+    totalEquity: BN;
+    totalFloor: BN;
+    totalBuffer: BN;
+    /** `totalEquity - (totalFloor + totalBuffer)`: the slack the whole pool has to allocate. */
+    totalBufferedHeadroom: BN;
+    /** Worst level across subaccounts with a floor set. */
+    level: EquityFloorLevel;
+    subaccounts: SubaccountFloorStatus[];
+};
+/** A floor-only rebalance step: zero-amount `transferDepositByDelegate` carrying `equityFloorDelta`. */
+export type FloorMove = {
+    fromSubAccountId: number;
+    toSubAccountId: number;
+    equityFloorDelta: BN;
+};
+/** A fully resolved quote transfer ready to submit. */
+export type QuoteTransferPlan = {
+    amount: BN;
+    marketIndex: number;
+    fromSubAccountId: number;
+    toSubAccountId: number;
+    equityFloorDelta: BN;
+};
+/**
+ * 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.
+ */
+export declare function allocateEquityFloors(totalFloor: BN, subaccounts: {
+    equity: BN;
+    buffer: BN;
+    currentFloor: BN;
+}[], pinned?: boolean[]): BN[] | null;
+/**
+ * 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.
+ */
+export declare function planFloorMoves(subAccountIds: number[], current: BN[], target: BN[]): FloorMove[];
+export type EquityFloorManagerConfig = {
+    /**
+     * Subaccount ids to manage. Defaults to every subaccount of the client's
+     * authority currently subscribed on the `VelocityClient`.
+     */
+    subAccountIds?: number[];
+    /**
+     * Client-side equity haircut (QUOTE_PRECISION) applied when sizing floor
+     * deltas, absorbing the dust by which strict on-chain pricing can differ
+     * from the client's. Defaults to 1 quote unit ($1).
+     */
+    collateralHaircut?: BN;
+};
+/**
+ * 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`.
+ */
+export declare class EquityFloorManager {
+    private velocityClient;
+    private collateralHaircut;
+    private subAccountIds?;
+    constructor(velocityClient: VelocityClient, config?: EquityFloorManagerConfig);
+    private getManagedUsers;
+    private getSubaccountStatus;
+    /** Full authority-wide standing: aggregates, worst level, per-subaccount detail. */
+    getStatus(): EquityFloorStatus;
+    /**
+     * 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: number): BN;
+    /**
+     * 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: number, toSubAccountId: number): BN;
+    /**
+     * Resolves a quote transfer into the exact instruction parameters,
+     * padding the auto floor delta by the haircut so on-chain strict 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: BN, fromSubAccountId: number, toSubAccountId: number): QuoteTransferPlan;
+    /** Plans and submits a quote transfer between two subaccounts in one call. */
+    transferQuote(amount: BN, fromSubAccountId: number, toSubAccountId: number, txParams?: TxParams): Promise<TransactionSignature>;
+    /**
+     * 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).
+     */
+    planFloorRebalance(): FloorMove[];
+    /**
+     * Executes `planFloorRebalance` serially. Safe to run at any time; a
+     * no-op when the split already matches the equity distribution.
+     */
+    rebalanceFloors(txParams?: TxParams): Promise<TransactionSignature[]>;
+}
+//# sourceMappingURL=equityFloorManager.d.ts.map

package/lib/node/equityFloorManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"equityFloorManager.d.ts","sourceRoot":"","sources":["../../src/equityFloorManager.ts"],"names":[],"mappings":"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"}

package/lib/node/equityFloorManager.js

@@ -0,0 +1,279 @@
+"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.getTotalCollateral('Initial', true);
+        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 on-chain strict 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.getTotalCollateral('Initial', true).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).
+     */
+    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,24 @@ 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 equity (cross-margin total collateral). 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";
                     }
                 ];
             };