@gearbox-protocol/sdk 15.0.0 → 15.1.0-next.2

package/dist/esm/preview/preview/previewCloseOrRepayCreditAccount.js

@@ -0,0 +1,65 @@
+import { AP_WETH_TOKEN } from "../../sdk/constants/address-provider.js";
+import "../../sdk/constants/math.js";
+import "../../sdk/index.js";
+import { classifyCloseOrRepay } from "./detectCloseOrRepay.js";
+import { replayMulticall } from "./replayMulticall.js";
+import { unwrapNativeCollateral } from "./unwrapNativeCollateral.js";
+//#region src/preview/preview/previewCloseOrRepayCreditAccount.ts
+async function previewCloseOrRepayCreditAccount(input, operation, permanent, options) {
+	const { sdk } = input;
+	const market = sdk.marketRegister.findByCreditManager(operation.creditManager);
+	const exitTokens = [market.underlying];
+	const meta = sdk.tokensMeta.get(market.underlying);
+	if (meta && sdk.tokensMeta.isRWAUnderlying(meta)) exitTokens.push(meta.asset);
+	const replay = await replayMulticall(sdk, operation, options);
+	return classifyCloseOrRepay(operation.multicall, exitTokens) === "close" ? previewCloseCreditAccount(input, operation, permanent, replay) : previewRepayCreditAccount(input, operation, permanent, replay);
+}
+/**
+* Previews a credit account closure: all collateral is swapped into
+* underlying, the debt is fully repaid and the remaining underlying is
+* withdrawn to the user.
+*/
+function previewCloseCreditAccount(input, operation, permanent, replay) {
+	const { sdk } = input;
+	const market = sdk.marketRegister.findByCreditManager(operation.creditManager);
+	const { after, error } = replay;
+	let receivedToken = market.underlying;
+	for (const m of operation.multicall) if (m.operation === "WithdrawCollateral" && m.amount === 115792089237316195423570985008687907853269984665640564039457584007913129639935n) {
+		receivedToken = m.token;
+		break;
+	}
+	return {
+		operation: "CloseCreditAccount",
+		permanent,
+		creditManager: operation.creditManager,
+		creditAccount: operation.creditAccount,
+		receivedAmount: {
+			token: receivedToken,
+			balance: after.collateralWithdrawn.getOrZero(receivedToken)
+		},
+		error
+	};
+}
+/**
+* Previews a credit account repayment: the debt is fully repaid (topped up
+* from the wallet when needed) and collateral is returned to the user
+* in-kind.
+*/
+function previewRepayCreditAccount(input, operation, permanent, replay) {
+	const { sdk, value = 0n } = input;
+	const { before, after, error: replayError } = replay;
+	const { assets: collateralAdded, error: unwrapError } = unwrapNativeCollateral(after.collateralAdded.toAssets(), value, sdk.addressProvider.getAddress(AP_WETH_TOKEN, 0));
+	const error = replayError ?? unwrapError;
+	return {
+		operation: "RepayCreditAccount",
+		permanent,
+		creditManager: operation.creditManager,
+		creditAccount: operation.creditAccount,
+		collateralAdded,
+		debtRepaid: before.totalDebt - after.account.totalDebt,
+		collateralWithdrawn: after.collateralWithdrawn.toAssets(),
+		error
+	};
+}
+//#endregion
+export { previewCloseOrRepayCreditAccount };

package/dist/esm/preview/preview/previewOpenCreditAccount.js

@@ -0,0 +1,56 @@
+import { AP_WETH_TOKEN } from "../../sdk/constants/address-provider.js";
+import "../../sdk/index.js";
+import { ERROR_UNPRICEABLE_TOKEN } from "./types.js";
+import { CreditAccountState } from "./CreditAccountState.js";
+import { makeReplayState, replayInnerOperations } from "./replayInnerOperations.js";
+import { unwrapNativeCollateral } from "./unwrapNativeCollateral.js";
+//#region src/preview/preview/previewOpenCreditAccount.ts
+async function previewOpenCreditAccount(input, operation) {
+	const { sdk, value = 0n } = input;
+	const market = sdk.marketRegister.findByCreditManager(operation.creditManager);
+	const state = makeReplayState(CreditAccountState.beforeOpen(operation.creditManager, market.underlying));
+	let error = await replayInnerOperations(sdk, operation.multicall, state);
+	const account = state.account;
+	let priceError;
+	const collateralValue = state.collateralAdded.sum((token, balance) => {
+		try {
+			return market.priceOracle.convert(token, market.underlying, balance);
+		} catch {
+			priceError ??= {
+				code: ERROR_UNPRICEABLE_TOKEN,
+				message: `cannot price token ${token}`
+			};
+			return 0n;
+		}
+	});
+	const { assets: collateral, error: unwrapError } = unwrapNativeCollateral(state.collateralAdded.toAssets(), value, sdk.addressProvider.getAddress(AP_WETH_TOKEN, 0));
+	error ??= unwrapError ?? priceError;
+	const assets = account.balances.toAssets(1n);
+	return {
+		operation: operation.operation,
+		creditManager: operation.creditManager,
+		target: inferTargetAsset(operation.multicall, account.balances),
+		collateral,
+		collateralValue,
+		debt: account.debt,
+		quotas: account.quotas.toAssets(0n),
+		assets,
+		error
+	};
+}
+/**
+* Infers the strategy target token of an account opening: the first quoted
+* token (first `UpdateQuota` with a positive change), with its balance taken
+* from the computed assets. Returns `undefined` when nothing is quoted.
+*/
+function inferTargetAsset(multicall, balances) {
+	for (const op of multicall) if (op.operation === "UpdateQuota" && op.change > 0n) {
+		const balance = balances.get(op.token);
+		return balance ? {
+			token: op.token,
+			balance
+		} : void 0;
+	}
+}
+//#endregion
+export { previewOpenCreditAccount };

package/dist/esm/preview/preview/previewOperation.js

@@ -0,0 +1,76 @@
+import { parseOperationCalldata } from "../parse/parseOperationCalldata.js";
+import { isPoolOperation } from "../parse/types.js";
+import "../parse/index.js";
+import { buildDelayedPreview } from "./buildDelayedPreview.js";
+import { isCloseOrRepay } from "./detectCloseOrRepay.js";
+import { resolveDelayedClaimIntent } from "./detectDelayedClaim.js";
+import { detectDelayedOperation } from "./detectDelayedOperation.js";
+import { UnsupportedOperationError } from "./errors.js";
+import { replayMulticall } from "./replayMulticall.js";
+import { previewAdjustCreditAccount } from "./previewAdjustCreditAccount.js";
+import { previewCloseOrRepayCreditAccount } from "./previewCloseOrRepayCreditAccount.js";
+import { previewOpenCreditAccount } from "./previewOpenCreditAccount.js";
+import { previewPoolOperation } from "./previewPoolOperation.js";
+//#region src/preview/preview/previewOperation.ts
+/**
+* Previews a raw operation calldata: decodes it into a typed operation and
+* assembles an operation-specific, human-displayable preview.
+*/
+async function previewOperation(input, options) {
+	const operation = parseOperationCalldata(input);
+	if (isPoolOperation(operation)) return previewPoolOperation(input, operation, options);
+	if (operation.operation === "OpenCreditAccount" || operation.operation === "RWAOpenCreditAccount") return previewOpenCreditAccount(input, operation);
+	if (operation.operation === "CloseCreditAccount") {
+		const resolved = await resolveCreditAccount(input, operation, options);
+		const preview = await previewCloseOrRepayCreditAccount(input, operation, true, resolved);
+		preview.intent = await resolveDelayedClaimIntent(input.sdk, operation.multicall, options?.blockNumber);
+		return preview;
+	}
+	if (operation.operation === "MultiCall" || operation.operation === "BotMulticall" || operation.operation === "RWAMulticall") return previewMulticallOperation(input, operation, await resolveCreditAccount(input, operation, options));
+	throw new UnsupportedOperationError(operation.operation);
+}
+/**
+* Resolves the pre-state of the credit account an operation targets: uses the
+* state provided via options when present, otherwise fetches it from the
+* credit account compressor.
+*/
+async function resolveCreditAccount(input, operation, options) {
+	let creditAccount = options?.creditAccount;
+	if (!creditAccount) creditAccount = await input.sdk.accounts.getCreditAccountData(operation.creditAccount, options?.blockNumber);
+	if (!creditAccount) throw new Error(`credit account ${operation.creditAccount} not found`);
+	return {
+		...options,
+		creditAccount
+	};
+}
+/**
+* Previews a plain/bot/RWA multicall: classifies the instant preview
+* (zero-debt closure/repay vs adjustment) and, when the multicall requests a
+* delayed withdrawal, wraps the instant preview into a
+* `DelayedCreditAccountOperation` together with the best-effort preview of
+* the state after the withdrawal is claimed.
+*/
+async function previewMulticallOperation(input, operation, options) {
+	const { sdk } = input;
+	const instantPreview = isCloseOrRepay(operation.multicall) ? await previewCloseOrRepayCreditAccount(input, operation, false, options) : await previewAdjustCreditAccount(input, operation, options);
+	const delayed = detectDelayedOperation(sdk, operation.multicall);
+	if (!delayed) {
+		instantPreview.intent = await resolveDelayedClaimIntent(sdk, operation.multicall, options?.blockNumber);
+		return instantPreview;
+	}
+	const { before, after } = await replayMulticall(sdk, operation, options);
+	const market = sdk.marketRegister.findByCreditManager(operation.creditManager);
+	const convert = (token, to, amount) => market.priceOracle.convert(token, to, amount);
+	const meta = sdk.tokensMeta.get(market.underlying);
+	const receivedToken = meta && sdk.tokensMeta.isRWAUnderlying(meta) ? meta.asset : market.underlying;
+	return {
+		operation: "DelayedCreditAccountOperation",
+		creditAccount: operation.creditAccount,
+		creditManager: operation.creditManager,
+		intent: delayed.intent,
+		instantPreview,
+		delayedPreview: buildDelayedPreview(after.account, before, delayed, convert, receivedToken)
+	};
+}
+//#endregion
+export { previewOperation };

package/dist/esm/preview/preview/previewPoolOperation.js

@@ -0,0 +1,27 @@
+import { simulatePoolOperation } from "../simulate/simulatePoolOperation.js";
+import "../simulate/index.js";
+//#region src/preview/preview/previewPoolOperation.ts
+async function previewPoolOperation(input, operation, options) {
+	const { sdk, to, calldata } = input;
+	const { tokenIn, tokenOut } = operation;
+	const sim = await simulatePoolOperation({
+		sdk,
+		operation,
+		to,
+		calldata
+	}, options);
+	return {
+		operation: operation.operation,
+		pool: operation.pool,
+		tokenIn: {
+			token: tokenIn,
+			balance: sim.amountIn
+		},
+		tokenOut: {
+			token: tokenOut,
+			balance: sim.amountOut
+		}
+	};
+}
+//#endregion
+export { previewPoolOperation };

package/dist/esm/preview/preview/replayInnerOperations.js

@@ -0,0 +1,144 @@
+import { AssetsMap } from "../../sdk/utils/AssetsMap.js";
+import "../../sdk/constants/math.js";
+import "../../sdk/index.js";
+import { AbstractAdapterContract } from "../../plugins/adapters/contracts/AbstractAdapter.js";
+import { ERC4626AdapterContract } from "../../plugins/adapters/contracts/ERC4626AdapterContract.js";
+import "../../plugins/adapters/index.js";
+import { ERROR_ADAPTER_CALL_OUTSIDE_BRACKET, ERROR_MALFORMED_BRACKET, ERROR_NON_ADAPTER_CALL_IN_BRACKET, ERROR_UNPREVIEWABLE_ADAPTER_CALL, ERROR_UNPREVIEWABLE_RWA_WRAP_UNWRAP } from "./types.js";
+import { applyRWAWrapUnwrap } from "./applyRWAWrapUnwrap.js";
+//#region src/preview/preview/replayInnerOperations.ts
+/**
+* Creates a {@link ReplayState} around the given account seed, with empty
+* bookkeeping.
+*/
+function makeReplayState(account) {
+	return {
+		account,
+		collateralAdded: new AssetsMap(),
+		collateralWithdrawn: new AssetsMap()
+	};
+}
+/**
+* Replays a credit-facade multicall over `state`, mutating it in place in
+* facade execution order. The result is the *minimal guaranteed* post-state.
+*
+* The function assumes that the call was generated by our frontend using
+* router/withdrawal compressor, otherwise it returns an error, but still
+* proceeds best-effort.
+*
+* @returns `undefined` on success, the error on a malformed multicall.
+*/
+async function replayInnerOperations(sdk, multicall, state) {
+	let inBracket = false;
+	let error;
+	for (const op of multicall) {
+		let opError;
+		switch (op.operation) {
+			case "AddCollateral":
+				applyAddCollateral(state, op);
+				break;
+			case "WithdrawCollateral":
+				applyWithdrawCollateral(state, op);
+				break;
+			case "IncreaseBorrowedAmount":
+				state.account.increaseDebt(op.amount);
+				break;
+			case "DecreaseBorrowedAmount":
+				state.account.repay(op.amount);
+				break;
+			case "UpdateQuota":
+				state.account.updateQuota(op.token, op.change);
+				break;
+			case "StoreExpectedBalances":
+				if (inBracket) opError = {
+					code: ERROR_MALFORMED_BRACKET,
+					message: "nested storeExpectedBalances/compareBalances bracket"
+				};
+				inBracket = true;
+				for (const { token, balance } of op.deltas) state.account.balances.inc(token, balance);
+				break;
+			case "CompareBalances":
+				if (!inBracket) opError = {
+					code: ERROR_MALFORMED_BRACKET,
+					message: "compareBalances without a preceding storeExpectedBalances"
+				};
+				inBracket = false;
+				break;
+			case "Execute": opError = await applyExecute(sdk, op, inBracket, state.account.balances);
+		}
+		error ??= opError;
+	}
+	if (inBracket) error ??= {
+		code: ERROR_MALFORMED_BRACKET,
+		message: "storeExpectedBalances without a matching compareBalances"
+	};
+	return error;
+}
+function applyAddCollateral(state, op) {
+	state.collateralAdded.inc(op.token, op.amount);
+	state.account.balances.inc(op.token, op.amount);
+}
+/**
+* `MAX_UINT256` is the facade sentinel for "withdraw the entire balance", so
+* it is resolved against the running balance at the point of the call.
+*/
+function applyWithdrawCollateral(state, op) {
+	const running = state.account.balances.getOrZero(op.token);
+	const amount = op.amount === 115792089237316195423570985008687907853269984665640564039457584007913129639935n ? running > 0n ? running : 0n : op.amount;
+	state.account.balances.dec(op.token, amount);
+	state.collateralWithdrawn.inc(op.token, amount);
+}
+/**
+* Replays an adapter `Execute` call against the running balances.
+*
+* Inside a bracket, the adapter's balance changes are previewed via
+* {@link AbstractAdapterContract.previewBalanceChanges}. Outside a bracket,
+* only RWA wrap/unwrap calls are allowed (see {@link applyRWAWrapUnwrap});
+* nothing enforces the outcome of any other out-of-bracket adapter call
+* on-chain, so its effect on balances cannot be previewed.
+*/
+async function applyExecute(sdk, op, inBracket, balances) {
+	const adapter = sdk.getContract(op.adapter);
+	if (!inBracket) {
+		if (!isRWAShare(sdk, adapter)) return {
+			code: ERROR_ADAPTER_CALL_OUTSIDE_BRACKET,
+			message: `call to ${op.adapter} outside of a storeExpectedBalances/compareBalances bracket`
+		};
+		try {
+			applyRWAWrapUnwrap(adapter, op.calldata, balances);
+			return;
+		} catch (e) {
+			return {
+				code: ERROR_UNPREVIEWABLE_RWA_WRAP_UNWRAP,
+				message: e instanceof Error ? e.message : String(e)
+			};
+		}
+	}
+	if (!(adapter instanceof AbstractAdapterContract)) return {
+		code: ERROR_NON_ADAPTER_CALL_IN_BRACKET,
+		message: `call to ${op.adapter} between storeExpectedBalances and compareBalances is not an adapter call`
+	};
+	try {
+		await adapter.previewBalanceChanges(balances, op.calldata);
+		return;
+	} catch (e) {
+		return {
+			code: ERROR_UNPREVIEWABLE_ADAPTER_CALL,
+			message: e instanceof Error ? e.message : String(e)
+		};
+	}
+}
+/**
+* True when the ERC4626 adapter converts an RWA underlying, i.e. it is the
+* wrap/unwrap adapter of an RWA market rather than a regular vault strategy
+* adapter.
+*/
+function isRWAShare(sdk, adapter) {
+	if (adapter instanceof ERC4626AdapterContract) {
+		const meta = sdk.tokensMeta.get(adapter.share);
+		return !!meta && sdk.tokensMeta.isRWAUnderlying(meta);
+	}
+	return false;
+}
+//#endregion
+export { makeReplayState, replayInnerOperations };

package/dist/esm/preview/preview/replayMulticall.js

@@ -0,0 +1,18 @@
+import { CreditAccountState } from "./CreditAccountState.js";
+import { makeReplayState, replayInnerOperations } from "./replayInnerOperations.js";
+//#region src/preview/preview/replayMulticall.ts
+/**
+* Replays the operation's multicall over the account's pre-resolved
+* pre-state (`options.creditAccount`) via {@link replayInnerOperations}.
+*/
+async function replayMulticall(sdk, operation, options) {
+	const before = CreditAccountState.fromCreditAccountData(options.creditAccount);
+	const after = makeReplayState(before.clone());
+	return {
+		before,
+		after,
+		error: await replayInnerOperations(sdk, operation.multicall, after)
+	};
+}
+//#endregion
+export { replayMulticall };

package/dist/esm/preview/preview/types.js

@@ -0,0 +1,35 @@
+//#region src/preview/preview/types.ts
+/**
+* Broken `storeExpectedBalances`/`compareBalances` bracket structure:
+* `storeExpectedBalances` without a matching `compareBalances`, nested
+* brackets, or `compareBalances` without a preceding `storeExpectedBalances`.
+* We expect transactions that were generated by our frontend using router/withdrawal compressor
+**/
+const ERROR_MALFORMED_BRACKET = 1001;
+/**
+* Adapter call outside a `storeExpectedBalances`/`compareBalances` bracket
+* We expect transactions that were generated by our frontend using router/withdrawal compressor,
+**/
+const ERROR_ADAPTER_CALL_OUTSIDE_BRACKET = 1002;
+/**
+* Bracketed call whose target is not an adapter (or adapter that is not known to the SDK)
+**/
+const ERROR_NON_ADAPTER_CALL_IN_BRACKET = 1003;
+/**
+* Bracketed adapter call cannot be replayed (undecodable/unsupported calldata)
+**/
+const ERROR_UNPREVIEWABLE_ADAPTER_CALL = 1004;
+/**
+* Out-of-bracket RWA wrap/unwrap calldata cannot be decoded
+**/
+const ERROR_UNPREVIEWABLE_RWA_WRAP_UNWRAP = 1005;
+/**
+* `msg.value` does not fit into the declared WETH collateral
+* Transactions can have arbitrary value, but the ones that we create
+* using our frontend should have a value that fits into the declared WETH collateral.
+**/
+const ERROR_INVALID_TRANSACTION_VALUE = 1006;
+/** A token in the preview could not be priced by the oracle */
+const ERROR_UNPRICEABLE_TOKEN = 2001;
+//#endregion
+export { ERROR_ADAPTER_CALL_OUTSIDE_BRACKET, ERROR_INVALID_TRANSACTION_VALUE, ERROR_MALFORMED_BRACKET, ERROR_NON_ADAPTER_CALL_IN_BRACKET, ERROR_UNPREVIEWABLE_ADAPTER_CALL, ERROR_UNPREVIEWABLE_RWA_WRAP_UNWRAP, ERROR_UNPRICEABLE_TOKEN };

package/dist/esm/preview/preview/unwrapNativeCollateral.js

@@ -0,0 +1,43 @@
+import { AssetsMap } from "../../sdk/utils/AssetsMap.js";
+import { NATIVE_ADDRESS } from "../../sdk/constants/addresses.js";
+import "../../sdk/index.js";
+import { ERROR_INVALID_TRANSACTION_VALUE } from "./types.js";
+//#region src/preview/preview/unwrapNativeCollateral.ts
+/**
+* Represents the transaction's attached native value as a `NATIVE_ADDRESS`
+* entry in the collateral list.
+*
+* The credit facade wraps `msg.value` into WETH before `AddCollateral(WETH)`
+* pulls it, so the WETH collateral amount already includes the attached native
+* value. This helper splits the WETH entry back: the native amount is shown as
+* `NATIVE_ADDRESS` and the WETH entry is reduced accordingly (dropped when it
+* reaches zero). Other entries are preserved.
+*
+* When `nativeAmount` is positive but the WETH collateral is missing or
+* smaller than it, the transaction is malformed: the collateral is returned
+* as-is (no unwrapping) together with an `ERROR_INVALID_TRANSACTION_VALUE`
+* error.
+*
+* @param collateral - Collateral assets as declared by the multicall.
+* @param nativeAmount - Transaction `msg.value`.
+* @param wethToken - Wrapped native token address.
+* @returns Collateral with the native amount unwrapped from the WETH entry,
+* plus the error on a malformed transaction value.
+*/
+function unwrapNativeCollateral(collateral, nativeAmount, wethToken) {
+	if (nativeAmount === 0n) return { assets: collateral };
+	const balances = new AssetsMap(collateral);
+	const wethBalance = balances.get(wethToken) ?? 0n;
+	if (wethBalance < nativeAmount) return {
+		assets: collateral,
+		error: {
+			code: ERROR_INVALID_TRANSACTION_VALUE,
+			message: `transaction value ${nativeAmount} exceeds WETH collateral ${wethBalance}`
+		}
+	};
+	balances.upsert(wethToken, wethBalance === nativeAmount ? void 0 : wethBalance - nativeAmount);
+	balances.inc(NATIVE_ADDRESS, nativeAmount);
+	return { assets: balances.toAssets() };
+}
+//#endregion
+export { unwrapNativeCollateral };

package/dist/esm/preview/simulate/errors.js

@@ -0,0 +1,79 @@
+import { errorAbis } from "../../abi/errors.js";
+import { BaseError, ContractFunctionRevertedError, decodeErrorResult } from "viem";
+//#region src/preview/simulate/errors.ts
+/**
+* Error returned by the pool simulation when it fails. It wraps the flow's
+* decoded revert reason (see {@link failures}).
+*/
+var PreviewSimulationError = class extends BaseError {
+	name = "PreviewSimulationError";
+	/** Per-flow decoded failures behind this error. */
+	failures;
+	constructor(failures) {
+		const shortMessage = failures.length <= 1 ? failures[0]?.detail.reason ?? "simulation failed" : "all simulation flows failed";
+		const cause = failures.find((f) => f.detail.cause instanceof Error)?.detail.cause;
+		super(shortMessage, {
+			metaMessages: failures.map((f) => `[${f.source}] ${f.detail.reason}`),
+			cause
+		});
+		this.failures = failures;
+	}
+};
+/**
+* Normalises an unknown rejection reason into a {@link PreviewSimulationError}.
+* Pass-through when it already is one; otherwise decodes it under `source`.
+*/
+function asPreviewSimulationError(reason, source) {
+	if (reason instanceof PreviewSimulationError) return reason;
+	return new PreviewSimulationError([{
+		source,
+		detail: decodeSimulationError({ error: reason instanceof Error ? reason : new Error(String(reason)) })
+	}]);
+}
+/**
+* Decodes a simulated call revert into a {@link SimulationError}.
+*
+* We first try to decode any raw return bytes against the SDK's
+* {@link errorAbis} (Gearbox protocol exceptions plus standard ERC-20 custom
+* errors); failing that, we walk viem's error chain for a
+* {@link ContractFunctionRevertedError} (covers `Error(string)` / `Panic`).
+*/
+function decodeSimulationError(revert) {
+	const { error, data } = revert;
+	if (data && data !== "0x") try {
+		const decoded = decodeErrorResult({
+			abi: errorAbis,
+			data
+		});
+		return {
+			reason: formatDecodedError(decoded.errorName, decoded.args),
+			cause: error
+		};
+	} catch {}
+	if (error instanceof BaseError) {
+		const reverted = error.walk((e) => e instanceof ContractFunctionRevertedError);
+		if (reverted instanceof ContractFunctionRevertedError) return {
+			reason: reverted.data?.errorName ?? reverted.reason ?? reverted.shortMessage ?? "reverted",
+			cause: error
+		};
+		return {
+			reason: error.shortMessage ?? error.name,
+			cause: error
+		};
+	}
+	if (error instanceof Error) return {
+		reason: error.message,
+		cause: error
+	};
+	return {
+		reason: "reverted",
+		cause: error
+	};
+}
+/** Renders `Name` or `Name(arg0, arg1)` for a decoded custom error. */
+function formatDecodedError(errorName, args) {
+	if (!args || args.length === 0) return errorName;
+	return `${errorName}(${args.map((arg) => String(arg)).join(", ")})`;
+}
+//#endregion
+export { PreviewSimulationError, asPreviewSimulationError, decodeSimulationError };

package/dist/esm/preview/simulate/index.js

@@ -0,0 +1,6 @@
+import { PreviewSimulationError } from "./errors.js";
+import { simulateFacadeOperation } from "./simulateFacadeOperation.js";
+import { simulatePoolOperation } from "./simulatePoolOperation.js";
+import { simulateRWAOperation } from "./simulateRWAOperation.js";
+import { simulateOperation } from "./simulateOperation.js";
+export { PreviewSimulationError, simulateFacadeOperation, simulateOperation, simulatePoolOperation, simulateRWAOperation };

package/dist/esm/preview/simulate/simulateFacadeOperation.js

@@ -0,0 +1,14 @@
+//#region src/preview/simulate/simulateFacadeOperation.ts
+/**
+* Simulates a credit-facade operation.
+*
+* Not yet implemented: credit-facade simulation requires multicall-aware
+* balance/transfer accounting that the pool simulation does not cover. The
+* signature mirrors {@link simulatePoolOperation} so the
+* {@link simulateOperation} wrapper can delegate uniformly once implemented.
+*/
+async function simulateFacadeOperation(_input, _options) {
+	throw new Error("not yet implemented");
+}
+//#endregion
+export { simulateFacadeOperation };

package/dist/esm/preview/simulate/simulateOperation.js

@@ -0,0 +1,26 @@
+import { isPoolOperation, isRWAOperation } from "../parse/types.js";
+import "../parse/index.js";
+import { simulateFacadeOperation } from "./simulateFacadeOperation.js";
+import { simulatePoolOperation } from "./simulatePoolOperation.js";
+import { simulateRWAOperation } from "./simulateRWAOperation.js";
+//#region src/preview/simulate/simulateOperation.ts
+/**
+* Simulates a parsed pool or credit account operation
+*/
+async function simulateOperation(input, options) {
+	const { operation } = input;
+	if (isPoolOperation(operation)) return simulatePoolOperation({
+		...input,
+		operation
+	}, options);
+	if (isRWAOperation(operation)) return simulateRWAOperation({
+		...input,
+		operation
+	}, options);
+	return simulateFacadeOperation({
+		...input,
+		operation
+	}, options);
+}
+//#endregion
+export { simulateOperation };