docs(shadow-testing): clarify PostEuclidV2 function vs PostFeynman verifier, add v0.9.0 lessons

Author: lispc

tests/shadow-testing/docs/GUIDE.md

@@ -573,7 +573,7 @@ For `finalizeBundlePostEuclidV2`, the batch was already committed on mainnet at
 
 ## Real Verifier Deployment
 
-### Option 1: Copy the Mainnet Verifier (Fastest)
+### Option 1: Copy the Mainnet Verifier (Fastest — Only if Digests Match)
 
 For quick testing, copy the exact mainnet verifier contract code to Anvil using `anvil_setCode`:
 
@@ -589,7 +589,7 @@ PLONK_CODE=$(cast code $PLONK --rpc-url https://ethereum-rpc.publicnode.com)
 cast rpc anvil_setCode $PLONK $PLONK_CODE --rpc-url http://localhost:18545
 ```
 
-This preserves the exact immutables (plonkVerifier address, digests, protocolVersion) from mainnet and works as long as your proofs use the same digests as mainnet.
+This preserves the exact immutables (plonkVerifier address, digests, protocolVersion) from mainnet and works **only** if your proofs use the same digests as mainnet. When testing a new guest / circuit version (e.g., v0.9.0) whose digests differ from mainnet, this will produce `VerificationFailed`; use Option 2 instead.
 
 ### Option 2: Deploy a Fresh Verifier Using S3 Digests
 
@@ -616,6 +616,24 @@ For v0.9.0 release assets are under `scroll-zkvm/releases/v0.9.0/`:
 
 > ✅ **Use the S3 digest files directly.** For guest v0.9.0, `digest_1.hex` / `digest_2.hex` are published in the canonical form expected by the Plonk verifier. You no longer need to extract digests from a proof's `instances` array.
 
+### Important: `finalizeBundlePostEuclidV2` uses a `ZkEvmVerifierPostFeynman` verifier
+
+Do not be misled by the contract function name. `ScrollChain` only has one bundle-finalize entry point:
+
+```text
+finalizeBundlePostEuclidV2(bytes,uint256,bytes32,bytes32,bytes)
+```
+
+There is **no** `finalizeBundlePostFeynman` function. The actual verifier used by this function is selected by `MultipleVersionRollupVerifier.getVerifier(version, batchIndex)`. For the current mainnet GalileoV2 range, that verifier is a `ZkEvmVerifierPostFeynman`-style wrapper whose `protocolVersion` immutable equals `10`.
+
+- `ZkEvmVerifierPostEuclid` computes `keccak256(publicInput)`. This is old code and is **not** used for current GalileoV2 / v0.9.0 proofs.
+- `ZkEvmVerifierPostFeynman` computes `keccak256(abi.encodePacked(protocolVersion, publicInput))` with `protocolVersion = 10`. This matches the `bundle_pi_hash` produced by v0.9.0 guest provers.
+
+So on a shadow fork you must either:
+
+1. Copy the exact mainnet `ZkEvmVerifierPostFeynman` wrapper (only works if your local proofs use the **same digests** as mainnet), or
+2. Deploy a fresh `ZkEvmVerifierPostFeynman` with the digests from the v0.9.0 S3 release and register it on the MVRV.
+
 ### Verifying Digests Match Your Proofs
 
 If you want to double-check, compare the canonical digests from S3 against the values stored in the deployed wrapper:

tests/shadow-testing/docs/TROUBLESHOOTING.md

@@ -236,6 +236,46 @@ Before executing a single command:
 | Coordinator asset download 403 (`galileov2/verifier/...`) | Wrong S3 prefix; use `v0.8.0/verifier/` | Trap 14 |
 | `l2_block` export hangs for minutes | Slow `chunk_hash` JOIN; export by block-number range | Trap 15 |
 
+## Lessons from the v0.9.0 Multi-Bundle Shadow Test
+
+The following issues were hit while finalizing bundles 17297–17301 (batches 517761–517765) on an Anvil mainnet fork with zkvm guest prover v0.9.0. Keep them in mind for future upgrades.
+
+### 1. Do not `git checkout --` uncommitted source changes blindly
+
+When cleaning up the branch, the v0.9.0 source adaptations (`libzkp`, `prover-bin`, Go `message` types, `rust-toolchain`, `Cargo.lock`) were accidentally reverted because they were not committed. They had to be reconstructed from compiler errors. Always check `git diff --stat` before a bulk revert, and stage or stash anything you intend to keep.
+
+### 2. `finalizeBundlePostEuclidV2` is the only finalize function, but the verifier must be Post-Feynman
+
+`ScrollChain` exposes only one bundle-finalize selector (`0xc1aa4e19`). The name says `PostEuclidV2`, but the verifier it actually calls is chosen by `MultipleVersionRollupVerifier.getVerifier(10, batchIndex)`. For GalileoV2 / v0.9.0 this must be a `ZkEvmVerifierPostFeynman`-style wrapper whose `protocolVersion` immutable is `10`.
+
+- `ZkEvmVerifierPostEuclid` computes `keccak256(publicInput)` — this is old code and will reject current proofs.
+- `ZkEvmVerifierPostFeynman` computes `keccak256(protocolVersion || publicInput)` — this matches v0.9.0 `bundle_pi_hash`.
+
+### 3. Copying the mainnet verifier via `anvil_setCode` fails for new guest versions
+
+`anvil_setCode` copies runtime bytecode but **preserves the original immutables** (`plonkVerifier`, `verifierDigest1/2`, `protocolVersion`). If your local v0.9.0 proofs use different digests than mainnet, the wrapper will return `VerificationFailed`. For a new guest version, deploy a fresh `ZkEvmVerifierPostFeynman` using the S3 release digests.
+
+### 4. MVRV routing must be verified per target batch
+
+After deploying a new verifier, confirm that `MVRV.getVerifier(10, batchIndex)` returns your wrapper for every batch you intend to finalize. If the fork block already contains a later mainnet verifier registration, a plain `updateVerifier` may be rejected; force the storage slot or impersonate the owner as needed for the shadow fork.
+
+### 5. v0.9.0 dependency graph needs a fresh `Cargo.lock`
+
+Pointing `Cargo.toml` to v0.9.0 is not enough. The first `cargo check` hit a revm version conflict because the old `Cargo.lock` pinned incompatible crate versions. Regenerating `Cargo.lock` resolved it.
+
+### 6. Prover aggregation circuits need deferral enabled
+
+OpenVM v2+ requires `Prover::enable_deferral(child_prover)` before proving aggregation tasks:
+
+- Batch proving needs a chunk child prover.
+- Bundle proving needs a batch child prover.
+
+The prover config therefore needs `child_circuit_vks` so the prover can load the correct child circuit assets.
+
+### 7. S3 digest files are canonical — no proof extraction needed
+
+For v0.9.0, `.../releases/v0.9.0/bundle/digest_1.hex` and `digest_2.hex` are published in the canonical form expected by the Plonk verifier. Do not apply Montgomery→canonical conversion and do not extract digests from proof `instances` unless you are double-checking a specific artifact.
+
 ## Documentation Priority
 
 When debugging, read docs in this order: