@gearbox-protocol/sdk 15.1.0-next.9 → 16.0.0-next.1

package/dist/esm/sdk/accounts/intents/index.js

@@ -1,389 +1,293 @@
 import { SDKConstruct } from "../../base/SDKConstruct.js";
-import { assembleOperationCalls } from "./utils/assemble-operation-calls.js";
-import { simulateState } from "./utils/simulate-adjust-state.js";
-import { getOperationsWithQuotaUpdate } from "./utils/with-quota-update.js";
-import "./utils/index.js";
-import { primaryInstantOutput } from "./operations/claim-delayed/index.js";
-import "./operations/index.js";
-import { buildResumeAddCollateralOperations } from "./intents/resume/add-collateral/add-collateral.js";
-import { buildResumeCloseOperations } from "./intents/resume/close/close.js";
-import { buildResumeDecreaseLeverageOperations } from "./intents/resume/decrease-leverage/decrease-leverage.js";
-import { buildResumeDepositOperations } from "./intents/resume/deposit/deposit.js";
-import { buildResumeIncreaseLeverageOperations } from "./intents/resume/increase-leverage/increase-leverage.js";
-import { buildResumeWithdrawOperations } from "./intents/resume/withdraw/withdraw.js";
-import "./intents/resume/index.js";
-import { createCloseOracleQuoter, createRouterCloseQuoter } from "./quoters/close.js";
-import { createOracleSwapQuoter, createRouterSwapQuoter } from "./quoters/swap.js";
-import "./quoters/index.js";
+import { MIN_HF_LIMITED } from "../../../common-utils/utils/validation/validate-hf.js";
+import { IntentPreviewError } from "./types.js";
+import { assertMarketOperable } from "./guards.js";
+import { maxProportionalWithdrawal } from "./math.js";
+import { maxWithdrawCollateral } from "./maxWithdrawCollateral.js";
+import { fetchCreditAccountSlice, toCreditAccountSlice } from "./utils/credit-account-slice.js";
+import { previewOpenStrategy } from "./open-strategy.js";
+import { planAddCollateral, planAdjustLeverage, planAdjustLeverageDelayed, planDeposit, planRepay, planWithdraw, planWithdrawAsset, planWithdrawDelayed } from "./plan.js";
+import { realize } from "./realize.js";
+import { accountView } from "./view.js";
+import { planTail, projectTail } from "./tail.js";
 //#region src/sdk/accounts/intents/index.ts
+/**
+* Previews of everything a wallet can do to an existing credit account.
+*
+* Two halves, deliberately kept apart: `plan.ts` turns an intent into a few
+* steps with pure arithmetic, `realize.ts` turns the steps into router-backed
+* operations. This class only picks the planner and wraps the outcome.
+*/
 var CreditAccountOperationsService = class extends SDKConstruct {
-	async finishIntent(props) {
-		const intent = props.intent;
-		switch (intent.type) {
-			case "ADD_COLLATERAL": return this.#finishAddCollateralIntent({
-				...props,
-				intent
-			});
-			case "INCREASE_LEVERAGE": return this.#finishIncreaseLeverageIntent({
-				...props,
-				intent
-			});
-			case "DEPOSIT": return this.#finishDepositIntent({
-				...props,
-				intent
-			});
-			case "DEPOSIT_AND_INCREASE_LEVERAGE": return this.#finishDepositAndIncreaseLeverageIntent({
-				...props,
-				intent
-			});
-			case "CLOSE_ACCOUNT": return this.#finishCloseAccountIntent({
-				...props,
-				intent
-			});
-			case "WITHDRAW_COLLATERAL": return this.#finishWithdrawCollateralIntent({
-				...props,
-				intent
-			});
-			case "DECREASE_LEVERAGE": return this.#finishDecreaseLeverageIntent({
-				...props,
-				intent
-			});
-			default: throw new Error(`${props.intent.type} - not implemented`);
-		}
-	}
 	/**
-	* Shared resume flow for claim-only intents (add collateral, increase
-	* leverage, deposit, deposit+increase): claim op + trailing changeQuota.
-	* If any implementations change, respective handler should be implemented separately
+	* Previews an operation on an existing account.
+	*
+	* @param props - Intent plus account slice, quota reserve and slippage
+	* @returns Operations, projected state and calldata, or `{ ok: false, reason }`
+	* when the intent cannot be satisfied (e.g. the account lacks the source
+	* balance)
 	*/
-	#finishClaimOnlyIntent = (buildOperations) => async (props) => {
-		switch (props.options.kind) {
-			case "offchain": return this.#finishClaimOnlyIntentOffchain(props, props.options, buildOperations);
-			default: return this.#finishClaimOnlyIntentOnchain(props, props.options, buildOperations);
-		}
-	};
-	#finishClaimOnlyIntentOffchain(props, options, buildOperations) {
-		const baseOperations = buildOperations(props.creditAccount, options, this.sdk);
-		const state = simulateState({
-			...props,
-			operations: baseOperations
-		});
-		return {
-			ok: true,
-			instant: {
-				operations: getOperationsWithQuotaUpdate({
-					operations: baseOperations,
-					state,
-					creditAccount: props.creditAccount,
-					sdk: this.sdk,
-					options
-				}),
-				preview: { min: state.state },
-				calls: []
-			},
-			instantError: void 0,
-			delayedBranch: void 0,
-			delayedError: void 0
-		};
-	}
-	async #finishClaimOnlyIntentOnchain(props, options, buildOperations) {
-		const baseOperations = buildOperations(props.creditAccount, options, this.sdk);
-		const state = simulateState({
-			...props,
-			operations: baseOperations
-		});
-		const operations = getOperationsWithQuotaUpdate({
-			operations: baseOperations,
-			state,
-			creditAccount: props.creditAccount,
-			sdk: this.sdk,
-			options
-		});
-		const calls = await assembleOperationCalls({
-			...props,
-			operations
-		});
-		return {
-			ok: true,
-			instant: {
-				operations,
-				preview: { min: state.state },
-				calls
-			},
-			instantError: void 0,
-			delayedBranch: void 0,
-			delayedError: void 0
-		};
+	async startIntent(props) {
+		return plain(await this.#preview(props, () => {
+			const { intent } = props;
+			const view = accountView(props.creditAccount, props.sdk);
+			switch (intent.type) {
+				case "ADD_COLLATERAL": return planAddCollateral(intent);
+				case "WITHDRAW_ASSET": return planWithdrawAsset(intent, view);
+				case "ADJUST_LEVERAGE": return planAdjustLeverage(intent, view);
+				case "DEPOSIT": return planDeposit(intent, view);
+				case "REPAY": return planRepay(intent, view);
+				case "WITHDRAW": return planWithdraw(intent, view);
+				default: throw new Error(`${intent.type} - not implemented`);
+			}
+		}));
 	}
-	#finishAddCollateralIntent = this.#finishClaimOnlyIntent(buildResumeAddCollateralOperations);
-	#finishIncreaseLeverageIntent = this.#finishClaimOnlyIntent(buildResumeIncreaseLeverageOperations);
-	#finishDepositIntent = this.#finishClaimOnlyIntent(buildResumeDepositOperations);
-	#finishDepositAndIncreaseLeverageIntent = this.#finishClaimOnlyIntent(buildResumeDepositOperations);
 	/**
-	* Resume close: claim, then close against quoted post-claim balances.
-	* Offchain quotes equity by oracle prices, onchain — router close path.
-	* Router miss soft-fails to the oracle quote with `calls: []` (legacy parity).
+	* Largest `WITHDRAW` amount (in underlying) the account can take out while
+	* keeping leverage and staying inside the facade's debt band — the ceiling a
+	* withdraw form should offer. Taking everything out is the same intent with
+	* `MAX_UINT256` for an amount, and needs none of this arithmetic.
+	*
+	* @param props - Account slice and the SDK holding its market
+	* @returns Amount in underlying units; `0n` when nothing can leave
 	*/
-	async #finishCloseAccountIntent({ options, ...props }) {
-		switch (options.kind) {
-			case "offchain": return this.#finishCloseAccountIntentOffchain({
-				...props,
-				options
-			});
-			default: try {
-				return await this.#finishCloseAccountIntentOnchain({
-					...props,
-					options
-				});
-			} catch {
-				return this.#finishCloseAccountIntentOffchain({
-					...props,
-					options
-				});
-			}
-		}
+	maxWithdraw(props) {
+		const view = accountView(props.creditAccount, props.sdk);
+		return maxProportionalWithdrawal(view, view.band);
 	}
-	async #finishCloseAccountIntentOffchain({ options, ...props }) {
-		const quoter = createCloseOracleQuoter({
-			sdk: this.sdk,
-			creditAccount: props.creditAccount
-		});
-		const { operations, quote } = await buildResumeCloseOperations({
-			...props,
-			options
-		}, quoter);
-		return {
-			ok: true,
-			instant: {
-				operations,
-				preview: { min: {
-					kind: "close",
-					amount: quote.amount,
-					minAmount: quote.minAmount,
-					underlyingBalance: quote.underlyingBalance
-				} },
-				calls: []
-			},
-			instantError: void 0,
-			delayedBranch: void 0,
-			delayedError: void 0
-		};
+	/**
+	* Debt a `REPAY` would have to cover to settle the account, in underlying
+	* units: principal plus the interest and fees accrued as of the read.
+	*
+	* A repayment of exactly this leaves nothing behind at the block it was read
+	* at, and a little behind at any later one, since interest does not stop —
+	* so a wallet meaning to clear the account sends this with a buffer on top,
+	* which the intent caps at the debt rather than spending. `REPAY` with
+	* `MAX_UINT256` sizes that buffer itself.
+	*
+	* @param props - Account slice and the SDK holding its market
+	* @returns Amount in underlying units; `0n` on an account that owes nothing
+	*/
+	maxRepay(props) {
+		return accountView(props.creditAccount, props.sdk).debt;
 	}
-	async #finishCloseAccountIntentOnchain({ options, slippage = 0, ...props }) {
-		const quoter = createRouterCloseQuoter({
-			sdk: this.sdk,
-			creditAccount: props.creditAccount,
-			slippage
-		});
-		const { operations, quote } = await buildResumeCloseOperations({
-			...props,
-			options
-		}, quoter);
-		const calls = await assembleOperationCalls({
+	/**
+	* Largest `WITHDRAW_ASSET` amount of one token the account can take out
+	* while its health factor stays at {@link MIN_HF_LIMITED} plus a basis
+	* point — the ceiling a withdraw-collateral form should offer. Thresholds,
+	* prices and quota activity come from the account's market, valued the way
+	* the facade values a call that pays out; zero debt frees the whole balance.
+	*
+	* @param props - Account slice, the SDK holding its market, and the
+	* collateral to withdraw
+	* @returns Amount in the token's units; `0n` when nothing can leave
+	*/
+	maxWithdrawCollateral(props) {
+		return maxWithdrawCollateral({
 			...props,
-			operations
+			targetHF: MIN_HF_LIMITED + 2n
 		});
-		return {
-			ok: true,
-			instant: {
-				operations,
-				preview: { min: {
-					kind: "close",
-					amount: quote.amount,
-					minAmount: quote.minAmount,
-					underlyingBalance: quote.underlyingBalance
-				} },
-				calls
-			},
-			instantError: void 0,
-			delayedBranch: void 0,
-			delayedError: void 0
-		};
 	}
 	/**
-	* Resume withdraw: claim → (swap?) → decreaseDebt? → (unwrapRwa?) →
-	* withdrawCollateral + trailing changeQuota. Offchain prices swaps by
-	* oracle, onchain — router swap paths (leftover-aware).
+	* Previews the same operation when its source only redeems through its
+	* issuer: a Securitize dsToken, a Mellow share.
+	*
+	* Sits apart from {@link startIntent} because it is a different trade route,
+	* not a different intent: the request goes to the issuer instead of the
+	* router, and the proceeds — hence the repayment and the payout — arrive days
+	* later. Both routes of one intent are quoted together by
+	* {@link intentRoutes}; this is the one to call when the delayed route is the
+	* only one of interest.
+	*
+	* `preview` is where the intent ends — the account once the redemption has
+	* matured, been claimed and the tail has run — because that is what the
+	* caller asked for; the half-way state the request itself lands in is
+	* `delayed.afterRequest`. Both are validated, so a request whose tail could
+	* not be completed is refused instead of started.
+	*
+	* @param props - Intent plus account slice, quota reserve and slippage
+	* @returns The request transaction, the state it ends in and what it recorded
+	* for the tail, or `{ ok: false, reason }` — `noDelayedRoute` when this route
+	* does not exist for the account at all
 	*/
-	async #finishWithdrawCollateralIntent({ options, ...props }) {
-		switch (options.kind) {
-			case "offchain": return this.#finishWithdrawCollateralIntentOffchain({
-				...props,
-				options
-			});
-			default: try {
-				return await this.#finishWithdrawCollateralIntentOnchain({
-					...props,
-					options
-				});
-			} catch {
-				return this.#finishWithdrawCollateralIntentOffchain({
-					...props,
-					options
-				});
+	async startDelayedIntent(props) {
+		const { intent } = props;
+		const result = await this.#preview(props, () => {
+			const view = accountView(props.creditAccount, props.sdk);
+			switch (intent.type) {
+				case "ADJUST_LEVERAGE": return planAdjustLeverageDelayed(intent, view);
+				case "WITHDRAW": return planWithdrawDelayed(intent, view);
+				default: throw new Error(`${intent.type} - cannot be delayed`);
 			}
+		});
+		if (!result.ok) return result;
+		const { delayed } = result;
+		if (!delayed) throw new Error("startDelayedIntent: plan started no withdrawal");
+		if (delayed.settlement === "instant") return {
+			...result,
+			delayed
+		};
+		const request = result.operations.find((op) => op.type === "startDelayedWithdrawal");
+		if (!request) throw new Error("startDelayedIntent: no request among the operations");
+		try {
+			const tail = await projectTail({
+				request,
+				delayed,
+				creditAccount: props.creditAccount,
+				sdk: props.sdk,
+				quotaReserve: props.quotaReserve
+			});
+			return {
+				...result,
+				preview: tail.state,
+				delayed
+			};
+		} catch (e) {
+			return asFailure(e);
 		}
 	}
-	async #finishWithdrawCollateralIntentOffchain({ options, ...props }) {
-		const quoter = createOracleSwapQuoter({
-			sdk: this.sdk,
-			creditAccount: props.creditAccount
-		});
-		const baseOperations = await buildResumeWithdrawOperations({
-			...props,
-			options
-		}, quoter);
-		const state = simulateState({
-			...props,
-			operations: baseOperations
-		});
-		return {
+	/**
+	* Previews a delayable intent both ways at once: settled by the router now,
+	* and started as a redemption that finishes days later.
+	*
+	* Which routes an account has depends on the intent and the token it sells,
+	* and a form has to know before it can offer a choice — so both are quoted
+	* from the same request and each is reported on its own. A route the account
+	* cannot take comes back `undefined` with its refusal in `refused`; only when
+	* neither answers is the whole result `{ ok: false }`.
+	*
+	* A route that could not be quoted at all — a pathfinder with no path out of
+	* the source, a read that failed — counts as missing rather than fatal, since
+	* the other route may be the one the caller wanted. With nothing left to
+	* report the failure is rethrown, as {@link startIntent} would have.
+	*
+	* @param props - A withdraw or adjust-leverage intent plus account slice,
+	* quota reserve and slippage
+	* @returns Whichever routes are viable, or `{ ok: false, reason }` when none is
+	*/
+	async intentRoutes(props) {
+		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 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
+		};
+		if (instantRoute || delayedRoute) return {
 			ok: true,
-			instant: {
-				operations: getOperationsWithQuotaUpdate({
-					operations: baseOperations,
-					state,
-					creditAccount: props.creditAccount,
-					sdk: this.sdk,
-					options
-				}),
-				preview: { min: state.state },
-				calls: []
-			},
-			instantError: void 0,
-			delayedBranch: void 0,
-			delayedError: void 0
+			instant: instantRoute,
+			delayed: delayedRoute,
+			refused
 		};
-	}
-	async #finishWithdrawCollateralIntentOnchain({ options, slippage = 0, ...props }) {
-		const quoter = createRouterSwapQuoter({
-			sdk: this.sdk,
-			creditAccount: props.creditAccount,
-			slippage
-		});
-		const baseOperations = await buildResumeWithdrawOperations({
-			...props,
-			options
-		}, quoter);
-		const state = simulateState({
-			...props,
-			operations: baseOperations
-		});
-		const operations = getOperationsWithQuotaUpdate({
-			operations: baseOperations,
-			state,
-			creditAccount: props.creditAccount,
-			sdk: this.sdk,
-			options
-		});
-		const calls = await assembleOperationCalls({
-			...props,
-			operations
-		});
+		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");
 		return {
-			ok: true,
-			instant: {
-				operations,
-				preview: { min: state.state },
-				calls
-			},
-			instantError: void 0,
-			delayedBranch: void 0,
-			delayedError: void 0
+			ok: false,
+			reason,
+			refused
 		};
 	}
 	/**
-	* Resume decrease leverage: claim → (wrapRwa | swap)? → decreaseDebt +
-	* trailing changeQuota. Offchain prices swaps by oracle, onchain — router
-	* swap paths. Router miss soft-fails to the oracle quote (legacy parity).
+	* Previews the tail of a delayed intent, once the withdrawal it started has
+	* matured: the claim, then whatever the intent still owes.
+	*
+	* Serves the three operations that can genuinely be interrupted by a delay —
+	* a withdrawal, a deleveraging and an exit. For the rest, the claim is the
+	* whole tail: the tokens land on the account and only their quota has to
+	* catch up.
+	*
+	* @param props - The recorded intent, the account slice as it stands now, and
+	* the matured claimable
+	* @returns Shaped exactly like {@link startIntent}'s result, so both halves of
+	* an operation are consumed the same way
 	*/
-	async #finishDecreaseLeverageIntent({ options, ...props }) {
-		switch (options.kind) {
-			case "offchain": return this.#finishDecreaseLeverageIntentOffchain({
-				...props,
-				options
-			});
-			default: try {
-				return await this.#finishDecreaseLeverageIntentOnchain({
-					...props,
-					options
-				});
-			} catch {
-				return this.#finishDecreaseLeverageIntentOffchain({
-					...props,
-					options
-				});
-			}
-		}
+	async finishIntent(props) {
+		return plain(await this.#preview(props, () => planTail({
+			intent: props.intent,
+			claimable: props.claimable,
+			view: accountView(props.creditAccount, props.sdk)
+		})));
 	}
-	async #finishDecreaseLeverageIntentOffchain({ options, ...props }) {
-		const quoter = createOracleSwapQuoter({
-			sdk: this.sdk,
-			creditAccount: props.creditAccount
-		});
-		const baseOperations = await buildResumeDecreaseLeverageOperations({
-			...props,
-			options
-		}, quoter);
-		const state = simulateState({
-			...props,
-			operations: baseOperations
-		});
-		return {
-			ok: true,
-			instant: {
-				operations: getOperationsWithQuotaUpdate({
-					operations: baseOperations,
-					state,
-					creditAccount: props.creditAccount,
-					sdk: this.sdk,
-					options
-				}),
-				preview: { min: state.state },
-				calls: []
-			},
-			instantError: void 0,
-			delayedBranch: void 0,
-			delayedError: void 0
-		};
+	/**
+	* Previews opening a brand-new leveraged position.
+	*
+	* Sits apart from {@link startIntent} because there is no account yet: nothing
+	* can be projected from existing balances, and the output feeds
+	* `sdk.accounts.openCA` rather than a facade multicall assembled here.
+	*
+	* @param props - Credit manager, wallet collateral, target token and leverage
+	* @returns Debt, position size, projected balances and quotas for both the
+	* expected and the floor branch, or `{ ok: false, reason }` when the requested
+	* leverage or the resulting debt is not viable
+	*/
+	async openStrategyIntent(props) {
+		try {
+			return {
+				ok: true,
+				preview: await previewOpenStrategy(props)
+			};
+		} catch (e) {
+			return asFailure(e);
+		}
 	}
-	async #finishDecreaseLeverageIntentOnchain({ options, slippage = 0, ...props }) {
-		const quoter = createRouterSwapQuoter({
-			sdk: this.sdk,
-			creditAccount: props.creditAccount,
-			slippage
-		});
-		const baseOperations = await buildResumeDecreaseLeverageOperations({
-			...props,
-			options
-		}, quoter);
-		const state = simulateState({
-			...props,
-			operations: baseOperations
-		});
-		const operations = getOperationsWithQuotaUpdate({
-			operations: baseOperations,
-			state,
-			creditAccount: props.creditAccount,
-			sdk: this.sdk,
-			options
-		});
-		const calls = await assembleOperationCalls({
-			...props,
-			operations
-		});
-		return {
-			ok: true,
-			instant: {
+	/** Plan → realise → wrap. Unviable requests become `{ ok: false }`. */
+	async #preview(props, plan) {
+		try {
+			assertMarketOperable(props.sdk.marketRegister.findCreditManager(props.creditAccount.creditManager));
+			const { operations, state, calls, delayed } = await realize(plan(), {
+				creditAccount: props.creditAccount,
+				sdk: props.sdk,
+				slippage: props.slippage ?? 0,
+				quotaReserve: props.quotaReserve
+			});
+			return {
+				ok: true,
 				operations,
-				preview: { min: state.state },
-				calls
-			},
-			instantError: void 0,
-			delayedBranch: void 0,
-			delayedError: void 0
-		};
+				preview: state,
+				calls,
+				delayed
+			};
+		} catch (e) {
+			return asFailure(e);
+		}
 	}
 };
+/** Drops the delayed half for the flows that cannot produce one. */
+function plain(result) {
+	if (!result.ok) return result;
+	const { operations, preview, calls } = result;
+	return {
+		ok: true,
+		operations,
+		preview,
+		calls
+	};
+}
+/** Unviable requests are values; anything else is a genuine failure. */
+function asFailure(e) {
+	if (e instanceof IntentPreviewError) return {
+		ok: false,
+		reason: e.reason
+	};
+	if (isUnroutable(e)) return {
+		ok: false,
+		reason: "unsupportedTokenPair"
+	};
+	throw e;
+}
+/**
+* How the pathfinder says there is no route: it reverts instead of answering
+* with an empty path, so viem raises a contract error where the rest of the
+* engine raises an {@link IntentPreviewError}. Nothing is wrong — the trade
+* asked for cannot be made, which is a refusal the caller can act on, and one
+* `intentRoutes` in particular must keep as a value so the other route can
+* still be offered.
+*/
+function isUnroutable(e) {
+	for (let cause = e; cause instanceof Error; cause = cause.cause) if (cause.message.includes("no optimal edge found")) return true;
+	return false;
+}
 //#endregion
-export { CreditAccountOperationsService, primaryInstantOutput };
+export { CreditAccountOperationsService, IntentPreviewError, fetchCreditAccountSlice, toCreditAccountSlice };