feat: update upgrade process documentation and scripts

- Added new parameters to .env.example for Safe upgrade proposals.
- Modified package.json to streamline the upgrade submission script.
- Expanded MULTISIG_UPGRADE_GUIDE.md with detailed steps for proposing upgrades.
- Enhanced submit-upgrade-to-safe.mjs to load env and improve error messaging.

Made-with: Cursor

Author: ae2079

.env.example

@@ -11,8 +11,12 @@ CELO_RPC=
 OPTIMISM_RPC=
 POLYGON_RPC=
 
-# For auto-proposing upgrade to Safe (proposer must be a Safe owner)
+# For upgrade:submit-to-safe (proposer must be a Safe owner)
 SAFE_ADDRESS=
+PROXY_ADMIN_ADDRESS=
+PROXY_ADDRESS=
+NEW_IMPLEMENTATION_ADDRESS=
 PROPOSER_PRIVATE_KEY=
+SAFE_API_KEY=   # required: get at https://developer.safe.global
 
 ETHERSCAN_API_KEY=

docs/MULTISIG_UPGRADE_GUIDE.md

@@ -4,6 +4,71 @@ This guide is for signers of the **ProxyAdmin** multisig. It explains how to run
 
 ---
 
+## Steps to propose the transaction
+
+Choose one of two ways: **A) Submit from your machine** (script posts to Safe) or **B) Generate payload** then create the tx in the Safe UI.
+
+### Parameters and inputs you need
+
+| Parameter | Where to set | Description |
+|-----------|----------------|--------------|
+| **SAFE_ADDRESS** | `.env` or CLI | The multisig Safe address (owner of ProxyAdmin). |
+| **PROXY_ADMIN_ADDRESS** | `.env` or CLI | The ProxyAdmin contract address. |
+| **PROXY_ADDRESS** | `.env` or CLI | The DonationHandler proxy to upgrade. |
+| **NEW_IMPLEMENTATION_ADDRESS** | `.env` or CLI | The new implementation contract address (from `yarn deploy:implementation <chain>`). |
+| **PROPOSER_PRIVATE_KEY** (or **PROPOSER_PK**) | `.env` only | Private key of a Safe **owner** (used only for **Option A**). |
+| **&lt;CHAIN&gt;_RPC** | `.env` | RPC URL for the chain, e.g. `BASE_RPC`, `MAINNET_RPC`. |
+| **CHAIN** | CLI argument or `.env` | Chain name: `mainnet`, `base`, `arbitrum`, `optimism`, `polygon`, `gnosis`, `celo`, `sepolia`. |
+| **SAFE_API_KEY** | `.env` (optional) | Safe API key if you hit rate limits. |
+
+---
+
+### Option A — Submit proposal from your machine (recommended if you have proposer key)
+
+1. **Set in `.env`:**
+   - `SAFE_ADDRESS` = your multisig address  
+   - `PROXY_ADMIN_ADDRESS` = ProxyAdmin contract  
+   - `PROXY_ADDRESS` = DonationHandler proxy  
+   - `NEW_IMPLEMENTATION_ADDRESS` = new implementation (from deploy)  
+   - `PROPOSER_PRIVATE_KEY` or `PROPOSER_PK` = private key of **one Safe owner**  
+   - `<CHAIN>_RPC` = RPC URL (e.g. `BASE_RPC`, `MAINNET_RPC`)
+
+2. **Run (from repo root):**
+   ```bash
+   yarn upgrade:submit-to-safe base
+   ```
+   Use the correct chain instead of `base` if needed (e.g. `mainnet`, `arbitrum`).
+
+3. The script will create the upgrade tx, sign it with the proposer key, and submit it to the Safe Transaction Service. Other signers see it in the Safe UI and can confirm/execute.
+
+---
+
+### Option B — Generate payload, then create the tx in Safe UI
+
+1. **Set in `.env` (or pass as CLI args):**
+   - `PROXY_ADMIN_ADDRESS`  
+   - `PROXY_ADDRESS`  
+   - `NEW_IMPLEMENTATION_ADDRESS`  
+   Optional: `SAFE_ADDRESS`, `CHAIN` (for the printed Safe link).
+
+2. **Generate the payload:**
+   ```bash
+   yarn upgrade:generate-payload 0x<ProxyAdmin> 0x<Proxy> 0x<NewImplementation>
+   # Or with env set: yarn upgrade:generate-payload
+   ```
+
+3. **Use the output:**
+   - Open the printed Safe link (or [app.safe.global](https://app.safe.global)).
+   - **New transaction** → **Contract interaction** (or **Apps** → **Transaction Builder**).
+   - **To:** paste `PROXY_ADMIN_ADDRESS`.
+   - **Data:** paste the hex **Data (calldata)** from the script output, or use the function `upgrade(address,address)` with `proxy` = `PROXY_ADDRESS` and `implementation` = `NEW_IMPLEMENTATION_ADDRESS`.
+   - **Value:** 0.
+   - **Create transaction** so other signers can sign and execute.
+
+   Alternatively, in Safe go to **Apps** → **Transaction Builder** → **Import** and select the generated `upgrade-payload.json`.
+
+---
+
 ## Proposing the transaction (for the proposer)
 
 If you have the three addresses (ProxyAdmin, proxy, new implementation), you can **generate** the exact transaction payload and a Safe Transaction Builder–ready JSON:

package.json

@@ -10,18 +10,13 @@
   "license": "MIT",
   "author": "Wonderland",
   "scripts": {
+    "addresses": "./scripts/get-proxy-addresses.sh",
     "build": "forge build",
     "build:optimized": "FOUNDRY_PROFILE=optimized forge build",
     "coverage": "forge coverage --ir-minimum --report summary --report lcov --match-path 'test/unit/*'",
+    "deploy:implementation": "./scripts/deploy-implementation.sh",
     "deploy:mainnet": "bash -c 'source .env && forge script Deploy --rpc-url $MAINNET_RPC --account $MAINNET_DEPLOYER_NAME --broadcast --verify --chain mainnet -vvvvv'",
     "deploy:sepolia": "bash -c 'source .env && forge script script/DeployDonationHandler.s.sol:DeployDonationHandler --rpc-url $SEPOLIA_RPC --broadcast --verify -vvvv'",
-    "addresses": "./scripts/get-proxy-addresses.sh",
-    "upgrade:mainnet": "bash -c 'source .env && forge script script/UpgradeDonationHandler.s.sol:UpgradeDonationHandler --rpc-url $MAINNET_RPC --broadcast --verify -vvvv'",
-    "upgrade:mainnet:simulate": "bash -c 'source .env && forge script script/UpgradeDonationHandler.s.sol:UpgradeDonationHandler --fork-url $MAINNET_RPC -vvvv'",
-    "upgrade:sepolia": "bash -c 'source .env && forge script script/UpgradeDonationHandler.s.sol:UpgradeDonationHandler --rpc-url $SEPOLIA_RPC --broadcast --verify -vvvv'",
-    "deploy:implementation": "./scripts/deploy-implementation.sh",
-    "upgrade:generate-payload": "./scripts/generate-upgrade-payload.sh",
-    "upgrade:submit-to-safe": "bash -c 'source .env && node scripts/submit-upgrade-to-safe.mjs \"$@\"' bash",
     "lint:check": "yarn lint:sol && forge fmt --check",
     "lint:fix": "sort-package-json && forge fmt && yarn lint:sol --fix",
     "lint:natspec": "npx @defi-wonderland/natspec-smells --config natspec-smells.config.js",
@@ -32,26 +27,32 @@
     "test:integration": "forge test --match-contract Integration -vvv",
     "test:symbolic": "halmos",
     "test:unit": "forge test --match-contract Unit -vvv",
-    "test:unit:deep": "FOUNDRY_FUZZ_RUNS=5000 yarn test:unit"
+    "test:unit:deep": "FOUNDRY_FUZZ_RUNS=5000 yarn test:unit",
+    "upgrade:generate-payload": "./scripts/generate-upgrade-payload.sh",
+    "upgrade:mainnet": "bash -c 'source .env && forge script script/UpgradeDonationHandler.s.sol:UpgradeDonationHandler --rpc-url $MAINNET_RPC --broadcast --verify -vvvv'",
+    "upgrade:mainnet:simulate": "bash -c 'source .env && forge script script/UpgradeDonationHandler.s.sol:UpgradeDonationHandler --fork-url $MAINNET_RPC -vvvv'",
+    "upgrade:sepolia": "bash -c 'source .env && forge script script/UpgradeDonationHandler.s.sol:UpgradeDonationHandler --rpc-url $SEPOLIA_RPC --broadcast --verify -vvvv'",
+    "upgrade:submit-to-safe": "node scripts/submit-upgrade-to-safe.mjs"
   },
   "lint-staged": {
     "*.{js,css,md,ts,sol}": "forge fmt",
     "(src|test|script)/**/*.sol": "yarn lint:sol",
     "package.json": "sort-package-json"
   },
   "devDependencies": {
-    "@safe-global/api-kit": "^4.0.0",
-    "@safe-global/protocol-kit": "^4.0.0",
-    "@safe-global/types-kit": "^4.0.0",
     "@commitlint/cli": "19.3.0",
     "@commitlint/config-conventional": "19.2.2",
     "@defi-wonderland/natspec-smells": "1.1.6",
-    "forge-std": "github:foundry-rs/forge-std#1.9.2",
+    "@safe-global/api-kit": "^4.0.0",
+    "@safe-global/protocol-kit": "^4.0.0",
+    "@safe-global/types-kit": "^3.0.0",
+    "dotenv": "^16.4.5",
+    "ethers": "^6.13.0",
+    "forge-std": "github:foundry-rs/forge-std#v1.9.2",
     "halmos-cheatcodes": "github:a16z/halmos-cheatcodes#c0d8655",
     "husky": ">=9",
     "lint-staged": ">=10",
     "solhint-community": "4.0.1",
-    "sort-package-json": "2.10.0",
-    "ethers": "^6.13.0"
+    "sort-package-json": "2.10.0"
   }
 }