docs(l2): fix version number in upgrade docs

[avilagaston9]

Motivation

Two issues discovered while writing up a v9 → v10 upgrade runbook:

1. The upgrade section for the CommonBridge l2GasLimit migration was labeled "From v10 to v11" but was actually introduced in v10 (i.e., the migration is from v9 to v10).
2. docs/l2/fundamentals/contracts.md shows upgradeToAndCall being called directly on a contract proxy, but the OnChainProposer is owned by the Timelock — so any operator following those steps on the OCP hits an onlyOwner revert with no hint as to why.

Description

docs/l2/deployment/upgrades.md

• Rename section from "From v10 to v11" to "From v9 to v10"
• Update "From v11 onwards" to "From v10 onwards"

docs/l2/deployment/vanilla.md

• Fix cross-reference anchor (#from-v10-to-v11 → #from-v9-to-v10)

docs/l2/fundamentals/contracts.md

• Add a note that the OCP is owned by the Timelock, so upgradeToAndCall (and other onlyOwner operations like pause/unpause) cannot be called directly — the call must be routed through the Timelock. Points to the Timelock doc for the available execution paths (scheduled with delay vs. emergencyExecute), without prescribing one.

[github-actions]

🤖 Kimi Code Review

This is a documentation-only PR with valid fixes. Here's the review:

docs/l2/deployment/upgrades.md (lines 86, 89):

• Good fix correcting the version numbering from v10→v11 to v9→v10. This aligns the upgrade documentation with the actual release sequence.

docs/l2/deployment/vanilla.md (line 93):

• Correctly updates the anchor link reference to match the fixed version number in upgrades.md.

docs/l2/fundamentals/contracts.md (lines 132-135, 139):

• Line 132-135: Excellent addition. The note about Timelock ownership of the OnChainProposer is critical operational security documentation. Prevents operators from attempting direct calls that would revert with onlyOwner, saving debugging time and preventing potential operational incidents.
• Line 139: Important bug fix in the example command. Adding quotes around "<PROXY_ADDRESS>" ensures valid JSON-RPC format (addresses must be JSON strings). The previous unquoted <PROXY_ADDRESS> would produce malformed JSON when substituted. Changing from hardcoded localhost to <L1_RPC_URL> placeholder also improves portability.

Summary: Clean documentation improvements. No code changes, no security concerns. The Timelock note is particularly valuable for preventing operational errors.

---

Automated review by Kimi (Moonshot AI) · kimi-k2.5 · custom prompt

[github-actions]

🤖 Claude Code Review

Here is my review of PR #6515:

---

PR #6515 — docs(l2): fix version number in upgrade docs

Overview

Pure documentation fix addressing two real operator pain points: a mislabeled version section that would lead operators to the wrong upgrade runbook, and missing guidance about the Timelock requirement for OCP operations. All three changed files are docs only — no code changes.

---

What's correct and well done

• The v10 → v11 → v9 → v10 rename in upgrades.md is the right fix; the section heading and the "From vX onwards" prose are both updated consistently.
• The vanilla.md anchor update (#from-v10-to-v11 → #from-v9-to-v10) correctly tracks the heading rename.
• The Timelock note in contracts.md is accurate and prevents a very confusing onlyOwner revert with no clear hint. Positioning it immediately after the rex send command for step 2 is the right place.
• Replacing localhost:8545 with <L1_RPC_URL> prevents operators from sending a mainnet eth_getStorageAt check to a local node. Good catch.
• Adding quotes around <PROXY_ADDRESS> in the JSON array is a correctness fix — JSON string values require quotes, and the curl call would have been silently malformed before.
• The EIP-1967 implementation slot (0x360894a...382bbc) is correct (keccak256("eip1967.proxy.implementation") - 1).

---

Issues found

Broken internal link — validium.md not updated (same defect as vanilla.md)

docs/l2/deployment/validium.md:95 still contains the old anchor:

See [Upgrades](./upgrades.md#from-v10-to-v11) for how to view and update it.

The PR updated the identical sentence in vanilla.md but missed the same line in validium.md. After this PR merges, clicking that link in the validium deployment guide silently lands at the top of the upgrades page (no matching anchor), which is exactly the same broken-link class of bug the PR is trying to fix. This should be fixed in the same PR.

---

Minor observations (non-blocking)

• The Timelock note in contracts.md is scoped to OCP only ("The OnChainProposer is owned by the Timelock..."). The section it lives in is generic ("Upgrade the contracts" — applies to both OCP and CommonBridge). If CommonBridge is also Timelock-owned, the note should say so explicitly; if it isn't, a brief parenthetical clarifying that CommonBridge can be called directly would prevent operators from wondering whether the restriction applies to both proxies.

• The note says upgradeToAndCall must go through the Timelock and then links to timelock.md. It would be marginally more helpful if the note mentioned that the proxy address to pass to rex send is the Timelock's address (not the OCP proxy address directly), since the mental model shift from "call this proxy" to "call the Timelock targeting this proxy" is non-obvious.

---

Summary

The fix is correct and addresses real operator pain. One required fix: update validium.md:95 to #from-v9-to-v10 to complete the anchor rename. The two minor observations are suggestions, not blockers.

---

Automated review by Claude (Anthropic) · sonnet · custom prompt

[greptile-apps]

Greptile Summary

This PR fixes three documentation inaccuracies in the L2 docs: corrects version labels for the CommonBridge l2GasLimit migration section (v9→v10, not v10→v11), updates the cross-reference anchor in vanilla.md to match, and adds a critical operational note in contracts.md clarifying that upgradeToAndCall on the OnChainProposer must be routed through the Timelock. As a bonus, the curl command in contracts.md is also fixed (hardcoded localhost:8545 → <L1_RPC_URL>, and <PROXY_ADDRESS> is now properly quoted in the JSON body).

Confidence Score: 5/5

Safe to merge — all changes are documentation corrections with no code impact.

All three changes are purely documentation fixes that correct factual errors and add missing operational guidance. The timelock.md link target exists, the renamed anchor is consistent across files, and no code is affected.

No files require special attention.

Important Files Changed

Filename	Overview
docs/l2/deployment/upgrades.md	Version labels corrected from "v10→v11" to "v9→v10"; "From v11 onwards" phrase updated to "From v10 onwards" — aligns documentation with the actual release in which the CommonBridge l2GasLimit feature shipped.
docs/l2/deployment/vanilla.md	Cross-reference anchor updated from #from-v10-to-v11 to #from-v9-to-v10 to match the renamed section in upgrades.md — keeps the in-doc link functional.
docs/l2/fundamentals/contracts.md	Added Timelock ownership note for OCP upgrade path; also fixed curl command (hardcoded localhost → <L1_RPC_URL>, missing JSON string quotes around <PROXY_ADDRESS> added).

Sequence Diagram

sequenceDiagram
    participant Operator
    participant Timelock
    participant OCP as OnChainProposer (proxy)
    participant Impl as New Implementation

    Note over Operator,Impl: Upgrading OnChainProposer (OCP)

    Operator->>Operator: Deploy new implementation contract
    Operator->>Timelock: schedule(upgradeToAndCall, delay) OR emergencyExecute(upgradeToAndCall)
    Timelock->>OCP: upgradeToAndCall(newImpl, initData)
    OCP->>Impl: delegatecall initialize()
    OCP-->>Operator: Upgrade complete

    Note over Operator,OCP: Verify upgrade
    Operator->>OCP: eth_getStorageAt(ERC1967 slot)
    OCP-->>Operator: Returns new implementation address

Loading

_{Reviews (1): Last reviewed commit: "Add note about OCP ownership by Timelock..." | Re-trigger Greptile}

[github-actions]

🤖 Codex Code Review

1. Broken anchor introduced by the heading rename. upgrades.md now defines the section as From v9 to v10, but validium.md still links to ./upgrades.md#from-v10-to-v11. That leaves the validium deployment docs pointing to a dead anchor for the l2GasLimit upgrade instructions.

2. The new Timelock note is correct for OnChainProposer, but it is placed inside a generic “Upgrade the contracts” section and reads as if it applies to all contracts in that procedure. See contracts.md and contracts.md. CommonBridge is still upgraded by its direct owner, not through the Timelock, so this wording can send operators down the wrong admin path. I’d either scope the note explicitly to OCP upgrades or split the upgrade docs by contract.

Assumptions:

• The diff in /tmp/pr_diff.txt is complete; I did not find any executable Rust/Solidity changes in this PR.

Aside from those doc regressions, this PR looks fine. No code-correctness, gas-accounting, consensus, or memory-safety concerns are in scope here because the patch is documentation-only.

---

Automated review by OpenAI Codex · gpt-5.4 · custom prompt

[Copilot]

Pull request overview

Fixes L2 documentation versioning and upgrade guidance so operators follow the correct upgrade path and don’t hit avoidable onlyOwner reverts when interacting with the OnChainProposer.

Changes:

• Correct the CommonBridge l2GasLimit migration section to be v9 → v10 (and “From v10 onwards”).
• Update the vanilla deployment doc cross-reference to the corrected upgrades anchor.
• Add a Timelock ownership note clarifying OCP upgrades/admin actions must be executed via the Timelock.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.

File	Description
docs/l2/fundamentals/contracts.md	Adds Timelock ownership note for OCP and adjusts the RPC example placeholder.
docs/l2/deployment/vanilla.md	Fixes upgrades section anchor link to point at v9 → v10.
docs/l2/deployment/upgrades.md	Renames the upgrade section to v9 → v10 and updates the “from vX onwards” wording accordingly.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

This note contradicts the immediately preceding step that instructs calling upgradeToAndCall directly on <PROXY_ADDRESS>. Consider rewording/restructuring so it’s clear that direct upgradeToAndCall works only when the proxy owner is your EOA, but for OnChainProposer upgrades/admin actions you must execute the call via the Timelock (and point readers to the Timelock doc for how to encode/route the call).

[Copilot]

<L1_RPC_URL> is introduced here but isn’t defined anywhere else in this document, and this “upgrade the contracts” section isn’t clearly L1-specific. To avoid confusion, use a generic placeholder like <RPC_URL> (or explicitly <L1_RPC_URL> vs <L2_RPC_URL> with a short explanation) and keep it consistent with the rest of the steps/tools.

Suggested change

	curl <L1_RPC_URL> -d '{"jsonrpc": "2.0", "id": "1", "method": "eth_getStorageAt", "params": ["<PROXY_ADDRESS>", "0x360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc", "latest"]}'
	curl <RPC_URL> -d '{"jsonrpc": "2.0", "id": "1", "method": "eth_getStorageAt", "params": ["<PROXY_ADDRESS>", "0x360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc", "latest"]}'