{"version":3,"file":"types.mjs","names":[],"sources":["../../src/core/types.ts"],"sourcesContent":["/** Explorers — Unified block explorer provider types */\n\nimport { getChain } from \"@agntn/chains\";\nimport type { ChainKey } from \"@agntn/chains\";\n\nexport type { ChainKey } from \"@agntn/chains\";\n\n/** Transaction status */\nexport type TxStatus = \"success\" | \"failed\" | \"pending\";\n\n/** Normalized fungible-token transfer */\nexport interface TokenTransfer {\n  /** Token contract address */\n  contract: string;\n  /** Token symbol */\n  symbol: string;\n  /** Token name */\n  name?: string;\n  /** Token decimals */\n  decimals: number;\n  /** Transfer amount (raw, string to avoid float) */\n  value: string;\n  /** Human-readable amount */\n  valueFormatted: string;\n  /** From address */\n  from: string;\n  /** To address */\n  to: string;\n  /** Transaction hash */\n  txHash: string;\n  /** Block number */\n  blockNumber: number;\n  /** Timestamp (ISO) */\n  timestamp?: string;\n}\n\n/** One data push carried by an OP_RETURN output */\nexport interface OpReturnPayload {\n  /** Pushed bytes as lowercase hex, without the opcode and the push prefix */\n  hex: string;\n  /** UTF-8 reading of the payload, present only when the bytes are printable text */\n  text?: string;\n}\n\n/** Normalized transaction */\nexport interface Transaction {\n  /** Transaction hash */\n  hash: string;\n  /** Block number */\n  blockNumber: number;\n  /** Timestamp (ISO) */\n  timestamp?: string;\n  /** Sender */\n  from: string;\n  /** Recipient (null for contract creation) */\n  to: string | null;\n  /** Value in the chain's smallest native unit */\n  value: string;\n  /** Human-readable value in native token */\n  valueFormatted: string;\n  /** Execution units consumed, when the chain exposes them */\n  gasUsed?: string;\n  /** Price per execution unit in the chain's smallest native unit */\n  gasPrice?: string;\n  /** Total transaction fee in the chain's smallest native unit */\n  fee?: string;\n  /** Transaction status */\n  status: TxStatus;\n  /** Method ID (first 4 bytes of input data) */\n  methodId?: string;\n  /** Function name if decoded */\n  functionName?: string;\n  /** Whether this is a contract interaction */\n  isContractInteraction: boolean;\n  /** Token transfers within this tx */\n  tokenTransfers: TokenTransfer[];\n  /** Data pushed by the OP_RETURN outputs, on chains that carry them */\n  opReturn?: OpReturnPayload[];\n  /** Raw provider data */\n  raw?: Record<string, unknown>;\n}\n\n/** Unspent output an address still controls */\nexport interface Utxo {\n  /** Transaction that created the output */\n  txid: string;\n  /** Output index inside that transaction */\n  vout: number;\n  /** Value in the chain's smallest native unit */\n  value: string;\n  /** Human-readable value in native token */\n  valueFormatted: string;\n  /** Whether the funding transaction is in a block */\n  confirmed: boolean;\n  /** Block number of the funding transaction, or null while it waits in the mempool */\n  blockNumber: number | null;\n  /** Block hash of the funding transaction, or null while it waits in the mempool */\n  blockHash: string | null;\n  /** Timestamp (ISO) of the funding block */\n  timestamp?: string;\n}\n\n/** Normalized address balance */\nexport interface Balance {\n  /** Address */\n  address: string;\n  /** Chain */\n  chain: ChainKey;\n  /** Time when the provider completed the read */\n  fetchedAt: string;\n  /** Chain height represented by the response, or null when unavailable */\n  blockNumber: number | null;\n  /** Block hash represented by the response, or null when unavailable */\n  blockHash: string | null;\n  /** Balance in the chain's smallest native unit */\n  balance: string;\n  /** Human-readable balance */\n  balanceFormatted: string;\n  /** Cumulative value received in the smallest native unit, when the provider exposes it */\n  funded?: string;\n  /** Cumulative value spent in the smallest native unit, when the provider exposes it */\n  spent?: string;\n  /** Signed mempool delta in base units, separate from balance; absent when unavailable. */\n  unconfirmed?: string;\n  /** Native token symbol (ETH, BNB, etc.) */\n  symbol: string;\n}\n\n/** Fungible token holding for an address */\nexport interface TokenBalance {\n  /** Token contract address */\n  contract: string;\n  /** Token symbol */\n  symbol: string;\n  /** Token name */\n  name?: string;\n  /** Token decimals */\n  decimals: number;\n  /** Balance (raw string) */\n  balance: string;\n  /** Human-readable balance */\n  balanceFormatted: string;\n  /** USD price if available */\n  priceUsd?: number;\n  /** USD value if available */\n  valueUsd?: number;\n}\n\n/** Contract information */\nexport interface ContractInfo {\n  /** Contract address */\n  address: string;\n  /** Whether verified (source code available) */\n  isVerified: boolean;\n  /** Whether it's a proxy contract */\n  isProxy?: boolean;\n  /** Implementation address if proxy */\n  implementationAddress?: string;\n  /** Contract name */\n  name?: string;\n  /** Compiler version */\n  compilerVersion?: string;\n  /** Contract ABI (JSON string) */\n  abi?: string;\n  /** Source code */\n  sourceCode?: string;\n  /** Whether it's a token (ERC-20/721/1155) */\n  isToken?: boolean;\n  /** Token standard if applicable */\n  tokenStandard?: \"ERC-20\" | \"ERC-721\" | \"ERC-1155\";\n  /** Creator address */\n  creator?: string;\n  /** Creation transaction hash */\n  creationTxHash?: string;\n}\n\n/** Unit used by a provider's fee suggestions. */\nexport type GasUnit = \"gwei\" | \"sat/vB\" | \"litoshi/vB\" | \"micro-lamports/CU\" | \"MIST\" | \"stroops\";\n\n/** Gas or fee-market data in provider-native units. */\nexport interface GasData {\n  /** Chain */\n  chain: ChainKey;\n  /** Unit shared by all price fields in this result. */\n  unit: GasUnit;\n  /** Safe/low price */\n  safeGasPrice?: string;\n  /** Proposed/average price */\n  proposedGasPrice?: string;\n  /** Fast price */\n  fastGasPrice?: string;\n  /** Base fee */\n  baseFee?: string;\n  /** Suggested priority fee */\n  priorityFee?: string;\n}\n\n/** Block info */\nexport interface BlockInfo {\n  /** Block number */\n  number: number;\n  /** Block hash */\n  hash: string;\n  /** Parent hash */\n  parentHash: string;\n  /** Timestamp (ISO) */\n  timestamp: string;\n  /** Miner/validator address */\n  miner: string;\n  /** Gas used */\n  gasUsed: string;\n  /** Gas limit */\n  gasLimit: string;\n  /** Number of transactions */\n  txCount: number;\n  /** Base fee per gas (EIP-1559) */\n  baseFee?: string;\n}\n\n/** Feature flags for operations available on a provider at runtime. */\nexport interface ProviderCapabilities {\n  /** Can get address balances */\n  balances: boolean;\n  /** Can list transaction history */\n  txHistory: boolean;\n  /** Can get single tx detail */\n  txDetail: boolean;\n  /** Can list the unspent outputs of an address */\n  utxos: boolean;\n  /** Can get contract info (ABI, source) */\n  contractInfo: boolean;\n  /** Can get token holdings for address */\n  tokenBalances: boolean;\n  /** Can list token transfers involving an address */\n  tokenTransfers: boolean;\n  /** Can get gas estimates */\n  gasData: boolean;\n  /** Can get block info */\n  blockInfo: boolean;\n}\n\n/** Options for tx history */\nexport interface TxHistoryOptions {\n  /** Start block (inclusive) */\n  startBlock?: number;\n  /** End block (inclusive) */\n  endBlock?: number;\n  /** Sort order */\n  sort?: \"asc\" | \"desc\";\n  /** Max results */\n  limit?: number;\n  /** Page number (1-indexed) */\n  page?: number;\n}\n\n/** Options for token transfer history */\nexport interface TokenTransferOptions extends TxHistoryOptions {\n  /** Only include transfers of this token contract */\n  token?: string;\n}\n\n/** Options for token balances */\nexport interface TokenBalanceOptions {\n  /** Only include tokens with non-zero balance */\n  nonZeroOnly?: boolean;\n}\n\n/** Shared construction options. Providers ignore fields they cannot use. */\nexport interface ProviderConfig {\n  /** API key for providers that require one. */\n  apiKey?: string;\n  /** Custom API or RPC base URL when the provider supports an override. */\n  baseUrl?: string;\n  /** Request timeout in milliseconds. Defaults to 15 seconds. */\n  timeout?: number;\n  /** Fallback chain for multi-chain providers. */\n  defaultChain?: ChainKey;\n}\n\n/**\n * Round a requested result limit and keep it inside the provider's range.\n *\n * A missing or zero limit uses `max`.\n *\n * @param {number} limit - The `limit` value.\n * @param {number} max - Provider-specific upper bound.\n * @returns {number} The resulting value.\n */\nexport function clampMaxResults(limit?: number, max = 100): number {\n  if (!limit) return max;\n  return Math.min(Math.max(1, Math.round(limit)), max);\n}\n\n/**\n * Convert a unix timestamp in seconds to an ISO 8601 string.\n *\n * @param {number} seconds - The `seconds` value.\n * @returns {string} The resulting value.\n */\nexport function toTimestamp(seconds: number): string {\n  return new Date(seconds * 1000).toISOString();\n}\n\n/**\n * Format a raw integer amount using token decimals, without float rounding.\n *\n * @example\n *   ```ts\n *   formatWei(\"1234500000000000000\"); // '1.2345'\n *   ```\n *\n * @param {string | bigint} wei - The `wei` value.\n * @param {number} decimals - Number of fractional base-10 digits.\n * @returns {string} The resulting value.\n */\nexport function formatWei(wei: string | bigint, decimals = 18): string {\n  if (!Number.isInteger(decimals) || decimals < 0 || decimals > 255) {\n    throw new RangeError(`Invalid decimals: ${decimals}`);\n  }\n  const w = typeof wei === \"string\" ? BigInt(wei) : wei;\n  const negative = w < 0n;\n  const abs = negative ? -w : w;\n  const base = 10n ** BigInt(decimals);\n  const intPart = abs / base;\n  const fracPart = abs % base;\n  const fracStr = fracPart.toString().padStart(decimals, \"0\").replace(/0+$/, \"\");\n  const result = fracStr ? `${intPart}.${fracStr}` : `${intPart}`;\n  return negative ? `-${result}` : result;\n}\n\n/**\n * Convert a hexadecimal integer into a decimal string.\n *\n * @example\n *   ```ts\n *   hexToWei(\"0xff\"); // '255'\n *   ```\n *\n * @param {string} hex - The `hex` value.\n * @returns {string} The resulting value.\n */\nexport function hexToWei(hex: string): string {\n  return BigInt(hex).toString();\n}\n\n/**\n * Multiply decimal integer strings without crossing the IEEE-754 boundary.\n *\n * @param {string} left - The `left` value.\n * @param {string} right - The `right` value.\n * @returns {string} The resulting value.\n */\nexport function multiplyIntegerStrings(left: string, right: string): string {\n  return (BigInt(left) * BigInt(right)).toString();\n}\n\n/**\n * Normalize a canonical chain key, display name, or common CLI alias.\n *\n * Missing values default to `ethereum`. Unknown values are rejected, an empty string included, so a\n * typo cannot silently query the wrong network.\n *\n * @example\n *   ```ts\n *   normalizeChain(\"arb\"); // 'arbitrum'\n *   ```\n *\n * @param {string} input - The `input` value.\n * @returns {ChainKey} The resulting value.\n */\nexport function normalizeChain(input?: string): ChainKey {\n  try {\n    return getChain(input).key;\n  } catch {\n    throw new RangeError(`Unknown chain: ${input}`);\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;AAiSE,SAAK,UAAO,KAAO,WAAA,IAAA;CACnB,IAAA,CAAA,OAAY,UAAS,QAAO,KAAK,WAAY,KAAM,WAAA,KAAA,MAAA,IAAA,WAAA,qBAAA,UAAA;CACrD,MAAA,IAAA,OAAA,QAAA,WAAA,OAAA,GAAA,IAAA;;;;;;;CAQA,OAAA,WAAgB,IAAY,WAAyB;AACnD;;;;;;;;;;;EAeF,MAAA,IAAgB,WAAU,kBAA6C,OAAA;CACrE;AAGA;AAEA,SAAM,iBAAkB,WAAI,UAAA,wBAAA,gBAAA,aAAA"}