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

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

@@ -1,10 +1,12 @@
 import { hexEq } from "../../onchain/utils/hex.js";
 import { MultichainConstruct } from "../../onchain/base/MultichainConstruct.js";
+import { sdkErr, sdkOk } from "../../model/result.js";
+import "../../model/index.js";
 import { toToken } from "../../onchain/validation/token.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 { creditAccountNotFound, noStrategyTargetCollateral, toRefusalError, unexpectedFailure } from "./errors.js";
 import { withdrawableCollaterals } from "./withdrawable-collaterals.js";
 //#region src/sdk/prepare/PrepareApi.ts
 /**
@@ -15,15 +17,18 @@ import { withdrawableCollaterals } from "./withdrawable-collaterals.js";
 * protocol knowledge stays in `CreditAccountOperationsService` and
 * `PoolService`.
 *
-* 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, is a
-* failure of the whole request rather than a thinner answer.
+* A prepared operation names one chain and reads it directly: there is no
+* second source to fall back to, so 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`.
+* No refusable async method here throws. Every way such a preparation can
+* fail — the market's own refusals, the ones the namespace decides itself, and
+* anything the chain or the engine raises — comes back in the failure half of
+* its `SDKReturn`, under the codes that method's signature names. A caller
+* writes one branch, not a branch and a `try`. The synchronous LP methods and
+* the bare `max*` reads throw on bugs and lifecycle errors instead, see
+* {@link IOpportunitiesPrepare}.
 **/
 var PrepareApi = class extends MultichainConstruct {
 	#ensureFresh;
@@ -31,54 +36,28 @@ var PrepareApi = class extends MultichainConstruct {
 		super(sdk);
 		this.#ensureFresh = ensureFresh;
 	}
-	async queryChain(props) {
-		await this.#ensureFresh?.([this.sdk.chain(props.network).chainId]);
-		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`.
+	* The chain an async method reads, revalidated first so the state it is
+	* about to weigh is no older than the SDK's freshness bar.
 	**/
-	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)] }
-			};
-		}
+	async #chain(chainId) {
+		await this.#ensureFresh?.([this.sdk.chain(chainId).chainId]);
+		return this.sdk.chain(chainId);
 	}
 	/**
 	* {@inheritDoc IOpportunitiesPrepare.finalize}
 	**/
 	async finalize(position, params) {
-		return this.#answer(position.chainId, async (sdk) => {
+		try {
+			const sdk = await this.#chain(position.chainId);
+			const at = stateBlock(sdk);
 			const intent = resumable(params.intent ?? params.claimable.intent);
-			if (!intent) return {
-				success: false,
-				error: toPrepareError({
-					reason: "noRecordedIntent",
-					detail: void 0
-				})
-			};
+			if (!intent) return sdkErr(toRefusalError({
+				reason: "noRecordedIntent",
+				detail: void 0
+			}));
 			const creditAccount = await slice(sdk, position.creditAccount);
-			if (!creditAccount) return {
-				success: false,
-				error: creditAccountNotFound(position.creditAccount)
-			};
+			if (!creditAccount) return sdkErr(creditAccountNotFound(position.creditAccount));
 			return planned(await service(sdk).finishIntent({
 				intent,
 				claimable: toClaimableWithdrawal(params.claimable),
@@ -86,27 +65,15 @@ var PrepareApi = class extends MultichainConstruct {
 				sdk,
 				slippage: params.slippage,
 				quotaReserve: params.quotaReserve
-			}));
-		});
-	}
-	/**
-	* {@inheritDoc IOpportunitiesPrepare.deposit}
-	**/
-	deposit(pool, params) {
-		try {
-			return this.#depositPlan(pool, params);
+			}), at);
 		} catch (e) {
-			return {
-				success: false,
-				error: unexpectedFailure(e)
-			};
+			return sdkErr(unexpectedFailure(e));
 		}
 	}
 	/**
-	* The arithmetic behind {@link deposit}, which throws where the SDK holds
-	* nothing for the pool or the chain it was handed.
+	* {@inheritDoc IOpportunitiesPrepare.deposit}
 	**/
-	#depositPlan(pool, params) {
+	deposit(pool, params) {
 		const chain = this.sdk.chain(pool.chainId);
 		const { marketRegister, pools } = chain;
 		const tokenIn = params.tokenIn ?? marketRegister.findByPool(pool.pool).pool.underlying;
@@ -128,32 +95,17 @@ var PrepareApi = class extends MultichainConstruct {
 			meta: pools.getDepositMetadata(pool.pool, tokenIn, tokenOut)
 		});
 		if (!call) return unroutable(chain, tokenIn, tokenOut);
-		return {
-			success: true,
-			data: {
-				operations: [],
-				state,
-				calls: call.calls
-			}
-		};
+		return sdkOk({
+			operations: [],
+			state,
+			calls: call.calls,
+			...stateBlock(chain)
+		});
 	}
 	/**
 	* {@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;
@@ -173,32 +125,17 @@ var PrepareApi = class extends MultichainConstruct {
 			meta: pools.getWithdrawalMetadata(pool.pool, tokenIn, tokenOut),
 			mode: "withdraw"
 		});
-		return {
-			success: true,
-			data: {
-				operations: [],
-				state,
-				calls
-			}
-		};
+		return sdkOk({
+			operations: [],
+			state,
+			calls,
+			...stateBlock(chain)
+		});
 	}
 	/**
 	* {@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;
@@ -218,25 +155,22 @@ var PrepareApi = class extends MultichainConstruct {
 			meta: pools.getWithdrawalMetadata(pool.pool, tokenIn, tokenOut),
 			mode: "redeem"
 		});
-		return {
-			success: true,
-			data: {
-				operations: [],
-				state,
-				calls
-			}
-		};
+		return sdkOk({
+			operations: [],
+			state,
+			calls,
+			...stateBlock(chain)
+		});
 	}
 	/**
 	* {@inheritDoc IOpportunitiesPrepare.openNewStrategy}
 	**/
 	async openNewStrategy(strategy, params) {
-		return this.#answer(strategy.chainId, async (sdk) => {
+		try {
+			const sdk = await this.#chain(strategy.chainId);
+			const at = stateBlock(sdk);
 			const targetToken = params.targetToken ?? sdk.marketRegister.findCreditManager(strategy.creditManager).strategyTargetCollateral;
-			if (!targetToken) return {
-				success: false,
-				error: noStrategyTargetCollateral(strategy.creditManager)
-			};
+			if (!targetToken) return sdkErr(noStrategyTargetCollateral(strategy.creditManager));
 			return opened(await service(sdk).openStrategyIntent({
 				sdk,
 				creditManager: strategy.creditManager,
@@ -246,8 +180,10 @@ var PrepareApi = class extends MultichainConstruct {
 				leftoverBalances: params.leftoverBalances,
 				slippage: params.slippage,
 				quotaReserve: params.quotaReserve
-			}));
-		});
+			}), at);
+		} catch (e) {
+			return sdkErr(unexpectedFailure(e));
+		}
 	}
 	/**
 	* {@inheritDoc IOpportunitiesPrepare.depositStrategy}
@@ -278,19 +214,11 @@ var PrepareApi = class extends MultichainConstruct {
 	* {@inheritDoc IOpportunitiesPrepare.maxWithdraw}
 	**/
 	async maxWithdraw(position) {
-		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
-				})
-			};
+		const sdk = await this.#chain(position.chainId);
+		const creditAccount = await this.#account(sdk, position);
+		return service(sdk).maxWithdraw({
+			creditAccount,
+			sdk
 		});
 	}
 	/**
@@ -308,19 +236,11 @@ var PrepareApi = class extends MultichainConstruct {
 	* {@inheritDoc IOpportunitiesPrepare.maxRepay}
 	**/
 	async maxRepay(position) {
-		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
-				})
-			};
+		const sdk = await this.#chain(position.chainId);
+		const creditAccount = await this.#account(sdk, position);
+		return service(sdk).maxRepay({
+			creditAccount,
+			sdk
 		});
 	}
 	/**
@@ -377,75 +297,92 @@ var PrepareApi = class extends MultichainConstruct {
 	* {@inheritDoc IOpportunitiesPrepare.maxWithdrawCollateral}
 	**/
 	async maxWithdrawCollateral(position, 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
-				})
-			};
+		const sdk = await this.#chain(position.chainId);
+		const creditAccount = await this.#account(sdk, position);
+		return service(sdk).maxWithdrawCollateral({
+			creditAccount,
+			sdk,
+			token,
+			targetHF
 		});
 	}
 	/**
-	* Shared path of the two flows that sell a position asset, and therefore have
-	* two routes to offer: one account read, one intent, both routes quoted.
+	* The account a bare `max*` read weighs. These reads answer a number, not
+	* an envelope, so an account the markets do not hold is thrown rather than
+	* described, see {@link IOpportunitiesPrepare.maxWithdraw}.
+	**/
+	async #account(sdk, position) {
+		const creditAccount = await slice(sdk, position.creditAccount);
+		if (!creditAccount) throw new Error(creditAccountNotFound(position.creditAccount).message);
+		return creditAccount;
+	}
+	/**
+	* Shared path of the two flows that sell a position asset, and therefore
+	* have two routes to offer: one account read, one intent, both routes
+	* quoted. Every refusal, the crash wrap included, carries `refused` so a
+	* form can say which routes were ruled out and why.
+	*
+	* @typeParam X - The codes the calling flow can raise beyond the shared
+	* ones, per the engine trace its signature spells out.
 	**/
 	async #startRoutes(position, options, intent) {
 		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
-					}));
-				}
-			});
+			const sdk = await this.#chain(position.chainId);
+			const at = stateBlock(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
+			}), at);
 		} catch (e) {
-			return {
-				data: neitherRoute(unexpectedFailure(e)),
-				meta: { chains: [failedChain(position.chainId, e)] }
-			};
+			return neitherRoute(unexpectedFailure(e));
 		}
 	}
 	/**
 	* Shared path of the five flows that act on an existing account: read the
-	* account, then run the intent through the engine.
+	* account, then run the intent through the engine. Whatever the chain or
+	* the engine throws on the way is described as `unexpectedFailure` instead
+	* of escaping, so the flow always answers.
+	*
+	* @typeParam X - The codes the calling flow can raise beyond the shared
+	* ones, per the engine trace its signature spells out.
 	**/
 	async #startIntent(position, options, intent) {
-		return this.#answer(position.chainId, async (sdk) => {
+		try {
+			const sdk = await this.#chain(position.chainId);
+			const at = stateBlock(sdk);
 			const creditAccount = await slice(sdk, position.creditAccount);
-			if (!creditAccount) return {
-				success: false,
-				error: creditAccountNotFound(position.creditAccount)
-			};
+			if (!creditAccount) return sdkErr(creditAccountNotFound(position.creditAccount));
 			return planned(await service(sdk).startIntent({
 				intent,
 				creditAccount,
 				sdk,
 				slippage: options.slippage,
 				quotaReserve: options.quotaReserve
-			}));
-		});
+			}), at);
+		} catch (e) {
+			return sdkErr(unexpectedFailure(e));
+		}
 	}
 };
 function service(sdk) {
 	return new CreditAccountOperationsService(sdk);
 }
 /**
+* Reads the block the SDK's loaded state stands at — the same state every
+* preparation below is computed from, so it is the block the result reports.
+**/
+function stateBlock(sdk) {
+	return {
+		blockNumber: Number(sdk.currentBlock),
+		timestamp: Number(sdk.timestamp)
+	};
+}
+/**
 * 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.
@@ -485,89 +422,59 @@ function toClaimableWithdrawal(claimable) {
 	};
 }
 /**
+* The engine's refusal as one flow's failure half.
+*
+* The engine answers with the open union of every reason it can raise
+* anywhere; which of them a given flow actually reaches is the engine trace
+* written into the public signatures. This cast is the one place the open
+* union is narrowed onto them — a code added to or removed from a flow has to
+* move its signature, which `types.test-d.ts` pins.
+**/
+function refusal(issue) {
+	return sdkErr(toRefusalError(issue));
+}
+/**
 * 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
-			}
+	return sdkErr({
+		...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
-* is the usual way of it; both are present where a pair exists but nothing of
-* ours implements it.
-**/
-function unroutable(sdk, from, 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}.
+* operation comes to under `data`, stamped with the block it was computed
+* from, or the refusal as an error carrying its own numbers, see
+* {@link refusal}.
 *
 * 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)
-	};
+function planned(result, at) {
+	if (!result.ok) return refusal(result);
 	const { operations, state, calls } = result;
-	return {
-		success: true,
-		data: {
-			operations,
-			state,
-			calls
-		}
-	};
+	return sdkOk({
+		operations,
+		state,
+		calls,
+		...at
+	});
 }
 /**
 * {@inheritDoc planned}
 **/
-function opened(result) {
-	return result.ok ? {
-		success: true,
-		data: { state: result.state }
-	} : {
-		success: false,
-		error: toPrepareError(result)
-	};
+function opened(result, at) {
+	return result.ok ? sdkOk({
+		state: result.state,
+		...at
+	}) : refusal(result);
 }
 /**
 * {@inheritDoc planned}
@@ -576,40 +483,53 @@ function opened(result) {
 * 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) {
+function routed(result, at) {
 	if (!result.ok) {
 		const { refused, ...issue } = result;
-		return {
-			success: false,
-			error: {
-				...toPrepareError(issue),
-				refused
-			}
-		};
+		return sdkErr({
+			...toRefusalError(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
+	return sdkOk({
+		instant: instant && {
+			operations: instant.operations,
+			state: instant.state,
+			calls: instant.calls,
+			...at
+		},
+		delayed: delayed && {
+			operations: delayed.operations,
+			state: delayed.state,
+			calls: delayed.calls,
+			delayed: delayed.delayed,
+			...at
+		},
+		refused,
+		...at
+	});
+}
+/**
+* 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
+* is the usual way of it; both are present where a pair exists but nothing of
+* ours implements it.
+**/
+function unroutable(sdk, from, to) {
+	return sdkErr(toRefusalError({
+		reason: "unsupportedTokenPair",
+		detail: {
+			from: toToken(sdk, from),
+			to: to === void 0 ? void 0 : toToken(sdk, to)
 		}
-	};
+	}));
 }
 /**
 * Picks the route the operation takes out of `tokenIn`, as a value rather than
 * an exception: an unroutable or ambiguous pair is a request the caller can
-* fix, so it belongs in the `ok: false` half alongside the strategy refusals.
+* fix, so it belongs in the failure half alongside the strategy refusals.
 *
 * A pool with no route out of the input reports it by throwing, hence the
 * catch; a requested output is checked against the list rather than trusted,

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

@@ -34,8 +34,11 @@ const MESSAGES = {
 * {@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.
+*
+* Generic over the issue it is handed, so a call site that already knows the
+* reason gets that reason's error back rather than a union to narrow again.
 **/
-function toPrepareError(issue) {
+function toRefusalError(issue) {
 	if (issue.reason === "malformedTransaction") return {
 		code: "malformedTransaction",
 		message: MESSAGES.malformedTransaction,
@@ -83,4 +86,4 @@ function unexpectedFailure(thrown) {
 	};
 }
 //#endregion
-export { creditAccountNotFound, noStrategyTargetCollateral, toPrepareError, unexpectedFailure };
+export { creditAccountNotFound, noStrategyTargetCollateral, toRefusalError, unexpectedFailure };

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

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