@gearbox-protocol/sdk 16.0.0-next.7 → 16.0.0-next.9

package/dist/cjs/onchain/accounts/index.js

@@ -6,7 +6,7 @@ const require_onchain_accounts_credit_account_compressor_CreditAccountCompressor
 const require_onchain_accounts_credit_account_compressor_CreditAccountCompressor = require("./credit-account-compressor/CreditAccountCompressor.js");
 require("./credit-account-compressor/index.js");
 const require_onchain_accounts_CreditAccountsServiceV310 = require("./CreditAccountsServiceV310.js");
-const require_onchain_accounts_intents_types = require("./intents/types.js");
+const require_onchain_accounts_intents_refusal = require("./intents/refusal.js");
 const require_onchain_accounts_intents_utils_credit_account_slice = require("./intents/utils/credit-account-slice.js");
 const require_onchain_accounts_intents_index = require("./intents/index.js");
 const require_onchain_accounts_liquidations_constants = require("./liquidations/constants.js");
@@ -34,7 +34,7 @@ exports.CreditAccountOperationsService = require_onchain_accounts_intents_index.
 exports.CreditAccountsServiceV310 = require_onchain_accounts_CreditAccountsServiceV310.CreditAccountsServiceV310;
 exports.DELAYED_INTENT_TYPES = require_onchain_accounts_withdrawal_compressor_intent_codec.DELAYED_INTENT_TYPES;
 exports.DELAYED_INTENT_VERSION = require_onchain_accounts_withdrawal_compressor_intent_codec.DELAYED_INTENT_VERSION;
-exports.IntentPreviewError = require_onchain_accounts_intents_types.IntentPreviewError;
+exports.IntentPreviewError = require_onchain_accounts_intents_refusal.IntentPreviewError;
 exports.InvalidDelayedIntentError = require_onchain_accounts_withdrawal_compressor_errors.InvalidDelayedIntentError;
 exports.LIQUIDATION_APPROVAL_BUFFER = require_onchain_accounts_liquidations_constants.LIQUIDATION_APPROVAL_BUFFER;
 exports.LIQUIDATION_COMPRESSOR_V313_ADDRESS = require_onchain_accounts_liquidations_constants.LIQUIDATION_COMPRESSOR_V313_ADDRESS;
@@ -52,6 +52,7 @@ exports.encodeDelayedIntent = require_onchain_accounts_withdrawal_compressor_int
 exports.fetchCreditAccountSlice = require_onchain_accounts_intents_utils_credit_account_slice.fetchCreditAccountSlice;
 exports.getWithdrawalCompressorAddress = require_onchain_accounts_withdrawal_compressor_addresses.getWithdrawalCompressorAddress;
 exports.iCreditAccountAbi = require_onchain_accounts_withdrawal_compressor_AbstractWithdrawalCompressorContract.iCreditAccountAbi;
+exports.refuse = require_onchain_accounts_intents_refusal.refuse;
 exports.toClaimableWithdrawal = require_onchain_accounts_withdrawal_compressor_AbstractWithdrawalCompressorContract.toClaimableWithdrawal;
 exports.toCreditAccountSlice = require_onchain_accounts_intents_utils_credit_account_slice.toCreditAccountSlice;
 exports.toPendingWithdrawal = require_onchain_accounts_withdrawal_compressor_AbstractWithdrawalCompressorContract.toPendingWithdrawal;

package/dist/cjs/onchain/accounts/intents/guards.js

@@ -1,7 +1,7 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-require("../../constants/math.js");
+const require_onchain_constants_math = require("../../constants/math.js");
 require("../../constants/index.js");
-const require_onchain_accounts_intents_types = require("./types.js");
+const require_onchain_accounts_intents_refusal = require("./refusal.js");
 const require_onchain_accounts_intents_utils_common = require("./utils/common.js");
 const require_onchain_accounts_intents_utils_pick_token = require("./utils/pick-token.js");
 //#region src/onchain/accounts/intents/guards.ts
@@ -13,14 +13,23 @@ const require_onchain_accounts_intents_utils_pick_token = require("./utils/pick-
 * pool has run out of what it lends. On-chain those come back as a reverted
 * multicall with a selector no form can explain, so they are read from the
 * loaded market and reported as refusals instead.
+*
+* Every guard here refuses something the market decides rather than something
+* the arithmetic cannot do, which is why all six of their reasons are
+* `blocking`: the walk that hit one still reached an end state, and a caller
+* gets that state alongside the refusal.
 */
 /**
 * The facade takes no multicall while it is paused or past its expiration, so
 * every intent the engine previews would revert on arrival.
 */
 function assertMarketOperable(suite) {
-	if (suite.isPaused) throw new require_onchain_accounts_intents_types.IntentPreviewError("marketPaused", `${suite.creditManager.address} is paused`);
-	if (suite.isExpired) throw new require_onchain_accounts_intents_types.IntentPreviewError("marketExpired", `${suite.creditManager.address} expired at ${suite.creditFacade.expirationDate}`);
+	const creditManager = suite.creditManager.address;
+	if (suite.isPaused) throw new require_onchain_accounts_intents_refusal.IntentPreviewError("marketPaused", { creditManager }, `${creditManager} is paused`);
+	if (suite.isExpired) throw new require_onchain_accounts_intents_refusal.IntentPreviewError("marketExpired", {
+		creditManager,
+		expirationDate: suite.creditFacade.expirationDate
+	}, `${creditManager} expired at ${suite.creditFacade.expirationDate}`);
 }
 /**
 * What the pool will hand this manager in one transaction: the tightest of its
@@ -42,7 +51,19 @@ function borrowable(suite) {
 /** The pool has to be able to lend what the plan means to draw. */
 function assertCanBorrow(suite, amount) {
 	const limit = borrowable(suite);
-	if (amount > limit) throw new require_onchain_accounts_intents_types.IntentPreviewError("insufficientPoolLiquidity", `borrow: ${amount} exceeds what the pool can lend now (${limit})`);
+	if (amount > limit) {
+		const token = suite.market.pool.underlying;
+		throw new require_onchain_accounts_intents_refusal.IntentPreviewError("insufficientPoolLiquidity", {
+			requested: {
+				token,
+				balance: amount
+			},
+			available: {
+				token,
+				balance: limit
+			}
+		}, `borrow: ${amount} exceeds what the pool can lend now (${limit})`);
+	}
 }
 /**
 * What the account is allowed to end up holding more of than it started with.
@@ -62,9 +83,16 @@ function assertGrowthAllowed(args) {
 	const underlying = market.pool.underlying;
 	for (const { token, balance } of after) {
 		if (balance <= (before.find((a) => require_onchain_accounts_intents_utils_common.eq(a.token, token))?.balance ?? 0n)) continue;
-		if (forbidden.some((f) => require_onchain_accounts_intents_utils_common.eq(f, token))) throw new require_onchain_accounts_intents_types.IntentPreviewError("forbiddenToken", `${token} is forbidden in this market and the plan buys more of it`);
+		if (forbidden.some((f) => require_onchain_accounts_intents_utils_common.eq(f, token))) throw new require_onchain_accounts_intents_refusal.IntentPreviewError("forbiddenToken", { token }, `${token} is forbidden in this market and the plan buys more of it`);
 		if (require_onchain_accounts_intents_utils_common.eq(token, underlying) || require_onchain_accounts_intents_utils_pick_token.isPhantomToken(sdk, token)) continue;
-		if (!market.pool.pqk.hasActiveQuota(token)) throw new require_onchain_accounts_intents_types.IntentPreviewError("quotaLimitReached", `${token} takes no quota in this market, so it counts as no collateral`);
+		if (!market.pool.pqk.hasActiveQuota(token)) throw new require_onchain_accounts_intents_refusal.IntentPreviewError("quotaLimitReached", {
+			token,
+			requested: void 0,
+			available: {
+				token: underlying,
+				balance: 0n
+			}
+		}, `${token} takes no quota in this market, so it counts as no collateral`);
 	}
 }
 /**
@@ -72,10 +100,23 @@ function assertGrowthAllowed(args) {
 * and reverts if the collateral does not cover it, so a plan that lands the
 * account below water is refused here.
 *
-* The bar is the health factor of the state the plan projects: collateral under
-* liquidation thresholds, capped by quota, against the debt. Note that a
-* position already underwater cannot be nursed back one step at a time — the
-* check is on where the transaction ends, not on whether it improved things.
+* The bar is the facade's own `1.0`, because this guard answers one question:
+* would the transaction revert. It is deliberately not `MIN_HF_LIMITED`, and
+* the three bars in this codebase are three different jobs:
+*
+* - here, `1.0` — what the facade enforces, so what a plan must clear to land;
+* - `maxWithdrawCollateral` sizes at `MIN_HF_LIMITED + 2` — a *sizing* helper
+*   leaving headroom, which is not the same as a validity check;
+* - `validateHF` refuses at or below `MIN_HF_LIMITED` — a form's own caution.
+*
+* Raising this one to `MIN_HF_LIMITED` was tried and reverted: it made
+* `maxWithdraw` hand back a ceiling this guard then refused, and it blocked
+* small top-ups of an account sitting in `[1.0, 1.01)` — the very operations
+* that rescue it. A form wanting the stricter bar has `validateHF`.
+*
+* Note that a position already underwater cannot be nursed back one step at a
+* time — the check is on where the transaction ends, not on whether it
+* improved things.
 *
 * @remarks
 * The caller decides the pricing the factor was computed at: main prices, or
@@ -83,20 +124,36 @@ function assertGrowthAllowed(args) {
 * whose reserve feed the SDK cannot read keeps its main price, so a plan can
 * still be refused on-chain after passing here.
 */
-function assertCollateralised(healthFactorBps) {
-	if (healthFactorBps < Number(10000n)) throw new require_onchain_accounts_intents_types.IntentPreviewError("insufficientCollateral", `the account would end at a health factor of ${healthFactorBps}, below 1.0`);
+function assertCollateralised(healthFactorBps, safePrices) {
+	const required = Number(require_onchain_constants_math.PERCENTAGE_FACTOR);
+	if (healthFactorBps < required) throw new require_onchain_accounts_intents_refusal.IntentPreviewError("insufficientCollateral", {
+		healthFactor: healthFactorBps,
+		required,
+		safePrices
+	}, `the account would end at a health factor of ${healthFactorBps}, below ${required}`);
 }
 /**
 * A quota can only be raised as far as the market still has room for: past the
 * token's limit the keeper takes nothing more, whoever is asking.
 */
 function assertQuotaHeadroom(market, increases) {
+	const underlying = market.pool.underlying;
 	for (const { token, balance } of increases) {
 		if (balance <= 0n) continue;
 		const quota = market.pool.pqk.quotas.get(token);
 		if (!quota) continue;
 		const left = quota.limit - quota.totalQuoted;
-		if (balance > left) throw new require_onchain_accounts_intents_types.IntentPreviewError("quotaLimitReached", `${token} has ${left} of quota left, the plan needs ${balance}`);
+		if (balance > left) throw new require_onchain_accounts_intents_refusal.IntentPreviewError("quotaLimitReached", {
+			token,
+			requested: {
+				token: underlying,
+				balance
+			},
+			available: {
+				token: underlying,
+				balance: left
+			}
+		}, `${token} has ${left} of quota left, the plan needs ${balance}`);
 	}
 }
 //#endregion

package/dist/cjs/onchain/accounts/intents/index.js

@@ -1,7 +1,7 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_onchain_base_SDKConstruct = require("../../base/SDKConstruct.js");
 const require_common_utils_utils_validation_validate_hf = require("../../../common-utils/utils/validation/validate-hf.js");
-const require_onchain_accounts_intents_types = require("./types.js");
+const require_onchain_accounts_intents_refusal = require("./refusal.js");
 const require_onchain_accounts_intents_guards = require("./guards.js");
 const require_onchain_accounts_intents_math = require("./math.js");
 const require_onchain_accounts_intents_maxWithdrawCollateral = require("./maxWithdrawCollateral.js");
@@ -170,9 +170,11 @@ var CreditAccountOperationsService = class extends require_onchain_base_SDKConst
 		const [instant, delayed] = await Promise.allSettled([this.startIntent(props), this.startDelayedIntent(props)]);
 		const instantRoute = instant.status === "fulfilled" && instant.value.ok ? instant.value : void 0;
 		const delayedRoute = delayed.status === "fulfilled" && delayed.value.ok ? delayed.value : void 0;
+		const instantRefusal = instant.status === "fulfilled" && !instant.value.ok ? instant.value : void 0;
+		const delayedRefusal = delayed.status === "fulfilled" && !delayed.value.ok ? delayed.value : void 0;
 		const refused = {
-			instant: instant.status === "fulfilled" && !instant.value.ok ? instant.value.reason : void 0,
-			delayed: delayed.status === "fulfilled" && !delayed.value.ok ? delayed.value.reason : void 0
+			instant: instantRefusal?.reason,
+			delayed: delayedRefusal?.reason
 		};
 		if (instantRoute || delayedRoute) return {
 			ok: true,
@@ -182,11 +184,10 @@ var CreditAccountOperationsService = class extends require_onchain_base_SDKConst
 		};
 		const failed = [instant, delayed].find((s) => s.status === "rejected");
 		if (failed?.status === "rejected") throw failed.reason;
-		const reason = refused.instant ?? refused.delayed;
-		if (reason === void 0) throw new Error("intentRoutes: a route neither answered nor refused");
+		const chosen = instantRefusal ?? delayedRefusal;
+		if (chosen === void 0) throw new Error("intentRoutes: a route neither answered nor refused");
 		return {
-			ok: false,
-			reason,
+			...chosen,
 			refused
 		};
 	}
@@ -268,14 +269,8 @@ function plain(result) {
 }
 /** Unviable requests are values; anything else is a genuine failure. */
 function asFailure(e) {
-	if (e instanceof require_onchain_accounts_intents_types.IntentPreviewError) return {
-		ok: false,
-		reason: e.reason
-	};
-	if (isUnroutable(e)) return {
-		ok: false,
-		reason: "unsupportedTokenPair"
-	};
+	if (e instanceof require_onchain_accounts_intents_refusal.IntentPreviewError) return require_onchain_accounts_intents_refusal.refuse(e.reason, e.detail);
+	if (isUnroutable(e)) return require_onchain_accounts_intents_refusal.refuse("unsupportedTokenPair", void 0);
 	throw e;
 }
 /**
@@ -292,6 +287,7 @@ function isUnroutable(e) {
 }
 //#endregion
 exports.CreditAccountOperationsService = CreditAccountOperationsService;
-exports.IntentPreviewError = require_onchain_accounts_intents_types.IntentPreviewError;
+exports.IntentPreviewError = require_onchain_accounts_intents_refusal.IntentPreviewError;
 exports.fetchCreditAccountSlice = require_onchain_accounts_intents_utils_credit_account_slice.fetchCreditAccountSlice;
+exports.refuse = require_onchain_accounts_intents_refusal.refuse;
 exports.toCreditAccountSlice = require_onchain_accounts_intents_utils_credit_account_slice.toCreditAccountSlice;

package/dist/cjs/onchain/accounts/intents/math.js

@@ -1,6 +1,7 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_onchain_utils_bigint_math = require("../../utils/bigint-math.js");
 const require_onchain_constants_math = require("../../constants/math.js");
-const require_onchain_accounts_intents_types = require("./types.js");
+const require_onchain_accounts_intents_refusal = require("./refusal.js");
 //#region src/onchain/accounts/intents/math.ts
 /** Debt that realises `leverage` on `collateral`: `D = C · (L − 1)`. */
 function debtForLeverage(collateral, leverage) {
@@ -14,7 +15,7 @@ function debtForLeverage(collateral, leverage) {
 * it, so no rounding is introduced on the way.
 */
 function proportionalDebt(position, collateralDelta) {
-	if (position.collateral <= 0n) throw new require_onchain_accounts_intents_types.IntentPreviewError("insufficientSourceBalance", "cannot preserve leverage on an account with no collateral");
+	if (position.collateral <= 0n) throw new require_onchain_accounts_intents_refusal.IntentPreviewError("insufficientSourceBalance", void 0, "cannot preserve leverage on an account with no collateral");
 	return position.debt * collateralDelta / position.collateral;
 }
 /**
@@ -32,21 +33,37 @@ function maxProportionalWithdrawal(position, band) {
 	if (debt === 0n) return allButLast;
 	const repayable = debt - band.minDebt;
 	if (repayable < 0n) return 0n;
-	const bound = ceilDiv(collateral * (repayable + 1n), debt) - 1n;
+	const bound = require_onchain_utils_bigint_math.BigIntMath.ceilDiv(collateral * (repayable + 1n), debt) - 1n;
 	return bound < allButLast ? bound : allButLast;
 }
-const ceilDiv = (a, b) => (a + b - 1n) / b;
 /** Total leverage cannot drop below 1x — that would be negative debt. */
 function assertLeverageAtLeastOne(leverage) {
-	if (leverage < 100n) throw new require_onchain_accounts_intents_types.IntentPreviewError("leverageOutOfRange", `target leverage ${leverage} is below 1x`);
+	if (leverage < 100n) throw new require_onchain_accounts_intents_refusal.IntentPreviewError("leverageOutOfRange", {
+		requested: leverage,
+		min: require_onchain_constants_math.LEVERAGE_DECIMALS
+	}, `target leverage ${leverage} is below 1x`);
 }
 /**
 * Rejects a debt the facade would revert on: zero is always fine (no loan at
 * all), anything else has to sit inside `[minDebt, maxDebt]`.
 */
-function assertDebtInBand(debt, band) {
-	if (debt > band.maxDebt) throw new require_onchain_accounts_intents_types.IntentPreviewError("debtOutOfRange", `debt ${debt} exceeds maxDebt ${band.maxDebt}`);
-	if (debt > 0n && debt < band.minDebt) throw new require_onchain_accounts_intents_types.IntentPreviewError("debtOutOfRange", `debt ${debt} is below minDebt ${band.minDebt}`);
+function assertDebtInBand(debt, band, underlying) {
+	const detail = {
+		requested: {
+			token: underlying,
+			balance: debt
+		},
+		minDebt: {
+			token: underlying,
+			balance: band.minDebt
+		},
+		maxDebt: {
+			token: underlying,
+			balance: band.maxDebt
+		}
+	};
+	if (debt > band.maxDebt) throw new require_onchain_accounts_intents_refusal.IntentPreviewError("debtOutOfRange", detail, `debt ${debt} exceeds maxDebt ${band.maxDebt}`);
+	if (debt > 0n && debt < band.minDebt) throw new require_onchain_accounts_intents_refusal.IntentPreviewError("debtOutOfRange", detail, `debt ${debt} is below minDebt ${band.minDebt}`);
 }
 //#endregion
 exports.assertDebtInBand = assertDebtInBand;

package/dist/cjs/onchain/accounts/intents/maxWithdrawCollateral.js

@@ -57,8 +57,8 @@ function maxWithdrawCollateral(props) {
 	const targetLt = BigInt(creditManager.liquidationThresholds.get(target.token) ?? 0);
 	const targetUsd = safeUsd(priceOracle, target.token, target.balance);
 	if (targetLt === 0n || !targetUsd) return 0n;
-	const keptUsd = ceilDiv(shortfall, targetLt);
-	const kept = ceilDiv(target.balance * keptUsd, targetUsd);
+	const keptUsd = require_onchain_utils_bigint_math.BigIntMath.ceilDiv(shortfall, targetLt);
+	const kept = require_onchain_utils_bigint_math.BigIntMath.ceilDiv(target.balance * keptUsd, targetUsd);
 	return kept >= target.balance ? 0n : target.balance - kept;
 }
 /** USD value at the main feed, or `undefined` when the token has no price. */
@@ -82,8 +82,5 @@ function safeUsd(oracle, token, amount) {
 		return main;
 	}
 }
-function ceilDiv(a, b) {
-	return (a + b - 1n) / b;
-}
 //#endregion
 exports.maxWithdrawCollateral = maxWithdrawCollateral;

package/dist/cjs/onchain/accounts/intents/open-strategy.js

@@ -1,6 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-require("../../constants/math.js");
-const require_onchain_accounts_intents_types = require("./types.js");
+const require_onchain_accounts_intents_refusal = require("./refusal.js");
 const require_onchain_accounts_intents_utils_convert_amount = require("./utils/convert-amount.js");
 const require_onchain_accounts_intents_guards = require("./guards.js");
 const require_onchain_accounts_intents_math = require("./math.js");
@@ -23,14 +22,14 @@ const NO_ACCOUNT = "0x0000000000000000000000000000000000000000";
 */
 async function previewOpenStrategy(props) {
 	const { sdk, creditManager, collateral, targetToken, leverage, slippage = 0, quotaReserve, leftoverBalances = [] } = props;
-	if (leverage < 100n) throw new require_onchain_accounts_intents_types.IntentPreviewError("leverageOutOfRange", `openStrategy: leverage ${leverage} is below 1x`);
+	require_onchain_accounts_intents_math.assertLeverageAtLeastOne(leverage);
 	const suite = sdk.marketRegister.findCreditManager(creditManager);
 	const market = sdk.marketRegister.findByCreditManager(creditManager);
 	require_onchain_accounts_intents_guards.assertMarketOperable(suite);
 	const underlying = market.pool.underlying.toLowerCase();
 	const convert = require_onchain_accounts_intents_utils_convert_amount.convertAmount(sdk, creditManager);
 	const margin = collateral.reduce((acc, a) => acc + convert(a.token, underlying, a.balance), 0n);
-	if (margin <= 0n) throw new require_onchain_accounts_intents_types.IntentPreviewError("insufficientSourceBalance", "openStrategy: collateral is worth nothing in underlying");
+	if (margin <= 0n) throw new require_onchain_accounts_intents_refusal.IntentPreviewError("insufficientSourceBalance", void 0, "openStrategy: collateral is worth nothing in underlying");
 	const debt = require_onchain_accounts_intents_math.debtForLeverage(margin, leverage);
 	const account = {
 		creditAccount: NO_ACCOUNT,
@@ -42,7 +41,7 @@ async function previewOpenStrategy(props) {
 		accountDebt: 0n,
 		tokens: []
 	};
-	require_onchain_accounts_intents_math.assertDebtInBand(debt, suite.creditFacade);
+	require_onchain_accounts_intents_math.assertDebtInBand(debt, suite.creditFacade, underlying);
 	require_onchain_accounts_intents_guards.assertCanBorrow(suite, debt);
 	const leg = await require_onchain_accounts_intents_utils_router_path.createRouterPaths({
 		sdk,
@@ -91,7 +90,7 @@ async function previewOpenStrategy(props) {
 		timeToLiquidation: sdk.positions.timeToLiquidation(snapshot, projectedPool),
 		liquidationPrice: sdk.positions.liquidationPrice(snapshot)
 	};
-	require_onchain_accounts_intents_guards.assertCollateralised(metrics.healthFactor);
+	require_onchain_accounts_intents_guards.assertCollateralised(metrics.healthFactor, false);
 	return {
 		debt,
 		collateral: margin,

package/dist/cjs/onchain/accounts/intents/plan.js

@@ -1,7 +1,7 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_onchain_constants_math = require("../../constants/math.js");
 require("../../constants/index.js");
-const require_onchain_accounts_intents_types = require("./types.js");
+const require_onchain_accounts_intents_refusal = require("./refusal.js");
 const require_onchain_accounts_intents_utils_common = require("./utils/common.js");
 const require_onchain_accounts_intents_math = require("./math.js");
 //#region src/onchain/accounts/intents/plan.ts
@@ -24,18 +24,27 @@ function planAdjustLeverage(intent, view) {
 	const T = intent.token ?? positionToken(view, "adjustLeverage");
 	if (delta > 0n) return [borrow(delta), convert(U, T, delta)];
 	const shortfall = -delta - view.balanceOf(U);
-	if (shortfall > 0n && require_onchain_accounts_intents_utils_common.eq(T, U)) throw new require_onchain_accounts_intents_types.IntentPreviewError("insufficientSourceBalance", `adjustLeverage: needs ${-delta} underlying, account holds ${view.balanceOf(U)}`);
+	if (shortfall > 0n && require_onchain_accounts_intents_utils_common.eq(T, U)) throw new require_onchain_accounts_intents_refusal.IntentPreviewError("insufficientSourceBalance", {
+		required: {
+			token: U,
+			balance: -delta
+		},
+		held: {
+			token: U,
+			balance: view.balanceOf(U)
+		}
+	}, `adjustLeverage: needs ${-delta} underlying, account holds ${view.balanceOf(U)}`);
 	return [...shortfall > 0n ? [convert(T, U, view.price(U, T, shortfall))] : [], repay(-delta)];
 }
 /** Intents 1.1 / 1.2: collateral grows by `a`, debt grows to match. */
 function planDeposit(intent, view) {
 	assertPositive(intent.amount, "deposit");
 	const U = view.underlying;
-	if (!require_onchain_accounts_intents_utils_common.eq(intent.token, U) && !(view.rwaAsset && require_onchain_accounts_intents_utils_common.eq(intent.token, view.rwaAsset))) throw new require_onchain_accounts_intents_types.IntentPreviewError("unsupportedCollateralToken", `deposit: only ${U}${view.rwaAsset ? ` or ${view.rwaAsset}` : ""} can be deposited, got ${intent.token}`);
+	if (!require_onchain_accounts_intents_utils_common.eq(intent.token, U) && !(view.rwaAsset && require_onchain_accounts_intents_utils_common.eq(intent.token, view.rwaAsset))) throw new require_onchain_accounts_intents_refusal.IntentPreviewError("unsupportedCollateralToken", { token: intent.token }, `deposit: only ${U}${view.rwaAsset ? ` or ${view.rwaAsset}` : ""} can be deposited, got ${intent.token}`);
 	const aU = view.price(intent.token, U, intent.amount);
 	const debtDelta = intent.targetLeverage === void 0 ? require_onchain_accounts_intents_math.proportionalDebt(view, aU) : require_onchain_accounts_intents_math.debtForLeverage(view.collateral + aU, intent.targetLeverage) - view.debt;
-	if (debtDelta < 0n) throw new require_onchain_accounts_intents_types.IntentPreviewError("leverageOutOfRange", `deposit: target leverage ${intent.targetLeverage} would require repaying debt`);
-	require_onchain_accounts_intents_math.assertDebtInBand(view.debt + debtDelta, view.band);
+	if (debtDelta < 0n) throw new require_onchain_accounts_intents_refusal.IntentPreviewError("leverageOutOfRange", void 0, `deposit: target leverage ${intent.targetLeverage} would require repaying debt`);
+	require_onchain_accounts_intents_math.assertDebtInBand(view.debt + debtDelta, view.band, U);
 	const T = intent.positionToken ?? positionToken(view, "deposit");
 	const depositStays = require_onchain_accounts_intents_utils_common.eq(intent.token, T);
 	return [
@@ -62,11 +71,24 @@ function planRepay(intent, view) {
 	assertPositive(intent.amount, "repay");
 	const U = view.underlying;
 	const fundsInU = require_onchain_accounts_intents_utils_common.eq(intent.token, U);
-	if (!fundsInU && !(view.rwaAsset && require_onchain_accounts_intents_utils_common.eq(intent.token, view.rwaAsset))) throw new require_onchain_accounts_intents_types.IntentPreviewError("unsupportedCollateralToken", `repay: only ${U}${view.rwaAsset ? ` or ${view.rwaAsset}` : ""} can be repaid with, got ${intent.token}`);
-	if (view.debt <= 0n) throw new require_onchain_accounts_intents_types.IntentPreviewError("debtOutOfRange", "repay: the account owes nothing");
+	if (!fundsInU && !(view.rwaAsset && require_onchain_accounts_intents_utils_common.eq(intent.token, view.rwaAsset))) throw new require_onchain_accounts_intents_refusal.IntentPreviewError("unsupportedCollateralToken", { token: intent.token }, `repay: only ${U}${view.rwaAsset ? ` or ${view.rwaAsset}` : ""} can be repaid with, got ${intent.token}`);
+	if (view.debt <= 0n) throw new require_onchain_accounts_intents_refusal.IntentPreviewError("debtOutOfRange", {
+		requested: {
+			token: U,
+			balance: view.debt
+		},
+		minDebt: {
+			token: U,
+			balance: view.band.minDebt
+		},
+		maxDebt: {
+			token: U,
+			balance: view.band.maxDebt
+		}
+	}, "repay: the account owes nothing");
 	const funding = everything(intent.amount) ? view.price(U, intent.token, withMargin(view.debt)) : intent.amount;
 	const repaid = min(view.price(intent.token, U, funding), view.debt);
-	require_onchain_accounts_intents_math.assertDebtInBand(view.debt - repaid, view.band);
+	require_onchain_accounts_intents_math.assertDebtInBand(view.debt - repaid, view.band, U);
 	return [
 		add(intent.token, funding, intent.value),
 		...fundsInU ? [] : [convert(intent.token, U, funding)],
@@ -122,7 +144,7 @@ function planWithdrawDelayed(intent, view) {
 	const { U, T, S, WU, dD, all } = withdrawShape(intent, view);
 	if (all) {
 		const held = view.balanceOf(S);
-		if (held <= 0n) throw new require_onchain_accounts_intents_types.IntentPreviewError("insufficientSourceBalance", `withdraw: account holds no ${S} to redeem`);
+		if (held <= 0n) throw new require_onchain_accounts_intents_refusal.IntentPreviewError("insufficientSourceBalance", void 0, `withdraw: account holds no ${S} to redeem`);
 		return [{
 			kind: "request",
 			token: S,
@@ -134,7 +156,7 @@ function planWithdrawDelayed(intent, view) {
 			}
 		}];
 	}
-	if (!require_onchain_accounts_intents_utils_common.eq(T, U) && !(view.rwaAsset && require_onchain_accounts_intents_utils_common.eq(T, view.rwaAsset))) throw new require_onchain_accounts_intents_types.IntentPreviewError("noDelayedRoute", `withdraw: a delayed route cannot pay out in ${T}`);
+	if (!require_onchain_accounts_intents_utils_common.eq(T, U) && !(view.rwaAsset && require_onchain_accounts_intents_utils_common.eq(T, view.rwaAsset))) throw new require_onchain_accounts_intents_refusal.IntentPreviewError("noDelayedRoute", { token: T }, `withdraw: a delayed route cannot pay out in ${T}`);
 	const payoutIsSource = require_onchain_accounts_intents_utils_common.eq(T, S);
 	return [{
 		kind: "request",
@@ -160,9 +182,9 @@ function planWithdrawDelayed(intent, view) {
 */
 function planAdjustLeverageDelayed(intent, view) {
 	const { U, delta } = leverageShape(intent, view);
-	if (delta >= 0n) throw new require_onchain_accounts_intents_types.IntentPreviewError("noDelayedRoute", "adjustLeverage: only deleveraging can settle with a delay");
+	if (delta >= 0n) throw new require_onchain_accounts_intents_refusal.IntentPreviewError("noDelayedRoute", void 0, "adjustLeverage: only deleveraging can settle with a delay");
 	const shortfall = -delta - view.balanceOf(U);
-	if (shortfall <= 0n) throw new require_onchain_accounts_intents_types.IntentPreviewError("noDelayedRoute", "adjustLeverage: idle underlying covers the repayment, nothing to redeem");
+	if (shortfall <= 0n) throw new require_onchain_accounts_intents_refusal.IntentPreviewError("noDelayedRoute", void 0, "adjustLeverage: idle underlying covers the repayment, nothing to redeem");
 	const T = intent.token ?? positionToken(view, "adjustLeverage");
 	return [{
 		kind: "request",
@@ -190,7 +212,7 @@ function planFinishWithdraw(intent, claimable, claimed, view) {
 	const U = view.underlying;
 	const T = intent.withdrawToken;
 	const W = intent.withdrawAmount;
-	if (!require_onchain_accounts_intents_utils_common.eq(T, U) && !(view.rwaAsset && require_onchain_accounts_intents_utils_common.eq(T, view.rwaAsset))) throw new require_onchain_accounts_intents_types.IntentPreviewError("noDelayedRoute", `finishWithdraw: cannot pay out in ${T}`);
+	if (!require_onchain_accounts_intents_utils_common.eq(T, U) && !(view.rwaAsset && require_onchain_accounts_intents_utils_common.eq(T, view.rwaAsset))) throw new require_onchain_accounts_intents_refusal.IntentPreviewError("noDelayedRoute", { token: T }, `finishWithdraw: cannot pay out in ${T}`);
 	if (intent.debtRepaid === 0n) return [
 		claim(claimable),
 		convert(claimed.token, T, claimed.amount),
@@ -282,7 +304,7 @@ function withdrawShape(intent, view) {
 		};
 	}
 	const WU = view.price(T, U, intent.amount);
-	if (WU <= 0n) throw new require_onchain_accounts_intents_types.IntentPreviewError("insufficientSourceBalance", `withdraw: cannot price ${intent.amount} of ${T}`);
+	if (WU <= 0n) throw new require_onchain_accounts_intents_refusal.IntentPreviewError("insufficientSourceBalance", void 0, `withdraw: cannot price ${intent.amount} of ${T}`);
 	if (WU >= view.collateral) {
 		assertHasValue(view);
 		return {
@@ -295,7 +317,7 @@ function withdrawShape(intent, view) {
 		};
 	}
 	const dD = require_onchain_accounts_intents_math.proportionalDebt(view, WU);
-	require_onchain_accounts_intents_math.assertDebtInBand(view.debt - dD, view.band);
+	require_onchain_accounts_intents_math.assertDebtInBand(view.debt - dD, view.band, U);
 	return {
 		U,
 		T,
@@ -312,9 +334,9 @@ function withdrawShape(intent, view) {
 */
 function leverageShape(intent, view) {
 	require_onchain_accounts_intents_math.assertLeverageAtLeastOne(intent.targetLeverage);
-	if (view.collateral <= 0n) throw new require_onchain_accounts_intents_types.IntentPreviewError("insufficientSourceBalance", "adjustLeverage: account has no collateral to lever");
+	if (view.collateral <= 0n) throw new require_onchain_accounts_intents_refusal.IntentPreviewError("insufficientSourceBalance", void 0, "adjustLeverage: account has no collateral to lever");
 	const target = require_onchain_accounts_intents_math.debtForLeverage(view.collateral, intent.targetLeverage);
-	require_onchain_accounts_intents_math.assertDebtInBand(target, view.band);
+	require_onchain_accounts_intents_math.assertDebtInBand(target, view.band, view.underlying);
 	return {
 		U: view.underlying,
 		delta: target - view.debt
@@ -380,20 +402,20 @@ function payout(view, token, amount, to) {
 }
 function positionToken(view, flow) {
 	const pick = view.fattest([view.underlying]);
-	if (!pick) throw new require_onchain_accounts_intents_types.IntentPreviewError("insufficientSourceBalance", `${flow}: no position token on the account`);
+	if (!pick) throw new require_onchain_accounts_intents_refusal.IntentPreviewError("insufficientSourceBalance", void 0, `${flow}: no position token on the account`);
 	return pick;
 }
 function sourceToken(view) {
 	const pick = view.fattest();
-	if (!pick) throw new require_onchain_accounts_intents_types.IntentPreviewError("insufficientSourceBalance", "withdraw: account has no spendable balance");
+	if (!pick) throw new require_onchain_accounts_intents_refusal.IntentPreviewError("insufficientSourceBalance", void 0, "withdraw: account has no spendable balance");
 	return pick;
 }
 /** An account whose debt has eaten its collateral has nothing to hand over. */
 function assertHasValue(view) {
-	if (view.collateral <= 0n) throw new require_onchain_accounts_intents_types.IntentPreviewError("insufficientSourceBalance", `withdraw: nothing to withdraw, net value is ${view.collateral}`);
+	if (view.collateral <= 0n) throw new require_onchain_accounts_intents_refusal.IntentPreviewError("insufficientSourceBalance", void 0, `withdraw: nothing to withdraw, net value is ${view.collateral}`);
 }
 function assertPositive(amount, flow) {
-	if (amount <= 0n) throw new require_onchain_accounts_intents_types.IntentPreviewError("insufficientSourceBalance", `${flow}: amount must be positive`);
+	if (amount <= 0n) throw new require_onchain_accounts_intents_refusal.IntentPreviewError("insufficientSourceBalance", void 0, `${flow}: amount must be positive`);
 }
 //#endregion
 exports.RAISED = RAISED;

package/dist/cjs/onchain/accounts/intents/realize.js

@@ -1,6 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_onchain_market_math = require("../../market/math.js");
-const require_onchain_accounts_intents_types = require("./types.js");
+const require_onchain_accounts_intents_refusal = require("./refusal.js");
 const require_onchain_accounts_intents_utils_common = require("./utils/common.js");
 const require_onchain_accounts_intents_utils_convert_amount = require("./utils/convert-amount.js");
 const require_onchain_accounts_intents_utils_pick_token = require("./utils/pick-token.js");
@@ -60,7 +60,16 @@ async function realize(steps, props) {
 	const amountOf = (a) => typeof a === "bigint" ? a : min(raised, a.max ?? raised);
 	const assertHolds = (token, amount, what) => {
 		const held = ledger.balanceOf(token);
-		if (amount <= 0n || held < amount) throw new require_onchain_accounts_intents_types.IntentPreviewError("insufficientSourceBalance", `${what}: needs ${amount} of ${token}, account holds ${held}`);
+		if (amount <= 0n || held < amount) throw new require_onchain_accounts_intents_refusal.IntentPreviewError("insufficientSourceBalance", {
+			required: {
+				token,
+				balance: amount
+			},
+			held: {
+				token,
+				balance: held
+			}
+		}, `${what}: needs ${amount} of ${token}, account holds ${held}`);
 	};
 	for (const step of steps) switch (step.kind) {
 		case "add":
@@ -144,7 +153,7 @@ async function realize(steps, props) {
 		case "closeAll": {
 			const balances = ledger.snapshot().assets.filter((a) => !require_onchain_accounts_intents_utils_common.eq(a.token, underlying) && a.balance > DUST);
 			const pending = balances.find((a) => require_onchain_accounts_intents_utils_pick_token.isRedemptionPhantomToken(sdk, a.token));
-			if (pending) throw new require_onchain_accounts_intents_types.IntentPreviewError("withdrawalInProgress", `closeAll: ${pending.token} is a pending withdrawal, claim it first`);
+			if (pending) throw new require_onchain_accounts_intents_refusal.IntentPreviewError("withdrawalInProgress", { inFlight: pending }, `closeAll: ${pending.token} is a pending withdrawal, claim it first`);
 			if (balances.length > 0) {
 				const leg = await paths.closeAll({ balances });
 				if (leg.calls.length > 0 || leg.minAmount > 0n) push(require_onchain_accounts_intents_operations.buildCloseSwapOperation({
@@ -172,7 +181,10 @@ async function realize(steps, props) {
 		}
 		case "request": {
 			const asset = await delayedConfig(sdk, creditAccount, step.token);
-			if (ledger.balanceOf(asset.withdrawalPhantomToken) > 0n) throw new require_onchain_accounts_intents_types.IntentPreviewError("withdrawalInProgress", `request: ${asset.withdrawalPhantomToken} already holds a pending withdrawal`);
+			if (ledger.balanceOf(asset.withdrawalPhantomToken) > 0n) throw new require_onchain_accounts_intents_refusal.IntentPreviewError("withdrawalInProgress", { inFlight: {
+				token: asset.withdrawalPhantomToken,
+				balance: ledger.balanceOf(asset.withdrawalPhantomToken)
+			} }, `request: ${asset.withdrawalPhantomToken} already holds a pending withdrawal`);
 			assertHolds(step.token, step.amount + step.reserve, "request");
 			const preview = await sdk.accounts.previewDelayedWithdrawal({
 				creditAccount: creditAccount.creditAccount,
@@ -271,7 +283,7 @@ async function realize(steps, props) {
 		timeToLiquidation: sdk.positions.timeToLiquidation(snapshot, projectedPool),
 		liquidationPrice: sdk.positions.liquidationPrice(snapshot)
 	};
-	require_onchain_accounts_intents_guards.assertCollateralised(paysOut ? sdk.positions.healthFactor(snapshot, { safePrices: true }) : metrics.healthFactor);
+	require_onchain_accounts_intents_guards.assertCollateralised(paysOut ? sdk.positions.healthFactor(snapshot, { safePrices: true }) : metrics.healthFactor, paysOut);
 	const state = {
 		totalValue,
 		accountDebt: debt,
@@ -298,10 +310,13 @@ async function realize(steps, props) {
 */
 async function delayedConfig(sdk, creditAccount, token) {
 	const compressor = sdk.withdrawalCompressor;
-	if (!compressor) throw new require_onchain_accounts_intents_types.IntentPreviewError("noDelayedRoute", "request: chain has no withdrawal compressor");
+	if (!compressor) throw new require_onchain_accounts_intents_refusal.IntentPreviewError("noDelayedRoute", { token }, "request: chain has no withdrawal compressor");
 	const assets = await compressor.findWithdrawableAssets(creditAccount.creditManager, token);
-	if (assets.length === 0) throw new require_onchain_accounts_intents_types.IntentPreviewError("noDelayedRoute", `request: ${token} has no delayed withdrawal config`);
-	if (assets.length > 1) throw new require_onchain_accounts_intents_types.IntentPreviewError("multipleDelayedWithdrawals", `request: ${token} has ${assets.length} delayed withdrawal configs`);
+	if (assets.length === 0) throw new require_onchain_accounts_intents_refusal.IntentPreviewError("noDelayedRoute", { token }, `request: ${token} has no delayed withdrawal config`);
+	if (assets.length > 1) throw new require_onchain_accounts_intents_refusal.IntentPreviewError("multipleDelayedWithdrawals", {
+		token,
+		venues: assets.length
+	}, `request: ${token} has ${assets.length} delayed withdrawal configs`);
 	return assets[0];
 }
 const callsOf = (operations) => operations.flatMap((op) => op.calls);

package/dist/cjs/onchain/accounts/intents/refusal.js

@@ -0,0 +1,28 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/onchain/accounts/intents/refusal.ts
+/** Builds the refusal a caller sees. */
+function refuse(reason, detail) {
+	return {
+		ok: false,
+		reason,
+		detail
+	};
+}
+/**
+* Validation failure that maps onto {@link PreviewErrorReason} rather than
+* crashing the caller: raised by the planners and the guards, turned into
+* `{ ok: false }` by `CreditAccountOperationsService`.
+*/
+var IntentPreviewError = class extends Error {
+	reason;
+	detail;
+	constructor(reason, detail, message) {
+		super(message ?? reason);
+		this.name = "IntentPreviewError";
+		this.reason = reason;
+		this.detail = detail;
+	}
+};
+//#endregion
+exports.IntentPreviewError = IntentPreviewError;
+exports.refuse = refuse;