Modify CDN payment rails and add methods for usage-based payments #237

pyropy · 2025-09-25T14:59:37Z

Motivation

To support FilBeam's usage-based payment model, this PR adds methods to the FWSS contract for settling CDN payment rails without payment validators

Description

Introduces two new methods:

settleCDNPaymentRails - for settling CDN payment rails
topUpCDNPaymentRails - for topping up balance in CDN payment rails (increasing fixed lockup)

Adding these two methods would enable usage-based payments for CDN-related payment rails as FilBeam contract would be able to calculate settlement amounts based on the reported egress usage and settle payment rails via settleCDNPaymentRails.

Validator has been removed from CDN-related payment rails as settling is done by FilBeam contract.

Users are be able to increase fixed lockup for their CDN-related payment rails by calling topUpCDNPaymentRails in return increasing their data set egress limit. Initial fixed lockup for CDN payment rails is set to 0 as we're unable to pass lockup amounts via metadata without increasing contract byte size due to addition of helper new functions.

Changelog

Remove validator from CDN payment rails
Add methods for FilBeam operator contract to settle cdn payment rails
Add method for increasing fixed lockup on cdn payment rails topUpCDNPaymentRails
Cleanup variables, errors and events related to cdn service termination
Remove handling of cdn payment rail termination from railTerminated method

Related to:

- Remove validator from cdn payment rails - Add fixed lockup during cdn payment rail creation - Add methods for FilBeam operator contract to settle cdn payment rails - Add method for increasing fixed lockup on cdn payment rails - Cleanup variables, errors and events related to cdn service termination - Remove handling of cdn payment rail termination from `railTerminated` method

…t/usage-based-payments

- Replace percentage-based lockup ratios with absolute lockup values - Remove cdnEndEpoch field from DataSetInfo as CDN rails don't track termination - Update metadata keys from ratio to value naming convention - Modify lockup calculation to use provided values directly instead of percentage calculations - Update test cases to use absolute values instead of percentages - Add validation for empty lockup value strings - Support asymmetric and zero lockup values for flexible CDN configuration

… settleCDNPaymentRails method - Combine two separate settlement methods into one with signature: settleCDNPaymentRails(uint256 dataSetId, uint256 cdnAmount, uint256 cacheMissAmount) - Consolidates validation logic and reduces code duplication - Maintains all access control and validation requirements - Add comprehensive test coverage with 13 test cases covering success scenarios, access control, validation errors, event emission, and payment processing

…t/usage-based-payments

- Remove specialized _getCDNMetadataKV helper function - Replace all calls with the more general _getSingleMetadataKV("withCDN", value) - Simplifies codebase by using existing generic metadata helper

…stCreateDataSetCreatesRail

- Remove redundant tests - Add CDNPaymentRailsToppedUp event and modify top-up tests

Co-authored-by: Julian Gruber <[email protected]>

…t/usage-based-payments

bajtos · 2025-10-06T14:00:04Z

service_contracts/src/FilecoinWarmStorageService.sol

+     * @param cdnAmount Amount to settle for CDN rail
+     * @param cacheMissAmount Amount to settle for cache miss rail
+     */
+    function settleCDNPaymentRails(uint256 dataSetId, uint256 cdnAmount, uint256 cacheMissAmount)


We are discussing this API in the PR adding code that calls this method, let's resolve that thread first:

filbeam/contracts#1 (comment)

bajtos

Other than the discussion around settleCDNPaymentRails API, I think the pull request looks great now!

…BeamPaymentRails_*

wjmelements · 2025-10-07T04:50:11Z

service_contracts/src/FilecoinWarmStorageService.sol


    event ViewContractSet(address indexed viewContract);

+    event CDNPaymentRailsToppedUp(uint256 indexed dataSetId, uint256 totalCdnLockup, uint256 totalCacheMissLockup);


Do we really need an event for this?

wjmelements · 2025-10-07T04:53:23Z

service_contracts/src/FilecoinWarmStorageService.sol

                createData.payer, // from (payer)
                filBeamBeneficiaryAddress, // to FilBeam beneficiary
-                address(this), // this contract acts as the arbiter
+                address(0), // no validator


are you sure? We use this validator to adjust payments according to service uptime. For example for PDP if you aren't proving possession you aren't getting paid. Maybe CDN should have its own validator?

Is IValidator(filBeamController) not possible because the controller doesn't have the information yet?

service_contracts/src/FilecoinWarmStorageService.sol

…lOzone#237)

wjmelements · 2025-10-10T05:43:07Z

service_contracts/src/FilecoinWarmStorageService.sol

                usdfcTokenAddress, // token address
                createData.payer, // from (payer)
                payee, // payee address from registry
-                address(this), // this contract acts as the arbiter


since this contract is not the rail validator any more, don't need to set railToDataSet for the rail

@rvagg

Reviewer @rvagg CC @Chaitu-Tatipamula Closes #277 Resolves #269 (review) We are able to remove this mapping because it is only used by IValidator functions, and, since #237, FWSS is not the IValidator for these rails. This reduces codesize 23,991 -> 23,898 (-93) #### Changes * remove railToDataSet mapping for both cdn rails

@bajtos

## Description This pull request modifies the existing `CDNPaymentRailsToppedUp `event by adding two new fields: `cdnAmountAdded `and `cacheMissAmountAdded`. These additions are designed to simplify the tracking of remaining user egress in the off-chain component. ## Motivation Following discussions with @bajtos, we identified the need to modify the `CDNPaymentRailsToppedUp` event signature to streamline our egress accounting process. Our initial approach involved extending the `FilBeamOperator` contract with a `topUpCDNPaymentRails` method and adding authorization to the existing `FilecoinWarmStorageService.topUpCDNPaymentRails` method. However, I opted against this approach since these modifications can be implemented through a contract upgrade instead. ## Changelog - Add `cdnAmountAdded` and `cacheMissAmountAdded` fields to `CDNPaymentRailsToppedUp` event - Refactor tests to match updated event signature ## Related - filbeam/worker#333 - #237

wjmelements · 2025-10-23T15:53:59Z

service_contracts/src/FilecoinWarmStorageService.sol

+        }
+
+        if (cacheMissAmount > 0) {
+            payments.modifyRailPayment(info.cacheMissRailId, 0, cacheMissAmount);


Setting these rates to zero here is negated by updatePaymentRates. Should we also set the payment rate to zero in there?

@pyropy PTAL

There was already a fix PR before I noticed this.

FilOzzy added this to FS Sep 25, 2025

github-project-automation bot moved this to 📌 Triage in FS Sep 25, 2025

pyropy changed the title ~~Modify payment rails and add methods for usage-based payments~~ WIP: Modify payment rails and add methods for usage-based payments Sep 25, 2025

pyropy added 6 commits September 26, 2025 11:38

Merge branch 'main' of github.com:FilOzone/filecoin-services into fea…

8b8acd8

…t/usage-based-payments

Merge branch 'main' of github.com:FilOzone/filecoin-services into fea…

874f75d

…t/usage-based-payments

Update ABI

f420cd2

Check cdn lockup numeric values instead of stings

89dd069

pyropy mentioned this pull request Sep 30, 2025

feat: implement FilBeam (operator) contract filbeam/contracts#1

Merged

pyropy added 9 commits September 30, 2025 16:39

Remove CDN lockup metadata keys and set default lockup to 0

39a3d02

Merge branch 'main' of github.com:FilOzone/filecoin-services into fea…

854ea19

…t/usage-based-payments

Remove foundry.lock

3d0d0e8

Don't track package-lock.json

138bd28

refactor: replace _getCDNMetadataKV with _getSingleMetadataKV

2d47ba1

- Remove specialized _getCDNMetadataKV helper function - Replace all calls with the more general _getSingleMetadataKV("withCDN", value) - Simplifies codebase by using existing generic metadata helper

Rollback tests related to data set metadata

1261123

Cleanup tests

e6c9446

Rename test back from testCreateDataSetCreatesRailAndChargesFee to te…

2b3029c

…stCreateDataSetCreatesRail

chore: Emit CDNPaymentRailsToppedUp when CDN payment rail is topped up

1268de7

- Remove redundant tests - Add CDNPaymentRailsToppedUp event and modify top-up tests

pyropy changed the title ~~WIP: Modify payment rails and add methods for usage-based payments~~ Modify payment rails and add methods for usage-based payments Oct 1, 2025

pyropy marked this pull request as ready for review October 1, 2025 10:30

pyropy requested review from ZenGround0, bajtos and juliangruber and removed request for juliangruber October 1, 2025 10:30

pyropy self-assigned this Oct 1, 2025

pyropy requested review from jennijuju and rvagg October 1, 2025 10:31

pyropy and others added 4 commits October 6, 2025 12:45

Update service_contracts/src/FilecoinWarmStorageService.sol

962dfcc

Co-authored-by: Julian Gruber <[email protected]>

Update service_contracts/src/FilecoinWarmStorageService.sol

f832caa

Co-authored-by: Julian Gruber <[email protected]>

Merge branch 'main' of github.com:FilOzone/filecoin-services into fea…

dc783b0

…t/usage-based-payments

fix: failing test

a49b223

Kubuxu approved these changes Oct 6, 2025

View reviewed changes

pyropy requested a review from juliangruber October 6, 2025 13:55

bajtos reviewed Oct 6, 2025

View reviewed changes

bajtos approved these changes Oct 6, 2025

View reviewed changes

pyropy added 2 commits October 6, 2025 16:17

chore: Rename settleCNDPaymentRails to settleFilBeamPaymentRails

0968f4e

chore: Rename tests from testSettleCNDPaymentRails_* to testSettleFil…

2d596c6

…BeamPaymentRails_*

juliangruber approved these changes Oct 6, 2025

View reviewed changes

github-project-automation bot moved this from ⌨️ In Progress to ✔️ Approved by reviewer in FS Oct 6, 2025

bajtos approved these changes Oct 6, 2025

View reviewed changes

pyropy merged commit 8cece67 into main Oct 6, 2025
5 checks passed

pyropy deleted the feat/usage-based-payments branch October 6, 2025 15:19

github-project-automation bot moved this from ✔️ Approved by reviewer to 🎉 Done in FS Oct 6, 2025

rjan90 mentioned this pull request Oct 6, 2025

chore: prep v0.2.0 changelog #262

Merged

wjmelements reviewed Oct 7, 2025

View reviewed changes

service_contracts/src/FilecoinWarmStorageService.sol Show resolved Hide resolved

wjmelements reviewed Oct 7, 2025

View reviewed changes

service_contracts/src/FilecoinWarmStorageService.sol Show resolved Hide resolved

DarkLord017 pushed a commit to DarkLord017/filecoin-services that referenced this pull request Oct 8, 2025

Modify CDN payment rails and add methods for usage-based payments (Fi…

c1ecef0

…lOzone#237)

wjmelements reviewed Oct 10, 2025

View reviewed changes

This was referenced Oct 10, 2025

perf: Do not need to set railToDataSet for cdn rails #277

Closed

perf: rm railToDataSet mapping for cdn rails #278

Merged

pyropy mentioned this pull request Oct 13, 2025

refactor: CDNPaymentRailsToppedUp event #284

Merged

wjmelements reviewed Oct 23, 2025

View reviewed changes

wjmelements mentioned this pull request Oct 23, 2025

feat(pricing): make pricing constants mutable with owner-controlled u… #325

Merged


		event ViewContractSet(address indexed viewContract);

		event CDNPaymentRailsToppedUp(uint256 indexed dataSetId, uint256 totalCdnLockup, uint256 totalCacheMissLockup);

Modify CDN payment rails and add methods for usage-based payments #237

Modify CDN payment rails and add methods for usage-based payments #237

Uh oh!

Conversation

pyropy commented Sep 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Motivation

Description

Changelog

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bajtos left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

pyropy commented Sep 25, 2025 •

edited

Loading