Circular import between `TransparentUpgradeableProxy` and `ProxyAdmin`

[tinom9]

TransparentUpgradeableProxy.sol and ProxyAdmin.sol form a circular import because ITransparentUpgradeableProxy is defined in the same file as TransparentUpgradeableProxy. Hardhat flatten fails with HH603 on either file.

💻 Environment

• @openzeppelin/contracts ≥ 5.0 (introduced in #4382)
• Hardhat 2.28.5 (HH603); Hardhat 3 has the same limitation (HHE602 / FLATTEN_CYCLIC_DEPENDENCY)

📝 Details

ProxyAdmin imports the interface from the proxy file:

import {ITransparentUpgradeableProxy} from "./TransparentUpgradeableProxy.sol";

Since v5, TransparentUpgradeableProxy also imports ProxyAdmin:

import {ProxyAdmin} from "./ProxyAdmin.sol";

This creates a cycle:

ProxyAdmin.sol
  → ITransparentUpgradeableProxy (in TransparentUpgradeableProxy.sol)
    → ProxyAdmin.sol

Solidity and forge flatten accept this. Hardhat does not, so npx hardhat flatten on either file fails with HH603. That blocks single-file flattening for verification workflows.

Extracting ITransparentUpgradeableProxy to its own file removes the cycle (see draft implementation in #6653), although breaks for code that currently imports the interface from TransparentUpgradeableProxy.sol.

🔢 Code to reproduce bug

npx hardhat flatten contracts/proxy/transparent/TransparentUpgradeableProxy.sol
npx hardhat flatten contracts/proxy/transparent/ProxyAdmin.sol

Error HH603: Hardhat flatten doesn't support cyclic dependencies.

[ernestognw]

Hey @tinom9, thanks for bringing it up.

So the reason we kept this interface in the same file as the TransparentUpgradeableProxy is because the interface is really meaningless to any other than the ProxyAdmin, so it doesn't make sense to create a file for it and pollute the library.

Although the decision was deliberate, I see the circular import issue is veridic. I'm just wondering if we could find a way to workaround it without creating the interface file

[tinom9]

An alternative is moving ITransparentUpgradeableProxy to ProxyAdmin.sol, but that feels backwards.

If the current direction is to lock down TransparentUpgradeableProxy rather than allowing composability (see #5855 (comment)), it may be fine to just acknowledge the issue, given that there are alternative ways to flatten.

Otherwise I'd consider the new interface file.