Skip to content

Commit 0ab88d3

Browse files
rjan90CopilotBigLepDarkLord017claude
authored
feat: v1.1.0 FWSS upgrade scripts and documentation (#384)
Closes: #346, #358, #393, #394 Kind of a large PR, that expanded in size due to encountering issues with scripts along the way. But high-level changes are: ### Version updates - `FilecoinWarmStorageService`: 1.0.0 → 1.1.0 - `ServiceProviderRegistry`: 1.0.0 → 1.1.0 - Updated test assertions to match new version ### Deployment infrastructure - Added automatic deployments.json integration to a couple of deployment scripts I used during the contract deployment - Added loading defaults from `deployments.json` and persist new addresses to some scripts I used during the upgrade. ### Script enhancements - `deploy-warm-storage-implementation-only.sh`: - Network-specific USDFC token address handling (devnet/calibnet/mainnet) - Automatic SignatureVerificationLib deployment tracking - Deployment address persistence - `deploy-warm-storage-view.sh`: - Added deployments.json integration - Automatic address persistence - `set-warm-storage-view.sh`: - Added deployments.json integration - Updates view address in deployments file - `deploy-registry.sh` - Updated to be network agnostic (removed the deploy-registry-calibnet.sh) - Supports implementation-only or full proxy deployment modes - deployments.json integration ### GitHub workflow - New workflow: .github/workflows/upgrade-announcement.yml - Creates upgrade announcement issues automatically - Supports multiple contract selection (FWSS, Registry, StateView) - Calculates estimated execution time from epoch - Formats changes summary from pipe-separated input - Generates issues matching the template in UPGRADE-PROCESS.md ### Documentation - Changelog - Added v1.1.0 entry with: - Added features (ProviderIdSet, upgrade flows, devnet support) - Breaking changes (deployment key renames, rail settlement requirements) - Bug fixes and documentation updates --------- Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Co-authored-by: Steve Loeppky <biglep@filoz.org> Co-authored-by: Sambhav Jain <136801346+DarkLord017@users.noreply.github.com> Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
1 parent 252f376 commit 0ab88d3

23 files changed

+1168
-225
lines changed

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

Lines changed: 440 additions & 0 deletions
Large diffs are not rendered by default.

‎.github/workflows/create-upgrade-announcement-issue.yml‎

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
name: Create Release Issue
2+
3+
on:
4+
workflow_dispatch:
5+
inputs:
6+
network:
7+
description: 'Target network'
8+
required: true
9+
type: choice
10+
options:
11+
- Calibnet
12+
- Mainnet
13+
upgrade_type:
14+
description: 'Type of upgrade'
15+
required: true
16+
type: choice
17+
options:
18+
- Routine
19+
- Breaking Change
20+
upgrade_registry:
21+
description: '(Rare) Also upgrading ServiceProviderRegistry?'
22+
required: false
23+
type: boolean
24+
default: false
25+
upgrade_state_view:
26+
description: '(Rare) Also redeploying FilecoinWarmStorageServiceStateView?'
27+
required: false
28+
type: boolean
29+
default: false
30+
after_epoch:
31+
description: 'AFTER_EPOCH (block number after which upgrade can execute)'
32+
required: true
33+
type: string
34+
changelog_pr:
35+
description: 'PR number with changelog updates'
36+
required: true
37+
type: string
38+
changes_summary:
39+
description: 'Summary of changes (use | for multiple lines)'
40+
required: true
41+
type: string
42+
action_required:
43+
description: 'Action required for integrators (or "None" if no action needed)'
44+
required: true
45+
type: string
46+
default: 'None'
47+
release_tag:
48+
description: 'Release tag if already created (usually added after upgrade completes)'
49+
required: false
50+
type: string
51+
dry_run:
52+
description: 'Dry run (preview issue without creating)'
53+
required: false
54+
type: boolean
55+
default: false
56+
57+
jobs:
58+
create-announcement:
59+
runs-on: ubuntu-latest
60+
permissions:
61+
issues: write
62+
steps:
63+
- name: Checkout
64+
uses: actions/checkout@v4
65+
66+
- name: Setup Node.js
67+
uses: actions/setup-node@v4
68+
with:
69+
node-version: '20'
70+
71+
- name: Create announcement issue
72+
id: create_issue
73+
env:
74+
NETWORK: ${{ inputs.network }}
75+
UPGRADE_TYPE: ${{ inputs.upgrade_type }}
76+
UPGRADE_REGISTRY: ${{ inputs.upgrade_registry }}
77+
UPGRADE_STATE_VIEW: ${{ inputs.upgrade_state_view }}
78+
AFTER_EPOCH: ${{ inputs.after_epoch }}
79+
CHANGELOG_PR: ${{ inputs.changelog_pr }}
80+
CHANGES_SUMMARY: ${{ inputs.changes_summary }}
81+
ACTION_REQUIRED: ${{ inputs.action_required }}
82+
RELEASE_TAG: ${{ inputs.release_tag }}
83+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
84+
GITHUB_REPOSITORY: ${{ github.repository }}
85+
run: |
86+
if [ "${{ inputs.dry_run }}" = "true" ]; then
87+
node .github/scripts/create-upgrade-announcement.js --dry-run
88+
else
89+
node .github/scripts/create-upgrade-announcement.js
90+
fi
91+
92+
- name: Summary
93+
run: |
94+
echo "## Release Issue ${{ inputs.dry_run == true && '(Dry Run)' || 'Created' }}" >> $GITHUB_STEP_SUMMARY
95+
echo "" >> $GITHUB_STEP_SUMMARY
96+
echo "**Network**: ${{ inputs.network }}" >> $GITHUB_STEP_SUMMARY
97+
echo "**After Epoch**: ${{ inputs.after_epoch }}" >> $GITHUB_STEP_SUMMARY
98+
echo "" >> $GITHUB_STEP_SUMMARY
99+
if [ "${{ inputs.dry_run }}" = "true" ]; then
100+
echo "This was a dry run. No issue was created." >> $GITHUB_STEP_SUMMARY
101+
else
102+
echo "See the created issue for full details." >> $GITHUB_STEP_SUMMARY
103+
fi

‎service_contracts/README.md‎

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

‎service_contracts/src/FilecoinWarmStorageService.sol‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -60,7 +60,7 @@ contract FilecoinWarmStorageService is
6060
EIP712Upgradeable
6161
{
6262
// Version tracking
63-
string public constant VERSION = "1.0.0";
63+
string public constant VERSION = "1.1.0";
6464

6565
// =========================================================================
6666
// Events

‎service_contracts/src/ServiceProviderRegistry.sol‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -43,7 +43,7 @@ contract ServiceProviderRegistry is
4343
}
4444

4545
/// @notice Version of the contract implementation
46-
string public constant VERSION = "1.0.0";
46+
string public constant VERSION = "1.1.0";
4747

4848
/// @notice Maximum length for service URL
4949
uint256 private constant MAX_SERVICE_URL_LENGTH = 256;

‎service_contracts/test/FilecoinWarmStorageService.t.sol‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5387,7 +5387,7 @@ contract FilecoinWarmStorageServiceUpgradeTest is Test {
53875387
if (logs[i].topics[0] == expectedTopic) {
53885388
// Decode and verify the event data
53895389
(string memory version, address implementation) = abi.decode(logs[i].data, (string, address));
5390-
assertEq(version, "1.0.0", "Version should be 1.0.0");
5390+
assertEq(version, "1.1.0", "Version should be 1.1.0");
53915391
assertTrue(implementation != address(0), "Implementation address should not be zero");
53925392
foundEvent = true;
53935393
break;

‎service_contracts/test/ServiceProviderRegistry.t.sol‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -38,7 +38,7 @@ contract ServiceProviderRegistryTest is MockFVMTest {
3838

3939
function testInitialState() public view {
4040
// Check version
41-
assertEq(registry.VERSION(), "1.0.0", "Version should be 1.0.0");
41+
assertEq(registry.VERSION(), "1.1.0", "Version should be 1.1.0");
4242

4343
// Check owner
4444
assertEq(registry.owner(), owner, "Service provider should be deployer");

‎service_contracts/test/ServiceProviderRegistryFull.t.sol‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -85,7 +85,7 @@ contract ServiceProviderRegistryFullTest is MockFVMTest {
8585
// ========== Initial State Tests ==========
8686

8787
function testInitialState() public view {
88-
assertEq(registry.VERSION(), "1.0.0", "Version should be 1.0.0");
88+
assertEq(registry.VERSION(), "1.1.0", "Version should be 1.1.0");
8989
assertEq(registry.owner(), owner, "Service provider should be deployer");
9090
assertEq(registry.getNextProviderId(), 1, "Next provider ID should start at 1");
9191
assertEq(registry.REGISTRATION_FEE(), 5 ether, "Registration fee should be 5 FIL");

‎service_contracts/tools/README.md‎

Lines changed: 54 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -2,25 +2,51 @@
22

33
This directory contains scripts for deploying and upgrading the FilecoinWarmStorageService contract on Calibration testnet and Mainnet.
44

5+
> **For detailed upgrade procedures**, see [UPGRADE-PROCESS.md](./UPGRADE-PROCESS.md).
6+
57
## Scripts Overview
68

7-
### Available Scripts
9+
Scripts are organized with prefixes for better discoverability:
10+
11+
### Warm Storage Scripts
12+
13+
| Script | Description |
14+
|--------|-------------|
15+
| `warm-storage-deploy-all.sh` | Deploy all contracts (PDPVerifier, FilecoinPayV1, FWSS, etc.) |
16+
| `warm-storage-deploy-implementation.sh` | Deploy FWSS implementation only (for upgrades) |
17+
| `warm-storage-deploy-view.sh` | Deploy FilecoinWarmStorageServiceStateView |
18+
| `warm-storage-deploy-calibnet.sh` | Deploy FWSS only (requires existing dependencies) |
19+
| `warm-storage-announce-upgrade.sh` | Announce a planned FWSS upgrade |
20+
| `warm-storage-execute-upgrade.sh` | Execute a previously announced FWSS upgrade |
21+
| `warm-storage-set-view.sh` | Set the StateView address on FWSS |
22+
23+
### Service Provider Registry Scripts
24+
25+
| Script | Description |
26+
|--------|-------------|
27+
| `service-provider-registry-deploy.sh` | Deploy ServiceProviderRegistry |
28+
| `service-provider-registry-announce-upgrade.sh` | Announce a planned registry upgrade |
29+
| `service-provider-registry-execute-upgrade.sh` | Execute a previously announced registry upgrade |
30+
31+
### Other Scripts
832

9-
- `deploy-warm-storage-calibnet.sh` - Deploy FilecoinWarmStorageService only (requires existing PDPVerifier and FilecoinPayV1 contracts)
10-
- `deploy-all-warm-storage.sh` - Deploy all contracts to either Calibnet or Mainnet
11-
- `upgrade-warm-storage-calibnet.sh` - Upgrade existing FilecoinWarmStorageService contract with new proving period parameters
33+
| Script | Description |
34+
|--------|-------------|
35+
| `session-key-registry-deploy.sh` | Deploy SessionKeyRegistry |
36+
| `provider-id-set-deploy.sh` | Deploy ProviderIdSet |
1237

1338
### Usage
1439

1540
```bash
16-
# Deploy to Calibnet
17-
./tools/deploy-warm-storage-calibnet.sh
18-
1941
# Deploy all contracts
20-
./tools/deploy-all-warm-storage.sh
42+
./tools/warm-storage-deploy-all.sh
43+
44+
# Deploy to Calibnet (FWSS only)
45+
./tools/warm-storage-deploy-calibnet.sh
2146

22-
# Upgrade existing deployment
23-
./tools/upgrade-warm-storage-calibnet.sh
47+
# Upgrade existing deployment (see UPGRADE-PROCESS.md for details)
48+
./tools/warm-storage-announce-upgrade.sh # Step 1: Announce
49+
./tools/warm-storage-execute-upgrade.sh # Step 2: Execute (after AFTER_EPOCH)
2450
```
2551

2652
## Deployment Parameters
@@ -115,17 +141,14 @@ These scripts now follow forge/cast's environment variable conventions. Set the
115141
- `ETH_FROM` - Optional: address to use as deployer (forge/cast default is taken from the keystore)
116142

117143
### Required for specific scripts:
118-
- `deploy-warm-storage-calibnet.sh` requires:
119-
144+
- `warm-storage-deploy-calibnet.sh` requires:
120145
- `PDP_VERIFIER_PROXY_ADDRESS` - Address of deployed PDPVerifier contract
121146
- `FILECOIN_PAY_ADDRESS` - Address of deployed FilecoinPayV1 contract
122147

123-
124-
- `deploy-all-warm-storage.sh` requires:
148+
- `warm-storage-deploy-all.sh` requires:
125149
- `CHALLENGE_FINALITY` - Challenge finality parameter for PDPVerifier
126150

127-
- `upgrade-warm-storage-calibnet.sh` requires:
128-
- `WARM_STORAGE_SERVICE_PROXY_ADDRESS` - Address of existing FilecoinWarmStorageService proxy to upgrade
151+
- Upgrade scripts - see [UPGRADE-PROCESS.md](./UPGRADE-PROCESS.md) for complete environment variable reference
129152

130153
## Usage Examples
131154

@@ -143,7 +166,7 @@ export CHALLENGE_FINALITY="10" # Use "150" for mainnet
143166
export MAX_PROVING_PERIOD="240" # 240 epochs for calibnet, 2880 for mainnet
144167
export CHALLENGE_WINDOW_SIZE="20" # 20 epochs for calibnet, 60 for mainnet
145168

146-
./deploy-all-warm-storage.sh
169+
./warm-storage-deploy-all.sh
147170
```
148171

149172
### Deploy FilecoinWarmStorageService Only
@@ -155,30 +178,29 @@ export ETH_RPC_URL="https://api.calibration.node.glif.io/rpc/v1"
155178
export PDP_VERIFIER_PROXY_ADDRESS="0x123..."
156179
export FILECOIN_PAY_ADDRESS="0x456..."
157180

158-
./deploy-warm-storage-calibnet.sh
181+
./warm-storage-deploy-calibnet.sh
159182
```
160183

161184
### Upgrade Existing Contract
162185

163-
```bash
164-
export ETH_KEYSTORE="/path/to/keystore.json"
165-
export PASSWORD="your-password"
166-
export ETH_RPC_URL="https://api.calibration.node.glif.io/rpc/v1"
167-
export WARM_STORAGE_SERVICE_PROXY_ADDRESS="0x789..."
186+
See [UPGRADE-PROCESS.md](./UPGRADE-PROCESS.md) for the complete two-step upgrade workflow.
168187

169-
# Optional: Custom proving periods
170-
export MAX_PROVING_PERIOD="240" # 240 epochs for calibnet, 2880 for mainnet
171-
export CHALLENGE_WINDOW_SIZE="20" # 20 epochs for calibnet, 60 for mainnet
188+
## Contract Upgrade Process
172189

173-
./upgrade-warm-storage-calibnet.sh
174-
```
190+
The FilecoinWarmStorageService and ServiceProviderRegistry contracts use a **two-step upgrade process** for security:
175191

176-
## Contract Upgrade Process
192+
1. **Announce**: Call `announcePlannedUpgrade()` with the new implementation address and a future epoch
193+
2. **Execute**: After the announced epoch, call `upgradeToAndCall()` to complete the upgrade
194+
195+
This gives stakeholders time to review changes before execution.
177196

178-
The FilecoinWarmStorageService contract uses OpenZeppelin's upgradeable pattern. When upgrading:
197+
**For complete upgrade documentation**, including:
198+
- Step-by-step upgrade workflows
199+
- Environment variable reference
200+
- Immutable dependency handling
201+
- Verification procedures
179202

180-
1. **Deploy new implementation**: The script deploys a new implementation contract
181-
2. **Upgrade proxy**: Uses `upgradeToAndCall` to point the proxy to the new implementation
203+
See [UPGRADE-PROCESS.md](./UPGRADE-PROCESS.md).
182204

183205
## Testing
184206

0 commit comments

Comments
 (0)