add get_interchain: trace a transaction/block to validator blocks + interchain anchors

New transaction.get_interchain and block.get_interchain call the prime-node
/api/v1/{transaction,block}/{id}/interchain endpoints, returning an
InterchainTrace {block_id, validator_blocks, interchain_transactions}. Adds
VerificationBlock / InterchainTransaction / InterchainTrace dataclasses with
from_dict, exports them, and a from_dict test.

prime_sdk/__init__.py

@@ -48,6 +48,8 @@ from .models import (
     BlockHeader,
     BlockProof,
     GrpcConnectionInfo,
+    InterchainTrace,
+    InterchainTransaction,
     ListResponse,
     ListTransactionsResponse,
     SmartContract,
@@ -67,6 +69,7 @@ from .models import (
     TransactionType,
     TransactionTypeCreateRequest,
     TransactionTypeCreateResponse,
+    VerificationBlock,
 )
 from .system import SystemClient
 from .transaction import TransactionClient
@@ -125,6 +128,8 @@ __all__ = [
     "BlockHeader",
     "BlockProof",
     "GrpcConnectionInfo",
+    "InterchainTrace",
+    "InterchainTransaction",
     "ListResponse",
     "ListTransactionsResponse",
     "SmartContract",
@@ -144,4 +149,5 @@ __all__ = [
     "TransactionType",
     "TransactionTypeCreateRequest",
     "TransactionTypeCreateResponse",
+    "VerificationBlock",
 ]

prime_sdk/block.py

@@ -1,7 +1,7 @@
 """Block endpoints."""
 
 from .client import Client
-from .models import Block
+from .models import Block, InterchainTrace
 
 
 class BlockClient:
@@ -10,3 +10,11 @@ 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:
+        """Trace a block to the validator (verification) blocks that validated it
+        and the public-chain interchain anchors those validator blocks were
+        bundled into."""
+        return self._client.get(
+            f"/api/v1/block/{block_id}/interchain", InterchainTrace
+        )

prime_sdk/models.py

@@ -350,6 +350,92 @@ class Block:
         )
 
 
+# --------------------------------------------------------------------------- #
+# Interchain trace
+# --------------------------------------------------------------------------- #
+
+
+@dataclass
+class VerificationBlock:
+    """A validator's verification of a prime block."""
+
+    version: str = ""
+    prime_chain_id: str = ""
+    prime_block_id: str = ""
+    timestamp: str = ""
+    verifier_public_key: str = ""
+    verifier_signature: str = ""
+
+    @classmethod
+    def from_dict(cls, d: Dict[str, Any]) -> "VerificationBlock":
+        return cls(
+            version=d.get("version", ""),
+            prime_chain_id=d.get("primeChainId", ""),
+            prime_block_id=d.get("primeBlockId", ""),
+            timestamp=d.get("timestamp", ""),
+            verifier_public_key=d.get("verifierPublicKey", ""),
+            verifier_signature=d.get("verifierSignature", ""),
+        )
+
+
+@dataclass
+class InterchainTransaction:
+    """An anchor broadcast to a public blockchain (e.g. ETH/BTC) bundling one or
+    more validator blocks. ``validator_blocks`` holds the covered prime block ids;
+    ``covered_prime_chain_ids`` the prime chains they belong to."""
+
+    id: int = 0
+    version: str = ""
+    timestamp: str = ""
+    chain_id: str = ""
+    trans_hash: str = ""
+    block_id: str = ""
+    validator_blocks: List[str] = field(default_factory=list)
+    validator_blockhash: str = ""
+    signature: str = ""
+    covered_prime_chain_ids: List[str] = field(default_factory=list)
+
+    @classmethod
+    def from_dict(cls, d: Dict[str, Any]) -> "InterchainTransaction":
+        return cls(
+            id=d.get("id", 0),
+            version=d.get("version", ""),
+            timestamp=d.get("timestamp", ""),
+            chain_id=d.get("chainId", ""),
+            trans_hash=d.get("transHash", ""),
+            block_id=d.get("blockId", ""),
+            validator_blocks=d.get("validatorBlocks") or [],
+            validator_blockhash=d.get("validatorBlockhash", ""),
+            signature=d.get("signature", ""),
+            covered_prime_chain_ids=d.get("coveredPrimeChainIds") or [],
+        )
+
+
+@dataclass
+class InterchainTrace:
+    """Links a prime block to the validator (verification) blocks that validated
+    it and the public-chain interchain anchors those validator blocks were
+    bundled into. Returned by ``transaction.get_interchain`` and
+    ``block.get_interchain``."""
+
+    block_id: str = ""
+    validator_blocks: List[VerificationBlock] = field(default_factory=list)
+    interchain_transactions: List[InterchainTransaction] = field(default_factory=list)
+
+    @classmethod
+    def from_dict(cls, d: Dict[str, Any]) -> "InterchainTrace":
+        return cls(
+            block_id=d.get("blockId", ""),
+            validator_blocks=[
+                VerificationBlock.from_dict(v) for v in (d.get("validatorBlocks") or [])
+            ],
+            interchain_transactions=[
+                InterchainTransaction.from_dict(v)
+                for v in (d.get("interchainTransactions") or [])
+            ],
+        )
+
+
 # --------------------------------------------------------------------------- #
 # System / generic
 # --------------------------------------------------------------------------- #

prime_sdk/transaction.py

@@ -2,6 +2,7 @@
 
 from .client import CONTENT_TYPE_JSON, Client
 from .models import (
+    InterchainTrace,
     ListTransactionsResponse,
     Transaction,
     TransactionBulkRequest,
@@ -39,5 +40,14 @@ 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:
+        """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."""
+        return self._client.get(
+            f"/api/v1/transaction/{transaction_id}/interchain", InterchainTrace
+        )
+
     def list(self) -> ListTransactionsResponse:
         return self._client.get("/api/v1/transaction/", ListTransactionsResponse)