{"id":13409952,"url":"https://github.com/kkrt-labs/cairo-vm-ts","last_synced_at":"2025-08-18T08:13:16.685Z","repository":{"id":195038133,"uuid":"692120267","full_name":"kkrt-labs/cairo-vm-ts","owner":"kkrt-labs","description":"A typescript implementation of the Cairo VM","archived":false,"fork":false,"pushed_at":"2024-05-22T11:03:33.000Z","size":309,"stargazers_count":10,"open_issues_count":6,"forks_count":6,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-05-22T15:34:25.104Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kkrt-labs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-09-15T15:49:37.000Z","updated_at":"2024-05-28T09:15:36.772Z","dependencies_parsed_at":"2023-09-16T09:07:16.342Z","dependency_job_id":"88ac37dc-5fe1-49ab-aff0-76589a484428","html_url":"https://github.com/kkrt-labs/cairo-vm-ts","commit_stats":null,"previous_names":["kkrt-labs/cairo-vm-ts"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/kkrt-labs/cairo-vm-ts","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kkrt-labs%2Fcairo-vm-ts","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kkrt-labs%2Fcairo-vm-ts/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kkrt-labs%2Fcairo-vm-ts/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kkrt-labs%2Fcairo-vm-ts/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kkrt-labs","download_url":"https://codeload.github.com/kkrt-labs/cairo-vm-ts/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kkrt-labs%2Fcairo-vm-ts/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270962404,"owners_count":24675968,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-18T02:00:08.743Z","response_time":89,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-30T20:01:04.208Z","updated_at":"2025-08-18T08:13:16.664Z","avatar_url":"https://github.com/kkrt-labs.png","language":"TypeScript","funding_links":[],"categories":["Cairo VM"],"sub_categories":[],"readme":"# Cairo VM Typescript\n\n\u003cdiv align=\"center\"\u003e\n  \u003ch1\u003e\u003ccode\u003eCairo VM TypeScript\u003c/code\u003e\u003c/h1\u003e\n\n\u003cstrong\u003eAn implementation of the Cairo VM in TypeScript, focusing on\neducation\u003c/strong\u003e\n\n[Github](https://github.com/kkrt-labs/cairo-vm-ts) ·\n[Telegram](https://t.me/cairovmts)\n\n\u003csub\u003eBuilt with 🥕 by \u003ca href=\"https://twitter.com/KakarotZkEvm\"\u003eKKRT\nLabs\u003c/a\u003e\u003c/sub\u003e\n\n\u003c/div\u003e\n\n\u003e ⚠️ This project is in its genesis, undergoing fast-paced development. It is\n\u003e not suitable for production yet. Expect frequent breaking changes.\n\n## What is Cairo\n\nCairo stands for CPU AIR \"o\" (like insp\"o\", conv\"o\", 🤔).\n\nIt is a framework (a machine, an assembly and a language) which allows writing\nprovable programs without having to understand the underneath ZK-technology.\n\nA program written in Cairo (or Cairo Zero) is compiled to Cairo Assembly (CASM)\nand then executed on a Cairo VM which produces traces to be used for the STARK\nproof generation.\n\nSee [resources](#resources) for more information.\n\n## Why this\n\n### Implementation Diversity\n\nThere are currently seven other Cairo VM implementations:\n\n- Reference (original)\n  [implementation in Python](https://github.com/starkware-libs/cairo-lang) by\n  Starkware (prod)\n- New [implementation in Rust](https://github.com/lambdaclass/cairo-vm) by\n  Lambda Class (prod)\n- A [Go implementation](https://github.com/lambdaclass/cairo-vm_in_go), by\n  Lambda Class (dev)\n- Another [Go implementation](https://github.com/NethermindEth/cairo-vm-go) by\n  Nethermind (dev)\n- A\n  [Zig implementation](https://github.com/keep-starknet-strange/ziggy-starkdust),\n  by Community (dev)\n- A [C++ implementation](https://github.com/lambdaclass/cairo-vm.c) by Lambda\n  Class (dev)\n- A\n  [GoogleSheets (gs AppScript) implementation](https://github.com/ClementWalter/cairo-vm-gs)\n  by Clément Walter (dev)\n\nThe Lambda Class alt-implementations comes with a detailed guide\n([Go](https://github.com/lambdaclass/cairo-vm_in_go/blob/main/README.md#documentation),\n[C++](https://github.com/lambdaclass/cairo-vm.c?tab=readme-ov-file#documentation))\non how they built their Cairo VM. It gives insights into the overall Cairo VM\nbut is incomplete and rather specific to language details.\n\nWhy would you have different implementations of the same program in multiple\nlanguages? For **implementation diversity**.\n\nMore implementations provide more:\n\n- **Resilience**. It helps in finding bugs in the existing   implementations.\n- **Documentation**. The documentation over the Cairo VM is   still scarce, and\n  the latest version in prod (Rust) is not easy to read for   the average dev.\n- **Architecture diversity**. Different architectures can be   implemented to\n  achieve the same goal (e.g. memory model). However, most of the current\n  implementations essentially are a rewrite of the Rust implementation, which is\n  an (enhanced) rewrite of the Python implementation itself.\n\nImplementation diversity also implies **usage diversity**. The primary goals of\neach implementation can differ.\n\nFor example, the EVM implementation in clients (e.g.\n[geth](https://geth.ethereum.org/) and\n[reth](https://github.com/paradigmxyz/reth) written in Go and Rust), whose\nprimary goals are **performance** and **safety**, and the\n[reference EVM implementation](https://github.com/ethereum/execution-specs/?tab=readme-ov-file#execution-specification-work-in-progress)\nin Python, prioritizing **readability** and **simplicity**.\n\nAnalogous to the EVM implementations, the primary goals of the Rust Cairo VM are\nperformance and safety. While the ones of our TypeScript implementation is\n**education** through **readability** and **simplicity**.\n\n### Demistifying the Cairo VM\n\n- TypeScript is easily readable and known by most devs if not all\n- Deliberate design choices to further improve readability and simplicity\n- Extensive documentation: JSDoc, diagrams, explainers, etc.\n\n## Local Development\n\n### Requirements\n\n- Install [Bun](https://bun.sh/)\n- Install [Poetry](https://python-poetry.org/docs/#installation) to compile\n  Cairo Programs\n\n```bash\nbun install # install all dependencies\nbun test # run all tests\n```\n\n## Usage\n\n### CLI\n\nYou can install the CLI `cairo-vm-ts` by doing the following:\n\n1. Clone this repo: `git clone git@github.com:kkrt-labs/cairo-vm-ts.git`\n2. Go to the cloned directory: `cd cairo-vm-ts`\n3. Install the dependencies: `bun install`\n4. Register the package as a _linkable_ package: `bun link`\n\nSteps 3. and 4. can be replaced by `make build`\n\nExample usage:\n\n```bash\ncairo run fibonacci.json --export-memory fib_mem.bin --print-memory --print-output\n```\n\n### As a dependency\n\nNo package release has been done yet.\n\nYou can still add it as a dependency with a local copy:\n\n1. Clone this repo: `git clone git@github.com:kkrt-labs/cairo-vm-ts.git`\n2. Go to the cloned directory: `cd cairo-vm-ts`\n3. Install the dependencies: `bun install`\n4. Build the project: `bun run build`\n5. Go to your project `cd ~/my-project`\n6. Add `cairo-vm-ts` to your project dependency:\n   `\u003cbun | yarn | npm\u003e add ~/path/to/cairo-vm-ts`\n\n## State of the VM\n\n| Goals                        | Done?   |\n| ---------------------------- | ------- |\n| Run basic Cairo Zero program | \u0026#9745; |\n| Run basic Cairo program      | \u0026#9745; |\n| Add [builtins](#builtins)    | \u0026#9745; |\n| Add [hints](#hints)          | \u0026#9744; |\n| Run StarkNet contracts       | \u0026#9744; |\n| Benchmark against other VMs  | \u0026#9744; |\n\n\u003c!-- TODO: Add the state of each section of the VM and a small explainer of their purpose (VM core, hints, builtins, runner...) --\u003e\n\n### Builtins\n\n| Builtin                                                              | Done?   |\n| -------------------------------------------------------------------- | ------- |\n| [Output](https://github.com/kkrt-labs/cairo-vm-ts/issues/65)         | \u0026#9745; |\n| [Pedersen](https://github.com/kkrt-labs/cairo-vm-ts/issues/70)       | \u0026#9745; |\n| [Range Check](https://github.com/kkrt-labs/cairo-vm-ts/issues/68)    | \u0026#9745; |\n| [ECDSA](https://github.com/kkrt-labs/cairo-vm-ts/issues/67)          | \u0026#9745; |\n| [Bitwise](https://github.com/kkrt-labs/cairo-vm-ts/issues/62)        | \u0026#9745; |\n| [EcOp](https://github.com/kkrt-labs/cairo-vm-ts/issues/66)           | \u0026#9745; |\n| [Keccak](https://github.com/kkrt-labs/cairo-vm-ts/issues/69)         | \u0026#9745; |\n| [Poseidon](https://github.com/kkrt-labs/cairo-vm-ts/issues/71)       | \u0026#9745; |\n| [Range Check 96](https://github.com/kkrt-labs/cairo-vm-ts/issues/81) | \u0026#9745; |\n| [Segment Arena](https://github.com/kkrt-labs/cairo-vm-ts/pull/106)   | \u0026#9745; |\n| AddMod                                                               | \u0026#9744; |\n| MulMod                                                               | \u0026#9744; |\n\n### Hints\n\nHints are currently being implemented.\n\nTheir development can be tracked\n[here](https://github.com/kkrt-labs/cairo-vm-ts/issues/90).\n\n#### How to implement a hint ?\n\nA how-to guide has been written [here](/docs/howToImplementAHint.md).\n\n### Differential Testing \u0026 Benchmark\n\nPre-requisite: `make`\n\n### Differential Testing\n\nCompare the encoded memory and trace of execution between different Cairo VM\nimplementations on a broad range of Cairo programs.\n\nIt is currently only done in execution mode (non-proof mode) on programs with no\nhints. It uses the CLI of each VM implementation.\n\n| Cairo VM Implementations                                                     | Added to `diff-test` |\n| ---------------------------------------------------------------------------- | -------------------- |\n| [Cairo VM TS](https://github.com/kkrt-labs/cairo-vm-ts)                      | \u0026#9745;              |\n| [Cairo VM Rust](https://github.com/lambdaclass/cairo-vm)                     | \u0026#9745;              |\n| [Cairo VM Python](https://github.com/starkware-libs/cairo-lang)              | \u0026#9745;              |\n| [Cairo VM Zig](https://github.com/keep-starknet-strange/ziggy-starkdust)     | \u0026#9745;              |\n| [Cairo VM Go](https://github.com/NethermindEth/cairo-vm-go) - ProofMode only | \u0026#9744;              |\n\n#### Differential Testing Dependencies\n\nTo build the different projects CLI, you'll need the following dependencies:\n\n- [Rust 1.74.1 or newer](https://www.rust-lang.org/tools/install)\n- [Cargo](https://doc.rust-lang.org/cargo/getting-started/installation.html)\n- [Zig](https://ziglang.org/)\n- [Poetry](https://python-poetry.org/docs/#installation)\n\n#### How to diff-test\n\nTo run the differential tests, simply use `make diff-test`.\n\nIf you wanna compare an arbitrary amount of memory or trace files, you can\ndirectly use the `compare` command\n\n```bash\ncompare memory fib.memory fib2.memory fib3.memory\ncompare trace fib.trace fib2.trace fib3.trace\n```\n\n### Benchmark\n\n#### Benchmark Dependencies\n\n[`hyperfine`](https://github.com/sharkdp/hyperfine)\n\n#### Benchmark Details\n\nFor a quick benchmarking tool, one can run `make bench`\n\nIt uses `hyperfine` to benchmark the CLI command of the different Cairo VM\nimplementations. These benchmarks might not be accurate, it should be done in a\nproper environment.\n\nThe benchmark programs used currently come from the\n`cairo-vm/cairo_programs/benchmarks`. The workload of each program has been\nreduced for slower implementations to finish () Only Cairo programs with no\nhints are used at the moment:\n\n| Cairo Program                | Description                                                                                                                                                                                                                                                                    | Value                                                        |\n| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------ |\n| `big_factorial.cairo`        | Computes $n!$                                                                                                                                                                                                                                                                  | $n = 50000$                                                  |\n| `big_fibonacci.cairo`        | Computes $u_n = u_{n-1} + u_{n-2}, n \\geq 2, u_0 = 0, u_1 = 1$                                                                                                                                                                                                                 | $n = 40000$                                                  |\n| `integration_builtins.cairo` | Computes $N$ times $\\text{Pedersen}(a, u_{20})$. $\\forall n \\in \\mathbb{N^*}, u_n = D(u_{n-1}, v_{n})$, $v_n = 3v_{n-1}$, $D(x, y) = (x \\oplus y) \\land (x \\lor (y \\gg 1))$. Verifies that $\\forall n \\in \\mathbb{N}, v_n \u003c 2^{64}$ and stores the value in the output segment | $N = 100$, $a = 123568$, $u_0 = 5673940$, $v_0 = 6783043740$ |\n| `pedersen.cairo`             | Computes $N$ times $\\text{Pedersen}(a, b)$                                                                                                                                                                                                                                     | $N = 5000$, $a = 123568$, $b = 5673940$                      |\n\nA benchmark using each VM implementation API is developped at\n[`cairo-vm-bench`](https://github.com/kkrt-labs/cairo-vm-bench)\n\n## Resources\n\n- [Cairo whitepaper](https://eprint.iacr.org/2021/1063)\n- [Cairo Book](https://book.cairo-lang.org/)\n- [Cairo website](https://www.cairo-lang.org/)\n\n\u003c!-- TODO: Add Project Guidelines --\u003e\n\n## Contributing Guidelines\n\n- All commits must be\n  [signed](https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits)\n  (PGP or SSH key, we recommend PGP keys)\n- Issue assignment have a lifespan (e.g. 1d, 2d, 1w...), if no PR has been\n  opened between assignment and expiry date, you'll be unassigned. Issues\n  lifespan is introduced to avoid staling issues as the project moves quickly.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkkrt-labs%2Fcairo-vm-ts","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkkrt-labs%2Fcairo-vm-ts","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkkrt-labs%2Fcairo-vm-ts/lists"}