# EVM From Scratch: a test suite that grades your own Ethereum VM

> EVM From Scratch is a course repository built around a single evm.json file of test cases, where the goal is to write an EVM implementation in any language that passes them, and starter templates in twelve languages are provided. The advanced test set is paid for, the licence is not stated, and the primary language of the repository is Zig.

**w1nt3r-eth/evm-from-scratch** — Super secret 100% practical EVM course. Please do not share

- Repository: https://github.com/w1nt3r-eth/evm-from-scratch
- Website: https://evmfromscratch.com/
- Stars: 738 · Forks: 179
- Language: Zig
- License: not declared
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/w1nt3r-eth-evm-from-scratch

## The specification is a JSON file, the implementation is yours

EVM From Scratch is described as a fully practical course whose goal is to help you understand the inner workings of the Ethereum Virtual Machine by implementing it. The unusual thing is that the repository is not a tutorial with steps. It is a test suite.

The central artefact is evm.json, a file of test cases, and the stated goal is to create an implementation in any programming language of your choice that passes all of them. The documentation is explicit that you do not have to use the provided templates and can build your own test suite based on the same file, or on the Pro variant described later.

Each test case has a name, code and an expectation. The code comes in two forms: a human-readable instruction list called asm, and machine-readable bytecode encoded in hex called bin. The rules are precise, and the reason for the split is debugging. Your implementation should only look at bin, because bin is what a real EVM would execute, and asm exists so that when a test fails you can read what was supposed to happen rather than reverse engineering hex.

That is a sound testing design. A test that lets you pass by reading the answer teaches the reader the answer rather than the machine.

The cases are organised by complexity, starting with the simplest opcodes and progressing gradually to advanced ones. So the suite is also a curriculum: the order of the file is a suggested order of implementation.

## Twelve language templates, one Makefile entry each

The repository ships starter templates for JavaScript, TypeScript, Python, Go and Rust, and the directory listing shows the range is in fact wider: there are directories for cpp, csharp, elixir, java, kotlin, ruby, swift and zig as well, alongside javascript, python, rust, go and typescript.

The primary language of the repository is listed as Zig, which is a fact about the code rather than a recommendation, and the Makefile gives each language a target that runs the corresponding implementation.

The commands are short. Most are a single line:

```bash
go:
	cd go && go test -count=1 -v ./...

rust:
	cd rust && cargo run

zig:
	cd zig && zig run evm.zig
```

The Go target is the exception in style, since it runs the test framework rather than a script, while Python, Ruby, JavaScript and TypeScript run their entry file with the interpreter, for example python3 python/evm.py or node typescript/evm.test.ts. C# runs dotnet run evm.cs and Swift runs swift run.

Two targets fetch dependencies before running, and this is where the cross-language differences show. The Java and Kotlin targets both depend on a Gson jar, downloaded with curl into a .deps directory, and then run with the jar on the classpath, Java with java --class-path and Kotlin with kotlin -classpath pointing at the same file. The C++ target depends on two header only libraries, intx.hpp from the intx project at version 0.15.0 and json.hpp from the nlohmann json project at 3.12.0, and compiles with the C++20 standard flag before running the result.

The practical workflow is: pick one language, run its make target, and watch the cases fail one at a time.

## The advanced cases are a paid file placed beside the free one

There is a two tier structure, and the boundary is a file on disk rather than a login.

To use the paid test suite you place evm-pro.json in the repository root, next to evm.json. The Pro version has more than 200 test cases that gradually walk you through implementing your own EVM. The documentation points to the course site for getting the full course.

The design is worth a second look, because it is unusual and mostly a good one. The free artefact is the specification, and it is genuinely complete enough to learn from. The paid artefact is a much larger set of cases, which is useful for two different reasons: it is more thorough, and it is the thing you use to check that your implementation is right in the cases the free file does not cover. A course that shipped only the harder tests would be a poor teaching tool, and one that shipped only the easy ones would not verify much.

Placing the file next to the original rather than behind a service keeps the workflow offline. Once you have it, the test runner reads it like any other JSON, and there is no network dependency in the loop.

The repository description asks people not to share it, which is worth noting as a fact about the project rather than an instruction to follow here. Everything in the repository was made by w1nt3r.eth, and the repository is described as part of the EVM From Scratch course. The site is evmfromscratch.com.

## An unlicensed repository with no releases and a Zig leaning

Two facts should be checked before you build on this.

The first is the licence. No licence is named for the repository, and there is no LICENSE file among the top level entries, which run from .github and .gitignore through AGENTS.md, CLAUDE.md, Makefile, README.md and the language directories. Without a licence file, the default under copyright applies, which means there is no permission to copy, modify or redistribute the code, and no grant for the templates either. For a repository whose entire purpose is to be copied and modified, that is a significant gap, and it is the kind of thing that a company lawyer will flag immediately.

The second is the release and activity picture. The repository has no GitHub releases, the default branch is main, and the last push was on 2026-09-14, about five weeks before the current date. So the code is being worked on, but there is no versioned artifact to depend on. You take the main branch as it stands.

The topic list is also slightly broader than the code. It names ethereum, evm, go, python, rust and typescript, while the primary language is recorded as Zig. That spread is explained by the templates, one per language, and the topics reflect the languages a learner is most likely to pick rather than the language the course itself is written in.

There is a Makefile at the root, an AGENTS.md and a CLAUDE.md for working with the project, and a .github/ directory. The AGENTS.md and CLAUDE.md files are worth a look before you contribute, since they describe the conventions a coding agent is expected to follow when touching this repository.

## What the format does not tell you

A test suite is a precise contract, and it is not the same thing as a specification of the EVM.

The tests exercise opcodes, and the cases are ordered from simple to advanced, which means the suite defines a subset of behaviour rather than the whole machine. A passing implementation tells you that your EVM agrees with the reference on the cases in evm.json. It does not tell you about gas accounting subtleties, about the full opcode set, about precompiles, or about the edge cases that only appear under adversarial input. The documentation does not claim otherwise, but a learner who assumes a green test run means a complete EVM will be disappointed later.

The bin and asm split is also a boundary worth noting. Because your implementation only reads bin, the suite is checking that you execute the right bytes. It is not checking that you agree with the reference implementation's internal state, its error handling or its memory model, only that the observable results match the expectations.

There is a practical consequence for the multi-language templates. Each template is a starting point with its own idioms, its own test harness and its own dependency handling, and the Makefile shows the spread: Java and Kotlin share a downloaded Gson jar, C++ needs two vendored headers fetched by curl, Go uses the standard test framework, Rust uses cargo run. The JavaScript and TypeScript entries run a node script and a node test file respectively, so even the two closest languages differ in how the suite is invoked.

None of that is a flaw. It is the honest cost of a course that wants to work in whatever language you already know, and it is why the documentation insists you can throw the templates away and build your own harness against the same JSON.

## Conclusion

EVM From Scratch suits a developer who wants to understand the Ethereum Virtual Machine by implementing it, and who is comfortable working from a test suite rather than from a tutorial, since the whole design is a specification in JSON with a reference implementation per language. It does not suit a team shipping an EVM for production use, because the repository has no releases, no stated licence, and the advanced cases live behind a paid file. Before starting, read evm.json to see how the cases are shaped, pick one language template and delete the rest, and treat the Pro suite as a paid dependency if you need it.

## FAQ

### What is EVM From Scratch?

It is a practical course repository whose central artefact is evm.json, a file of test cases. The goal is to write an EVM implementation in any programming language of your choice that passes all of them, and starter templates are provided in twelve languages including Go, Rust, Python, JavaScript, TypeScript, Zig, C++, Java, Kotlin, Ruby, C# and Swift.

### What is the difference between the asm and bin fields in the test cases?

Each test case provides the code as a human-readable instruction list called asm and as machine-readable bytecode in hex called bin. Your implementation should only look at bin, and asm is provided to make unit tests easier to debug.

### What does the paid Pro test suite add?

You place evm-pro.json in the repository root next to evm.json, and it contains more than 200 test cases that gradually walk you through implementing your own EVM. The full course is available through the linked course site.

### How do I run the tests for my language?

Each language has a Makefile target, for example the go target runs go test -count=1 -v ./... inside the go directory, the rust target runs cargo run, and the zig target runs zig run evm.zig. Java and Kotlin targets first download a Gson jar, and the C++ target fetches two header only libraries before compiling.

### Can I use the EVM From Scratch templates in a commercial project?

The repository records no licence, and there is no LICENSE file among the top level entries, so there is no explicit permission to copy, modify or redistribute the templates or the test data. Check this with whoever handles licensing in your organisation before relying on it.

## Sources

- [Issues](https://github.com/w1nt3r-eth/evm-from-scratch/issues)
- [Project website](https://evmfromscratch.com/)
- [README](https://github.com/w1nt3r-eth/evm-from-scratch/blob/main/README.md)
- [w1nt3r-eth/evm-from-scratch on GitHub](https://github.com/w1nt3r-eth/evm-from-scratch)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/w1nt3r-eth-evm-from-scratch