"""Query builder for the interchain-trace endpoints.

Anchor proofs are chained, so by default the trace returns the first anchor per
public chain; these options change how many and which chains are returned.
"""

from typing import List, Optional
from urllib.parse import quote


def interchain_query(
    per_chain: Optional[int] = None, chains: Optional[List[str]] = None
) -> str:
    """Build the "?perChain=...&chains=..." suffix for the interchain trace
    endpoints.

    Returns "" when nothing is set (the server then applies its defaults: one
    anchor per chain, all chains). ``per_chain`` caps anchors per public chain,
    earliest-first (1 = first per chain; 0 = all). ``chains`` restricts to the
    given chain ids ("1" = ETH mainnet, "0" = BTC; testnet ids differ).
    """
    parts: List[str] = []
    if per_chain is not None:
        parts.append(f"perChain={int(per_chain)}")
    if chains:
        parts.append("chains=" + ",".join(quote(str(c), safe="") for c in chains))
    return "?" + "&".join(parts) if parts else ""