From 448f7451bab990e45e14ace9b067ff9b0f093895 Mon Sep 17 00:00:00 2001 From: malatrax Date: Thu, 2 May 2024 12:43:03 +0200 Subject: [PATCH 01/10] doc: fill What, Why sections of the README --- README.md | 105 +++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 85 insertions(+), 20 deletions(-) diff --git a/README.md b/README.md index ac1d8be5..cb188b77 100644 --- a/README.md +++ b/README.md @@ -1,36 +1,101 @@ -# Cairo VM in Typescript +# TypeScript Cairo VM + +
+

TypeScript Cairo VM

+ +An implementation of the Cairo VM in TypeScript, focusing on +education + +[Github](https://github.com/kkrt-labs/cairo-vm-ts) + +Built with 🥕 by KKRT Labs + +
+ +> ⚠️ This project is in its genesis, undergoing fast-paced development. It is +> not suitable for production yet. Expect frequent breaking changes. ## What is Cairo - +Cairo stands for CPU AIR "o" (like insp"o", conv"o", 🤔). -Cairo stands for CPU AIR "o" (like insp"o", conv"o", 🤔). See -[Cairo whitepaper](https://eprint.iacr.org/2021/1063) for more information. +It is a framework (a machine, an assembly and a language) which allows writing provable programs without having to understand the underneath ZK-technology. + +A program written in Cairo (or Cairo Zero) is compiled and then executed on a Cairo VM which produces traces to be used for the STARK proof generation. + +See [resources](#resources) for more information. ## Why this -There are currently three Cairo VM implementations: +### Client Diversity + +There are currently five other Cairo VM implementations: + + + +- Reference (original) [implementation in Python](https://github.com/starkware-libs/cairo-lang) by Starkware (prod) +- New [implementation in Rust](https://github.com/lambdaclass/cairo-vm) by Lambda Class (prod) +- A [Go implementation](https://github.com/lambdaclass/cairo-vm_in_go), by Lambda Class (dev) +- Another [Go implementation](https://github.com/NethermindEth/cairo-vm-go) by Nethermind (dev) +- A [Zig implementation](https://github.com/keep-starknet-strange/ziggy-starkdust), by Community (dev) +- A [C++ implementation](https://github.com/lambdaclass/cairo-vm.c) by Lambda Class (dev) -- the original - [python implementation](https://github.com/starkware-libs/cairo-lang) by - Starkware (prod) -- the new [rust implementation](https://github.com/lambdaclass/cairo-vm) by - Lambda Class (prod) -- a new [go implementation](https://github.com/lambdaclass/cairo-vm_in_go) by - Lambda Class (dev) +The Lambda Class alt-implementations comes with a +detailed guide ([Go](https://github.com/lambdaclass/cairo-vm_in_go/blob/main/README.md#documentation), [C++](https://github.com/lambdaclass/cairo-vm.c?tab=readme-ov-file#documentation)) on how they built their Cairo VM. +It gives insights into the overall Cairo VM but is incomplete and rather specific to language details. - +Why would you have different implementations of the same program in multiple languages? +For **client diversity**. As more clients provide more: -The Go implementation comes with an -[impressive documentation](https://github.com/lambdaclass/cairo-vm_in_go/blob/main/README.md#documentation) -regarding the how-to for a Cairo VM. This repo is coded with the flow while -reading it. +- **Resilience**. It helps in finding bugs in the existing +  implementations. +- **Documentation**. The documentation over the Cairo VM is +  still scarce, and the latest version in prod (Rust) is not easy to read for +  the average dev. +- **Architecture diversity**. Different architectures can +  implemented to achieve the same goal (e.g. memory model). However, most of the current implementation essentially is a rewrite of the Rust implementation, which is an (enhanced) rewrite of the Python implementation itself. +- **Usage diversity**. The primary goals of each client can differ. For example, the primary goals of production clients are performance and safety (Rust). -Read so far up to -[#Run Context](https://github.com/lambdaclass/cairo-vm_in_go/blob/main/README.md#runcontext) +The primary goal of our TypeScript client is **education** through **readability** and **expressiveness**. +### Demistifying the Cairo VM -## Requirements +The Cairo VM is still obscure to most of us, from a lack of documentation and hard-to-read languages obfuscating the inner workings of the VM. Nobody wants to struggle to reconstruct the missing pieces to understand how something works. + +We are implementing a Cairo VM in TypeScript to provide a well +documented and easy-to-comprehend Cairo VM + +- TypeScript is easily readable and known by most devs if not all +- Deliberate design choices to further improve readability and simplicity +- Extensive documentation: JSDoc, diagrams, explainers, etc. + +## State of the VM + +| Goals | Done? | +| ---------------------------- | ----- | +| Run basic Cairo Zero program | 🗹 | +| Run basic Cairo program | ☐ | +| Run any Cairo Zero program | ☐ | +| Run any Cairo program | ☐ | +| Run any StarkNet contract | ☐ | +| Benchmark against other VMs | ☐ | + + + + + +## Resources + +- [Cairo whitepaper](https://eprint.iacr.org/2021/1063) +- [Cairo Book](https://book.cairo-lang.org/) +- [Cairo website](https://www.cairo-lang.org/) +- + +## Local Development + +### Requirements - Install [bun](https://bun.sh/) - Run `bun install` to install all dependencies - Run `bun test` to run all tests + + From bd0aa9db34d2cbdc5088f593f242c29c5edced5e Mon Sep 17 00:00:00 2001 From: Malatrax <71888134+zmalatrax@users.noreply.github.com> Date: Thu, 2 May 2024 16:43:06 +0200 Subject: [PATCH 02/10] chore: fix typo Co-authored-by: Thomas Coratger <60488569+tcoratger@users.noreply.github.com> --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index cb188b77..fc3c0d1a 100644 --- a/README.md +++ b/README.md @@ -52,8 +52,8 @@ For **client diversity**. As more clients provide more: - **Documentation**. The documentation over the Cairo VM is   still scarce, and the latest version in prod (Rust) is not easy to read for   the average dev. -- **Architecture diversity**. Different architectures can -  implemented to achieve the same goal (e.g. memory model). However, most of the current implementation essentially is a rewrite of the Rust implementation, which is an (enhanced) rewrite of the Python implementation itself. +- **Architecture diversity**. Different architectures can be +  implemented to achieve the same goal (e.g. memory model). However, most of the current implementations essentially are a rewrite of the Rust implementation, which is an (enhanced) rewrite of the Python implementation itself. - **Usage diversity**. The primary goals of each client can differ. For example, the primary goals of production clients are performance and safety (Rust). The primary goal of our TypeScript client is **education** through **readability** and **expressiveness**. From 2f209d576437113fae80032571ff7c9c7db42b81 Mon Sep 17 00:00:00 2001 From: malatrax Date: Thu, 2 May 2024 16:43:58 +0200 Subject: [PATCH 03/10] chore: fmt --- README.md | 78 ++++++++++++++++++++++++++++++++++--------------------- 1 file changed, 48 insertions(+), 30 deletions(-) diff --git a/README.md b/README.md index fc3c0d1a..12f4444f 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,8 @@ education [Github](https://github.com/kkrt-labs/cairo-vm-ts) -Built with 🥕 by KKRT Labs +Built with 🥕 by KKRT +Labs @@ -19,9 +20,11 @@ education Cairo stands for CPU AIR "o" (like insp"o", conv"o", 🤔). -It is a framework (a machine, an assembly and a language) which allows writing provable programs without having to understand the underneath ZK-technology. +It is a framework (a machine, an assembly and a language) which allows writing +provable programs without having to understand the underneath ZK-technology. -A program written in Cairo (or Cairo Zero) is compiled and then executed on a Cairo VM which produces traces to be used for the STARK proof generation. +A program written in Cairo (or Cairo Zero) is compiled and then executed on a +Cairo VM which produces traces to be used for the STARK proof generation. See [resources](#resources) for more information. @@ -33,36 +36,51 @@ There are currently five other Cairo VM implementations: -- Reference (original) [implementation in Python](https://github.com/starkware-libs/cairo-lang) by Starkware (prod) -- New [implementation in Rust](https://github.com/lambdaclass/cairo-vm) by Lambda Class (prod) -- A [Go implementation](https://github.com/lambdaclass/cairo-vm_in_go), by Lambda Class (dev) -- Another [Go implementation](https://github.com/NethermindEth/cairo-vm-go) by Nethermind (dev) -- A [Zig implementation](https://github.com/keep-starknet-strange/ziggy-starkdust), by Community (dev) -- A [C++ implementation](https://github.com/lambdaclass/cairo-vm.c) by Lambda Class (dev) - -The Lambda Class alt-implementations comes with a -detailed guide ([Go](https://github.com/lambdaclass/cairo-vm_in_go/blob/main/README.md#documentation), [C++](https://github.com/lambdaclass/cairo-vm.c?tab=readme-ov-file#documentation)) on how they built their Cairo VM. -It gives insights into the overall Cairo VM but is incomplete and rather specific to language details. - -Why would you have different implementations of the same program in multiple languages? -For **client diversity**. As more clients provide more: - -- **Resilience**. It helps in finding bugs in the existing -  implementations. -- **Documentation**. The documentation over the Cairo VM is -  still scarce, and the latest version in prod (Rust) is not easy to read for -  the average dev. -- **Architecture diversity**. Different architectures can be -  implemented to achieve the same goal (e.g. memory model). However, most of the current implementations essentially are a rewrite of the Rust implementation, which is an (enhanced) rewrite of the Python implementation itself. -- **Usage diversity**. The primary goals of each client can differ. For example, the primary goals of production clients are performance and safety (Rust). - -The primary goal of our TypeScript client is **education** through **readability** and **expressiveness**. +- Reference (original) + [implementation in Python](https://github.com/starkware-libs/cairo-lang) by + Starkware (prod) +- New [implementation in Rust](https://github.com/lambdaclass/cairo-vm) by + Lambda Class (prod) +- A [Go implementation](https://github.com/lambdaclass/cairo-vm_in_go), by + Lambda Class (dev) +- Another [Go implementation](https://github.com/NethermindEth/cairo-vm-go) by + Nethermind (dev) +- A + [Zig implementation](https://github.com/keep-starknet-strange/ziggy-starkdust), + by Community (dev) +- A [C++ implementation](https://github.com/lambdaclass/cairo-vm.c) by Lambda + Class (dev) + +The Lambda Class alt-implementations comes with a detailed guide +([Go](https://github.com/lambdaclass/cairo-vm_in_go/blob/main/README.md#documentation), +[C++](https://github.com/lambdaclass/cairo-vm.c?tab=readme-ov-file#documentation)) +on how they built their Cairo VM. It gives insights into the overall Cairo VM +but is incomplete and rather specific to language details. + +Why would you have different implementations of the same program in multiple +languages? For **client diversity**. As more clients provide more: + +- **Resilience**. It helps in finding bugs in the existing   implementations. +- **Documentation**. The documentation over the Cairo VM is   still scarce, and + the latest version in prod (Rust) is not easy to read for   the average dev. +- **Architecture diversity**. Different architectures can be   implemented to + achieve the same goal (e.g. memory model). However, most of the current + implementations essentially are a rewrite of the Rust implementation, which is + an (enhanced) rewrite of the Python implementation itself. +- **Usage diversity**. The primary goals of each client can differ. For example, + the primary goals of production clients are performance and safety (Rust). + +The primary goal of our TypeScript client is **education** through +**readability** and **expressiveness**. + ### Demistifying the Cairo VM -The Cairo VM is still obscure to most of us, from a lack of documentation and hard-to-read languages obfuscating the inner workings of the VM. Nobody wants to struggle to reconstruct the missing pieces to understand how something works. +The Cairo VM is still obscure to most of us, from a lack of documentation and +hard-to-read languages obfuscating the inner workings of the VM. Nobody wants to +struggle to reconstruct the missing pieces to understand how something works. -We are implementing a Cairo VM in TypeScript to provide a well -documented and easy-to-comprehend Cairo VM +We are implementing a Cairo VM in TypeScript to provide a well documented and +easy-to-comprehend Cairo VM - TypeScript is easily readable and known by most devs if not all - Deliberate design choices to further improve readability and simplicity From 374d592525ae6b16ccefa0ef3b288d5d1c93ec59 Mon Sep 17 00:00:00 2001 From: malatrax Date: Thu, 2 May 2024 16:46:51 +0200 Subject: [PATCH 04/10] doc: change "client" to "implementation" --- README.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 12f4444f..f67f7d33 100644 --- a/README.md +++ b/README.md @@ -30,7 +30,7 @@ See [resources](#resources) for more information. ## Why this -### Client Diversity +### Implementation Diversity There are currently five other Cairo VM implementations: @@ -58,7 +58,8 @@ on how they built their Cairo VM. It gives insights into the overall Cairo VM but is incomplete and rather specific to language details. Why would you have different implementations of the same program in multiple -languages? For **client diversity**. As more clients provide more: +languages? For **implementation diversity**. As more implementations provide +more: - **Resilience**. It helps in finding bugs in the existing   implementations. - **Documentation**. The documentation over the Cairo VM is   still scarce, and @@ -67,10 +68,11 @@ languages? For **client diversity**. As more clients provide more: achieve the same goal (e.g. memory model). However, most of the current implementations essentially are a rewrite of the Rust implementation, which is an (enhanced) rewrite of the Python implementation itself. -- **Usage diversity**. The primary goals of each client can differ. For example, - the primary goals of production clients are performance and safety (Rust). +- **Usage diversity**. The primary goals of each implementation can differ. For + example, the primary goals of production implementations are performance and + safety (Rust). -The primary goal of our TypeScript client is **education** through +The primary goal of our TypeScript implementation is **education** through **readability** and **expressiveness**. ### Demistifying the Cairo VM From b046b7e95b6a06f5eb7904881280d29baee1e404 Mon Sep 17 00:00:00 2001 From: malatrax Date: Mon, 13 May 2024 09:13:42 +0200 Subject: [PATCH 05/10] doc: fix number of VM implem --- README.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index f67f7d33..9a25429a 100644 --- a/README.md +++ b/README.md @@ -23,8 +23,9 @@ Cairo stands for CPU AIR "o" (like insp"o", conv"o", 🤔). It is a framework (a machine, an assembly and a language) which allows writing provable programs without having to understand the underneath ZK-technology. -A program written in Cairo (or Cairo Zero) is compiled and then executed on a -Cairo VM which produces traces to be used for the STARK proof generation. +A program written in Cairo (or Cairo Zero) is compiled to Cairo Assembly (CASM) +and then executed on a Cairo VM which produces traces to be used for the STARK +proof generation. See [resources](#resources) for more information. @@ -32,7 +33,7 @@ See [resources](#resources) for more information. ### Implementation Diversity -There are currently five other Cairo VM implementations: +There are currently seven other Cairo VM implementations: @@ -50,6 +51,9 @@ There are currently five other Cairo VM implementations: by Community (dev) - A [C++ implementation](https://github.com/lambdaclass/cairo-vm.c) by Lambda Class (dev) +- A + [GoogleSheets (gs AppScript) implementation](https://github.com/ClementWalter/cairo-vm-gs) + by Clément Walter (dev) The Lambda Class alt-implementations comes with a detailed guide ([Go](https://github.com/lambdaclass/cairo-vm_in_go/blob/main/README.md#documentation), From ebe6aa9940f57be00867c3604ddd43e19663d89e Mon Sep 17 00:00:00 2001 From: malatrax Date: Mon, 13 May 2024 09:21:10 +0200 Subject: [PATCH 06/10] doc: remove erroneous/unnecessary parts --- README.md | 9 --------- 1 file changed, 9 deletions(-) diff --git a/README.md b/README.md index 9a25429a..8c51f770 100644 --- a/README.md +++ b/README.md @@ -35,8 +35,6 @@ See [resources](#resources) for more information. There are currently seven other Cairo VM implementations: - - - Reference (original) [implementation in Python](https://github.com/starkware-libs/cairo-lang) by Starkware (prod) @@ -81,13 +79,6 @@ The primary goal of our TypeScript implementation is **education** through ### Demistifying the Cairo VM -The Cairo VM is still obscure to most of us, from a lack of documentation and -hard-to-read languages obfuscating the inner workings of the VM. Nobody wants to -struggle to reconstruct the missing pieces to understand how something works. - -We are implementing a Cairo VM in TypeScript to provide a well documented and -easy-to-comprehend Cairo VM - - TypeScript is easily readable and known by most devs if not all - Deliberate design choices to further improve readability and simplicity - Extensive documentation: JSDoc, diagrams, explainers, etc. From b425e43e9e6b8dd5aa70565fff640bd107225895 Mon Sep 17 00:00:00 2001 From: malatrax Date: Mon, 13 May 2024 09:42:26 +0200 Subject: [PATCH 07/10] doc: add EVM ref implem on usage diversity and analogy --- README.md | 20 +++++++++++++------- 1 file changed, 13 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 8c51f770..5727fa91 100644 --- a/README.md +++ b/README.md @@ -60,8 +60,9 @@ on how they built their Cairo VM. It gives insights into the overall Cairo VM but is incomplete and rather specific to language details. Why would you have different implementations of the same program in multiple -languages? For **implementation diversity**. As more implementations provide -more: +languages? For **implementation diversity**. + +More implementations provide more: - **Resilience**. It helps in finding bugs in the existing   implementations. - **Documentation**. The documentation over the Cairo VM is   still scarce, and @@ -70,12 +71,17 @@ more: achieve the same goal (e.g. memory model). However, most of the current implementations essentially are a rewrite of the Rust implementation, which is an (enhanced) rewrite of the Python implementation itself. -- **Usage diversity**. The primary goals of each implementation can differ. For - example, the primary goals of production implementations are performance and - safety (Rust). -The primary goal of our TypeScript implementation is **education** through -**readability** and **expressiveness**. +Implementation diversity also implies **usage diversity**. The primary goals of +each implementation can differ. For example, the EVM implementation in clients +(e.g. geth and reth written in Go and Rust), whose primary goals are +**performance** and **safety**, and the +[reference EVM implementation](https://github.com/ethereum/execution-specs/?tab=readme-ov-file#execution-specification-work-in-progress) +in Python, prioritizing **readability** and **simplicity**. + +Analogous to the EVM implementations, the primary goals of the Rust Cairo VM are +performance and safety. While the ones of our TypeScript implementation is +**education** through **readability** and **simplicity**. ### Demistifying the Cairo VM From 5b5403156d8386d0c803cb5a4fb8c711840f6dd0 Mon Sep 17 00:00:00 2001 From: malatrax Date: Mon, 13 May 2024 09:43:48 +0200 Subject: [PATCH 08/10] doc: replace unescaped character by unicode html entity --- README.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 5727fa91..fac1a353 100644 --- a/README.md +++ b/README.md @@ -91,14 +91,14 @@ performance and safety. While the ones of our TypeScript implementation is ## State of the VM -| Goals | Done? | -| ---------------------------- | ----- | -| Run basic Cairo Zero program | 🗹 | -| Run basic Cairo program | ☐ | -| Run any Cairo Zero program | ☐ | -| Run any Cairo program | ☐ | -| Run any StarkNet contract | ☐ | -| Benchmark against other VMs | ☐ | +| Goals | Done? | +| ---------------------------- | ------- | +| Run basic Cairo Zero program | ☑ | +| Run basic Cairo program | ☐ | +| Run any Cairo Zero program | ☐ | +| Run any Cairo program | ☐ | +| Run any StarkNet contract | ☐ | +| Benchmark against other VMs | ☐ | From b8ca2373f28c2e41cf690765f965e1ecbec69926 Mon Sep 17 00:00:00 2001 From: malatrax Date: Mon, 13 May 2024 10:08:26 +0200 Subject: [PATCH 09/10] doc: make goals more concrete --- README.md | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index fac1a353..8cdcf109 100644 --- a/README.md +++ b/README.md @@ -95,13 +95,22 @@ performance and safety. While the ones of our TypeScript implementation is | ---------------------------- | ------- | | Run basic Cairo Zero program | ☑ | | Run basic Cairo program | ☐ | -| Run any Cairo Zero program | ☐ | -| Run any Cairo program | ☐ | -| Run any StarkNet contract | ☐ | +| Add [builtins](#builtins) | ☐ | +| Add [hints](#hints) | ☐ | +| Run StarkNet contracts | ☐ | | Benchmark against other VMs | ☐ | +### Builtins + + + +### Hints + + + + ## Resources @@ -109,7 +118,6 @@ performance and safety. While the ones of our TypeScript implementation is - [Cairo whitepaper](https://eprint.iacr.org/2021/1063) - [Cairo Book](https://book.cairo-lang.org/) - [Cairo website](https://www.cairo-lang.org/) -- ## Local Development From 31f05213e4f862d6391fe7d8964d5238385cee94 Mon Sep 17 00:00:00 2001 From: malatrax Date: Mon, 13 May 2024 10:13:39 +0200 Subject: [PATCH 10/10] doc: add spacing and links to EL clients --- README.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 8cdcf109..0a969407 100644 --- a/README.md +++ b/README.md @@ -73,9 +73,12 @@ More implementations provide more: an (enhanced) rewrite of the Python implementation itself. Implementation diversity also implies **usage diversity**. The primary goals of -each implementation can differ. For example, the EVM implementation in clients -(e.g. geth and reth written in Go and Rust), whose primary goals are -**performance** and **safety**, and the +each implementation can differ. + +For example, the EVM implementation in clients (e.g. +[geth](https://geth.ethereum.org/) and +[reth](https://github.com/paradigmxyz/reth) written in Go and Rust), whose +primary goals are **performance** and **safety**, and the [reference EVM implementation](https://github.com/ethereum/execution-specs/?tab=readme-ov-file#execution-specification-work-in-progress) in Python, prioritizing **readability** and **simplicity**.