get_interchain: per_chain + chains options (default first anchor per chain); bump 0.5.0

transaction.get_interchain / block.get_interchain take per_chain= and chains=
kwargs mapping to prime-node's ?perChain=&chains= params. Default (no kwargs)
returns one anchor per chain. Shared interchain_query() helper, exported; pytest.

prime_sdk/__init__.py

@@ -81,6 +81,7 @@ from .models import (
     SecurityResult,
     TransactionReport,
 )
+from .interchain import interchain_query
 from .proof_measure import DEFAULT_BASE_URL as PROOF_MEASURE_DEFAULT_BASE_URL
 from .proof_measure import ProofMeasureClient
 from .system import SystemClient
@@ -88,7 +89,7 @@ from .transaction import TransactionClient
 from .transaction_type import TransactionTypeClient
 from .unauthenticated_client import UnauthenticatedClient
 
-__version__ = "0.4.0"
+__version__ = "0.5.0"
 
 
 class DragonchainSDK:
@@ -148,6 +149,7 @@ __all__ = [
     "ProofMeasureClient",
     "UnauthenticatedClient",
     "PROOF_MEASURE_DEFAULT_BASE_URL",
+    "interchain_query",
     # models
     "Block",
     "BlockHeader",

prime_sdk/block.py

@@ -1,6 +1,9 @@
 """Block endpoints."""
 
+from typing import List, Optional
+
 from .client import Client
+from .interchain import interchain_query
 from .models import Block, InterchainTrace
 
 
@@ -11,10 +14,21 @@ class BlockClient:
     def get(self, block_id: str) -> Block:
         return self._client.get(f"/api/v1/block/{block_id}", Block)
 
-    def get_interchain(self, block_id: str) -> InterchainTrace:
+    def get_interchain(
+        self,
+        block_id: str,
+        per_chain: Optional[int] = None,
+        chains: Optional[List[str]] = None,
+    ) -> InterchainTrace:
         """Trace a block to the validator (verification) blocks that validated it
         and the public-chain interchain anchors those validator blocks were
-        bundled into."""
+        bundled into.
+
+        By default returns the first anchor per public chain (anchor proofs are
+        chained, so the earliest per chain is the meaningful one). ``per_chain``
+        caps anchors per chain (1 = first per chain; 0 = all); ``chains``
+        restricts to specific chain ids."""
         return self._client.get(
-            f"/api/v1/block/{block_id}/interchain", InterchainTrace
+            f"/api/v1/block/{block_id}/interchain{interchain_query(per_chain, chains)}",
+            InterchainTrace,
         )

prime_sdk/interchain.py

@@ -0,0 +1,27 @@
+"""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 ""

prime_sdk/transaction.py

@@ -1,6 +1,9 @@
 """Transaction endpoints."""
 
+from typing import List, Optional
+
 from .client import CONTENT_TYPE_JSON, Client
+from .interchain import interchain_query
 from .models import (
     InterchainTrace,
     ListTransactionsResponse,
@@ -40,13 +43,25 @@ class TransactionClient:
     def get(self, transaction_id: str) -> Transaction:
         return self._client.get(f"/api/v1/transaction/{transaction_id}", Transaction)
 
-    def get_interchain(self, transaction_id: str) -> InterchainTrace:
+    def get_interchain(
+        self,
+        transaction_id: str,
+        per_chain: Optional[int] = None,
+        chains: Optional[List[str]] = None,
+    ) -> InterchainTrace:
         """Trace a transaction to the validator (verification) blocks that
         validated its prime block and the public-chain interchain anchors those
         validator blocks were bundled into. If the transaction is still pending
-        (not yet in a block) the trace's lists are empty."""
+        (not yet in a block) the trace's lists are empty.
+
+        By default returns the first anchor per public chain (anchor proofs are
+        chained, so the earliest per chain is the meaningful one). ``per_chain``
+        caps anchors per chain (1 = first per chain; 0 = all); ``chains``
+        restricts to specific chain ids."""
         return self._client.get(
-            f"/api/v1/transaction/{transaction_id}/interchain", InterchainTrace
+            f"/api/v1/transaction/{transaction_id}/interchain"
+            f"{interchain_query(per_chain, chains)}",
+            InterchainTrace,
         )
 
     def list(self) -> ListTransactionsResponse: