Merge pull request #602 from input-output-hk/javierdiaz/trace-translator

Translate traces between Cardano Tracer and Leios trace verifier

Author: javierdiaz72

scripts/trace-translator/README.md

@@ -0,0 +1,41 @@
+# Trace translator
+
+The trace translator translates traces generated by the Praos node into traces in the format expected by the Leios trace verifier.
+
+## Example usage
+
+The trace translator uses the standard input and the standard output to perform translations:
+
+```bash
+trace-translator.py < praos-node.json > leios-node.json
+```
+
+Assuming that the input file `praos-node.json` contains the following traces:
+
+```json
+{"at":"2025-10-27T16:24:31.972897Z","ns":"Forge.Loop.StartLeadershipCheck","data":{"kind":"TraceStartLeadershipCheck","slot":0},"sev":"Info","thread":"45","host":"node-0"}
+{"at":"2025-10-27T16:24:31.972919Z","ns":"Forge.Loop.ForgedBlock","data":{"block":"e2a10cab9cda1227ae6d78811c730c88c66047927cba9a4a6bf41559efc38d67","blockNo":4,"blockPrev":"9bea965ee016f724368911fa77abfb95ee0145a27ed6dbc096695dbd19311ab7","kind":"TraceForgedBlock","slot":92},"sev":"Info","thread":"45","host":"node-0"}
+{"at":"2025-10-27T16:24:32.061155Z","ns":"BlockFetch.Client.CompletedBlockFetch","data":{"block":"e996590b50ee39d640975de80b1c4ebfaa923866437d36b2d2ab08dacda2a09d","delay":8.924e-3,"kind":"CompletedBlockFetch","peer":{"connectionId":"127.0.0.1:30001 127.0.0.1:30000"},"size":2472},"sev":"Info","thread":"74","host":"node-0"}
+{"at":"2025-10-27T16:24:33.061305Z","ns":"Forge.Loop.AdoptedBlock","data":{"blockHash":"26ab7db1ca55e69885665f625262118ef7db99172be6d3591ad2a8e9bfeabffa","blockSize":864,"kind":"TraceAdoptedBlock","slot":0},"sev":"Info","thread":"34","host":"node-0"}
+{"at":"2025-10-27T16:24:33.063728Z","ns":"Forge.Loop.StartLeadershipCheck","data":{"kind":"TraceStartLeadershipCheck","slot":1},"sev":"Info","thread":"45","host":"node-0"}
+{"at":"2025-10-27T16:24:33.066668Z","ns":"BlockFetch.Client.CompletedBlockFetch","data":{"block":"ffff590b50ee39d640975de80b1c4ebfaa923866437d36b2d2ab08dacda2a09d","delay":123,"kind":"CompletedBlockFetch","peer":{"connectionId":"127.0.0.1:30001 127.0.0.1:30000"},"size":2472},"sev":"Info","thread":"74","host":"node-0"}
+{"at":"2025-10-27T16:24:33.074447Z","ns":"Forge.Loop.StartLeadershipCheck","data":{"kind":"TraceStartLeadershipCheck","slot":2},"sev":"Info","thread":"45","host":"node-0"}
+{"at":"2025-10-27T16:24:33.080000Z","ns":"BlockFetch.Client.CompletedBlockFetch","data":{"block":"eeee590b50ee39d640975de80b1c4ebfaa923866437d36b2d2ab08dacda2a09d","delay":123,"kind":"CompletedBlockFetch","peer":{"connectionId":"127.0.0.1:30001 127.0.0.1:30000"},"size":2472},"sev":"Info","thread":"74","host":"node-0"}
+{"at":"2025-10-27T16:24:33.080001Z","ns":"Forge.Loop.StartLeadershipCheck","data":{"kind":"TraceStartLeadershipCheck","slot":3},"sev":"Info","thread":"45","host":"node-0"}
+```
+
+Then the output file `leios-node.json` will contain the following resulting traces:
+
+```json
+{"message": {"type": "RBReceived", "recipient": "node-0", "id": "e996590b50ee39d640975de80b1c4ebfaa923866437d36b2d2ab08dacda2a09d"}, "time_s": 0.088236}
+{"message": {"type": "RBGenerated", "producer": "node-0", "slot": 0, "id": "26ab7db1ca55e69885665f625262118ef7db99172be6d3591ad2a8e9bfeabffa", "endorsement": null, "parent": null, "size": 864, "tx_payload_bytes": null}, "time_s": 1.00015}
+{"message": {"type": "Slot", "node": "node-0", "slot": 0}, "time_s": 0.002423}
+{"message": {"type": "RBReceived", "recipient": "node-0", "id": "ffff590b50ee39d640975de80b1c4ebfaa923866437d36b2d2ab08dacda2a09d"}, "time_s": 0.00294}
+{"message": {"type": "Slot", "node": "node-0", "slot": 1}, "time_s": 0.007779}
+{"message": {"type": "RBReceived", "recipient": "node-0", "id": "eeee590b50ee39d640975de80b1c4ebfaa923866437d36b2d2ab08dacda2a09d"}, "time_s": 0.005553}
+{"message": {"type": "Slot", "node": "node-0", "slot": 2}, "time_s": 1e-06}
+```
+
+## Limitations
+
+Currently, the `parent` and `tx_payload_bytes` fields in the output traces of type `RBGenerated` are not available since these are not present in the input traces of type `Forge.Loop.AdoptedBlock`. A possible solution to the absense of the `parent` field may imply the use of the corresponding input trace of type `Forge.Loop.ForgedBlock`.

scripts/trace-translator/trace-translator.py

@@ -0,0 +1,65 @@
+#!/usr/bin/env python3
+
+"""
+Translate trace log files generated by the Praos node into log files
+in the format expected by the Leios trace verifier.
+"""
+
+import json, sys
+from datetime import datetime, timezone
+
+def log_message(message, time):
+    print(json.dumps({"message": message, "time_s": time.total_seconds()}))
+
+fmt = "%Y-%m-%dT%H:%M:%S.%fZ"
+last_at = None
+last_SLC_slot = None
+
+for line in sys.stdin:
+    try:
+        obj = json.loads(line)
+    except json.JSONDecodeError as e:
+        print(f"Error decoding JSON: {e}")
+        exit(127)
+
+    if last_at is None:
+        last_at = obj['at']
+
+    curr_at = obj['at']
+    time = datetime.strptime(curr_at, fmt).replace(tzinfo=timezone.utc) \
+           -                                                            \
+           datetime.strptime(last_at, fmt).replace(tzinfo=timezone.utc)
+    last_at = curr_at
+
+    if obj['ns'] == "Forge.Loop.AdoptedBlock":
+        message = {
+            "type":             "RBGenerated",
+            "producer":         obj['host'],
+            "slot":             last_SLC_slot,
+            "id":               obj['data']['blockHash'],
+            "endorsement":      None,
+            "parent":           None, # FIXME: This is not available
+            "size":             obj['data']['blockSize'],
+            "tx_payload_bytes": None, # FIXME: This is not available
+            }
+    elif obj['ns'] == "BlockFetch.Client.CompletedBlockFetch":
+        message = {
+            "type":      "RBReceived",
+            "recipient": obj['host'],
+            "id":        obj['data']['block']
+            }
+    else:
+        if obj['ns'] == "Forge.Loop.StartLeadershipCheck":
+            if last_SLC_slot is None:
+                last_SLC_slot = obj['data']['slot']
+            else:
+                message = {
+                    "type": "Slot",
+                    "node": obj['host'],
+                    "slot": last_SLC_slot
+                    }
+                log_message(message, time)
+                last_SLC_slot = obj['data']['slot']
+        continue
+
+    log_message(message, time)