import { Balance, BlockInfo, ChainKey, ContractInfo, GasData, GasUnit, OpReturnPayload, Provider, ProviderCapabilities, ProviderCapability, ProviderConfig, ProviderConstructor, ProviderEntry, ProviderMeta, TokenBalance, TokenBalanceOptions, TokenTransfer, TokenTransferOptions, Transaction, TxHistoryOptions, TxStatus, Utxo, buildQuery, clampMaxResults, formatWei, getJSON, hexToWei, normalizeChain } from "./_chunks/provider.mjs";
export declare const version: string;
/**
 * Every provider shipped with the package, in registration order.
 *
 * A provider missing here is invisible to `create()`. `test/unit/registry.test.ts` compares each
 * entry against the class it loads, so metadata cannot drift away from the implementation.
 */
export declare const builtins: readonly ProviderEntry[];
/** Explorers error hierarchy */
/**
 * Base class for failures surfaced through Explorers.
 *
 * Every message passes through `sanitizeUrl` here, so secret query params are redacted at one
 * boundary instead of at each construction site.
 */
export declare class ExplorerError extends Error {
  readonly provider?: string | undefined;
  constructor(message: string, provider?: string | undefined);
}
/** HTTP failure with a redacted request URL in its message and a redacted response body. */
export declare class HTTPError extends ExplorerError {
  readonly statusCode: number;
  /**
   * Request URL with secret query params redacted. Non-enumerable to keep serialized errors
   * compact.
   */
  readonly rawUrl: string;
  /** Response body, redacted in case the server echoes the request URL. */
  readonly body?: string;
  constructor(statusCode: number, url: string, body?: string, provider?: string);
}
/** Provider credentials were missing or rejected. */
export declare class AuthError extends ExplorerError {
  constructor(provider: string, detail?: string);
}
/** Provider refused a request because its rate limit was reached. */
export declare class RateLimitError extends ExplorerError {
  readonly retryAfter?: number | undefined;
  constructor(provider: string, retryAfter?: number | undefined);
}
/** Provider credentials are valid, but the current plan does not cover the requested read. */
export declare class PlanRestrictedError extends ExplorerError {
  constructor(provider: string, detail?: string);
}
/** Requested transaction, address, contract, or block was not found. */
export declare class NotFoundError extends ExplorerError {
  constructor(resource: string, provider?: string);
}
/** Provider does not serve the requested chain. */
export declare class UnsupportedChainError extends ExplorerError {
  constructor(chain: string, provider: string);
}
/** Explorer backend does not expose the requested operation. */
export declare class UnsupportedOperationError extends ExplorerError {
  constructor(operation: string, provider: string);
}
/** Registry does not contain the requested provider name. */
export declare class UnknownProviderError extends ExplorerError {
  constructor(provider: string);
}
/**
 * Turn an unknown provider or transport failure into the Explorers error hierarchy.
 *
 * Existing `ExplorerError` instances pass through unchanged. Structured HTTP failures retain their
 * status, response body, and redacted request URL.
 *
 * @param {unknown} error - The `error` value.
 * @param {string} provider - The `provider` value.
 * @param {string} requestUrl - The `requestUrl` value.
 * @returns {ExplorerError} The resulting value.
 */
export declare function normalizeError(error: unknown, provider?: string, requestUrl?: string): ExplorerError;
/**
 * Cheap `.eth` shape check. It does not resolve the name or verify ownership.
 *
 * @param {string} input - The `input` value.
 * @returns {boolean} The resulting value.
 */
export declare function isEnsName(input: string): boolean;
/**
 * Match a 20-byte EVM hex address. This is not a validator for non-EVM chains.
 *
 * @param {string} input - The `input` value.
 * @returns {boolean} The resulting value.
 */
export declare function isAddress(input: string): boolean;
/**
 * Resolve an ENS name through public HTTP resolvers.
 *
 * Resolver failures are tried in order and collapse to `null` when every endpoint fails.
 *
 * @param {string} name - The `name` value.
 * @returns {Promise<string | null>} The resulting value.
 */
export declare function resolveEns(name: string): Promise<string | null>;
/**
 * Resolve one address or an address list, including lists serialized by a tool host.
 *
 * @throws {NotFoundError} When any ENS name cannot be resolved.
 * @throws {TypeError} When a serialized tool list falls outside its input contract.
 *
 * @param {string | readonly string[]} input - The `input` value.
 * @param {ChainKey} chain - The `chain` value.
 * @returns {Promise<string[]>} The resulting value.
 */
export declare function resolveAddresses(input: string | readonly string[], chain?: ChainKey): Promise<string[]>;
/** One registered provider as its registry metadata describes it. */
interface ProviderListing {
  /** Registry key accepted by `create()` and the `provider` option. */
  readonly name: string;
  /** Chains the provider declares. */
  readonly chains: readonly ChainKey[];
  /** Public endpoint advertised for the provider. */
  readonly defaultUrl?: string;
  /**
   * Operations the provider declares, in the shape of the instance getter.
   *
   * Declared for the provider as a whole, not per chain: a provider can still refuse one of them on
   * one of its chains at call time. Absent when an external registration left capability metadata
   * out.
   */
  readonly capabilities?: Readonly<ProviderCapabilities>;
}
/**
 * Register a provider class under its stable `key`.
 *
 * Built-in providers are already registered; this is the entry point for classes living outside the
 * package, and their class is kept as is instead of being loaded on demand. Registering the same
 * name again replaces the previous entry. That is useful in tests, but easy to do by accident in
 * application code.
 *
 * @param {ProviderConstructor} providerClass - The `providerClass` value.
 * @param {Readonly<ProviderMeta>} meta - The `meta` value.
 */
export declare function register(providerClass: ProviderConstructor, meta: Readonly<ProviderMeta>): void;
/**
 * Create a registered provider with optional backend configuration.
 *
 * The first call for a built-in provider imports its module; later calls reuse the loaded class.
 *
 * @example
 *   ```ts
 *   import { create } from "@agntn/explorers";
 *
 *   const provider = await create("blockscout");
 *   const balance = await provider.getBalance("0x0000000000000000000000000000000000000000", "ethereum");
 *   ```
 *
 * @throws {UnknownProviderError} When `name` has not been registered.
 *
 * @param {string} name - The `name` value.
 * @param {Readonly<ProviderConfig>} config - The `config` value.
 * @returns {Promise<Provider>} The resulting value.
 */
export declare function create(name: string, config?: Readonly<ProviderConfig>): Promise<Provider>;
/**
 * Return registered provider names in registration order.
 *
 * @returns {string[]} The resulting value.
 */
export declare function providers(): string[];
/**
 * Describe every registered provider from registry metadata alone.
 *
 * Nothing here imports a provider module, so discovery stays cheap and answers the same on every
 * host. A provider whose constructor demands credentials is listed like any other; the credential
 * error waits for the first real read.
 *
 * @returns {ProviderListing[]} One record per provider, in registration order.
 */
export declare function listProviders(): ProviderListing[];
/**
 * Check whether a name can be passed to `create`.
 *
 * @param {string} name - The `name` value.
 * @returns {boolean} The resulting value.
 */
export declare function has(name: string): boolean;
/**
 * Check whether a registered provider declares support for `chain`.
 *
 * @param {string} name - The `name` value.
 * @param {ChainKey} chain - The `chain` value.
 * @returns {boolean} The resulting value.
 */
export declare function supportsChain(name: string, chain: ChainKey): boolean;
/**
 * Check whether a registered provider declares support for `capability`.
 *
 * External registrations without capability metadata remain eligible so adding this routing hint
 * does not silently remove existing providers from auto-selection.
 *
 * @param {string} name - The `name` value.
 * @param {ProviderCapability} capability - The required operation.
 * @returns {boolean} Whether the provider can be considered for the operation.
 */
export declare function supportsCapability(name: string, capability: ProviderCapability): boolean;
/**
 * Return the public endpoint advertised for a provider.
 *
 * Per-instance `baseUrl` overrides are deliberately not reflected here.
 *
 * @param {string} name - The `name` value.
 * @returns {string | undefined} The resulting value.
 */
export declare function getDefaultURL(name: string): string | undefined;
/** Provider-specific default chains */
export declare const PROVIDER_DEFAULT_CHAIN: Partial<Record<string, ChainKey>>;
/**
 * Choose a registered provider for the current environment.
 *
 * An explicit preference wins, even for a chain it cannot serve, so misconfiguration stays visible.
 * Without one, candidates that declare support for the requested chain and optional capability are
 * considered in order: configured credentials first, then keyless providers, then any matching
 * registry entry, and finally Blockscout when no provider matches the chain.
 *
 * @throws {UnknownProviderError} When an explicit preference is not registered.
 *
 * @param {string} preferred - The `preferred` value.
 * @param {ChainKey} chain - The `chain` value.
 * @param {ProviderCapability} capability - Operation required from an automatic selection.
 * @returns {string} The resulting value.
 */
export declare function resolveProvider(preferred?: string, chain?: ChainKey, capability?: ProviderCapability): string;
/** Provider and effective chain selected for one read. */
interface ProviderContext {
  readonly chain: ChainKey;
  readonly name: string;
  readonly provider: Provider;
}
/**
 * Run one read with provider selection and one automatic retry after a transient or plan limit.
 *
 * When neither provider nor chain is explicit, selection starts on Ethereum. An explicit provider
 * without a chain keeps that provider's default chain. The callback must be safe to run twice.
 *
 * @param {string | undefined} preferred - The `preferred` value.
 * @param {ChainKey | undefined} chain - The `chain` value.
 * @param {(context: Readonly<ProviderContext>) => Promise<T>} run - The `run` value.
 * @param {ProviderCapability} capability - Operation required from an automatic selection.
 * @returns {Promise<T>} The resulting value.
 */
export declare function withProvider<T>(preferred: string | undefined, chain: ChainKey | undefined, run: (context: ProviderContext) => Promise<T>, capability?: ProviderCapability): Promise<T>;
export { type Balance, type BlockInfo, type ChainKey, type ContractInfo, type GasData, type GasUnit, type OpReturnPayload, Provider, type ProviderCapabilities, type ProviderCapability, type ProviderConfig, type ProviderConstructor, type ProviderContext, type ProviderEntry, type ProviderListing, type ProviderMeta, type TokenBalance, type TokenBalanceOptions, type TokenTransfer, type TokenTransferOptions, type Transaction, type TxHistoryOptions, type TxStatus, type Utxo, buildQuery, clampMaxResults, formatWei, getJSON, hexToWei, normalizeChain };
//# sourceMappingURL=index.d.mts.map