Add Debug scripts

CHANGELOG.md

@@ -2,6 +2,8 @@
 
 #### Upcoming Changes
 
+* docs: Add debugging scripts and documentation [#1839](https://github.com/lambdaclass/cairo-vm/pull/1839)
+
 * chore: bump pip `cairo-lang` 0.13.2 [#1827](https://github.com/lambdaclass/cairo-vm/pull/1827)
 
 * chore: bump `cairo-lang-` dependencies to 2.8.0 [#1833](https://github.com/lambdaclass/cairo-vm/pull/1833/files)

docs/README.md

@@ -5,3 +5,4 @@
 * [How to run a cairo program with custom hints](./hint_processor/builtin_hint_processor)
 * [References parsing](./references_parsing/)
 * [Tracer](./tracer/)
+* [Debugging](./debugging.md)

docs/debugging.md

@@ -0,0 +1,31 @@
+# Debugging
+
+## Comparing with Cairo-Lang
+
+If you executed a Cairo0 proof program with both Rust and Python VM, you can use the following scripts to compare their output. They all require `delta` (modern diff) to be installed. If you don't have you can locally change it.
+
+No output when running a differ script implies that there are no differences.
+
+To compare the public inputs, run:
+```bash
+scripts/air_public_inputs_differ.bash file1 file2
+```
+
+To compare the private inputs, run:
+```bash
+scripts/air_private_inputs_differ.bash file1 file2
+```
+
+If you just want to visualize the memory, run:
+```bash
+scripts/memory_viewer.bash file
+```
+It will output the memory in two columns: address and value
+
+
+To compare the memory, run:
+```bash
+scripts/memory_differ.bash file1 file2
+```
+
+

scripts/air_private_inputs_differ.bash

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+
+delta \
+    <(jq -S 'del(.memory_path,.trace_path)' "$1") \
+    <(jq -S 'del(.memory_path,.trace_path)' "$2") \
+    -s

scripts/air_public_inputs_differ.bash

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+
+delta \
+    <(jq -S . "$1") \
+    <(jq -S . "$2") \
+    -s

scripts/memory_differ.bash

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+
+delta \
+    <(hexdump -e '1/8 "%u " 4/8 "%x " "\n"' "$1" | sort -n) \
+    <(hexdump -e '1/8 "%u " 4/8 "%x " "\n"' "$2" | sort -n) \
+    -s

scripts/memory_viewer.bash

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+#
+# outputs memory file in "ADDR VALUE" format, on cell per line
+
+hexdump -e '1/8 "%10u " 4/8 "%x " "\n"' "$1" | sort -n