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.
2026-06-02 14:12:59 -04:00
parent 8b007dcbab
commit e4e49218d0
5 changed files with 148 additions and 1 deletions
--- a/prime_sdk/models.py
+++ b/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
 # --------------------------------------------------------------------------- #