Comet

class Comet(
  Status,
  Block,
  BlockResults,
  Tx,
  TxSearch,
  CometRouter,
):
  """Read-only dYdX Chain Comet HTTP endpoint group."""

  @classmethod
  def new(cls, base_url: str, **kwargs: Unpack[CometOptions]) -> Self:
    """Create a Comet client for a custom RPC endpoint."""
    return cls(base_url=base_url, **kwargs)

  @classmethod
  def oegs(cls, **kwargs: Unpack[CometOptions]) -> Self:
    """Create a Comet client for the OEGS mainnet RPC endpoint."""
    return cls.new(DYDX_COMET_OEGS_RPC_URL, **kwargs)

  @classmethod
  def polkachu(cls, **kwargs: Unpack[CometOptions]) -> Self:
    """Create a Comet client for the Polkachu mainnet RPC endpoint."""
    return cls.new(DYDX_COMET_POLKACHU_RPC_URL, **kwargs)

  @classmethod
  def kingnodes(cls, **kwargs: Unpack[CometOptions]) -> Self:
    """Create a Comet client for the KingNodes mainnet RPC endpoint."""
    return cls.new(DYDX_COMET_KINGNODES_RPC_URL, **kwargs)

  @classmethod
  def enigma(cls, **kwargs: Unpack[CometOptions]) -> Self:
    """Create a Comet client for the Enigma mainnet RPC endpoint."""
    return cls.new(DYDX_COMET_ENIGMA_RPC_URL, **kwargs)

  @classmethod
  def polkachu_archive(cls, **kwargs: Unpack[CometOptions]) -> Self:
    """Create a Comet client for the Polkachu archive mainnet RPC endpoint."""
    return cls.new(DYDX_COMET_POLKACHU_ARCHIVE_RPC_URL, **kwargs)

  @classmethod
  def kingnodes_archive(cls, **kwargs: Unpack[CometOptions]) -> Self:
    """Create a Comet client for the KingNodes archive mainnet RPC endpoint."""
    return cls.new(DYDX_COMET_KINGNODES_ARCHIVE_RPC_URL, **kwargs)

  @classmethod
  def enigma_archive(cls, **kwargs: Unpack[CometOptions]) -> Self:
    """Create a Comet client for the Enigma archive mainnet RPC endpoint."""
    return cls.new(DYDX_COMET_ENIGMA_ARCHIVE_RPC_URL, **kwargs)

  @classmethod
  def publicnode(cls, **kwargs: Unpack[CometOptions]) -> Self:
    """Create a Comet client for the PublicNode community mainnet RPC endpoint."""
    return cls.new(DYDX_COMET_PUBLICNODE_RPC_URL, **kwargs)

  @classmethod
  def lavenderfive(cls, **kwargs: Unpack[CometOptions]) -> Self:
    """Create a Comet client for the Lavender.Five community mainnet RPC endpoint."""
    return cls.new(DYDX_COMET_LAVENDERFIVE_RPC_URL, **kwargs)

  @classmethod
  def imperator(cls, **kwargs: Unpack[CometOptions]) -> Self:
    """Create a Comet client for the Imperator community mainnet RPC endpoint."""
    return cls.new(DYDX_COMET_IMPERATOR_RPC_URL, **kwargs)

  @classmethod
  def testnet_oegs(cls, **kwargs: Unpack[CometOptions]) -> Self:
    """Create a Comet client for the OEGS testnet RPC endpoint."""
    return cls.new(DYDX_TESTNET_COMET_OEGS_RPC_URL, **kwargs)

  @classmethod
  def testnet_enigma(cls, **kwargs: Unpack[CometOptions]) -> Self:
    """Create a Comet client for the Enigma testnet RPC endpoint."""
    return cls.new(DYDX_TESTNET_COMET_ENIGMA_RPC_URL, **kwargs)

  @classmethod
  def testnet_kingnodes(cls, **kwargs: Unpack[CometOptions]) -> Self:
    """Create a Comet client for the KingNodes testnet RPC endpoint."""
    return cls.new(DYDX_TESTNET_COMET_KINGNODES_RPC_URL, **kwargs)

  @classmethod
  def testnet_polkachu(cls, **kwargs: Unpack[CometOptions]) -> Self:
    """Create a Comet client for the Polkachu testnet RPC endpoint."""
    return cls.new(DYDX_TESTNET_COMET_POLKACHU_RPC_URL, **kwargs)

class Status(CometEndpoint):
  """Comet status endpoint group."""

  async def status(self, validate: bool | None = None) -> StatusResponse:
    """Return Comet node health, sync state, and validator info.

    Args:
      validate: Validation override for this request.

    Returns:
      Node status result.

    References:
      - [CometBFT RPC docs](https://docs.cosmos.network/cometbft/latest/api-reference/rpc/info/status)
    """
    return await self.result('/status', result_adapter=status_adapter, validate=validate)

class Block(CometEndpoint):
  """Comet block endpoint group."""

  async def block(
    self,
    height: int | None = None,
    validate: bool | None = None,
  ) -> BlockResponse:
    """Return a Comet block by height or the latest block.

    Args:
      height: Block height to fetch.
      validate: Validation override for this request.

    Returns:
      Block result.

    References:
      - [CometBFT RPC docs](https://docs.cosmos.network/cometbft/latest/api-reference/rpc/info/block)
    """
    params = {'height': height} if height is not None else None
    return await self.result('/block', params=params, result_adapter=block_adapter, validate=validate)

class BlockResults(CometEndpoint):
  """Comet block results endpoint group."""

  async def block_results(
    self,
    height: int | None = None,
    validate: bool | None = None,
  ) -> BlockResultsResponse:
    """Return ABCI execution results for a block.

    Args:
      height: Block height whose execution results should be returned.
      validate: Validation override for this request.

    Returns:
      Block execution results.

    References:
      - [CometBFT RPC docs](https://docs.cosmos.network/cometbft/latest/api-reference/rpc/info/block_results)
    """
    params = {'height': height} if height is not None else None
    return await self.result('/block_results', params=params, result_adapter=block_results_adapter, validate=validate)

class Tx(CometEndpoint):
  """Comet transaction lookup endpoint group."""

  async def tx(
    self,
    hash: str,
    *,
    prove: bool | None = None,
    validate: bool | None = None,
  ) -> TxResponse:
    """Return one indexed Comet transaction by hash.

    Args:
      hash: Transaction hash. Comet HTTP accepts the hash with a `0x` prefix.
      prove: Include a Merkle proof for the transaction.
      validate: Validation override for this request.

    Returns:
      Transaction lookup result.

    References:
      - [CometBFT RPC docs](https://docs.cosmos.network/cometbft/latest/api-reference/rpc/info/tx)
    """
    params: dict[str, str | bool] = {'hash': hash}
    if prove is not None:
      params['prove'] = prove
    return await self.result('/tx', params=params, result_adapter=tx_adapter, validate=validate)

class TxSearch(CometEndpoint):
  """Comet transaction search endpoint group."""

  async def tx_search(
    self,
    query: str,
    *,
    prove: bool | None = None,
    page: int | None = None,
    per_page: int | None = None,
    order_by: Literal['asc', 'desc'] | None = None,
    validate: bool | None = None,
  ) -> TxSearchResponse:
    """Search indexed Comet transactions by event query.

    Args:
      query: Comet event query expression.
      prove: Include proofs for returned transactions.
      page: Page number for paginated results.
      per_page: Maximum transactions to return on the page.
      order_by: Sort order for matching transactions.
      validate: Validation override for this request.

    Returns:
      Transaction search result.

    References:
      - [CometBFT RPC docs](https://docs.cosmos.network/cometbft/latest/api-reference/rpc/info/tx_search)
    """
    params: dict[str, str | bool | int] = {'query': json.dumps(query)}
    if prove is not None:
      params['prove'] = prove
    if page is not None:
      params['page'] = page
    if per_page is not None:
      params['per_page'] = per_page
    if order_by is not None:
      params['order_by'] = json.dumps(order_by)
    return await self.result('/tx_search', params=params, result_adapter=tx_search_adapter, validate=validate)

  def tx_search_paged(
    self,
    query: str,
    *,
    prove: bool | None = None,
    per_page: int | None = None,
    order_by: Literal['asc', 'desc'] | None = None,
    validate: bool | None = None,
  ) -> PaginatedResponse[TxResponse, tuple[int, int]]:
    """Page through indexed Comet transactions by event query.

    Args:
      query: Comet event query expression.
      prove: Include proofs for returned transactions.
      per_page: Maximum transactions to return on each page.
      order_by: Sort order for matching transactions.
      validate: Validation override for each request.

    Returns:
      A paginated response yielding matching transaction pages.

    References:
      - [CometBFT RPC docs](https://docs.cosmos.network/cometbft/latest/api-reference/rpc/info/tx_search)
    """
    async def next(state: tuple[int, int]) -> tuple[list[TxResponse], tuple[int, int] | None]:
      """Fetch the next transaction search page."""
      page, seen = state
      response = await self.tx_search(
        query,
        prove=prove,
        page=page,
        per_page=per_page,
        order_by=order_by,
        validate=validate,
      )
      txs = response['txs']
      seen += len(txs)
      total = int(response['total_count'])
      if seen >= total or not txs:
        return txs, None
      return txs, (page + 1, seen)

    return PaginatedResponse((1, 0), next)