Update readme

README.md

@@ -25,28 +25,60 @@
 - [Possible changes for the future](#possible-changes-for-the-future)
 - [Changelog](#changelog)
 - [License](#license)
-
+
+## Disclaimer
+
+ 🚧 `cairo-rs` is still being built therefore breaking changes might happen often so use it at your own risks.🚧 
 
 ## About
 
-cairo-rs is a Rust implementation of the Cairo VM.
+### This repository
+Cairo VM is the virtual machine for the [Cairo language](www.cairo-lang.org/).
+
+There's an older version of [Cairo VM](https://github.com/starkware-libs/cairo-lang) written in Python, which is **currently in production**.
+
+This repository contains the newer version, written in Rust. It's faster and has safer and more expressive typing. Once completed, it will replace the older one as the sole Cairo VM.
+
+### The Cairo language
+Cairo is the first production-grade platform for generating [STARK](https://vitalik.ca/general/2017/11/09/starks_part_1.html) proofs for general computation.
 
-The code of the original Cairo VM can be found [here](https://github.com/starkware-libs/cairo-lang).
+It's Turing-complete and it was created by [Starkware](https://starkware.co/) as part of the [Starknet](https://starkware.co/starknet/) ecosystem.
 
 ## Getting Started
 
 ### Dependencies
-- [Rust](https://www.rust-lang.org/tools/install)
+**Required**
+- [Rust 1.66.1](https://www.rust-lang.org/tools/install)
 - Cargo
-- PyEnv for running the original VM and compiling cairo programs
+
+**Optional**
+These dependencies are only necessary in order to run the original VM and compile Cairo programs.
+- PyEnv with Python 3.9 
 - cairo-lang (optional)
 
 ## Usage
 ### Running cairo-rs
-Compile with `cargo build --release`, once the binary is built, it can be found in `target/release/` under the name `cairo-rs-run`.
-To run a compiled json program through the VM, call the executable giving it the path and name of the file to be executed.
+To compile the repository, run:
+```bash
+cargo build --release
+```
+
+Once the binary is built, it can be found in `target/release/` under the name `cairo-rs-run`.
+
+To compile a program, use `cairo-compile [path_to_the_.cairo_file] --output [desired_path_of_the_compiled_.json_file]`. For example:
+
+```bash 
+cairo-compile cairo_programs/abs_value_array.cairo --output cairo_programs/abs_value_array_compiled.json
+```
+
+To run a compiled .json program through the VM, call the executable giving it the path and name of the file to be executed. For example: 
+
+```bash 
+target/release/cairo-rs-run cairo_programs/abs_value_array_compiled.json --layout all
+```
+
+To sum up, the following code will get you from zero to running a Cairo program:
 
-Full compilation and execution example:
 ```bash
 git clone https://github.com/lambdaclass/cairo-rs.git
 
@@ -58,6 +90,14 @@ cairo-compile cairo_programs/abs_value_array.cairo --output cairo_programs/abs_v
 
 target/release/cairo-rs-run cairo_programs/abs_value_array_compiled.json --layout all
 ```
+### Using hints
+
+Currently, as this VM is under construction, it's missing some of the features of the original VM. Notably, this VM only implements a limited number of hints at the moment, while the [Python Cairo VM](https://github.com/starkware-libs/cairo-lang) allows for the implementation of user-defined hints.
+
+There are two ways to use non-standard hints in this VM:
+
+- Extend the cairo-rs code and build your own binary using the interface hint processor
+- Use [cairo-rs-py](https://github.com/lambdaclass/cairo-rs-py) which supports running any arbitrary hint in a Python interpreter.
 
 ### Running a function in a Cairo program with arguments
 When running a Cairo program directly using the Cairo-rs repository you would first need to prepare a couple of things. 
@@ -139,7 +179,7 @@ cargo bench
 - [starknet_in_rust](https://github.com/lambdaclass/starknet_in_rust): implementation of Starknet in Rust, powered by the cairo-rs VM.
 - [cairo-rs-py](https://github.com/lambdaclass/cairo-rs-py): Bindings for using cairo-rs from Python code.
 
-## Documentation
+## Documentation and further reading
 
 ### Cairo
 * From Cairo Documentation: [How Cairo Works](https://www.cairo-lang.org/docs/how_cairo_works/index.html#how-cairo-works)
@@ -208,7 +248,7 @@ StarkWare's STARK Math blog series:
 
 ## Changelog
 
-Keep track of the latest changes [here](CHANGELOG.md).
+Keeps track of the latest changes [here](CHANGELOG.md).
 
 ## License