refactor(sdk): decompose preflight into reusable primitives

- Add PaymentsService.checkServiceReadiness() for any service
- Rename calculateStorageCost() to calculateUploadCost(), expose floor pricing
- Simplify prepareStorageUpload() signature (dataSize only, monthly cost only)
- Remove checkAllowanceForStorage()
- Add getContractAddress(), export ServiceReadinessCheck type

Author: rvagg

packages/synapse-sdk/src/payments/service.ts

@@ -4,7 +4,7 @@
  */
 
 import { ethers } from 'ethers'
-import type { RailInfo, SettlementResult, TokenAmount, TokenIdentifier } from '../types.ts'
+import type { RailInfo, ServiceReadinessCheck, SettlementResult, TokenAmount, TokenIdentifier } from '../types.ts'
 import {
   CHAIN_IDS,
   CONTRACT_ABIS,
@@ -602,6 +602,69 @@ export class PaymentsService {
     }
   }
 
+  /**
+   * Check if the user is ready to use a service with given requirements
+   * Performs comprehensive checks including approval status, allowances, and funds
+   * @param service - Service contract address
+   * @param requirements - Required rate, lockup, and lockup period
+   * @param token - The token to check (defaults to USDFC)
+   * @returns Readiness status with detailed checks, current state, and gaps
+   */
+  async checkServiceReadiness(
+    service: string,
+    requirements: {
+      rateNeeded: bigint
+      lockupNeeded: bigint
+      lockupPeriodNeeded: bigint
+    },
+    token: TokenIdentifier = TOKENS.USDFC
+  ): Promise<ServiceReadinessCheck> {
+    // Fetch approval and account info in parallel
+    const [approval, accountInfo] = await Promise.all([this.serviceApproval(service, token), this.accountInfo(token)])
+
+    // Perform all checks
+    const checks = {
+      isOperatorApproved: approval.rateAllowance > 0n || approval.lockupAllowance > 0n,
+      hasSufficientFunds: accountInfo.availableFunds >= requirements.lockupNeeded,
+      hasRateAllowance: approval.rateAllowance >= approval.rateUsed + requirements.rateNeeded,
+      hasLockupAllowance: approval.lockupAllowance >= approval.lockupUsed + requirements.lockupNeeded,
+      hasValidLockupPeriod: approval.maxLockupPeriod >= requirements.lockupPeriodNeeded,
+    }
+
+    const sufficient = Object.values(checks).every((check) => check)
+
+    // Calculate gaps if not sufficient
+    const gaps: {
+      fundsNeeded?: bigint
+      rateAllowanceNeeded?: bigint
+      lockupAllowanceNeeded?: bigint
+      lockupPeriodNeeded?: bigint
+    } = {}
+
+    if (!checks.hasSufficientFunds) {
+      gaps.fundsNeeded = requirements.lockupNeeded - accountInfo.availableFunds
+    }
+    if (!checks.hasRateAllowance) {
+      gaps.rateAllowanceNeeded = approval.rateUsed + requirements.rateNeeded - approval.rateAllowance
+    }
+    if (!checks.hasLockupAllowance) {
+      gaps.lockupAllowanceNeeded = approval.lockupUsed + requirements.lockupNeeded - approval.lockupAllowance
+    }
+    if (!checks.hasValidLockupPeriod) {
+      gaps.lockupPeriodNeeded = requirements.lockupPeriodNeeded - approval.maxLockupPeriod
+    }
+
+    return {
+      sufficient,
+      checks,
+      currentState: {
+        approval,
+        accountInfo,
+      },
+      gaps: sufficient ? undefined : gaps,
+    }
+  }
+
   async deposit(
     amount: TokenAmount,
     token: TokenIdentifier = TOKENS.USDFC,

packages/synapse-sdk/src/storage/context.ts

@@ -54,6 +54,8 @@ import {
   getCurrentEpoch,
   METADATA_KEYS,
   SIZE_CONSTANTS,
+  TIME_CONSTANTS,
+  TOKENS,
   timeUntilEpoch,
 } from '../utils/index.ts'
 import { combineMetadata, metadataMatches, objectToEntries, validatePieceMetadata } from '../utils/metadata.ts'
@@ -785,34 +787,70 @@ export class StorageContext {
 
   /**
    * Static method to perform preflight checks for an upload
-   * @param size - The size of data to upload in bytes
-   * @param withCDN - Whether CDN is enabled
+   * Composes cost calculation from WarmStorageService and readiness checks from PaymentsService
    * @param warmStorageService - WarmStorageService instance
    * @param paymentsService - PaymentsService instance
+   * @param size - The size of data to upload in bytes
    * @returns Preflight check results without provider/dataSet specifics
    */
   static async performPreflightCheck(
     warmStorageService: WarmStorageService,
     paymentsService: PaymentsService,
-    size: number,
-    withCDN: boolean
+    size: number
   ): Promise<PreflightInfo> {
     // Validate size before proceeding
     StorageContext.validateRawSize(size, 'preflightUpload')
 
-    // Check allowances and get costs in a single call
-    const allowanceCheck = await warmStorageService.checkAllowanceForStorage(size, withCDN, paymentsService)
+    // Calculate upload cost
+    const cost = await warmStorageService.calculateUploadCost(size)
 
-    // Return preflight info
-    return {
-      estimatedCost: {
-        perEpoch: allowanceCheck.costs.perEpoch,
-        perDay: allowanceCheck.costs.perDay,
-        perMonth: allowanceCheck.costs.perMonth,
+    // Calculate rate per epoch from floor-adjusted monthly price
+    const pricing = await warmStorageService.getServicePrice()
+    const ratePerEpoch = cost.withFloorPerMonth / pricing.epochsPerMonth
+
+    // Calculate lockup requirements
+    const lockupEpochs = BigInt(TIME_CONSTANTS.DEFAULT_LOCKUP_DAYS * TIME_CONSTANTS.EPOCHS_PER_DAY)
+    const lockupNeeded = ratePerEpoch * lockupEpochs
+
+    // Check payment readiness
+    const readiness = await paymentsService.checkServiceReadiness(
+      warmStorageService.getContractAddress(),
+      {
+        rateNeeded: ratePerEpoch,
+        lockupNeeded,
+        lockupPeriodNeeded: lockupEpochs,
       },
+      TOKENS.USDFC
+    )
+
+    // Build error message if not sufficient
+    let message: string | undefined
+    if (!readiness.sufficient) {
+      const issues: string[] = []
+      if (!readiness.checks.hasSufficientFunds && readiness.gaps?.fundsNeeded) {
+        issues.push(`Insufficient funds: need ${readiness.gaps.fundsNeeded} more`)
+      }
+      if (!readiness.checks.isOperatorApproved) {
+        issues.push('Operator not approved for service')
+      }
+      if (!readiness.checks.hasRateAllowance && readiness.gaps?.rateAllowanceNeeded) {
+        issues.push(`Insufficient rate allowance: need ${readiness.gaps.rateAllowanceNeeded} more`)
+      }
+      if (!readiness.checks.hasLockupAllowance && readiness.gaps?.lockupAllowanceNeeded) {
+        issues.push(`Insufficient lockup allowance: need ${readiness.gaps.lockupAllowanceNeeded} more`)
+      }
+      if (!readiness.checks.hasValidLockupPeriod && readiness.gaps?.lockupPeriodNeeded) {
+        issues.push(`Lockup period too short: need ${readiness.gaps.lockupPeriodNeeded} more epochs`)
+      }
+      message = issues.join('; ')
+    }
+
+    return {
+      estimatedCostPerMonth: cost.withFloorPerMonth,
       allowanceCheck: {
-        sufficient: allowanceCheck.sufficient,
-        message: allowanceCheck.message,
+        sufficient: readiness.sufficient,
+        message,
+        checks: readiness.checks,
       },
       selectedProvider: null,
       selectedDataSetId: null,
@@ -829,8 +867,7 @@ export class StorageContext {
     const preflightResult = await StorageContext.performPreflightCheck(
       this._warmStorageService,
       this._synapse.payments,
-      size,
-      this._withCDN
+      size
     )
 
     // Return preflight info with provider and dataSet specifics

packages/synapse-sdk/src/storage/manager.ts

@@ -213,22 +213,19 @@ export class StorageManager {
     size: number,
     options?: { withCDN?: boolean; metadata?: Record<string, string> }
   ): Promise<PreflightInfo> {
-    // Determine withCDN from metadata if provided, otherwise use option > manager default
-    let withCDN = options?.withCDN ?? this._withCDN
-
-    // Check metadata for withCDN key - this takes precedence
+    // Note: withCDN from metadata is checked here for validation but doesn't affect base storage costs
+    // CDN pricing is usage-based (egress charges), so base storage cost is the same regardless
     if (options?.metadata != null && METADATA_KEYS.WITH_CDN in options.metadata) {
       // The withCDN metadata entry should always have an empty string value by convention,
       // but the contract only checks for key presence, not value
       const value = options.metadata[METADATA_KEYS.WITH_CDN]
       if (value !== '') {
         console.warn(`Warning: withCDN metadata entry has unexpected value "${value}". Expected empty string.`)
       }
-      withCDN = true // Enable CDN when key exists (matches contract behavior)
     }
 
     // Use the static method from StorageContext for core logic
-    return await StorageContext.performPreflightCheck(this._warmStorageService, this._synapse.payments, size, withCDN)
+    return await StorageContext.performPreflightCheck(this._warmStorageService, this._synapse.payments, size)
   }
 
   /**