Skip to content
foc Filecoin Onchain Cloud Documentation

Payments & Storage

How It Works

Section titled “How It Works”

Storage on Filecoin Onchain Cloud uses two connected on-chain systems:

  • Filecoin Pay: a generic payment protocol for streaming and one-time payments
  • Filecoin Warm Storage Service (FWSS): a storage service that builds on Filecoin Pay

Think of your Filecoin Pay account as a checking account with a running tab. You deposit USDFC, and FWSS continuously streams payments from it to storage providers on your behalf. The developer flow is:

  1. Deposit USDFC into your Filecoin Pay account
  2. Approve FWSS as your operator (one-time)
  3. Upload data through the SDK
  4. FWSS handles the rest: creating payment channels, streaming funds to storage providers

The SDK’s prepare() method handles steps 1-2 automatically. See Storage Costs for code examples.

Pricing

Section titled “Pricing”
ComponentCostNotes
Storage$2.50/TiB/monthMinimum $0.06/month per dataset (~24.567 GiB threshold)
Sybil fee0.1 USDFC (one-time)Per new dataset creation; prevents state-growth spam
CDN egress$14/TiB downloaded1 USDFC top-up ≈ 71.5 GiB of downloads
CDN setup1 USDFC (one-time)Per dataset; reusing existing datasets incurs no cost

Floor Pricing

Section titled “Floor Pricing”

Every dataset has a minimum monthly charge of $0.06/month, regardless of size. This compensates storage providers for the overhead of maintaining a dataset. Files under ~24.567 GiB all pay this same floor rate. Above that threshold, the natural rate (bytes/TiB × $2.50/month) takes over.

Dataset Creation Costs

Section titled “Dataset Creation Costs”

Creating a new dataset requires minimum available funds to cover the initial lockup plus the sybil fee:

ScenarioMinimum Funds Required
No CDN0.16 USDFC (0.06 floor lockup + 0.10 sybil fee)
With CDN1.16 USDFC (0.06 floor + 0.10 sybil + 0.70 CDN + 0.30 cache miss)

The storage rate starts at zero when a dataset is created and is set automatically when you add data.

Payment Rails

Section titled “Payment Rails”

For each dataset, FWSS creates payment channels called rails that stream funds from your account to the storage provider. A dataset can have up to three rails:

RailTypePurpose
PDP railStreamingPays for storage at a rate per epoch
CDN railFixed0.7 USDFC lockup for CDN egress credits
Cache missFixed0.3 USDFC lockup for cache miss credits

Every dataset gets a PDP rail. CDN and cache miss rails are added only when CDN is enabled.

FWSS enforces a 30-day lockup period: your account must always have enough funds to cover at least 30 days of storage at the current rate. Think of it as a security deposit. The funds aren’t spent upfront, but they’re reserved so providers are guaranteed payment even if you stop topping up.

When you add data to an existing dataset, FWSS automatically adjusts the rail’s payment rate. The SDK calculates the correct deposit amount for you via getUploadCosts() and prepare().

Operator Approval

Section titled “Operator Approval”

Before FWSS can manage payment rails on your behalf, you need to approve it as an operator on your Filecoin Pay account. Think of this like approving a token allowance: you’re authorizing FWSS to create and modify payment channels using your deposited funds.

The SDK handles this automatically: the first time you call prepare(), the returned transaction includes the approval alongside any needed deposit. After that, only deposits are needed.

If you’re building custom integrations outside the SDK, FWSS approval uses the Filecoin Pay operator system with three allowance dimensions (rate, lockup amount, and lockup period). See the Filecoin Pay spec for details.

Running Low on Funds

Section titled “Running Low on Funds”

Your account has a funded-until epoch: the point in time when your balance runs out at the current rate. You can check this via the SDK’s account queries (see Storage Costs: Account Queries).

When your balance runs out, the account becomes underfunded. This has real consequences:

  • Uploads fail: new storage operations require the account to be current on payments, and an underfunded account can’t settle to the current epoch
  • Existing data is at risk: after the 30-day lockup grace period, providers may remove your data
  • Deposits must cover the shortfall first: when you deposit into an underfunded account, part of the deposit goes toward settling outstanding obligations before it can fund new storage

The SDK handles this automatically: getUploadCosts() and prepare() account for any outstanding debt when calculating the deposit amount. If your account is underfunded, the deposit will include the shortfall so your upload can proceed.

To avoid interruptions, keep your account funded well beyond the 30-day lockup window. You can request extra runway when preparing uploads via the extraRunwayEpochs parameter.

Advanced Details

Section titled “Advanced Details”

Rate Precision

Section titled “Rate Precision”

Storage prices are stored per-month on-chain but rails operate per-epoch. Integer division during conversion means perEpoch × EPOCHS_PER_MONTH is slightly less than the true monthly rate due to truncation. The SDK returns both values: use rate.perMonth for display and rate.perEpoch for on-chain math.

Deposit Components

Section titled “Deposit Components”

The deposit amount for an upload is built from four parts:

ComponentWhat it covers
Additional lockupRate increase × 30-day lockup period, plus any CDN lockup
RunwayExtra funded time beyond the lockup (if requested)
DebtOutstanding obligations on underfunded accounts
BufferSafety margin for time between balance check and transaction execution

The buffer accounts for the fact that funds drain between when you check your balance and when the transaction lands on-chain. The SDK adds a small buffer (default: 5 epochs ≈ 2.5 minutes) to prevent reverts. New users with no existing storage skip the buffer since nothing is draining yet.

Further Reading

Section titled “Further Reading”

Next Steps

Section titled “Next Steps”