docs: consolidate deployment docs to eliminate duplication (#253)

Closes: #221 

Consolidate deployment docs to eliminate duplication, and document the
different deployment parameters for Calibration and Mainnet.

Author: rjan90

README.md

@@ -122,20 +122,9 @@ Run `make help` to see all available targets:
 make help
 ```
 
-### Deployment
+## 🚀 Deployment
 
-Use the provided deployment scripts in the `tools/` directory:
-
-```bash
-# Deploy to Calibnet
-./tools/deploy-warm-storage-calibnet.sh
-
-# Deploy all contracts
-./tools/deploy-all-warm-storage-calibnet.sh
-
-# Upgrade existing deployment
-./tools/upgrade-warm-storage-calibnet.sh
-```
+For comprehensive deployment instructions, parameters, and scripts, see [service_contracts/tools/README.md](./service_contracts/tools/README.md).
 
 ## 🔗 Dependencies
 

service_contracts/tools/README.md

@@ -1,13 +1,54 @@
 # FilecoinWarmStorageService Deployment Scripts
 
-This directory contains scripts for deploying and upgrading the FilecoinWarmStorageService contract on Calibration testnet.
+This directory contains scripts for deploying and upgrading the FilecoinWarmStorageService contract on Calibration testnet and Mainnet.
 
 ## Scripts Overview
 
+### Available Scripts
+
 - `deploy-warm-storage-calibnet.sh` - Deploy FilecoinWarmStorageService only (requires existing PDPVerifier and Payments contracts)
-- `deploy-all-warm-storage-calibnet.sh` - Deploy all contracts (PDPVerifier, Payments, and FilecoinWarmStorageService)
+- `deploy-all-warm-storage.sh` - Deploy all contracts to either Calibnet or Mainnet
 - `upgrade-warm-storage-calibnet.sh` - Upgrade existing FilecoinWarmStorageService contract with new proving period parameters
 
+### Usage
+
+```bash
+# Deploy to Calibnet
+./tools/deploy-warm-storage-calibnet.sh
+
+# Deploy all contracts
+./tools/deploy-all-warm-storage.sh
+
+# Upgrade existing deployment
+./tools/upgrade-warm-storage-calibnet.sh
+```
+
+## Deployment Parameters
+
+The following parameters are critical for proof generation and validation. They differ between **Mainnet** (production) and **Calibnet** (testing/iteration).
+
+| Parameter | Mainnet (Production) | Calibnet (Testing) | Notes |
+|-----------|----------------------|---------------------|-------|
+| `DEFAULT_CHALLENGE_FINALITY` | `150` | `10` | **Security parameter.** Always set to `150` in production. Enforces that the challenge epoch is far enough in the future to prevent reorg-based attacks. See [PDP Implementation Design Doc](https://filoznotebook.notion.site/PDP-Implementation-Design-Doc-64a66516416441c69b9d8e5d63120f1c?pvs=21). |
+| `DEFAULT_MAX_PROVING_PERIOD` | `2880` | `240` | **Product parameter.** Defines how often proofs must be submitted. Mainnet default is 2880 epochs ≈ 24h (one proof/day). On Calibnet we use shorter proving periods for faster iteration. See [Simple PDP Service Fault Model](https://filoznotebook.notion.site/Simple-PDP-Service-Fault-Model-1a9dc41950c180c4bdc7ef2d91db73b6?pvs=21). |
+| `DEFAULT_CHALLENGE_WINDOW_SIZE` | `60` | `30` | **Security parameter.** Defines the grace window within the proving period. Typically ~2% of the proving period. On Mainnet: 60 epochs (≈2% of 2880). On Calibnet: 30 epochs. See [Simple PDP Service Fault Model](https://filoznotebook.notion.site/Simple-PDP-Service-Fault-Model-1a9dc41950c180c4bdc7ef2d91db73b6?pvs=21). |
+
+### Quick Reference
+
+- **Mainnet**
+  ```bash
+  DEFAULT_CHALLENGE_FINALITY="150"       # Production security value
+  DEFAULT_MAX_PROVING_PERIOD="2880"      # 2880 epochs (≈1 proof per day)
+  DEFAULT_CHALLENGE_WINDOW_SIZE="60"     # 60 epochs grace period
+  ```
+
+- **Calibnet**
+  ```bash
+  DEFAULT_CHALLENGE_FINALITY="10"        # Low value for fast testing (should be 150 in production)
+  DEFAULT_MAX_PROVING_PERIOD="240"       # 240 epochs
+  DEFAULT_CHALLENGE_WINDOW_SIZE="30"     # 30 epochs
+  ```
+
 ## Environment Variables
 
 ### Required for all scripts:
@@ -20,16 +61,12 @@ This directory contains scripts for deploying and upgrading the FilecoinWarmStor
   - `PDP_VERIFIER_ADDRESS` - Address of deployed PDPVerifier contract
   - `PAYMENTS_CONTRACT_ADDRESS` - Address of deployed Payments contract
 
-- `deploy-all-warm-storage-calibnet.sh` requires:
+- `deploy-all-warm-storage.sh` requires:
   - `CHALLENGE_FINALITY` - Challenge finality parameter for PDPVerifier
 
 - `upgrade-warm-storage-calibnet.sh` requires:
   - `WARM_STORAGE_SERVICE_PROXY_ADDRESS` - Address of existing FilecoinWarmStorageService proxy to upgrade
 
-### Optional proving period configuration:
-- `MAX_PROVING_PERIOD` - Maximum epochs between proofs (default: 30 epochs = 15 minutes on calibnet)
-- `CHALLENGE_WINDOW_SIZE` - Challenge window size in epochs (default: 15 epochs)
-
 ## Usage Examples
 
 ### Fresh Deployment (All Contracts)
@@ -38,13 +75,13 @@ This directory contains scripts for deploying and upgrading the FilecoinWarmStor
 export KEYSTORE="/path/to/keystore.json"
 export PASSWORD="your-password"
 export RPC_URL="https://api.calibration.node.glif.io/rpc/v1"
-export CHALLENGE_FINALITY="900"
+export CHALLENGE_FINALITY="10"  # Use "150" for mainnet
 
 # Optional: Custom proving periods
-export MAX_PROVING_PERIOD="60"        # 30 minutes instead of default 15 minutes
-export CHALLENGE_WINDOW_SIZE="20"     # 20 epochs instead of default 15
+export MAX_PROVING_PERIOD="240"        # 240 epochs for calibnet, 2880 for mainnet
+export CHALLENGE_WINDOW_SIZE="30"      # 30 epochs for calibnet, 60 for mainnet
 
-./deploy-all-warm-storage-calibnet.sh
+./deploy-all-warm-storage.sh
 ```
 
 ### Deploy FilecoinWarmStorageService Only
@@ -67,9 +104,9 @@ export PASSWORD="your-password"
 export RPC_URL="https://api.calibration.node.glif.io/rpc/v1"
 export WARM_STORAGE_SERVICE_PROXY_ADDRESS="0x789..."
 
-# Optional: Set new proving period parameters
-export MAX_PROVING_PERIOD="120"       # 1 hour
-export CHALLENGE_WINDOW_SIZE="30"     # 30 epochs
+# Optional: Custom proving periods
+export MAX_PROVING_PERIOD="240"        # 240 epochs for calibnet, 2880 for mainnet
+export CHALLENGE_WINDOW_SIZE="30"      # 30 epochs for calibnet, 60 for mainnet
 
 ./upgrade-warm-storage-calibnet.sh
 ```
@@ -81,23 +118,6 @@ The FilecoinWarmStorageService contract uses OpenZeppelin's upgradeable pattern.
 1. **Deploy new implementation**: The script deploys a new implementation contract
 2. **Upgrade proxy**: Uses `upgradeToAndCall` to point the proxy to the new implementation
 
-### Important Notes for Upgrades:
-
-- The original `initialize` function can only be called once during initial deployment
-- Use `configureProvingPeriod` to set the new proving period parameters
-- Storage layout is preserved - new variables are added at the end of existing storage
-
-## Proving Period Parameters
-
-- **Max Proving Period**: Maximum number of epochs between consecutive proofs
-  - Calibnet default: 30 epochs (≈15 minutes, since calibnet has ~30 second epochs)
-  - Mainnet typical: 2880 epochs (≈24 hours, since mainnet has ~30 second epochs)
-
-- **Challenge Window Size**: Number of epochs at the end of each proving period during which proofs can be submitted
-  - Calibnet default: 15 epochs
-  - Must be less than Max Proving Period
-  - Must be greater than 0
-
 ## Testing
 
 Run the upgrade tests:

service_contracts/tools/deploy-all-warm-storage.sh

@@ -39,8 +39,7 @@ if [ -z "$CHAIN_ID" ]; then
 fi
 
 # Set network-specific configuration based on chain ID
-# NOTE: CHALLENGE_FINALITY should always be 150 in production for security.
-# Calibnet uses lower values for faster testing and development.
+# See service_contracts/tools/README.md for deployment parameter documentation
 case "$CHAIN_ID" in
   "314159")
     NETWORK_NAME="calibnet"
@@ -128,6 +127,7 @@ if [ "$MAX_PROVING_PERIOD" -lt "$MIN_REQUIRED" ]; then
     echo "Error: MAX_PROVING_PERIOD ($MAX_PROVING_PERIOD) is too small for CHALLENGE_FINALITY ($CHALLENGE_FINALITY)"
     echo "       MAX_PROVING_PERIOD must be at least $MIN_REQUIRED (CHALLENGE_FINALITY + CHALLENGE_WINDOW_SIZE/2)"
     echo "       Either increase MAX_PROVING_PERIOD or decrease CHALLENGE_FINALITY"
+    echo "       See service_contracts/tools/README.md for deployment parameter guidelines."
     exit 1
 fi