Add README.md

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`.