{"slug": "a-solidity-compiler-written-in-zig", "title": "A Solidity compiler written in Zig", "summary": "Chainwall released oksolc 0.1.6, a Solidity compiler written in Zig that targets byte-compatibility with Solidity 0.8.36 through the optimized via-IR Standard JSON path, though the team states it is not production ready for onchain deployment and recommends the original solc for that. The project ships a CLI, a libsolc-compatible C ABI with libsolc.h, and a public Zig module named solidity, and was built with AI assistance (GPT 5.5 then 5.6 Sol) under human guidance. Documented deviations from solc 0.8.36 include named custom-error arguments in require encoding in declaration order, hexadecimal array bounds in IR, and Yul memoryguard retaining the exclusive 2^32 - 1 size limit.", "body_md": "`oksolc` is a Zig implementation of the Solidity compiler that we built for our\ninternal use in developing [Chainwall](https://chainwall.org).\n\nIts goal is to provide an alternative implementation of Solidity for development purposes, allowing faster iteration on the developer experience.\n\n**We don’t consider `oksolc` to be production ready for deploying smart\ncontracts onchain, and recommend using the original solc compiler for\ndeployment. That said, we strive to be byte-compatible at this stage with\nSolidity 0.8.36, apart from the documented exceptions below. Other deviations in\ncompiler output should be considered bugs and reported in Issues.**\n\nThe supported compilation path is the optimized, via-IR compilation through the Standard JSON interface.\n\nThe project provides:\n\n- `oksolc` , a small command-line interface\n- a shared `libsolc` -compatible C ABI and installed`libsolc.h`\n- a public Zig module named `solidity`\n\nNote this project was built with AI assistance (using GPT 5.5 then 5.6 Sol) but under strict human guidance and control, our team having previous experience in building compilers and in formal verification. We intend to publish the methods and controls that we used.\n\nThe compatibility target is the original Solidity `0.8.36` compiler for Standard\nJSON, creation bytecode, diagnostics, and deterministic output.\n\nIntentional exceptions:\n\n- Named custom-error arguments in `require` encode in declaration order.\n- Array bounds retain hexadecimal spelling in IR.\n- Empty dispatch omits unused helpers from unoptimized IR.\n- Hexadecimal subassembly prefixes require a following hex digit.\n- Yul `memoryguard` retains the exclusive`2^32 - 1` size limit.\n\nThe `compile` command enables the optimizer with 200 runs. Use `standard-json`\nwhen exact control of compiler settings or output selection is required.\n\noksolc has an independent product version; the Solidity version identifies its\ncompatibility target. See [CHANGELOG.md](https://github.com/okcontract/oksolc/blob/main/CHANGELOG.md) for release history.\n\n``` bash\n$ oksolc version\noksolc 0.1.6 (Solidity 0.8.36)\n$ oksolc --version\noksolc, a solidity compiler commandline interface\nVersion: 0.8.36+oksolc.0.1.6\n```\n\n`oksolc version --json` returns `version` (the product version),\n`solidity_version` (the compatibility target), `compatibility_version` (the\nSolidity SemVer with oksolc build metadata), and `build_identity` (the compiler\ncontent identity, or `null` if unavailable). Include this output in bug reports.\nThe public Zig module exposes the product version as `solidity.version` and the\nSolidity target as `solidity.baseline.version`.\n\n`--version` and the C ABI's `solidity_version()` retain a Solidity-compatible\nSemVer for tools such as Foundry. Even development releases put the oksolc\nversion after `+`, so the Solidity target is still treated as a release.\nContract metadata and CBOR keep the pinned reference compiler identity to\npreserve output and bytecode compatibility. Use the product version for upgrade\ncomparisons; SemVer precedence ignores the build metadata after `+`.\n\n- Zig `0.16.0`\n- TypeScript `7.0.2` (`tsc` ) and Bun`1.4.2` only for the optional web browser\n- libc and a working C toolchain\n- Clang with ASan/UBSan runtimes for `fuzz-json-adapter` and`fuzz` (limited to\nthe yyjson adapter for now)\n- Python 3 for tests and benchmark orchestration\n- `solc` version`0.8.36` for optional reference audits and benchmark\ncomparisons\n- `zstd` to replay the bundled external benchmarks; Forge and Git to capture\nfresh requests, plus Node.js/npm for old Uniswap and Node.js for Pendle setup\n\nThe first Zig build downloads the dependencies declared in `build.zig.zon`.\n\nBuild the CLI, shared library, and C header:\n\n```\nzig build -Doptimize=ReleaseFast\n```\n\nThe executable is at `zig-out/bin/oksolc`; the library and header are in\n`zig-out/lib` and `zig-out/include`. Add `zig-out/bin` to your `PATH` or install\nto a different prefix:\n\n```\nzig build -Doptimize=ReleaseFast --prefix \"$HOME/.local\"\n```\n\nFor development, omit `-Doptimize` for Debug mode, or use\n`-Doptimize=ReleaseSafe` for an optimized build with runtime safety checks. To\nbuild only the CLI, use `zig build build-cli`.\n\nThe web browser is disabled by default, so ordinary builds require neither Bun\nnor TypeScript. To include `oksolc browse` and `oksolc serve --browse`, install\nthe pinned browser tools and opt in:\n\n```\nzig build -Doptimize=ReleaseFast -Dbrowser=true\n```\n\nDistribution builds can strip debug information and select a target:\n\n```\nzig build -Dtarget=aarch64-macos -Doptimize=ReleaseFast -Dstrip=true \\\n  --prefix build/macos-arm64\nzig build -Dtarget=x86_64-linux-gnu -Doptimize=ReleaseFast -Dstrip=true \\\n  --prefix build/linux-amd64\n```\n\nCompile one or more Solidity files and write the Standard JSON result to stdout:\n\n```\noksolc compile Contract.sol Library.sol\n```\n\nFor control over compiler settings and requested artifacts, supply a Standard\nJSON request from a file or stdin. Use `-o` to save the result:\n\n```\noksolc standard-json request.json\noksolc standard-json - < request.json\noksolc standard-json -o build/output.json request.json\n```\n\nFor filesystem imports, `--base-path` sets the source lookup root and repeatable\n`--include-path` options add library directories (include paths require an\nexplicit base path).\n\nAS of now, source paths must stay within the configured roots and cannot contain symlinks.\n\nIndependent contract backends can compile in parallel. `--jobs` sets total\nconcurrency, including the main thread:\n\n```\noksolc compile --parallel --jobs 4 Contract.sol Library.sol\n```\n\nAdd `--progress` for terminal progress, or `--profile-optimizer FILE` to save\ncompiler timings as JSON. Run `oksolc --help` or `oksolc <command> --help` for\nall options.\n\nPoint your project’s `foundry.toml` at the built executable and enable the\nsupported optimized via-IR pipeline:\n\n```\n[profile.default]\nsolc = \"/absolute/path/to/oksolc/zig-out/bin/oksolc\"\nvia_ir = true\noptimizer = true\noptimizer_runs = 200\n```\n\nThen run `forge build` as usual. Run `forge clean` first if you need to rebuild\nartifacts produced by a previous compiler.\n\nTo enable parallel compilation for the project, add an `oksolc.toml` alongside\n`foundry.toml`:\n\n```\nparallel = true\njobs = 4\n```\n\nFor projects that manage libraries as Git submodules:\n\n```\noksolc install\n```\n\nThis uses Git to install the submodules needed by `remappings.txt`, including\nnested dependencies, at the commits recorded by the repository. Without\n`remappings.txt`, it installs all declared submodules; an empty file selects\nnone.\n\nGit must be on `PATH`. Use `--base-path PATH` to select another project and\n`--jobs N` to change the number of concurrent clones (default: 4). Git handles\ncredentials and checkout conflicts; resolve any conflict and rerun to continue.\n\nBuild with `-Dbrowser=true` to include the web browser, which updates as you edit:\n\n```\noksolc serve --browse\n```\n\nOpen `http://127.0.0.1:8080`. The browser provides source navigation, search,\ndefinition links, references, diagnostics, ABI, bytecode, and other compiler\nartifacts. Use `--port` to choose another port.\n\nBy default, `serve` watches Solidity files in `src/` and their imported\ndependencies. It reads `remappings.txt` and recompiles when sources, used\nimports, or remappings change. To watch another source directory, set it in\n`oksolc.toml`:\n\n```\nsource-path = \"contracts\"\n```\n\nYou can also use `--source-path contracts`. Restart the server after changing\n`oksolc.toml`.\n\nFor a single compilation or an existing Standard JSON request/output pair:\n\n```\noksolc browse src/Vault.sol\noksolc browse --request input.json\noksolc browse --request input.json --import-output output.json\n```\n\nCompilations are saved in `.oksolc/browser.sqlite`.\n\nNote you should add `.oksolc/` to your project `.gitignore`.\n\nRun `oksolc browse` to reopen saved results. Select an older compilation to\ninspect it, or **Follow latest** to return to live updates. Use\n`--database FILE` for another location or `--database :memory:` for a temporary\nsession.\n\nWithout `--browse`, `oksolc serve` writes one Standard JSON result per line. You\ncan also watch a request file and update an output file after each change:\n\n```\noksolc watch request.json -o output.json\n```\n\nFor tool integrations, `oksolc serve --stdio` keeps a compiler session alive and\nexchanges Standard JSON messages.\n\nProject settings live in `oksolc.toml`. The project root is the nearest parent\ncontaining that file or a `.git` marker, or the current directory if neither\nexists. Commands accepting `--base-path` use that path as the project root.\n\nUser defaults live in `$XDG_CONFIG_HOME/oksolc/config.toml`, normally\n`~/.config/oksolc/config.toml`. Project settings override user defaults, with\none exception: persistent compiler caching must be enabled in the user\nconfiguration, outside the repository:\n\n```\ncache = true\n```\n\nEvery compilation uses the incremental compiler. Long-running `serve` and\n`watch` sessions reuse work in memory; persistent caching allows reuse between\nprocesses. Each project’s cache is stored under\n`$XDG_CACHE_HOME/oksolc/projects-v2`, normally `~/.cache/oksolc/projects-v2`,\nand authenticated with a local key created in the user configuration directory.\n\nUse `--no-cache` or set `cache = false` in `oksolc.toml` to disable persistence.\nBrowser snapshots are saved separately, so they remain available with caching\noff.\n\nInspect, prune, or remove the current project’s compiler cache:\n\n```\noksolc cache stats\noksolc cache prune --max-bytes 8GiB --max-entries 51200\noksolc clean\n```\n\nCache limits can also be set in `oksolc.toml`. The defaults are:\n\n```\ncache-max-entries = 102400\ncache-max-bytes = \"16GiB\"\ncache-busy-timeout-ms = 250\n```\n\nCI runs unit and ownership tests in Debug and compiler interface and output checks in ReleaseFast, in parallel. Debug retains runtime safety checks and avoids optimizing every unit-test binary. Run the same checks locally:\n\n```\nzig build test-unit -Doptimize=Debug -Dbrowser=true\nzig build cli-smoke libsolc-c-smoke compatibility-check -Doptimize=ReleaseFast\nzig build fmt-check\nzig build lint\n```\n\nThe separate fuzz workflow runs in ReleaseSafe. `zig build test` still runs\nthe combined suite, including compiler smoke tests, compatibility checks, and\nfuzz seeds; use `-Doptimize=ReleaseSafe` for a full optimized safety-check run.\n\nCI validates workflow definitions with actionlint. Run the same check locally before changing the workflows:\n\n```\ngo run github.com/rhysd/actionlint/cmd/actionlint@v1.7.12 -color\n```\n\n`zig build check` compiles the compiler, CLI, and tests without running the\nunit-test executables. For browser changes, use:\n\n```\nzig build typecheck-browser test-browser-types\nzig build browser-smoke test-cli test-browser-store -Dbrowser=true -Doptimize=ReleaseSafe\n```\n\nCompiler and CLI tests also work without the browser tools; omit `-Dbrowser=true`\nto test the default build. Browser HTTP smoke targets (including\n`diagnostic-limit-smoke`) require `-Dbrowser=true`. Explicit asset targets such\nas `build-browser`, `typecheck-browser`, and `test-browser-types` always use the\nbrowser tools.\n\nThe test suite compares against checked-in `solc 0.8.36` outputs. Unoptimized\ncontract IR is compared as Yul tokens, allowing whitespace and comment changes\nfrom direct tree generation. All other output bytes must match exactly. Run that\ncheck alone, or audit the fixtures against your installed `solc`:\n\n```\nzig build compatibility-check\nzig build reference-check -Dbenchmark-reference-solc=solc\n```\n\nSee the [compatibility corpus](https://github.com/okcontract/oksolc/blob/main/test/zig/standard-json/README.md) for fixture\ndetails. To run the parser, JSON, and Standard JSON fuzzers, plus the yyjson\nadapter under ASan/UBSan:\n\n```\nzig build fuzz --fuzz=10K -Dadapter-fuzz-runs=10000 -j2\n```\n\nRun benchmarks on an otherwise idle machine with a native ReleaseFast build.\nReports are written under `build/benchmarks`.\n\nThe local suite checks exact Standard JSON output against system `solc`, then\ntimes three contracts:\n\n```\nzig build benchmark-local -Doptimize=ReleaseFast \\\n  -Dbenchmark-reference-solc=solc -Dbenchmark-runs=3\n```\n\nFor focused compiler and optimizer workloads:\n\n```\nzig build benchmark-zbench -Doptimize=ReleaseFast\n```\n\nFor incremental compilation, the synthetic edit traces check output compatibility and record cache metrics:\n\n```\nzig build benchmark-incremental -Doptimize=ReleaseFast\n```\n\nThe external suite compares oksolc with original `solc 0.8.36`. Replay the\nimported Standard JSON requests without project downloads or Forge:\n\n```\nzig build benchmark-external -Doptimize=ReleaseFast \\\n  -Dbenchmark-reference-solc=solc -Dbenchmark-runs=3 -Dbenchmark-warmups=1 \\\n  -- --bundled-requests\n```\n\nSelect projects with repeated `--project NAME` flags. For example, to compare\nonly Pendle, including all its production contracts and imported dependencies:\n\n```\nzig build benchmark-external -Doptimize=ReleaseFast \\\n  -- --bundled-requests --project pendle-v2-2026-09-16\n```\n\nTo download the pinned projects and capture fresh requests through Forge:\n\n```\ntest/benchmarks/external-setup.sh\nzig build benchmark-external -Doptimize=ReleaseFast\n```\n\nSetup also accepts `--project NAME`. Project checkouts go in the ignored\n`benchmarks/` directory; override it with `BENCHMARK_DIR`. Captured requests\nare retained under `build/benchmarks/external/<project>/requests/`. To repeat\nthe comparison using exactly those requests:\n\n```\nzig build benchmark-external -Doptimize=ReleaseFast \\\n  -- --reuse-captured-requests build/benchmarks/external\n```\n\nUse a new `BENCHMARK_REPORT_DIR` for another fresh capture. It also controls\nwhere per-project JSON reports and numeric summaries are written. The direct\nlauncher accepts compiler paths and the measured run count:\n\n```\nzig build build-cli -Doptimize=ReleaseFast\ntest/benchmarks/external-compare.sh --bundled-requests \\\n  solc zig-out/bin/oksolc 3\n```\n\n| Path | Contents | \n|---|---|\n| `src/cli/` | CLI and local compiler browser | \n| `src/libsolidity/` | Solidity frontend and via-IR code generation | \n| `src/libyul/` | Yul parser, analysis, code generation, and optimizer | \n| `src/libevmasm/` | EVM assembly and optimization | \n| `src/libsolc/` | Standard JSON dispatcher and C ABI | \n| `src/incremental/` | Incremental compilation and persistent caching | \n| `src/root.zig` | Public `solidity` Zig API | \n| `include/libsolc.h` | Public C header | \n| `test/zig/` | Unit, integration, CLI, and compatibility tests | \n| `test/benchmarks/` | Benchmark fixtures and launchers | \n| `build.zig` | Build, test, and benchmark steps | \n\n`oksolc` is licensed under the [GNU General Public License v3.0](https://github.com/okcontract/oksolc/blob/main/LICENSE.txt).\nSee [THIRD_PARTY_LICENSES.txt](https://github.com/okcontract/oksolc/blob/main/THIRD_PARTY_LICENSES.txt) for dependency notices.", "url": "https://wpnews.pro/news/a-solidity-compiler-written-in-zig", "canonical_source": "https://github.com/okcontract/oksolc", "published_at": "2026-10-12 14:29:00+00:00", "updated_at": "2026-10-12 14:46:33.366477+00:00", "lang": "en", "topics": ["developer-tools", "artificial-intelligence"], "entities": ["oksolc", "Chainwall", "Solidity", "Zig", "solc", "GPT 5.5", "GPT 5.6 Sol", "Foundry"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/a-solidity-compiler-written-in-zig", "markdown": "https://wpnews.pro/news/a-solidity-compiler-written-in-zig.md", "text": "https://wpnews.pro/news/a-solidity-compiler-written-in-zig.txt", "jsonld": "https://wpnews.pro/news/a-solidity-compiler-written-in-zig.jsonld"}}