diff --git a/README.md b/README.md index 67dda87b..bab2fb08 100644 --- a/README.md +++ b/README.md @@ -66,6 +66,20 @@ To run the factorial demo: make demo_factorial ``` +These demos compare the trace and memory files generated by the `Go` and `Rust` VM implementations to make sure they coincide. We have more general Makefile targets that do this comparison for every program we use for testing. You can check out a list of all these programs under the `cairo_programs` directory. The targets to run these comparisons are + +``` +make compare_trace_memory +``` + +and + +``` +make compare_proof_trace_memory +``` + +The first one does the comparison for normal executions, while the second one does it with *proof mode* enabled. + ## Project Guidelines - PRs addressing performance are forbidden. We are currently concerned with making it work without bugs and nothing more. @@ -90,53 +104,47 @@ The milestone includes: - Writing of the memory into files with the correct format. - Make the fibonacci and factorial tests pass, comparing our own memory with the Rust VM one, making sure they match. -## Roadmap - -### Cairo 0/Cairo 1 - -The above will work for Cairo 0 programs. Cairo 1 has the following extra issues to address: - -- There is no `Json` representation of a Cairo 1 Program, so we can only run contracts. This means we will have to add functions to run cairo contracts (aka implement run_from_entrypoint). -- Cairo 1 contracts use the `range_check` builtin by default, so we need to implement it. - -### Full VM implementation - -To have a full implementation, we will need the following: - -- Builtins. Add the `BuiltinRunner` logic, then implement each builtin: - - `Range check (RC)` - - `Output` - - `Bitwise` - - `Ec_op` - - `Pedersen` - - `Keccak` - - `Poseidon` - - `Signature` - - `Segment Arena` -- Memory layouts. This is related to builtins but we will do it after implementing them. -- Hints. Add the `HintProcessor` logic, then implement each hint. Hints need to be documented extensively, implementing them is super easy since it's just porting code; what's not so clear is what they are used for. Having explanations and examples for each is important. List of hints below: - - [Parsing of references](https://github.com/lambdaclass/cairo-vm/tree/main/docs/references_parsing) - - [`CommonLib`](https://github.com/starkware-libs/cairo-lang/tree/master/src/starkware/cairo/common) - - `Secp` - - `Vrf` - - `BigInt` - - `Blake2` - - `DictManager` - - `EcRecover` - - `Field Arithmetic` - - `Garaga` - - `set_add` - - `sha256 utils` - - `ECDSA verification` - - `uint384` and `uint384 extension` - - `uint512 utils` - - `Cairo 1` hints. -- Proof mode. It's important to explain in detail what this is when we do it. It's one of the most obscure parts of the VM in my experience. -- Air Public inputs. (Tied to Proof-mode) -- Temporary segments. -- Program tests from Cairo VM in Rust. -- Fuzzing/Differential fuzzing. - +### Second Milestone: Full VM implementation + +Below is a list of requirements to have a full implementation along with their progress: + +- ✅ Builtins. Add the `BuiltinRunner` logic, then implement each builtin: + - ✅ `Range check (RC)` + - ✅ `Output` + - ✅ `Bitwise` + - ✅ `Ec_op` + - ✅ `Pedersen` + - ✅ `Keccak` + - ✅ `Poseidon` + - ✅ `Signature` +- ✅ Memory layouts. (plain, small, all_cairo) +- Hints. + - ✅ Add the `HintProcessor` logic + - ✅ [Parsing of references](https://github.com/lambdaclass/cairo-vm/tree/main/docs/references_parsing) + - Implement each hint. This is a long task which we divided into milestones. You can check out their progress [here](https://github.com/lambdaclass/cairo-vm_in_go/milestones). +- ✅ Proof mode. It's important to explain in detail what this is when we do it. It's one of the most obscure parts of the VM in my experience. +- ✅ Program tests from Cairo VM in Rust. +- Support for Temporary Memory + - Handle temporary addresses in memory-related code + - Implement relocation process for temporary memory +- Print debug information on failure (i.e. introduce the concept of a `VmException`) +- Air Public inputs. (Tied to Proof mode) +- Starknet integration: + - Running cairo contracts (i.e. implement `RunFromEntrypoint`) + - Tracking `ExecutionResources` and `RunResources`. +- Cairo 1 support. This requires: + - Parsing Cairo 1 contracts. There is no `Json` representation of a Cairo 1 Program, so we can only run contracts. This means this depends on the `RunFromEntrypoint` feature above. + - Implementing Cairo 1 builtin (`Segment Arena`) + - Implementing Cairo 1 Hints +- Support for `CairoPie` (Cairo Position Independent Code). + + +### Other Stuff: Performance and Fuzzing + +Things that are out of the second milestone but we want to have: + +- Add benchmarks to track performance and compare against the Rust implementation. +- Add Fuzzing and Differential fuzzing to catch errors that our regular tests don't and compare ourselves against the Rust VM. ## Documentation ### High Level Overview