docs: document use of precompiled proxies and compiler version for proxies by jose-blockchain · Pull Request #1210 · OpenZeppelin/openzeppelin-upgrades

jose-blockchain · 2026-02-16T20:40:54Z

Summary

Add new FAQ entry explaining that the Hardhat Upgrades plugin deploys proxy contracts using precompiled bytecodes from @openzeppelin/upgrades-core, independent of the user's project compiler version
Add cross-referenced notes in the Overview (index.adoc) and Hardhat usage guide (hardhat-upgrades.adoc) pointing to the new FAQ entry
Clarify that different versions of upgrades-core may ship different proxy compiler versions and OpenZeppelin Contracts versions
Note that consistent package versions should be used across chains for reproducible bytecodes and source code verification

Files changed:

docs/modules/ROOT/pages/faq.adoc -- new FAQ section "What compiler version is used for proxy contracts?"
docs/modules/ROOT/pages/index.adoc -- note in "How the plugins work" step 3
docs/modules/ROOT/pages/hardhat-upgrades.adoc -- NOTE admonition after deployProxy example

Summary by CodeRabbit

Documentation
- Added FAQ section clarifying how proxy contracts are compiled in the Hardhat Upgrades plugin
- Updated deployment documentation to note that proxy contracts use precompiled bytecodes from the upgrades package, independent of your project's Solidity version

…oxies Adds FAQ entry explaining that the Hardhat Upgrades plugin deploys proxy contracts using precompiled bytecodes from @openzeppelin/upgrades-core, independently of the user's project compiler version. Adds cross-references in the Overview and Hardhat usage guide. Closes OpenZeppelin#1187

coderabbitai · 2026-02-16T20:41:12Z

Important

Review skipped

Auto incremental reviews are disabled on this repository.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

🔍 Trigger review

Walkthrough

Documentation updates across three files to clarify that the Hardhat Upgrades plugin uses precompiled proxy bytecodes from @openzeppelin/upgrades-core, independent of the user's project Solidity compiler version, with guidance for consistent deployments across chains.

Changes

Cohort / File(s)	Summary
Documentation Updates `docs/modules/ROOT/pages/faq.adoc`, `docs/modules/ROOT/pages/hardhat-upgrades.adoc`, `docs/modules/ROOT/pages/index.adoc`	Added clarifications explaining that proxy contracts use precompiled bytecodes from `@openzeppelin/upgrades-core` (independent of project compiler version), guidance for consistent deployments across chains, and notes about version dependencies.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~8 minutes

Poem

🐰 Hopping through docs with glee so bright,
Precompiled proxies now in sight!
No compiler conflicts to untangle today,
Clear guidance for upgrades—hip hip hooray! 🎉

🚥 Pre-merge checks | ✅ 6

✅ Passed checks (6 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and specifically describes the main change: documenting precompiled proxies and compiler version handling in the Hardhat Upgrades plugin documentation.
Linked Issues check	✅ Passed	All three objectives from issue `#1187` are addressed: precompiled bytecode independence documented [`#1187`], version differences explained [`#1187`], and guidance for consistent versioning provided [`#1187`].
Out of Scope Changes check	✅ Passed	All changes are within scope—three documentation files updated to address issue `#1187` requirements with no unrelated modifications.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Merge Conflict Detection	✅ Passed	✅ No merge conflicts detected when merging into `master`

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Post copyable unit tests in a comment

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

ericglau

Thanks for the PR! A few comments.

ericglau · 2026-02-17T20:56:41Z

docs/modules/ROOT/pages/hardhat-upgrades.adoc


 This will automatically check that the `Box` contract is upgrade-safe, deploy an implementation contract for the `Box` contract (unless there is one already from a previous deployment), create a proxy (along with a proxy admin if needed), and initialize it by calling `initialize(42)`.

+NOTE: The proxy contract itself is deployed using precompiled bytecodes from `@openzeppelin/upgrades-core`, not compiled with your project's Solidity compiler. See xref:faq.adoc#precompiled-proxy-contracts[Precompiled proxy contracts] for details.


Can you also add the same note in https://github.com/OpenZeppelin/openzeppelin-upgrades/blob/master/packages/plugin-hardhat/README.md (it is a mostly a duplicate of this file, but is used as a readme for this subfolder in the GitHub repo)

done @ericglau thanks for the comment.

ericglau · 2026-02-17T20:59:17Z

docs/modules/ROOT/pages/index.adoc

 2. Deploys the xref:faq.adoc#what-is-an-implementation-contract[implementation contract]. Note that the Hardhat plugin first checks if there is an implementation contract deployed with the same bytecode, and skips this step if one is already deployed.

-3. Creates and initializes the proxy contract, along with a xref:faq.adoc#what-is-a-proxy-admin[proxy admin] (if needed).
+3. Creates and initializes the proxy contract, along with a xref:faq.adoc#what-is-a-proxy-admin[proxy admin] (if needed). Note that the Hardhat plugin deploys proxy contracts using xref:faq.adoc#precompiled-proxy-contracts[precompiled bytecodes] from the `@openzeppelin/upgrades-core` package, which are compiled independently from your project's Solidity compiler version.


I would suggest moving this lower to around line 41, so that it fits into the existing paragraphs about the differences between the Hardhat and Foundry Upgrades plugins.

Can you also make a similar change in https://github.com/OpenZeppelin/openzeppelin-upgrades/blob/master/README.md ?

done @ericglau thanks for the comment.

ericglau · 2026-02-17T21:00:24Z

docs/modules/ROOT/pages/faq.adoc

+
+* **For consistent proxy bytecodes across chains**, you should use the same versions of `@openzeppelin/hardhat-upgrades` and `@openzeppelin/upgrades-core` for all deployments. This is particularly important for **source code verification**, since the verification process depends on the exact compiler version and settings used to produce the deployed bytecode.
+
+NOTE: The Foundry Upgrades library (https://github.com/OpenZeppelin/openzeppelin-foundry-upgrades[`openzeppelin-foundry-upgrades`]) compiles proxy contracts as part of the project's build process using the project's own compiler configuration, so this behavior is specific to the Hardhat plugin.


I would clarify this as follows, since currently it is a bit ambiguous:

Suggested change

NOTE: The Foundry Upgrades library (https://github.com/OpenZeppelin/openzeppelin-foundry-upgrades[`openzeppelin-foundry-upgrades`]) compiles proxy contracts as part of the project's build process using the project's own compiler configuration, so this behavior is specific to the Hardhat plugin.

NOTE: The Foundry Upgrades library (https://github.com/OpenZeppelin/openzeppelin-foundry-upgrades[`openzeppelin-foundry-upgrades`]) compiles proxy contracts as part of the project's build process using the project's own compiler configuration, so the above behavior is specific to the Hardhat plugin only.

done @ericglau thanks for the comment.

…mment

ericglau reviewed Feb 17, 2026

View reviewed changes

jose-blockchain added 3 commits February 18, 2026 07:55

index.adoc review comment

edc1a1e

faq.adoc review comment

e022782

hardhat-upgrades.adoc and packages/plugin-hardhat/README.md review co…

ecbf335

…mment

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: document use of precompiled proxies and compiler version for proxies#1210

docs: document use of precompiled proxies and compiler version for proxies#1210
jose-blockchain wants to merge 4 commits intoOpenZeppelin:masterfrom
jose-blockchain:docs

jose-blockchain commented Feb 16, 2026 •

edited by coderabbitai bot

Loading

Uh oh!

coderabbitai bot commented Feb 16, 2026 •

edited

Loading

Review skipped

Uh oh!

ericglau left a comment

Uh oh!

ericglau Feb 17, 2026

Uh oh!

jose-blockchain Feb 18, 2026

Uh oh!

ericglau Feb 17, 2026 •

edited

Loading

Uh oh!

jose-blockchain Feb 18, 2026

Uh oh!

ericglau Feb 17, 2026

Uh oh!

jose-blockchain Feb 18, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants


		This will automatically check that the `Box` contract is upgrade-safe, deploy an implementation contract for the `Box` contract (unless there is one already from a previous deployment), create a proxy (along with a proxy admin if needed), and initialize it by calling `initialize(42)`.

		NOTE: The proxy contract itself is deployed using precompiled bytecodes from `@openzeppelin/upgrades-core`, not compiled with your project's Solidity compiler. See xref:faq.adoc#precompiled-proxy-contracts[Precompiled proxy contracts] for details.


		* For consistent proxy bytecodes across chains, you should use the same versions of `@openzeppelin/hardhat-upgrades` and `@openzeppelin/upgrades-core` for all deployments. This is particularly important for source code verification, since the verification process depends on the exact compiler version and settings used to produce the deployed bytecode.

		NOTE: The Foundry Upgrades library (https://github.com/OpenZeppelin/openzeppelin-foundry-upgrades[`openzeppelin-foundry-upgrades`]) compiles proxy contracts as part of the project's build process using the project's own compiler configuration, so this behavior is specific to the Hardhat plugin.

Conversation

jose-blockchain commented Feb 16, 2026 • edited by coderabbitai bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Summary by CodeRabbit

Uh oh!

coderabbitai bot commented Feb 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review skipped

Walkthrough

Changes

Estimated code review effort

Poem

Uh oh!

ericglau left a comment

Choose a reason for hiding this comment

Uh oh!

ericglau Feb 17, 2026

Choose a reason for hiding this comment

Uh oh!

jose-blockchain Feb 18, 2026

Choose a reason for hiding this comment

Uh oh!

ericglau Feb 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jose-blockchain Feb 18, 2026

Choose a reason for hiding this comment

Uh oh!

ericglau Feb 17, 2026

Choose a reason for hiding this comment

Uh oh!

jose-blockchain Feb 18, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

jose-blockchain commented Feb 16, 2026 •

edited by coderabbitai bot

Loading

coderabbitai bot commented Feb 16, 2026 •

edited

Loading

ericglau Feb 17, 2026 •

edited

Loading