Towards Source Mapping for Zero-Knowledge Smart Contracts: Design and Preliminary Evaluation

TL;DR

This work tackles the lack of source mapping in zkSolc by proposing a preliminary framework that ties Solidity source code to LLVM IR and zkEVM bytecode through dual mapping layers and a unified metadata table. It addresses the non-linear transformations of zero-knowledge compilation with lightweight consistency checks and demonstrates feasibility via experiments on 50 benchmark and 500 real-world contracts, achieving around 97% mapping accuracy with modest overhead. The approach enables improved debugging, security auditing, and optimization analysis in zk-Rollup environments, though it acknowledges limitations with inline assembly, complex inheritance, and current tooling gaps. Overall, the study lays foundational methodology for end-to-end traceability in zero-knowledge smart contract tooling and points to future work on broader platform generalization and tighter toolchain integration.

Abstract

Debugging and auditing zero-knowledge-compatible smart contracts remains a significant challenge due to the lack of source mapping in compilers such as zkSolc. In this work, we present a preliminary source mapping framework that establishes traceability between Solidity source code, LLVM IR, and zkEVM bytecode within the zkSolc compilation pipeline. Our approach addresses the traceability challenges introduced by non-linear transformations and proof-friendly optimizations in zero-knowledge compilation. To improve the reliability of mappings, we incorporate lightweight consistency checks based on static analysis and structural validation. We evaluate the framework on a dataset of 50 benchmark contracts and 500 real-world zkSync contracts, observing a mapping accuracy of approximately 97.2% for standard Solidity constructs. Expected limitations arise in complex scenarios such as inline assembly and deep inheritance hierarchies. The measured compilation overhead remains modest, at approximately 8.6%. Our initial results suggest that source mapping support in zero-knowledge compilation pipelines is feasible and can benefit debugging, auditing, and development workflows. We hope that this work serves as a foundation for further research and tool development aimed at improving developer experience in zk-Rollup environments.

Figures (1)

• Figure 1: zkSolc compilation pipeline zksync_toolchain. Yul is an intermediate language used in Solidity compilation. Vyper and LLL are alternative smart contract languages supported by EVM toolchains but are outside the scope of this work.