Skip to content

docs: add upgrade testing guide with block number rotation process#301

Open
okwn wants to merge 3 commits into
base:mainfrom
okwn:contrib/contracts/block-num-rotation-doc
Open

docs: add upgrade testing guide with block number rotation process#301
okwn wants to merge 3 commits into
base:mainfrom
okwn:contrib/contracts/block-num-rotation-doc

Conversation

@okwn
Copy link
Copy Markdown

@okwn okwn commented May 22, 2026

Summary

Adds a new docs/upgrade-testing.md that documents the upgrade testing process for the Base contracts repository.

What it covers

  • Overview of why pinned block numbers are used for upgrade testing
  • Block number configuration — where sepoliaBlockNumber and mainnetBlockNumber are set in justfile
  • How to run upgrade testsjust test-fork sepolia, just test-fork mainnet, just coverage-upgrade
  • When and how to update block numbers — finding current block via cast block-number, updating justfile, verifying tests pass
  • CI staleness enforcement — the 90-day rule that warns when block numbers are stale

Why this matters

The backlog identified that "no documented process exists for when/how to update sepoliaBlockNumber / mainnetBlockNumber". Without documented process, block numbers go stale and tests run against outdated chain state, missing potential upgrade issues.

Why Safe

  • Pure documentation — no production code changed
  • Follows the existing CONTRIBUTING.md pattern
  • Does not modify any behavior, only adds guidance

okwn added 3 commits May 22, 2026 08:54
- Add coverage check using 'just coverage-lcov' with 70% threshold
- Add semgrep as blocking step via returntocorp/semgrep-action
- Fix semgrep justfile target to use ./src instead of non-existent path
Add invariant tests for OptimismPortal2 covering:
- minimumGasLimit is never zero for any calldata size
- portal paused state is consistent with system config
- portal has minimum balance (sanity check)

These invariants verify critical security properties of the portal's
configuration and access controls. The tests follow the pattern of
existing invariant tests in test/invariants/ (SafeCall, CrossDomainMessenger).

Part of effort to increase invariant test coverage for the bridge
protocol which currently has only 2 invariant test files.
@cb-heimdall
Copy link
Copy Markdown
Collaborator

🟡 Heimdall Review Status

Requirement Status More Info
Reviews 🟡 0/1
Denominator calculation
Show calculation
1 if user is bot 0
1 if user is external 0
2 if repo is sensitive 0
From .codeflow.yml 1
Additional review requirements
Show calculation
Max 0
0
From CODEOWNERS 0
Global minimum 0
Max 1
1
1 if commit is unverified 1
Sum 2

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants