refactor: rename scripts with hierarchical prefixes

.github/scripts/create-upgrade-announcement.js

@@ -5,27 +5,7 @@
  * Generates a release issue that combines user-facing upgrade information
  * with a release engineer checklist (similar to Lotus release issues).
  *
- * Usage:
- *   node create-upgrade-announcement.js [options]
- *
- * Options:
- *   --dry-run       Output issue text without creating an issue
- *   --help          Show this help message
- *
- * Environment variables (required unless --dry-run with minimal output):
- *   NETWORK              Target network (Calibnet or Mainnet)
- *   UPGRADE_TYPE         Type of upgrade (Routine or Breaking Change)
- *   AFTER_EPOCH          Block number after which upgrade can execute
- *   CHANGELOG_PR         PR number with changelog updates
- *   CHANGES_SUMMARY      Summary of changes (use | for multiple lines)
- *   ACTION_REQUIRED      Action required for integrators (default: None)
- *   UPGRADE_REGISTRY     Also upgrading ServiceProviderRegistry? (true/false, rare)
- *   UPGRADE_STATE_VIEW   Also redeploying FilecoinWarmStorageServiceStateView? (true/false, rare)
- *   RELEASE_TAG          Release tag if already created (optional)
- *
- * GitHub-specific environment variables (required when not using --dry-run):
- *   GITHUB_TOKEN         GitHub token with issues:write permission
- *   GITHUB_REPOSITORY    Repository in format owner/repo
+ * See help text below for more info.
  */
 
 const https = require("https");
@@ -234,11 +214,11 @@ function generateBody(timeEstimate) {
   const deployChecklist = contracts
     .map((c) => {
       if (c === "FilecoinWarmStorageService") {
-        return "- [ ] Deploy FWSS implementation: `./deploy-warm-storage-implementation-only.sh`";
+        return "- [ ] Deploy FWSS implementation: `./warm-storage-deploy-implementation.sh`";
       } else if (c === "ServiceProviderRegistry") {
-        return "- [ ] Deploy Registry implementation: `./deploy-registry.sh`";
+        return "- [ ] Deploy Registry implementation: `./service-provider-registry-deploy.sh`";
       } else if (c === "FilecoinWarmStorageServiceStateView") {
-        return "- [ ] Deploy StateView: `./deploy-warm-storage-view.sh`";
+        return "- [ ] Deploy StateView: `./warm-storage-deploy-view.sh`";
       }
       return `- [ ] Deploy ${c}`;
     })
@@ -247,9 +227,9 @@ function generateBody(timeEstimate) {
   const announceChecklist = contracts
     .map((c) => {
       if (c === "FilecoinWarmStorageService") {
-        return "- [ ] Announce FWSS upgrade: `./announce-planned-upgrade.sh`";
+        return "- [ ] Announce FWSS upgrade: `./warm-storage-announce-upgrade.sh`";
       } else if (c === "ServiceProviderRegistry") {
-        return "- [ ] Announce Registry upgrade: `./announce-planned-upgrade-registry.sh`";
+        return "- [ ] Announce Registry upgrade: `./service-provider-registry-announce-upgrade.sh`";
       }
       return null;
     })
@@ -259,9 +239,9 @@ function generateBody(timeEstimate) {
   const executeChecklist = contracts
     .map((c) => {
       if (c === "FilecoinWarmStorageService") {
-        return "- [ ] Execute FWSS upgrade: `./upgrade.sh`";
+        return "- [ ] Execute FWSS upgrade: `./warm-storage-execute-upgrade.sh`";
       } else if (c === "ServiceProviderRegistry") {
-        return "- [ ] Execute Registry upgrade: `./upgrade-registry.sh`";
+        return "- [ ] Execute Registry upgrade: `./service-provider-registry-execute-upgrade.sh`";
       }
       return null;
     })
@@ -341,6 +321,8 @@ ${executeChecklist}
 - [ ] Merge changelog PR: #${config.changelogPr}
 - [ ] Tag release: \`git tag vX.Y.Z && git push origin vX.Y.Z\`
 - [ ] Create GitHub Release with changelog
+- [ ] Merge auto-generated PRs in [filecoin-cloud](https://github.com/FilOzone/filecoin-cloud/pulls) so docs.filecoin.cloud and filecoin.cloud reflect new contract versions
+- [ ] Create "Upgrade Synapse to use newest contracts" issue
 - [ ] Update this issue with release link
 - [ ] Close this issue
 

service_contracts/README.md

@@ -16,8 +16,8 @@ This directory contains the smart contracts for different Filecoin services usin
   - `FilecoinWarmStorageService.t.sol` - Tests for the service contract
 - `tools/` - Deployment and utility scripts
   - `create_data_set_with_payments.sh` - Script to create data sets with payments
-  - `deploy-warm-storage-calibnet.sh` - Deployment script for Warm Storage service on Calibnet
-  - `deploy-all-warm-storage-calibnet.sh` - Deployment script for all Warm Storage contracts on Calibnet
+  - `warm-storage-deploy-calibnet.sh` - Deployment script for Warm Storage service on Calibnet
+  - `warm-storage-deploy-all.sh` - Deployment script for all Warm Storage contracts
   - Note: deployment scripts now deploy and link `SignatureVerificationLib` when deploying `FilecoinWarmStorageService`.
     The scripts will deploy `src/lib/SignatureVerificationLib.sol` (or simulate it in dry-run) and pass the library address
     to `forge create` via the `--libraries` flag so the service implementation is correctly linked.

service_contracts/tools/README.md

@@ -6,32 +6,47 @@ This directory contains scripts for deploying and upgrading the FilecoinWarmStor
 
 ## Scripts Overview
 
-### Deployment Scripts
+Scripts are organized with prefixes for better discoverability:
 
-- `deploy-warm-storage-calibnet.sh` - Deploy FilecoinWarmStorageService only (requires existing PDPVerifier and FilecoinPayV1 contracts)
-- `deploy-warm-storage-implementation-only.sh` - Deploy FWSS implementation only; loads defaults from `deployments.json` and writes back new implementation + metadata (reuses existing signature lib unless redeployed)
-- `deploy-all-warm-storage.sh` - Deploy all contracts to either Calibnet or Mainnet
+### Warm Storage Scripts
 
-### Upgrade Scripts
+| Script | Description |
+|--------|-------------|
+| `warm-storage-deploy-all.sh` | Deploy all contracts (PDPVerifier, FilecoinPayV1, FWSS, etc.) |
+| `warm-storage-deploy-implementation.sh` | Deploy FWSS implementation only (for upgrades) |
+| `warm-storage-deploy-view.sh` | Deploy FilecoinWarmStorageServiceStateView |
+| `warm-storage-deploy-calibnet.sh` | Deploy FWSS only (requires existing dependencies) |
+| `warm-storage-announce-upgrade.sh` | Announce a planned FWSS upgrade |
+| `warm-storage-execute-upgrade.sh` | Execute a previously announced FWSS upgrade |
+| `warm-storage-set-view.sh` | Set the StateView address on FWSS |
 
-For the [two step upgrade process](#contract-upgrade-process):
-- `announce-planned-upgrade.sh` - Announce a planned FWSS upgrade (two-step process)
-- `upgrade.sh` - Execute a previously announced FWSS upgrade
-- `announce-planned-upgrade-registry.sh` - Announce a planned ServiceProviderRegistry upgrade
-- `upgrade-registry.sh` - Execute a previously announced registry upgrade
+### Service Provider Registry Scripts
+
+| Script | Description |
+|--------|-------------|
+| `service-provider-registry-deploy.sh` | Deploy ServiceProviderRegistry |
+| `service-provider-registry-announce-upgrade.sh` | Announce a planned registry upgrade |
+| `service-provider-registry-execute-upgrade.sh` | Execute a previously announced registry upgrade |
+
+### Other Scripts
+
+| Script | Description |
+|--------|-------------|
+| `session-key-registry-deploy.sh` | Deploy SessionKeyRegistry |
+| `provider-id-set-deploy.sh` | Deploy ProviderIdSet |
 
 ### Usage
 
 ```bash
-# Deploy to Calibnet
-./tools/deploy-warm-storage-calibnet.sh
-
 # Deploy all contracts
-./tools/deploy-all-warm-storage.sh
+./tools/warm-storage-deploy-all.sh
+
+# Deploy to Calibnet (FWSS only)
+./tools/warm-storage-deploy-calibnet.sh
 
 # Upgrade existing deployment (see UPGRADE-PROCESS.md for details)
-./tools/announce-planned-upgrade.sh  # Step 1: Announce
-./tools/upgrade.sh                   # Step 2: Execute (after AFTER_EPOCH)
+./tools/warm-storage-announce-upgrade.sh    # Step 1: Announce
+./tools/warm-storage-execute-upgrade.sh     # Step 2: Execute (after AFTER_EPOCH)
 ```
 
 ## Deployment Parameters
@@ -126,11 +141,11 @@ These scripts now follow forge/cast's environment variable conventions. Set the
 - `ETH_FROM` - Optional: address to use as deployer (forge/cast default is taken from the keystore)
 
 ### Required for specific scripts:
-- `deploy-warm-storage-calibnet.sh` requires:
+- `warm-storage-deploy-calibnet.sh` requires:
   - `PDP_VERIFIER_PROXY_ADDRESS` - Address of deployed PDPVerifier contract
   - `FILECOIN_PAY_ADDRESS` - Address of deployed FilecoinPayV1 contract
 
-- `deploy-all-warm-storage.sh` requires:
+- `warm-storage-deploy-all.sh` requires:
   - `CHALLENGE_FINALITY` - Challenge finality parameter for PDPVerifier
 
 - Upgrade scripts - see [UPGRADE-PROCESS.md](./UPGRADE-PROCESS.md) for complete environment variable reference
@@ -151,7 +166,7 @@ export CHALLENGE_FINALITY="10"  # Use "150" for mainnet
 export MAX_PROVING_PERIOD="240"        # 240 epochs for calibnet, 2880 for mainnet
 export CHALLENGE_WINDOW_SIZE="20"      # 20 epochs for calibnet, 60 for mainnet
 
-./deploy-all-warm-storage.sh
+./warm-storage-deploy-all.sh
 ```
 
 ### Deploy FilecoinWarmStorageService Only
@@ -163,7 +178,7 @@ export ETH_RPC_URL="https://api.calibration.node.glif.io/rpc/v1"
 export PDP_VERIFIER_PROXY_ADDRESS="0x123..."
 export FILECOIN_PAY_ADDRESS="0x456..."
 
-./deploy-warm-storage-calibnet.sh
+./warm-storage-deploy-calibnet.sh
 ```
 
 ### Upgrade Existing Contract

service_contracts/tools/UPGRADE-PROCESS.md

@@ -12,6 +12,8 @@ This document describes the upgrade process for FilecoinWarmStorageService (FWSS
 | PDPVerifier | Yes (ERC1967) | Via [pdp repo](https://github.com/FilOzone/pdp) |
 | FilecoinPayV1, SessionKeyRegistry | No (immutable) | Not expected to change |
 
+**UUPS, two-step** — These contracts use the [UUPS (ERC-1822)](https://eips.ethereum.org/EIPS/eip-1822) proxy pattern via OpenZeppelin's `UUPSUpgradeable`, where the upgrade authorization logic lives in the *implementation* contract rather than the proxy. On top of standard UUPS, we add a **two-step upgrade mechanism**: the owner must first call `announcePlannedUpgrade()` to record the new implementation address and a future epoch, then wait for that epoch to pass before `upgradeToAndCall()` will succeed.
+
 > For upgrading ServiceProviderRegistry or redeploying StateView, see [Upgrading Other Contracts](#upgrading-other-contracts).
 
 ## Two-Step Upgrade Mechanism
@@ -50,7 +52,7 @@ echo "Current: $CURRENT_EPOCH, Upgrade after: $AFTER_EPOCH"
    - Mark breaking changes clearly
    - Include migration notes if needed
 
-2. **Update the version** string in the contract if applicable.
+2. **Update the [version](https://github.com/FilOzone/filecoin-services/blob/main/service_contracts/src/FilecoinWarmStorageService.sol#L63)** string in the contract.
 
 3. **Create an upgrade PR** with your changelog updates.
    - Example title: `feat: FWSS v1.2.0 upgrade`
@@ -68,10 +70,10 @@ Always test the upgrade on Calibnet before mainnet.
 cd service_contracts/tools
 export ETH_RPC_URL="https://api.calibration.node.glif.io/rpc/v1"
 
-./deploy-warm-storage-implementation-only.sh
+./warm-storage-deploy-implementation.sh
 ```
 
-The script updates `deployments.json` automatically. Commit the changes.
+The script updates `deployments.json` automatically. Commit the changes in the branch of the "upgrade PR" above.
 
 ### Announce Upgrade
 
@@ -80,7 +82,7 @@ export WARM_STORAGE_PROXY_ADDRESS="0x..."
 export NEW_WARM_STORAGE_IMPLEMENTATION_ADDRESS="0x..."
 export AFTER_EPOCH="123456"
 
-./announce-planned-upgrade.sh
+./warm-storage-announce-upgrade.sh
 ```
 
 ### Execute Upgrade
@@ -91,7 +93,7 @@ After `AFTER_EPOCH` passes:
 export WARM_STORAGE_PROXY_ADDRESS="0x..."
 export NEW_WARM_STORAGE_IMPLEMENTATION_ADDRESS="0x..."
 
-./upgrade.sh
+./warm-storage-execute-upgrade.sh
 ```
 
 Verify the upgrade on [Calibnet Blockscout](https://calibration.filfox.info/).
@@ -102,10 +104,10 @@ Verify the upgrade on [Calibnet Blockscout](https://calibration.filfox.info/).
 cd service_contracts/tools
 export ETH_RPC_URL="https://api.node.glif.io/rpc/v1"
 
-./deploy-warm-storage-implementation-only.sh
+./warm-storage-deploy-implementation.sh
 ```
 
-Commit the updated `deployments.json`.
+Commit the updated `deployments.json` in the branch of the "upgrade PR" above.
 
 ## Phase 4: Announce Mainnet Upgrade
 
@@ -115,7 +117,7 @@ export WARM_STORAGE_PROXY_ADDRESS="0x..."
 export NEW_WARM_STORAGE_IMPLEMENTATION_ADDRESS="0x..."
 export AFTER_EPOCH="123456"
 
-./announce-planned-upgrade.sh
+./warm-storage-announce-upgrade.sh
 ```
 
 Notify stakeholders (see [Stakeholder Communication](#stakeholder-communication)).
@@ -129,7 +131,7 @@ export ETH_RPC_URL="https://api.node.glif.io/rpc/v1"
 export WARM_STORAGE_PROXY_ADDRESS="0x..."
 export NEW_WARM_STORAGE_IMPLEMENTATION_ADDRESS="0x..."
 
-./upgrade.sh
+./warm-storage-execute-upgrade.sh
 ```
 
 ## Phase 6: Verify and Release
@@ -178,7 +180,7 @@ The registry uses the same two-step upgrade mechanism as FWSS. Only upgrade it w
 
 **Deploy new implementation:**
 ```bash
-./deploy-registry.sh
+./service-provider-registry-deploy.sh
 ```
 
 **Announce upgrade:**
@@ -187,15 +189,15 @@ export REGISTRY_PROXY_ADDRESS="0x..."
 export NEW_REGISTRY_IMPLEMENTATION_ADDRESS="0x..."
 export AFTER_EPOCH="123456"
 
-./announce-planned-upgrade-registry.sh
+./service-provider-registry-announce-upgrade.sh
 ```
 
 **Execute upgrade (after AFTER_EPOCH):**
 ```bash
 export SERVICE_PROVIDER_REGISTRY_PROXY_ADDRESS="0x..."
 export NEW_REGISTRY_IMPLEMENTATION_ADDRESS="0x..."
 
-./upgrade-registry.sh
+./service-provider-registry-execute-upgrade.sh
 ```
 
 **Environment variables:**
@@ -215,13 +217,13 @@ StateView is a helper contract (not upgradeable). Redeploy it when:
 
 **Deploy new StateView:**
 ```bash
-./deploy-warm-storage-view.sh
+./warm-storage-deploy-view.sh
 ```
 
 **Update FWSS to use new StateView (during upgrade):**
 ```bash
 export NEW_WARM_STORAGE_VIEW_ADDRESS="0x..."
-./upgrade.sh
+./warm-storage-execute-upgrade.sh
 ```
 
 ### Immutable Dependencies

service_contracts/tools/deploy-provider-id-set.sh → service_contracts/tools/provider-id-set-deploy.sh

@@ -1,5 +1,5 @@
 #!/bin/bash
-# deploy-provider-id-set deploys a ProviderIdSet contract
+# provider-id-set-deploy.sh deploys a ProviderIdSet contract
 # Assumption: ETH_KEYSTORE, PASSWORD, ETH_RPC_URL env vars are set to an appropriate eth keystore path and password
 # Assumption: forge, cast, jq are in the PATH
 # Assumption: called from contracts directory so forge paths work out

service_contracts/tools/announce-planned-upgrade-registry.sh → service_contracts/tools/service-provider-registry-announce-upgrade.sh

@@ -1,6 +1,6 @@
 #!/bin/bash
 
-# announce-planned-upgrade-registry.sh: Announces a planned upgrade for ServiceProviderRegistry
+# service-provider-registry-announce-upgrade.sh: Announces a planned upgrade for ServiceProviderRegistry
 # Required args: ETH_RPC_URL, SERVICE_PROVIDER_REGISTRY_PROXY_ADDRESS, ETH_KEYSTORE, PASSWORD, NEW_SERVICE_PROVIDER_REGISTRY_IMPLEMENTATION_ADDRESS, AFTER_EPOCH
 
 if [ -z "$ETH_RPC_URL" ]; then

service_contracts/tools/deploy-registry.sh → service_contracts/tools/service-provider-registry-deploy.sh

@@ -1,5 +1,5 @@
 #!/bin/bash
-# deploy-registry deploys the Service Provider Registry contract to a target network
+# service-provider-registry-deploy.sh deploys the Service Provider Registry contract to a target network
 # Assumption: ETH_KEYSTORE, PASSWORD, ETH_RPC_URL env vars are set to an appropriate eth keystore path and password
 # and to a valid ETH_RPC_URL for the target network.
 # Assumption: forge, cast, jq are in the PATH
@@ -190,7 +190,7 @@ if [ "$WITH_PROXY" = "true" ]; then
   echo "5. The registry is ready for provider registrations"
 else
   echo "1. Save the implementation address for upgrade announcement"
-  echo "2. Proceed with announce-planned-upgrade-registry.sh"
+  echo "2. Proceed with service-provider-registry-announce-upgrade.sh"
 fi
 echo ""
 if [ "$WITH_PROXY" = "true" ]; then

service_contracts/tools/upgrade-registry.sh → service_contracts/tools/service-provider-registry-execute-upgrade.sh

@@ -1,6 +1,6 @@
 #!/bin/bash
 
-# upgrade-registry.sh: Completes a pending upgrade for ServiceProviderRegistry
+# service-provider-registry-execute-upgrade.sh: Completes a pending upgrade for ServiceProviderRegistry
 # Required args: ETH_RPC_URL, SERVICE_PROVIDER_REGISTRY_PROXY_ADDRESS, ETH_KEYSTORE, PASSWORD, NEW_SERVICE_PROVIDER_REGISTRY_IMPLEMENTATION_ADDRESS
 # Optional args: NEW_VERSION
 # Calculated if unset: CHAIN
@@ -91,13 +91,13 @@ if [ $CAST_CALL_EXIT_CODE -eq 0 ] && [ -n "$UPGRADE_PLAN_OUTPUT" ]; then
     # Method exists but returns zero - no planned upgrade or already completed
     # On new contracts, _authorizeUpgrade requires a planned upgrade, so one-step will fail
     echo "No planned upgrade detected (nextUpgrade returns zero)"
-    echo "Error: This contract requires a planned upgrade. Please call announce-planned-upgrade-registry.sh first."
+    echo "Error: This contract requires a planned upgrade. Please call service-provider-registry-announce-upgrade.sh first."
     exit 1
   fi
 else
   # Method doesn't exist (old contract without nextUpgrade) or call failed
   echo "nextUpgrade() method not found or call failed, using one-step mechanism (direct upgrade)"
-  echo "WARNING: This is the legacy upgrade path. For new deployments, use announce-planned-upgrade-registry.sh first."
+  echo "WARNING: This is the legacy upgrade path. For new deployments, use service-provider-registry-announce-upgrade.sh first."
 fi
 
 if [ -n "$NEW_VERSION" ]; then

service_contracts/tools/announce-planned-upgrade.sh → service_contracts/tools/warm-storage-announce-upgrade.sh

@@ -1,6 +1,6 @@
 #!/bin/bash
 
-# announce-planned-upgrade.sh: Completes a pending upgrade
+# warm-storage-announce-upgrade.sh: Completes a pending upgrade
 # Required args: ETH_RPC_URL, FWSS_PROXY_ADDRESS, ETH_KEYSTORE, PASSWORD, NEW_FWSS_IMPLEMENTATION_ADDRESS, AFTER_EPOCH
 
 if [ -z "$ETH_RPC_URL" ]; then