fix: replace SDK activePieceCount with hasActivePieces

Listing paths now report piece presence from leaf count, and getActivePieceCount paginates the cursor API instead of the linear-scan getter.

Author: hugomrdias

docs/src/content/docs/developer-guides/migration-guide.md

@@ -121,9 +121,15 @@ if (dataSet?.hasActivePieces) {
 }
 ```
 
-`WarmStorageService.hasActivePieces()` keeps the same public API, but now uses the same leaf-count proxy instead of calculating an exact count.
+`WarmStorageService.hasActivePieces()` keeps the same public API, but now uses the same leaf-count proxy instead of calculating an exact count. `EnhancedDataSetInfo` from `getClientDataSetsWithDetails()` / `findDataSets()` also exposes `hasActivePieces` instead of `activePieceCount`.
 
-The standalone `getActivePieceCount()` action remains available, but the underlying contract getter scans the data set's piece-ID range and can fail for large data sets. If you need an exact count, explicitly paginate the active pieces:
+The core `getActivePieceCount()` action remains available, but the underlying contract getter scans the data set's piece-ID range and can fail for large data sets. `WarmStorageService.getActivePieceCount()` now paginates `getActivePiecesByCursor` to derive an exact count:
+
+```ts
+const activePieceCount = await warmStorageService.getActivePieceCount({ dataSetId })
+```
+
+To paginate explicitly in core:
 
 ```ts
 let activePieceCount = 0n
@@ -135,8 +141,6 @@ for await (const _piece of paginate(({ cursor }) =>
 }
 ```
 
-This field change is limited to the enriched data set types in `@filoz/synapse-core`; the SDK's legacy `EnhancedDataSetInfo.activePieceCount` field is unchanged.
-
 ---
 
 ## 1.0.0

docs/src/content/docs/developer-guides/storage/storage-operations.mdx

@@ -196,7 +196,7 @@ These APIs are useful when you want to inspect existing data sets, query stored
 
 ### Getting All Data Sets
 
-Retrieve all data sets owned by your account to inspect piece counts, CDN status, and metadata:
+Retrieve all data sets owned by your account to inspect piece presence, CDN status, and metadata:
 
 ```ts twoslash
 // @lib: esnext,dom
@@ -210,7 +210,7 @@ for (const ds of dataSets) {
   console.log(`Dataset ${ds.pdpVerifierDataSetId}:`, {
     live: ds.isLive,
     cdn: ds.withCDN,
-    pieces: ds.activePieceCount,
+    hasActivePieces: ds.hasActivePieces,
     metadata: ds.metadata
   });
 }

packages/synapse-sdk/src/test/warm-storage-service.test.ts

@@ -8,7 +8,8 @@ import { calibration } from '@filoz/synapse-core/chains'
 import * as Mocks from '@filoz/synapse-core/mocks'
 import { assert } from 'chai'
 import { setup } from 'iso-web/msw'
-import { type Address, createWalletClient, http as viemHttp } from 'viem'
+import { CID } from 'multiformats/cid'
+import { type Address, bytesToHex, createWalletClient, http as viemHttp } from 'viem'
 import { privateKeyToAccount } from 'viem/accounts'
 import { WarmStorageService } from '../warm-storage/index.ts'
 
@@ -83,6 +84,51 @@ describe('WarmStorageService', () => {
     })
   })
 
+  describe('getActivePieceCount', () => {
+    it('should count active pieces by paginating the cursor', async () => {
+      server.use(Mocks.JSONRPC(Mocks.presets.basic))
+      const warmStorageService = await createWarmStorageService()
+      assert.equal(await warmStorageService.getActivePieceCount({ dataSetId: 1n }), 2n)
+    })
+
+    it('should return zero when the data set has no active pieces', async () => {
+      server.use(
+        Mocks.JSONRPC({
+          ...Mocks.presets.basic,
+          pdpVerifier: {
+            ...Mocks.presets.basic.pdpVerifier,
+            getActivePiecesByCursor: () => [[], [], false],
+          },
+        })
+      )
+      const warmStorageService = await createWarmStorageService()
+      assert.equal(await warmStorageService.getActivePieceCount({ dataSetId: 1n }), 0n)
+    })
+
+    it('should sum pieces across cursor pages', async () => {
+      const first = CID.parse('bafkzcibcd4bdomn3tgwgrh3g532zopskstnbrd2n3sxfqbze7rxt7vqn7veigmy')
+      const second = CID.parse('bafkzcibeqcad6efnpwn62p5vvs5x3nh3j7xkzfgb3xtitcdm2hulmty3xx4tl3wace')
+      server.use(
+        Mocks.JSONRPC({
+          ...Mocks.presets.basic,
+          pdpVerifier: {
+            ...Mocks.presets.basic.pdpVerifier,
+            getActivePiecesByCursor: (args) => {
+              const startPieceId = args[1]
+              if (startPieceId === 0n) {
+                return [[{ data: bytesToHex(first.bytes) }], [1n], true]
+              }
+              assert.equal(startPieceId, 2n)
+              return [[{ data: bytesToHex(second.bytes) }], [2n], false]
+            },
+          },
+        })
+      )
+      const warmStorageService = await createWarmStorageService()
+      assert.equal(await warmStorageService.getActivePieceCount({ dataSetId: 1n }), 2n)
+    })
+  })
+
   describe('getDataSet', () => {
     it('should return a single data set by ID', async () => {
       server.use(Mocks.JSONRPC(Mocks.presets.basic))
@@ -485,7 +531,7 @@ describe('WarmStorageService', () => {
       assert.lengthOf(detailedDataSets, 1)
       assert.equal(detailedDataSets[0].pdpRailId, 48n)
       assert.equal(detailedDataSets[0].pdpVerifierDataSetId, 242n)
-      assert.equal(detailedDataSets[0].activePieceCount, 2n)
+      assert.isTrue(detailedDataSets[0].hasActivePieces)
       assert.isTrue(detailedDataSets[0].isLive)
       assert.isTrue(detailedDataSets[0].isManaged)
     })

packages/synapse-sdk/src/types.ts

@@ -256,8 +256,8 @@ export interface DataSetInfo {
 export interface EnhancedDataSetInfo extends DataSetInfo {
   /** PDPVerifier global data set ID */
   pdpVerifierDataSetId: bigint
-  /** Number of active pieces in the data set (excludes removed pieces) */
-  activePieceCount: bigint
+  /** Whether the data set contains at least one active piece (non-zero leaf count). */
+  hasActivePieces: boolean
   /** Whether the data set is live on-chain */
   isLive: boolean
   /** Whether this data set is managed by the current Warm Storage contract */

packages/synapse-sdk/src/warm-storage/service.ts

@@ -148,9 +148,8 @@ export class WarmStorageService {
    * Get all data sets for a client with enhanced details
    * This includes live status and management information.
    *
-   * `activePieceCount` still uses the contract's linear-scan getter and can run
-   * out of gas for large data sets. Prefer {@link hasActivePieces} when only
-   * presence is needed.
+   * Piece presence uses a non-zero PDP leaf count rather than an exact active
+   * piece count. Prefer {@link getActivePieceCount} when an exact count is needed.
    * @param options - Options for the client data sets
    * @param options.address - The client address. Defaults to the client account address.
    * @param options.onlyManaged - If true, only return data sets managed by this Warm Storage contract. Defaults to false.
@@ -195,15 +194,13 @@ export class WarmStorageService {
           return null // Will be filtered out
         }
 
-        // Get active piece count only if the data set is live
-        const activePieceCount = isLive
-          ? await PDPVerifier.getActivePieceCount(this._client, { dataSetId: dataSet.dataSetId })
-          : 0n
+        // Get piece presence only if the data set is live
+        const hasActivePieces = isLive ? await this.hasActivePieces({ dataSetId: dataSet.dataSetId }) : false
 
         return {
           ...dataSet,
           pdpVerifierDataSetId: dataSet.dataSetId,
-          activePieceCount,
+          hasActivePieces,
           isLive,
           isManaged,
           withCDN: dataSet.cdnRailId > 0 && metadata[0].includes(METADATA_KEYS.WITH_CDN),
@@ -284,15 +281,18 @@ export class WarmStorageService {
   /**
    * Get the count of active pieces in a dataset (excludes removed pieces)
    *
-   * The contract getter scans the data set's piece-ID range and can run out of
-   * gas for large data sets. Prefer {@link hasActivePieces} when only presence
-   * is needed, or paginate `getActivePiecesByCursor` to derive an exact count.
+   * Paginates `getActivePiecesByCursor` rather than calling the contract's
+   * linear-scan getter, which can run out of gas for large data sets.
+   * Prefer {@link hasActivePieces} when only presence is needed.
    * @param options - Options for the data set
    * @param options.dataSetId - The PDPVerifier data set ID
    * @returns The number of active pieces
    */
   async getActivePieceCount(options: { dataSetId: bigint }): Promise<bigint> {
-    return PDPVerifier.getActivePieceCount(this._client, { dataSetId: options.dataSetId })
+    const pieces = await Array.fromAsync(
+      paginate(({ cursor }) => PDPVerifier.getActivePiecesByCursor(this._client, { ...options, cursor }))
+    )
+    return BigInt(pieces.length)
   }
 
   /**