Support new per-operation fee structure

[timfong888]

Original issue description, replaced by @rvagg comment below

Context

From the Pricing Proposal review (Apr 28–29, 2026):

Hugo: "all of this will change the current Costs api"

Rod: "In all of this there will be SDK work; which may end up being the hardest part of implementation (floor-price-while-zero-data contract problem is the second most complicated bit). Costs API was hard enough with the simple pricing, this will take a lot of care and thought and we might need to add some fuzz to our language and the things we return and give access to pricing schedules (which we should surface from the contracts)."

The pricing model is moving from a single floor + creation fee to a layered structure that the SDK / Costs API needs to expose cleanly — including the new per-operation gas fee paid by the user.

Scope

• Surface the on-contract pricing schedule so SDK consumers can read upcoming pricing (depends on filecoin-services#466)
• Differentiate fee components in the Costs API response:
  • Sybil fee (client-paid, currently 0.1 USDFC)
  • SP gas-cover fee on createDataSet (~$0.00112) — the per-operation fee originally scoped here
  • Recurring per-data-set floor ($0.06/mo today)
  • Per-piece add / delete fees
• Handle floor-price-while-zero-data semantics (drawing from escrow against an empty data set)
• Token-decimal aware floor — 6-decimal ERC20s like axlUSDC truncate the current $0.06/mo floor to 0 (separate pricing decision ticket coming)
• Add fuzz/flexibility to the API language and returned shapes so future pricing tweaks don't require breaking changes

Related

• filecoin-services#466 — contract-side pricing schedule (prerequisite)
• filecoin-services#458 — empty data set / floor-from-escrow
• Per-operation pricing for FilecoinWarmStorageService filecoin-services#469

Owner

Rod (assigned) — Hugo on SDK side

[rvagg]

Building on the description and in FilOzone/filecoin-services#469 (note the details in there, particularly the precision note) and assuming that shape continues to deployment, this is the design proposal for Synapse APIs:

Vocabulary: three top-level concepts used consistently across types, function names, fields, and docs.

• rates: recurring per-time charges (per-epoch / per-month). Streaming.
• fees: one-time charges that leave the user's USDFC balance permanently (paid to SP or burned). Each field suffix Fee (e.g. addPiecesFee).
• lockups: amounts reserved on a rail; recoverable at finalisation. Each field suffix Lockup (e.g. lifecycleLockup).

Group names are plural collective nouns; field suffixes are the matching singular. APIs, types, and docs follow this triplet throughout.

packages/synapse-core/src/warm-storage/get-price-list.ts (new, replaces get-service-price.ts)

export type GetPriceListOutput = {
  token: Address
  storagePerTibPerMonth: bigint
  provingServicePerMonth: bigint
  createDataSetFee: bigint
  addPiecesFee: bigint
  schedulePieceRemovalsFee: bigint
  deleteDataSetFee: bigint
  terminateServiceFee: bigint
  cdnEgressPerTib: bigint
  cacheMissEgressPerTib: bigint
  sybilFee: bigint
  lifecycleReserveTarget: bigint
  lifecycleReserveRefreshThreshold: bigint
}

export async function getPriceList(stateView, ...): Promise<GetPriceListOutput>

Delete get-service-price.ts. WarmStorageService.getServicePrice() in packages/synapse-sdk/src/warm-storage/service.ts becomes getPriceList() calling the new core function.

packages/synapse-core/src/warm-storage/calculate-effective-rate.ts

Rewrite formula:

// rate = bytes > 0 ? naturalRate(bytes) + provingServicePerMonth : 0
// per-month, then convert to per-epoch

Inputs change: takes storagePerTibPerMonth and provingServicePerMonth, drops minimumPricePerMonth. Empty data set short-circuits to zero.

packages/synapse-core/src/warm-storage/calculate-additional-lockup-required.ts

Scope to lockups only. Sybil fee (which was previously bundled here) is a fee, not a lockup, and moves to the fees calculation in get-upload-costs.ts.

export type CalculateAdditionalLockupRequiredOutput = {
  lifecycleLockup: bigint    // new, populated from prices.lifecycleReserveTarget for new data sets
  streamingLockup: bigint    // delta from rate change (was rateLockupDelta)
  cdnLockup: bigint          // CDN rails' fixed lockup (was cdnFixedLockup)
  total: bigint
}

Drop the floor-to-floor edge case (any size delta produces a rate delta under additive math).

packages/synapse-core/src/warm-storage/get-upload-costs.ts

Restructure output with fees/lockups breakdown:

export type GetUploadCostsOutput = {
  rates: { perEpoch: bigint, perMonth: bigint }

  fees: {                        // gone after this op (paid to SP or burned)
    createDataSetFee: bigint
    sybilFee: bigint
    addPiecesFee: bigint
    total: bigint
  }

  lockups: {                     // reserved on rails, refunded at finalisation
    lifecycleLockup: bigint      // pool for future per-op fees (PDP rail fixed lockup); refill amount on ongoing ops
    streamingLockup: bigint      // delta to PDP rail's rate × period reserve
    cdnLockup: bigint            // CDN rails' fixed lockup
    total: bigint
  }

  depositNeeded: bigint          // additional USDFC user needs to deposit before this op
  needsFwssMaxApproval: boolean
  ready: boolean
}

Naming pattern: plural collective nouns at the group level (fees, lockups); each field's suffix matches the group (*Fee, *Lockup). Each group has its own total; no combined total (would conflate gone with recoverable).

Optional input for projected future expectations (would need solid docs for this) expectedOps?: { addPieces?: number, scheduleRemovals?: number } adds projected per-op cost into depositNeeded for callers planning a workload. Default zero.

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

calculateMultiContextCosts: every field in fees and lockups scales per context (each copy = its own data set). Aggregate by field-wise sum across contexts; aggregate rates as today.

packages/synapse-core/src/utils/constants.ts

Drop chain-tunable values from constants. Keep Filecoin-fundamental ones.

// Keep (chain-fundamental, won't change without protocol changes)
export const EPOCHS_PER_DAY = 2880n
export const EPOCHS_PER_MONTH = 86400n           // 30 × EPOCHS_PER_DAY

// Keep (FWSS / PDPVerifier baseline; matches contract immutables, change implies coordinated upgrade)
export const DEFAULT_LOCKUP_DAYS = 30n
export const LOCKUP_PERIOD = DEFAULT_LOCKUP_DAYS * EPOCHS_PER_DAY
export const USDFC_SYBIL_FEE = 100_000_000_000_000_000n  // 0.1 USDFC, fallback only

// Drop (now sourced from getPriceList)
// USDFC_STORAGE_PRICE_PER_TIB_PER_MONTH
// USDFC_MINIMUM_STORAGE_RATE_PER_MONTH
// CDN_FIXED_LOCKUP { cdn, cacheMiss, total }
// CDN_EGRESS_PRICE_PER_TIB

Rationale: streaming-rate prices and per-op fees are designed to be tuned via FWSS upgrades; SDK reads them from chain. Lockup period and sybil fee are firm (changing them would be a coordinated PDPVerifier/FWSS upgrade, not a pricing adjustment). EPOCHS_PER_* are protocol-level constants. USDFC_SYBIL_FEE kept as a fallback / reference but the chain value is canonical when fetched (it's in PriceList). Maybe deprecate USDFC_SYBIL_FEE and see where it hurts?

packages/synapse-react/src/warm-storage/use-service-price.ts

Rename to use-price-list.ts, switch to the new core function and output type.

Caching

getPriceList() result is per-deployment, rarely changes. Cache at the SDK instance level with manual invalidation on contract upgrade (or simple TTL, e.g. 1h). All hot paths use cached values.

Tests

packages/synapse-core/test/calculate-effective-rate.test.ts: rewrite for additive maths. Tiny-data-set case still produces non-zero rate (via proving fee, not floor). packages/synapse-core/test/calculate-additional-lockup-required.test.ts: rewrite for new locked-only output (lifecycleLockup, streamingLockup, cdnLockup, total); drop sybil-fee assertions. packages/synapse-core/test/get-upload-costs.test.ts: rewrite for the fees / lockups split; new cases for lifecycle reserve refill projection (lockups.lifecycleLockup > 0 mid-life), expectedOps projection, per-op fee debits. Multi-context test updates for per-context, field-wise aggregation.

Docs

docs/dist/developer-guides/storage/storage-costs.md: full rewrite. New shape: streaming charges (storage + proving), per-op fees table mirroring the contract price list, lifecycle reserve mechanic, multi-copy scaling, worked examples for small / medium / large data sets.

Sources for context:

• FilOzone/filecoin-services#469: pricing proposal and contract spec
• FilOzone/filecoin-services#468: pricing reasoning and value derivation
• FilOzone/synapse-sdk#763: This issue for SDK additions
• Pricing Model Framing (Google Doc): Tim's Customer UX vs SP Cost Coverage analysis
• Pricing Sensitivity (Google Sheet): scenario-based cost projections

[juliangruber]

• rates: recurring per-time charges (per-epoch / per-month). Streaming.

I assume this is also a suffix, like fees and lookup?

storagePerTibPerMonth: bigint

Should this and similar fields include "rate", or is that the price including rate and fees? Do we need a 4th named for the combined price?