From e34aec975bf9a8f1fa304f758aa9d0ebd7147768 Mon Sep 17 00:00:00 2001 From: Rodrigo Date: Tue, 22 Aug 2023 09:54:41 -0400 Subject: [PATCH 1/5] Initial draft --- README.md | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/README.md b/README.md index 0ce1fa875..29b0c0e99 100644 --- a/README.md +++ b/README.md @@ -1 +1,28 @@ # Cairo VM in Go + +> :warning: This project is still in it's infancy. Contributions are welcomed! + +This projects aims to implement the Cairo Virtual Machine in Go. This kind of tool is the one that Starknet nodes use to execute and prove transactions. Up to this point there have been several implementations of the vm: + +* cairo-lang on python by Starkware +* three implementations of the VM in rust, go and c by LambdaClass + +Having several implementations helps the ecosystem by making the net bug resistant (what is the chance that a same vm bug happens accross several vms) and offering choice to users. + +## Install + +The project requires Go -> link to where to install go + +### Interact with the Project + +Some stuff explaining the makefile + +## Documentation + +## Related Projects + +Have a list of similar projects + +## Contributing + +link to contributing file From 0fc7a87386064bee8cc6f87ffd872dc5b04848ab Mon Sep 17 00:00:00 2001 From: Rodrigo Date: Tue, 22 Aug 2023 18:45:07 -0400 Subject: [PATCH 2/5] Add empty contributing file --- CONTRIBUTING.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..e69de29bb From 061429e74dc34a89ad62243c3b6b51a0ee5eaa9b Mon Sep 17 00:00:00 2001 From: Rodrigo Date: Tue, 22 Aug 2023 18:47:12 -0400 Subject: [PATCH 3/5] Add intro, install, docs and related projects --- README.md | 48 ++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 38 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 29b0c0e99..aca781e2f 100644 --- a/README.md +++ b/README.md @@ -1,28 +1,56 @@ # Cairo VM in Go -> :warning: This project is still in it's infancy. Contributions are welcomed! +> ⚠️ This project is undergoing heavy development and is still on its early stages. There is a risk of abundant breaking changes. -This projects aims to implement the Cairo Virtual Machine in Go. This kind of tool is the one that Starknet nodes use to execute and prove transactions. Up to this point there have been several implementations of the vm: +This project aims to implement a Cairo Virtual Machine using Go. This is one of [many other](#related-projects) implementations that are being developed and its main goals are: -* cairo-lang on python by Starkware -* three implementations of the VM in rust, go and c by LambdaClass +* making the Starknet ecosystem secure by reducing the risk of a single critical vulnerability, +* decentralizing development and maintenance of the different VMs, +* cross-checking and validation with other implementations and +* to foster innovation through competition. -Having several implementations helps the ecosystem by making the net bug resistant (what is the chance that a same vm bug happens accross several vms) and offering choice to users. +## Intro + +The Cairo Virtual Machine (CVM) is a crucial component of the Starknet ecosystem. It serves as the runtime environment for all smart contracts on the platform. +When users write contracts in high-level Cairo, it gets compiled to Sierra, and then to CASM bytecode. The VM receives this bytecode, executes it and generates a proof of execution. This proof is then sent from a sequencer to the verifier to include the transaction in a new block. ## Install -The project requires Go -> link to where to install go +This Virtual Machine is still in development and there is no public release available yet. +Currently, it is only possible to use it by building it from source by following these instructions: + +1. Clone the repo to your machine: `git clone https://github.com/NethermindEth/cairo-vm-go`. +2. Install golang on your PC, instructions [here](https://go.dev/.doc/install). +3. Execute on the root folder of the repo: `make build`. +4. Make sure everything is running smoothly by executing: `make test`. -### Interact with the Project +After completing these steps, the compiled VM would be in `bin/cairo-vm`. It is worth noting that this binary, in the current state of the project, is still non-functional. -Some stuff explaining the makefile +### Useful Commands + +For convenience, we have created a `makefile` that includes the most used commands such as `make build`. To see all of them please run: +```bash +make help +``` ## Documentation +### Cairo + +* Cairo Zero Docs: [How Cairo Works](https://docs.cairo-lang.org/0.12.0/how_cairo_works/index.html) +* Whitepaper: [Cairo a Turing-complete STARK-friendly CPU architecture](https://eprint.iacr.org/2021/1063.pdf) +* A formalization of the whitepaper: [A Verified Algebraic Representation of Cairo Program Execution](https://arxiv.org/pdf/2109.14534.pdf) + +### Other + +The previous list includes the most helpful documentation for the current state of the project but it does not represent all available documentation. If you are interested to go beyond, there is this [list](https://github.com/lambdaclass/cairo-vm#-documentation) made by [LambdaClass](https://github.com/lambdaclass) which has a much broader scope. + ## Related Projects -Have a list of similar projects +* [Cairo Zero VM](https://github.com/starkware-libs/cairo-lang) by [Starkware](https://github.com/starkware-libs), not being developed anymore. +* [VM in Rust](https://github.com/lambdaclass/cairo-vm), [Go](https://github.com/lambdaclass/cairo-vm.go) and [C](https://github.com/lambdaclass/cairo-vm.c) by [LambdaClass](https://github.com/lambdaclass). +* [oriac](https://github.com/xJonathanLEI/oriac/) a toy VM by [xJonathanLEI](https://github.com/xJonathanLEI) ## Contributing -link to contributing file +If you wish to contribute or learn a little bit more about how our VM works, please visit our [CONTRIBUTING.md](./CONTRIBUTING.md) From 50ea3ba02331ad1dc6a263b5178c29451a571762 Mon Sep 17 00:00:00 2001 From: Rodrigo Date: Tue, 22 Aug 2023 18:50:42 -0400 Subject: [PATCH 4/5] Minor word change --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index aca781e2f..587aa624e 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Cairo VM in Go -> ⚠️ This project is undergoing heavy development and is still on its early stages. There is a risk of abundant breaking changes. +> ⚠️ This project is undergoing heavy development and is still on its early stages. There will be constant breaking changes. This project aims to implement a Cairo Virtual Machine using Go. This is one of [many other](#related-projects) implementations that are being developed and its main goals are: @@ -20,7 +20,7 @@ This Virtual Machine is still in development and there is no public release avai Currently, it is only possible to use it by building it from source by following these instructions: 1. Clone the repo to your machine: `git clone https://github.com/NethermindEth/cairo-vm-go`. -2. Install golang on your PC, instructions [here](https://go.dev/.doc/install). +2. Install `golang` on your PC, instructions [here](https://go.dev/.doc/install). 3. Execute on the root folder of the repo: `make build`. 4. Make sure everything is running smoothly by executing: `make test`. From e49b5732f3570d2a91ea0a43ef694a3b0484990e Mon Sep 17 00:00:00 2001 From: Rodrigo Date: Tue, 22 Aug 2023 18:52:30 -0400 Subject: [PATCH 5/5] Improve wording --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 587aa624e..284efa5ca 100644 --- a/README.md +++ b/README.md @@ -11,7 +11,7 @@ This project aims to implement a Cairo Virtual Machine using Go. This is one of ## Intro -The Cairo Virtual Machine (CVM) is a crucial component of the Starknet ecosystem. It serves as the runtime environment for all smart contracts on the platform. +The Cairo Virtual Machine is a crucial component of the Starknet ecosystem. It serves as the runtime environment for all smart contracts on the platform. When users write contracts in high-level Cairo, it gets compiled to Sierra, and then to CASM bytecode. The VM receives this bytecode, executes it and generates a proof of execution. This proof is then sent from a sequencer to the verifier to include the transaction in a new block. ## Install @@ -24,7 +24,7 @@ Currently, it is only possible to use it by building it from source by following 3. Execute on the root folder of the repo: `make build`. 4. Make sure everything is running smoothly by executing: `make test`. -After completing these steps, the compiled VM would be in `bin/cairo-vm`. It is worth noting that this binary, in the current state of the project, is still non-functional. +After completing these steps, you can find the compiled VM in `bin/cairo-vm`. It is worth noting that this binary, in the current state of the project, is still non-functional. ### Useful Commands