Backward-Compatibility and Breaking Change Policy

The ZK Stack defines a strict policy for backward compatibility to provide a predictable upgrade path for zkSync Era and other ZK Stack hyperchains. This policy distinguishes between the core protocol, which may introduce breaking changes with a mandatory migration window, and the Web3 API, which follows a deprecation-and-sunset cycle. The primary goal is to eliminate the surprise of 'silent' breaking changes, ensuring that wallet teams, bridge operators, and dApp developers have a clear, time-bound signal to adapt their software before an upgrade activates on mainnet.

A breaking change is formally defined as any modification that would cause a previously valid transaction, API call, or smart contract interaction to fail or produce a different result. This includes changes to the IAccount interface, modifications to system contract addresses or their public methods, alterations to the gas metering schema, and the removal of precompiles. Critically, the policy mandates that such changes are communicated with a minimum deprecation period, typically spanning several upgrade epochs, before the breaking logic is activated. This allows developers to deploy new wallet versions, update SDK dependencies, and migrate smart contracts to new interfaces without risking a sudden loss of liveness for their users.

For operators and integration partners, the breaking change policy shifts the risk from the moment of upgrade activation to the preceding migration window. The operational burden is on teams to monitor the protocol's versioning announcements and execute the necessary code updates before the deadline. Failure to do so can result in transaction submission failures from outdated wallets, incorrect fee estimation from unpatched SDKs, and a complete inability for users to interact with dApps that rely on deprecated system contract functions. Chainscore Labs helps teams manage this risk by providing breaking-change impact analysis and migration planning, ensuring that integration logic and smart contract code are updated and verified against the new protocol version before the compatibility window closes.

A backward-compatibility policy on zkSync Era is only as strong as the definition of its compatibility surface. This surface includes every stable interface a builder, operator, or downstream system depends on: the JSON-RPC API, the L1 smart contract ABIs, the L2 system contract addresses and their IAccount and IPaymaster interfaces, the block and transaction formats, the gas metering and fee estimation logic, the state tree and storage log layout, and the pubdata compression and posting format. A protocol upgrade that modifies any of these vectors can break wallets, block explorers, indexers, bridges, centralized exchanges, or prover operators, even if the change is semantically backward-compatible at the execution layer.

The most common breakage vectors are not always the most obvious. A change to the bootloader or DefaultAccount implementation can alter how EOAs validate transactions, silently breaking SDKs that simulate eth_estimateGas or paymasters that rely on specific validation flow ordering. A modification to the ContractDeployer system contract can change the address derivation for CREATE2, breaking factory contracts and cross-chain deployment tools. An upgrade to the fee model that introduces a new pricing dimension, such as a storage-access cost, will cause every wallet and dApp that uses eth_gasPrice or eth_feeHistory to misprice transactions until their estimation logic is updated. Even a change to the L2 block structure, such as adding a new field to the block header, can break indexers and block explorers that parse raw block data without a version-aware decoder.

For operators, the compatibility surface extends to the node and prover software. A state tree migration that changes the Merkle tree version or the storage log format will force archive nodes and data pipelines to re-index historical state. A pubdata format change will break any external prover or bridge that independently reconstructs L2 state from L1 calldata or blobs. The Gateway upgrade path itself, which commits new bootloader and default account hashes through the ValidatorTimelock, is a compatibility event: any system that hardcodes these hashes for security verification must be updated in lockstep with the L1 transaction. Chainscore Labs helps teams map their specific dependency surface against each protocol upgrade, providing a breaking-change impact analysis that identifies exactly which components require code changes, configuration updates, or re-indexing before the activation epoch.