Update transpilation process

[Amxx]

Use transpiler v0.4.1

• Initializable imports (for the transpiled contracts) point to the peer project. In practice, that means that upgradeable contract will import @openzeppelin/contracts/proxy/utils/Initializable.sol instead of a relative (local) import.
• Initializable and UUPS upgradeable are no longer transpiled. The transpiler removes them.
• Add "alias" files that import Initializable and UUPSUpgradeable from the peer project. This prevents breaking projects that import these files from the upgradeable repo. The alias will serve them the contract implemented in the peer project.

[changeset-bot]

⚠️ No Changeset found

Latest commit: 4c473b5

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	npm/​@​openzeppelin/​upgrade-safe-transpiler@​0.3.33 ⏵ 0.4.1	+1		+2	+10

View full report

[coderabbitai]

Walkthrough

This change updates documentation and tooling: CHANGELOG.md notes that Initializable and UUPSUpgradeable are no longer transpiled into @openzeppelin/contracts-upgradeable and removes two previously listed breaking-change entries. UUPSUpgradeable.sol gains a NatSpec tag "@Custom:stateless" with no code or API changes. package.json bumps devDependency "@openzeppelin/upgrade-safe-transpiler" from ^0.3.32 to ^0.4.0. scripts/upgradeable/transpile.sh refines exclusion patterns to target only contracts/proxy/**/Proxy.sol and contracts/proxy/beacon/UpgradeableBeacon.sol, and updates an explanatory comment. No exported/public declarations are altered.

Pre-merge checks and finishing touches

❌ Failed checks (1 inconclusive)

Check name	Status	Explanation	Resolution
Description Check	❓ Inconclusive	No pull request description was provided by the author, so there is no explicit summary of intent, rationale, or migration notes; although the diff shows transpilation-related changes, the absence of a description leaves reviewer intent and any required follow-up unclear. Because the description is missing, this check is inconclusive.	Ask the author to add a brief description summarizing the objective, the key files changed (notably scripts/transpile.sh and package.json), any breaking effects or migration steps, and the reason for the changelog update so reviewers have sufficient context before merging.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title Check	✅ Passed	The PR title "Update transpilation process" accurately and concisely summarizes the primary change shown in the diff (transpilation script adjustments and an associated transpiler devDependency bump) and is directly related to the changeset without unnecessary noise. It is clear and specific enough for a teammate scanning history to understand the main intent.
Docstring Coverage	✅ Passed	No functions found in the changes. Docstring coverage check skipped.

✨ Finishing touches

• 📝 Generate Docstrings

🧪 Generate unit tests

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch next/transpile

Tip

👮 Agentic pre-merge checks are now available in preview!

Pro plan users can now enable pre-merge checks in their settings to enforce checklists before merging PRs.

• Built-in checks – Quickly apply ready-made checks to enforce title conventions, require pull request descriptions that follow templates, validate linked issues for compliance, and more.
• Custom agentic checks – Define your own rules using CodeRabbit’s advanced agentic capabilities to enforce organization-specific policies and workflows. For example, you can instruct CodeRabbit’s agent to verify that API documentation is updated whenever API schema files are modified in a PR. Note: Upto 5 custom checks are currently allowed during the preview period. Pricing for this feature will be announced in a few weeks.

Please see the documentation for more information.

Example:

reviews:
  pre_merge_checks:
    custom_checks:
      - name: "Undocumented Breaking Changes"
        mode: "warning"
        instructions: |
          Pass/fail criteria: All breaking changes to public APIs, CLI flags, environment variables, configuration keys, database schemas, or HTTP/GraphQL endpoints must be documented in the "Breaking Change" section of the PR description and in CHANGELOG.md. Exclude purely internal or private changes (e.g., code not exported from package entry points or explicitly marked as internal).

Please share your feedback with us on this Discord post.

---

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

• X
• Mastodon
• Reddit
• LinkedIn

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

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

CHANGELOG.md (1)

9-9: Clarify migration with an import example.

The note is good; add a short snippet to reduce user friction.

- - `Initializable` and `UUPSUpgradeable` are no longer transpiled, and are now absent from the `@openzeppelin/contracts-upgradeable` package. Imports must be updated to get these files from `@openzeppelin/contracts` instead.
+ - `Initializable` and `UUPSUpgradeable` are no longer transpiled, and are now absent from the `@openzeppelin/contracts-upgradeable` package. Import them from `@openzeppelin/contracts` instead. Example:
+
+   ```diff
+   - import { Initializable } from "@openzeppelin/contracts-upgradeable/proxy/utils/Initializable.sol";
+   - import { UUPSUpgradeable } from "@openzeppelin/contracts-upgradeable/proxy/utils/UUPSUpgradeable.sol";
+   + import { Initializable } from "@openzeppelin/contracts/proxy/utils/Initializable.sol";
+   + import { UUPSUpgradeable } from "@openzeppelin/contracts/proxy/utils/UUPSUpgradeable.sol";
+   ```

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between e2e9908 and 258e110.

⛔ Files ignored due to path filters (1)

• package-lock.json is excluded by !**/package-lock.json

📒 Files selected for processing (4)

• CHANGELOG.md (1 hunks)
• contracts/proxy/utils/UUPSUpgradeable.sol (1 hunks)
• package.json (1 hunks)
• scripts/upgradeable/transpile.sh (2 hunks)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (4)

• GitHub Check: coverage
• GitHub Check: tests-upgradeable
• GitHub Check: tests
• GitHub Check: tests-foundry

🔇 Additional comments (4)

contracts/proxy/utils/UUPSUpgradeable.sol (1)

18-19: NatSpec “stateless” tag added — LGTM.

No functional change; consistent with documentation patterns. Ensure docs toolchain surfaces custom tags.

If using solidity-docgen, confirm @Custom:stateless is preserved in generated docs with current config.

scripts/upgradeable/transpile.sh (2)

26-26: Comment tweak OK.

The updated description matches the narrower -x globs.

---

31-44: Add CI guard: fail if transpiler output contains Initializable or UUPSUpgradeable

Repo search found only originals at contracts/proxy/utils/Initializable.sol and contracts/proxy/utils/UUPSUpgradeable.sol and no contracts-upgradeable outputs — add a CI job that runs the transpiler and fails if any generated files named Initializable.sol or UUPSUpgradeable.sol appear (e.g., check the transpile output dir).

package.json (1)

65-65: Transpiler 0.4.0 not published — confirm dependency and CLI flags.
npm shows @openzeppelin/upgrade-safe-transpiler latest published is 0.3.33; no 0.4.0 release exists to verify -i/-x/-N/-q behavior.
Either change package.json to a published version (e.g., "^0.3.33") or provide the private 0.4.0 package.json/CHANGELOG or repo/PR so the CLI flags can be checked.
File: package.json (line 65)

[Amxx]

Note: the storage layout breaking in checks/tests-upgradeable is expected

[ernestognw]

In regards to ERC721Holder and ERC1155Holder, we can also keep them stateless and provide a concrete instruction to use the ones from @openzeppelin/contracts instead of upgradeables. I see it was removed, what's the rationale?

[Amxx]

In regards to ERC721Holder and ERC1155Holder, we can also keep them stateless and provide a concrete instruction to use the ones from @openzeppelin/contracts instead of upgradeables. I see it was removed, what's the rationale?

The rational was to minimize the breaking change, and delay that for later.

One important thing to note is that ERC721Holder and ERC1155Holder are not in conflict with their Upgreable counterpart. The Upgradeable versions have a different name, and you can import both without getting into symbol colision.

Do we want to remove them now ?

[ernestognw]

Ah I see that this PR is about stop transpiling (or porting) UUPSUpgradeable and Initializable over to upgradeable contracts and not necessarily about being strict on all the contracts we should transpile.

I would consider adding the @custom:stateless to ERC721Holder and ERC1155Holder in another PR with a deprecation notice as well. 5.5 seems like the right fit for doing this, though.