Improve upgrade safety and deployment guardrail workflows

[franrolotti]

Context

#119 introduces upgrade safety validation and deploy/upgrade guardrail scripts.
This follow-up issue intends to track and improve these workflows.

Objective

Improve reliability, clarity, and operational safety of upgrade validation and deployment scripts used in CI and release processes.

Scope

• Upgrade safety CI workflow (.github/workflows/upgrade-safety-check.yml)
• Upgrade safety script (scripts/check_upgrade_safety.sh)
• Deploy/upgrade scripts:
  • script/UpgradeValidate.s.sol
  • script/UpgradeExecute.s.sol
  • script/UpgradePostValidate.s.sol

Proposed improvements

• Standardize workflow naming, job naming, and step labeling for clarity.
• Ensure all script/tool invocations are CI-safe and non-interactive.
• Improve script ergonomics:
  • clearer errors
  • stronger precondition checks
  • better logging for operators
• Revisit warning handling strategy (avoid permanent suppression where possible).
• Document expected env vars and recommended execution sequence for upgrades.
• Verify branch/reference assumptions are explicit and consistent (dev baseline vs PR HEAD).

Acceptance criteria

• CI upgrade safety workflow is stable on PRs to dev.
• Deploy/upgrade scripts have clear failure modes and operator guidance.
• Validation flow is reproducible locally and in CI.
• Documentation covers end-to-end upgrade validation + execution + post-validation steps.

[RonTuretzky]

etherform literally solves this though?

[franrolotti]

@RonTuretzky yes, and i'm now seeing the importance of etherform for us... do you think we should put an effort to ship a working version of etherform now and add it to this PR?

I did this PR because I needed them for the deployment and upgrading for the testing rounds

[RonTuretzky]

@hudsonhrh you mentioned that etherform is ready now?

[hudsonhrh]

@hudsonhrh you mentioned that etherform is ready now?

for certain use cases yes. is cross chain support needed? also block scout verification is still inconsistent. wouldn't say it's fully ready needs some work. will make some progress on it monday but lmk what the needs are for this repo and i can make sure its ready

[franrolotti]

@hudsonhrh @RonTuretzky

I had AI do a review of saving-circles against etherform, and the main takeaway was that the integration looks directionally compatible, but not fully ready yet for this repo’s actual needs.

The biggest point is that for saving-circles the main requirement is not fresh deployments, it’s upgrades of already deployed transparent proxies. This branch already has a pretty clear upgrade flow in-repo: validate the target upgrade, execute ProxyAdmin.upgradeAndCall, then do post-upgrade validation. So the AI’s view was that etherform would need to support that live upgrade workflow well, not just “deploy contracts from CI”.

It also called out a few repo-specific needs:

• support for the env/config this repo uses around upgrades, like proxy address, expected admin owner, current implementation, new implementation, optional calldata, viewer address
• support for Node/Yarn install in workflows, since this repo depends on node_modules
• upgrade-safety validation that matches this repo’s current OZ build-info based approach, not only a baseline snapshot model
• better handling of Blockscout / artifact parsing

On the cross-chain question, i don't think it's the main issue here. The core need is safe upgrades of existing deployments. Fresh proxy/full-stack deployments are still useful as a secondary path, but not the main operational one right now.

So overall the AI’s conclusion was: etherform seems close enough that it could be adapted for saving-circles, but it’s probably not fully ready for this repo until the upgrade path is a first-class workflow.

Does that line up with how you’re seeing it, or is the AI missing something important?

[RonTuretzky]

@hudsonhrh @RonTuretzky

I had AI do a review of saving-circles against etherform, and the main takeaway was that the integration looks directionally compatible, but not fully ready yet for this repo’s actual needs.

The biggest point is that for saving-circles the main requirement is not fresh deployments, it’s upgrades of already deployed transparent proxies. This branch already has a pretty clear upgrade flow in-repo: validate the target upgrade, execute ProxyAdmin.upgradeAndCall, then do post-upgrade validation. So the AI’s view was that etherform would need to support that live upgrade workflow well, not just “deploy contracts from CI”.

It also called out a few repo-specific needs:

• support for the env/config this repo uses around upgrades, like proxy address, expected admin owner, current implementation, new implementation, optional calldata, viewer address
• support for Node/Yarn install in workflows, since this repo depends on node_modules
• upgrade-safety validation that matches this repo’s current OZ build-info based approach, not only a baseline snapshot model
• better handling of Blockscout / artifact parsing

On the cross-chain question, i don't think it's the main issue here. The core need is safe upgrades of existing deployments. Fresh proxy/full-stack deployments are still useful as a secondary path, but not the main operational one right now.

So overall the AI’s conclusion was: etherform seems close enough that it could be adapted for saving-circles, but it’s probably not fully ready for this repo until the upgrade path is a first-class workflow.

Does that line up with how you’re seeing it, or is the AI missing something important?

Etherform was expressly created for this repo and safety net. It would have been better to do this work on that repo so that it could be reused. I would recommend doing a fresh deploy, accomdating for proxy admins and yarn compilation etc in etherform rather than here because we're gonna run into duplicate work on safety net with these issues. If you want to go quickly then don't use etherform.