@raac/rpc 2.0.0-beta.21 → 2.0.0-beta.22

package/dist/pools/stabilityPool/liquidation.js

@@ -3,41 +3,47 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.minSharesOut = exports.sameSplit = exports.splitTotal = exports.SPLIT_KEYS = void 0;
+exports.minSharesOut = exports.sharesAtNav = exports.valueAtNav = exports.curveQuote = exports.DEFAULT_PLAN_PARAMS = exports.sameSplit = exports.splitTotal = exports.SPLIT_KEYS = void 0;
 exports.readLiquidationContext = readLiquidationContext;
 exports.readLiquidationTarget = readLiquidationTarget;
-exports.quoteLiquidation = quoteLiquidation;
-exports.suggestSplit = suggestSplit;
-exports.simulateWithSplit = simulateWithSplit;
+exports.toleranceNeeded = toleranceNeeded;
+exports.priceImpact = priceImpact;
+exports.largestClearingFloor = largestClearingFloor;
+exports.planLiquidation = planLiquidation;
 /**
- * Liquidation simulation for StabilityPool.liquidateBorrower, mirroring LiquidationStrategyProxy:
+ * Planning StabilityPool.liquidateBorrower, mirroring LiquidationStrategyProxy:
  *   1. the seized collateral is deposited into the RWAVault for vault-token shares, unless it already is the vault token;
  *   2. the stability pool's whole vault-token balance (the proxy runs under delegatecall) is split by BPS into
- *      mint (treasury fee), burn, swap and liquidity (fee collector);
- *   3. only the swap slice becomes crvUSD, through LiquidationSwap and its Curve pool;
- *   3b. LiquidationSwap reverts when slippage protection is on and get_dy falls below pricePerShare / oracle price
- *       less its tolerance, which is the case when Curve trades below the vault's value;
- *   4. the crvUSD must cover the position's debt; any shortfall is withdrawn from the LendingPool with the pool's
- *      rTokens, so stability pool depositors pay it, and the call reverts (InsufficientBalance) if they hold too few.
+ *      mint (treasury), burn, swap and liquidity (fee collector);
+ *   3. the swap slice is sold on Curve through LiquidationSwap, whose floor is the vault's NAV less a tolerance;
+ *   4. the reserve asset the pool then holds (swap proceeds plus whatever it held before) repays the debt; a shortfall
+ *      is drawn from the pool's rTokens through the LendingPool, and the call reverts (InsufficientBalance) if too few.
+ *
+ * The plan sizes the swap on Curve's get_dy and values every other leg at NAV. Any gap between the swap and the debt
+ * is reserve asset the Treasury sends to the pool beforehand, and the unsold vault tokens go to the Treasury for it.
  */
 const ethers_1 = require("ethers");
 const contracts_1 = require("../../utils/contracts");
 const artifacts_1 = require("../../utils/artifacts");
 const getAdapters_1 = __importDefault(require("../rwaVault/getAdapters"));
 const getParameters_1 = __importDefault(require("../lendingPool/getParameters"));
+const getState_1 = __importDefault(require("../../contracts/crvUSDToUSDOracle/getState"));
 const BPS = BigInt(10_000);
 const WAD = BigInt(10) ** BigInt(18);
 const ZERO = BigInt(0);
+/** Curve quotes its fee on a 1e10 scale. */
+const CURVE_FEE_PER_BPS = BigInt(10) ** BigInt(6);
+const LIQUIDITY_FEE_TYPE = ethers_1.ethers.id("RWA_INDEX_TOKEN_LIQUIDITY_REWARDS");
 const SWAP_ABI = [
     "function liquidityPool() view returns (address)",
-    "function swapToken() view returns (address)",
     "function iIn() view returns (uint256)",
     "function iOut() view returns (uint256)",
     "function enableSlippageProtection() view returns (bool)",
     "function slippageProtectionBps() view returns (uint256)",
     "function crvusdToUSDOracle() view returns (address)",
+    "function owner() view returns (address)",
 ];
-const CURVE_ABI = ["function get_dy(uint256 i, uint256 j, uint256 dx) view returns (uint256)", "function balances(uint256 i) view returns (uint256)"];
+const CURVE_ABI = ["function get_dy(uint256 i, uint256 j, uint256 dx) view returns (uint256)", "function balances(uint256 i) view returns (uint256)", "function fee() view returns (uint256)"];
 const VAULT_ABI = ["function underlyingVaultToken() view returns (address)", "function previewDeposit(uint256 assetAmount) view returns (uint256)", "function pricePerShare() view returns (uint256)"];
 const VAULT_ADAPTER_ABI = ["function getAssetToken() view returns (address)", "function getAssetValue(bytes data) view returns (uint256)"];
 const ADAPTER_ABI = [
@@ -47,64 +53,103 @@ const ADAPTER_ABI = [
     "function balanceOf(address user) view returns (uint256)",
     "function getDepositedTokens(address user) view returns (uint256[])",
 ];
-const ERC20_ABI = ["function balanceOf(address) view returns (uint256)"];
+const ERC20_ABI = ["function balanceOf(address) view returns (uint256)", "function totalSupply() view returns (uint256)", "function symbol() view returns (string)"];
+const YIELD_VAULT_ABI = ["function maxWithdraw(address owner, uint256 maxLoss, address[] strategies) view returns (uint256)"];
+const TREASURY_ABI = ["function isTokenSupported(address) view returns (bool)"];
 exports.SPLIT_KEYS = ["mintBps", "burnBps", "swapBps", "liquidityBps"];
 const splitTotal = (s) => s.mintBps + s.burnBps + s.swapBps + s.liquidityBps;
 exports.splitTotal = splitTotal;
 const sameSplit = (a, b) => exports.SPLIT_KEYS.every((k) => a[k] === b[k]);
 exports.sameSplit = sameSplit;
+exports.DEFAULT_PLAN_PARAMS = { burnBps: BigInt(250), treasuryBps: BigInt(250), liquidityCapBps: BigInt(1500), impactCapBps: BigInt(100), toleranceCeilingBps: BigInt(500), toleranceCushionBps: BigInt(10), marginBps: BigInt(100) };
 const contract = (address, abi, provider) => new ethers_1.ethers.Contract(address, abi, provider);
 const decodeAmount = (data) => ethers_1.ethers.AbiCoder.defaultAbiCoder().decode(["uint256"], data)[0];
-/** Reads the stability pool's liquidation route, split, balances and the LendingPool grace period. */
+const min = (...values) => values.reduce((a, b) => (a < b ? a : b));
+const ceilDiv = (a, b) => (a + b - BigInt(1)) / b;
+/** Reads the stability pool's liquidation route, balances, Curve, NAV, floor and leg prerequisites at one block. */
 async function readLiquidationContext(chainId, provider) {
     const stabilityPool = (0, contracts_1.getContractAddress)(chainId, "stabilitypool");
+    const lendingPool = (0, contracts_1.getContractAddress)(chainId, "lendingpool");
     const sp = contract(stabilityPool, (0, artifacts_1.getABI)("stabilitypool"), provider);
-    const [liquidationSwap, rwaVault, split, rToken, params] = await Promise.all([
+    const [liquidationSwap, rwaVault, split, rToken, deToken, reserveAsset, treasury, feeCollector, params, yieldVault, reserve] = await Promise.all([
         sp.liquidationSwap(),
         sp.rwaVault(),
         sp.liquidationSplit(),
         sp.rToken(),
+        sp.deToken(),
+        sp.crvUSDToken(),
+        sp.treasury(),
+        sp.feeCollector(),
         (0, getParameters_1.default)(chainId, provider),
+        contract(lendingPool, (0, artifacts_1.getABI)("lendingpool"), provider).vault(),
+        contract(lendingPool, (0, artifacts_1.getABI)("lendingpool"), provider).reserve(),
     ]);
     if (liquidationSwap === ethers_1.ethers.ZeroAddress)
         throw new Error("The stability pool has no LiquidationSwap set, so the swap leg reverts.");
     const swap = contract(liquidationSwap, SWAP_ABI, provider);
     const vault = contract(rwaVault, VAULT_ABI, provider);
-    const [liquidityPool, iIn, iOut, vaultToken, protect] = await Promise.all([
+    const [liquidityPool, iIn, iOut, vaultToken, enabled, bps, owner, oracle, pricePerShare] = await Promise.all([
         swap.liquidityPool(),
         swap.iIn(),
         swap.iOut(),
         vault.underlyingVaultToken(),
         swap.enableSlippageProtection(),
+        swap.slippageProtectionBps(),
+        swap.owner(),
+        swap.crvusdToUSDOracle(),
+        vault.pricePerShare(),
     ]);
-    const slippage = protect
-        ? await Promise.all([
-            swap.slippageProtectionBps(),
-            vault.pricePerShare(),
-            swap.crvusdToUSDOracle().then((o) => contract(o, ["function getPrice() view returns (uint256)"], provider).getPrice()),
-        ]).then(([bps, pricePerShare, oraclePrice]) => ({ bps, pricePerShare, oraclePrice }))
-        : null;
     if (liquidityPool === ethers_1.ethers.ZeroAddress)
         throw new Error("LiquidationSwap has no Curve pool set, so the swap leg reverts.");
-    const [vaultSymbol, poolVaultTokens, rTokens] = await Promise.all([
-        contract(vaultToken, ["function symbol() view returns (string)"], provider).symbol().catch(() => "vault token"),
-        contract(vaultToken, ERC20_ABI, provider).balanceOf(stabilityPool),
-        contract(rToken, ERC20_ABI, provider).balanceOf(stabilityPool),
+    const curve = contract(liquidityPool, CURVE_ABI, provider);
+    const erc20 = (token) => contract(token, ERC20_ABI, provider);
+    const fc = feeCollector === ethers_1.ethers.ZeroAddress ? null : contract(feeCollector, (0, artifacts_1.getABI)("feecollector"), provider);
+    const [vaultSymbol, poolVaultTokens, vaultTokenSupply, rTokens, poolReserve, deTokenSupply, buffer, vaultWithdrawable, spot, depth, curveFee, oraclePrice, oracleState, fcPaused, feeType, treasurySupportsVaultToken] = await Promise.all([
+        erc20(vaultToken).symbol().catch(() => "vault token"),
+        erc20(vaultToken).balanceOf(stabilityPool),
+        erc20(vaultToken).totalSupply(),
+        erc20(rToken).balanceOf(stabilityPool),
+        erc20(reserveAsset).balanceOf(stabilityPool),
+        erc20(deToken).totalSupply(),
+        erc20(reserveAsset).balanceOf(rToken),
+        yieldVault === ethers_1.ethers.ZeroAddress ? ZERO : contract(yieldVault, YIELD_VAULT_ABI, provider).maxWithdraw(lendingPool, 0, []).catch(() => null),
+        curve.get_dy(iIn, iOut, WAD),
+        curve.balances(iOut),
+        curve.fee(),
+        contract(oracle, ["function getPrice() view returns (uint256)"], provider).getPrice(),
+        (0, getState_1.default)(chainId, provider, oracle).catch(() => null),
+        fc ? fc.paused() : false,
+        fc ? fc.getFeeType(LIQUIDITY_FEE_TYPE) : null,
+        treasury === ethers_1.ethers.ZeroAddress ? false : contract(treasury, TREASURY_ABI, provider).isTokenSupported(vaultToken),
     ]);
     return {
         stabilityPool,
+        lendingPool,
         liquidationSwap,
         liquidityPool,
         rwaVault,
+        treasury,
+        feeCollector,
         vaultToken,
         vaultSymbol,
+        reserveAsset,
+        rToken,
         iIn,
         iOut,
         split: { mintBps: split[0], burnBps: split[1], swapBps: split[2], liquidityBps: split[3] },
         poolVaultTokens,
+        poolReserve,
         rTokens,
+        deTokenSupply,
+        idleCash: { buffer, vaultWithdrawable },
+        lendingPoolLiquidity: { total: reserve.totalLiquidity, bufferRatioBps: params.liquidityBufferRatio, minRebalance: params.minVaultRebalanceAmount.value },
+        curve: { spot, depth, feeBps: curveFee / CURVE_FEE_PER_BPS },
+        nav: { pricePerShare, oraclePrice, priceTimestamp: oracleState?.priceTimestamp ?? null },
+        vaultTokenSupply,
+        floor: { enabled, bps, owner },
+        feeCollectorState: { paused: fcPaused, liquidityFeeTypeRegistered: feeType !== null && feeType.feeType !== ethers_1.ethers.ZeroHash },
+        treasurySupportsVaultToken,
         gracePeriod: Number(params.liquidationGracePeriod),
-        slippage,
     };
 }
 /**
@@ -147,13 +192,18 @@ async function findVaultAdapter(chainId, provider, assetToken, vaultToken) {
 async function readLiquidationTarget(chainId, provider, ctx, positionId) {
     const [user, poolAdapter, positionKey] = positionId.split(":");
     const { data, assetType, assetToken } = await readLiquidationData(provider, poolAdapter, user, positionKey);
-    const pool = contract((0, contracts_1.getContractAddress)(chainId, "lendingpool"), (0, artifacts_1.getABI)("lendingpool"), provider);
+    const pool = contract(ctx.lendingPool, (0, artifacts_1.getABI)("lendingpool"), provider);
+    const isVaultToken = assetToken.toLowerCase() === ctx.vaultToken.toLowerCase();
     const [vaultAdapter, collateralValue, debt, position] = await Promise.all([
         findVaultAdapter(chainId, provider, assetToken, ctx.vaultToken),
         contract(poolAdapter, ADAPTER_ABI, provider).getAssetValue(user, data),
         pool.getPositionScaledDebt(poolAdapter, user, data),
         pool.getPosition(poolAdapter, user, data),
     ]);
+    // poolDepositAsset mints from the vault adapter's own valuation, which may use a different oracle than the pool's.
+    const sharesFromCollateral = isVaultToken
+        ? decodeAmount(data)
+        : await contract(ctx.rwaVault, VAULT_ABI, provider).previewDeposit(await contract(vaultAdapter, VAULT_ADAPTER_ABI, provider).getAssetValue(data));
     return {
         poolAdapter: ethers_1.ethers.getAddress(poolAdapter),
         vaultAdapter,
@@ -161,137 +211,160 @@ async function readLiquidationTarget(chainId, provider, ctx, positionId) {
         data,
         assetType,
         assetToken,
-        isVaultToken: assetToken.toLowerCase() === ctx.vaultToken.toLowerCase(),
+        isVaultToken,
         collateralValue,
+        sharesFromCollateral,
         debt,
         isUnderLiquidation: position.isUnderLiquidation,
         isInsured: position.isInsured,
         liquidationStartTime: Number(position.liquidationStartTime),
     };
 }
-async function quoteDy(provider, ctx, amount) {
-    if (amount <= ZERO)
-        return ZERO;
-    return contract(ctx.liquidityPool, CURVE_ABI, provider).get_dy(ctx.iIn, ctx.iOut, amount).catch(() => null);
+/** get_dy on the context's Curve pool. */
+const curveQuote = (provider, ctx) => (amount) => amount <= ZERO ? Promise.resolve(ZERO) : contract(ctx.liquidityPool, CURVE_ABI, provider).get_dy(ctx.iIn, ctx.iOut, amount).catch(() => null);
+exports.curveQuote = curveQuote;
+/** Reserve asset that `shares` vault tokens are worth at NAV, as LiquidationSwap computes its expected output. */
+const valueAtNav = (ctx, shares) => (ctx.nav.pricePerShare * shares) / ctx.nav.oraclePrice;
+exports.valueAtNav = valueAtNav;
+/** Vault tokens worth `value` of reserve asset at NAV, rounded up. */
+const sharesAtNav = (ctx, value) => ceilDiv(value * ctx.nav.oraclePrice, ctx.nav.pricePerShare);
+exports.sharesAtNav = sharesAtNav;
+/**
+ * The floor tolerance a swap of `amount` returning `out` needs: how far `out` falls below NAV, in bps, rounded up.
+ * The proxy burns the burn leg before it swaps, which lifts the vault's price per share by the burned share of the
+ * supply, so the floor LiquidationSwap applies is computed on that higher NAV; `burned` accounts for it.
+ */
+function toleranceNeeded(ctx, amount, out, burned = ZERO) {
+    const supplyAfter = ctx.vaultTokenSupply - burned;
+    const expected = supplyAfter > ZERO && burned > ZERO ? ((0, exports.valueAtNav)(ctx, amount) * ctx.vaultTokenSupply) / supplyAfter : (0, exports.valueAtNav)(ctx, amount);
+    return expected <= out || expected === ZERO ? ZERO : ceilDiv((expected - out) * BPS, expected);
 }
-/** Prices the liquidation with `split`, using the deployed Curve pool's get_dy rather than the vault's oracle price. */
-async function quoteLiquidation(provider, ctx, target, split) {
-    // poolDepositAsset mints from the vault adapter's own valuation, which may use a different oracle than the pool's.
-    const sharesFromCollateral = target.isVaultToken
-        ? decodeAmount(target.data)
-        : await contract(ctx.rwaVault, VAULT_ABI, provider).previewDeposit(await contract(target.vaultAdapter, VAULT_ADAPTER_ABI, provider).getAssetValue(target.data));
-    const totalVaultTokens = sharesFromCollateral + ctx.poolVaultTokens;
-    const swapAmount = (totalVaultTokens * split.swapBps) / BPS;
-    const [swapOut, maxSwapOut, spotOut, poolReserveOut] = await Promise.all([
-        quoteDy(provider, ctx, swapAmount),
-        quoteDy(provider, ctx, totalVaultTokens),
-        quoteDy(provider, ctx, WAD),
-        contract(ctx.liquidityPool, CURVE_ABI, provider).balances(ctx.iOut).catch(() => null),
-    ]);
-    let priceImpactBps = null;
-    if (swapOut !== null && spotOut && swapAmount > ZERO) {
-        const realised = (swapOut * WAD) / swapAmount;
-        priceImpactBps = realised >= spotOut ? ZERO : ((spotOut - realised) * BPS) / spotOut;
-    }
-    return {
-        split,
-        sharesFromCollateral,
-        totalVaultTokens,
-        swapAmount,
-        swapOut,
-        minSwapOut: ctx.slippage && swapAmount > ZERO ? ((ctx.slippage.pricePerShare * swapAmount) / ctx.slippage.oraclePrice) * (BPS - ctx.slippage.bps) / BPS : null,
-        shortfall: swapOut === null ? target.debt : swapOut >= target.debt ? ZERO : target.debt - swapOut,
-        coversDebt: swapOut !== null && swapOut >= target.debt,
-        badDebt: target.collateralValue < target.debt ? target.debt - target.collateralValue : ZERO,
-        maxSwapOut,
-        priceImpactBps,
-        poolReserveOut,
-    };
+/** How far the realised rate of a swap falls below Curve's spot rate, in bps. */
+function priceImpact(ctx, amount, out) {
+    if (amount === ZERO || ctx.curve.spot === ZERO)
+        return ZERO;
+    const realised = (out * WAD) / amount;
+    return realised >= ctx.curve.spot ? ZERO : ((ctx.curve.spot - realised) * BPS) / ctx.curve.spot;
 }
+const shareOf = (total, bps) => (total * bps) / BPS;
 /**
- * The smallest swap share whose get_dy still covers the debt plus `bufferBps`, with the rest given back to mint,
- * burn and liquidity in their current proportion. get_dy grows with dx, so a binary search over BPS is sound.
+ * Binary search over the swap share in bps of `total`, which is exact because the proxy computes the swap amount the
+ * same way. `holds` must be monotone in the share: true up to some share for "largest", true from some share on for
+ * "smallest". A reverted quote counts as not holding. Returns the share, or null when no share holds.
  */
-async function suggestSplit(provider, ctx, target, quote, bufferBps = BigInt(100)) {
-    if (quote.totalVaultTokens <= ZERO)
-        return null;
-    const required = (target.debt * (BPS + bufferBps)) / BPS;
-    const spread = (swapBps, projectedOut, bestEffort) => {
-        const rest = BPS - swapBps;
-        const others = ctx.split.mintBps + ctx.split.burnBps + ctx.split.liquidityBps;
-        const mintBps = others === ZERO ? ZERO : (rest * ctx.split.mintBps) / others;
-        const burnBps = others === ZERO ? ZERO : (rest * ctx.split.burnBps) / others;
-        return { mintBps, burnBps, swapBps, liquidityBps: rest - mintBps - burnBps, projectedOut, bestEffort };
+async function searchShare(total, quote, holds, want) {
+    const test = async (bps) => {
+        const amount = shareOf(total, bps);
+        const out = await quote(amount);
+        return out !== null && holds(amount, out);
     };
-    const full = quote.maxSwapOut ?? (await quoteDy(provider, ctx, quote.totalVaultTokens));
-    if (full === null)
+    if (want === "largest") {
+        if (!(await test(ZERO)))
+            return null;
+        let low = ZERO;
+        let high = BPS;
+        while (low < high) {
+            const mid = (low + high + BigInt(1)) / BigInt(2);
+            if (await test(mid))
+                low = mid;
+            else
+                high = mid - BigInt(1);
+        }
+        return low;
+    }
+    if (!(await test(BPS)))
         return null;
-    if (full < required)
-        return spread(BPS, full, true);
     let low = ZERO;
     let high = BPS;
-    let best = full;
     while (low < high) {
         const mid = (low + high) / BigInt(2);
-        const out = await quoteDy(provider, ctx, (quote.totalVaultTokens * mid) / BPS);
-        if (out !== null && out >= required) {
+        if (await test(mid))
             high = mid;
-            best = out;
-        }
-        else {
+        else
             low = mid + BigInt(1);
-        }
     }
-    return spread(low, best, false);
+    return low;
+}
+/** The largest swap share (bps) whose output clears the floor at `toleranceBps` once `burned` vault tokens are gone; the whole balance when the floor is off. */
+async function largestClearingFloor(ctx, quote, total, toleranceBps, burned = ZERO) {
+    if (!ctx.floor.enabled)
+        return BPS;
+    return (await searchShare(total, quote, (amount, out) => toleranceNeeded(ctx, amount, out, burned) <= toleranceBps, "largest")) ?? ZERO;
 }
-/** minSharesOut for the RWAVault deposit: previewDeposit less `slippageBps`. Zero when nothing is deposited. */
-const minSharesOut = (target, quote, slippageBps) => (target.isVaultToken ? ZERO : (quote.sharesFromCollateral * (BPS - slippageBps)) / BPS);
-exports.minSharesOut = minSharesOut;
-// StabilityPoolStorage is inherited first and the OpenZeppelin parents use namespaced storage, so liquidationSplit
-// takes slots 10 to 13. Checked against the live split before it is relied on.
-const SPLIT_SLOT = 10;
 /**
- * Simulates liquidateBorrower from `sender` with the split overridden in storage (an eth_call state override), so a
- * split change in the same batch is simulated rather than only checked. Returns null when the RPC or the storage
- * layout cannot be used; otherwise the revert reason, or "" when it succeeds.
+ * Sizes the swap, derives the split and says what the Treasury must send. `quote` is Curve's get_dy, so a test can
+ * pass a synthetic curve. In "otc" mode nothing is swapped and the Treasury funds the whole uncovered debt.
  */
-async function simulateWithSplit(provider, ctx, sender, data, split) {
-    const send = provider.send?.bind(provider);
-    if (!send)
-        return null;
-    const slot = (i) => ethers_1.ethers.toBeHex(SPLIT_SLOT + i, 32);
-    try {
-        const live = await Promise.all(exports.SPLIT_KEYS.map((_, i) => provider.getStorage(ctx.stabilityPool, SPLIT_SLOT + i)));
-        if (exports.SPLIT_KEYS.some((k, i) => BigInt(live[i]) !== ctx.split[k]))
-            return null;
-    }
-    catch {
-        return null;
-    }
-    const stateDiff = Object.fromEntries(exports.SPLIT_KEYS.map((k, i) => [slot(i), ethers_1.ethers.toBeHex(split[k], 32)]));
-    try {
-        await send("eth_call", [{ from: sender, to: ctx.stabilityPool, data }, "latest", { [ctx.stabilityPool]: { stateDiff } }]);
-        return "";
-    }
-    catch (error) {
-        if (!ethers_1.ethers.isError(error, "CALL_EXCEPTION"))
-            return null;
-        return (error.data && attemptParse(error.data)) || error.reason || error.shortMessage;
-    }
-}
-function attemptParse(data) {
-    for (const key of ["stabilitypool", "lendingpool"]) {
-        try {
-            const e = new ethers_1.ethers.Interface((0, artifacts_1.getABI)(key)).parseError(data);
-            if (e)
-                return e.name === "Error" ? String(e.args[0]) : e.name;
-        }
-        catch { }
-    }
-    try {
-        return ethers_1.ethers.AbiCoder.defaultAbiCoder().decode(["string"], ethers_1.ethers.dataSlice(data, 4))[0];
+async function planLiquidation(ctx, target, quote, params = exports.DEFAULT_PLAN_PARAMS, mode = "defi") {
+    const total = target.sharesFromCollateral + ctx.poolVaultTokens;
+    const required = (target.debt * (BPS + params.marginBps)) / BPS;
+    const toCover = required > ctx.poolReserve ? required - ctx.poolReserve : ZERO;
+    const floorCap = ctx.floor.enabled ? (params.toleranceCeilingBps > params.toleranceCushionBps ? params.toleranceCeilingBps - params.toleranceCushionBps : ZERO) : BPS;
+    // The burn runs before the swap; the policy burn is close enough to size the floor searches on.
+    const burnEstimate = shareOf(total, min(params.burnBps, BPS));
+    const [underImpact, atCurrent, atCeiling, needed] = total === ZERO ? [ZERO, ZERO, ZERO, ZERO] : await Promise.all([
+        searchShare(total, quote, (amount, out) => priceImpact(ctx, amount, out) <= params.impactCapBps, "largest").then((s) => s ?? ZERO),
+        largestClearingFloor(ctx, quote, total, ctx.floor.bps, burnEstimate),
+        largestClearingFloor(ctx, quote, total, floorCap, burnEstimate),
+        toCover === ZERO ? ZERO : searchShare(total, quote, (_, out) => out >= toCover, "smallest"),
+    ]);
+    let swapBps;
+    let bound;
+    if (mode === "otc") {
+        swapBps = ZERO;
+        bound = "mode";
     }
-    catch {
-        return null;
+    else {
+        const wanted = needed ?? BPS;
+        swapBps = min(wanted, underImpact, atCeiling);
+        bound = swapBps === wanted ? (needed === null ? "balance" : "debt") : swapBps === underImpact ? "impact" : "floor";
     }
+    const swapAmount = shareOf(total, swapBps);
+    const swapOut = swapAmount === ZERO ? ZERO : ((await quote(swapAmount)) ?? ZERO);
+    const gap = toCover > swapOut ? toCover - swapOut : ZERO;
+    const liquidityDisabled = ctx.feeCollectorState.paused || !ctx.feeCollectorState.liquidityFeeTypeRegistered;
+    const burnBps = min(params.burnBps, BPS - swapBps);
+    const treasuryBaseBps = min(params.treasuryBps, BPS - swapBps - burnBps);
+    const remainderBps = BPS - swapBps - burnBps - treasuryBaseBps;
+    const gapBps = gap === ZERO || total === ZERO ? ZERO : ceilDiv((0, exports.sharesAtNav)(ctx, gap) * BPS, total);
+    const treasuryGapBps = min(gapBps, remainderBps);
+    const leftoverBps = remainderBps - treasuryGapBps;
+    const liquidityBps = liquidityDisabled ? ZERO : gap > ZERO ? min(leftoverBps, params.liquidityCapBps) : leftoverBps;
+    const split = { mintBps: treasuryBaseBps + treasuryGapBps + leftoverBps - liquidityBps, burnBps, swapBps, liquidityBps };
+    const legs = { swap: swapAmount, burn: shareOf(total, split.burnBps), treasury: shareOf(total, split.mintBps), liquidity: shareOf(total, split.liquidityBps) };
+    const needsBps = toleranceNeeded(ctx, swapAmount, swapOut, legs.burn);
+    const raise = ctx.floor.enabled && swapAmount > ZERO && needsBps > ctx.floor.bps;
+    const treasuryValue = (0, exports.valueAtNav)(ctx, legs.treasury);
+    const idle = ctx.idleCash.vaultWithdrawable === null ? null : ctx.idleCash.buffer + ctx.idleCash.vaultWithdrawable;
+    const wanted = ceilDiv((ctx.lendingPoolLiquidity.total + target.debt) * ctx.lendingPoolLiquidity.bufferRatioBps, BPS);
+    const shortage = wanted > ctx.idleCash.buffer ? wanted - ctx.idleCash.buffer : ZERO;
+    const rebalances = shortage >= ctx.lendingPoolLiquidity.minRebalance && shortage > ZERO;
+    const rebalanceFeasible = !rebalances ? true : ctx.idleCash.vaultWithdrawable === null ? null : shortage <= ctx.idleCash.vaultWithdrawable;
+    return {
+        mode,
+        params,
+        totalVaultTokens: total,
+        required,
+        toCover,
+        swapAmount,
+        swapOut,
+        priceImpactBps: priceImpact(ctx, swapAmount, swapOut),
+        toleranceNeededBps: needsBps,
+        proposedToleranceBps: raise ? min(needsBps + params.toleranceCushionBps, params.toleranceCeilingBps > needsBps ? params.toleranceCeilingBps : needsBps) : null,
+        bound,
+        ceilings: { atCurrent: shareOf(total, atCurrent), atCeiling: shareOf(total, atCeiling), underImpact: shareOf(total, underImpact) },
+        split,
+        legs,
+        gap,
+        treasuryValue,
+        treasuryNet: treasuryValue - gap,
+        liquidityCapped: !liquidityDisabled && gap > ZERO && leftoverBps > params.liquidityCapBps,
+        liquidityDisabled,
+        route: gap === ZERO ? "covered" : swapAmount > ZERO ? "partial" : "otc",
+        absorb: { feasible: idle === null ? null : ctx.rTokens >= gap && idle >= gap, rTokensAfter: ctx.rTokens - gap, inject: idle !== null && idle < gap ? gap - idle : ZERO },
+        rebalance: { shortage, feasible: rebalanceFeasible, inject: rebalanceFeasible === false ? shortage : ZERO },
+    };
 }
+/** minSharesOut for the RWAVault deposit: previewDeposit less `slippageBps`. Zero when nothing is deposited. */
+const minSharesOut = (target, slippageBps) => (target.isVaultToken ? ZERO : (target.sharesFromCollateral * (BPS - slippageBps)) / BPS);
+exports.minSharesOut = minSharesOut;

package/dist/types/RPCLibrary.d.ts

@@ -140,7 +140,7 @@ import getRoles from "./contracts/getRoles";
 import getTreasuryState from "./contracts/treasury/getState";
 import getComplianceStatuses from "./contracts/complianceRegistry/getStatuses";
 import getStabilityPoolAdminState from "./pools/stabilityPool/getAdminState";
-import { readLiquidationContext, readLiquidationTarget, quoteLiquidation, suggestSplit, simulateWithSplit, minSharesOut } from "./pools/stabilityPool/liquidation";
+import { readLiquidationContext, readLiquidationTarget, planLiquidation, curveQuote, largestClearingFloor, toleranceNeeded, priceImpact, valueAtNav, sharesAtNav, minSharesOut, DEFAULT_PLAN_PARAMS } from "./pools/stabilityPool/liquidation";
 import { getEmissionSchedule, getSchedulePosition, getEmissionPerSecondForWeek, getMintingWeekForTimestamp } from "./minter/emissionSchedule";
 import getRWAVaultRegisteredAdapters from "./pools/rwaVault/getRegisteredAdapters";
 import getRWAVaultSeedStatus from "./pools/rwaVault/getSeedStatus";
@@ -707,10 +707,15 @@ declare class RPCLibrary {
             liquidation: {
                 getContext: typeof readLiquidationContext;
                 getTarget: typeof readLiquidationTarget;
-                quote: typeof quoteLiquidation;
-                suggestSplit: typeof suggestSplit;
-                simulateWithSplit: typeof simulateWithSplit;
+                plan: typeof planLiquidation;
+                curveQuote: typeof curveQuote;
+                largestClearingFloor: typeof largestClearingFloor;
+                toleranceNeeded: typeof toleranceNeeded;
+                priceImpact: typeof priceImpact;
+                valueAtNav: typeof valueAtNav;
+                sharesAtNav: typeof sharesAtNav;
                 minSharesOut: typeof minSharesOut;
+                DEFAULT_PLAN_PARAMS: typeof DEFAULT_PLAN_PARAMS;
             };
         };
         lendingPool: {

package/dist/types/contracts/governance/gauge/getUserGaugeState.d.ts

@@ -7,8 +7,6 @@ export interface UserGaugeTokenState {
     symbol?: string;
     /** From the token registry, or read from the token when the registry does not list it. */
     decimals: number;
-    /** Wallet balance, in this token's base units. */
-    balance: TokenAmount;
     /** Allowance to `spender`, in this token's base units. */
     allowance: TokenAmount;
     /** The contract that pulls the token: the gauge for the staking token, the wrapper for the underlying. */
@@ -23,8 +21,9 @@ export interface UserGaugeState {
     underlying: UserGaugeTokenState | null;
 }
 /**
- * What a wallet needs to stake in, wrap for, or unstake from a gauge: its stake, its balance of the staking token and its
- * allowance to the gauge, and for a wrapped gauge its balance of the underlying and allowance to the wrapper.
+ * What a wallet needs to stake in, wrap for, or unstake from a gauge: its stake, its allowance of the staking token to the
+ * gauge, and for a wrapped gauge its allowance of the underlying to the wrapper. Read the wallet's token balances with
+ * `wallet.assets.getBalance`.
  *
  * @param chainId - The chain/network to use.
  * @param gaugeAddressOrId - Address of the gauge contract or its config ID.

package/dist/types/contracts/psm/getVaultInfo.d.ts

@@ -1,8 +1,8 @@
 import { Provider } from "ethers";
 import { ChainId } from "../../configs/chains";
 import { TokenAmount, ScaledValue } from "../../utils/amount";
+/** A wallet's open redeem request and allowances to the vault. Token balances, shares included, come from `wallet.assets.getBalance`. */
 export interface PsmVaultUserInfo {
-    shareBalance: TokenAmount;
     redeemRequest: {
         shares: TokenAmount;
         exitTime: number;