feat: settle CDN bandwidth per shared rail (subscription)

[juliangruber]

What

Updates FilBeamOperator so CDN bandwidth is metered and settled per shared bandwidth rail (the CDN subscription) instead of per data set, while cache-miss stays per data set.

Full proposal, with rationale and the companion changes in the other repos: https://gist.github.com/juliangruber/a34b225f9588ec68d069054d731e20c9

The gist also links to the companion draft PRs in FilOzone/filecoin-services, FilOzone/synapse-sdk, and filbeam/worker.

Why

Multi-copy upload stores a piece in 2 data sets on 2 providers. When CDN is enabled on both, the bandwidth service was bought twice. FWSS now lets data sets share one bandwidth rail keyed by (payer, group), and exposes settleCDNBandwidthRail(cdnRailId, cdnAmount) to settle that shared rail once. The shared cdnRailId is the subscription identity, so the operator aggregates and settles bandwidth by rail id.

How

• Bandwidth usage accumulates in cdnRailAmount[cdnRailId], resolved from FilecoinWarmStorageServiceStateView.getDataSet(dataSetId).cdnRailId at record time. Cache-miss stays in dataSetUsage[dataSetId].
• settleCDNBandwidthRails(uint256[] cdnRailIds) is the canonical bandwidth settlement path, it settles each shared rail once with its aggregated amount via FWSS settleCDNBandwidthRail. This is what the FilBeam worker calls with the distinct rail ids it has metered.
• settleCDNPaymentRails(uint256[] dataSetIds) is kept as a convenience that resolves each data set to its rail first, both paths share one internal settle-by-rail-id helper.
• Cache-miss is settled per data set via FWSS settleFilBeamPaymentRails(dataSetId, 0, cacheMissAmount), with cdnAmount always 0 so the bandwidth portion is never double-settled.
• CDNSettlement is keyed by cdnRailId, CacheMissSettlement stays keyed by dataSetId. MockFWSS gains settleCDNBandwidthRail.

Cross-repo interface

The wire ABI the filbeam/worker PR targets:

• recordUsageRollups(uint256 toEpoch, uint256[] dataSetIds, uint256[] cdnBytesUsed, uint256[] cacheMissBytesUsed) - usage reported per data set, the contract resolves and aggregates bandwidth onto the shared rail.
• settleCDNBandwidthRails(uint256[] cdnRailIds) - bandwidth, once per rail.
• settleCacheMissPaymentRails(uint256[] dataSetIds) - cache-miss, per data set.

Reviewer notes

The real FWSS must expose settleCDNBandwidthRail(uint256,uint256) callable by the FilBeam controller, see the companion filecoin-services PR. Called here through a minimal local IFilBeamBandwidthSettlement interface against fwssContractAddress.

Follow-ups

These are intentionally out of scope for this draft.

• Consider collapsing settleCDNPaymentRails (by data set) into settleCDNBandwidthRails (by rail) once downstream settles by rail id everywhere.
• Per-rail replay guard for bandwidth recording, mirroring the per-data-set maxReportedEpoch guard.