build(agent): new-agents-2#7e3bbc iteration

cosmic_ledger/__init__.py

@@ -1,6 +1,6 @@
 from .ledger import LocalLedger
 from .contracts import DataContractRegistry
-from .delta import DeltaLog, merkle_root
+from .delta import DeltaLog, merkle_root, verify_delta_root
 from .crypto import Signer
 
-__all__ = ["LocalLedger", "DataContractRegistry", "DeltaLog", "merkle_root", "Signer"]
+__all__ = ["LocalLedger", "DataContractRegistry", "DeltaLog", "merkle_root", "verify_delta_root", "Signer"]

cosmic_ledger/delta.py

@@ -50,6 +50,34 @@ def merkle_path_for_index(digests: List[str], index: int) -> dict:
     root = level[0].hex()
     return {"root": root, "path": path}
 
+def verify_delta_root(delta_entries: List[dict]) -> bool:
+    """Verify that a sequence of delta entries shares a consistent Merkle root.
+
+    Each delta entry is expected to contain a top-level "digest" field, which
+    is the SHA-256 digest of the serialized entry payload. The function computes
+    the Merkle root over all provided digests and ensures that every delta entry
+    that carries a "delta_root" field agrees with the computed root. If no
+    delta_root is present, the function returns True once a root can be derived
+    from the available digests.
+
+    This helper is intended for cross-node verification when exchanging delta blocks.
+    """
+    if not delta_entries:
+        return True
+
+    # Collect all available digests in the delta entries
+    digests = [e.get("digest") for e in delta_entries if e.get("digest") is not None]
+    if not digests:
+        return True
+
+    computed_root = merkle_root(digests)
+    # If entries provide an explicit delta_root, ensure consistency across them
+    for e in delta_entries:
+        explicit = e.get("delta_root")
+        if explicit is not None and explicit != computed_root:
+            return False
+    return True
+
 class DeltaLog:
     def __init__(self):
         self.entries = []  # each entry is a dict with digest and payload