A Solidity compiler written in Zig

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.

oksolc is a Zig implementation of the Solidity compiler that we built for our internal use in developing Chainwall https://chainwall.org . Its goal is to provide an alternative implementation of Solidity for development purposes, allowing faster iteration on the developer experience. We don’t consider oksolc to be production ready for deploying smart contracts onchain, and recommend using the original solc compiler for deployment. That said, we strive to be byte-compatible at this stage with Solidity 0.8.36, apart from the documented exceptions below. Other deviations in compiler output should be considered bugs and reported in Issues. The supported compilation path is the optimized, via-IR compilation through the Standard JSON interface. The project provides: - oksolc , a small command-line interface - a shared libsolc -compatible C ABI and installed libsolc.h - a public Zig module named solidity Note 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. The compatibility target is the original Solidity 0.8.36 compiler for Standard JSON, creation bytecode, diagnostics, and deterministic output. Intentional exceptions: - Named custom-error arguments in require encode in declaration order. - Array bounds retain hexadecimal spelling in IR. - Empty dispatch omits unused helpers from unoptimized IR. - Hexadecimal subassembly prefixes require a following hex digit. - Yul memoryguard retains the exclusive 2^32 - 1 size limit. The compile command enables the optimizer with 200 runs. Use standard-json when exact control of compiler settings or output selection is required. oksolc has an independent product version; the Solidity version identifies its compatibility target. See CHANGELOG.md https://github.com/okcontract/oksolc/blob/main/CHANGELOG.md for release history. bash $ oksolc version oksolc 0.1.6 Solidity 0.8.36 $ oksolc --version oksolc, a solidity compiler commandline interface Version: 0.8.36+oksolc.0.1.6 oksolc version --json returns version the product version , solidity version the compatibility target , compatibility version the Solidity SemVer with oksolc build metadata , and build identity the compiler content identity, or null if unavailable . Include this output in bug reports. The public Zig module exposes the product version as solidity.version and the Solidity target as solidity.baseline.version . --version and the C ABI's solidity version retain a Solidity-compatible SemVer for tools such as Foundry. Even development releases put the oksolc version after + , so the Solidity target is still treated as a release. Contract metadata and CBOR keep the pinned reference compiler identity to preserve output and bytecode compatibility. Use the product version for upgrade comparisons; SemVer precedence ignores the build metadata after + . - Zig 0.16.0 - TypeScript 7.0.2 tsc and Bun 1.4.2 only for the optional web browser - libc and a working C toolchain - Clang with ASan/UBSan runtimes for fuzz-json-adapter and fuzz limited to the yyjson adapter for now - Python 3 for tests and benchmark orchestration - solc version 0.8.36 for optional reference audits and benchmark comparisons - zstd to replay the bundled external benchmarks; Forge and Git to capture fresh requests, plus Node.js/npm for old Uniswap and Node.js for Pendle setup The first Zig build downloads the dependencies declared in build.zig.zon . Build the CLI, shared library, and C header: zig build -Doptimize=ReleaseFast The executable is at zig-out/bin/oksolc ; the library and header are in zig-out/lib and zig-out/include . Add zig-out/bin to your PATH or install to a different prefix: zig build -Doptimize=ReleaseFast --prefix "$HOME/.local" For development, omit -Doptimize for Debug mode, or use -Doptimize=ReleaseSafe for an optimized build with runtime safety checks. To build only the CLI, use zig build build-cli . The web browser is disabled by default, so ordinary builds require neither Bun nor TypeScript. To include oksolc browse and oksolc serve --browse , install the pinned browser tools and opt in: zig build -Doptimize=ReleaseFast -Dbrowser=true Distribution builds can strip debug information and select a target: zig build -Dtarget=aarch64-macos -Doptimize=ReleaseFast -Dstrip=true \ --prefix build/macos-arm64 zig build -Dtarget=x86 64-linux-gnu -Doptimize=ReleaseFast -Dstrip=true \ --prefix build/linux-amd64 Compile one or more Solidity files and write the Standard JSON result to stdout: oksolc compile Contract.sol Library.sol For control over compiler settings and requested artifacts, supply a Standard JSON request from a file or stdin. Use -o to save the result: oksolc standard-json request.json oksolc standard-json - < request.json oksolc standard-json -o build/output.json request.json For filesystem imports, --base-path sets the source lookup root and repeatable --include-path options add library directories include paths require an explicit base path . AS of now, source paths must stay within the configured roots and cannot contain symlinks. Independent contract backends can compile in parallel. --jobs sets total concurrency, including the main thread: oksolc compile --parallel --jobs 4 Contract.sol Library.sol Add --progress for terminal progress, or --profile-optimizer FILE to save compiler timings as JSON. Run oksolc --help or oksolc <command --help for all options. Point your project’s foundry.toml at the built executable and enable the supported optimized via-IR pipeline: profile.default solc = "/absolute/path/to/oksolc/zig-out/bin/oksolc" via ir = true optimizer = true optimizer runs = 200 Then run forge build as usual. Run forge clean first if you need to rebuild artifacts produced by a previous compiler. To enable parallel compilation for the project, add an oksolc.toml alongside foundry.toml : parallel = true jobs = 4 For projects that manage libraries as Git submodules: oksolc install This uses Git to install the submodules needed by remappings.txt , including nested dependencies, at the commits recorded by the repository. Without remappings.txt , it installs all declared submodules; an empty file selects none. Git must be on PATH . Use --base-path PATH to select another project and --jobs N to change the number of concurrent clones default: 4 . Git handles credentials and checkout conflicts; resolve any conflict and rerun to continue. Build with -Dbrowser=true to include the web browser, which updates as you edit: oksolc serve --browse Open http://127.0.0.1:8080 . The browser provides source navigation, search, definition links, references, diagnostics, ABI, bytecode, and other compiler artifacts. Use --port to choose another port. By default, serve watches Solidity files in src/ and their imported dependencies. It reads remappings.txt and recompiles when sources, used imports, or remappings change. To watch another source directory, set it in oksolc.toml : source-path = "contracts" You can also use --source-path contracts . Restart the server after changing oksolc.toml . For a single compilation or an existing Standard JSON request/output pair: oksolc browse src/Vault.sol oksolc browse --request input.json oksolc browse --request input.json --import-output output.json Compilations are saved in .oksolc/browser.sqlite . Note you should add .oksolc/ to your project .gitignore . Run oksolc browse to reopen saved results. Select an older compilation to inspect it, or Follow latest to return to live updates. Use --database FILE for another location or --database :memory: for a temporary session. Without --browse , oksolc serve writes one Standard JSON result per line. You can also watch a request file and update an output file after each change: oksolc watch request.json -o output.json For tool integrations, oksolc serve --stdio keeps a compiler session alive and exchanges Standard JSON messages. Project settings live in oksolc.toml . The project root is the nearest parent containing that file or a .git marker, or the current directory if neither exists. Commands accepting --base-path use that path as the project root. User defaults live in $XDG CONFIG HOME/oksolc/config.toml , normally ~/.config/oksolc/config.toml . Project settings override user defaults, with one exception: persistent compiler caching must be enabled in the user configuration, outside the repository: cache = true Every compilation uses the incremental compiler. Long-running serve and watch sessions reuse work in memory; persistent caching allows reuse between processes. Each project’s cache is stored under $XDG CACHE HOME/oksolc/projects-v2 , normally ~/.cache/oksolc/projects-v2 , and authenticated with a local key created in the user configuration directory. Use --no-cache or set cache = false in oksolc.toml to disable persistence. Browser snapshots are saved separately, so they remain available with caching off. Inspect, prune, or remove the current project’s compiler cache: oksolc cache stats oksolc cache prune --max-bytes 8GiB --max-entries 51200 oksolc clean Cache limits can also be set in oksolc.toml . The defaults are: cache-max-entries = 102400 cache-max-bytes = "16GiB" cache-busy-timeout-ms = 250 CI 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: zig build test-unit -Doptimize=Debug -Dbrowser=true zig build cli-smoke libsolc-c-smoke compatibility-check -Doptimize=ReleaseFast zig build fmt-check zig build lint The separate fuzz workflow runs in ReleaseSafe. zig build test still runs the combined suite, including compiler smoke tests, compatibility checks, and fuzz seeds; use -Doptimize=ReleaseSafe for a full optimized safety-check run. CI validates workflow definitions with actionlint. Run the same check locally before changing the workflows: go run github.com/rhysd/actionlint/cmd/actionlint@v1.7.12 -color zig build check compiles the compiler, CLI, and tests without running the unit-test executables. For browser changes, use: zig build typecheck-browser test-browser-types zig build browser-smoke test-cli test-browser-store -Dbrowser=true -Doptimize=ReleaseSafe Compiler and CLI tests also work without the browser tools; omit -Dbrowser=true to test the default build. Browser HTTP smoke targets including diagnostic-limit-smoke require -Dbrowser=true . Explicit asset targets such as build-browser , typecheck-browser , and test-browser-types always use the browser tools. The test suite compares against checked-in solc 0.8.36 outputs. Unoptimized contract IR is compared as Yul tokens, allowing whitespace and comment changes from direct tree generation. All other output bytes must match exactly. Run that check alone, or audit the fixtures against your installed solc : zig build compatibility-check zig build reference-check -Dbenchmark-reference-solc=solc See the compatibility corpus https://github.com/okcontract/oksolc/blob/main/test/zig/standard-json/README.md for fixture details. To run the parser, JSON, and Standard JSON fuzzers, plus the yyjson adapter under ASan/UBSan: zig build fuzz --fuzz=10K -Dadapter-fuzz-runs=10000 -j2 Run benchmarks on an otherwise idle machine with a native ReleaseFast build. Reports are written under build/benchmarks . The local suite checks exact Standard JSON output against system solc , then times three contracts: zig build benchmark-local -Doptimize=ReleaseFast \ -Dbenchmark-reference-solc=solc -Dbenchmark-runs=3 For focused compiler and optimizer workloads: zig build benchmark-zbench -Doptimize=ReleaseFast For incremental compilation, the synthetic edit traces check output compatibility and record cache metrics: zig build benchmark-incremental -Doptimize=ReleaseFast The external suite compares oksolc with original solc 0.8.36 . Replay the imported Standard JSON requests without project downloads or Forge: zig build benchmark-external -Doptimize=ReleaseFast \ -Dbenchmark-reference-solc=solc -Dbenchmark-runs=3 -Dbenchmark-warmups=1 \ -- --bundled-requests Select projects with repeated --project NAME flags. For example, to compare only Pendle, including all its production contracts and imported dependencies: zig build benchmark-external -Doptimize=ReleaseFast \ -- --bundled-requests --project pendle-v2-2026-09-16 To download the pinned projects and capture fresh requests through Forge: test/benchmarks/external-setup.sh zig build benchmark-external -Doptimize=ReleaseFast Setup also accepts --project NAME . Project checkouts go in the ignored benchmarks/ directory; override it with BENCHMARK DIR . Captured requests are retained under build/benchmarks/external/<project /requests/ . To repeat the comparison using exactly those requests: zig build benchmark-external -Doptimize=ReleaseFast \ -- --reuse-captured-requests build/benchmarks/external Use a new BENCHMARK REPORT DIR for another fresh capture. It also controls where per-project JSON reports and numeric summaries are written. The direct launcher accepts compiler paths and the measured run count: zig build build-cli -Doptimize=ReleaseFast test/benchmarks/external-compare.sh --bundled-requests \ solc zig-out/bin/oksolc 3 | Path | Contents | |---|---| | src/cli/ | CLI and local compiler browser | | src/libsolidity/ | Solidity frontend and via-IR code generation | | src/libyul/ | Yul parser, analysis, code generation, and optimizer | | src/libevmasm/ | EVM assembly and optimization | | src/libsolc/ | Standard JSON dispatcher and C ABI | | src/incremental/ | Incremental compilation and persistent caching | | src/root.zig | Public solidity Zig API | | include/libsolc.h | Public C header | | test/zig/ | Unit, integration, CLI, and compatibility tests | | test/benchmarks/ | Benchmark fixtures and launchers | | build.zig | Build, test, and benchmark steps | oksolc is licensed under the GNU General Public License v3.0 https://github.com/okcontract/oksolc/blob/main/LICENSE.txt . See THIRD PARTY LICENSES.txt https://github.com/okcontract/oksolc/blob/main/THIRD PARTY LICENSES.txt for dependency notices.