feat!: simplify dataset status to two-state lifecycle (Inactive/Active)

rjan90 · rjan90 · commit ddd6ccd5f072 · 2025-10-24T18:34:36.000+02:00
Implement simplified dataset status system as specified in issue #169. Replaces the 3-state system (NotFound/Active/Terminating) with a clearer 2-state system (Inactive/Active). Key changes: - Updated DataSetStatus enum from 3 states to 2 states (Inactive/Active) - Status now reflects data existence, not operational state - Inactive = Dataset doesn't exist or has no pieces - Active = Dataset has data and proving history (including terminated) - Updated contract logic, tests, subgraph, and documentation BREAKING CHANGE: DataSetStatus enum values changed. Terminated datasets are now Active (not Terminating). Check operational state using pdpEndEpoch or isTerminated() instead.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -6,8 +6,22 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 ## [Unreleased]
 
 ### Added
+- Dataset lifecycle tracking with `DataSetStatusChanged` event ([#169](https://github.com/FilOzone/filecoin-services/issues/169))
+- Convenience functions `isDataSetActive()` and `getDataSetStatusDetails()` for status checking
+- Comprehensive documentation: dataset lifecycle guide and integration guide
+- Subgraph status history tracking with `DataSetStatusHistory` entity
 
 ### Changed
+- **BREAKING**: Simplified `DataSetStatus` enum from 3 states to 2 states ([#169](https://github.com/FilOzone/filecoin-services/issues/169))
+  - **Old values**: `NotFound (0)`, `Active (1)`, `Terminating (2)`
+  - **New values**: `Inactive (0)`, `Active (1)`
+  - **Migration**: 
+    - `NotFound` → `Inactive` (non-existent datasets)
+    - `Terminating` → `Active` (terminated datasets with pieces are still Active)
+    - Use `pdpEndEpoch` to check if a dataset is terminated
+  - **Details**: `Inactive` represents non-existent datasets or datasets with no pieces yet. `Active` represents all datasets with pieces, including terminated ones.
+  - Use `getDataSetStatusDetails()` to check termination status separately from Active/Inactive status
+- Subgraph schema updated with status enum and history tracking
 
 ## [0.3.0] - 2025-10-08 - M3.1 Calibration Network Deployment
 
diff --git a/service_contracts/README.md b/service_contracts/README.md
@@ -29,6 +29,46 @@ This directory contains the smart contracts for different Filecoin services usin
   - `pdp` - PDP verifier contract (from main branch)
 
 
+## Dataset Status & Lifecycle
+
+Datasets have a simplified two-state lifecycle system to track their operational status:
+
+### Status States
+
+- **Inactive**: Dataset doesn't exist or has no pieces added yet (rate = 0, no proving)
+- **Active**: Dataset has pieces and proving history (including terminated datasets)
+
+**Important**: Terminated datasets remain **Active** because they still have data. Status reflects data existence, not operational state. Use `pdpEndEpoch` to check if a dataset is terminated.
+
+### Querying Status
+
+**From Solidity:**
+```solidity
+import {FilecoinWarmStorageServiceStateLibrary} from "./lib/FilecoinWarmStorageServiceStateLibrary.sol";
+
+// Get status
+DataSetStatus status = FilecoinWarmStorageServiceStateLibrary.getDataSetStatus(service, dataSetId);
+bool isActive = (status == FilecoinWarmStorageService.DataSetStatus.Active);
+```
+
+**From Subgraph:**
+```graphql
+{
+  dataSet(id: "0x...") {
+    setId
+    status  # "ACTIVE" or "INACTIVE"
+    totalPieces
+    pdpEndEpoch
+  }
+}
+```
+
+**Via View Contract:**
+```solidity
+DataSetStatus status = viewContract.getDataSetStatus(dataSetId);
+// 0 = Inactive, 1 = Active
+```
+
 ### Extsload
 The allow for many view methods within the 24 KiB contract size constraint, viewing is done with `extsload` and `extsloadStruct`.
 There are three recommended ways to access `view` methods.
diff --git a/service_contracts/src/FilecoinWarmStorageService.sol b/service_contracts/src/FilecoinWarmStorageService.sol
@@ -130,12 +130,11 @@ contract FilecoinWarmStorageService is
     }
 
     enum DataSetStatus {
-        // Data set doesn't yet exist or has been deleted
-        NotFound,
-        // Data set is active
-        Active,
-        // Data set is in the process of being terminated
-        Terminating
+        // Dataset is inactive: non-existent (pdpRailId==0) or no pieces added yet (rate==0, no proving)
+        Inactive,
+        // Dataset has pieces and proving history (includes datasets in process of being terminated)
+        // Note: Datasets being terminated remain Active - they become Inactive after deletion when data is wiped
+        Active
     }
 
     // Decode structure for data set creation extra data
diff --git a/service_contracts/src/lib/FilecoinWarmStorageServiceStateInternalLibrary.sol b/service_contracts/src/lib/FilecoinWarmStorageServiceStateInternalLibrary.sol
@@ -119,18 +119,33 @@ library FilecoinWarmStorageServiceStateInternalLibrary {
         info.dataSetId = dataSetId;
     }
 
+    /**
+     * @notice Get the current status of a dataset
+     * @dev A dataset is Active when it has pieces and proving history (including terminated datasets)
+     * @dev A dataset is Inactive when: non-existent or no pieces added yet
+     * @param service The service contract
+     * @param dataSetId The ID of the dataset
+     * @return status The current status
+     */
     function getDataSetStatus(FilecoinWarmStorageService service, uint256 dataSetId)
         internal
         view
         returns (FilecoinWarmStorageService.DataSetStatus status)
     {
         FilecoinWarmStorageService.DataSetInfoView memory info = getDataSet(service, dataSetId);
+
+        // Non-existent datasets are inactive
         if (info.pdpRailId == 0) {
-            return FilecoinWarmStorageService.DataSetStatus.NotFound;
+            return FilecoinWarmStorageService.DataSetStatus.Inactive;
         }
-        if (info.pdpEndEpoch != 0) {
-            return FilecoinWarmStorageService.DataSetStatus.Terminating;
+
+        // Check if proving is activated (has pieces)
+        // Inactive only if no proving has started, everything else is Active
+        uint256 activationEpoch = provingActivationEpoch(service, dataSetId);
+        if (activationEpoch == 0) {
+            return FilecoinWarmStorageService.DataSetStatus.Inactive;
         }
+
         return FilecoinWarmStorageService.DataSetStatus.Active;
     }
 
diff --git a/service_contracts/src/lib/FilecoinWarmStorageServiceStateLibrary.sol b/service_contracts/src/lib/FilecoinWarmStorageServiceStateLibrary.sol
@@ -115,18 +115,33 @@ library FilecoinWarmStorageServiceStateLibrary {
         info.dataSetId = dataSetId;
     }
 
+    /**
+     * @notice Get the current status of a dataset
+     * @dev A dataset is Active when it has pieces and proving history (including terminated datasets)
+     * @dev A dataset is Inactive when: non-existent or no pieces added yet
+     * @param service The service contract
+     * @param dataSetId The ID of the dataset
+     * @return status The current status
+     */
     function getDataSetStatus(FilecoinWarmStorageService service, uint256 dataSetId)
         public
         view
         returns (FilecoinWarmStorageService.DataSetStatus status)
     {
         FilecoinWarmStorageService.DataSetInfoView memory info = getDataSet(service, dataSetId);
+
+        // Non-existent datasets are inactive
         if (info.pdpRailId == 0) {
-            return FilecoinWarmStorageService.DataSetStatus.NotFound;
+            return FilecoinWarmStorageService.DataSetStatus.Inactive;
         }
-        if (info.pdpEndEpoch != 0) {
-            return FilecoinWarmStorageService.DataSetStatus.Terminating;
+
+        // Check if proving is activated (has pieces)
+        // Inactive only if no proving has started, everything else is Active
+        uint256 activationEpoch = provingActivationEpoch(service, dataSetId);
+        if (activationEpoch == 0) {
+            return FilecoinWarmStorageService.DataSetStatus.Inactive;
         }
+
         return FilecoinWarmStorageService.DataSetStatus.Active;
     }
 
diff --git a/service_contracts/test/FilecoinWarmStorageService.t.sol b/service_contracts/test/FilecoinWarmStorageService.t.sol
@@ -1782,7 +1782,7 @@ contract FilecoinWarmStorageServiceTest is MockFVMTest {
 
         // 0. Verify that DataSet with ID 1 is not found
         FilecoinWarmStorageService.DataSetStatus status = viewContract.getDataSetStatus(1);
-        assertEq(uint256(status), uint256(FilecoinWarmStorageService.DataSetStatus.NotFound), "expected NotFound");
+        assertEq(uint256(status), uint256(FilecoinWarmStorageService.DataSetStatus.Inactive), "expected Inactive");
 
         // 1. Setup: Create a dataset with CDN enabled.
         console.log("1. Setting up: Creating dataset with service provider");
@@ -1828,7 +1828,11 @@ contract FilecoinWarmStorageServiceTest is MockFVMTest {
         console.log("Created data set with ID:", dataSetId);
 
         status = viewContract.getDataSetStatus(dataSetId);
-        assertEq(uint256(status), uint256(FilecoinWarmStorageService.DataSetStatus.Active), "expected Active");
+        assertEq(
+            uint256(status),
+            uint256(FilecoinWarmStorageService.DataSetStatus.Inactive),
+            "expected Inactive (no pieces yet)"
+        );
 
         // 2. Submit a valid proof.
         console.log("\n2. Starting proving period and submitting proof");
@@ -1880,9 +1884,11 @@ contract FilecoinWarmStorageServiceTest is MockFVMTest {
         assertFalse(exists, "withCDN metadata should not exist after termination");
         assertEq(withCDN, "", "withCDN value should be cleared for dataset");
 
-        // check status is terminating
+        // check status remains active (terminated datasets are still Active)
         status = viewContract.getDataSetStatus(dataSetId);
-        assertEq(uint256(status), uint256(FilecoinWarmStorageService.DataSetStatus.Terminating), "expected Terminating");
+        assertEq(
+            uint256(status), uint256(FilecoinWarmStorageService.DataSetStatus.Active), "expected Active (terminating)"
+        );
 
         // Ensure piecesAdded reverts
         console.log("\n4. Testing operations after termination");
@@ -1909,9 +1915,11 @@ contract FilecoinWarmStorageServiceTest is MockFVMTest {
         console.log("Rolling to block:", info.pdpEndEpoch + 1);
         vm.roll(info.pdpEndEpoch + 1);
 
-        // check status is still Terminating as data set is not yet deleted from PDP
+        // check status is still Active as data set is not yet deleted from PDP
         status = viewContract.getDataSetStatus(dataSetId);
-        assertEq(uint256(status), uint256(FilecoinWarmStorageService.DataSetStatus.Terminating), "expected Terminating");
+        assertEq(
+            uint256(status), uint256(FilecoinWarmStorageService.DataSetStatus.Active), "expected Active (terminating)"
+        );
 
         // Ensure other functions also revert now
         console.log("\n6. Testing operations after payment end epoch");
@@ -1956,7 +1964,9 @@ contract FilecoinWarmStorageServiceTest is MockFVMTest {
         pdpServiceWithPayments.dataSetDeleted(dataSetId, 10, bytes(""));
 
         status = viewContract.getDataSetStatus(dataSetId);
-        assertEq(uint256(status), uint256(FilecoinWarmStorageService.DataSetStatus.NotFound), "expected NotFound");
+        assertEq(
+            uint256(status), uint256(FilecoinWarmStorageService.DataSetStatus.Inactive), "expected Inactive (deleted)"
+        );
         console.log("\n=== Test completed successfully! ===");
     }
 
diff --git a/subgraph/schemas/schema.v1.graphql b/subgraph/schemas/schema.v1.graphql
@@ -1,3 +1,8 @@
+enum DataSetStatus {
+  INACTIVE
+  ACTIVE
+}
+
 type DataSet @entity(immutable: false) {
   id: Bytes! # setId
   setId: BigInt! # uint256
@@ -10,7 +15,8 @@ type DataSet @entity(immutable: false) {
   pdpEndEpoch: BigInt!
   leafCount: BigInt! # uint256
   challengeRange: BigInt! # uint256
-  isActive: Boolean!
+  isActive: Boolean! # Deprecated: use status field instead
+  status: DataSetStatus! # Current lifecycle status
   lastProvenEpoch: BigInt! # uint256
   nextChallengeEpoch: BigInt! # uint256
   totalPieces: BigInt! # uint256
diff --git a/subgraph/src/filecoin-warm-storage-service.ts b/subgraph/src/filecoin-warm-storage-service.ts
@@ -284,7 +284,8 @@ export function handleDataSetCreated(event: DataSetCreatedEvent): void {
   dataSet.payee = payee;
   dataSet.serviceProvider = serviceProvider;
   dataSet.withCDN = withCDN;
-  dataSet.isActive = true;
+  dataSet.isActive = true; // Deprecated: kept for backward compatibility
+  dataSet.status = "INACTIVE"; // Initially inactive (no pieces yet)
   dataSet.pdpEndEpoch = BIGINT_ZERO;
   dataSet.leafCount = BIGINT_ZERO;
   dataSet.challengeRange = BIGINT_ZERO;
@@ -496,6 +497,7 @@ export function handlePDPPaymentTerminated(event: PDPPaymentTerminatedEvent): vo
   }
   if (dataSet) {
     dataSet.isActive = false;
+    dataSet.status = "INACTIVE";
     dataSet.pdpEndEpoch = endEpoch;
     dataSet.save();
   }
@@ -531,6 +533,8 @@ export function handleCDNPaymentTerminated(event: CDNPaymentTerminatedEvent): vo
   }
   if (dataSet) {
     dataSet.isActive = false;
+    dataSet.status = "INACTIVE";
     dataSet.save();
   }
 }
+

Original file line number	Diff line number	Diff line change
`@@ -284,7 +284,8 @@ export function handleDataSetCreated(event: DataSetCreatedEvent): void {`
`284`	`284`	`dataSet.payee = payee;`
`285`	`285`	`dataSet.serviceProvider = serviceProvider;`
`286`	`286`	`dataSet.withCDN = withCDN;`
`287`		`- dataSet.isActive = true;`
	`287`	`+ dataSet.isActive = true; // Deprecated: kept for backward compatibility`
	`288`	`+ dataSet.status = "INACTIVE"; // Initially inactive (no pieces yet)`
`288`	`289`	`dataSet.pdpEndEpoch = BIGINT_ZERO;`
`289`	`290`	`dataSet.leafCount = BIGINT_ZERO;`
`290`	`291`	`dataSet.challengeRange = BIGINT_ZERO;`
`@@ -496,6 +497,7 @@ export function handlePDPPaymentTerminated(event: PDPPaymentTerminatedEvent): vo`
`496`	`497`	`}`
`497`	`498`	`if (dataSet) {`
`498`	`499`	`dataSet.isActive = false;`
	`500`	`+ dataSet.status = "INACTIVE";`
`499`	`501`	`dataSet.pdpEndEpoch = endEpoch;`
`500`	`502`	`dataSet.save();`
`501`	`503`	`}`
`@@ -531,6 +533,8 @@ export function handleCDNPaymentTerminated(event: CDNPaymentTerminatedEvent): vo`
`531`	`533`	`}`
`532`	`534`	`if (dataSet) {`
`533`	`535`	`dataSet.isActive = false;`
	`536`	`+ dataSet.status = "INACTIVE";`
`534`	`537`	`dataSet.save();`
`535`	`538`	`}`
`536`	`539`	`}`
	`540`	`+`