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

README.md

@@ -41,6 +41,8 @@ And when you call `upgradeProxy`:
 
 The Hardhat plugin keeps track of all the implementation contracts you have deployed in an `.openzeppelin` folder in the project root. You will find one file per network there. It is advised that you commit to source control the files for all networks except the development ones (you may see them as `.openzeppelin/unknown-*.json`).
 
+Note that the Hardhat plugin deploys proxy contracts using [precompiled bytecodes](https://docs.openzeppelin.com/upgrades-plugins/faq#precompiled-proxy-contracts) from the `@openzeppelin/upgrades-core` package, which are compiled independently from your project's Solidity compiler version.
+
 The Foundry plugin does not keep track of implementation contracts, but requires you to [define reference contracts](https://github.com/OpenZeppelin/openzeppelin-foundry-upgrades?tab=readme-ov-file#before-running) in order to validate new versions of implementations for upgrade safety.
 
 ## Proxy patterns

docs/modules/ROOT/pages/faq.adoc

@@ -1,6 +1,19 @@
 [[frequently-asked-questions]]
 = Frequently Asked Questions
 
+[[precompiled-proxy-contracts]]
+== What compiler version is used for proxy contracts?
+
+The Hardhat Upgrades plugin deploys proxy contracts using **precompiled bytecodes** that are packaged in the `@openzeppelin/upgrades-core` NPM package. This means:
+
+* **The proxy compiler version is independent of your project's compiler version.** Even if your `hardhat.config.js` specifies a different Solidity version, the proxy contracts (such as `ERC1967Proxy`, `TransparentUpgradeableProxy`, `BeaconProxy`, and `UpgradeableBeacon`) are deployed using the bytecode that was precompiled with the version of Solidity included in `@openzeppelin/upgrades-core`. This does _not_ affect your implementation contracts, which are compiled with your project's configured compiler.
+
+* **Different versions of `@openzeppelin/upgrades-core` may use different compiler versions** and different versions of the proxy contracts from https://docs.openzeppelin.com/contracts[OpenZeppelin Contracts]. Upgrading `@openzeppelin/upgrades-core` or `@openzeppelin/hardhat-upgrades` may change the precompiled proxy bytecodes.
+
+* **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 the above behavior is specific to the Hardhat plugin only.
+
 [[is-it-safe-to-upgrade-a-contract-compiled-with-a-version-of-solidity-to-another-compiled-with-a-different-version]]
 == Can I change Solidity compiler versions when upgrading?
 

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

@@ -46,6 +46,8 @@ main();
 
 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.
+
 Then, in another script, you can use the `upgradeProxy` function to upgrade the deployed instance to a new version. The new version can be a different contract (such as `BoxV2`), or you can just modify the existing `Box` contract and recompile it - the plugin will note it changed.
 
 [source,js]

docs/modules/ROOT/pages/index.adoc

@@ -39,6 +39,8 @@ And when you call `upgradeProxy`:
 
 The Hardhat plugin keeps track of all the implementation contracts you have deployed in an `.openzeppelin` folder in the project root, as well as the proxy admin. You will find one file per network there. It is advised that you commit to source control the files for all networks except the development ones (you may see them as `.openzeppelin/unknown-*.json`).
 
+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.
+
 The Foundry plugin does not keep track of implementation contracts, but requires you to https://github.com/OpenZeppelin/openzeppelin-foundry-upgrades?tab=readme-ov-file#before-running[define reference contracts] in order to validate new versions of implementations for upgrade safety.
 
 [[proxy-patterns]]

packages/plugin-hardhat/README.md

@@ -44,6 +44,8 @@ main();
 
 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 [Precompiled proxy contracts](https://docs.openzeppelin.com/upgrades-plugins/faq#precompiled-proxy-contracts) for details.
+
 Then, in another script, you can use the `upgradeProxy` function to upgrade the deployed instance to a new version. The new version can be a different contract (such as `BoxV2`), or you can just modify the existing `Box` contract and recompile it - the plugin will note it changed.
 
 ```js