Per-operation pricing for FilecoinWarmStorageService

[rvagg]

Project Tracking

This is the master tracking issue for the per-operation pricing changes for GA. Below is intended to make sure we're thinking wholistically on delivering for this effort:

• Termination clarification / simplification
  • Termination clarifications / simplifications design #477
  • [pdp] Simplified DataSet terminations and cleanup for GA pdp#269
  • PDPVerifier upgrade from v3.3.0 to v3.4.0 pdp#271
  • FWSS support for simplified DataSet terminations and cleanup for GA #484
  • PDP: Implement pdpv0 client termination endpoint filecoin-project/curio#1235
  • PDP: Update pdpv0 termination cleanup state machine for PDPVerifier cleanup mode filecoin-project/curio#1236
  • PDP: Send 0.1 FIL cleanup deposit on pdpv0 data set creation filecoin-project/curio#1237
  • Synapse support for simplified DataSet terminations and cleanup for GA synapse-sdk#792
  • update dealbot session key dealbot#575
• Client changes:
  • Support new per-operation fee structure synapse-sdk#763
  • Use Synapse's costs API (including per operation fee structure for GA) filecoin-project/filecoin-pin#402
• FWSS changes
  • Emit event from dataSetDeleted method, handle optional signed user auth #457
  • feat: per-dataset pricing #482
  • Per Operation Payments: feat: operational pricing #488
  • Support pricing schedule changes via contract upgrade with announcement window #466
  • Set addPieces batch limits and adjust pricing #496
  • feat(pricing): add getPriceList() for full on-chain price discovery #501
• Test pricing, termination, and calldata limit contract+client changes in devnet foc-devnet#113
• FWSS M4.2 Contract Upgrade #453
• Public communication
  • Docs: validate and document the pricing changes for GA synapse-sdk#817
  • Document rationale for new pricing model (sybil, gas-cover, floor, per-piece) #468
  • filecoin.cloud updates?
  • email outreach with subscribers / known users?

About

FWSS currently charges clients a single streaming USDFC rate per dataset, scaled by stored data with a minimum floor. Storage providers are expected to absorb the gas cost of every onchain operation.

The proposed change is to introduce per-operation pricing. Onchain operations (create data set, add pieces, schedule piece removals, delete data set, terminate service) become individual billable line items, paid by the client to the SP at the moment the operation occurs. The streaming rate is split into a fixed Proving Service fee per data set plus a per-TiB storage rate.

All operation fees flow through the existing PDP payment rail via FilecoinPay's one-time payment mechanism. A small lifecycle reserve is locked at data set creation, replenished as operations occur, and refunded if unused at rail finalisation. No new payment rails are introduced.

Proposed prices (USDFC)

Initial values derived from observed gas costs at current FIL prices with headroom for volatility. Reasoning will be captured alongside the values so they can be revisited as conditions change; see #468. Tunability is a core requirement: prices must be adjustable as network conditions, gas, and FIL price drift.

This is the current draft price list, I'll update it if/when it changes. There's still some ongoing investigation.

Item	Charge	Notes
Storage	$2.50 / TiB / month	streaming rate, paid to SP
Proving Service	$0.024 / data set / month	streaming rate, additive to storage, paid to SP
Create Data Set	$0 $0.00112 $0.0025 $0.025	one-time on creation, paid to SP. Network Congestion Fee (below) also applies.
Network Congestion Fee	$0.10	one-time on every data set creation, burned via FilecoinPay's USDFC auction (Sybil Fee)
Add Pieces	$0.002 $0.0005 + $0.0003 x N	per addPieces call (flat per batch) (N = number of pieces in a batch), paid to SP
Schedule Piece Removals	$0.002	per schedulePieceDeletions call (flat per batch), paid to SP
Delete Data Set	$0.00112	only when user-signed authorisation is supplied, paid to SP
Terminate Service	$0.00112	only when user-initiated, paid to SP
Egress / cache miss	up to $0.014 / GB	usage-settled by FilBeam

Implementation nuances

• Empty data sets pay nothing. Storage rate and proving fee are zero until pieces exist. Both activate on first piecesAdded. Charge floor price even if zero data #458 likely won't be needed.
• Proving fee is additive, not a floor. Rate becomes naturalRate(bytes) + provingFee, replacing the current max(naturalRate, floor).
• Add vs delete batch asymmetry. addPieces is bounded to 61 pieces per call by the extraData size limit. schedulePieceDeletions has no equivalent cap (only PDPVerifier's MAX_ENQUEUED_REMOVALS = 2000 per-data set queue limit). Per-op delete pricing creates SP gas asymmetry at large batch sizes. Cost of delete is spread over schedulePieceDeletions and nextProvingPeriod so is hard to measure. addPieces batch size may be lifted (Should we increase the extradata limits ? #460) and we may reconsider this cost based on the higher limits.
• Lifecycle reserve. A small fixed-lockup pool (in the order of ~$0.10) is maintained on the PDP rail to give users headroom for wind-down operations after termination, when FilecoinPay forbids refilling a terminated rail's lockup. While the rail is active the pool also smooths per-op gas: most ops draw their fee from the pool in a single call, with periodic refills back to target when the balance drops below a threshold. Users see ~$0.10 of additional USDFC locked while the data set is active, refunded at rail finalisation.
• Lockup window after termination. Per-op fees continue firing from the existing lifecycle reserve. FilecoinPay forbids raising a terminated rail's fixed lockup, so the pool cannot be refilled. Users wanting more wind-down deletions than their pool supports must pre-fund before terminating; SP-terminated users are stuck with whatever was in the pool at termination.
• Asymmetric termination paths. User-initiated terminateService charges the termination fee and best-effort tops up the lifecycle reserve. SP-initiated termination charges no fee and does not top up.
• Delete-data set fee gated by user signature. Per FilOzone/filecoin-services#457 (now in scope), the fee fires only when the SP supplies a valid client EIP-712 authorization. SP-unilateral deletions remain free.
• Token precision. $0.024/month math fits 18-decimal USDFC. Does not fit 6-decimal stablecoins (axlUSDC etc.). Launch is USDFC-only; multi-token support is will have a per-token PriceList and 6-decimal tokens likely get a proving fee of $0.0864/month.
• Existing data sets are not back-filled. Live rails keep their pre-upgrade rate until the next piecesAdded or nextProvingPeriod-with-removals triggers a recalculation. Dormant pre-upgrade datasets stay at the old rate indefinitely.
• Per-epoch precision. The rail rate is (storagePerMonth + provingServicePerMonth) / EPOCHS_PER_MONTH, integer-divided. Each summed component truncates sub-USDFC per epoch; total cumulative loss is ~1e-13 USDFC per month, well below USDFC's smallest representable unit. Same magnitude as the existing floor model, just two truncations summed instead of one MAX'd. Lockup and pre-flight math must use multiply-first form (perMonth × months) to preserve the exact user-facing monthly value; per-epoch truncation is a rail-side artefact only. Same pattern the contract already uses for the floor; SDK should mirror it.

[rvagg]

Implementation proposal details

Original replaced with updated in post further down this issue after feedback

No breaking ABI or storage layout changes. Behavioural changes consumers should be aware of: calculateRatePerEpoch returns the new additive formula; per-op fee events fire as one-time payments on the existing PDP rail; lifecycle reserve activity surfaces as additional RailLockupModified events.

Architecture

Pricing values and rail orchestration are factored out of FWSS into a per-token price library plus three Solidity libraries for math and orchestration. Prices are Solidity constant literals in the price library. FWSS holds no price values, no public pricing API, no token-aware machinery.

• PriceList.sol (struct): generic shared PriceList struct including IERC20 token plus all price fields.
• PriceListUSDFC.sol (library): all USDFC prices as internal constant literals (open the file, see the numbers). Plus a forToken(IERC20 token) pure helper that returns a PriceList populated from the constants.
• FWSSRails: FilecoinPay orchestration (rail creation, lockup, one-time payments + refresh, termination, CDN).
• FWSSPricing: pure pricing math (rate calc, lockup requirements, lifecycle reserve sizing) plus the existing payer-setup pre-flight.
• FWSSSettlement: existing _findProvenEpochs and proving-period math, lifted into a library over the provenPeriods storage mapping.

Tunability via FWSS impl upgrades. A price change is a source edit to PriceListUSDFC.sol plus a standard UUPS announce-then-execute. Reviewers diff the price library between old and new impl source. No new storage slots.

Multi-token deferred but assumed coming. FWSS today is fully USDFC-coupled (every createRail, getAccountInfoIfSettled, operatorApprovals hardcodes USDFC). Adding a second token needs sibling price libraries plus a DataSetInfo/rail-setup refactor. Library shape and discovery API absorb that without caller churn or much complexity.

Internal vs external library: default to internal during development; flip to external (public entry points, DELEGATECALL'd) if FWSS bytecode approaches the size cap. Same pattern already used for SignatureVerificationLib.

Convention

Callbacks that touch pricing resolve a price snapshot at entry and pass it to any library calls:

function piecesAdded(...) external onlyPDPVerifier {
    PriceList memory prices = PriceListUSDFC.forToken(usdfcTokenAddress);
    FWSSRails.payOpFeeWithRefresh(prices, payments, info.pdpRailId, prices.addPiecesFee);
    FWSSPricing.updateRate(prices, payments, info.pdpRailId, leafCount);
    ...
}

Library functions never read pricing; all inputs are explicit.

PriceList struct

struct PriceList {
    IERC20 token;
    uint256 storagePerTibPerMonth;
    uint256 provingServicePerMonth;
    uint256 createDataSetFee;
    uint256 addPiecesFee;
    uint256 schedulePieceRemovalsFee;
    uint256 deleteDataSetFee;
    uint256 terminateServiceFee;
    uint256 cdnEgressPerTib;
    uint256 cacheMissEgressPerTib;
    uint256 sybilFee;
    uint256 lifecycleReserveTarget;
    uint256 lifecycleReserveRefreshThreshold;
}

Public discovery API on FilecoinWarmStorageServiceStateView

Lives on the existing view contract, not the FWSS proxy. Mirrors the synapse-sdk token: shape.

function getPriceList(IERC20 token) external view returns (PriceList memory);  // single token, reverts on unsupported
function getPriceLists() external view returns (PriceList[] memory);           // length-1 today, grows with token count
function getSupportedTokens() external view returns (IERC20[] memory);         // length-1 today, grows with token count

getPriceList(token) dispatches per token, reverts on unsupported. Array methods grow as tokens are added. No API churn when a second token arrives.

FWSSRails

function createPDPRail(PriceList memory prices, FilecoinPayV1 payments, IERC20 token, address payer, address payee) internal returns (uint256);
function createCDNRails(PriceList memory prices, FilecoinPayV1 payments, IERC20 token, address payer, address spPayee, address filBeamBeneficiary) internal returns (uint256, uint256);
function settleSybilBurn(PriceList memory prices, FilecoinPayV1 payments, IERC20 token, address payer) internal;
function payOpFeeWithRefresh(PriceList memory prices, FilecoinPayV1 payments, uint256 railId, uint256 opFee) internal;
function updateRate(FilecoinPayV1 payments, uint256 railId, uint256 newRate) internal;
function terminatePDPRail(PriceList memory prices, FilecoinPayV1 payments, uint256 railId, bool isUserInitiated) internal;
function terminateCDNRails(FilecoinPayV1 payments, uint256 cacheMissRailId, uint256 cdnRailId) internal;
function topUpFixedLockup(FilecoinPayV1 payments, uint256 railId, uint256 amount) internal;
function topUpCDNRails(FilecoinPayV1 payments, uint256 cacheMissRailId, uint256 cdnRailId, uint256 cacheMissAmount, uint256 cdnAmount) internal returns (uint256, uint256);

FWSSPricing

function calculateStorageRate(PriceList memory prices, uint256 totalBytes) internal pure returns (uint256);
function calculateLockupRequirement(PriceList memory prices, uint256 ratePerEpoch) internal pure returns (uint256);
function calculateLifecycleReserve(PriceList memory prices) internal pure returns (uint256);
function validatePayerSetup(PriceList memory prices, FilecoinPayV1 payments, IERC20 token, address payer, bool includeCDN, address fwssAddress) internal view;

FWSSSettlement

function findProvenEpochs(mapping(uint256 => uint256) storage provenPeriodsForDataSet, uint256 fromEpoch, uint256 toEpoch, uint256 activationEpoch, uint256 maxProvingPeriod) internal view returns (uint256, uint256);
function provingPeriodForEpoch(uint256 activationEpoch, uint256 epoch, uint256 maxProvingPeriod) internal pure returns (uint256);
function calcPeriodDeadline(uint256 activationEpoch, uint256 periodId, uint256 maxProvingPeriod) internal pure returns (uint256);

What stays in FWSS

Storage layout, PDPListener and IValidator callback entry points (thin orchestrators over the libraries), governance, existing immutable addresses (pdpVerifierAddress, usdfcTokenAddress, etc.), event emission, DataSetInfo. EIP-712 verification stays in SignatureVerificationLib. No public pricing on the proxy; discovery moves to the view contract.

[BigLep]

@rvagg : thanks for putting this together! Per slack, lets please:

1. Link all related work for delivering on "GA pricing updates". I'm treating this as the master tracking issue, but I believe there is Synapse work (Support new per-operation fee structure synapse-sdk#763 ), and I'm wondering if there's anything else we need to account for (e.g., foc-devnet, deployment scripts, Curio).
2. Add estimates for each item

[wjmelements]

PriceList

PriceList is too large (13 words). For example, for this usage:

    PriceList memory prices = PriceListUSDFC.forToken(usdfcTokenAddress);
    FWSSRails.payOpFeeWithRefresh(prices, payments, info.pdpRailId, prices.addPiecesFee);
    FWSSPricing.updateRate(prices, payments, info.pdpRailId, leafCount);

• Rail operations don't need to know the token.
• Rate calculation doesn't need the deleteDataSetFee.
• structs can only live in storage or memory even when they are constant

I would modify the methods to only parameterize what is needed, and use the struct only for offchain view methods.

Adding more supported tokens

To support more tokens within FWSS, you would have to track which token per dataset. Currently that information is only accessible by looking up getRail with the dataset's railId, which loads 12 (!) slots. Another way to do this would be to extend the DataSetInfo to add the IERC20 token, but existing data sets would then have IERC20(address(0)) for that field, which we would like to interpret as NATIVE_TOKEN because that is how it is treated in FilecoinPayV1.

We've been avoiding this by hardcoding USDFC, and that's fine. Instead of expanding FWSS to support every token and having a different pricing policy per token, each service can have its own token+policy hardcoded. This would also avoid the PriceListUSDFC.forToken lookup.

For example, in combination with the PriceList suggestion, settleSybilBurn would go from

• settleSybilBurn(PriceList memory prices, FilecoinPayV1 payments, IERC20 token, address payer)

to

• settleSybilBurn(address payer) (with payments, token, and sybileFeebeingimmutable` in the library).

External libraries

External libraries are a good way to stay under the codesize limit. As a guideline though, they'll only save you on codesize if they have logic in excess of the delegation's dispatch and the calldata coding. I suspect some of the proposed methods, like updateRate, might not meet that threshold.

The superior delegation architecture is to adopt a diamond pattern such as ERC-8167. This would let us abolish the View contract, and perhaps constrain the total number of delegatecalls. I have implemented a one-method-per-delegate architecture in a different repo; code generation helps with a lot of the boilerplate.