alx-protocol 1.0.0__py3-none-any.whl

alx_protocol/__init__.py

@@ -0,0 +1,34 @@
+"""
+ALX Protocol — Python implementation.
+
+Deterministic infrastructure for verifiable content,
+interoperable context, and traceable attribution.
+
+One primitive: Block = { blockHash, contentHash, parentHashes, content }
+Four operations: canonicalize, hash, validate, trace
+"""
+
+from alx_protocol.canonical import canonicalize
+from alx_protocol.block import (
+    derive_block_hash,
+    derive_content_hash,
+    create_block,
+    validate_block,
+    normalize_hash,
+    normalize_hashes,
+)
+from alx_protocol.lineage import validate_lineage, validate_graph, build_graph
+from alx_protocol.trace import trace_attribution
+from alx_protocol.merkle import build_merkle_tree, get_merkle_proof, verify_merkle_proof
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "__version__",
+    "canonicalize",
+    "derive_block_hash", "derive_content_hash", "create_block", "validate_block",
+    "normalize_hash", "normalize_hashes",
+    "validate_lineage", "validate_graph", "build_graph",
+    "trace_attribution",
+    "build_merkle_tree", "get_merkle_proof", "verify_merkle_proof",
+]

alx_protocol/block.py

@@ -0,0 +1,58 @@
+"""
+ALX Protocol — Block primitive.
+
+Block = { blockHash, contentHash, parentHashes, content }
+
+blockHash   = keccak256(canonicalize({ content, parentHashes }))
+contentHash = keccak256(canonicalize(content))
+"""
+
+import re
+from typing import Any, Dict, List, Optional
+from eth_hash.auto import keccak
+from alx_protocol.canonical import canonicalize
+
+HASH_PATTERN = re.compile(r"^0x[a-f0-9]{64}$")
+
+
+def derive_block_hash(content: Any, parent_hashes: Optional[List[str]] = None) -> str:
+    parents = normalize_hashes(parent_hashes or [])
+    canonical = canonicalize({"content": content, "parentHashes": parents})
+    return "0x" + keccak(canonical.encode("utf-8")).hex()
+
+
+def derive_content_hash(content: Any) -> str:
+    canonical = canonicalize(content if content is not None else None)
+    return "0x" + keccak(canonical.encode("utf-8")).hex()
+
+
+def create_block(content: Any, parent_hashes: Optional[List[str]] = None) -> Dict[str, Any]:
+    parents = normalize_hashes(parent_hashes or [])
+    return {
+        "blockHash": derive_block_hash(content, parents),
+        "contentHash": derive_content_hash(content),
+        "parentHashes": parents,
+        "content": content,
+    }
+
+
+def validate_block(block: Dict[str, Any]) -> Dict[str, Any]:
+    expected = derive_block_hash(block.get("content"), block.get("parentHashes", []))
+    actual = normalize_hash(block["blockHash"])
+    return {"ok": expected == actual, "expected": expected, "actual": actual}
+
+
+def normalize_hash(h: str) -> str:
+    s = str(h).strip().lower()
+    if not HASH_PATTERN.match(s):
+        raise ValueError(f"invalid hash: {h}")
+    return s
+
+
+def normalize_hashes(hashes: List[str]) -> List[str]:
+    result = set()
+    for h in hashes:
+        s = str(h).strip().lower()
+        if HASH_PATTERN.match(s):
+            result.add(s)
+    return sorted(result)

alx_protocol/canonical.py

@@ -0,0 +1,63 @@
+"""
+ALX Protocol — Canonicalization.
+
+Deterministic JSON serialization. Layer 1 of the protocol.
+
+Rules:
+  - Objects: keys sorted lexicographically, undefined/None values excluded
+  - Arrays: order-preserving (not sorted)
+  - null/None: canonicalizes to "null"
+  - Numbers: -0 → 0, safe integer range enforced, non-finite rejected
+  - Strings: JSON-escaped
+  - Depth limit: 128
+"""
+
+import json
+import math
+from typing import Any
+
+MAX_DEPTH = 128
+MAX_SAFE_INTEGER = 2**53 - 1
+MIN_SAFE_INTEGER = -(2**53 - 1)
+
+
+def canonicalize(value: Any, _depth: int = 0) -> str:
+    if _depth > MAX_DEPTH:
+        raise ValueError(f"Canonicalization depth exceeded {MAX_DEPTH}")
+
+    if value is None:
+        return "null"
+
+    if isinstance(value, bool):
+        return "true" if value else "false"
+
+    if isinstance(value, int) and not isinstance(value, bool):
+        if value > MAX_SAFE_INTEGER or value < MIN_SAFE_INTEGER:
+            raise ValueError(f"Integer out of safe range: {value}")
+        return str(value)
+
+    if isinstance(value, float):
+        if not math.isfinite(value):
+            raise ValueError(f"Non-finite number not allowed: {value}")
+        if value == 0.0 and math.copysign(1.0, value) == -1.0:
+            return "0"  # -0 → 0
+        if value == int(value) and MIN_SAFE_INTEGER <= value <= MAX_SAFE_INTEGER:
+            return str(int(value))
+        return json.dumps(value)
+
+    if isinstance(value, str):
+        return json.dumps(value, ensure_ascii=False)
+
+    if isinstance(value, list):
+        return "[" + ",".join(canonicalize(v, _depth + 1) for v in value) + "]"
+
+    if isinstance(value, dict):
+        keys = sorted(k for k in value.keys() if value[k] is not None or True)
+        # Exclude keys whose values are the Python equivalent of JS undefined
+        # In Python, we don't have undefined — None maps to JSON null and is kept.
+        parts = []
+        for k in keys:
+            parts.append(json.dumps(str(k), ensure_ascii=False) + ":" + canonicalize(value[k], _depth + 1))
+        return "{" + ",".join(parts) + "}"
+
+    raise TypeError(f"Unsupported type for canonicalization: {type(value).__name__}")

alx_protocol/lineage.py

@@ -0,0 +1,94 @@
+"""ALX Protocol — Lineage validation."""
+
+from typing import Dict, List, Optional, Set
+
+
+def validate_lineage(
+    block_hash: str,
+    parent_hashes: List[str],
+    known_hashes: Optional[Set[str]] = None,
+) -> dict:
+    h = block_hash.strip().lower()
+    raw = [p.strip().lower() for p in parent_hashes]
+    unique = sorted(set(raw))
+
+    seen = set()
+    duplicates = []
+    for p in raw:
+        if p in seen:
+            duplicates.append(p)
+        seen.add(p)
+
+    self_ref = h in unique
+    known = known_hashes or set()
+    missing = sorted(p for p in unique if known and p not in known)
+
+    return {
+        "ok": not duplicates and not missing and not self_ref,
+        "blockHash": h,
+        "parents": unique,
+        "duplicates": sorted(set(duplicates)),
+        "missing": missing,
+        "selfRef": self_ref,
+        "cycle": self_ref,
+    }
+
+
+def validate_graph(graph: Dict[str, List[str]]) -> dict:
+    all_hashes = set(graph.keys())
+    cycle_nodes = _detect_all_cycles(graph)
+    issues = []
+    edges = 0
+    roots = []
+
+    for h, parents in graph.items():
+        edges += len(parents)
+        if not parents:
+            roots.append(h)
+        result = validate_lineage(h, parents, all_hashes)
+        if h in cycle_nodes:
+            result["cycle"] = True
+            result["ok"] = False
+        if not result["ok"]:
+            issues.append(result)
+
+    return {
+        "ok": len(issues) == 0,
+        "blocks": len(graph),
+        "edges": edges,
+        "roots": sorted(roots),
+        "issues": issues,
+    }
+
+
+def build_graph(blocks: list) -> Dict[str, List[str]]:
+    g = {}
+    for b in blocks:
+        h = b["blockHash"].strip().lower()
+        parents = sorted(p.strip().lower() for p in b.get("parentHashes", []))
+        g[h] = parents
+    return g
+
+
+def _detect_all_cycles(graph: Dict[str, List[str]]) -> Set[str]:
+    visiting = set()
+    visited = set()
+    in_cycle = set()
+
+    def visit(node):
+        if node in visited:
+            return False
+        if node in visiting:
+            in_cycle.add(node)
+            return True
+        visiting.add(node)
+        for parent in graph.get(node, []):
+            if visit(parent):
+                in_cycle.add(node)
+        visiting.discard(node)
+        visited.add(node)
+        return False
+
+    for node in graph:
+        visit(node)
+    return in_cycle

alx_protocol/merkle.py

@@ -0,0 +1,56 @@
+"""ALX Protocol — Sorted-pair Merkle tree for checkpoint proofs."""
+
+from typing import List, Optional, Dict
+from eth_hash.auto import keccak
+
+
+def _hash_pair(a: str, b: str) -> str:
+    a_bytes = bytes.fromhex(a[2:])
+    b_bytes = bytes.fromhex(b[2:])
+    if a.lower() < b.lower():
+        concat = a_bytes + b_bytes
+    else:
+        concat = b_bytes + a_bytes
+    return "0x" + keccak(concat).hex()
+
+
+def build_merkle_tree(leaves: List[str]) -> dict:
+    if not leaves:
+        raise ValueError("leaves must be a non-empty list")
+    layer = sorted(h.lower() for h in leaves)
+    layers = [list(layer)]
+    while len(layer) > 1:
+        next_layer = []
+        for i in range(0, len(layer), 2):
+            if i + 1 < len(layer):
+                next_layer.append(_hash_pair(layer[i], layer[i + 1]))
+            else:
+                next_layer.append(layer[i])
+        layer = next_layer
+        layers.append(list(layer))
+    return {"root": layer[0], "layers": layers}
+
+
+def get_merkle_proof(leaves: List[str], leaf: str) -> Optional[Dict]:
+    tree = build_merkle_tree(leaves)
+    target = leaf.lower()
+    try:
+        index = tree["layers"][0].index(target)
+    except ValueError:
+        return None
+    proof = []
+    idx = index
+    for i in range(len(tree["layers"]) - 1):
+        layer_len = len(tree["layers"][i])
+        sibling = idx + 1 if idx % 2 == 0 else idx - 1
+        if sibling < layer_len:
+            proof.append(tree["layers"][i][sibling])
+        idx //= 2
+    return {"proof": proof, "root": tree["root"], "leaf": target, "index": index}
+
+
+def verify_merkle_proof(root: str, leaf: str, proof: List[str]) -> bool:
+    h = leaf.lower()
+    for sibling in proof:
+        h = _hash_pair(h, sibling)
+    return h == root.lower()

alx_protocol/trace.py

@@ -0,0 +1,97 @@
+"""ALX Protocol — Attribution trace resolution."""
+
+from collections import deque
+from typing import Dict, List
+
+
+def trace_attribution(root_hash: str, graph: Dict[str, List[str]]) -> dict:
+    root = root_hash.strip().lower()
+    if not root:
+        raise ValueError("rootHash is required")
+
+    # Cycle pre-check via DFS
+    cycle_detected = False
+    visiting = set()
+    visited_cycle = set()
+
+    def check_cycle(node):
+        nonlocal cycle_detected
+        if node in visited_cycle:
+            return
+        if node in visiting:
+            cycle_detected = True
+            return
+        visiting.add(node)
+        for p in graph.get(node, []):
+            check_cycle(p.strip().lower())
+        visiting.discard(node)
+        visited_cycle.add(node)
+
+    check_cycle(root)
+
+    # BFS discovery
+    node_data = {}  # hash -> {min_depth, max_depth, parent_count}
+    edge_set = set()
+    edge_list = []
+    child_counts = {}
+    global_max_depth = 0
+
+    queue = deque([(root, 0)])
+    while queue:
+        h, depth = queue.popleft()
+        if h in node_data:
+            node_data[h]["min_depth"] = min(node_data[h]["min_depth"], depth)
+            node_data[h]["max_depth"] = max(node_data[h]["max_depth"], depth)
+            if depth > global_max_depth:
+                global_max_depth = depth
+            continue
+
+        parents = [p.strip().lower() for p in graph.get(h, [])]
+        node_data[h] = {"min_depth": depth, "max_depth": depth, "parent_count": len(parents)}
+        if depth > global_max_depth:
+            global_max_depth = depth
+
+        for p in parents:
+            edge_key = f"{h}\0{p}"
+            if edge_key not in edge_set:
+                edge_set.add(edge_key)
+                edge_list.append({"from": h, "to": p})
+                child_counts[p] = child_counts.get(p, 0) + 1
+            queue.append((p, depth + 1))
+
+    # Topological path count propagation
+    path_counts = {root: 1}
+    sorted_hashes = sorted(node_data.keys(), key=lambda x: (node_data[x]["min_depth"], x))
+    for h in sorted_hashes:
+        my_paths = path_counts.get(h, 0)
+        for p in [x.strip().lower() for x in graph.get(h, [])]:
+            if p in node_data:
+                path_counts[p] = path_counts.get(p, 0) + my_paths
+
+    # Build output
+    nodes = []
+    leaves = []
+    for h, data in node_data.items():
+        nodes.append({
+            "hash": h,
+            "minDepth": data["min_depth"],
+            "maxDepth": data["max_depth"],
+            "pathCount": path_counts.get(h, 0),
+            "parentCount": data["parent_count"],
+            "childCount": child_counts.get(h, 0),
+        })
+        if data["parent_count"] == 0:
+            leaves.append(h)
+
+    nodes.sort(key=lambda n: (n["minDepth"], n["hash"]))
+    edge_list.sort(key=lambda e: (e["from"], e["to"]))
+    leaves.sort()
+
+    return {
+        "root": root,
+        "nodes": nodes,
+        "edges": edge_list,
+        "leaves": leaves,
+        "maxDepth": global_max_depth,
+        "cycle": cycle_detected,
+    }

alx_protocol-1.0.0.dist-info/METADATA

@@ -0,0 +1,50 @@
+Metadata-Version: 2.4
+Name: alx-protocol
+Version: 1.0.0
+Summary: ALX Protocol — Python implementation
+Author: ALX Protocol contributors
+License: MIT
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: eth-hash[pycryptodome]>=0.5.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+
+<p align="center">
+  <img src="../../assets/xandrlabs/xandrlabs_logo3.png" alt="Xandr Labs" width="160"/>
+</p>
+<p align="center"><strong><em>Infrastructure compounds. Block by block.</em></strong></p><p align="center">https://xandrlabs.ai</p>
+
+---
+
+# ALX Protocol - Python Implementation
+
+This implementation tracks parity with the TypeScript SDK in `reference-implementations/typescript`.
+
+## Authority
+
+- Canonical specification: [`protocol/spec.md`](../../protocol/spec.md)
+- JSON Schemas: [`protocol/schemas/`](../../protocol/schemas/)
+- Test vectors: [`protocol/test-vectors/`](../../protocol/test-vectors/)
+- Companion docs: [`docs/`](../../docs/)
+
+## Layout
+
+- `pyproject.toml` - package `alx-protocol`, `src/alx_protocol/`
+- `tests/` - smoke tests (`pytest`)
+
+```bash
+cd reference-implementations/python
+python -m venv .venv
+.venv\Scripts\activate   # Windows
+pip install -e ".[dev]"
+pytest
+# or vector replay only (same entrypoint as CI):
+python verify_vectors.py
+```
+
+Next steps: virtual registry, signing (EIP-712), and broader API parity with the TypeScript reference implementation.
+
+## Reference
+
+Compare behavior with [`reference-implementations/typescript`](../../reference-implementations/typescript/), especially `src/canonicalization.js` and `src/__tests__/conformance-vectors.test.js`.

alx_protocol-1.0.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+alx_protocol/__init__.py,sha256=fOSqi9GRDHsIRGRRfYsPKRJeza-IEI5xKKmASOzR094,1093
+alx_protocol/block.py,sha256=jhOWS2wQELvVTYTJrgjVfOPssXNOp0r0Rf2U2Z3fL78,1901
+alx_protocol/canonical.py,sha256=VPe3xvQ4DtvCBnQUinHg5QlNZt0Zl6b6o6u-KliE7wY,2220
+alx_protocol/lineage.py,sha256=BmgQUR_EdgR4roojnb5CVJ2vOuBhdhCGHwXH63kAVwA,2455
+alx_protocol/merkle.py,sha256=KuAdNdEXi_CSZRqJnIRMrHX1PPxpUiFYPoq62QIFetY,1813
+alx_protocol/trace.py,sha256=C84I5VWnl6Mh-svy4jKfASLCVveNLaxMzOcjdF3VF_c,3122
+alx_protocol-1.0.0.dist-info/METADATA,sha256=Dzq3BKAlxF_UxS2vAHXZE-RXTGwErKa_CzTgaj9XKvs,1680
+alx_protocol-1.0.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+alx_protocol-1.0.0.dist-info/top_level.txt,sha256=8AtWpigdDJn0YputhbBmsCs-quwEO5W7xaTZH3hrc0Y,13
+alx_protocol-1.0.0.dist-info/RECORD,,

alx_protocol-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

alx_protocol-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+alx_protocol