epic: CLI

[zmalatrax]

Create a CLI that allows to run Cairo programs on the Cairo VM in TS.

The goal is to reach parity with available flags in the VMs in prod (Python/Rust, need to list the different features)

As all functionalities are not available in the project yet (e.g. proof mode, cairo PIE), this issue is about listing features and tracking their implementation in other issues.

[zmalatrax]

Flags of the Python VM:

Flag	Description
-h, --help	display help for command
-v, --version	output the version number
--program PROGRAM	path to the program to execute
--steps STEPS	specify the number of steps to execute
--min_steps MIN_STEPS	minimum of steps to be executed
--debug_error	Stops the execution if there is an error but produce the partial outputs (print memory before leaving)
--no_end	No check program successfully ended
--print_memory	Print the memory (Address --> Value)
--relocate_prints	Print relocated memory (a contiguous segment)
--secure_run	Add a few checks at the end of the run (default to true)
-- no_secure_run	Negate secure_run
--print_info	Print info on the execution of the program: number of steps, number of memory cells used, register values after execution (pc, ap, fp)
--print_output	Print the output segment, nothing if empty
--memory_file MEMORY_FILE	Export the relocated memory to specified file (binary little-endian encoded)
--trace_file TRACE_FILE	Export the trace to specified file (binary little-endian encoded)
--run_from_cairo_pie PIE_FILE	Execute a run from the given PIE archive (behaviour to be confirmed)
--cairo_pie_output CAIRO_PIE_OUTPUT	Export to an archive in the PIE format (relocated memory, metadata, version, execution_resources, additional_data)
--debug_info_file DEBIG_INFO_FILE	Dump debug_info to this file (JSON)
--air_public_input	Export the AIR public input to specified file (JSON) (layout, rc_min, rc_max, n_steps, memory_segments, public_memory and dynamic_params)
--air_private_input	Export the AIR private input to specified file (JSON) (path to the trace and relocated memory binary files)
--layout	Layout to use for the run (different params for usage checks of the builtins)
--cairo_layout_params_file CAIRO_LAYOUT_PARAMS_FILE	Read a CairoLayoutParams object at the specified path, only for dynamic layouts
--tracer	launch the tracer (visual tool to follow the execution (code source, memory and the 3 registers)
--profile_output PROFILE_OUTPUT	Dump profiling data to the specified file (expected format: profile.pb.gz) To be opened with tools like pprof
--proof_mode	Run in ProofMode
--show_trace	Print the encountered python errors if any
--flavor {Debug, Release, RelWithDebInfo}	Specifiy the mode to run the program in (mostly optimization flags), to be confirmed
--allow_missing_builtins	Allow missing builtins in the layout compared to the one required by the program
--python_dependencies	Output starkware python modules used in program as CMake file

Flags of the Rust VM

Flag	Description
-h, --help	display help for command
-V, --version	output the version number
--print_output	Print the output segment, nothing if empty
--trace_file TRACE_FILE
--memory_file MEMORY_FILE	Export the relocated memory to specified file (binary little-endian encoded)
--entrypoint ENTRYPOINT	Specify the entrypoint to run the program from (mostly for starknet contracts)
--layout LAYOUT	Layout to use for the run (different params for usage checks of the builtins)
--proof_mode	Run in ProofMode
--secure_run BOOLEAN	Add a few checks at the end of the run (defaults to true)
--air_public_input FILENAME	Export the AIR public input to specified file (JSON)
--air_private_input FILENAME	Export the AIR privateinput to specified file (JSON)
--cairo_pie_output FILENAME	Export to an archive in the PIE format
--allow_missing_builtins BOOLEAN	Allow missing builtins in the layout compared to the one required by the program

[zmalatrax]

Current flags of the Cairo VM Typescript cli (cairo-vm-ts) (done in #85 #84 ):

Flag	Description
-h, --help	display help for command
-V, --version	output the version number

Subcommand run (cairo-vm-ts run <program.json>)

Argument	Description
<program.json>	Path to Cairo compilation artifacts

Flag	Description
--no-relocate	do not relocate memory
--offset	start address of the relocated memory. StarkWare verifier expects offset to be 1 (default: 0)
--export-trace <TRACE_FILENAME>	export the trace, little-endian encoded
--export-memory <MEMORY_FILENAME>	export the relocated memory, little-endian encoded
--print-trace	print the trace
--print-memory	print the non-relocated memory
--print-relocated-memory	print the relocated memory
--print-output	print the output segment
-h, --help	display help for command

Layouts have not been implemented yet.

The flags related to the ProofMode will be implemented in another subcommands, called prove.