feat: implement SynapseStorage#pieceStatus(commp) (#127)

Closes: #16

Author: rvagg

README.md

@@ -384,6 +384,12 @@ const downloaded = await storage.providerDownload(result.commp)
 // Get the list of root CIDs in the current proof set by querying the provider
 const rootCids = await storage.getProofSetRoots()
 console.log(`Root CIDs: ${rootCids.map(cid => cid.toString()).join(', ')}`)
+
+// Check the status of a piece on the storage provider
+const status = await storage.pieceStatus(result.commp)
+console.log(`Piece exists: ${status.exists}`)
+console.log(`Proof set last proven: ${status.proofSetLastProven}`)
+console.log(`Proof set next proof due: ${status.proofSetNextProofDue}`)
 ```
 
 **Storage Service Methods:**
@@ -392,6 +398,7 @@ console.log(`Root CIDs: ${rootCids.map(cid => cid.toString()).join(', ')}`)
 - `preflightUpload(dataSize)` - Check if an upload is possible before attempting it
 - `getProviderInfo()` - Get detailed information about the selected storage provider
 - `getProofSetRoots()` - Get the list of root CIDs in the proof set by querying the provider
+- `pieceStatus(commp)` - Get the status of a piece including proof set timing information
 
 ##### Size Constraints
 

src/pandora/service.ts

@@ -879,4 +879,75 @@ export class PandoraService {
       epochsPerMonth: result.epochsPerMonth
     }
   }
+
+  // ========== Proving Period Operations ==========
+
+  /**
+   * Get the maximum proving period in epochs
+   * This is the maximum time allowed between proofs before a fault is recorded
+   * @returns Maximum proving period in epochs
+   */
+  async getMaxProvingPeriod (): Promise<number> {
+    const contract = this._getPandoraContract()
+    const maxProvingPeriod = await contract.getMaxProvingPeriod()
+    return Number(maxProvingPeriod)
+  }
+
+  /**
+   * Get the challenge window size in epochs
+   * This is the window at the end of each proving period where proofs can be submitted
+   * @returns Challenge window size in epochs
+   */
+  async getChallengeWindow (): Promise<number> {
+    const contract = this._getPandoraContract()
+    const challengeWindow = await contract.challengeWindow()
+    return Number(challengeWindow)
+  }
+
+  /**
+   * Get the maximum proving period in hours
+   * Convenience method that converts epochs to hours
+   * @returns Maximum proving period in hours
+   */
+  async getProvingPeriodInHours (): Promise<number> {
+    const maxProvingPeriod = await this.getMaxProvingPeriod()
+    // Convert epochs to hours: epochs * 30 seconds / 3600 seconds per hour
+    return (maxProvingPeriod * 30) / 3600
+  }
+
+  /**
+   * Get the challenge window in minutes
+   * Convenience method that converts epochs to minutes
+   * @returns Challenge window in minutes
+   */
+  async getChallengeWindowInMinutes (): Promise<number> {
+    const challengeWindow = await this.getChallengeWindow()
+    // Convert epochs to minutes: epochs * 30 seconds / 60 seconds per minute
+    return (challengeWindow * 30) / 60
+  }
+
+  /**
+   * Get comprehensive proving period information
+   * @returns Object with all proving period timing information
+   */
+  async getProvingPeriodInfo (): Promise<{
+    maxProvingPeriodEpochs: number
+    challengeWindowEpochs: number
+    maxProvingPeriodHours: number
+    challengeWindowMinutes: number
+    epochDurationSeconds: number
+  }> {
+    const [maxProvingPeriod, challengeWindow] = await Promise.all([
+      this.getMaxProvingPeriod(),
+      this.getChallengeWindow()
+    ])
+
+    return {
+      maxProvingPeriodEpochs: maxProvingPeriod,
+      challengeWindowEpochs: challengeWindow,
+      maxProvingPeriodHours: (maxProvingPeriod * 30) / 3600,
+      challengeWindowMinutes: (challengeWindow * 30) / 60,
+      epochDurationSeconds: 30
+    }
+  }
 }

src/storage/service.ts

@@ -19,14 +19,16 @@ import type {
   UploadCallbacks,
   UploadResult,
   RootData,
-  CommP
+  CommP,
+  PieceStatus
 } from '../types.js'
 import type { Synapse } from '../synapse.js'
 import type { PandoraService } from '../pandora/service.js'
 import { PDPServer } from '../pdp/server.js'
 import { PDPAuthHelper } from '../pdp/auth.js'
-import { createError } from '../utils/index.js'
+import { createError, epochToDate, calculateLastProofDate, timeUntilEpoch } from '../utils/index.js'
 import { SIZE_CONSTANTS, TIMING_CONSTANTS } from '../utils/constants.js'
+import { asCommP } from '../commp/index.js'
 
 export class StorageService {
   private readonly _synapse: Synapse
@@ -1028,4 +1030,131 @@ export class StorageService {
     const proofSetData = await this._pdpServer.getProofSet(this._proofSetId)
     return proofSetData.roots.map(root => root.rootCid)
   }
+
+  /**
+   * Get the status of a piece on this storage provider
+   * This method checks if the piece exists on the provider and provides proof timing information
+   * for the proof set containing this piece.
+   *
+   * Note: Proofs are submitted for entire proof sets, not individual pieces. The timing information
+   * returned reflects when the proof set (containing this piece) was last proven and when the next
+   * proof is due.
+   *
+   * @param commp - The CommP (piece CID) to check
+   * @returns Status information including existence, proof set timing, and retrieval URL
+   */
+  async pieceStatus (commp: string | CommP): Promise<PieceStatus> {
+    const parsedCommP = asCommP(commp)
+    if (parsedCommP == null) {
+      throw createError('StorageService', 'pieceStatus', 'Invalid CommP provided')
+    }
+
+    // Run multiple operations in parallel for better performance
+    const [pieceCheckResult, proofSetData, currentEpoch] = await Promise.all([
+      // Check if piece exists on provider
+      this._pdpServer.findPiece(parsedCommP, 0).then(() => true).catch(() => false),
+      // Get proof set data
+      this._pdpServer.getProofSet(this._proofSetId).catch((error) => {
+        console.debug('Failed to get proof set data:', error)
+        return null
+      }),
+      // Get current epoch
+      this._synapse.payments.getCurrentEpoch()
+    ])
+
+    const exists = pieceCheckResult
+    const network = this._synapse.getNetwork()
+
+    // Initialize return values
+    let retrievalUrl: string | null = null
+    let rootId: number | undefined
+    let lastProven: Date | null = null
+    let nextProofDue: Date | null = null
+    let inChallengeWindow = false
+    let hoursUntilChallengeWindow = 0
+    let isProofOverdue = false
+
+    // If piece exists, get provider info for retrieval URL and proving params in parallel
+    if (exists) {
+      const [providerInfo, provingParams] = await Promise.all([
+        // Get provider info for retrieval URL
+        this.getProviderInfo().catch(() => null),
+        // Get proving period configuration (only if we have proof set data)
+        proofSetData != null
+          ? Promise.all([
+            this._pandoraService.getMaxProvingPeriod(),
+            this._pandoraService.getChallengeWindow()
+          ]).then(([maxProvingPeriod, challengeWindow]) => ({ maxProvingPeriod, challengeWindow }))
+            .catch(() => null)
+          : Promise.resolve(null)
+      ])
+
+      // Set retrieval URL if we have provider info
+      if (providerInfo != null) {
+        // Remove trailing slash from pieceRetrievalUrl to avoid double slashes
+        retrievalUrl = `${providerInfo.pieceRetrievalUrl.replace(/\/$/, '')}/piece/${parsedCommP.toString()}`
+      }
+
+      // Process proof timing data if we have proof set data and proving params
+      if (proofSetData != null && provingParams != null) {
+        // Check if this CommP is in the proof set
+        const rootData = proofSetData.roots.find(root => root.rootCid.toString() === parsedCommP.toString())
+
+        if (rootData != null) {
+          rootId = rootData.rootId
+
+          // Calculate timing based on nextChallengeEpoch
+          if (proofSetData.nextChallengeEpoch > 0) {
+            // nextChallengeEpoch is when the challenge window STARTS, not ends!
+            // The proving deadline is nextChallengeEpoch + challengeWindow
+            const challengeWindowStart = proofSetData.nextChallengeEpoch
+            const provingDeadline = challengeWindowStart + provingParams.challengeWindow
+
+            // Calculate when the next proof is due (end of challenge window)
+            nextProofDue = epochToDate(provingDeadline, network)
+
+            // Calculate last proven date (one proving period before next challenge)
+            const lastProvenDate = calculateLastProofDate(
+              proofSetData.nextChallengeEpoch,
+              provingParams.maxProvingPeriod,
+              network
+            )
+            if (lastProvenDate != null) {
+              lastProven = lastProvenDate
+            }
+
+            // Check if we're in the challenge window
+            inChallengeWindow = currentEpoch >= challengeWindowStart && currentEpoch < provingDeadline
+
+            // Check if proof is overdue (past the proving deadline)
+            isProofOverdue = currentEpoch >= provingDeadline
+
+            // Calculate hours until challenge window starts (only if before challenge window)
+            if (currentEpoch < challengeWindowStart) {
+              const timeUntil = timeUntilEpoch(challengeWindowStart, Number(currentEpoch))
+              hoursUntilChallengeWindow = timeUntil.hours
+            }
+          } else {
+            // If nextChallengeEpoch is 0, it might mean:
+            // 1. Proof was just submitted and system is updating
+            // 2. Proof set is not active
+            // In case 1, we might have just proven, so set lastProven to very recent
+            // This is a temporary state and should resolve quickly
+            console.debug('Proof set has nextChallengeEpoch=0, may have just been proven')
+          }
+        }
+      }
+    }
+
+    return {
+      exists,
+      proofSetLastProven: lastProven,
+      proofSetNextProofDue: nextProofDue,
+      retrievalUrl,
+      rootId,
+      inChallengeWindow,
+      hoursUntilChallengeWindow,
+      isProofOverdue
+    }
+  }
 }

src/test/epoch.test.ts

@@ -0,0 +1,142 @@
+/* globals describe it */
+import { assert } from 'chai'
+import {
+  epochToDate,
+  dateToEpoch,
+  getGenesisTimestamp,
+  timeUntilEpoch,
+  calculateLastProofDate
+} from '../utils/epoch.js'
+import { GENESIS_TIMESTAMPS, TIME_CONSTANTS } from '../utils/constants.js'
+
+describe('Epoch Utilities', () => {
+  describe('epochToDate', () => {
+    it('should convert epoch 0 to genesis timestamp for mainnet', () => {
+      const date = epochToDate(0, 'mainnet')
+      assert.equal(date.getTime(), GENESIS_TIMESTAMPS.mainnet * 1000)
+    })
+
+    it('should convert epoch 0 to genesis timestamp for calibration', () => {
+      const date = epochToDate(0, 'calibration')
+      assert.equal(date.getTime(), GENESIS_TIMESTAMPS.calibration * 1000)
+    })
+
+    it('should calculate correct date for future epochs', () => {
+      const epochsPerDay = 24 * 60 * 2 // 2880 epochs per day
+      const date = epochToDate(epochsPerDay, 'mainnet')
+      const expectedTime = (GENESIS_TIMESTAMPS.mainnet + epochsPerDay * TIME_CONSTANTS.EPOCH_DURATION) * 1000
+      assert.equal(date.getTime(), expectedTime)
+    })
+
+    it('should handle large epoch numbers', () => {
+      const largeEpoch = 1000000
+      const date = epochToDate(largeEpoch, 'calibration')
+      const expectedTime = (GENESIS_TIMESTAMPS.calibration + largeEpoch * TIME_CONSTANTS.EPOCH_DURATION) * 1000
+      assert.equal(date.getTime(), expectedTime)
+    })
+  })
+
+  describe('dateToEpoch', () => {
+    it('should convert genesis date to epoch 0 for mainnet', () => {
+      const genesisDate = new Date(GENESIS_TIMESTAMPS.mainnet * 1000)
+      const epoch = dateToEpoch(genesisDate, 'mainnet')
+      assert.equal(epoch, 0)
+    })
+
+    it('should convert genesis date to epoch 0 for calibration', () => {
+      const genesisDate = new Date(GENESIS_TIMESTAMPS.calibration * 1000)
+      const epoch = dateToEpoch(genesisDate, 'calibration')
+      assert.equal(epoch, 0)
+    })
+
+    it('should calculate correct epoch for future dates', () => {
+      const futureDate = new Date((GENESIS_TIMESTAMPS.mainnet + 3600) * 1000) // 1 hour after genesis
+      const epoch = dateToEpoch(futureDate, 'mainnet')
+      assert.equal(epoch, 120) // 3600 seconds / 30 seconds per epoch
+    })
+
+    it('should round down to nearest epoch', () => {
+      const partialEpochDate = new Date((GENESIS_TIMESTAMPS.calibration + 45) * 1000) // 1.5 epochs
+      const epoch = dateToEpoch(partialEpochDate, 'calibration')
+      assert.equal(epoch, 1) // Should round down
+    })
+  })
+
+  describe('getGenesisTimestamp', () => {
+    it('should return correct timestamp for mainnet', () => {
+      const timestamp = getGenesisTimestamp('mainnet')
+      assert.equal(timestamp, GENESIS_TIMESTAMPS.mainnet)
+    })
+
+    it('should return correct timestamp for calibration', () => {
+      const timestamp = getGenesisTimestamp('calibration')
+      assert.equal(timestamp, GENESIS_TIMESTAMPS.calibration)
+    })
+  })
+
+  describe('timeUntilEpoch', () => {
+    it('should calculate correct time difference', () => {
+      const currentEpoch = 1000
+      const futureEpoch = 1120 // 120 epochs in the future = 1 hour
+      const result = timeUntilEpoch(futureEpoch, currentEpoch)
+
+      assert.equal(result.epochs, 120)
+      assert.equal(result.seconds, 3600)
+      assert.equal(result.minutes, 60)
+      assert.equal(result.hours, 1)
+      assert.equal(result.days, 1 / 24)
+    })
+
+    it('should handle same epoch', () => {
+      const result = timeUntilEpoch(1000, 1000)
+
+      assert.equal(result.epochs, 0)
+      assert.equal(result.seconds, 0)
+      assert.equal(result.minutes, 0)
+      assert.equal(result.hours, 0)
+      assert.equal(result.days, 0)
+    })
+
+    it('should handle negative differences (past epochs)', () => {
+      const result = timeUntilEpoch(1000, 1120)
+
+      assert.equal(result.epochs, -120)
+      assert.equal(result.seconds, -3600)
+      assert.equal(result.minutes, -60)
+      assert.equal(result.hours, -1)
+      assert.equal(result.days, -1 / 24)
+    })
+  })
+
+  describe('calculateLastProofDate', () => {
+    it('should return null when nextChallengeEpoch is 0', () => {
+      const result = calculateLastProofDate(0, 2880, 'mainnet')
+      assert.isNull(result)
+    })
+
+    it('should return null when in first proving period', () => {
+      const result = calculateLastProofDate(100, 2880, 'mainnet')
+      assert.isNull(result)
+    })
+
+    it('should calculate correct last proof date', () => {
+      const nextChallengeEpoch = 5760 // 2 days worth of epochs
+      const maxProvingPeriod = 2880 // 1 day
+      const result = calculateLastProofDate(nextChallengeEpoch, maxProvingPeriod, 'mainnet')
+
+      assert.isNotNull(result)
+      // Last proof should be at epoch 2880 (5760 - 2880)
+      const expectedDate = epochToDate(2880, 'mainnet')
+      assert.equal(result?.getTime(), expectedDate.getTime())
+    })
+
+    it('should handle edge case at proving period boundary', () => {
+      const nextChallengeEpoch = 2880
+      const maxProvingPeriod = 2880
+      const result = calculateLastProofDate(nextChallengeEpoch, maxProvingPeriod, 'mainnet')
+
+      // Should return null since lastProofEpoch would be 0
+      assert.isNull(result)
+    })
+  })
+})