From 2a244bb8b62ba2080fd63f0d37019d340efcccde Mon Sep 17 00:00:00 2001
From: Phi <orjan.roren@gmail.com>
Date: Wed, 4 Feb 2026 13:20:55 +0100
Subject: [PATCH 1/3] refactor: rename scripts with hierarchical prefixes for
 better discoverability

refactor: rename scripts with hierarchical prefixes for better discoverability
---
 .../scripts/create-upgrade-announcement.js    | 14 ++---
 service_contracts/README.md                   |  4 +-
 service_contracts/tools/README.md             | 55 ++++++++++++-------
 service_contracts/tools/UPGRADE-PROCESS.md    | 22 ++++----
 ...er-id-set.sh => provider-id-set-deploy.sh} |  2 +-
 ...ice-provider-registry-announce-upgrade.sh} |  2 +-
 ...sh => service-provider-registry-deploy.sh} |  4 +-
 ...vice-provider-registry-execute-upgrade.sh} |  6 +-
 ...stry.sh => session-key-registry-deploy.sh} |  0
 ...de.sh => warm-storage-announce-upgrade.sh} |  2 +-
 ...-storage.sh => warm-storage-deploy-all.sh} | 16 +++---
 ...net.sh => warm-storage-deploy-calibnet.sh} |  4 +-
 ... => warm-storage-deploy-implementation.sh} |  2 +-
 ...ge-view.sh => warm-storage-deploy-view.sh} |  0
 ...ade.sh => warm-storage-execute-upgrade.sh} |  2 +-
 ...orage-view.sh => warm-storage-set-view.sh} |  0
 16 files changed, 75 insertions(+), 60 deletions(-)
 rename service_contracts/tools/{deploy-provider-id-set.sh => provider-id-set-deploy.sh} (97%)
 rename service_contracts/tools/{announce-planned-upgrade-registry.sh => service-provider-registry-announce-upgrade.sh} (95%)
 rename service_contracts/tools/{deploy-registry.sh => service-provider-registry-deploy.sh} (97%)
 rename service_contracts/tools/{upgrade-registry.sh => service-provider-registry-execute-upgrade.sh} (96%)
 rename service_contracts/tools/{deploy-session-key-registry.sh => session-key-registry-deploy.sh} (100%)
 rename service_contracts/tools/{announce-planned-upgrade.sh => warm-storage-announce-upgrade.sh} (96%)
 rename service_contracts/tools/{deploy-all-warm-storage.sh => warm-storage-deploy-all.sh} (97%)
 rename service_contracts/tools/{deploy-warm-storage-calibnet.sh => warm-storage-deploy-calibnet.sh} (98%)
 rename service_contracts/tools/{deploy-warm-storage-implementation-only.sh => warm-storage-deploy-implementation.sh} (98%)
 rename service_contracts/tools/{deploy-warm-storage-view.sh => warm-storage-deploy-view.sh} (100%)
 rename service_contracts/tools/{upgrade.sh => warm-storage-execute-upgrade.sh} (98%)
 rename service_contracts/tools/{set-warm-storage-view.sh => warm-storage-set-view.sh} (100%)

diff --git a/.github/scripts/create-upgrade-announcement.js b/.github/scripts/create-upgrade-announcement.js
index 93615736..1d6640a0 100644
--- a/.github/scripts/create-upgrade-announcement.js
+++ b/.github/scripts/create-upgrade-announcement.js
@@ -234,11 +234,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 +247,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 +259,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;
     })
diff --git a/service_contracts/README.md b/service_contracts/README.md
index 0e4e6813..40a85ad1 100644
--- a/service_contracts/README.md
+++ b/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.
diff --git a/service_contracts/tools/README.md b/service_contracts/tools/README.md
index 3a9e847e..0aeafd9b 100644
--- a/service_contracts/tools/README.md
+++ b/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
diff --git a/service_contracts/tools/UPGRADE-PROCESS.md b/service_contracts/tools/UPGRADE-PROCESS.md
index db6292e9..741e2b38 100644
--- a/service_contracts/tools/UPGRADE-PROCESS.md
+++ b/service_contracts/tools/UPGRADE-PROCESS.md
@@ -68,7 +68,7 @@ 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.
@@ -80,7 +80,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 +91,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,7 +102,7 @@ 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`.
@@ -115,7 +115,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 +129,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 +178,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,7 +187,7 @@ 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):**
@@ -195,7 +195,7 @@ export AFTER_EPOCH="123456"
 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 +215,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
diff --git a/service_contracts/tools/deploy-provider-id-set.sh b/service_contracts/tools/provider-id-set-deploy.sh
similarity index 97%
rename from service_contracts/tools/deploy-provider-id-set.sh
rename to service_contracts/tools/provider-id-set-deploy.sh
index 68631732..f60f7dfb 100755
--- a/service_contracts/tools/deploy-provider-id-set.sh
+++ b/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
diff --git a/service_contracts/tools/announce-planned-upgrade-registry.sh b/service_contracts/tools/service-provider-registry-announce-upgrade.sh
similarity index 95%
rename from service_contracts/tools/announce-planned-upgrade-registry.sh
rename to service_contracts/tools/service-provider-registry-announce-upgrade.sh
index 00542ab1..7428bdcd 100755
--- a/service_contracts/tools/announce-planned-upgrade-registry.sh
+++ b/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
diff --git a/service_contracts/tools/deploy-registry.sh b/service_contracts/tools/service-provider-registry-deploy.sh
similarity index 97%
rename from service_contracts/tools/deploy-registry.sh
rename to service_contracts/tools/service-provider-registry-deploy.sh
index 1e05702a..b6dd2c6b 100755
--- a/service_contracts/tools/deploy-registry.sh
+++ b/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
diff --git a/service_contracts/tools/upgrade-registry.sh b/service_contracts/tools/service-provider-registry-execute-upgrade.sh
similarity index 96%
rename from service_contracts/tools/upgrade-registry.sh
rename to service_contracts/tools/service-provider-registry-execute-upgrade.sh
index fbd7f9ca..96d3e63c 100755
--- a/service_contracts/tools/upgrade-registry.sh
+++ b/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
diff --git a/service_contracts/tools/deploy-session-key-registry.sh b/service_contracts/tools/session-key-registry-deploy.sh
similarity index 100%
rename from service_contracts/tools/deploy-session-key-registry.sh
rename to service_contracts/tools/session-key-registry-deploy.sh
diff --git a/service_contracts/tools/announce-planned-upgrade.sh b/service_contracts/tools/warm-storage-announce-upgrade.sh
similarity index 96%
rename from service_contracts/tools/announce-planned-upgrade.sh
rename to service_contracts/tools/warm-storage-announce-upgrade.sh
index 88d650b2..ef624731 100755
--- a/service_contracts/tools/announce-planned-upgrade.sh
+++ b/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
diff --git a/service_contracts/tools/deploy-all-warm-storage.sh b/service_contracts/tools/warm-storage-deploy-all.sh
similarity index 97%
rename from service_contracts/tools/deploy-all-warm-storage.sh
rename to service_contracts/tools/warm-storage-deploy-all.sh
index 590439a8..08ed63bf 100755
--- a/service_contracts/tools/deploy-all-warm-storage.sh
+++ b/service_contracts/tools/warm-storage-deploy-all.sh
@@ -1,5 +1,5 @@
 #! /bin/bash
-# deploy-all-warm-storage deploys the PDP verifier, FilecoinPayV1 contract, and Warm Storage service
+# warm-storage-deploy-all.sh deploys the PDP verifier, FilecoinPayV1 contract, and Warm Storage service
 # Auto-detects network based on RPC chain ID and sets appropriate configuration
 # Assumption: 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.
@@ -271,7 +271,7 @@ deploy_proxy_if_needed() {
     echo
 }
 
-# Deploy session key registry if needed (uses ./deploy-session-key-registry.sh)
+# Deploy session key registry if needed (uses ./session-key-registry-deploy.sh)
 deploy_session_key_registry_if_needed() {
     if [ -n "$SESSION_KEY_REGISTRY_ADDRESS" ]; then
         echo -e "${BOLD}SessionKeyRegistry${RESET}"
@@ -287,7 +287,7 @@ deploy_session_key_registry_if_needed() {
         echo "  🧪 Using dummy address: $SESSION_KEY_REGISTRY_ADDRESS"
     else
         echo "  🔧 Using external deployment script..."
-        source "$SCRIPT_DIR/deploy-session-key-registry.sh"
+        source "$SCRIPT_DIR/session-key-registry-deploy.sh"
         NONCE=$(expr $NONCE + "1")
         echo "  ✅ Deployed at: $SESSION_KEY_REGISTRY_ADDRESS"
         
@@ -299,7 +299,7 @@ deploy_session_key_registry_if_needed() {
     echo
 }
 
-# Deploy endorsements ProviderIdSet contract if needed (uses ./deploy-provider-id-set.sh)
+# Deploy endorsements ProviderIdSet contract if needed (uses ./provider-id-set-deploy.sh)
 deploy_endorsements_if_needed() {
     if [ -n "$ENDORSEMENT_SET_ADDRESS" ]; then
         echo -e "${BOLD}Endorsements ProviderIdSet${RESET}"
@@ -318,7 +318,7 @@ deploy_endorsements_if_needed() {
         AUTO_VERIFY_BEFORE=${AUTO_VERIFY:-true}
         AUTO_VERIFY=false # override so as to set last
         # This also updates deployments.json
-        source "$SCRIPT_DIR/deploy-provider-id-set.sh"
+        source "$SCRIPT_DIR/provider-id-set-deploy.sh"
         AUTO_VERIFY=$AUTO_VERIFY_BEFORE
         NONCE=$(expr $NONCE + "1")
         echo "  ✅ Deployed at: $ENDORSEMENT_SET_ADDRESS"
@@ -486,7 +486,7 @@ if [ "$DRY_RUN" = "true" ]; then
     echo "  ✅ Deployment planned (dummy: $FWSS_VIEW_ADDRESS)"
 else
     echo "  🔧 Using external deployment script..."
-    source "$SCRIPT_DIR/deploy-warm-storage-view.sh"
+    source "$SCRIPT_DIR/warm-storage-deploy-view.sh"
     echo "  ✅ Deployed at: $FWSS_VIEW_ADDRESS"
     NONCE=$(expr $NONCE + "1")
     
@@ -503,7 +503,7 @@ if [ "$DRY_RUN" = "true" ]; then
     echo "  🔍 Would set view contract address on main contract (skipping in dry-run)"
 else
     echo "  🔧 Setting view address on FilecoinWarmStorageService..."
-    source "$SCRIPT_DIR/set-warm-storage-view.sh"
+    source "$SCRIPT_DIR/warm-storage-set-view.sh"
     echo "  ✅ View address set"
     NONCE=$(expr $NONCE + "1")
 fi
@@ -517,7 +517,7 @@ if [ "$DRY_RUN" = "true" ]; then
     echo "✅ Dry run completed successfully!"
     echo "🔍 All contract compilations and simulations passed"
     echo
-    echo "To perform actual deployment, run with: DRY_RUN=false ./tools/deploy-all-warm-storage.sh"
+    echo "To perform actual deployment, run with: DRY_RUN=false ./tools/warm-storage-deploy-all.sh"
     echo
     echo "# DRY-RUN SUMMARY ($NETWORK_NAME)"
 else
diff --git a/service_contracts/tools/deploy-warm-storage-calibnet.sh b/service_contracts/tools/warm-storage-deploy-calibnet.sh
similarity index 98%
rename from service_contracts/tools/deploy-warm-storage-calibnet.sh
rename to service_contracts/tools/warm-storage-deploy-calibnet.sh
index 5c8a72ec..bd727599 100755
--- a/service_contracts/tools/deploy-warm-storage-calibnet.sh
+++ b/service_contracts/tools/warm-storage-deploy-calibnet.sh
@@ -1,5 +1,5 @@
 #! /bin/bash
-# deploy-warm-storage-calibnet deploys the Warm Storage service contract to calibration net
+# warm-storage-deploy-calibnet.sh deploys the Warm Storage service contract to calibration net
 # 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 calibnet.
 # Assumption: forge, cast, jq are in the PATH
@@ -109,7 +109,7 @@ if [ "$MAX_PROVING_PERIOD" -lt "$MIN_REQUIRED" ]; then
   echo "       MAX_PROVING_PERIOD must be at least $MIN_REQUIRED (CHALLENGE_FINALITY + CHALLENGE_WINDOW_SIZE/2)"
   echo "       To fix: Set MAX_PROVING_PERIOD to at least $MIN_REQUIRED"
   echo ""
-  echo "       Example: MAX_PROVING_PERIOD=$MIN_REQUIRED CHALLENGE_WINDOW_SIZE=$CHALLENGE_WINDOW_SIZE ./deploy-warm-storage-calibnet.sh"
+  echo "       Example: MAX_PROVING_PERIOD=$MIN_REQUIRED CHALLENGE_WINDOW_SIZE=$CHALLENGE_WINDOW_SIZE ./warm-storage-deploy-calibnet.sh"
   exit 1
 fi
 
diff --git a/service_contracts/tools/deploy-warm-storage-implementation-only.sh b/service_contracts/tools/warm-storage-deploy-implementation.sh
similarity index 98%
rename from service_contracts/tools/deploy-warm-storage-implementation-only.sh
rename to service_contracts/tools/warm-storage-deploy-implementation.sh
index 39596438..47428450 100755
--- a/service_contracts/tools/deploy-warm-storage-implementation-only.sh
+++ b/service_contracts/tools/warm-storage-deploy-implementation.sh
@@ -1,5 +1,5 @@
 #!/bin/bash
-# deploy-warm-storage-implementation-only.sh - Deploy only FilecoinWarmStorageService implementation (no proxy)
+# warm-storage-deploy-implementation.sh - Deploy only FilecoinWarmStorageService implementation (no proxy)
 # This allows updating an existing proxy to point to the new implementation
 # Assumption: ETH_KEYSTORE, PASSWORD, ETH_RPC_URL env vars are set
 # Assumption: forge, cast are in the PATH
diff --git a/service_contracts/tools/deploy-warm-storage-view.sh b/service_contracts/tools/warm-storage-deploy-view.sh
similarity index 100%
rename from service_contracts/tools/deploy-warm-storage-view.sh
rename to service_contracts/tools/warm-storage-deploy-view.sh
diff --git a/service_contracts/tools/upgrade.sh b/service_contracts/tools/warm-storage-execute-upgrade.sh
similarity index 98%
rename from service_contracts/tools/upgrade.sh
rename to service_contracts/tools/warm-storage-execute-upgrade.sh
index bb8ea307..35941ad0 100755
--- a/service_contracts/tools/upgrade.sh
+++ b/service_contracts/tools/warm-storage-execute-upgrade.sh
@@ -1,6 +1,6 @@
 #!/bin/bash
 
-# upgrade.sh: Completes a pending upgrade
+# warm-storage-execute-upgrade.sh: Completes a pending upgrade
 # Required args: ETH_RPC_URL, FWSS_PROXY_ADDRESS, ETH_KEYSTORE, PASSWORD, NEW_WARM_STORAGE_IMPLEMENTATION_ADDRESS
 # Optional args: NEW_FWSS_VIEW_ADDRESS
 # Calculated if unset: CHAIN, FWSS_VIEW_ADDRESS
diff --git a/service_contracts/tools/set-warm-storage-view.sh b/service_contracts/tools/warm-storage-set-view.sh
similarity index 100%
rename from service_contracts/tools/set-warm-storage-view.sh
rename to service_contracts/tools/warm-storage-set-view.sh

From f8ffc6aba9bd6ba01bb65bca1bef0dabb1dbe7e9 Mon Sep 17 00:00:00 2001
From: Phi <orjan.roren@gmail.com>
Date: Fri, 6 Feb 2026 12:16:22 +0100
Subject: [PATCH 2/3] chore: address PR review comments

chore: address PR review comments
---
 .../scripts/create-upgrade-announcement.js    | 24 +++----------------
 service_contracts/tools/README.md             |  2 +-
 service_contracts/tools/UPGRADE-PROCESS.md    |  8 ++++---
 3 files changed, 9 insertions(+), 25 deletions(-)

diff --git a/.github/scripts/create-upgrade-announcement.js b/.github/scripts/create-upgrade-announcement.js
index 93615736..12bdb98d 100644
--- a/.github/scripts/create-upgrade-announcement.js
+++ b/.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");
@@ -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
 
diff --git a/service_contracts/tools/README.md b/service_contracts/tools/README.md
index 3a9e847e..04cbb0ae 100644
--- a/service_contracts/tools/README.md
+++ b/service_contracts/tools/README.md
@@ -8,7 +8,7 @@ This directory contains scripts for deploying and upgrading the FilecoinWarmStor
 
 ### Deployment Scripts
 
-- `deploy-warm-storage-calibnet.sh` - Deploy FilecoinWarmStorageService only (requires existing PDPVerifier and FilecoinPayV1 contracts)
+- `deploy-warm-storage-calibnet.sh` - Deploy FilecoinWarmStorageService to **Calibnet only** (deploys both the ERC1967 proxy and implementation, plus the SignatureVerificationLib library; requires existing PDPVerifier, FilecoinPayV1, FilBeam, SessionKeyRegistry, and ServiceProviderRegistry 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
 
diff --git a/service_contracts/tools/UPGRADE-PROCESS.md b/service_contracts/tools/UPGRADE-PROCESS.md
index db6292e9..be19b33b 100644
--- a/service_contracts/tools/UPGRADE-PROCESS.md
+++ b/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`
@@ -71,7 +73,7 @@ export ETH_RPC_URL="https://api.calibration.node.glif.io/rpc/v1"
 ./deploy-warm-storage-implementation-only.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
 
@@ -105,7 +107,7 @@ export ETH_RPC_URL="https://api.node.glif.io/rpc/v1"
 ./deploy-warm-storage-implementation-only.sh
 ```
 
-Commit the updated `deployments.json`.
+Commit the updated `deployments.json` in the branch of the "upgrade PR" above.
 
 ## Phase 4: Announce Mainnet Upgrade
 

From baba29d7641e4ae1c2155096ab4c8ad7ac4a353b Mon Sep 17 00:00:00 2001
From: Phi <orjan.roren@gmail.com>
Date: Wed, 4 Feb 2026 13:20:55 +0100
Subject: [PATCH 3/3] refactor: rename scripts with hierarchical prefixes for
 better discoverability

refactor: rename scripts with hierarchical prefixes for better discoverability
---
 .../scripts/create-upgrade-announcement.js    | 14 ++---
 service_contracts/README.md                   |  4 +-
 service_contracts/tools/README.md             | 55 ++++++++++++-------
 service_contracts/tools/UPGRADE-PROCESS.md    | 22 ++++----
 ...er-id-set.sh => provider-id-set-deploy.sh} |  2 +-
 ...ice-provider-registry-announce-upgrade.sh} |  2 +-
 ...sh => service-provider-registry-deploy.sh} |  4 +-
 ...vice-provider-registry-execute-upgrade.sh} |  6 +-
 ...stry.sh => session-key-registry-deploy.sh} |  0
 ...de.sh => warm-storage-announce-upgrade.sh} |  2 +-
 ...-storage.sh => warm-storage-deploy-all.sh} | 16 +++---
 ...net.sh => warm-storage-deploy-calibnet.sh} |  4 +-
 ... => warm-storage-deploy-implementation.sh} |  2 +-
 ...ge-view.sh => warm-storage-deploy-view.sh} |  0
 ...ade.sh => warm-storage-execute-upgrade.sh} |  2 +-
 ...orage-view.sh => warm-storage-set-view.sh} |  0
 16 files changed, 75 insertions(+), 60 deletions(-)
 rename service_contracts/tools/{deploy-provider-id-set.sh => provider-id-set-deploy.sh} (97%)
 rename service_contracts/tools/{announce-planned-upgrade-registry.sh => service-provider-registry-announce-upgrade.sh} (95%)
 rename service_contracts/tools/{deploy-registry.sh => service-provider-registry-deploy.sh} (97%)
 rename service_contracts/tools/{upgrade-registry.sh => service-provider-registry-execute-upgrade.sh} (96%)
 rename service_contracts/tools/{deploy-session-key-registry.sh => session-key-registry-deploy.sh} (100%)
 rename service_contracts/tools/{announce-planned-upgrade.sh => warm-storage-announce-upgrade.sh} (96%)
 rename service_contracts/tools/{deploy-all-warm-storage.sh => warm-storage-deploy-all.sh} (97%)
 rename service_contracts/tools/{deploy-warm-storage-calibnet.sh => warm-storage-deploy-calibnet.sh} (98%)
 rename service_contracts/tools/{deploy-warm-storage-implementation-only.sh => warm-storage-deploy-implementation.sh} (98%)
 rename service_contracts/tools/{deploy-warm-storage-view.sh => warm-storage-deploy-view.sh} (100%)
 rename service_contracts/tools/{upgrade.sh => warm-storage-execute-upgrade.sh} (98%)
 rename service_contracts/tools/{set-warm-storage-view.sh => warm-storage-set-view.sh} (100%)

diff --git a/.github/scripts/create-upgrade-announcement.js b/.github/scripts/create-upgrade-announcement.js
index 12bdb98d..b0695bcb 100644
--- a/.github/scripts/create-upgrade-announcement.js
+++ b/.github/scripts/create-upgrade-announcement.js
@@ -214,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}`;
     })
@@ -227,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;
     })
@@ -239,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;
     })
diff --git a/service_contracts/README.md b/service_contracts/README.md
index 0e4e6813..40a85ad1 100644
--- a/service_contracts/README.md
+++ b/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.
diff --git a/service_contracts/tools/README.md b/service_contracts/tools/README.md
index 04cbb0ae..0aeafd9b 100644
--- a/service_contracts/tools/README.md
+++ b/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 to **Calibnet only** (deploys both the ERC1967 proxy and implementation, plus the SignatureVerificationLib library; requires existing PDPVerifier, FilecoinPayV1, FilBeam, SessionKeyRegistry, and ServiceProviderRegistry 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
diff --git a/service_contracts/tools/UPGRADE-PROCESS.md b/service_contracts/tools/UPGRADE-PROCESS.md
index be19b33b..7584fce6 100644
--- a/service_contracts/tools/UPGRADE-PROCESS.md
+++ b/service_contracts/tools/UPGRADE-PROCESS.md
@@ -70,7 +70,7 @@ 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 in the branch of the "upgrade PR" above.
@@ -82,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
@@ -93,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/).
@@ -104,7 +104,7 @@ 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` in the branch of the "upgrade PR" above.
@@ -117,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)).
@@ -131,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
@@ -180,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:**
@@ -189,7 +189,7 @@ 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):**
@@ -197,7 +197,7 @@ export AFTER_EPOCH="123456"
 export SERVICE_PROVIDER_REGISTRY_PROXY_ADDRESS="0x..."
 export NEW_REGISTRY_IMPLEMENTATION_ADDRESS="0x..."
 
-./upgrade-registry.sh
+./service-provider-registry-execute-upgrade.sh
 ```
 
 **Environment variables:**
@@ -217,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
diff --git a/service_contracts/tools/deploy-provider-id-set.sh b/service_contracts/tools/provider-id-set-deploy.sh
similarity index 97%
rename from service_contracts/tools/deploy-provider-id-set.sh
rename to service_contracts/tools/provider-id-set-deploy.sh
index 68631732..f60f7dfb 100755
--- a/service_contracts/tools/deploy-provider-id-set.sh
+++ b/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
diff --git a/service_contracts/tools/announce-planned-upgrade-registry.sh b/service_contracts/tools/service-provider-registry-announce-upgrade.sh
similarity index 95%
rename from service_contracts/tools/announce-planned-upgrade-registry.sh
rename to service_contracts/tools/service-provider-registry-announce-upgrade.sh
index 00542ab1..7428bdcd 100755
--- a/service_contracts/tools/announce-planned-upgrade-registry.sh
+++ b/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
diff --git a/service_contracts/tools/deploy-registry.sh b/service_contracts/tools/service-provider-registry-deploy.sh
similarity index 97%
rename from service_contracts/tools/deploy-registry.sh
rename to service_contracts/tools/service-provider-registry-deploy.sh
index 1e05702a..b6dd2c6b 100755
--- a/service_contracts/tools/deploy-registry.sh
+++ b/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
diff --git a/service_contracts/tools/upgrade-registry.sh b/service_contracts/tools/service-provider-registry-execute-upgrade.sh
similarity index 96%
rename from service_contracts/tools/upgrade-registry.sh
rename to service_contracts/tools/service-provider-registry-execute-upgrade.sh
index fbd7f9ca..96d3e63c 100755
--- a/service_contracts/tools/upgrade-registry.sh
+++ b/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
diff --git a/service_contracts/tools/deploy-session-key-registry.sh b/service_contracts/tools/session-key-registry-deploy.sh
similarity index 100%
rename from service_contracts/tools/deploy-session-key-registry.sh
rename to service_contracts/tools/session-key-registry-deploy.sh
diff --git a/service_contracts/tools/announce-planned-upgrade.sh b/service_contracts/tools/warm-storage-announce-upgrade.sh
similarity index 96%
rename from service_contracts/tools/announce-planned-upgrade.sh
rename to service_contracts/tools/warm-storage-announce-upgrade.sh
index 88d650b2..ef624731 100755
--- a/service_contracts/tools/announce-planned-upgrade.sh
+++ b/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
diff --git a/service_contracts/tools/deploy-all-warm-storage.sh b/service_contracts/tools/warm-storage-deploy-all.sh
similarity index 97%
rename from service_contracts/tools/deploy-all-warm-storage.sh
rename to service_contracts/tools/warm-storage-deploy-all.sh
index 590439a8..08ed63bf 100755
--- a/service_contracts/tools/deploy-all-warm-storage.sh
+++ b/service_contracts/tools/warm-storage-deploy-all.sh
@@ -1,5 +1,5 @@
 #! /bin/bash
-# deploy-all-warm-storage deploys the PDP verifier, FilecoinPayV1 contract, and Warm Storage service
+# warm-storage-deploy-all.sh deploys the PDP verifier, FilecoinPayV1 contract, and Warm Storage service
 # Auto-detects network based on RPC chain ID and sets appropriate configuration
 # Assumption: 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.
@@ -271,7 +271,7 @@ deploy_proxy_if_needed() {
     echo
 }
 
-# Deploy session key registry if needed (uses ./deploy-session-key-registry.sh)
+# Deploy session key registry if needed (uses ./session-key-registry-deploy.sh)
 deploy_session_key_registry_if_needed() {
     if [ -n "$SESSION_KEY_REGISTRY_ADDRESS" ]; then
         echo -e "${BOLD}SessionKeyRegistry${RESET}"
@@ -287,7 +287,7 @@ deploy_session_key_registry_if_needed() {
         echo "  🧪 Using dummy address: $SESSION_KEY_REGISTRY_ADDRESS"
     else
         echo "  🔧 Using external deployment script..."
-        source "$SCRIPT_DIR/deploy-session-key-registry.sh"
+        source "$SCRIPT_DIR/session-key-registry-deploy.sh"
         NONCE=$(expr $NONCE + "1")
         echo "  ✅ Deployed at: $SESSION_KEY_REGISTRY_ADDRESS"
         
@@ -299,7 +299,7 @@ deploy_session_key_registry_if_needed() {
     echo
 }
 
-# Deploy endorsements ProviderIdSet contract if needed (uses ./deploy-provider-id-set.sh)
+# Deploy endorsements ProviderIdSet contract if needed (uses ./provider-id-set-deploy.sh)
 deploy_endorsements_if_needed() {
     if [ -n "$ENDORSEMENT_SET_ADDRESS" ]; then
         echo -e "${BOLD}Endorsements ProviderIdSet${RESET}"
@@ -318,7 +318,7 @@ deploy_endorsements_if_needed() {
         AUTO_VERIFY_BEFORE=${AUTO_VERIFY:-true}
         AUTO_VERIFY=false # override so as to set last
         # This also updates deployments.json
-        source "$SCRIPT_DIR/deploy-provider-id-set.sh"
+        source "$SCRIPT_DIR/provider-id-set-deploy.sh"
         AUTO_VERIFY=$AUTO_VERIFY_BEFORE
         NONCE=$(expr $NONCE + "1")
         echo "  ✅ Deployed at: $ENDORSEMENT_SET_ADDRESS"
@@ -486,7 +486,7 @@ if [ "$DRY_RUN" = "true" ]; then
     echo "  ✅ Deployment planned (dummy: $FWSS_VIEW_ADDRESS)"
 else
     echo "  🔧 Using external deployment script..."
-    source "$SCRIPT_DIR/deploy-warm-storage-view.sh"
+    source "$SCRIPT_DIR/warm-storage-deploy-view.sh"
     echo "  ✅ Deployed at: $FWSS_VIEW_ADDRESS"
     NONCE=$(expr $NONCE + "1")
     
@@ -503,7 +503,7 @@ if [ "$DRY_RUN" = "true" ]; then
     echo "  🔍 Would set view contract address on main contract (skipping in dry-run)"
 else
     echo "  🔧 Setting view address on FilecoinWarmStorageService..."
-    source "$SCRIPT_DIR/set-warm-storage-view.sh"
+    source "$SCRIPT_DIR/warm-storage-set-view.sh"
     echo "  ✅ View address set"
     NONCE=$(expr $NONCE + "1")
 fi
@@ -517,7 +517,7 @@ if [ "$DRY_RUN" = "true" ]; then
     echo "✅ Dry run completed successfully!"
     echo "🔍 All contract compilations and simulations passed"
     echo
-    echo "To perform actual deployment, run with: DRY_RUN=false ./tools/deploy-all-warm-storage.sh"
+    echo "To perform actual deployment, run with: DRY_RUN=false ./tools/warm-storage-deploy-all.sh"
     echo
     echo "# DRY-RUN SUMMARY ($NETWORK_NAME)"
 else
diff --git a/service_contracts/tools/deploy-warm-storage-calibnet.sh b/service_contracts/tools/warm-storage-deploy-calibnet.sh
similarity index 98%
rename from service_contracts/tools/deploy-warm-storage-calibnet.sh
rename to service_contracts/tools/warm-storage-deploy-calibnet.sh
index 5c8a72ec..bd727599 100755
--- a/service_contracts/tools/deploy-warm-storage-calibnet.sh
+++ b/service_contracts/tools/warm-storage-deploy-calibnet.sh
@@ -1,5 +1,5 @@
 #! /bin/bash
-# deploy-warm-storage-calibnet deploys the Warm Storage service contract to calibration net
+# warm-storage-deploy-calibnet.sh deploys the Warm Storage service contract to calibration net
 # 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 calibnet.
 # Assumption: forge, cast, jq are in the PATH
@@ -109,7 +109,7 @@ if [ "$MAX_PROVING_PERIOD" -lt "$MIN_REQUIRED" ]; then
   echo "       MAX_PROVING_PERIOD must be at least $MIN_REQUIRED (CHALLENGE_FINALITY + CHALLENGE_WINDOW_SIZE/2)"
   echo "       To fix: Set MAX_PROVING_PERIOD to at least $MIN_REQUIRED"
   echo ""
-  echo "       Example: MAX_PROVING_PERIOD=$MIN_REQUIRED CHALLENGE_WINDOW_SIZE=$CHALLENGE_WINDOW_SIZE ./deploy-warm-storage-calibnet.sh"
+  echo "       Example: MAX_PROVING_PERIOD=$MIN_REQUIRED CHALLENGE_WINDOW_SIZE=$CHALLENGE_WINDOW_SIZE ./warm-storage-deploy-calibnet.sh"
   exit 1
 fi
 
diff --git a/service_contracts/tools/deploy-warm-storage-implementation-only.sh b/service_contracts/tools/warm-storage-deploy-implementation.sh
similarity index 98%
rename from service_contracts/tools/deploy-warm-storage-implementation-only.sh
rename to service_contracts/tools/warm-storage-deploy-implementation.sh
index 39596438..47428450 100755
--- a/service_contracts/tools/deploy-warm-storage-implementation-only.sh
+++ b/service_contracts/tools/warm-storage-deploy-implementation.sh
@@ -1,5 +1,5 @@
 #!/bin/bash
-# deploy-warm-storage-implementation-only.sh - Deploy only FilecoinWarmStorageService implementation (no proxy)
+# warm-storage-deploy-implementation.sh - Deploy only FilecoinWarmStorageService implementation (no proxy)
 # This allows updating an existing proxy to point to the new implementation
 # Assumption: ETH_KEYSTORE, PASSWORD, ETH_RPC_URL env vars are set
 # Assumption: forge, cast are in the PATH
diff --git a/service_contracts/tools/deploy-warm-storage-view.sh b/service_contracts/tools/warm-storage-deploy-view.sh
similarity index 100%
rename from service_contracts/tools/deploy-warm-storage-view.sh
rename to service_contracts/tools/warm-storage-deploy-view.sh
diff --git a/service_contracts/tools/upgrade.sh b/service_contracts/tools/warm-storage-execute-upgrade.sh
similarity index 98%
rename from service_contracts/tools/upgrade.sh
rename to service_contracts/tools/warm-storage-execute-upgrade.sh
index bb8ea307..35941ad0 100755
--- a/service_contracts/tools/upgrade.sh
+++ b/service_contracts/tools/warm-storage-execute-upgrade.sh
@@ -1,6 +1,6 @@
 #!/bin/bash
 
-# upgrade.sh: Completes a pending upgrade
+# warm-storage-execute-upgrade.sh: Completes a pending upgrade
 # Required args: ETH_RPC_URL, FWSS_PROXY_ADDRESS, ETH_KEYSTORE, PASSWORD, NEW_WARM_STORAGE_IMPLEMENTATION_ADDRESS
 # Optional args: NEW_FWSS_VIEW_ADDRESS
 # Calculated if unset: CHAIN, FWSS_VIEW_ADDRESS
diff --git a/service_contracts/tools/set-warm-storage-view.sh b/service_contracts/tools/warm-storage-set-view.sh
similarity index 100%
rename from service_contracts/tools/set-warm-storage-view.sh
rename to service_contracts/tools/warm-storage-set-view.sh