import { ChainKey, ChainKey as ChainKey$1 } from "@agntn/chains";
/** Transaction status */
export type TxStatus = "success" | "failed" | "pending";
/** Normalized fungible-token transfer */
export interface TokenTransfer {
  /** Token contract address */
  contract: string;
  /** Token symbol */
  symbol: string;
  /** Token name */
  name?: string;
  /** Token decimals */
  decimals: number;
  /** Transfer amount (raw, string to avoid float) */
  value: string;
  /** Human-readable amount */
  valueFormatted: string;
  /** From address */
  from: string;
  /** To address */
  to: string;
  /** Transaction hash */
  txHash: string;
  /** Block number */
  blockNumber: number;
  /** Timestamp (ISO) */
  timestamp?: string;
}
/** One data push carried by an OP_RETURN output */
export interface OpReturnPayload {
  /** Pushed bytes as lowercase hex, without the opcode and the push prefix */
  hex: string;
  /** UTF-8 reading of the payload, present only when the bytes are printable text */
  text?: string;
}
/** Normalized transaction */
export interface Transaction {
  /** Transaction hash */
  hash: string;
  /** Block number */
  blockNumber: number;
  /** Timestamp (ISO) */
  timestamp?: string;
  /** Sender */
  from: string;
  /** Recipient (null for contract creation) */
  to: string | null;
  /** Value in the chain's smallest native unit */
  value: string;
  /** Human-readable value in native token */
  valueFormatted: string;
  /** Execution units consumed, when the chain exposes them */
  gasUsed?: string;
  /** Price per execution unit in the chain's smallest native unit */
  gasPrice?: string;
  /** Total transaction fee in the chain's smallest native unit */
  fee?: string;
  /** Transaction status */
  status: TxStatus;
  /** Method ID (first 4 bytes of input data) */
  methodId?: string;
  /** Function name if decoded */
  functionName?: string;
  /** Whether this is a contract interaction */
  isContractInteraction: boolean;
  /** Token transfers within this tx */
  tokenTransfers: TokenTransfer[];
  /** Data pushed by the OP_RETURN outputs, on chains that carry them */
  opReturn?: OpReturnPayload[];
  /** Raw provider data */
  raw?: Record<string, unknown>;
}
/** Unspent output an address still controls */
export interface Utxo {
  /** Transaction that created the output */
  txid: string;
  /** Output index inside that transaction */
  vout: number;
  /** Value in the chain's smallest native unit */
  value: string;
  /** Human-readable value in native token */
  valueFormatted: string;
  /** Whether the funding transaction is in a block */
  confirmed: boolean;
  /** Block number of the funding transaction, or null while it waits in the mempool */
  blockNumber: number | null;
  /** Block hash of the funding transaction, or null while it waits in the mempool */
  blockHash: string | null;
  /** Timestamp (ISO) of the funding block */
  timestamp?: string;
}
/** Normalized address balance */
export interface Balance {
  /** Address */
  address: string;
  /** Chain */
  chain: ChainKey;
  /** Time when the provider completed the read */
  fetchedAt: string;
  /** Chain height represented by the response, or null when unavailable */
  blockNumber: number | null;
  /** Block hash represented by the response, or null when unavailable */
  blockHash: string | null;
  /** Balance in the chain's smallest native unit */
  balance: string;
  /** Human-readable balance */
  balanceFormatted: string;
  /** Cumulative value received in the smallest native unit, when the provider exposes it */
  funded?: string;
  /** Cumulative value spent in the smallest native unit, when the provider exposes it */
  spent?: string;
  /** Signed mempool delta in base units, separate from balance; absent when unavailable. */
  unconfirmed?: string;
  /** Native token symbol (ETH, BNB, etc.) */
  symbol: string;
}
/** Fungible token holding for an address */
export interface TokenBalance {
  /** Token contract address */
  contract: string;
  /** Token symbol */
  symbol: string;
  /** Token name */
  name?: string;
  /** Token decimals */
  decimals: number;
  /** Balance (raw string) */
  balance: string;
  /** Human-readable balance */
  balanceFormatted: string;
  /** USD price if available */
  priceUsd?: number;
  /** USD value if available */
  valueUsd?: number;
}
/** Contract information */
export interface ContractInfo {
  /** Contract address */
  address: string;
  /** Whether verified (source code available) */
  isVerified: boolean;
  /** Whether it's a proxy contract */
  isProxy?: boolean;
  /** Implementation address if proxy */
  implementationAddress?: string;
  /** Contract name */
  name?: string;
  /** Compiler version */
  compilerVersion?: string;
  /** Contract ABI (JSON string) */
  abi?: string;
  /** Source code */
  sourceCode?: string;
  /** Whether it's a token (ERC-20/721/1155) */
  isToken?: boolean;
  /** Token standard if applicable */
  tokenStandard?: "ERC-20" | "ERC-721" | "ERC-1155";
  /** Creator address */
  creator?: string;
  /** Creation transaction hash */
  creationTxHash?: string;
}
/** Unit used by a provider's fee suggestions. */
export type GasUnit = "gwei" | "sat/vB" | "litoshi/vB" | "micro-lamports/CU" | "MIST" | "stroops";
/** Gas or fee-market data in provider-native units. */
export interface GasData {
  /** Chain */
  chain: ChainKey;
  /** Unit shared by all price fields in this result. */
  unit: GasUnit;
  /** Safe/low price */
  safeGasPrice?: string;
  /** Proposed/average price */
  proposedGasPrice?: string;
  /** Fast price */
  fastGasPrice?: string;
  /** Base fee */
  baseFee?: string;
  /** Suggested priority fee */
  priorityFee?: string;
}
/** Block info */
export interface BlockInfo {
  /** Block number */
  number: number;
  /** Block hash */
  hash: string;
  /** Parent hash */
  parentHash: string;
  /** Timestamp (ISO) */
  timestamp: string;
  /** Miner/validator address */
  miner: string;
  /** Gas used */
  gasUsed: string;
  /** Gas limit */
  gasLimit: string;
  /** Number of transactions */
  txCount: number;
  /** Base fee per gas (EIP-1559) */
  baseFee?: string;
}
/** Feature flags for operations available on a provider at runtime. */
export interface ProviderCapabilities {
  /** Can get address balances */
  balances: boolean;
  /** Can list transaction history */
  txHistory: boolean;
  /** Can get single tx detail */
  txDetail: boolean;
  /** Can list the unspent outputs of an address */
  utxos: boolean;
  /** Can get contract info (ABI, source) */
  contractInfo: boolean;
  /** Can get token holdings for address */
  tokenBalances: boolean;
  /** Can list token transfers involving an address */
  tokenTransfers: boolean;
  /** Can get gas estimates */
  gasData: boolean;
  /** Can get block info */
  blockInfo: boolean;
}
/** Options for tx history */
export interface TxHistoryOptions {
  /** Start block (inclusive) */
  startBlock?: number;
  /** End block (inclusive) */
  endBlock?: number;
  /** Sort order */
  sort?: "asc" | "desc";
  /** Max results */
  limit?: number;
  /** Page number (1-indexed) */
  page?: number;
}
/** Options for token transfer history */
export interface TokenTransferOptions extends TxHistoryOptions {
  /** Only include transfers of this token contract */
  token?: string;
}
/** Options for token balances */
export interface TokenBalanceOptions {
  /** Only include tokens with non-zero balance */
  nonZeroOnly?: boolean;
}
/** Shared construction options. Providers ignore fields they cannot use. */
export interface ProviderConfig {
  /** API key for providers that require one. */
  apiKey?: string;
  /** Custom API or RPC base URL when the provider supports an override. */
  baseUrl?: string;
  /** Request timeout in milliseconds. Defaults to 15 seconds. */
  timeout?: number;
  /** Fallback chain for multi-chain providers. */
  defaultChain?: ChainKey;
}
/**
 * Round a requested result limit and keep it inside the provider's range.
 *
 * A missing or zero limit uses `max`.
 *
 * @param {number} limit - The `limit` value.
 * @param {number} max - Provider-specific upper bound.
 * @returns {number} The resulting value.
 */
export declare function clampMaxResults(limit?: number, max?: number): number;
/**
 * Format a raw integer amount using token decimals, without float rounding.
 *
 * @example
 *   ```ts
 *   formatWei("1234500000000000000"); // '1.2345'
 *   ```
 *
 * @param {string | bigint} wei - The `wei` value.
 * @param {number} decimals - Number of fractional base-10 digits.
 * @returns {string} The resulting value.
 */
export declare function formatWei(wei: string | bigint, decimals?: number): string;
/**
 * Convert a hexadecimal integer into a decimal string.
 *
 * @example
 *   ```ts
 *   hexToWei("0xff"); // '255'
 *   ```
 *
 * @param {string} hex - The `hex` value.
 * @returns {string} The resulting value.
 */
export declare function hexToWei(hex: string): string;
/**
 * Normalize a canonical chain key, display name, or common CLI alias.
 *
 * Missing values default to `ethereum`. Unknown values are rejected, an empty string included, so a
 * typo cannot silently query the wrong network.
 *
 * @example
 *   ```ts
 *   normalizeChain("arb"); // 'arbitrum'
 *   ```
 *
 * @param {string} input - The `input` value.
 * @returns {ChainKey} The resulting value.
 */
export declare function normalizeChain(input?: string): ChainKey;
/** Immutable view consumed by one HTTP request without freezing the public options DTO. */
interface ClientRequestOptions {
  readonly timeout?: number;
  readonly headers?: Readonly<Record<string, string>>;
  readonly signal?: AbortSignal;
  readonly provider?: string;
}
/**
 * Fetch JSON with Explorers headers and a 15-second default timeout.
 *
 * Transport failures are normalized before they leave this boundary.
 *
 * @param {string} url - The `url` value.
 * @param {ClientRequestOptions} options - Request metadata and cancellation.
 * @returns {Promise<T>} The resulting value.
 */
export declare function getJSON<T>(url: string, options?: ClientRequestOptions): Promise<T>;
/**
 * Build a query string while dropping parameters whose value is `undefined`.
 *
 * @example
 *   ```ts
 *   buildQuery({ page: 2, cursor: undefined }); // '?page=2'
 *   ```
 *
 * @param {Readonly<Record<string, string | number | undefined>>} params - The `params` value.
 * @returns {string} The resulting value.
 */
export declare function buildQuery(params: Readonly<Record<string, string | number | undefined>>): string;
/**
 * Common API for block explorer backends.
 *
 * A provider holds backend configuration, not an address. Pass addresses to the relevant methods
 * and check `capabilities` before using optional operations.
 */
export declare abstract class Provider {
  private readonly timeout;
  constructor(config?: Readonly<ProviderConfig>);
  /**
   * Registry key owned by the concrete class.
   *
   * @returns {string} The resulting value.
   */
  get name(): string;
  /** Operations this provider can actually serve. */
  abstract get capabilities(): ProviderCapabilities;
  /** Fetch the native-token balance for an address. */
  abstract getBalance(address: string, chain?: ChainKey$1): Promise<Balance>;
  /** List transactions involving an address. */
  abstract getTxHistory(address: string, chain?: ChainKey$1, options?: Readonly<TxHistoryOptions>): Promise<Transaction[]>;
  /**
   * Execute a provider-attributed GET request using the configured or per-request timeout.
   *
   * Retries HTTP 429 and JSON bodies that mention a rate limit, with backoff, before the error
   * leaves. The HTTP client itself does not retry.
   *
   * @param {string} url - Request URL.
   * @param {Omit<ClientRequestOptions, "provider">} options - Per-request headers, cancellation, and timeout override.
   * @returns {Promise<T>} Parsed JSON body.
   */
  protected getJSON<T>(url: string, options?: Omit<ClientRequestOptions, "provider">): Promise<T>;
  /**
   * Execute a provider-attributed JSON POST request using the configured timeout.
   *
   * Retries HTTP 429 and JSON bodies that mention a rate limit, with backoff, before the error
   * leaves. Explorer POSTs are reads, so retrying them is safe.
   *
   * @param {string} url - Request URL.
   * @param {unknown} body - JSON request body.
   * @param {Omit<ClientRequestOptions, "provider">} options - Per-request headers, cancellation, and timeout override.
   * @returns {Promise<T>} Parsed JSON body.
   */
  protected postJSON<T>(url: string, body: unknown, options?: Omit<ClientRequestOptions, "provider">): Promise<T>;
  /**
   * Date a completed balance read and preserve any chain position the response exposes.
   *
   * @param {Omit<Balance, "fetchedAt" | "blockNumber" | "blockHash">} balance - The `balance` value.
   * @param {Readonly<{ blockNumber?: number | null; blockHash?: string | null }>} position - The `position` value.
   * @returns {Balance} The resulting value.
   */
  protected snapshotBalance(balance: Omit<Balance, "fetchedAt" | "blockNumber" | "blockHash">, position?: Readonly<{
    blockNumber?: number | null;
    blockHash?: string | null;
  }>): Balance;
}
/** Concrete provider class accepted by the registry. */
export interface ProviderConstructor {
  /** Stable registry key owned by the concrete class. */
  readonly key: string;
  new (config: Readonly<ProviderConfig>): Provider;
}
/** One operation that provider selection can require. */
export type ProviderCapability = keyof ProviderCapabilities;
/** What the registry answers about a provider without loading its module. */
export interface ProviderMeta {
  /** Chains the provider can serve, consulted during auto-selection. */
  chains: readonly ChainKey$1[];
  /** Operations the provider can serve. Omit to keep external registrations backward-compatible. */
  capabilities?: readonly ProviderCapability[];
  /** Public endpoint advertised for the provider. */
  defaultURL?: string;
}
/**
 * One provider in the built-in list.
 *
 * The metadata is repeated here instead of read off the class so that listing providers, matching a
 * chain or reporting an endpoint never loads provider code. `load` pulls the class in when someone
 * actually asks for an instance.
 */
export interface ProviderEntry extends ProviderMeta {
  key: string;
  load: () => Promise<ProviderConstructor>;
}
/**
 * Operations exposed only by providers that support them.
 *
 * Unsupported methods stay absent at runtime. Check `capabilities` before calling.
 */
export interface Provider {
  /** Fetch one transaction by its hash. */
  getTxDetail?(hash: string, chain?: ChainKey$1): Promise<Transaction>;
  /** List the unspent outputs an address still controls, on chains that track them. */
  getUtxos?(address: string, chain?: ChainKey$1): Promise<Utxo[]>;
  /** Fetch available metadata, ABI, and source for a contract address. */
  getContractInfo?(address: string, chain?: ChainKey$1): Promise<ContractInfo>;
  /** List token holdings for an address. */
  getTokenBalances?(address: string, chain?: ChainKey$1, options?: Readonly<TokenBalanceOptions>): Promise<TokenBalance[]>;
  /** List fungible-token transfers involving an address. */
  getTokenTransfers?(address: string, chain?: ChainKey$1, options?: Readonly<TokenTransferOptions>): Promise<TokenTransfer[]>;
  /** Fetch the provider's current gas-price suggestions. */
  getGasData?(chain?: ChainKey$1): Promise<GasData>;
  /** Fetch a block by number. */
  getBlockInfo?(blockNumber: number, chain?: ChainKey$1): Promise<BlockInfo>;
}
export type { ChainKey$1 as ChainKey };
//# sourceMappingURL=provider.d.mts.map