feat: automatic deployment address management via deployments.json

service_contracts/deployments.json

@@ -0,0 +1,23 @@
+{
+  "314": {
+    "metadata": {
+      "note": "Filecoin mainnet deployments"
+    }
+  },
+  "314159": {
+    "metadata": {
+      "commit": "c633ae464d1581b5b1c6d651eed5bcc8e1178366",
+      "deployed_at": "2025-11-27T18:27:39Z"
+    },
+    "SESSION_KEY_REGISTRY_ADDRESS": "0x1fd7552F4fED1Be6a8e6d706f5B77B851a5d5F57",
+    "VERIFIER_IMPLEMENTATION_ADDRESS": "0xdd40a981C81397F88Dc3CdBc1Be169B46887a0ba",
+    "PDP_VERIFIER_ADDRESS": "0xD05E5d5511Ef352dAa94B320f8DfA1A81a8BfcB9",
+    "PAYMENTS_CONTRACT_ADDRESS": "0x0B91e3d578fe2A9b2442B2A5dEC3c980C2b855c5",
+    "REGISTRY_IMPLEMENTATION_ADDRESS": "0x311aFC5AF4347C7401B01BfC8DE6A89a28AC1485",
+    "SERVICE_PROVIDER_REGISTRY_PROXY_ADDRESS": "0xAb3f97FA4989bE446C75447d826131E78dC291B2",
+    "SIGNATURE_VERIFICATION_LIB_ADDRESS": "0xafb50cEA38cAF480bABF5EDd0e290E8B764aF6c1",
+    "FWS_IMPLEMENTATION_ADDRESS": "0xb07bA4811770fC65F6e1cdDdbe5f7f55e5362970",
+    "WARM_STORAGE_SERVICE_ADDRESS": "0xA755Ece81e0376A5Dff99Ae8682527D258fFDFE2",
+    "WARM_STORAGE_VIEW_ADDRESS": "0x4e3e6B7862a6DEda1049A9bE69f4E4042491760f"
+  }
+}

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_SERVICE_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_SERVICE_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:

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
 }
@@ -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
 
@@ -485,3 +511,10 @@ if [ "$DRY_RUN" = "false" ] && [ "${AUTO_VERIFY:-true}" = "true" ]; then
 
     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

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"

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

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"
@@ -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_SERVICE_ADDRESS" ]; then
+    update_deployment_address "$CHAIN" "WARM_STORAGE_SERVICE_ADDRESS" "$WARM_STORAGE_SERVICE_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_SERVICE_ADDRESS" ]; then
+    update_deployment_metadata "$CHAIN"
+fi
+
 # Automatic contract verification
 if [ "${AUTO_VERIFY:-true}" = "true" ]; then
   echo