@gearbox-protocol/sdk 18.1.0 → 18.2.0-next.10

package/dist/esm/permissionless/api/oracles/schemas.js

@@ -1,4 +1,5 @@
-import { addressRecord, addressSchema } from "../schemas.js";
+import { chainSchema } from "../chains/schemas.js";
+import { addressSchema } from "../schemas.js";
 import { z } from "zod/v4";
 //#region src/permissionless/api/oracles/schemas.ts
 /**
@@ -18,30 +19,106 @@ const priceFeedSchema = z.looseObject({
 	stalenessPeriod: z.number(),
 	name: z.string()
 });
-/** {@link PermissionlessAsset} */
-const assetSchema = z.looseObject({
+/**
+* {@link PermissionlessPriceFeedAsset}
+*
+* What identifies an asset, which is all a feed's own listing of one says.
+**/
+const priceFeedAssetSchema = z.looseObject({
 	address: addressSchema,
 	symbol: z.string(),
 	name: z.string(),
-	decimals: z.number(),
+	decimals: z.number()
+});
+/** {@link PermissionlessAsset} — identified as above, plus what prices it. */
+const assetSchema = priceFeedAssetSchema.extend({
 	owner: addressSchema,
 	priceFeeds: z.array(priceFeedSchema)
 });
-/** {@link PermissionlessPriceFeedStore} */
-const priceFeedStoreSchema = z.looseObject({
-	chainId: z.number(),
-	name: z.string(),
-	isPublic: z.boolean(),
-	isActivated: z.boolean(),
-	explorerUrl: z.string(),
+/**
+* {@link PermissionlessPriceFeedStore}
+*
+* A store is a chain's, and is described by the same five fields the chain
+* list answers with, so those are extended rather than restated.
+**/
+const priceFeedStoreSchema = chainSchema.extend({
 	assets: z.array(assetSchema),
 	priceFeeds: z.array(priceFeedSchema)
 });
-/** {@link PermissionlessPrices} */
-const pricesSchema = z.looseObject({
-	prices: addressRecord(z.string().nullable()),
-	marketCaps: addressRecord(addressRecord(z.string().nullable())),
-	time: z.number()
+/** Every chain's {@link PermissionlessPriceFeedStore}, one per chain. */
+const priceFeedStoresSchema = z.array(priceFeedStoreSchema);
+/**
+* What names a market, whichever side it is being listed from.
+*
+* A feed's markets and an asset's markets are different reads, but they
+* answer with the same market: who curates it, what it is denominated in and
+* how much of the quota is taken. Only what the read is about differs, which
+* is what each of the two below adds.
+**/
+const marketSchema = z.looseObject({
+	market: addressSchema,
+	marketConfigurator: addressSchema,
+	curatorName: z.string().nullable(),
+	marketName: z.string().nullable(),
+	underlyingSymbol: z.string().nullable(),
+	isUnderlying: z.boolean(),
+	quotaLimit: z.number().nullable(),
+	quotaUsed: z.number().nullable()
+});
+/**
+* {@link PermissionlessIndexedPriceFeedMarket} — the market as the feed's slot
+* in it, before the oracle is asked what period it holds for the slot.
+**/
+const priceFeedMarketSchema = marketSchema.extend({
+	token: addressSchema,
+	tokenSymbol: z.string().nullable(),
+	reserve: z.boolean(),
+	priceOracle: addressSchema
+});
+/** {@link PermissionlessIndexedPriceFeedDetails} */
+const priceFeedDetailsSchema = z.looseObject({
+	chainId: z.number(),
+	priceFeed: priceFeedSchema,
+	assets: z.array(priceFeedAssetSchema),
+	markets: z.array(priceFeedMarketSchema)
+});
+/** {@link PermissionlessAssetMarketFeed} */
+const assetMarketFeedSchema = z.looseObject({
+	address: addressSchema,
+	name: z.string().nullable(),
+	inStore: z.boolean()
+});
+/** {@link PermissionlessAssetMarket} — the market as what prices the asset in it. */
+const assetMarketSchema = marketSchema.extend({
+	underlyingToken: addressSchema,
+	underlyingPriceFeed: addressSchema.nullable(),
+	isShutdown: z.boolean(),
+	mainFeed: assetMarketFeedSchema.nullable(),
+	reserveFeed: assetMarketFeedSchema.nullable()
+});
+/** {@link PermissionlessIndexedAssetDetails} */
+const assetDetailsSchema = z.looseObject({
+	chainId: z.number(),
+	asset: priceFeedAssetSchema,
+	priceFeeds: z.array(priceFeedSchema),
+	markets: z.array(assetMarketSchema)
+});
+/** {@link PermissionlessAssetQuota} */
+const assetQuotaSchema = z.looseObject({
+	quotaLimit: z.number().nullable(),
+	quotaUsed: z.number().nullable(),
+	isShutdown: z.boolean(),
+	underlyingPriceFeed: addressSchema.nullable()
+});
+/** {@link PermissionlessIndexedAssetSummary} */
+const assetSummarySchema = z.looseObject({
+	chainId: z.number(),
+	address: addressSchema,
+	symbol: z.string(),
+	underlyingMarketCount: z.number(),
+	marketQuotas: z.array(assetQuotaSchema)
 });
+/** The list of {@link PermissionlessAssetSummary}, already ordered. */
+const assetSummariesSchema = z.array(assetSummarySchema);
 //#endregion
-export { assetSchema, priceFeedSchema, priceFeedStoreSchema, pricesSchema };
+export { assetDetailsSchema, assetMarketFeedSchema, assetMarketSchema, assetQuotaSchema, assetSchema, assetSummariesSchema, assetSummarySchema, priceFeedAssetSchema, priceFeedDetailsSchema, priceFeedMarketSchema, priceFeedSchema, priceFeedStoreSchema, priceFeedStoresSchema };

package/dist/esm/permissionless/api/schemas.js

@@ -1,4 +1,4 @@
-import { isAddress, isHex } from "viem";
+import { isAddress } from "viem";
 import { z } from "zod/v4";
 //#region src/permissionless/api/schemas.ts
 /**
@@ -11,8 +11,6 @@ import { z } from "zod/v4";
 **/
 /** An address, in whatever case the backend serves it. */
 const addressSchema = z.custom((value) => typeof value === "string" && isAddress(value, { strict: false }), { message: "invalid address" });
-/** A `0x`-prefixed hex string, as viem's `Hex`. */
-const hexSchema = z.custom((value) => typeof value === "string" && isHex(value), { message: "invalid hex string" });
 /**
 * A record keyed by address. Spelled out here because zod types a record key
 * by the schema's output, which the branded `Address` is not inferred as.
@@ -22,4 +20,4 @@ function addressRecord(value) {
 	return z.record(key, value);
 }
 //#endregion
-export { addressRecord, addressSchema, hexSchema };
+export { addressRecord, addressSchema };

package/dist/esm/permissionless/bindings/index.js

@@ -1,6 +1,7 @@
 import { BytecodeRepositoryContract } from "./bytecode-repository.js";
 import { priceFeedSetupParams } from "./pricefeeds/index.js";
 import { PriceFeedStoreContract } from "./price-feed-store.js";
+import { AddressProviderContract } from "./address-provider.js";
 import { TokenCompressorContract } from "./compressors/token-compressor.js";
 import { WithdrawalCompressorContract } from "./compressors/withdrawal-compressor.js";
 import "./compressors/index.js";
@@ -8,7 +9,6 @@ import { RoutingManagerContract } from "./router/routing-manager.js";
 import "./router/index.js";
 import { TreasurySplitterContract } from "./treasury-splitter.js";
 import { InstanceManagerContract } from "./instance-manager.js";
-import { AddressProviderContract } from "./address-provider.js";
 import { MarketConfiguratorFactoryContract } from "./market-configurator-factory.js";
 import { CrossChainMultisigContract } from "./cross-chain-multisig.js";
 import { AccessMode } from "./types.js";

package/dist/esm/permissionless/index.js

@@ -1,3 +1,4 @@
+import { PermissionlessAnalytics } from "./api/analytics/PermissionlessAnalytics.js";
 import { PermissionlessChainUnreachableError, PermissionlessNotAttachedError, PriceFeedNotInStoreError, PriceFeedSaltMissingError, PriceFeedStalenessUnknownError } from "./api/errors.js";
 import { ChainsNamespace } from "./api/chains/ChainsNamespace.js";
 import { deriveEffectiveStalenessPeriod } from "./api/deploy/effective-staleness.js";
@@ -9,7 +10,8 @@ import { PriceFeedStoreContract } from "./bindings/price-feed-store.js";
 import { Addresses } from "./deployment/addresses.js";
 import { encodeFunctionParams } from "./utils/abi-encoder.js";
 import { DEFAULT_DEPLOY_SALT, PermissionlessDeploy, priceFeedSalt } from "./api/deploy/PermissionlessDeploy.js";
-import { getPrices } from "./utils/price-update/get-prices.js";
+import { AddressProviderContract } from "./bindings/address-provider.js";
+import { getLatestPrices, getPrices } from "./utils/price-update/get-prices.js";
 import { GET_PRICES_CHUNK_SIZE, GET_PRICES_GAS_LIMIT_BY_CHAIN_ID, PermissionlessOracles } from "./api/oracles/PermissionlessOracles.js";
 import { TokenCompressorContract } from "./bindings/compressors/token-compressor.js";
 import { WithdrawalCompressorContract } from "./bindings/compressors/withdrawal-compressor.js";
@@ -21,7 +23,6 @@ import { getUpdatablePriceFeeds } from "./utils/price-update/get-updatable-feeds
 import { InstanceOwnerTransactions } from "./api/transactions/InstanceOwnerTransactions.js";
 import { GearboxPermissionless } from "./api/GearboxPermissionless.js";
 import "./api/index.js";
-import { AddressProviderContract } from "./bindings/address-provider.js";
 import { MarketConfiguratorFactoryContract } from "./bindings/market-configurator-factory.js";
 import { CrossChainMultisigContract } from "./bindings/cross-chain-multisig.js";
 import { PUBLIC_CREATE2_FACTORY, checkCreate2Deployment, checkCreate2DeploymentAddress, createCreate2DeployRawTx, deployUsingPublicCreate2, getCreate2AddressPublicFactory, getCreate2DeploymentAddress, handleSalt } from "./utils/create2.js";
@@ -40,4 +41,4 @@ import { getBlockNumberByTimestamp } from "./utils/block-utils.js";
 import { convertQueueBatchToExecuteTx } from "./utils/governance/timelock-txs.js";
 import { getPriceUpdateTx } from "./utils/price-update/get-price-update-tx.js";
 import "./utils/index.js";
-export { AccessMode, AddressProviderContract, Addresses, ArchiveTransport, BYTECODE_REPOSITORY, BytecodeRepositoryContract, CROSS_CHAIN_GOVERNANCE, CROSS_CHAIN_MULTISIG, ChainsNamespace, CrossChainMultisigContract, DEFAULT_DEPLOY_SALT, GET_PRICES_CHUNK_SIZE, GET_PRICES_GAS_LIMIT_BY_CHAIN_ID, GearboxPermissionless, GovernorContract, INSTANCE_MANAGER, InstanceManagerContract, InstanceOwnerTransactions, MAINNET_CCM_CONSTRUCTOR_PARAMS, MAINNET_DEPLOYMENT_BLOCK, MAINNET_DEPLOYMENT_CCM_SALT, MAINNET_DEPLOYMENT_IM_SALT, MARKET_CONFIGURATOR_FACTORY, MarketConfiguratorContract, MarketConfiguratorFactoryContract, PRICE_FEED_STORE, PUBLIC_CREATE2_FACTORY, PermissionlessChainUnreachableError, PermissionlessDeploy, PermissionlessNotAttachedError, PermissionlessOracles, PriceFeedNotInStoreError, PriceFeedSaltMissingError, PriceFeedStalenessUnknownError, PriceFeedStoreContract, RoutingManagerContract, TOKEN_COMPRESSOR, TimeLockContract, TokenCompressorContract, TreasurySplitterContract, WithdrawalCompressorContract, calculateChecksum, checkCreate2Deployment, checkCreate2DeploymentAddress, chunkedLogsTransport, convertPercent, convertQueueBatchToExecuteTx, convertRawTxToSafeMultisigTx, createCallData, createCreate2DeployRawTx, deepJsonParse, deployUsingPublicCreate2, deriveEffectiveStalenessPeriod, encodeFunctionParams, formatBytecodeSize, formatBytecodeVersion, getBlockNumberByTimestamp, getCreate2AddressPublicFactory, getCreate2DeploymentAddress, getPriceUpdateTx, getPrices, getSafeBatch, getSafeBatches, getUpdatablePriceFeeds, handleSalt, normalizeSignature, priceFeedSalt, priceFeedSetupParams, shortenHash, significantTrunc };
+export { AccessMode, AddressProviderContract, Addresses, ArchiveTransport, BYTECODE_REPOSITORY, BytecodeRepositoryContract, CROSS_CHAIN_GOVERNANCE, CROSS_CHAIN_MULTISIG, ChainsNamespace, CrossChainMultisigContract, DEFAULT_DEPLOY_SALT, GET_PRICES_CHUNK_SIZE, GET_PRICES_GAS_LIMIT_BY_CHAIN_ID, GearboxPermissionless, GovernorContract, INSTANCE_MANAGER, InstanceManagerContract, InstanceOwnerTransactions, MAINNET_CCM_CONSTRUCTOR_PARAMS, MAINNET_DEPLOYMENT_BLOCK, MAINNET_DEPLOYMENT_CCM_SALT, MAINNET_DEPLOYMENT_IM_SALT, MARKET_CONFIGURATOR_FACTORY, MarketConfiguratorContract, MarketConfiguratorFactoryContract, PRICE_FEED_STORE, PUBLIC_CREATE2_FACTORY, PermissionlessAnalytics, PermissionlessChainUnreachableError, PermissionlessDeploy, PermissionlessNotAttachedError, PermissionlessOracles, PriceFeedNotInStoreError, PriceFeedSaltMissingError, PriceFeedStalenessUnknownError, PriceFeedStoreContract, RoutingManagerContract, TOKEN_COMPRESSOR, TimeLockContract, TokenCompressorContract, TreasurySplitterContract, WithdrawalCompressorContract, calculateChecksum, checkCreate2Deployment, checkCreate2DeploymentAddress, chunkedLogsTransport, convertPercent, convertQueueBatchToExecuteTx, convertRawTxToSafeMultisigTx, createCallData, createCreate2DeployRawTx, deepJsonParse, deployUsingPublicCreate2, deriveEffectiveStalenessPeriod, encodeFunctionParams, formatBytecodeSize, formatBytecodeVersion, getBlockNumberByTimestamp, getCreate2AddressPublicFactory, getCreate2DeploymentAddress, getLatestPrices, getPriceUpdateTx, getPrices, getSafeBatch, getSafeBatches, getUpdatablePriceFeeds, handleSalt, normalizeSignature, priceFeedSalt, priceFeedSetupParams, shortenHash, significantTrunc };

package/dist/esm/permissionless/utils/index.js

@@ -1,7 +1,7 @@
 import { BYTECODE_REPOSITORY, CROSS_CHAIN_GOVERNANCE, CROSS_CHAIN_MULTISIG, INSTANCE_MANAGER, MARKET_CONFIGURATOR_FACTORY, PRICE_FEED_STORE, TOKEN_COMPRESSOR } from "./literals.js";
 import { normalizeSignature } from "./signature.js";
 import { encodeFunctionParams } from "./abi-encoder.js";
-import { getPrices } from "./price-update/get-prices.js";
+import { getLatestPrices, getPrices } from "./price-update/get-prices.js";
 import { calculateChecksum, convertRawTxToSafeMultisigTx, getSafeBatch, getSafeBatches } from "./governance/batch.js";
 import { getUpdatablePriceFeeds } from "./price-update/get-updatable-feeds.js";
 import { PUBLIC_CREATE2_FACTORY, checkCreate2Deployment, checkCreate2DeploymentAddress, createCreate2DeployRawTx, deployUsingPublicCreate2, getCreate2AddressPublicFactory, getCreate2DeploymentAddress, handleSalt } from "./create2.js";
@@ -11,4 +11,4 @@ import { convertQueueBatchToExecuteTx } from "./governance/timelock-txs.js";
 import "./governance/index.js";
 import { getPriceUpdateTx } from "./price-update/get-price-update-tx.js";
 import "./price-update/index.js";
-export { BYTECODE_REPOSITORY, CROSS_CHAIN_GOVERNANCE, CROSS_CHAIN_MULTISIG, INSTANCE_MANAGER, MARKET_CONFIGURATOR_FACTORY, PRICE_FEED_STORE, PUBLIC_CREATE2_FACTORY, TOKEN_COMPRESSOR, calculateChecksum, checkCreate2Deployment, checkCreate2DeploymentAddress, convertPercent, convertQueueBatchToExecuteTx, convertRawTxToSafeMultisigTx, createCreate2DeployRawTx, deepJsonParse, deployUsingPublicCreate2, encodeFunctionParams, formatBytecodeSize, formatBytecodeVersion, getBlockNumberByTimestamp, getCreate2AddressPublicFactory, getCreate2DeploymentAddress, getPriceUpdateTx, getPrices, getSafeBatch, getSafeBatches, getUpdatablePriceFeeds, handleSalt, normalizeSignature, shortenHash, significantTrunc };
+export { BYTECODE_REPOSITORY, CROSS_CHAIN_GOVERNANCE, CROSS_CHAIN_MULTISIG, INSTANCE_MANAGER, MARKET_CONFIGURATOR_FACTORY, PRICE_FEED_STORE, PUBLIC_CREATE2_FACTORY, TOKEN_COMPRESSOR, calculateChecksum, checkCreate2Deployment, checkCreate2DeploymentAddress, convertPercent, convertQueueBatchToExecuteTx, convertRawTxToSafeMultisigTx, createCreate2DeployRawTx, deepJsonParse, deployUsingPublicCreate2, encodeFunctionParams, formatBytecodeSize, formatBytecodeVersion, getBlockNumberByTimestamp, getCreate2AddressPublicFactory, getCreate2DeploymentAddress, getLatestPrices, getPriceUpdateTx, getPrices, getSafeBatch, getSafeBatches, getUpdatablePriceFeeds, handleSalt, normalizeSignature, shortenHash, significantTrunc };

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

@@ -39,6 +39,30 @@ function getLatestRoundDataCall(priceFeed) {
 		args: []
 	};
 }
+/**
+* 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) => ({
@@ -82,4 +106,4 @@ async function getPrices({ client, priceFeeds, chunkSize = 10, gasLimit }) {
 	}), {});
 }
 //#endregion
-export { getPrices };
+export { getLatestPrices, getPrices };

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

@@ -1,4 +1,4 @@
-import { getPrices } from "./get-prices.js";
+import { getLatestPrices, getPrices } from "./get-prices.js";
 import { getUpdatablePriceFeeds } from "./get-updatable-feeds.js";
 import { getPriceUpdateTx } from "./get-price-update-tx.js";
-export { getPriceUpdateTx, getPrices, getUpdatablePriceFeeds };
+export { getLatestPrices, getPriceUpdateTx, getPrices, getUpdatablePriceFeeds };

package/dist/esm/testnets/TestnetsAPI.js

@@ -0,0 +1,178 @@
+import { TestnetStatusError } from "./errors/TestnetStatusError.js";
+import { TestnetNotFoundError } from "./errors/TestnetNotFoundError.js";
+import { TestnetRequestFailedError } from "./errors/TestnetRequestFailedError.js";
+import { TestnetValidationError } from "./errors/TestnetValidationError.js";
+import { TestnetWaitTimeoutError } from "./errors/TestnetWaitTimeoutError.js";
+import "./errors/index.js";
+import { testnetSchema, testnetStatusSchema } from "./schemas.js";
+import { z } from "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 = z.object({ error: 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, z.array(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, 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, 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 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 TestnetRequestFailedError(url, error);
+		}
+		if (!response.ok) {
+			const responseBody = await response.text();
+			const details = errorBodySchema.safeParse(responseBody).data?.error;
+			throw response.status === 404 ? new TestnetNotFoundError(url, details) : new 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 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
+export { TestnetsAPI };

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

@@ -0,0 +1,14 @@
+import { TestnetStatusError } from "./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 TestnetStatusError {
+	name = "TestnetNotFoundError";
+	constructor(url, details) {
+		super(url, 404, details);
+	}
+};
+//#endregion
+export { TestnetNotFoundError };

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

@@ -0,0 +1,23 @@
+import { TestnetsError } from "./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 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
+export { TestnetRequestFailedError };

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

@@ -0,0 +1,18 @@
+import { TestnetsError } from "./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 TestnetsError {
+	name = "TestnetStatusError";
+	constructor(url, status, details) {
+		super(`anvil-manager answered ${status}.`, {
+			url,
+			status,
+			details
+		});
+	}
+};
+//#endregion
+export { TestnetStatusError };

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

@@ -0,0 +1,23 @@
+import { TestnetsError } from "./TestnetsError.js";
+import { z } from "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 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: z.prettifyError(zodError).split("\n")
+		});
+		this.zodError = zodError;
+	}
+};
+//#endregion
+export { TestnetValidationError };

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

@@ -0,0 +1,29 @@
+import { TestnetsError } from "./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 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
+export { TestnetWaitTimeoutError };

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

@@ -0,0 +1,33 @@
+import { BaseError } from "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 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
+export { TestnetsError };

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

@@ -0,0 +1,7 @@
+import { TestnetsError } from "./TestnetsError.js";
+import { TestnetStatusError } from "./TestnetStatusError.js";
+import { TestnetNotFoundError } from "./TestnetNotFoundError.js";
+import { TestnetRequestFailedError } from "./TestnetRequestFailedError.js";
+import { TestnetValidationError } from "./TestnetValidationError.js";
+import { TestnetWaitTimeoutError } from "./TestnetWaitTimeoutError.js";
+export { TestnetNotFoundError, TestnetRequestFailedError, TestnetStatusError, TestnetValidationError, TestnetWaitTimeoutError, TestnetsError };

package/dist/esm/testnets/index.js

@@ -0,0 +1,11 @@
+import { TestnetsError } from "./errors/TestnetsError.js";
+import { TestnetStatusError } from "./errors/TestnetStatusError.js";
+import { TestnetNotFoundError } from "./errors/TestnetNotFoundError.js";
+import { TestnetRequestFailedError } from "./errors/TestnetRequestFailedError.js";
+import { TestnetValidationError } from "./errors/TestnetValidationError.js";
+import { TestnetWaitTimeoutError } from "./errors/TestnetWaitTimeoutError.js";
+import "./errors/index.js";
+import { testnetBackendOptionsSchema, testnetBackendStateSchema, testnetBackendStatusSchema, testnetBlockSchema, testnetOptionsSchema, testnetSchema, testnetScriptBlockSchema, testnetScriptOptionsSchema, testnetScriptSchema, testnetStageStatusSchema, testnetStatusSchema, testnetTaskDefinitionSchema, testnetTaskProgressSchema, testnetTaskSchema } from "./schemas.js";
+import { TestnetsAPI } from "./TestnetsAPI.js";
+import "./types.js";
+export { TestnetNotFoundError, TestnetRequestFailedError, TestnetStatusError, TestnetValidationError, TestnetWaitTimeoutError, TestnetsAPI, TestnetsError, testnetBackendOptionsSchema, testnetBackendStateSchema, testnetBackendStatusSchema, testnetBlockSchema, testnetOptionsSchema, testnetSchema, testnetScriptBlockSchema, testnetScriptOptionsSchema, testnetScriptSchema, testnetStageStatusSchema, testnetStatusSchema, testnetTaskDefinitionSchema, testnetTaskProgressSchema, testnetTaskSchema };

package/dist/esm/testnets/package.json

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