feat: add zksync EraVM source verification and Abstract chain - #2788

Security: the attacker-controlled compilerVersion reaches this URL and the on-disk path with no validation.

For zksolc the only gate on compilerVersion is the new OpenAPI pattern ^zksolc:.+;solc:.+$ (apiv2.yaml). validateCompilerVersion in middlewares.ts is not wired into any route, and parseZkSolcCompilerVersion splits on ([^;]+);solc:(.+). So both halves are arbitrary strings, slashes and .. included, and they flow straight into path.join() and into this template.

Chain for the zksolc half (the era-solc half is identical via getEraSolcExecutable):

1. normalizeZkSolcVersion only prepends v, so ../../../../owner/repo/releases/download/tag survives.
2. getZkSolcFileName builds zksolc-<platform>-v<version>, and path.join(zksolcRepoPath, fileName) resolves the .. segments — the write target escapes the compiler repo directory.
3. Here releaseTag is inserted raw (only fileName is encodeURIComponent-ed), so fetch() normalizes the .. segments and the request leaves matter-labs/era-compiler-solidity for an arbitrary owner/repo on github.com. I confirmed this resolves: https://github.com/matter-labs/era-compiler-solidity/releases/download/ + ../../../../attacker/repo/releases/download/v1/evil becomes https://github.com/attacker/repo/releases/download/v1/evil, and GitHub serves it (302 to the asset CDN).
4. On HTTP 200 fetchAndSaveCompiler does mkdirSync(recursive) + writeFileSync(..., { mode: 0o755 }) at the traversed path, and validateCompilerPath then runs spawnSync(compilerPath, ['--version']) on it.

So a single unauthenticated POST /v2/verify/:chainId/:address can make the worker write an executable outside the compiler repo directory and execute it. Reachable on master/staging, where zksolcRepo/eraSolcRepo are configured and isZkSolcEnabled is therefore true.

The pre-existing solc path is permissive too (^v?\d+\.\d+\.\d+.*$ allows a trailing /..), but it is pinned to binaries.soliditylang.org, which only serves official binaries. The new zksolc path is what makes the owner/repo attacker-selectable.

Suggested fix: validate both halves against a strict charset before they are used, ideally in validateZkSolcRequest so it is rejected with a 400 rather than deep in the worker — e.g. zksolc ^v?\d+\.\d+\.\d+$ plus the vm-1.5.0-a167aa3 special case, and solc ^(zkVM-)?v?\d+\.\d+\.\d+(-1\.0\.\d+|\+commit\.[0-9a-fA-F]+)?$. Tightening the ZkSolcVersion pattern in apiv2.yaml alone would help, but a defensive check at the path.join/URL boundary is worth having regardless.

getZkSolcCompilerVersionCandidates is never called outside its own module and the tests — the candidate-expansion/fallback feature it implements no longer exists.

$ grep -rn "getZkSolcCompilerVersionCandidates" packages services --include=*.ts | grep -v test
packages/lib-sourcify/src/Compilation/ZkSolcCompilation.ts:189

compile() now does a single compiler.compile(zksolcVersion, solcCompilerVersion, jsonInput), and the retry machinery (useNextCompilerVersionCandidate, retryWithNextCompilerVersionCandidate, resetVerificationAttempt) is gone. That removal is good and resolves my earlier threads. What is left over is the dead function, its supporting helpers (ERA_SOLC_EDITIONS, isSupportedEraSolcVersion, isEraSolcEditionAvailable, isEraSolcEditionCompatibleWithZkSolc, MAX_ERA_SOLC_1_0_0_SOLIDITY_VERSION), and the whole ZkSolcCompilerVersionCandidates describe block, which now asserts behaviour production never runs.

The docs still describe the removed behaviour, so they read as a feature list that the code does not implement:

• PR description: "If the exact upstream solc candidate fails to compile or fails bytecode matching, Sourcify falls back through compatible era-solc candidates until one matches or all candidates are exhausted."
• ZKSOLC.md: "If the solc half is missing the -1.0.0 edition suffix, the actual era edition is found by iterating over the candidates" and "ZkSolcCompilation tries upstream solc first (when given a commit-bearing version), then falls back through era-solc candidates."
• zksync-fixtures/README.md: "resolved from a commit-form version by candidate expansion."

Concretely, zksolc:1.5.10;solc:0.8.26 now routes to the upstream solc downloader and never tries 0.8.26-1.0.2/1/0.

Either drop the dead code and correct the three docs, or re-wire the candidate expansion if dropping it was not intended. Worth being explicit about which, since it changes what a caller has to supply.

This defaults the EraVM e2e suite on, so a normal npm test in lib-sourcify reaches the public internet. The file matches the test/**/*.spec.ts glob in the test script, so CI (test-lib-sourcify) picks it up and, per fixture, downloads zksolc + era-solc binaries from GitHub and reads on-chain state from https://api.mainnet.abs.xyz.

The preflight getBytecode skip keeps a fully offline run green, but it does not help the cases that actually hurt: a reachable-but-slow or rate-limited Abstract RPC, a reorg-independent RPC behaviour change, or a GitHub outage mid-suite, any of which turn into red builds unrelated to the change under test. It also makes the runtime of the default suite depend on network conditions.

Prefer opt-in: process.env.ZKSYNC_E2E === 'true', and enable it explicitly in whichever CI job should own it. The server-side counterpart in verify.zksolc.e2e.spec.ts already got this right with MockRpcServer replaying captured responses — same treatment here would make the suite deterministic, though the compiler downloads would remain.

Now that the combined zksolc:<v>;solc:<v> version string carries the toolchain, nothing zksolc-specific is written to additional_input any more — getAdditionalInputFromVerification only ever sets storage_layout_overrides. So "plus compiler plumbing metadata needed to reproduce non-standard compilations" describes a field that no longer exists, and the properties block below still lists only storage_layout_overrides.

Reads like a leftover from the era_solc_version design. Suggest restoring the original sentence.

This strip resolves the "not decodable" half of my earlier padding comment, but only inside this library. The stored cborAuxdata.value still carries the leading zero padding, so a plain CBOR decode of what the API and the database hand out throws (Data read, but end of buffer not reached), with or without the trailing length bytes. For the 1.5.15 fixture that is 41 bytes of padding in front of the map.

The decision is explained well in ZKSOLC.md, but that is a reviewer-facing doc in the compilers package. None of the surfaces a consumer actually reads mention it:

• apiv2.yaml: every cborAuxdata description reads as if the value decodes like the Solidity one.
• packages/bytecode-utils/README.md: does not mention AuxdataStyle.ZKSYNC at all, nor that decode() handles the padding for you.

Please document it there — that for EraVM contracts the value is [zero padding][cbor][length], and that consumers must strip leading zero bytes before decoding (or use decode(bytecode, AuxdataStyle.ZKSYNC) from bytecode-utils).

Optional, since it changes more than this PR: this ZKSYNC-only fallback could go away if export() used the compilation getters (creationLinkReferences / runtimeLinkReferences) for every language, which is what the matching logic already does.

Why it is not a plain swap today: the server stores the exported value with || null (database-util.ts lines 794 and 815). Solidity always emits linkReferences: {} because the default output selection asks for it, so nothing changes there. Vyper and Fe have no such field, so they are stored as null today, and the getters would turn that into {}. Same meaning, different stored value.

Clean version: use the getters here for all languages, and let the server map an empty object to null, so stored rows stay as they are. That removes the special case and the two try/catch blocks. Also note the creation half of this fallback is a no-op: the getter reads the same evm.bytecode.linkReferences field and only turns undefined into {}.

Fine to leave for a follow-up if you prefer to keep this PR focused.

Prefer undefined over "" as the "disabled" state, and carry it through the types. The empty string is a sentinel the type system cannot see: VerificationServiceOptions declares both paths as plain string, so "" travels on as if it were a path.

Where it matters: verificationWorker.ts line 71 does not check at all. It always builds ZkSolcLocal from the worker data, with "" when zksolc is disabled, and path.join("", fileName) then resolves against the working directory. The API middleware keeps zksolc jobs out when disabled, so nothing reaches it today, but the worker itself has no guard, unlike this file and ServerFixture.ts.

Suggestion:

• zksolcRepoPath?: string / eraSolcRepoPath?: string in VerificationServiceOptions and VerificationService; isZkSolcEnabled keeps working unchanged.
• In the worker, mirror this file: build ZkSolcLocal only when both paths are set, else leave zksolc undefined. createCompilationFromJsonInput already accepts zksolc?: IZkSolcCompiler and throws when a zksolc version arrives without a compiler.
• The initWorker early-return condition includes zksolc; with undefined as a legal state it needs a separate initialized flag, or should check only solc, vyper and fe.

Please add a note here on why this exists next to LocalChainFixture, so nobody tries to fold it into the Hardhat fixture or picks it for a test where the Hardhat node is the right tool. Something like:

Only needed for EraVM (zksolc) tests. Hardhat runs EVM bytecode only: it cannot hold EraVM code, and it cannot produce a creation tx to the ContractDeployer with a receipt that carries the contract address, so LocalChainFixture cannot serve these tests. There is no local EraVM node in the repo (anvil-zksync is archived), so this replays captured responses instead. EVM tests should keep using LocalChainFixture.

Two limits worth stating in the same block: the replay is keyed by method only and ignores request params (any address gets the same eth_getCode result), and it cannot return JSON-RPC errors. Fine for the single-contract e2e it serves; both would need to change before it is used more widely.

Please revert this hunk and restore chai.assert.fail(...).

This is a leftover: commit 7ae73b90 changed the assertion into a skip at the same time as it added the chain 40 test with the same pattern. That test was removed in 9e0a7138, but this change stayed. It is unrelated to zksolc.

It is also dead code today. The loop covers chains 1, 43114, 100009 and 56, and all four are in the map this spec builds in beforeEach, so the branch can never run. What it changes is the failure mode: if someone adds a test case for a chain that is missing from the map, the test now passes silently instead of failing.

Two related asks for this test, since it is a storage-level verification case rather than an endpoint test:

1. Assert everything, with the existing helpers. This checks a hand-picked subset of fields. The verification-cases framework already has assertDatabase (every row and column a verification writes) and assertApiV2Lookup (the lookup with fields=all, every field compared with a case file). Neither depends on Hardhat: they take a VerificationTestCase JSON (onchain / input / output / verification), the chain id, the deployer address, and a DeploymentInfo (address, tx hash, block number, tx index). All of that is already in rpc-responses.json; only the case file needs to be captured once from this run. MockRpcServer stays as the chain.

This matters beyond coverage: a case file's output.metadata would have exposed the zksolc metadata wrapper shape, and output.creationCodeArtifacts + creationTransformations would have exposed the constructor offset that does not fit the stored recompiled creation code (see my comments on zksolcTestHelpers.ts and ZKSOLC.md). It also closes my earlier thread on verify.json.spec.ts.

2. Move it next to the other cases. verification-cases/ already holds a second spec for a different deployment mode (factories.spec.ts), and testdata/ already has per-language folders (fe, vyper). Suggest verification-cases/eravm.spec.ts, with the case file and rpc-responses.json under testdata/eravm/. That also drops the .e2e.spec.ts suffix, which only the two zksolc files in this PR use.