diff --git a/CHANGELOG.md b/CHANGELOG.md
index 52be3ba1..b1b91a0c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -40,10 +40,10 @@ Configuration:
   - From [PDP v3.1.0](https://github.com/FilOzone/pdp/releases/tag/v3.1.0)
 3. PDPVerifier Proxy: [0x85e366Cf9DD2c0aE37E963d9556F5f4718d6417C](https://filecoin-testnet.blockscout.com/address/0x85e366Cf9DD2c0aE37E963d9556F5f4718d6417C)
   - From [PDP v3.1.0](https://github.com/FilOzone/pdp/releases/tag/v3.1.0)
-4. SessionKeyRegistry: [0x97Dd879F5a97A8c761B94746d7F5cfF50AAd4452](https://filecoin-testnet.blockscout.com/address/0x97Dd879F5a97A8c761B94746d7F5cfF50AAd4452)
+4. SessionKeyRegistry: [0x518411c2062E119Aaf7A8B12A2eDf9a939347655](https://filecoin-testnet.blockscout.com/address/0x518411c2062E119Aaf7A8B12A2eDf9a939347655)
 5. ServiceProviderRegistry Implementation: [0xb32Bb530638d20f1B59B40CDD2Ce4208430f7DE3](https://filecoin-testnet.blockscout.com/address/0xb32Bb530638d20f1B59B40CDD2Ce4208430f7DE3)
 6. ServiceProviderRegistry Proxy: [0x839e5c9988e4e9977d40708d0094103c0839Ac9D](https://filecoin-testnet.blockscout.com/address/0x839e5c9988e4e9977d40708d0094103c0839Ac9D)
-7. FilecoinWarmStorageService Implementation: [0x4BCc752555Bf08A5Bd9a4Ce467a12607277450bA](https://filecoin-testnet.blockscout.com/address/0x4BCc752555Bf08A5Bd9a4Ce467a12607277450bA)
+7. FilecoinWarmStorageService Implementation: [0x1cAeE5EfCfc3681C2bBF689Ccb30d70c6e45F49f](https://filecoin-testnet.blockscout.com/address/0x1cAeE5EfCfc3681C2bBF689Ccb30d70c6e45F49f)
 8. FilecoinWarmStorageService Proxy: [0x02925630df557F957f70E112bA06e50965417CA0](https://filecoin-testnet.blockscout.com/address/0x02925630df557F957f70E112bA06e50965417CA0)
 9. FilecoinWarmStorageServiceStateView: [0xA5D87b04086B1d591026cCE10255351B5AA4689B](https://filecoin-testnet.blockscout.com/address/0xA5D87b04086B1d591026cCE10255351B5AA4689B)
 
diff --git a/service_contracts/deployments.json b/service_contracts/deployments.json
new file mode 100644
index 00000000..5f2b6a41
--- /dev/null
+++ b/service_contracts/deployments.json
@@ -0,0 +1,30 @@
+{
+  "314": {
+    "metadata": {
+      "note": "Filecoin mainnet deployments"
+    },
+    "PAYMENTS_CONTRACT_ADDRESS": "0x23b1e018F08BB982348b15a86ee926eEBf7F4DAa",
+    "VERIFIER_IMPLEMENTATION_ADDRESS": "0xe2Dc211BffcA499761570E04e8143Be2BA66095f",
+    "PDP_VERIFIER_ADDRESS": "0xBADd0B92C1c71d02E7d520f64c0876538fa2557F",
+    "SESSION_KEY_REGISTRY_ADDRESS": "0x74FD50525A958aF5d484601E252271f9625231aB",
+    "REGISTRY_IMPLEMENTATION_ADDRESS": "0xe255D3a89D6B326b48bc0fC94a472A839471D6B0",
+    "SERVICE_PROVIDER_REGISTRY_PROXY_ADDRESS": "0xf55dDbf63F1b55c3F1D4FA7e339a68AB7b64A5eB",
+    "FWS_IMPLEMENTATION_ADDRESS": "0xd60b90f6D3C42B26a246E141ec701a20Dde2fA61",
+    "WARM_STORAGE_PROXY_ADDRESS": "0x8408502033C418E1bbC97cE9ac48E5528F371A9f",
+    "WARM_STORAGE_VIEW_ADDRESS": "0x9e4e6699d8F67dFc883d6b0A7344Bd56F7E80B46"
+  },
+  "314159": {
+    "metadata": {
+      "note": "Filecoin calibnet deployments"
+    },
+    "PAYMENTS_CONTRACT_ADDRESS": "0x09a0fDc2723fAd1A7b8e3e00eE5DF73841df55a0",
+    "VERIFIER_IMPLEMENTATION_ADDRESS": "0x2355Cb19BA1eFF51673562E1a5fc5eE292AF9D42",
+    "PDP_VERIFIER_ADDRESS": "0x85e366Cf9DD2c0aE37E963d9556F5f4718d6417C",
+    "SESSION_KEY_REGISTRY_ADDRESS": "0x518411c2062E119Aaf7A8B12A2eDf9a939347655",
+    "REGISTRY_IMPLEMENTATION_ADDRESS": "0xb32Bb530638d20f1B59B40CDD2Ce4208430f7DE3",
+    "SERVICE_PROVIDER_REGISTRY_PROXY_ADDRESS": "0x839e5c9988e4e9977d40708d0094103c0839Ac9D",
+    "FWS_IMPLEMENTATION_ADDRESS": "0x1cAeE5EfCfc3681C2bBF689Ccb30d70c6e45F49f",
+    "WARM_STORAGE_PROXY_ADDRESS": "0x02925630df557F957f70E112bA06e50965417CA0",
+    "WARM_STORAGE_VIEW_ADDRESS": "0xA5D87b04086B1d591026cCE10255351B5AA4689B"
+  }
+}
diff --git a/service_contracts/tools/README.md b/service_contracts/tools/README.md
index 8c5fc1e8..731b1352 100644
--- a/service_contracts/tools/README.md
+++ b/service_contracts/tools/README.md
@@ -49,6 +49,62 @@ The following parameters are critical for proof generation and validation. They
   DEFAULT_CHALLENGE_WINDOW_SIZE="20"     # 20 epochs
   ```
 
+## Deployment Address Management
+
+Deployment scripts automatically load and update contract addresses in `deployments.json`, keyed by chain ID. This makes deployments easier and reduces mistakes when updating addresses downstream.
+
+### deployments.json Structure
+
+The `deployments.json` file stores deployment addresses organized by chain ID:
+
+```json
+{
+  "314": {
+    "PDP_VERIFIER_PROXY_ADDRESS": "0x...",
+    "PAYMENTS_CONTRACT_ADDRESS": "0x...",
+    "WARM_STORAGE_PROXY_ADDRESS": "0x...",
+    "metadata": {
+      "commit": "abc123...",
+      "deployed_at": "2024-01-01T00:00:00Z"
+    }
+  },
+  "314159": {
+    ...
+  }
+}
+```
+
+### How It Works
+
+1. **Loading addresses**: Scripts automatically load addresses from `deployments.json` for the detected chain ID. If an address doesn't exist in the JSON, the script will use environment variables or fail if required.
+
+2. **Updating addresses**: When a script deploys a new contract, it automatically updates `deployments.json` with the new address.
+
+3. **Environment variable override**: Environment variables take precedence over values loaded from JSON, allowing you to override specific addresses when needed.
+
+4. **Metadata tracking**: The system automatically tracks the git commit hash and deployment timestamp for each chain.
+
+### Control Flags
+
+- `SKIP_LOAD_DEPLOYMENTS=true` - Skip loading addresses from JSON (use only environment variables)
+- `SKIP_UPDATE_DEPLOYMENTS=true` - Skip updating JSON after deployment
+
+### Querying Addresses
+
+You can query addresses using `jq`:
+
+```bash
+# Get all addresses for a chain
+jq '.["314"]' deployments.json
+
+# Get a specific address
+jq -r '.["314"].WARM_STORAGE_PROXY_ADDRESS' deployments.json
+```
+
+### Version Control
+
+The `deployments.json` file should be committed to version control. Updates to it should be tagged as version releases.
+
 ## Environment Variables
 
 ### Required for all scripts:
diff --git a/service_contracts/tools/deploy-all-warm-storage.sh b/service_contracts/tools/deploy-all-warm-storage.sh
index 9915e00b..9dd605f2 100755
--- a/service_contracts/tools/deploy-all-warm-storage.sh
+++ b/service_contracts/tools/deploy-all-warm-storage.sh
@@ -24,6 +24,9 @@ fi
 # in the same directory, regardless of where this script is executed from
 SCRIPT_DIR="$(dirname "${BASH_SOURCE[0]}")"
 
+# Source the shared deployments script
+source "$SCRIPT_DIR/deployments.sh"
+
 echo "Deploying all Warm Storage contracts"
 
 if [ -z "$ETH_RPC_URL" ]; then
@@ -74,6 +77,9 @@ esac
 
 echo "Detected Chain ID: $CHAIN ($NETWORK_NAME)"
 
+# Load deployment addresses from deployments.json
+load_deployment_addresses "$CHAIN"
+
 if [ "$DRY_RUN" != "true" ] && [ -z "$ETH_KEYSTORE" ]; then
   echo "Error: ETH_KEYSTORE is not set (required for actual deployment)"
   exit 1
@@ -194,6 +200,11 @@ deploy_implementation_if_needed() {
 
         eval "$var_name='$address'"
         echo "  ✅ Deployed at: ${!var_name}"
+        
+        # Update deployments.json if this is an actual deployment
+        if [ "$DRY_RUN" != "true" ]; then
+            update_deployment_address "$CHAIN" "$var_name" "${!var_name}"
+        fi
     fi
 
     NONCE=$(expr $NONCE + "1")
@@ -237,6 +248,11 @@ deploy_proxy_if_needed() {
 
         eval "$var_name='$address'"
         echo "  ✅ Deployed at: ${!var_name}"
+        
+        # Update deployments.json if this is an actual deployment
+        if [ "$DRY_RUN" != "true" ]; then
+            update_deployment_address "$CHAIN" "$var_name" "${!var_name}"
+        fi
     fi
 
     NONCE=$(expr $NONCE + "1")
@@ -262,6 +278,11 @@ deploy_session_key_registry_if_needed() {
         source "$SCRIPT_DIR/deploy-session-key-registry.sh"
         NONCE=$(expr $NONCE + "1")
         echo "  ✅ Deployed at: $SESSION_KEY_REGISTRY_ADDRESS"
+        
+        # Update deployments.json
+        if [ -n "$SESSION_KEY_REGISTRY_ADDRESS" ]; then
+            update_deployment_address "$CHAIN" "SESSION_KEY_REGISTRY_ADDRESS" "$SESSION_KEY_REGISTRY_ADDRESS"
+        fi
     fi
     echo
 }
@@ -401,7 +422,7 @@ unset LIBRARIES
 # Initialize with max proving period, challenge window size, FilBeam controller address, name, and description
 INIT_DATA=$(cast calldata "initialize(uint64,uint256,address,string,string)" $MAX_PROVING_PERIOD $CHALLENGE_WINDOW_SIZE $FILBEAM_CONTROLLER_ADDRESS "$SERVICE_NAME" "$SERVICE_DESCRIPTION")
 deploy_proxy_if_needed \
-    "WARM_STORAGE_SERVICE_ADDRESS" \
+    "WARM_STORAGE_PROXY_ADDRESS" \
     "$FWS_IMPLEMENTATION_ADDRESS" \
     "$INIT_DATA" \
     "FilecoinWarmStorageService proxy"
@@ -416,6 +437,11 @@ else
     echo "  🔧 Using external deployment script..."
     source "$SCRIPT_DIR/deploy-warm-storage-view.sh"
     echo "  ✅ Deployed at: $WARM_STORAGE_VIEW_ADDRESS"
+    
+    # Update deployments.json
+    if [ -n "$WARM_STORAGE_VIEW_ADDRESS" ]; then
+        update_deployment_address "$CHAIN" "WARM_STORAGE_VIEW_ADDRESS" "$WARM_STORAGE_VIEW_ADDRESS"
+    fi
 fi
 echo
 
@@ -452,7 +478,7 @@ echo "FilecoinPayV1 Contract: $PAYMENTS_CONTRACT_ADDRESS"
 echo "ServiceProviderRegistry Implementation: $REGISTRY_IMPLEMENTATION_ADDRESS"
 echo "ServiceProviderRegistry Proxy: $SERVICE_PROVIDER_REGISTRY_PROXY_ADDRESS"
 echo "FilecoinWarmStorageService Implementation: $FWS_IMPLEMENTATION_ADDRESS"
-echo "FilecoinWarmStorageService Proxy: $WARM_STORAGE_SERVICE_ADDRESS"
+echo "FilecoinWarmStorageService Proxy: $WARM_STORAGE_PROXY_ADDRESS"
 echo "FilecoinWarmStorageServiceStateView: $WARM_STORAGE_VIEW_ADDRESS"
 echo
 echo "Network Configuration ($NETWORK_NAME):"
@@ -480,8 +506,15 @@ if [ "$DRY_RUN" = "false" ] && [ "${AUTO_VERIFY:-true}" = "true" ]; then
         "$REGISTRY_IMPLEMENTATION_ADDRESS,src/ServiceProviderRegistry.sol:ServiceProviderRegistry" \
         "$SERVICE_PROVIDER_REGISTRY_PROXY_ADDRESS,lib/openzeppelin-contracts/contracts/proxy/ERC1967/ERC1967Proxy.sol:ERC1967Proxy" \
         "$FWS_IMPLEMENTATION_ADDRESS,src/FilecoinWarmStorageService.sol:FilecoinWarmStorageService" \
-        "$WARM_STORAGE_SERVICE_ADDRESS,lib/openzeppelin-contracts/contracts/proxy/ERC1967/ERC1967Proxy.sol:ERC1967Proxy" \
+        "$WARM_STORAGE_PROXY_ADDRESS,lib/openzeppelin-contracts/contracts/proxy/ERC1967/ERC1967Proxy.sol:ERC1967Proxy" \
         "$WARM_STORAGE_VIEW_ADDRESS,src/FilecoinWarmStorageServiceStateView.sol:FilecoinWarmStorageServiceStateView"
     
     popd >/dev/null
 fi
+
+# Update deployment metadata if this was an actual deployment
+if [ "$DRY_RUN" != "true" ]; then
+    echo
+    echo "📝 Updating deployment metadata..."
+    update_deployment_metadata "$CHAIN"
+fi
diff --git a/service_contracts/tools/deploy-registry-calibnet.sh b/service_contracts/tools/deploy-registry-calibnet.sh
index 821b53cd..a2c85db0 100755
--- a/service_contracts/tools/deploy-registry-calibnet.sh
+++ b/service_contracts/tools/deploy-registry-calibnet.sh
@@ -6,10 +6,17 @@
 # Assumption: called from contracts directory so forge paths work out
 #
 
+# Get script directory and source deployments.sh
+SCRIPT_DIR="$(dirname "${BASH_SOURCE[0]}")"
+source "$SCRIPT_DIR/deployments.sh"
+
 echo "Deploying Service Provider Registry Contract"
 
 export CHAIN=314159
 
+# Load deployment addresses from deployments.json
+load_deployment_addresses "$CHAIN"
+
 if [ -z "$ETH_RPC_URL" ]; then
   echo "Error: ETH_RPC_URL is not set"
   exit 1
@@ -110,6 +117,17 @@ echo "=========================================="
 echo "ServiceProviderRegistry Implementation: $REGISTRY_IMPLEMENTATION_ADDRESS"
 echo "ServiceProviderRegistry Proxy: $REGISTRY_PROXY_ADDRESS"
 echo "=========================================="
+
+# Update deployments.json
+if [ -n "$REGISTRY_IMPLEMENTATION_ADDRESS" ]; then
+    update_deployment_address "$CHAIN" "REGISTRY_IMPLEMENTATION_ADDRESS" "$REGISTRY_IMPLEMENTATION_ADDRESS"
+fi
+if [ -n "$REGISTRY_PROXY_ADDRESS" ]; then
+    update_deployment_address "$CHAIN" "SERVICE_PROVIDER_REGISTRY_PROXY_ADDRESS" "$REGISTRY_PROXY_ADDRESS"
+fi
+if [ -n "$REGISTRY_IMPLEMENTATION_ADDRESS" ] || [ -n "$REGISTRY_PROXY_ADDRESS" ]; then
+    update_deployment_metadata "$CHAIN"
+fi
 echo ""
 echo "Contract Details:"
 echo "  - Version: $CONTRACT_VERSION"
diff --git a/service_contracts/tools/deploy-session-key-registry.sh b/service_contracts/tools/deploy-session-key-registry.sh
index 3095bf9f..a97d189c 100755
--- a/service_contracts/tools/deploy-session-key-registry.sh
+++ b/service_contracts/tools/deploy-session-key-registry.sh
@@ -9,6 +9,10 @@
 # - called from service_contracts directory
 # - PATH has forge and cast
 
+# Get script directory and source deployments.sh
+SCRIPT_DIR="$(dirname "${BASH_SOURCE[0]}")"
+source "$SCRIPT_DIR/deployments.sh"
+
 if [ -z "$ETH_RPC_URL" ]; then
   echo "Error: ETH_RPC_URL is not set"
   exit 1
@@ -23,6 +27,9 @@ if [ -z "$CHAIN" ]; then
   fi
 fi
 
+# Load deployment addresses from deployments.json
+load_deployment_addresses "$CHAIN"
+
 
 if [ -z "$ETH_KEYSTORE" ]; then
   echo "Error: ETH_KEYSTORE is not set"
@@ -42,6 +49,12 @@ export SESSION_KEY_REGISTRY_ADDRESS=$(forge create --password "$PASSWORD" --broa
 
 echo SessionKeyRegistry deployed at $SESSION_KEY_REGISTRY_ADDRESS
 
+# Update deployments.json
+if [ -n "$SESSION_KEY_REGISTRY_ADDRESS" ]; then
+    update_deployment_address "$CHAIN" "SESSION_KEY_REGISTRY_ADDRESS" "$SESSION_KEY_REGISTRY_ADDRESS"
+    update_deployment_metadata "$CHAIN"
+fi
+
 # Automatic contract verification
 if [ "${AUTO_VERIFY:-true}" = "true" ]; then
   echo
diff --git a/service_contracts/tools/deploy-warm-storage-calibnet.sh b/service_contracts/tools/deploy-warm-storage-calibnet.sh
index acb356e2..015e8a28 100755
--- a/service_contracts/tools/deploy-warm-storage-calibnet.sh
+++ b/service_contracts/tools/deploy-warm-storage-calibnet.sh
@@ -6,10 +6,16 @@
 # Assumption: called from contracts directory so forge paths work out
 #
 
+# Get script directory and source deployments.sh
+SCRIPT_DIR="$(dirname "${BASH_SOURCE[0]}")"
+source "$SCRIPT_DIR/deployments.sh"
+
 echo "Deploying Warm Storage Service Contract"
 
 export CHAIN=314159
 
+# Load deployment addresses from deployments.json
+load_deployment_addresses "$CHAIN"
 
 if [ -z "$ETH_RPC_URL" ]; then
   echo "Error: ETH_RPC_URL is not set"
@@ -145,18 +151,18 @@ NONCE=$(expr $NONCE + "1")
 echo "Deploying FilecoinWarmStorageService proxy..."
 # Initialize with max proving period, challenge window size, FilBeam controller address, name, and description
 INIT_DATA=$(cast calldata "initialize(uint64,uint256,address,string,string)" $MAX_PROVING_PERIOD $CHALLENGE_WINDOW_SIZE $FILBEAM_CONTROLLER_ADDRESS "$SERVICE_NAME" "$SERVICE_DESCRIPTION")
-WARM_STORAGE_SERVICE_ADDRESS=$(forge create --password "$PASSWORD" --broadcast --nonce $NONCE lib/pdp/src/ERC1967Proxy.sol:MyERC1967Proxy --constructor-args $SERVICE_PAYMENTS_IMPLEMENTATION_ADDRESS $INIT_DATA | grep "Deployed to" | awk '{print $3}')
-if [ -z "$WARM_STORAGE_SERVICE_ADDRESS" ]; then
+WARM_STORAGE_PROXY_ADDRESS=$(forge create --password "$PASSWORD" --broadcast --nonce $NONCE lib/pdp/src/ERC1967Proxy.sol:MyERC1967Proxy --constructor-args $SERVICE_PAYMENTS_IMPLEMENTATION_ADDRESS $INIT_DATA | grep "Deployed to" | awk '{print $3}')
+if [ -z "$WARM_STORAGE_PROXY_ADDRESS" ]; then
   echo "Error: Failed to extract FilecoinWarmStorageService proxy address"
   exit 1
 fi
-echo "FilecoinWarmStorageService proxy deployed at: $WARM_STORAGE_SERVICE_ADDRESS"
+echo "FilecoinWarmStorageService proxy deployed at: $WARM_STORAGE_PROXY_ADDRESS"
 
 # Summary of deployed contracts
 echo
 echo "# DEPLOYMENT SUMMARY"
 echo "FilecoinWarmStorageService Implementation: $SERVICE_PAYMENTS_IMPLEMENTATION_ADDRESS"
-echo "FilecoinWarmStorageService Proxy: $WARM_STORAGE_SERVICE_ADDRESS"
+echo "FilecoinWarmStorageService Proxy: $WARM_STORAGE_PROXY_ADDRESS"
 echo
 echo "USDFC token address: $USDFC_TOKEN_ADDRESS"
 echo "PDPVerifier address: $PDP_VERIFIER_PROXY_ADDRESS"
@@ -169,6 +175,20 @@ echo "Challenge window size: $CHALLENGE_WINDOW_SIZE epochs"
 echo "Service name: $SERVICE_NAME"
 echo "Service description: $SERVICE_DESCRIPTION"
 
+# Update deployments.json
+if [ -n "$SERVICE_PAYMENTS_IMPLEMENTATION_ADDRESS" ]; then
+    update_deployment_address "$CHAIN" "FWS_IMPLEMENTATION_ADDRESS" "$SERVICE_PAYMENTS_IMPLEMENTATION_ADDRESS"
+fi
+if [ -n "$WARM_STORAGE_PROXY_ADDRESS" ]; then
+    update_deployment_address "$CHAIN" "WARM_STORAGE_PROXY_ADDRESS" "$WARM_STORAGE_PROXY_ADDRESS"
+fi
+if [ -n "$SIGNATURE_VERIFICATION_LIB_ADDRESS" ]; then
+    update_deployment_address "$CHAIN" "SIGNATURE_VERIFICATION_LIB_ADDRESS" "$SIGNATURE_VERIFICATION_LIB_ADDRESS"
+fi
+if [ -n "$SERVICE_PAYMENTS_IMPLEMENTATION_ADDRESS" ] || [ -n "$WARM_STORAGE_PROXY_ADDRESS" ]; then
+    update_deployment_metadata "$CHAIN"
+fi
+
 # Automatic contract verification
 if [ "${AUTO_VERIFY:-true}" = "true" ]; then
   echo
diff --git a/service_contracts/tools/deploy-warm-storage-view.sh b/service_contracts/tools/deploy-warm-storage-view.sh
index ea26d4a5..1029c5aa 100755
--- a/service_contracts/tools/deploy-warm-storage-view.sh
+++ b/service_contracts/tools/deploy-warm-storage-view.sh
@@ -2,7 +2,7 @@
 
 # env params:
 # ETH_RPC_URL
-# WARM_STORAGE_SERVICE_ADDRESS
+# WARM_STORAGE_PROXY_ADDRESS
 # ETH_KEYSTORE
 # PASSWORD
 
@@ -24,8 +24,8 @@ if [ -z "$CHAIN" ]; then
   fi
 fi
 
-if [ -z "$WARM_STORAGE_SERVICE_ADDRESS" ]; then
-  echo "Error: WARM_STORAGE_SERVICE_ADDRESS is not set"
+if [ -z "$WARM_STORAGE_PROXY_ADDRESS" ]; then
+  echo "Error: WARM_STORAGE_PROXY_ADDRESS is not set"
   exit 1
 fi
 
@@ -43,7 +43,7 @@ if [ -z "$NONCE" ]; then
   NONCE="$(cast nonce "$ADDR")"
 fi
 
-export WARM_STORAGE_VIEW_ADDRESS=$(forge create --password "$PASSWORD" --broadcast --nonce $NONCE src/FilecoinWarmStorageServiceStateView.sol:FilecoinWarmStorageServiceStateView --constructor-args $WARM_STORAGE_SERVICE_ADDRESS | grep "Deployed to" | awk '{print $3}')
+export WARM_STORAGE_VIEW_ADDRESS=$(forge create --password "$PASSWORD" --broadcast --nonce $NONCE src/FilecoinWarmStorageServiceStateView.sol:FilecoinWarmStorageServiceStateView --constructor-args $WARM_STORAGE_PROXY_ADDRESS | grep "Deployed to" | awk '{print $3}')
 
 echo FilecoinWarmStorageServiceStateView deployed at $WARM_STORAGE_VIEW_ADDRESS
 
diff --git a/service_contracts/tools/deployments.sh b/service_contracts/tools/deployments.sh
new file mode 100755
index 00000000..d57c847f
--- /dev/null
+++ b/service_contracts/tools/deployments.sh
@@ -0,0 +1,206 @@
+#!/bin/bash
+# deployments.sh - Shared functions for loading and updating deployment addresses
+# 
+# This script provides functions to:
+# - Load deployment addresses from deployments.json (keyed by chain-id)
+# - Update deployment addresses in deployments.json when contracts are deployed
+# - Handle missing chains gracefully
+#
+# Usage:
+#   source "$(dirname "${BASH_SOURCE[0]}")/deployments.sh"
+#   load_deployment_addresses "$CHAIN"
+#   update_deployment_address "$CHAIN" "CONTRACT_NAME" "$ADDRESS"
+#
+# Environment variables:
+#   SKIP_LOAD_DEPLOYMENTS - If set to "true", skip loading from JSON (default: false)
+#   SKIP_UPDATE_DEPLOYMENTS - If set to "true", skip updating JSON (default: false)
+#   DEPLOYMENTS_JSON_PATH - Path to deployments.json (default: service_contracts/deployments.json)
+
+# Get the script directory to find deployments.json relative to tools/
+SCRIPT_DIR="$(dirname "${BASH_SOURCE[0]}")"
+DEPLOYMENTS_JSON_PATH="${DEPLOYMENTS_JSON_PATH:-$SCRIPT_DIR/../deployments.json}"
+
+# Ensure deployments.json exists with proper structure
+ensure_deployments_json() {
+    if [ ! -f "$DEPLOYMENTS_JSON_PATH" ]; then
+        echo "Creating deployments.json at $DEPLOYMENTS_JSON_PATH"
+        echo '{}' > "$DEPLOYMENTS_JSON_PATH"
+    fi
+    
+    # Ensure it's valid JSON
+    if ! jq empty "$DEPLOYMENTS_JSON_PATH" 2>/dev/null; then
+        echo "Error: deployments.json is not valid JSON"
+        exit 1
+    fi
+}
+
+# Load deployment addresses from deployments.json for a given chain
+# Args: $1=chain_id
+# Sets environment variables for all addresses found in the JSON
+load_deployment_addresses() {
+    local chain_id="$1"
+    
+    if [ -z "$chain_id" ]; then
+        echo "Error: chain_id is required for load_deployment_addresses"
+        return 1
+    fi
+    
+    # Check if we should skip loading
+    if [ "${SKIP_LOAD_DEPLOYMENTS:-false}" = "true" ]; then
+        echo "⏭️  Skipping loading from deployments.json (SKIP_LOAD_DEPLOYMENTS=true)"
+        return 0
+    fi
+    
+    ensure_deployments_json
+    
+    # Check if chain exists in JSON
+    if ! jq -e ".[\"$chain_id\"]" "$DEPLOYMENTS_JSON_PATH" > /dev/null 2>&1; then
+        echo "ℹ️  Chain $chain_id not found in deployments.json, will use environment variables"
+        return 0
+    fi
+    
+    echo "📖 Loading deployment addresses from deployments.json for chain $chain_id"
+    
+    # Load all addresses from the chain's section
+    # Extract all keys that are not "metadata"
+    local addresses=$(jq -r ".[\"$chain_id\"] | to_entries | .[] | select(.key != \"metadata\") | \"\(.key)=\(.value)\"" "$DEPLOYMENTS_JSON_PATH" 2>/dev/null)
+    
+    if [ -z "$addresses" ]; then
+        echo "ℹ️  No addresses found for chain $chain_id in deployments.json"
+        return 0
+    fi
+    
+    # Export each address as an environment variable
+    while IFS='=' read -r key value; do
+        if [ -n "$key" ] && [ -n "$value" ] && [ "$value" != "null" ]; then
+            # Only set if not already set (allow env vars to override)
+            if [ -z "${!key}" ]; then
+                export "$key=$value"
+                echo "  ✓ Loaded $key=$value"
+            else
+                echo "  ⊘ Skipped $key (already set to ${!key})"
+            fi
+        fi
+    done <<< "$addresses"
+}
+
+# Update a deployment address in deployments.json
+# Args: $1=chain_id, $2=contract_name (env var name), $3=address
+update_deployment_address() {
+    local chain_id="$1"
+    local contract_name="$2"
+    local address="$3"
+    
+    if [ -z "$chain_id" ]; then
+        echo "Error: chain_id is required for update_deployment_address"
+        return 1
+    fi
+    
+    if [ -z "$contract_name" ]; then
+        echo "Error: contract_name is required for update_deployment_address"
+        return 1
+    fi
+    
+    if [ -z "$address" ]; then
+        echo "Error: address is required for update_deployment_address"
+        return 1
+    fi
+    
+    # Check if we should skip updating
+    if [ "${SKIP_UPDATE_DEPLOYMENTS:-false}" = "true" ]; then
+        echo "⏭️  Skipping update to deployments.json (SKIP_UPDATE_DEPLOYMENTS=true)"
+        return 0
+    fi
+    
+    ensure_deployments_json
+    
+    echo "💾 Updating deployments.json: chain=$chain_id, contract=$contract_name, address=$address"
+    
+    # Update the JSON file using jq
+    # This ensures the chain entry exists and updates the specific contract address
+    local temp_file=$(mktemp)
+    jq --arg chain "$chain_id" \
+       --arg contract "$contract_name" \
+       --arg addr "$address" \
+       'if .[$chain] then .[$chain][$contract] = $addr else .[$chain] = {($contract): $addr} end' \
+       "$DEPLOYMENTS_JSON_PATH" > "$temp_file"
+    
+    if [ $? -ne 0 ]; then
+        echo "Error: Failed to update deployments.json"
+        rm -f "$temp_file"
+        return 1
+    fi
+    
+    mv "$temp_file" "$DEPLOYMENTS_JSON_PATH"
+    echo "  ✓ Updated $contract_name=$address for chain $chain_id"
+}
+
+# Update deployment metadata (commit hash, deployment timestamp, etc.)
+# Args: $1=chain_id, $2=commit_hash (optional), $3=deployed_at (optional, defaults to current timestamp)
+update_deployment_metadata() {
+    local chain_id="$1"
+    local commit_hash="${2:-}"
+    local deployed_at="${3:-$(date -u +"%Y-%m-%dT%H:%M:%SZ")}"
+    
+    if [ -z "$chain_id" ]; then
+        echo "Error: chain_id is required for update_deployment_metadata"
+        return 1
+    fi
+    
+    # Check if we should skip updating
+    if [ "${SKIP_UPDATE_DEPLOYMENTS:-false}" = "true" ]; then
+        return 0
+    fi
+    
+    ensure_deployments_json
+    
+    # Get current commit hash if not provided
+    if [ -z "$commit_hash" ]; then
+        if command -v git >/dev/null 2>&1; then
+            commit_hash=$(git rev-parse HEAD 2>/dev/null || echo "")
+        fi
+    fi
+    
+    local temp_file=$(mktemp)
+    local jq_cmd="if .[\"$chain_id\"] then .[\"$chain_id\"].metadata = {} else .[\"$chain_id\"] = {metadata: {}} end"
+    
+    if [ -n "$commit_hash" ]; then
+        jq_cmd="$jq_cmd | .[\"$chain_id\"].metadata.commit = \"$commit_hash\""
+    fi
+    
+    jq_cmd="$jq_cmd | .[\"$chain_id\"].metadata.deployed_at = \"$deployed_at\""
+    
+    jq "$jq_cmd" "$DEPLOYMENTS_JSON_PATH" > "$temp_file"
+    
+    if [ $? -ne 0 ]; then
+        echo "Error: Failed to update deployment metadata"
+        rm -f "$temp_file"
+        return 1
+    fi
+    
+    mv "$temp_file" "$DEPLOYMENTS_JSON_PATH"
+    
+    if [ -n "$commit_hash" ]; then
+        echo "  ✓ Updated metadata: commit=$commit_hash, deployed_at=$deployed_at"
+    else
+        echo "  ✓ Updated metadata: deployed_at=$deployed_at"
+    fi
+}
+
+# Get a deployment address from JSON (useful for scripts that just need to read)
+# Args: $1=chain_id, $2=contract_name
+# Outputs: address or empty string if not found
+get_deployment_address() {
+    local chain_id="$1"
+    local contract_name="$2"
+    
+    if [ -z "$chain_id" ] || [ -z "$contract_name" ]; then
+        return 1
+    fi
+    
+    ensure_deployments_json
+    
+    jq -r ".[\"$chain_id\"][\"$contract_name\"] // empty" "$DEPLOYMENTS_JSON_PATH" 2>/dev/null
+}
+
+
diff --git a/service_contracts/tools/set-warm-storage-view.sh b/service_contracts/tools/set-warm-storage-view.sh
index 731e4506..41e71300 100755
--- a/service_contracts/tools/set-warm-storage-view.sh
+++ b/service_contracts/tools/set-warm-storage-view.sh
@@ -5,7 +5,7 @@
 #
 # Environment variables required:
 # - ETH_RPC_URL: RPC endpoint URL
-# - WARM_STORAGE_SERVICE_ADDRESS: Address of the deployed FilecoinWarmStorageService proxy
+# - WARM_STORAGE_PROXY_ADDRESS: Address of the deployed FilecoinWarmStorageService proxy
 # - WARM_STORAGE_VIEW_ADDRESS: Address of the deployed FilecoinWarmStorageServiceStateView
 # - ETH_KEYSTORE: Path to keystore file
 # - PASSWORD: Keystore password
@@ -25,8 +25,8 @@ if [ -z "$CHAIN" ]; then
   fi
 fi
 
-if [ -z "$WARM_STORAGE_SERVICE_ADDRESS" ]; then
-  echo "Error: WARM_STORAGE_SERVICE_ADDRESS is not set"
+if [ -z "$WARM_STORAGE_PROXY_ADDRESS" ]; then
+  echo "Error: WARM_STORAGE_PROXY_ADDRESS is not set"
   exit 1
 fi
 
@@ -51,7 +51,7 @@ fi
 echo "Setting view contract address on FilecoinWarmStorageService..."
 
 # Execute transaction and capture output, only show errors if it fails
-TX_OUTPUT=$(cast send --password "$PASSWORD" --nonce $NONCE $WARM_STORAGE_SERVICE_ADDRESS "setViewContract(address)" $WARM_STORAGE_VIEW_ADDRESS 2>&1)
+TX_OUTPUT=$(cast send --password "$PASSWORD" --nonce $NONCE $WARM_STORAGE_PROXY_ADDRESS "setViewContract(address)" $WARM_STORAGE_VIEW_ADDRESS 2>&1)
 
 if [ $? -eq 0 ]; then
     echo "View contract address set successfully"
diff --git a/service_contracts/tools/upgrade-registry.sh b/service_contracts/tools/upgrade-registry.sh
index f891d764..d35e46dd 100755
--- a/service_contracts/tools/upgrade-registry.sh
+++ b/service_contracts/tools/upgrade-registry.sh
@@ -1,10 +1,14 @@
 #!/bin/bash
 
 # upgrade-registry.sh: Completes a pending upgrade for ServiceProviderRegistry
-# Required args: ETH_RPC_URL, REGISTRY_PROXY_ADDRESS, ETH_KEYSTORE, PASSWORD, NEW_REGISTRY_IMPLEMENTATION_ADDRESS
+# Required args: ETH_RPC_URL, SERVICE_PROVIDER_REGISTRY_PROXY_ADDRESS, ETH_KEYSTORE, PASSWORD, NEW_REGISTRY_IMPLEMENTATION_ADDRESS
 # Optional args: NEW_VERSION
 # Calculated if unset: CHAIN
 
+# Get script directory and source deployments.sh
+SCRIPT_DIR="$(dirname "${BASH_SOURCE[0]}")"
+source "$SCRIPT_DIR/deployments.sh"
+
 if [ -z "$ETH_RPC_URL" ]; then
   echo "Error: ETH_RPC_URL is not set"
   exit 1
@@ -28,18 +32,21 @@ if [ -z "$CHAIN" ]; then
   fi
 fi
 
+# Load deployment addresses from deployments.json
+load_deployment_addresses "$CHAIN"
+
 ADDR=$(cast wallet address --password "$PASSWORD")
 echo "Using owner address: $ADDR"
 
 # Get current nonce
 NONCE=$(cast nonce "$ADDR")
 
-if [ -z "$REGISTRY_PROXY_ADDRESS" ]; then
-  echo "Error: REGISTRY_PROXY_ADDRESS is not set"
+if [ -z "$SERVICE_PROVIDER_REGISTRY_PROXY_ADDRESS" ]; then
+  echo "Error: SERVICE_PROVIDER_REGISTRY_PROXY_ADDRESS is not set"
   exit 1
 fi
 
-PROXY_OWNER=$(cast call -f 0x0000000000000000000000000000000000000000 "$REGISTRY_PROXY_ADDRESS" "owner()(address)" 2>/dev/null)
+PROXY_OWNER=$(cast call -f 0x0000000000000000000000000000000000000000 "$SERVICE_PROVIDER_REGISTRY_PROXY_ADDRESS" "owner()(address)" 2>/dev/null)
 if [ "$PROXY_OWNER" != "$ADDR" ]; then
   echo "Supplied ETH_KEYSTORE ($ADDR) is not the proxy owner ($PROXY_OWNER)."
   exit 1
@@ -47,7 +54,7 @@ fi
 
 # Get the upgrade plan (if any)
 # Try to call nextUpgrade() - this will fail if the method doesn't exist (old contracts)
-UPGRADE_PLAN_OUTPUT=$(cast call -f 0x0000000000000000000000000000000000000000 "$REGISTRY_PROXY_ADDRESS" "nextUpgrade()(address,uint96)" 2>&1)
+UPGRADE_PLAN_OUTPUT=$(cast call -f 0x0000000000000000000000000000000000000000 "$SERVICE_PROVIDER_REGISTRY_PROXY_ADDRESS" "nextUpgrade()(address,uint96)" 2>&1)
 CAST_CALL_EXIT_CODE=$?
 
 ZERO_ADDRESS="0x0000000000000000000000000000000000000000"
@@ -103,7 +110,7 @@ fi
 
 # Call upgradeToAndCall on the proxy with migrate function
 echo "Upgrading proxy and calling migrate..."
-TX_HASH=$(cast send "$REGISTRY_PROXY_ADDRESS" "upgradeToAndCall(address,bytes)" "$NEW_REGISTRY_IMPLEMENTATION_ADDRESS" "$MIGRATE_DATA" \
+TX_HASH=$(cast send "$SERVICE_PROVIDER_REGISTRY_PROXY_ADDRESS" "upgradeToAndCall(address,bytes)" "$NEW_REGISTRY_IMPLEMENTATION_ADDRESS" "$MIGRATE_DATA" \
   --password "$PASSWORD" \
   --nonce "$NONCE" \
   --json | jq -r '.transactionHash')
@@ -125,13 +132,19 @@ cast receipt "$TX_HASH" --confirmations 1 > /dev/null
 
 # Verify the upgrade by checking the implementation address
 echo "Verifying upgrade..."
-NEW_IMPL=$(cast rpc eth_getStorageAt "$REGISTRY_PROXY_ADDRESS" 0x360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc latest | sed 's/"//g' | sed 's/0x000000000000000000000000/0x/')
+NEW_IMPL=$(cast rpc eth_getStorageAt "$SERVICE_PROVIDER_REGISTRY_PROXY_ADDRESS" 0x360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc latest | sed 's/"//g' | sed 's/0x000000000000000000000000/0x/')
 
 # Compare to lowercase
 export EXPECTED_IMPL=$(echo $NEW_REGISTRY_IMPLEMENTATION_ADDRESS | tr '[:upper:]' '[:lower:]')
 
 if [ "$NEW_IMPL" = "$EXPECTED_IMPL" ]; then
     echo "✅ Upgrade successful! Proxy now points to: $NEW_REGISTRY_IMPLEMENTATION_ADDRESS"
+    
+    # Update deployments.json with new implementation address
+    if [ -n "$NEW_REGISTRY_IMPLEMENTATION_ADDRESS" ]; then
+        update_deployment_address "$CHAIN" "REGISTRY_IMPLEMENTATION_ADDRESS" "$NEW_REGISTRY_IMPLEMENTATION_ADDRESS"
+    fi
+    update_deployment_metadata "$CHAIN"
 else
     echo "⚠️  Warning: Could not verify upgrade. Please check manually."
     echo "Expected: $NEW_REGISTRY_IMPLEMENTATION_ADDRESS"
diff --git a/service_contracts/tools/upgrade.sh b/service_contracts/tools/upgrade.sh
index 0d06edbb..30648638 100755
--- a/service_contracts/tools/upgrade.sh
+++ b/service_contracts/tools/upgrade.sh
@@ -5,6 +5,10 @@
 # Optional args: NEW_WARM_STORAGE_VIEW_ADDRESS
 # Calculated if unset: CHAIN, WARM_STORAGE_VIEW_ADDRESS
 
+# Get script directory and source deployments.sh
+SCRIPT_DIR="$(dirname "${BASH_SOURCE[0]}")"
+source "$SCRIPT_DIR/deployments.sh"
+
 if [ -z "$NEW_WARM_STORAGE_VIEW_ADDRESS" ]; then
   echo "Warning: NEW_WARM_STORAGE_VIEW_ADDRESS is not set. Keeping previous view contract." 
 fi
@@ -32,6 +36,9 @@ if [ -z "$CHAIN" ]; then
   fi
 fi
 
+# Load deployment addresses from deployments.json
+load_deployment_addresses "$CHAIN"
+
 ADDR=$(cast wallet address --password "$PASSWORD")
 echo "Using owner address: $ADDR"
 
@@ -114,6 +121,15 @@ export EXPECTED_IMPL=$(echo $NEW_WARM_STORAGE_IMPLEMENTATION_ADDRESS | tr '[:upp
 
 if [ "$NEW_IMPL" = "$EXPECTED_IMPL" ]; then
     echo "✅ Upgrade successful! Proxy now points to: $NEW_WARM_STORAGE_IMPLEMENTATION_ADDRESS"
+    
+    # Update deployments.json with new implementation address
+    if [ -n "$NEW_WARM_STORAGE_IMPLEMENTATION_ADDRESS" ]; then
+        update_deployment_address "$CHAIN" "FWS_IMPLEMENTATION_ADDRESS" "$NEW_WARM_STORAGE_IMPLEMENTATION_ADDRESS"
+    fi
+    if [ -n "$NEW_WARM_STORAGE_VIEW_ADDRESS" ]; then
+        update_deployment_address "$CHAIN" "WARM_STORAGE_VIEW_ADDRESS" "$NEW_WARM_STORAGE_VIEW_ADDRESS"
+    fi
+    update_deployment_metadata "$CHAIN"
 else
     echo "⚠️  Warning: Could not verify upgrade. Please check manually."
     echo "Expected: $NEW_WARM_STORAGE_IMPLEMENTATION_ADDRESS"