@gearbox-protocol/sdk 14.12.0-next.65 → 14.12.0-next.67

package/dist/esm/new-sdk/AbstractNamespace.js

@@ -0,0 +1,157 @@
+import { getNetworkType } from "../sdk/chain/chains.js";
+import { AllSourcesFailedError } from "./types.js";
+//#region src/new-sdk/AbstractNamespace.ts
+/**
+* Shared machinery of every {@link GearboxSDK} namespace.
+*
+* A namespace is a stateless router: it asks the sources its mode allows, in
+* parallel, merges what came back and reports what did not. This class owns
+* that routing — per-chain failure capture, backend degradation, the response
+* envelope and the all-sources-failed rule — so a namespace holds nothing but
+* its reads and its merge policy.
+*
+* The sources are whatever it was handed, and their readiness is their owner's
+* business: a source that is not ready to answer fails the read it was given,
+* and that failure is reported like any other.
+*
+* All protocol knowledge lives in the sources: `MultichainSDK` for the chain,
+* `GearboxAPI` for the backend. None of it is repeated here or in a subclass.
+*
+* @typeParam ListRow - Row type of the namespace's list read.
+**/
+var AbstractNamespace = class {
+	logger;
+	#onchain;
+	#offchain;
+	constructor(name, onchain, offchain, logger) {
+		this.#onchain = onchain;
+		this.#offchain = offchain;
+		this.logger = logger?.child?.({ name }) ?? logger;
+	}
+	/**
+	* Asks both sources in parallel and combines whatever answered.
+	*
+	* The action name is only used in diagnostics and in the error raised when
+	* every source the read had failed.
+	**/
+	async read(action, fromChain, fromBackend, combine) {
+		const [onchain, offchain] = await Promise.all([this.fromChain(fromChain), this.fromBackend(fromBackend)]);
+		const meta = toMeta(onchain, offchain);
+		this.assertAnySourceSucceeded(action, meta);
+		return {
+			result: combine(onchain.value, offchain.value),
+			meta
+		};
+	}
+	/**
+	* Reads the namespace's list from both sources, unioned by
+	* {@link AbstractNamespace.mergeList}.
+	**/
+	async readList(action, fromChain, fromBackend) {
+		return this.read(action, fromChain, fromBackend, (onchain, offchain) => this.mergeList(onchain ?? [], offchain ?? []));
+	}
+	/**
+	* Reads one row from both sources and merges them under
+	* {@link AbstractNamespace.mergeOne}. The key names the chain, so the
+	* on-chain leg queries exactly one.
+	**/
+	async readOne(action, chainId, fromChain, fromBackend) {
+		return this.read(action, async (sdk) => {
+			const network = this.networkOf(chainId);
+			if (!network) return { chains: [] };
+			return this.onOneChain(action, network, () => fromChain(sdk));
+		}, fromBackend, (onchain, offchain) => {
+			if (onchain && offchain) return this.mergeOne(onchain, offchain);
+			return onchain ?? offchain;
+		});
+	}
+	/**
+	* Reads something only the backend can answer.
+	*
+	* The fallback stands in for a backend that answered with nothing, which is
+	* a different thing from a backend that failed and was dropped.
+	**/
+	async readOffchain(action, fromBackend, fallback) {
+		const offchain = await this.fromBackend(fromBackend);
+		const meta = toMeta({ chains: [] }, offchain);
+		this.assertAnySourceSucceeded(action, meta);
+		return {
+			result: offchain.value ?? fallback,
+			meta
+		};
+	}
+	/**
+	* Runs a read against the chain, or reports the chain as absent when the
+	* namespace has no on-chain source at all.
+	**/
+	async fromChain(run) {
+		return this.#onchain ? run(this.#onchain) : { chains: [] };
+	}
+	/**
+	* Runs a read against the backend, turning any rejection into metadata so
+	* that a dead backend degrades a `both`-mode read instead of failing it.
+	**/
+	async fromBackend(run) {
+		if (!this.#offchain) return {};
+		try {
+			const { result, meta } = await run(this.#offchain);
+			return {
+				value: meta.status === "success" ? result : void 0,
+				status: meta
+			};
+		} catch (error) {
+			this.logger?.warn(error, "offchain read failed");
+			return { status: {
+				status: "error",
+				error
+			} };
+		}
+	}
+	/**
+	* Runs a read against one chain, turning a rejection into that chain's
+	* metadata entry.
+	**/
+	async onOneChain(action, network, run) {
+		try {
+			return {
+				value: await run(),
+				chains: [{
+					network,
+					status: "success"
+				}]
+			};
+		} catch (error) {
+			this.logger?.warn(error, `failed to ${action} on ${network}`);
+			return { chains: [{
+				network,
+				status: "error",
+				error
+			}] };
+		}
+	}
+	/**
+	* A read that reached at least one source returns what it has; a read where
+	* every source it had failed throws, because an empty result would otherwise
+	* be indistinguishable from "there is nothing here".
+	**/
+	assertAnySourceSucceeded(action, meta) {
+		const asked = meta.chains.length > 0 || meta.offchain !== void 0;
+		const answered = meta.chains.some((c) => c.status === "success") || meta.offchain?.status === "success";
+		if (asked && !answered) throw new AllSourcesFailedError(action, meta);
+	}
+	networkOf(chainId) {
+		try {
+			return getNetworkType(chainId);
+		} catch {
+			this.logger?.debug(`chain ${chainId} is not a Gearbox network, skipping the onchain source`);
+			return;
+		}
+	}
+};
+function toMeta(onchain, offchain) {
+	const meta = { chains: onchain.chains };
+	if (offchain.status) meta.offchain = offchain.status;
+	return meta;
+}
+//#endregion
+export { AbstractNamespace };

package/dist/esm/new-sdk/GearboxSDK.js

@@ -0,0 +1,121 @@
+import { MultichainSDK } from "../sdk/MultichainSDK.js";
+import "../sdk/index.js";
+import { GearboxAPI } from "../offchain/GearboxAPI.js";
+import "../offchain/index.js";
+import { OpportunitiesNamespace } from "./opportunities/OpportunitiesNamespace.js";
+import "./opportunities/index.js";
+//#region src/new-sdk/GearboxSDK.ts
+/**
+* Combined entry point over both sources of Gearbox data: the chain and the
+* Gearbox backend.
+*
+* The {@link Mode} is fixed at construction and decides which methods exist,
+* not what they return, so a screen written against `both` cannot silently
+* degrade to a subset when someone reconfigures the SDK:
+*
+* ```ts
+* const sdk = new GearboxSDK({
+*   mode: "both",
+*   networks: ["Mainnet"],
+*   onchain: { chains: { Mainnet: { rpcURLs } } },
+*   offchain: { baseUrl: "https://api.gearbox.fi" },
+* });
+* await sdk.attach();
+*
+* const { result, meta } = await sdk.opportunities.list({ kind: "strategy" });
+* ```
+*
+* Every read answers with `{ result, meta }`: `meta` says which chains and
+* which backend answered, because a partial answer is the normal case for a
+* multi-chain read.
+*
+* @typeParam M - Mode the instance was built in.
+**/
+var GearboxSDK = class {
+	/**
+	* Sources this instance reads from.
+	**/
+	mode;
+	/**
+	* Chains this instance covers. Authoritative even when an injected on-chain
+	* SDK covers a different set.
+	**/
+	networks;
+	/**
+	* Namespace for pool and strategy opportunities.
+	**/
+	opportunities;
+	#attachOptions;
+	#onchain;
+	#offchain;
+	/**
+	* Whether this instance built the on-chain SDK, and therefore attaches it.
+	**/
+	#ownsOnchain = false;
+	#attached;
+	constructor(options) {
+		const { mode, networks, onchain, offchain, attach, logger } = options;
+		this.mode = mode;
+		this.networks = [...networks];
+		this.#attachOptions = attach;
+		const needsOnchain = mode === "onchain" || mode === "both";
+		const needsOffchain = mode === "offchain" || mode === "both";
+		if (needsOnchain && !onchain) throw new Error(`GearboxSDK in ${mode} mode needs an onchain source`);
+		if (needsOffchain && !offchain) throw new Error(`GearboxSDK in ${mode} mode needs an offchain source`);
+		if (!needsOnchain && onchain) logger?.warn(`GearboxSDK in ${mode} mode ignores the onchain source it was given`);
+		if (!needsOffchain && offchain) logger?.warn(`GearboxSDK in ${mode} mode ignores the offchain source it was given`);
+		if (needsOnchain && onchain) if (onchain instanceof MultichainSDK) this.#onchain = onchain;
+		else {
+			this.#onchain = new MultichainSDK({
+				logger,
+				...onchain
+			});
+			this.#ownsOnchain = true;
+		}
+		if (needsOffchain && offchain) this.#offchain = offchain instanceof GearboxAPI ? offchain : new GearboxAPI({
+			logger,
+			...offchain
+		});
+		this.#attached = !this.#ownsOnchain;
+		this.opportunities = new OpportunitiesNamespace(this.#onchain, this.#offchain, logger);
+	}
+	/**
+	* Attaches the on-chain SDK when this instance owns one.
+	*
+	* Reads issued before this resolves still reach the chain and fail there, so
+	* in `both` mode they are served from the backend alone and report the chain
+	* as failed in their meta, rather than blocking.
+	*
+	* A no-op in `offchain` mode and when an already-attached SDK was injected.
+	**/
+	async attach() {
+		if (this.#attached || !this.#ownsOnchain || !this.#onchain) return;
+		await this.#onchain.attach(this.#attachOptions);
+		this.#attached = true;
+	}
+	/**
+	* Whether the on-chain source is ready to be read from. Always `true` in
+	* `offchain` mode, where there is nothing to wait for.
+	**/
+	get attached() {
+		return this.mode === "offchain" ? true : this.#attached;
+	}
+	/**
+	* The underlying on-chain SDK, for everything this facade does not expose
+	* yet: markets, credit accounts, transaction building.
+	*
+	* `undefined` in `offchain` mode. Otherwise it exists from construction on,
+	* but only answers reads once {@link attach} has resolved.
+	**/
+	get onchain() {
+		return this.#onchain;
+	}
+	/**
+	* The underlying backend client. `undefined` in `onchain` mode.
+	**/
+	get offchain() {
+		return this.#offchain;
+	}
+};
+//#endregion
+export { GearboxSDK };

package/dist/esm/new-sdk/index.js

@@ -0,0 +1,7 @@
+import { AllSourcesFailedError } from "./types.js";
+import { AbstractNamespace } from "./AbstractNamespace.js";
+import { OpportunitiesNamespace } from "./opportunities/OpportunitiesNamespace.js";
+import "./opportunities/index.js";
+import { GearboxSDK } from "./GearboxSDK.js";
+import "./utils/index.js";
+export { AbstractNamespace, AllSourcesFailedError, GearboxSDK, OpportunitiesNamespace };

package/dist/esm/new-sdk/opportunities/OpportunitiesNamespace.js

@@ -0,0 +1,121 @@
+import { opportunityId } from "../../model/opportunities.js";
+import "../../model/index.js";
+import { AbstractNamespace } from "../AbstractNamespace.js";
+//#region src/new-sdk/opportunities/OpportunitiesNamespace.ts
+/**
+* Fields the backend owns even when the chain also fills them.
+*
+* Empty of on-chain conflicts today — every yield group here is off-chain only,
+* so onchain-first would already yield the backend's value. It is written out
+* anyway so that adding an on-chain estimate of one of them is a deliberate
+* change to this list rather than a silent regression.
+**/
+const OFFCHAIN_OWNED_FIELDS = /* @__PURE__ */ new Set(["supplyApy", "collateralApy"]);
+/**
+* The `opportunities` namespace of the combined SDK.
+*
+* A stateless router over the two sources, see {@link AbstractNamespace} for
+* the routing itself. What is specific to opportunities is the reads below and
+* the merge policy at the bottom of the class.
+*
+* The class implements the methods of every mode; {@link GearboxSDK} exposes it
+* as its mode's slice of {@link OpportunitiesByMode}, so calling a method the
+* mode does not have is a compile error rather than a runtime one.
+**/
+var OpportunitiesNamespace = class extends AbstractNamespace {
+	constructor(onchain, offchain, logger) {
+		super("Opportunities", onchain, offchain, logger);
+	}
+	/**
+	* {@inheritDoc OpportunitiesBase.list}
+	**/
+	async list(filter) {
+		return this.readList("list opportunities", async (sdk) => {
+			const { result, meta } = await sdk.opportunities.list(filter);
+			return {
+				value: result,
+				chains: meta
+			};
+		}, (api) => api.opportunities.list(filter));
+	}
+	/**
+	* {@inheritDoc OpportunitiesBase.getPool}
+	**/
+	async getPool(key) {
+		return this.readOne("get pool opportunity", key.chainId, (sdk) => sdk.opportunities.getPool(key), (api) => api.opportunities.getPool(key));
+	}
+	/**
+	* {@inheritDoc OpportunitiesBase.getStrategy}
+	**/
+	async getStrategy(key) {
+		return this.readOne("get strategy opportunity", key.chainId, (sdk) => sdk.opportunities.getStrategy(key), (api) => api.opportunities.getStrategy(key));
+	}
+	history(key) {
+		return { chart: (metric, range) => this.#chart(key, metric, range) };
+	}
+	/**
+	* Reads one chart of one opportunity from the backend.
+	*
+	* The metric a caller may name is gated by the reader's type, so the kind of
+	* the key is not re-checked here.
+	**/
+	async #chart(key, metric, range) {
+		const { result, meta } = await this.readOffchain(`get ${metric} history`, (api) => api.opportunities.getHistory({
+			opportunity: key,
+			range,
+			metric
+		}), {
+			metric,
+			points: [],
+			metadata: {}
+		});
+		return {
+			data: result.points,
+			metadata: {
+				...result.metadata,
+				source: meta
+			}
+		};
+	}
+	/**
+	* Merges the two versions of one opportunity.
+	*
+	* The chain wins every field it fills; the backend fills the rest and owns
+	* {@link OFFCHAIN_OWNED_FIELDS}.
+	*
+	* The rule is onchain-first, field-wise, and never deeper than one level: a
+	* group like `totalSupply` or `supplyApy` is taken whole from one source, so
+	* a row never mixes an on-chain token amount with a backend dollar value
+	* derived from a different block.
+	**/
+	mergeOne(onchain, offchain) {
+		const merged = { ...onchain };
+		for (const [field, value] of Object.entries(offchain)) {
+			if (value === void 0) continue;
+			if (OFFCHAIN_OWNED_FIELDS.has(field) || merged[field] === void 0) merged[field] = value;
+		}
+		return merged;
+	}
+	/**
+	* Unions the two lists by canonical opportunity id.
+	*
+	* Rows present in both are merged by {@link OpportunitiesNamespace.mergeOne}.
+	* Rows only the backend knows are appended: a chain the SDK does not cover,
+	* or a market it has not loaded, is a reason to show more rather than fewer
+	* opportunities.
+	**/
+	mergeList(onchain, offchain) {
+		const byId = /* @__PURE__ */ new Map();
+		for (const row of onchain) byId.set(opportunityId(row), row);
+		const extra = [];
+		for (const row of offchain) {
+			const id = opportunityId(row);
+			const existing = byId.get(id);
+			if (existing) byId.set(id, this.mergeOne(existing, row));
+			else extra.push(row);
+		}
+		return [...byId.values(), ...extra];
+	}
+};
+//#endregion
+export { OpportunitiesNamespace };

package/dist/esm/new-sdk/opportunities/index.js

@@ -0,0 +1,3 @@
+import { OpportunitiesNamespace } from "./OpportunitiesNamespace.js";
+import "./types.js";
+export { OpportunitiesNamespace };

package/dist/esm/new-sdk/opportunities/types.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/new-sdk/package.json

@@ -0,0 +1 @@
+{"type": "module","sideEffects":false}

package/dist/esm/new-sdk/types.js

@@ -0,0 +1,21 @@
+//#region src/new-sdk/types.ts
+/**
+* Thrown when a read had sources to ask and none of them answered.
+*
+* A read that partially succeeded never throws: it returns what it has and
+* reports the rest in {@link SourceMeta}.
+**/
+var AllSourcesFailedError = class extends Error {
+	/**
+	* Outcome of every source the failed read asked.
+	**/
+	meta;
+	constructor(action, meta) {
+		const reasons = [...meta.chains.filter((c) => c.status === "error").map((c) => `${c.network}: ${c.error}`), ...meta.offchain?.status === "error" ? [`offchain: ${meta.offchain.error}`] : []];
+		super(`cannot ${action}, every source failed (${reasons.join("; ")})`);
+		this.name = "AllSourcesFailedError";
+		this.meta = meta;
+	}
+};
+//#endregion
+export { AllSourcesFailedError };

package/dist/esm/new-sdk/utils/history.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/new-sdk/utils/index.js

@@ -0,0 +1,2 @@
+import "./history.js";
+export {};

package/dist/esm/offchain/GearboxAPI.js

@@ -0,0 +1,32 @@
+import { OffchainOpportunities } from "./opportunities/OffchainOpportunities.js";
+import "./opportunities/index.js";
+//#region src/offchain/GearboxAPI.ts
+/**
+* Client for the Gearbox backend, the off-chain source of the read model.
+*
+* It mirrors the namespace layout of the combined `GearboxSDK`, so the same
+* call reads the same way against either source:
+*
+* ```ts
+* const api = new GearboxAPI({ baseUrl: "https://api.gearbox.fi" });
+* const { result } = await api.opportunities.list({ kind: "strategy" });
+* ```
+*
+* The backend imports the read model from this package and its endpoints
+* return those types directly, so there is no wire DTO layer here — only
+* transport and schema validation.
+*
+* The transport is not implemented yet; see {@link OffchainOpportunities} for
+* what each stubbed endpoint currently answers.
+**/
+var GearboxAPI = class {
+	/**
+	* Namespace for pool and strategy opportunities.
+	**/
+	opportunities;
+	constructor(options) {
+		this.opportunities = new OffchainOpportunities(options);
+	}
+};
+//#endregion
+export { GearboxAPI };

package/dist/esm/offchain/index.js

@@ -0,0 +1,5 @@
+import { OffchainNotImplementedError, OffchainOpportunities } from "./opportunities/OffchainOpportunities.js";
+import "./opportunities/index.js";
+import { GearboxAPI } from "./GearboxAPI.js";
+import "./types.js";
+export { GearboxAPI, OffchainNotImplementedError, OffchainOpportunities };

package/dist/esm/offchain/opportunities/OffchainOpportunities.js

@@ -0,0 +1,95 @@
+//#region src/offchain/opportunities/OffchainOpportunities.ts
+/**
+* Thrown by the endpoints that have no stub answer, so that a caller in
+* `offchain` mode fails loudly instead of reading an empty detail page as a
+* missing opportunity.
+**/
+var OffchainNotImplementedError = class extends Error {
+	constructor(endpoint) {
+		super(`GearboxAPI: ${endpoint} is not implemented yet`);
+		this.name = "OffchainNotImplementedError";
+	}
+};
+/**
+* Backend counterpart of the `opportunities` namespace.
+*
+* This is a stub: the HTTP client is not written yet, so list reads answer with
+* an empty list and detail reads throw. Every signature is already the final
+* one, because the backend returns the read model types directly — there is no
+* wire DTO and no mapper between the two.
+*
+* When the transport lands, each method will validate the response against the
+* matching schema from `src/model` before returning it. A validation failure is
+* a version-skew error and is handled exactly like a transport error: the
+* combined SDK drops the backend's contribution in `both` mode and rethrows in
+* `offchain` mode.
+**/
+var OffchainOpportunities = class {
+	#baseUrl;
+	#logger;
+	constructor(options) {
+		this.#baseUrl = options?.baseUrl;
+		this.#logger = options?.logger?.child?.({ name: "OffchainOpportunities" });
+	}
+	/**
+	* Base URL the client will call once the transport is implemented.
+	**/
+	get baseUrl() {
+		return this.#baseUrl;
+	}
+	/**
+	* All opportunities the backend knows about, optionally narrowed by
+	* {@link OpportunityFilter}.
+	*
+	* @returns An empty list until the backend client is implemented.
+	**/
+	async list(filter) {
+		this.#logger?.debug({ filter }, "offchain opportunities list is not implemented, serving empty list");
+		return {
+			result: [],
+			meta: { status: "success" }
+		};
+	}
+	/**
+	* Detailed view of one pool opportunity.
+	*
+	* @throws {@link OffchainNotImplementedError} until the backend client is
+	* implemented.
+	**/
+	async getPool(key) {
+		throw new OffchainNotImplementedError("opportunities.getPool");
+	}
+	/**
+	* Detailed view of one strategy opportunity.
+	*
+	* @throws {@link OffchainNotImplementedError} until the backend client is
+	* implemented.
+	**/
+	async getStrategy(key) {
+		throw new OffchainNotImplementedError("opportunities.getStrategy");
+	}
+	/**
+	* One historical series of one opportunity. History exists only here:
+	* rebuilding it from the chain would mean an archive read per point.
+	*
+	* The requested metric types the response, so a caller asking for one metric
+	* does not have to narrow the union back down. When the transport lands,
+	* validation is what upholds it: a response carrying a different metric than
+	* the one asked for is a version-skew error like any other.
+	*
+	* @returns An empty series until the backend client is implemented.
+	**/
+	async getHistory(query) {
+		this.#logger?.debug({ query }, "offchain opportunities history is not implemented, serving empty series");
+		return {
+			result: {
+				metric: query.metric,
+				points: [],
+				metadata: {}
+			},
+			meta: { status: "success" }
+		};
+	}
+};
+//#endregion
+export { OffchainNotImplementedError, OffchainOpportunities };

package/dist/esm/offchain/opportunities/index.js

@@ -0,0 +1,2 @@
+import { OffchainNotImplementedError, OffchainOpportunities } from "./OffchainOpportunities.js";
+export { OffchainNotImplementedError, OffchainOpportunities };

package/dist/esm/offchain/package.json

@@ -0,0 +1 @@
+{"type": "module","sideEffects":false}

package/dist/esm/offchain/types.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/preview/preview/buildDelayedPreview.js

@@ -1,6 +1,6 @@
 import { AssetsMap } from "../../sdk/utils/AssetsMap.js";
+import { BigIntMath } from "../../sdk/utils/bigint-math.js";
 import "../../sdk/index.js";
-import { BigIntMath } from "../../common-utils/utils/bigint-math.js";
 import "../../common-utils/index.js";
 import { ERROR_UNPRICEABLE_TOKEN, PREVIEW_DUST } from "./types.js";
 import { isAddressEqual } from "viem";

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

@@ -1,5 +1,5 @@
-import { iPoolV310Abi } from "../../abi/310/generated.js";
 import { iZapperAbi } from "../../abi/iZapper.js";
+import { iPoolV310Abi } from "../../abi/310/generated.js";
 import { asPreviewSimulationError } from "./errors.js";
 //#region src/preview/simulate/simulatePoolOperation.ts
 function previewRead(operation) {

package/dist/esm/preview/trace/extractTransfers.js

@@ -1,6 +1,6 @@
+import { ierc20Abi } from "../../abi/iERC20.js";
 import { iCreditFacadeV310Abi } from "../../abi/310/generated.js";
 import { AddressMap } from "../../sdk/utils/AddressMap.js";
-import { ierc20Abi } from "../../abi/iERC20.js";
 import "../../sdk/index.js";
 import { UnexpectedFacadeEventOrderError } from "./errors.js";
 import { getAddress, isAddressEqual, parseEventLogs } from "viem";

package/dist/esm/rewards/rewards/api.js

@@ -1,7 +1,7 @@
+import { BigIntMath } from "../../sdk/utils/bigint-math.js";
 import { chains } from "../../sdk/chain/chains.js";
 import { toBigInt } from "../../sdk/utils/formatter.js";
 import "../../sdk/index.js";
-import { BigIntMath } from "../../common-utils/utils/bigint-math.js";
 import "../../common-utils/index.js";
 import { MerkleXYZApi } from "./merkl-api.js";
 import { getAddress } from "viem";

package/dist/esm/rewards/rewards/extra-apy.js

@@ -1,8 +1,8 @@
+import { BigIntMath } from "../../sdk/utils/bigint-math.js";
 import { chains } from "../../sdk/chain/chains.js";
 import { PERCENTAGE_FACTOR } from "../../sdk/constants/math.js";
 import { toBN } from "../../sdk/utils/formatter.js";
 import "../../sdk/index.js";
-import { BigIntMath } from "../../common-utils/utils/bigint-math.js";
 import "../../common-utils/index.js";
 import axios from "axios";
 //#region src/rewards/rewards/extra-apy.ts