@gearbox-protocol/sdk 16.0.0-next.41 → 16.0.0-next.42

package/dist/esm/sdk/prepare/PrepareApi.js

@@ -1,10 +1,10 @@
 import { hexEq } from "../../onchain/utils/hex.js";
 import { MultichainConstruct } from "../../onchain/base/MultichainConstruct.js";
-import { refuse } from "../../onchain/validation/refusal.js";
 import { toToken } from "../../onchain/validation/token.js";
-import { fetchCreditAccountSlice } from "../../onchain/accounts/intents/utils/credit-account-slice.js";
+import { toCreditAccountSlice } from "../../onchain/accounts/intents/utils/credit-account-slice.js";
 import { CreditAccountOperationsService } from "../../onchain/accounts/intents/index.js";
 import "../../onchain/index.js";
+import { creditAccountNotFound, noStrategyTargetCollateral, toPrepareError, unexpectedFailure } from "./errors.js";
 import { withdrawableCollaterals } from "./withdrawable-collaterals.js";
 //#region src/sdk/prepare/PrepareApi.ts
 /**
@@ -17,8 +17,13 @@ import { withdrawableCollaterals } from "./withdrawable-collaterals.js";
 *
 * A prepared operation names one chain, so it reads through
 * {@link MultichainConstruct.queryChain}: there is no second source to fall back
-* to, hence a chain the SDK does not cover, or one that fails the read, throws
-* rather than answering with empty metadata.
+* to, hence a chain the SDK does not cover, or one that fails the read, is a
+* failure of the whole request rather than a thinner answer.
+*
+* No method here throws. Every way a preparation can fail — the market's own
+* refusals, the two the namespace decides itself, and anything the chain or the
+* engine raises — comes back described in the envelope, see {@link PrepareError}.
+* A caller writes one branch, not a branch and a `try`.
 **/
 var PrepareApi = class extends MultichainConstruct {
 	#ensureFresh;
@@ -31,29 +36,77 @@ var PrepareApi = class extends MultichainConstruct {
 		return super.queryChain(props);
 	}
 	/**
+	* Runs a one-chain request whose answer is an envelope, describing whatever
+	* the chain, the read or the engine throws on the way rather than letting it
+	* escape.
+	*
+	* So every method below answers instead of rejecting, and a caller has one
+	* thing to branch on. "This cannot be done" and "we could not find out" are
+	* still told apart, by `error.code`: only the second is
+	* `unexpectedFailure`, and only it marks the chain failed in `meta`.
+	**/
+	async #answer(chainId, run) {
+		try {
+			return await this.queryChain({
+				network: chainId,
+				run
+			});
+		} catch (e) {
+			return {
+				data: {
+					success: false,
+					error: unexpectedFailure(e)
+				},
+				meta: { chains: [failedChain(chainId, e)] }
+			};
+		}
+	}
+	/**
 	* {@inheritDoc IOpportunitiesPrepare.finalize}
 	**/
 	async finalize(position, params) {
-		return this.queryChain({
-			network: position.chainId,
-			run: async (sdk) => {
-				const intent = resumable(params.intent ?? params.claimable.intent);
-				if (!intent) return refuse("noRecordedIntent", void 0);
-				return service(sdk).finishIntent({
-					intent,
-					claimable: toClaimableWithdrawal(params.claimable),
-					creditAccount: await slice(sdk, position.creditAccount),
-					sdk,
-					slippage: params.slippage,
-					quotaReserve: params.quotaReserve
-				});
-			}
+		return this.#answer(position.chainId, async (sdk) => {
+			const intent = resumable(params.intent ?? params.claimable.intent);
+			if (!intent) return {
+				success: false,
+				error: toPrepareError({
+					reason: "noRecordedIntent",
+					detail: void 0
+				})
+			};
+			const creditAccount = await slice(sdk, position.creditAccount);
+			if (!creditAccount) return {
+				success: false,
+				error: creditAccountNotFound(position.creditAccount)
+			};
+			return planned(await service(sdk).finishIntent({
+				intent,
+				claimable: toClaimableWithdrawal(params.claimable),
+				creditAccount,
+				sdk,
+				slippage: params.slippage,
+				quotaReserve: params.quotaReserve
+			}));
 		});
 	}
 	/**
 	* {@inheritDoc IOpportunitiesPrepare.deposit}
 	**/
 	deposit(pool, params) {
+		try {
+			return this.#depositPlan(pool, params);
+		} catch (e) {
+			return {
+				success: false,
+				error: unexpectedFailure(e)
+			};
+		}
+	}
+	/**
+	* The arithmetic behind {@link deposit}, which throws where the SDK holds
+	* nothing for the pool or the chain it was handed.
+	**/
+	#depositPlan(pool, params) {
 		const chain = this.sdk.chain(pool.chainId);
 		const { marketRegister, pools } = chain;
 		const tokenIn = params.tokenIn ?? marketRegister.findByPool(pool.pool).pool.underlying;
@@ -76,16 +129,31 @@ var PrepareApi = class extends MultichainConstruct {
 		});
 		if (!call) return unroutable(chain, tokenIn, tokenOut);
 		return {
-			ok: true,
-			operations: [],
-			state,
-			calls: call.calls
+			success: true,
+			data: {
+				operations: [],
+				state,
+				calls: call.calls
+			}
 		};
 	}
 	/**
 	* {@inheritDoc IOpportunitiesPrepare.withdraw}
 	**/
 	withdraw(pool, params) {
+		try {
+			return this.#withdrawPlan(pool, params);
+		} catch (e) {
+			return {
+				success: false,
+				error: unexpectedFailure(e)
+			};
+		}
+	}
+	/**
+	* {@inheritDoc PrepareApi.depositPlan}
+	**/
+	#withdrawPlan(pool, params) {
 		const chain = this.sdk.chain(pool.chainId);
 		const { pools } = chain;
 		const tokenIn = params.tokenIn ?? pool.pool;
@@ -106,16 +174,31 @@ var PrepareApi = class extends MultichainConstruct {
 			mode: "withdraw"
 		});
 		return {
-			ok: true,
-			operations: [],
-			state,
-			calls
+			success: true,
+			data: {
+				operations: [],
+				state,
+				calls
+			}
 		};
 	}
 	/**
 	* {@inheritDoc IOpportunitiesPrepare.redeem}
 	**/
 	redeem(pool, params) {
+		try {
+			return this.#redeemPlan(pool, params);
+		} catch (e) {
+			return {
+				success: false,
+				error: unexpectedFailure(e)
+			};
+		}
+	}
+	/**
+	* {@inheritDoc PrepareApi.depositPlan}
+	**/
+	#redeemPlan(pool, params) {
 		const chain = this.sdk.chain(pool.chainId);
 		const { pools } = chain;
 		const tokenIn = params.tokenIn ?? pool.pool;
@@ -136,32 +219,34 @@ var PrepareApi = class extends MultichainConstruct {
 			mode: "redeem"
 		});
 		return {
-			ok: true,
-			operations: [],
-			state,
-			calls
+			success: true,
+			data: {
+				operations: [],
+				state,
+				calls
+			}
 		};
 	}
 	/**
 	* {@inheritDoc IOpportunitiesPrepare.openNewStrategy}
 	**/
 	async openNewStrategy(strategy, params) {
-		return this.queryChain({
-			network: strategy.chainId,
-			run: (sdk) => {
-				const targetToken = params.targetToken ?? sdk.marketRegister.findCreditManager(strategy.creditManager).strategyTargetCollateral;
-				if (!targetToken) throw new Error(`credit manager ${strategy.creditManager} has no strategy target collateral`);
-				return service(sdk).openStrategyIntent({
-					sdk,
-					creditManager: strategy.creditManager,
-					collateral: params.collateral,
-					targetToken,
-					leverage: params.leverage,
-					leftoverBalances: params.leftoverBalances,
-					slippage: params.slippage,
-					quotaReserve: params.quotaReserve
-				});
-			}
+		return this.#answer(strategy.chainId, async (sdk) => {
+			const targetToken = params.targetToken ?? sdk.marketRegister.findCreditManager(strategy.creditManager).strategyTargetCollateral;
+			if (!targetToken) return {
+				success: false,
+				error: noStrategyTargetCollateral(strategy.creditManager)
+			};
+			return opened(await service(sdk).openStrategyIntent({
+				sdk,
+				creditManager: strategy.creditManager,
+				collateral: params.collateral,
+				targetToken,
+				leverage: params.leverage,
+				leftoverBalances: params.leftoverBalances,
+				slippage: params.slippage,
+				quotaReserve: params.quotaReserve
+			}));
 		});
 	}
 	/**
@@ -193,12 +278,19 @@ var PrepareApi = class extends MultichainConstruct {
 	* {@inheritDoc IOpportunitiesPrepare.maxWithdraw}
 	**/
 	async maxWithdraw(position) {
-		return this.queryChain({
-			network: position.chainId,
-			run: async (sdk) => service(sdk).maxWithdraw({
-				creditAccount: await slice(sdk, position.creditAccount),
-				sdk
-			})
+		return this.#answer(position.chainId, async (sdk) => {
+			const creditAccount = await slice(sdk, position.creditAccount);
+			if (!creditAccount) return {
+				success: false,
+				error: creditAccountNotFound(position.creditAccount)
+			};
+			return {
+				success: true,
+				data: await service(sdk).maxWithdraw({
+					creditAccount,
+					sdk
+				})
+			};
 		});
 	}
 	/**
@@ -216,12 +308,19 @@ var PrepareApi = class extends MultichainConstruct {
 	* {@inheritDoc IOpportunitiesPrepare.maxRepay}
 	**/
 	async maxRepay(position) {
-		return this.queryChain({
-			network: position.chainId,
-			run: async (sdk) => service(sdk).maxRepay({
-				creditAccount: await slice(sdk, position.creditAccount),
-				sdk
-			})
+		return this.#answer(position.chainId, async (sdk) => {
+			const creditAccount = await slice(sdk, position.creditAccount);
+			if (!creditAccount) return {
+				success: false,
+				error: creditAccountNotFound(position.creditAccount)
+			};
+			return {
+				success: true,
+				data: await service(sdk).maxRepay({
+					creditAccount,
+					sdk
+				})
+			};
 		});
 	}
 	/**
@@ -278,14 +377,21 @@ var PrepareApi = class extends MultichainConstruct {
 	* {@inheritDoc IOpportunitiesPrepare.maxWithdrawCollateral}
 	**/
 	async maxWithdrawCollateral(position, token, targetHF) {
-		return this.queryChain({
-			network: position.chainId,
-			run: async (sdk) => service(sdk).maxWithdrawCollateral({
-				creditAccount: await slice(sdk, position.creditAccount),
-				sdk,
-				token,
-				targetHF
-			})
+		return this.#answer(position.chainId, async (sdk) => {
+			const creditAccount = await slice(sdk, position.creditAccount);
+			if (!creditAccount) return {
+				success: false,
+				error: creditAccountNotFound(position.creditAccount)
+			};
+			return {
+				success: true,
+				data: await service(sdk).maxWithdrawCollateral({
+					creditAccount,
+					sdk,
+					token,
+					targetHF
+				})
+			};
 		});
 	}
 	/**
@@ -293,42 +399,60 @@ var PrepareApi = class extends MultichainConstruct {
 	* two routes to offer: one account read, one intent, both routes quoted.
 	**/
 	async #startRoutes(position, options, intent) {
-		return this.queryChain({
-			network: position.chainId,
-			run: async (sdk) => service(sdk).intentRoutes({
-				intent,
-				creditAccount: await slice(sdk, position.creditAccount),
-				sdk,
-				slippage: options.slippage,
-				quotaReserve: options.quotaReserve
-			})
-		});
+		try {
+			return await this.queryChain({
+				network: position.chainId,
+				run: async (sdk) => {
+					const creditAccount = await slice(sdk, position.creditAccount);
+					if (!creditAccount) return neitherRoute(creditAccountNotFound(position.creditAccount));
+					return routed(await service(sdk).intentRoutes({
+						intent,
+						creditAccount,
+						sdk,
+						slippage: options.slippage,
+						quotaReserve: options.quotaReserve
+					}));
+				}
+			});
+		} catch (e) {
+			return {
+				data: neitherRoute(unexpectedFailure(e)),
+				meta: { chains: [failedChain(position.chainId, e)] }
+			};
+		}
 	}
 	/**
 	* Shared path of the five flows that act on an existing account: read the
 	* account, then run the intent through the engine.
 	**/
 	async #startIntent(position, options, intent) {
-		return this.queryChain({
-			network: position.chainId,
-			run: async (sdk) => {
-				const creditAccount = await slice(sdk, position.creditAccount);
-				return service(sdk).startIntent({
-					intent,
-					creditAccount,
-					sdk,
-					slippage: options.slippage,
-					quotaReserve: options.quotaReserve
-				});
-			}
+		return this.#answer(position.chainId, async (sdk) => {
+			const creditAccount = await slice(sdk, position.creditAccount);
+			if (!creditAccount) return {
+				success: false,
+				error: creditAccountNotFound(position.creditAccount)
+			};
+			return planned(await service(sdk).startIntent({
+				intent,
+				creditAccount,
+				sdk,
+				slippage: options.slippage,
+				quotaReserve: options.quotaReserve
+			}));
 		});
 	}
 };
 function service(sdk) {
 	return new CreditAccountOperationsService(sdk);
 }
-function slice(sdk, creditAccount) {
-	return fetchCreditAccountSlice(sdk, creditAccount);
+/**
+* The account the request names, or nothing where the markets this SDK is
+* connected to hold no such account — closed since it was listed, or named on
+* the wrong chain. Read rather than thrown, so the caller gets a code for it.
+**/
+async function slice(sdk, creditAccount) {
+	const data = await sdk.accounts.getCreditAccountData(creditAccount);
+	return data && toCreditAccountSlice(data);
 }
 /**
 * The operation a claim resumes, or `undefined` when there is none to resume:
@@ -361,6 +485,36 @@ function toClaimableWithdrawal(claimable) {
 	};
 }
 /**
+* A flow with two routes, refused before either could be quoted: the error is
+* the same one any other flow would report, with nothing to say about the
+* routes because neither was reached.
+**/
+function neitherRoute(error) {
+	return {
+		success: false,
+		error: {
+			...error,
+			refused: {
+				instant: void 0,
+				delayed: void 0
+			}
+		}
+	};
+}
+/**
+* The chain entry for a request that was answered with
+* {@link UnexpectedFailureError}: the read did not happen, so the metadata says
+* so rather than reporting a block it never got.
+**/
+function failedChain(chainId, error) {
+	return {
+		chainId,
+		status: "error",
+		source: "onchain",
+		error
+	};
+}
+/**
 * A pool route the market does not offer, as the refusal a caller reads.
 *
 * `to` is absent where {@link lpRoute} found no output to name at all, which
@@ -368,10 +522,89 @@ function toClaimableWithdrawal(claimable) {
 * ours implements it.
 **/
 function unroutable(sdk, from, to) {
-	return refuse("unsupportedTokenPair", {
-		from: toToken(sdk, from),
-		to: to === void 0 ? void 0 : toToken(sdk, to)
-	});
+	return {
+		success: false,
+		error: toPrepareError({
+			reason: "unsupportedTokenPair",
+			detail: {
+				from: toToken(sdk, from),
+				to: to === void 0 ? void 0 : toToken(sdk, to)
+			}
+		})
+	};
+}
+/**
+* The engine's answer, as the envelope the namespace speaks in: what the
+* operation comes to under `data`, or the refusal as an error carrying its own
+* numbers, see {@link toPrepareError}.
+*
+* The engine keeps its `ok` union — it is the shape the planners, the guards
+* and their tests are written against — and the boundary is the one place the
+* two vocabularies meet.
+**/
+function planned(result) {
+	if (!result.ok) return {
+		success: false,
+		error: toPrepareError(result)
+	};
+	const { operations, state, calls } = result;
+	return {
+		success: true,
+		data: {
+			operations,
+			state,
+			calls
+		}
+	};
+}
+/**
+* {@inheritDoc planned}
+**/
+function opened(result) {
+	return result.ok ? {
+		success: true,
+		data: { state: result.state }
+	} : {
+		success: false,
+		error: toPrepareError(result)
+	};
+}
+/**
+* {@inheritDoc planned}
+*
+* Both routes are payload, refusal and all: `refused` says why a missing one is
+* missing, and it stays on the error when neither route answered, since that is
+* the same question asked of a request that has no viable half at all.
+**/
+function routed(result) {
+	if (!result.ok) {
+		const { refused, ...issue } = result;
+		return {
+			success: false,
+			error: {
+				...toPrepareError(issue),
+				refused
+			}
+		};
+	}
+	const { instant, delayed, refused } = result;
+	return {
+		success: true,
+		data: {
+			instant: instant && {
+				operations: instant.operations,
+				state: instant.state,
+				calls: instant.calls
+			},
+			delayed: delayed && {
+				operations: delayed.operations,
+				state: delayed.state,
+				calls: delayed.calls,
+				delayed: delayed.delayed
+			},
+			refused
+		}
+	};
 }
 /**
 * Picks the route the operation takes out of `tokenIn`, as a value rather than

package/dist/esm/sdk/prepare/errors.js

@@ -0,0 +1,86 @@
+//#region src/sdk/prepare/errors.ts
+/**
+* One sentence per refusal, naming what was ruled out rather than restating the
+* numbers the error already carries.
+*
+* English and loggable, not a string to put on a screen: a form renders the
+* code and the amounts in its own words, see {@link IGearboxError.message}.
+**/
+const MESSAGES = {
+	debtOutOfRange: "The debt this request implies is outside the market's band.",
+	leverageOutOfRange: "The leverage asked for cannot be expressed as a plan.",
+	insufficientSourceBalance: "Neither the account nor the wallet holds enough to fund this request.",
+	unsupportedCollateralToken: "This flow does not accept that token.",
+	unsupportedTokenPair: "No route exists between these two tokens.",
+	noDelayedRoute: "This request cannot be served as a delayed redemption.",
+	multipleDelayedWithdrawals: "The source asset has several redemption venues and none was named.",
+	withdrawalInProgress: "A redemption of this asset is already in flight on the account.",
+	noRecordedIntent: "The claim names no operation to resume.",
+	marketPaused: "The market is paused.",
+	marketExpired: "The market is past its expiration date.",
+	insufficientPoolLiquidity: "The pool cannot lend what this plan draws.",
+	quotaLimitReached: "The market takes no more quota for a token this plan holds.",
+	forbiddenToken: "This plan would increase the balance of a forbidden token.",
+	insufficientCollateral: "The account would end this transaction under-collateralised.",
+	poolSunset: "The pool is winding down and takes no more deposits.",
+	quotaCountExceeded: "The account would hold more quoted tokens than the facade enables at once.",
+	malformedTransaction: "The transaction could not be replayed."
+};
+/**
+* The engine's refusal, as the error the namespace answers with.
+*
+* One place does the lifting, so the two shapes cannot drift: `reason` becomes
+* `code`, the detail is spread onto the error, and the sentence comes from
+* {@link MESSAGES}. A malformed transaction is spelled out rather than spread,
+* because its detail names a `code` and a `message` of its own and they are not
+* the envelope's.
+**/
+function toPrepareError(issue) {
+	if (issue.reason === "malformedTransaction") return {
+		code: "malformedTransaction",
+		message: MESSAGES.malformedTransaction,
+		previewCode: issue.detail.code,
+		detail: issue.detail.message
+	};
+	return {
+		code: issue.reason,
+		message: MESSAGES[issue.reason],
+		...issue.detail
+	};
+}
+/**
+* {@inheritDoc NoStrategyTargetCollateralError}
+**/
+function noStrategyTargetCollateral(creditManager) {
+	return {
+		code: "noStrategyTargetCollateral",
+		message: `Credit manager ${creditManager} has no strategy target collateral, and none was named.`,
+		creditManager
+	};
+}
+/**
+* {@inheritDoc CreditAccountNotFoundError}
+**/
+function creditAccountNotFound(creditAccount) {
+	return {
+		code: "creditAccountNotFound",
+		message: `Credit account not found: ${creditAccount}.`,
+		creditAccount
+	};
+}
+/**
+* {@inheritDoc UnexpectedFailureError}
+*
+* Takes what was thrown, whatever that is: a `throw` is not obliged to raise an
+* `Error`, and `cause` promises one.
+**/
+function unexpectedFailure(thrown) {
+	const cause = thrown instanceof Error ? thrown : new Error(String(thrown));
+	return {
+		code: "unexpectedFailure",
+		message: `The SDK could not prepare this operation: ${cause.message}`,
+		cause
+	};
+}
+//#endregion
+export { creditAccountNotFound, noStrategyTargetCollateral, toPrepareError, unexpectedFailure };

package/dist/esm/sdk/prepare/index.js

@@ -1,4 +1,5 @@
 import { IntentPreviewError, raise, refuse } from "../../onchain/validation/refusal.js";
+import { creditAccountNotFound, noStrategyTargetCollateral, toPrepareError, unexpectedFailure } from "./errors.js";
 import { PrepareApi } from "./PrepareApi.js";
 import "./types.js";
-export { IntentPreviewError, PrepareApi, raise, refuse };
+export { IntentPreviewError, PrepareApi, creditAccountNotFound, noStrategyTargetCollateral, raise, refuse, toPrepareError, unexpectedFailure };