@gearbox-protocol/sdk 18.3.1 → 18.4.0

package/dist/cjs/permissionless/utils/price-update/get-prices.js

@@ -32,6 +32,16 @@ const latestRoundDataAbi = [{
 	stateMutability: "view",
 	type: "function"
 }];
+const decimalsAbi = [{
+	inputs: [],
+	name: "decimals",
+	outputs: [{
+		name: "",
+		type: "uint8"
+	}],
+	stateMutability: "view",
+	type: "function"
+}];
 function getLatestRoundDataCall(priceFeed) {
 	return {
 		address: priceFeed,
@@ -40,6 +50,58 @@ function getLatestRoundDataCall(priceFeed) {
 		args: []
 	};
 }
+/**
+* The scale each feed's answer is in, in one multicall.
+*
+* Part of the Chainlink interface every feed in a Gearbox tree implements,
+* and the only way to read an answer that is not an oracle's own: a feed an
+* oracle holds reports 8 decimals by construction, while the feeds beneath a
+* composite are whatever was deployed — an ETH/USD aggregator at 8 and a
+* rate leg at 18 sit under the same parent.
+*
+* `null` is a feed that would not answer, which a caller should treat as
+* unknown rather than defaulting it to 8.
+*/
+async function getFeedDecimals({ client, priceFeeds }) {
+	if (priceFeeds.length === 0) return {};
+	const results = await client.multicall({
+		contracts: priceFeeds.map((priceFeed) => ({
+			address: priceFeed,
+			abi: decimalsAbi,
+			functionName: "decimals",
+			args: []
+		})),
+		allowFailure: true
+	});
+	return Object.fromEntries(priceFeeds.map((priceFeed, index) => {
+		const result = results[index];
+		return [priceFeed, result?.status === "success" ? Number(result.result) : null];
+	}));
+}
+/**
+* What the feeds report as they stand, in one multicall.
+*
+* What {@link getPrices} does without the part that makes it expensive: no
+* `OnchainSDK` to attach and no update transactions to assemble, which is the
+* whole cost of that call and is wasted on a feed that answers already. A feed
+* that needs a fresh answer before it will be read comes back `null` here, so
+* a caller that must price those falls back to {@link getPrices} for them and
+* pays once for the few rather than once for all.
+*
+* `null` is also a feed whose read reverted for any other reason, which is not
+* a zero.
+*/
+async function getLatestPrices({ client, priceFeeds }) {
+	if (priceFeeds.length === 0) return {};
+	const results = await client.multicall({
+		contracts: priceFeeds.map(getLatestRoundDataCall),
+		allowFailure: true
+	});
+	return Object.fromEntries(priceFeeds.map((priceFeed, index) => {
+		const result = results[index];
+		return [priceFeed, result?.status === "success" ? result.result[1] : null];
+	}));
+}
 async function getPricesChunk({ client, priceFeeds, sdk }) {
 	const updateCall = priceFeeds.map((priceFeed) => getLatestRoundDataCall(priceFeed));
 	const multicallCalls = (await sdk.priceFeeds.generateExternalPriceFeedsUpdateTxs(priceFeeds)).txs.map((tx) => ({
@@ -83,4 +145,6 @@ async function getPrices({ client, priceFeeds, chunkSize = 10, gasLimit }) {
 	}), {});
 }
 //#endregion
+exports.getFeedDecimals = getFeedDecimals;
+exports.getLatestPrices = getLatestPrices;
 exports.getPrices = getPrices;

package/dist/cjs/permissionless/utils/price-update/index.js

@@ -2,6 +2,8 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_permissionless_utils_price_update_get_prices = require("./get-prices.js");
 const require_permissionless_utils_price_update_get_updatable_feeds = require("./get-updatable-feeds.js");
 const require_permissionless_utils_price_update_get_price_update_tx = require("./get-price-update-tx.js");
+exports.getFeedDecimals = require_permissionless_utils_price_update_get_prices.getFeedDecimals;
+exports.getLatestPrices = require_permissionless_utils_price_update_get_prices.getLatestPrices;
 exports.getPriceUpdateTx = require_permissionless_utils_price_update_get_price_update_tx.getPriceUpdateTx;
 exports.getPrices = require_permissionless_utils_price_update_get_prices.getPrices;
 exports.getUpdatablePriceFeeds = require_permissionless_utils_price_update_get_updatable_feeds.getUpdatablePriceFeeds;

package/dist/cjs/testnets/TestnetsAPI.js

@@ -0,0 +1,179 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_testnets_errors_TestnetStatusError = require("./errors/TestnetStatusError.js");
+const require_testnets_errors_TestnetNotFoundError = require("./errors/TestnetNotFoundError.js");
+const require_testnets_errors_TestnetRequestFailedError = require("./errors/TestnetRequestFailedError.js");
+const require_testnets_errors_TestnetValidationError = require("./errors/TestnetValidationError.js");
+const require_testnets_errors_TestnetWaitTimeoutError = require("./errors/TestnetWaitTimeoutError.js");
+require("./errors/index.js");
+const require_testnets_schemas = require("./schemas.js");
+let zod_v4 = require("zod/v4");
+//#region src/testnets/TestnetsAPI.ts
+const DEFAULT_BASE_URL = "https://anvil.gearbox.foundation";
+const DEFAULT_TIMEOUT = 3e4;
+const DEFAULT_WAIT_TIMEOUT = 6e5;
+const DEFAULT_WAIT_INTERVAL = 5e3;
+const errorBodySchema = zod_v4.z.object({ error: zod_v4.z.string() });
+/**
+* Client for anvil-manager, which runs the anvil forks Gearbox calls
+* testnets. It manages non-persistent testnets only, addressed by their
+* execution id.
+*
+* ```ts
+* const testnets = new TestnetsAPI({ apiKey: process.env.ANVIL_MANAGER_API_KEY });
+* const { executionId } = await testnets.create({ network: "Mainnet", timeout: "2h" });
+* const status = await testnets.waitUntilReady(executionId);
+* // ... use status.rpcUrl ...
+* await testnets.kill(executionId);
+* ```
+*
+* Every method throws a {@link TestnetsError} subclass when it fails, except
+* when a response body is not JSON: then it rejects with the error of
+* `response.json()`.
+**/
+var TestnetsAPI = class {
+	logger;
+	#baseUrl;
+	#apiKey;
+	#timeout;
+	constructor(options = {}) {
+		this.#baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+		this.#apiKey = options.apiKey;
+		this.#timeout = options.timeout ?? DEFAULT_TIMEOUT;
+		this.logger = options.logger?.child?.({ name: "TestnetsAPI" }) ?? options.logger;
+	}
+	/**
+	* Base URL every request of this client is sent to.
+	**/
+	get baseUrl() {
+		return this.#baseUrl;
+	}
+	/**
+	* Every testnet anvil-manager knows of, persistent ones included.
+	**/
+	async list() {
+		const url = this.#url("/api/v1/forks");
+		const response = await this.#fetch(url, { method: "GET" });
+		return this.#decode(url, response, zod_v4.z.array(require_testnets_schemas.testnetSchema));
+	}
+	/**
+	* Status of one testnet.
+	*
+	* @param id - Execution id of the testnet.
+	* @throws {@link TestnetNotFoundError} when there is no such testnet.
+	**/
+	async get(id) {
+		const url = this.#forkUrl(id);
+		const response = await this.#fetch(url, { method: "GET" });
+		return this.#decode(url, response, require_testnets_schemas.testnetStatusSchema);
+	}
+	/**
+	* Starts a testnet. It answers as soon as the testnet is created, long
+	* before it is {@link TestnetStatus.ready}.
+	*
+	* @param files - Saved in the testnet's shared dir, where scripts and tasks
+	* can read them.
+	**/
+	async create(request, files) {
+		const url = this.#url("/api/v1/forks");
+		const response = await this.#fetch(url, {
+			method: "POST",
+			...createBody(request, files)
+		});
+		return this.#decode(url, response, require_testnets_schemas.testnetStatusSchema);
+	}
+	/**
+	* Stops a testnet. Stopping one that is already stopped succeeds.
+	*
+	* @param id - Execution id of the testnet.
+	* @throws {@link TestnetNotFoundError} when there is no such testnet.
+	* @throws {@link TestnetStatusError} with status 400 when the testnet is
+	* persistent.
+	**/
+	async kill(id) {
+		await this.#fetch(this.#forkUrl(id), { method: "DELETE" });
+	}
+	/**
+	* Polls a testnet's status until it is {@link TestnetStatus.ready}.
+	*
+	* @param id - Execution id of the testnet.
+	* @returns The first status that is ready.
+	* @throws {@link TestnetWaitTimeoutError} when the testnet is not ready in
+	* time. Any error of a poll is thrown as is, without retrying.
+	**/
+	async waitUntilReady(id, options = {}) {
+		const { timeout = DEFAULT_WAIT_TIMEOUT, interval = DEFAULT_WAIT_INTERVAL } = options;
+		const deadline = Date.now() + timeout;
+		while (true) {
+			const status = await this.get(id);
+			if (status.ready) return status;
+			const remaining = deadline - Date.now();
+			if (remaining <= 0) throw new require_testnets_errors_TestnetWaitTimeoutError.TestnetWaitTimeoutError(this.#forkUrl(id), id, timeout);
+			this.logger?.debug(`testnet ${id} is not ready yet`);
+			await new Promise((resolve) => setTimeout(resolve, Math.min(interval, remaining)));
+		}
+	}
+	#url(path) {
+		return `${this.#baseUrl}${path}`;
+	}
+	#forkUrl(id) {
+		return this.#url(`/api/v1/forks/${encodeURIComponent(id)}`);
+	}
+	/**
+	* Sends one request and returns its response once it is known to be 2xx.
+	**/
+	async #fetch(url, init) {
+		const headers = new Headers(init.headers);
+		headers.set("accept", "application/json");
+		if (this.#apiKey) headers.set("authorization", `Bearer ${this.#apiKey}`);
+		let response;
+		try {
+			response = await fetch(url, {
+				...init,
+				headers,
+				signal: AbortSignal.timeout(this.#timeout)
+			});
+		} catch (error) {
+			throw new require_testnets_errors_TestnetRequestFailedError.TestnetRequestFailedError(url, error);
+		}
+		if (!response.ok) {
+			const responseBody = await response.text();
+			const details = errorBodySchema.safeParse(responseBody).data?.error;
+			throw response.status === 404 ? new require_testnets_errors_TestnetNotFoundError.TestnetNotFoundError(url, details) : new require_testnets_errors_TestnetStatusError.TestnetStatusError(url, response.status, details);
+		}
+		return response;
+	}
+	/**
+	* Body of a 2xx response, decoded.
+	**/
+	async #decode(url, response, schema) {
+		const payload = await response.json();
+		const parsed = schema.safeParse(payload);
+		if (!parsed.success) {
+			const error = new require_testnets_errors_TestnetValidationError.TestnetValidationError(url, parsed.error);
+			this.logger?.error(error, "anvil-manager response does not match the testnet schemas");
+			throw error;
+		}
+		return parsed.data;
+	}
+};
+/**
+* Body and content type of a create request: JSON alone, or a multipart form
+* with the JSON in its `json` field when there are files to upload.
+**/
+function createBody(request, files) {
+	const json = JSON.stringify(request);
+	if (!files || Object.keys(files).length === 0) return {
+		body: json,
+		headers: { "content-type": "application/json" }
+	};
+	const form = new FormData();
+	form.append("json", json);
+	for (const [name, contents] of Object.entries(files)) form.append("file", toBlob(contents), name);
+	return { body: form };
+}
+function toBlob(contents) {
+	if (contents instanceof Blob) return contents;
+	return new Blob([typeof contents === "string" ? contents : new Uint8Array(contents)]);
+}
+//#endregion
+exports.TestnetsAPI = TestnetsAPI;

package/dist/cjs/testnets/errors/TestnetNotFoundError.js

@@ -0,0 +1,15 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_testnets_errors_TestnetStatusError = require("./TestnetStatusError.js");
+//#region src/testnets/errors/TestnetNotFoundError.ts
+/**
+* Thrown when anvil-manager answered 404: there is no testnet with that
+* execution id.
+**/
+var TestnetNotFoundError = class extends require_testnets_errors_TestnetStatusError.TestnetStatusError {
+	name = "TestnetNotFoundError";
+	constructor(url, details) {
+		super(url, 404, details);
+	}
+};
+//#endregion
+exports.TestnetNotFoundError = TestnetNotFoundError;

package/dist/cjs/testnets/errors/TestnetRequestFailedError.js

@@ -0,0 +1,24 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_testnets_errors_TestnetsError = require("./TestnetsError.js");
+//#region src/testnets/errors/TestnetRequestFailedError.ts
+/**
+* Thrown when a request to anvil-manager never completed: the network was
+* down, or it took longer than the client's timeout.
+**/
+var TestnetRequestFailedError = class extends require_testnets_errors_TestnetsError.TestnetsError {
+	name = "TestnetRequestFailedError";
+	constructor(url, cause) {
+		super(timedOut(cause) ? "The request to anvil-manager timed out." : "The request to anvil-manager failed.", {
+			url,
+			cause
+		});
+	}
+};
+/**
+* Whether a caught value is the rejection `AbortSignal.timeout` produces.
+**/
+function timedOut(error) {
+	return error instanceof Error && error.name === "TimeoutError";
+}
+//#endregion
+exports.TestnetRequestFailedError = TestnetRequestFailedError;

package/dist/cjs/testnets/errors/TestnetStatusError.js

@@ -0,0 +1,19 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_testnets_errors_TestnetsError = require("./TestnetsError.js");
+//#region src/testnets/errors/TestnetStatusError.ts
+/**
+* Thrown when anvil-manager answered with a status outside the 2xx range. What
+* it said about it, when it said anything, is the `details` of the error.
+**/
+var TestnetStatusError = class extends require_testnets_errors_TestnetsError.TestnetsError {
+	name = "TestnetStatusError";
+	constructor(url, status, details) {
+		super(`anvil-manager answered ${status}.`, {
+			url,
+			status,
+			details
+		});
+	}
+};
+//#endregion
+exports.TestnetStatusError = TestnetStatusError;

package/dist/cjs/testnets/errors/TestnetValidationError.js

@@ -0,0 +1,24 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_testnets_errors_TestnetsError = require("./TestnetsError.js");
+let zod_v4 = require("zod/v4");
+//#region src/testnets/errors/TestnetValidationError.ts
+/**
+* Thrown when anvil-manager answered, but with a payload the testnet schemas
+* do not describe, i.e. the two are of different versions.
+**/
+var TestnetValidationError = class extends require_testnets_errors_TestnetsError.TestnetsError {
+	name = "TestnetValidationError";
+	/**
+	* The zod failure itself, e.g. for `z.treeifyError(error.zodError)`.
+	**/
+	zodError;
+	constructor(url, zodError) {
+		super("The anvil-manager response does not match the testnet schemas.", {
+			url,
+			metaMessages: zod_v4.z.prettifyError(zodError).split("\n")
+		});
+		this.zodError = zodError;
+	}
+};
+//#endregion
+exports.TestnetValidationError = TestnetValidationError;

package/dist/cjs/testnets/errors/TestnetWaitTimeoutError.js

@@ -0,0 +1,30 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_testnets_errors_TestnetsError = require("./TestnetsError.js");
+//#region src/testnets/errors/TestnetWaitTimeoutError.ts
+/**
+* Thrown when a testnet did not become ready before the wait for it ran out.
+**/
+var TestnetWaitTimeoutError = class extends require_testnets_errors_TestnetsError.TestnetsError {
+	name = "TestnetWaitTimeoutError";
+	/**
+	* Execution id of the testnet that was waited for.
+	**/
+	id;
+	/**
+	* How long the wait lasted, in milliseconds.
+	**/
+	timeout;
+	/**
+	* @param url - Status URL that was polled.
+	**/
+	constructor(url, id, timeout) {
+		super(`Testnet ${id} did not become ready within ${timeout} ms.`, {
+			url,
+			metaMessages: [`Execution id: ${id}`, `Timeout: ${timeout} ms`]
+		});
+		this.id = id;
+		this.timeout = timeout;
+	}
+};
+//#endregion
+exports.TestnetWaitTimeoutError = TestnetWaitTimeoutError;

package/dist/cjs/testnets/errors/TestnetsError.js

@@ -0,0 +1,34 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let viem = require("viem");
+//#region src/testnets/errors/TestnetsError.ts
+/**
+* Thrown by every testnet API call that fails. Its subclasses say how it
+* failed; catch this one to catch all of them.
+**/
+var TestnetsError = class extends viem.BaseError {
+	/**
+	* URL that was requested.
+	**/
+	url;
+	/**
+	* Status anvil-manager answered with, absent when the request never
+	* completed.
+	**/
+	status;
+	constructor(summary, params) {
+		const { cause, details } = params;
+		super(summary, {
+			cause: cause instanceof Error ? cause : void 0,
+			details: cause === void 0 || cause instanceof Error ? details : String(cause),
+			metaMessages: [
+				`URL: ${params.url}`,
+				...params.status === void 0 ? [] : [`Status: ${params.status}`],
+				...params.metaMessages ?? []
+			]
+		});
+		this.url = params.url;
+		this.status = params.status;
+	}
+};
+//#endregion
+exports.TestnetsError = TestnetsError;

package/dist/cjs/testnets/errors/index.js

@@ -0,0 +1,13 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_testnets_errors_TestnetsError = require("./TestnetsError.js");
+const require_testnets_errors_TestnetStatusError = require("./TestnetStatusError.js");
+const require_testnets_errors_TestnetNotFoundError = require("./TestnetNotFoundError.js");
+const require_testnets_errors_TestnetRequestFailedError = require("./TestnetRequestFailedError.js");
+const require_testnets_errors_TestnetValidationError = require("./TestnetValidationError.js");
+const require_testnets_errors_TestnetWaitTimeoutError = require("./TestnetWaitTimeoutError.js");
+exports.TestnetNotFoundError = require_testnets_errors_TestnetNotFoundError.TestnetNotFoundError;
+exports.TestnetRequestFailedError = require_testnets_errors_TestnetRequestFailedError.TestnetRequestFailedError;
+exports.TestnetStatusError = require_testnets_errors_TestnetStatusError.TestnetStatusError;
+exports.TestnetValidationError = require_testnets_errors_TestnetValidationError.TestnetValidationError;
+exports.TestnetWaitTimeoutError = require_testnets_errors_TestnetWaitTimeoutError.TestnetWaitTimeoutError;
+exports.TestnetsError = require_testnets_errors_TestnetsError.TestnetsError;

package/dist/cjs/testnets/index.js

@@ -0,0 +1,32 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_testnets_errors_TestnetsError = require("./errors/TestnetsError.js");
+const require_testnets_errors_TestnetStatusError = require("./errors/TestnetStatusError.js");
+const require_testnets_errors_TestnetNotFoundError = require("./errors/TestnetNotFoundError.js");
+const require_testnets_errors_TestnetRequestFailedError = require("./errors/TestnetRequestFailedError.js");
+const require_testnets_errors_TestnetValidationError = require("./errors/TestnetValidationError.js");
+const require_testnets_errors_TestnetWaitTimeoutError = require("./errors/TestnetWaitTimeoutError.js");
+require("./errors/index.js");
+const require_testnets_schemas = require("./schemas.js");
+const require_testnets_TestnetsAPI = require("./TestnetsAPI.js");
+require("./types.js");
+exports.TestnetNotFoundError = require_testnets_errors_TestnetNotFoundError.TestnetNotFoundError;
+exports.TestnetRequestFailedError = require_testnets_errors_TestnetRequestFailedError.TestnetRequestFailedError;
+exports.TestnetStatusError = require_testnets_errors_TestnetStatusError.TestnetStatusError;
+exports.TestnetValidationError = require_testnets_errors_TestnetValidationError.TestnetValidationError;
+exports.TestnetWaitTimeoutError = require_testnets_errors_TestnetWaitTimeoutError.TestnetWaitTimeoutError;
+exports.TestnetsAPI = require_testnets_TestnetsAPI.TestnetsAPI;
+exports.TestnetsError = require_testnets_errors_TestnetsError.TestnetsError;
+exports.testnetBackendOptionsSchema = require_testnets_schemas.testnetBackendOptionsSchema;
+exports.testnetBackendStateSchema = require_testnets_schemas.testnetBackendStateSchema;
+exports.testnetBackendStatusSchema = require_testnets_schemas.testnetBackendStatusSchema;
+exports.testnetBlockSchema = require_testnets_schemas.testnetBlockSchema;
+exports.testnetOptionsSchema = require_testnets_schemas.testnetOptionsSchema;
+exports.testnetSchema = require_testnets_schemas.testnetSchema;
+exports.testnetScriptBlockSchema = require_testnets_schemas.testnetScriptBlockSchema;
+exports.testnetScriptOptionsSchema = require_testnets_schemas.testnetScriptOptionsSchema;
+exports.testnetScriptSchema = require_testnets_schemas.testnetScriptSchema;
+exports.testnetStageStatusSchema = require_testnets_schemas.testnetStageStatusSchema;
+exports.testnetStatusSchema = require_testnets_schemas.testnetStatusSchema;
+exports.testnetTaskDefinitionSchema = require_testnets_schemas.testnetTaskDefinitionSchema;
+exports.testnetTaskProgressSchema = require_testnets_schemas.testnetTaskProgressSchema;
+exports.testnetTaskSchema = require_testnets_schemas.testnetTaskSchema;

package/dist/cjs/testnets/package.json

@@ -0,0 +1 @@
+{"type": "commonjs"}