docs: update pricing for per-operation fees (#820)

* chore(docs): update latest pricing changes

* docs: update pricing docs for per-op model and fix MDX tables

Aligns three docs files with the per-op pricing model landed in
synapse-sdk#823 (synapse-sdk 1.0.1 / synapse-core 0.7.0):

- payments-and-storage.mdx: replace floor/sybil pricing with recurring
  rates ($2.50/TiB/mo, $0.024/dataset/mo proving) and per-op fees table;
  update dataset creation cost table; fix CDN unit to $14/TiB
- storage-costs.mdx: fix CDN unit, remove stale SDK-update caution,
  update getUploadCosts() examples to surface fees and lockups fields
- about.mdx: add proving-fee conditionality clause, fix CDN unit,
  mention lockup reserve in per-op fees sentence
- astro.config.mjs: add gfm: true to fix MDX table rendering (Astro 6
  deprecated but still respects the option via @astrojs/mdx)

* docs: say empty data sets have no recurring cost

"Free"/"costs nothing" overstated it: an empty data set still pays the
one-time creation fee. Reword the storage rows and proving text on the
storage-costs, payments-and-storage, and about pages.

* docs: drop earlier-pricing comparisons

State current pricing only. The old $0.06/month floor comparison adds
noise here; release history belongs in a changelog.

* docs: note CDN must be enabled at data set creation

CDN cannot currently be added to an existing data set; the previous
wording implied it could be enabled later. Link FilOzone/filecoin-services#529
so readers can follow or weigh in on changing this.

* docs: clarify CDN lockups are refunded only if unused

The egress and cache-miss lockups are returned on finalization only to
the extent they were not spent.

* docs: normalize spelling to US English

finalised/finalisation -> finalized/finalization, matching the rest of
the repo and this file's existing usage.

Author: nijoe1

docs/astro.config.mjs

@@ -30,6 +30,7 @@ export default defineConfig({
         },
       ],
     ],
+    gfm: true,
   },
   integrations: [
     mermaid({

docs/src/content/docs/cookbooks/payments-and-storage.mdx

@@ -8,8 +8,8 @@ sidebar:
 :::tip[What You'll Learn]
 
 - The mental model: deposit USDFC, FWSS handles payments to storage providers
-- How much storage costs (pricing, floors, CDN)
-- What payment rails are and why each dataset has up to three
+- How much storage costs (pricing, fees, CDN)
+- What payment rails are and why each data set has up to three
 - What happens if your account runs low on funds
 
 :::
@@ -41,47 +41,59 @@ This cookbook explains the underlying payment model. For practical code:
 
 ## Pricing
 
+Two recurring rates apply per data set:
+
 | Component | Cost | Notes |
 | -------------- | -------------------- | ------------------------------------------------------- |
-| **Storage** | $2.50/TiB/month | Minimum $0.06/month per dataset (~24.567 GiB threshold) |
-| **Sybil fee** | 0.1 USDFC (one-time) | Per new dataset creation; prevents state-growth spam |
-| **CDN egress** | $14/TiB downloaded | 1 USDFC top-up ≈ 71.5 GiB of downloads |
-| **CDN setup** | 1 USDFC (one-time) | Per dataset; reusing existing datasets incurs no cost |
+| **Storage** | $2.50/TiB/month per copy | Charged only while pieces exist. Empty data sets have no recurring cost |
+| **Proving Service** | $0.024/data set/month | Flat per-data-set fee, added on top of the storage rate |
+| **CDN egress** | up to $14/TiB (≈ $0.014/GiB) downloaded | Optional, via Filecoin Beam. About half this when served from cache |
 
 :::note
 "Month" always means exactly **30 days = 86,400 epochs** throughout the system. Filecoin epochs are ~30 seconds each.
 :::
 
-### Floor Pricing
+Each on-chain operation also pays a small one-time fee to the storage provider, covering the gas it spends on your behalf:
+
+| Operation | Fee |
+| -------------- | -------------------- |
+| **Create data set** | $0.025 |
+| **Add pieces** | $0.0005 + $0.0003 per piece |
+| **Schedule piece removals** | $0.002 per call |
+| **Terminate service** | $0.00112 (user-initiated only) |
+
+These are fractions of a cent. They are drawn from a ~$0.10 lockup reserve held while the data set is active, not billed separately on each call. See [Storage Costs: How the fees and lockup work](/developer-guides/storage/storage-costs/#how-the-fees-and-lockup-work) for the mechanics.
+
+### Proving Fee
 
-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.
+The monthly cost of an active data set is `(bytes / TiB) × $2.50 + $0.024`. There is no minimum floor: a data set with no pieces has no recurring cost, and the rate activates when the first piece is added. The proving fee is a flat addition per data set, on top of the per-size storage rate.
 
-### Dataset Creation Costs
+### Data Set Creation Costs
 
-Creating a new dataset requires minimum available funds to cover the initial lockup plus the sybil fee:
+Creating a data set locks a small lifecycle reserve. The storage rate starts at zero and is set automatically when you add data:
 
 | Scenario | Minimum Funds Required |
 | -------- | ---------------------- |
-| No CDN | 0.16 USDFC (0.06 floor lockup + 0.10 sybil fee) |
-| With CDN | 1.16 USDFC (0.06 floor + 0.10 sybil + 0.70 CDN + 0.30 cache miss) |
+| No CDN | ~0.10 USDFC (lifecycle reserve lockup) |
+| With CDN | ~1.10 USDFC (0.10 reserve + 0.70 CDN egress + 0.30 cache-miss) |
 
-The storage rate starts at zero when a dataset is created and is set automatically when you add data.
+One-time fees such as the $0.025 creation fee are drawn from the lifecycle reserve, not added on top of these amounts.
 
 ## 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:
+For each data set, FWSS creates payment channels called **rails** that stream funds from your account to the storage provider. A data set can have up to three rails:
 
 | Rail | Type | Purpose |
 | -------------- | --------- | ---------------------------------------- |
 | **PDP rail** | Streaming | Pays for storage at a rate per epoch |
 | **CDN rail** | Fixed | 0.7 USDFC lockup for CDN egress credits |
 | **Cache miss** | Fixed | 0.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.
+Every data set gets a PDP rail, which also holds the ~$0.10 lifecycle reserve that one-time fees draw from. CDN and cache miss rails are added only when CDN is enabled, which must happen at data set creation. CDN cannot currently be added to an existing data set. Follow [FilOzone/filecoin-services#529](https://github.com/FilOzone/filecoin-services/issues/529) to share your use case or track changes.
 
 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()`.
+When you add data to an existing data set, FWSS automatically adjusts the rail's payment rate. The SDK calculates the correct deposit amount for you via `getUploadCosts()` and `prepare()`.
 
 ## Operator Approval
 

docs/src/content/docs/developer-guides/storage/storage-costs.mdx

@@ -19,22 +19,38 @@ An **epoch** is Filecoin's block time, which is 30 seconds. Storage costs are ca
 
 ## Pricing Components
 
+Pricing has two recurring rates and a set of small one-time fees.
+
+### Recurring rates
+
 | Component | Cost | Notes |
 | -------------- | ------------------ | -------------------------------------------------------- |
-| **Storage** | $2.50/TiB/month | Minimum $0.06/month per data set (~24.567 GiB threshold) |
-| **Sybil Fee** | 0.1 USDFC (one-time) | Per new data set creation; prevents state-growth spam |
-| **CDN Egress** | $14/TiB downloaded | 1 USDFC top-up ≈ 71.5 GiB of downloads |
-| **CDN Setup** | 1 USDFC (one-time) | Per data set; reusing existing data sets incurs no cost |
+| **Storage** | $2.50/TiB/month per copy | Charged only while pieces exist. Empty data sets have no recurring cost. |
+| **Proving Service** | $0.024/data set/month | Flat per-data-set fee, added on top of the storage rate. |
+| **CDN egress** | up to $14/TiB (≈ $0.014/GiB) downloaded | Optional, via Filecoin Beam. About half this when served from cache. |
 
 :::note[Be aware]
-Per month means **per 30 days** here, not calendar month like a traditional storage service.
+"Month" means **30 days** here (86,400 epochs), not a calendar month.
 :::
-**Pricing Logic:**
 
-- Storage **< 24.567 GiB**: Minimum $0.06/month applies
-- Storage **≥ 24.567 GiB**: Actual cost `(bytes / TiB) × $2.50/month`
-- CDN data sets require 1 USDFC setup on first creation only
-- CDN egress credits can be topped up anytime
+The monthly rate for an active data set is `(bytes / TiB) × $2.50 + $0.024`. There is no minimum floor: a data set with no pieces has no recurring cost, and the rate activates when the first piece is added.
+
+### One-time fees
+
+Each on-chain operation pays a small fee to the storage provider, covering the gas that provider spends on your behalf:
+
+| Operation | Fee |
+| -------------- | ------------------ |
+| **Create data set** | $0.025 |
+| **Add pieces** | $0.0005 + $0.0003 per piece |
+| **Schedule piece removals** | $0.002 per call |
+| **Terminate service** | $0.00112 (user-initiated only) |
+
+These are fractions of a cent. Think of them like gas: negligible for normal use, only adding up at very high operation volumes. They are paid from a small lockup reserve (~$0.10) held while the data set is active, not billed separately on every call. See [How the fees and lockup work](#how-the-fees-and-lockup-work) below.
+
+:::note[CDN setup]
+Enabling CDN adds two refundable lockups on first use: ~0.7 USDFC for egress credits and ~0.3 USDFC for cache-miss credits. Reusing an existing CDN data set incurs no new setup. These are lockups, not fees, and are returned when the rail is finalized if unused.
+:::
 
 ### Real-World Cost Examples
 
@@ -44,17 +60,25 @@ These examples use plain arithmetic for clarity. For programmatic cost calculati
 
 ```ts twoslash
 // @lib: esnext,dom
-// 48.82 MiB less than 24.567 GiB threshold
-// Price is $0.06/month
-const PRICE_PER_MONTH = 0.06;
-const months = 24;
-const PRICE_FOR_24_MONTHS = PRICE_PER_MONTH * 24; // 1.44 USDFC
+// 48.82 MiB is tiny, so the storage rate is negligible.
+// The recurring cost is dominated by the flat proving fee.
+const STORAGE_PRICE_PER_TIB_PER_MONTH = 2.5;
+const PROVING_FEE_PER_MONTH = 0.024;
+
+const storageTiB = 48.82 / 1024 / 1024; // ≈ 0.0000466 TiB
+const storageCostPerMonth = storageTiB * STORAGE_PRICE_PER_TIB_PER_MONTH; // ≈ $0.00012
+
+// Per copy, per month
+const costPerMonth = storageCostPerMonth + PROVING_FEE_PER_MONTH; // ≈ 0.0241 USDFC
+const costFor24Months = costPerMonth * 24; // ≈ 0.578 USDFC
 ```
 
-| Duration  | Total Cost |
+| Duration | Per copy |
 | --------- | ---------- |
-| 1 month   | 0.06 USDFC |
-| 24 months | 1.44 USDFC |
+| 1 month | ≈ 0.024 USDFC |
+| 24 months | ≈ 0.58 USDFC |
+
+The default 2-copy configuration roughly doubles the recurring cost. One-time fees apply once: $0.025 to create the data set plus the per-batch add-pieces fee.
 
 ---
 
@@ -66,7 +90,8 @@ const PRICE_FOR_24_MONTHS = PRICE_PER_MONTH * 24; // 1.44 USDFC
 ```ts twoslash
 // @lib: esnext,dom
 const STORAGE_PRICE_PER_TIB_PER_MONTH = 2.5; // $2.50/TiB/month
-const CDN_EGRESS_PRICE_PER_TIB = 14; // $14/TiB downloaded
+const PROVING_FEE_PER_MONTH = 0.024; // flat per-data-set
+const CDN_EGRESS_PRICE_PER_TIB = 14; // up to $14/TiB on a cache miss
 const storageMiB = 100_000;
 const egressMiB = 100_000;
 
@@ -79,27 +104,51 @@ const egressTiB = egressMiB / 1024 / 1024;
 // Storage cost per month: 0.0953 TiB × $2.50 ≈ $0.238/month
 const storageCostPerMonth = storageTiB * STORAGE_PRICE_PER_TIB_PER_MONTH;
 
-// Egress cost per month: 0.0953 TiB × $14 ≈ $1.334/month
+// Egress cost per month (worst case, all cache misses): 0.0953 TiB × $14 ≈ $1.334/month
 const egressCostPerMonth = egressTiB * CDN_EGRESS_PRICE_PER_TIB;
 
-// Total cost per month: $0.238/month + $1.334/month ≈ $1.572/month
-const totalCostPerMonth = storageCostPerMonth + egressCostPerMonth;
+// Total cost per month: $0.238 + $0.024 proving + $1.334 egress ≈ $1.596/month
+const totalCostPerMonth = storageCostPerMonth + PROVING_FEE_PER_MONTH + egressCostPerMonth;
 
-// Total cost for 24 months: $1.572/month × 24 ≈ $37.728
+// Total cost for 24 months: $1.596/month × 24 ≈ $38.31
 const totalCostFor24Months = totalCostPerMonth * 24;
 ```
 
 | Cost Component | Per Month | 24 Months |
 | -------------- | ---------------- | ----------------- |
 | Storage | ≈ 0.238 USDFC | ≈ 5.71 USDFC |
+| Proving Service | ≈ 0.024 USDFC | ≈ 0.576 USDFC |
 | CDN Egress | ≈ 1.334 USDFC | ≈ 32.016 USDFC |
-| **Total** | **≈ 1.572 USDFC** | **≈ 37.728 USDFC** |
+| **Total** | **≈ 1.596 USDFC** | **≈ 38.31 USDFC** |
+
+Egress here is the worst case where every byte is a cache miss. When content is served from the Filecoin Beam cache, egress is roughly half this.
+
+## How the fees and lockup work
+
+Most developers can stop at the tables above. This section explains the mechanics behind the per-operation fees and the lockup reserve for anyone who needs the detail.
+
+**The proving fee is additive, not a floor.** The rate is `(bytes / TiB) × $2.50 + $0.024`, so storage scales with size and the proving fee is a flat addition per data set. A data set with no pieces has no recurring charge until the first piece is added.
+
+**Add-pieces pricing scales with batch size.** Each `addPieces` call costs `$0.0005 + $0.0003 × N`, where `N` is the number of pieces in the batch. The base fee is shared across the batch, so adding many pieces in one call is cheaper per piece than adding them one at a time. When estimating the cost of a single piece, assume the single-piece price (`$0.0008`); batching only makes it cheaper.
+
+**Fees are paid from a small lockup reserve, not billed per call.** When a data set is created, ~$0.10 of USDFC is locked as a lifecycle reserve on the data set's payment rail. One-time fees are drawn from this reserve as operations happen, and the reserve is topped back up toward its target as it is drawn down. You see ~$0.10 of additional locked USDFC while the data set is active. It is refunded when the rail is finalized.
+
+<details>
+<summary>Why the reserve exists: wind-down after termination</summary>
+
+Filecoin Pay does not allow raising a rail's fixed lockup once the rail has been terminated. The lifecycle reserve gives you headroom to run wind-down operations (such as scheduling piece removals) after termination, when the reserve can no longer be refilled.
+
+If you expect to need more wind-down operations than the reserve covers, fund the reserve before terminating. User-initiated termination charges the $0.00112 termination fee and makes a best-effort top-up of the reserve. Provider-initiated termination charges no fee and does not top up, so those data sets are limited to whatever was in the reserve at termination.
+
+For the full lockup model (streaming versus fixed lockup, rail settlement, finalization), see the [Payments & Storage cookbook](/cookbooks/payments-and-storage/) and the [Filecoin Pay spec](https://github.com/FilOzone/filecoin-pay/blob/main/SPEC.md).
+
+</details>
 
 ## Querying Upload Costs
 
-Use `getUploadCosts()` to preview costs without executing any transaction. This is useful for displaying pricing in a UI or letting users confirm before proceeding.
+Use `getUploadCosts()` to preview costs without executing any transaction. This is useful for displaying pricing in a UI or letting users confirm before proceeding. The result reads the on-chain price list, so it reflects the rates, one-time fees, and lockups described above.
 
-Getting the costs for uploading to an existing dataset:
+Getting the costs for uploading to an existing data set:
 
 ```ts twoslash
 // @lib: esnext,dom
@@ -108,23 +157,23 @@ import { Synapse, SIZE_CONSTANTS } from "@filoz/synapse-sdk"
 import { privateKeyToAccount } from 'viem/accounts'
 const synapse = Synapse.create({ account: privateKeyToAccount('0x...'), source: 'my-app' })
 // ---cut---
-// With currentDataSetSize — accurate floor-aware delta
-const { rates, depositNeeded } = await synapse.storage.getUploadCosts({
+// Pass currentDataSetSize so rates reflect the data set's new total size
+const { rates, fees, depositNeeded } = await synapse.storage.getUploadCosts({
   isNewDataSet: false,
   currentDataSetSize: 50n * SIZE_CONSTANTS.MiB,
   dataSize: 100n * SIZE_CONSTANTS.MiB,
 })
-// Shows incremental cost (newRate - currentRate), handles floor-to-floor
+// fees.addPiecesFee is the one-time fee for this upload
+// (pass pieceCount when adding more than one piece)
 
-// Without currentDataSetSize — safe overestimate for floor cases
+// Without currentDataSetSize, rates cover the new data alone
 const costs2 = await synapse.storage.getUploadCosts({
   isNewDataSet: false,
   dataSize: 100n * SIZE_CONSTANTS.MiB,
 })
-// Accurate for above-floor datasets, overestimates for floor-priced ones
 ```
 
-Getting the costs for uploading to a new dataset:
+Getting the costs for uploading to a new data set:
 
 ```ts twoslash
 // @lib: esnext,dom
@@ -133,7 +182,7 @@ import { Synapse, formatUnits, SIZE_CONSTANTS } from "@filoz/synapse-sdk"
 import { privateKeyToAccount } from 'viem/accounts'
 const synapse = Synapse.create({ account: privateKeyToAccount('0x...'), source: 'my-app' })
 // ---cut---
-const { rates, depositNeeded, needsFwssMaxApproval, ready } = await synapse.storage.getUploadCosts({
+const { rates, fees, lockups, depositNeeded, needsFwssMaxApproval, ready } = await synapse.storage.getUploadCosts({
   dataSize: 100n * SIZE_CONSTANTS.MiB,
   isNewDataSet: true,
   withCDN: true,
@@ -143,6 +192,10 @@ const { rates, depositNeeded, needsFwssMaxApproval, ready } = await synapse.stor
 console.log("Rate per epoch:", formatUnits(rates.perEpoch), "USDFC")
 // Storage rate per month
 console.log("Rate per month:", formatUnits(rates.perMonth), "USDFC")
+// One-time fees (create data set + add pieces)
+console.log("One-time fees:", formatUnits(fees.total), "USDFC")
+// Locked while the data set is active (lifecycle reserve, streaming, CDN)
+console.log("Total lockup:", formatUnits(lockups.total), "USDFC")
 // USDFC to deposit
 console.log("Deposit needed:", formatUnits(depositNeeded), "USDFC")
 // Whether FWSS needs to be approved

docs/src/content/docs/introduction/about.mdx

@@ -65,8 +65,11 @@ All payments are settled automatically through Filecoin Pay, ensuring on-chain a
 
 | **Service** | **Pricing** | **Description** |
 | ------- | --------- | -------------------- |
-| **Base Storage & Retrival** | **$2.5/TiB/month/copy** (minimum 2 copies) | Redundant storage ensures durability and continuous PDP verification.<br />Minimum monthly charge of **0.06 USDFC**, covering roughly **24 GiB** of total data (two copies). |
-| **Add-on Retrieval (Filecoin Beam)** | **Up to $0.014/GiB egress** | Charged for outbound data delivered via Filecoin Beam gateways or retrieval providers. |
+| **Storage** | **$2.50/TiB/month/copy** (minimum 2 copies) | Redundant storage with continuous PDP verification. Empty data sets have no recurring cost; charges begin when the first piece is added. |
+| **Proving Service** | **$0.024/data set/month** | Flat per-data-set fee for proof verification, added on top of the storage rate. Charged only while the data set holds pieces. |
+| **Add-on Retrieval (Filecoin Beam)** | **Up to $14/TiB (≈ $0.014/GiB) egress** | Outbound data delivered via Filecoin Beam. Roughly half this when served from cache, up to the full rate on a cache miss. |
+
+Beyond these recurring rates, each on-chain operation (creating a data set, adding or removing pieces, terminating service) carries a small one-time fee paid to the storage provider to cover its gas. These fees are fractions of a cent, drawn from a small refundable lockup reserve (~$0.10 USDFC) held while the data set is active, and only matter at very high operation volumes. See [Storage Costs](/developer-guides/storage/storage-costs/) for the full breakdown.
 
 :::note[Verifiable Payment]
 All storage and retrieval charges are denominated in **USDFC** (or supported ERC-20 tokens) and settled via **Filecoin Pay**. Every transaction is on-chain, auditable, and linked to verifiable service proofs.