diff --git a/docs/src/content/docs/cookbooks/payments-and-storage.mdx b/docs/src/content/docs/cookbooks/payments-and-storage.mdx index 16a027825..4b049788a 100644 --- a/docs/src/content/docs/cookbooks/payments-and-storage.mdx +++ b/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,35 +41,51 @@ 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 are free | +| **Proving Service** | $0.024/data set/month | Flat per-data-set fee, added on top of the storage rate | +| **CDN egress** | up to $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. + +:::caution[SDK pricing update in progress] +The per-operation fees and the additive proving fee are live in the Warm Storage contract, but the SDK cost APIs (`getUploadCosts()`, `prepare()`) are still being updated to surface them, tracked in [synapse-sdk#763](https://github.com/FilOzone/synapse-sdk/issues/763). Until that lands, returned `rate` and `depositNeeded` values reflect the previous model. +::: + +### 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 costs nothing, and the rate activates when the first piece is added. Earlier pricing used a single $0.06/month minimum. The flat proving fee replaces it as an additive per-data-set charge. -### 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 | | -------------- | --------- | ---------------------------------------- | @@ -77,11 +93,11 @@ For each dataset, FWSS creates payment channels called **rails** that stream fun | **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. 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 diff --git a/docs/src/content/docs/core-concepts/filecoin-pin.mdx b/docs/src/content/docs/core-concepts/filecoin-pin.mdx new file mode 100644 index 000000000..db0b7e0cf --- /dev/null +++ b/docs/src/content/docs/core-concepts/filecoin-pin.mdx @@ -0,0 +1,51 @@ +--- +title: Filecoin Pin +description: Filecoin Pin bridges Filecoin and IPFS, providing guaranteed IPFS pinning powered by the Filecoin Onchain Cloud. +sidebar: + order: 6 +--- + +:::tip[Production-ready on Filecoin Mainnet] +Filecoin Pin is live on Filecoin Mainnet and ready for use. Register for product updates and announcements at [filecoin.cloud](https://filecoin.cloud/). +::: + +## What is Filecoin Pin? + +Filecoin Pin bridges Filecoin and IPFS. It provides the infrastructure for guaranteed IPFS pinning, where your content stays addressable with standard IPFS tooling and Filecoin storage providers back it with daily cryptographic proofs that they still hold it. + +When you pin content with Filecoin Pin, your IPFS data gains: + +- **Verifiable persistence**: storage providers must cryptographically prove daily that they continue to store and serve your data. +- **Economic incentives**: you only pay when storage proofs are successfully delivered and verified on-chain. +- **Decentralized infrastructure**: your data can be stored across a global network of independent storage providers. +- **Sovereign data**: choose your providers, audit storage proofs and payments on-chain, with no dependency on a single company. +- **Native IPFS integration**: continue using standard [IPFS Mainnet](https://docs.ipfs.tech/concepts/glossary/#mainnet) tooling like Kubo, Helia, and IPFS HTTP Gateways while gaining Filecoin's persistence guarantees. + +## How it works + +Filecoin Pin is built on the [Filecoin Onchain Cloud](/core-concepts/architecture/), the programmable storage stack that the Synapse SDK also exposes. Adding a file combines a familiar IPFS workflow with on-chain storage and payments: + +1. Filecoin Pin packs your file into an IPFS CAR and uploads it to a storage provider. +2. The provider indexes the content and announces it to IPNI, so it resolves through standard IPFS gateways. +3. The upload is recorded on-chain as a data set and piece through the [Filecoin Warm Storage Service](/core-concepts/fwss-overview/). +4. The provider proves it still holds your data every day through [Proof of Data Possession](/core-concepts/pdp-overview/), and [Filecoin Pay](/core-concepts/filecoin-pay-overview/) releases payment as those proofs are verified. + +Everything you pin stays interoperable with the rest of the Filecoin Onchain Cloud. You can audit the same data sets, proofs, and payments on-chain, or manage them with the [Filecoin Pin CLI](https://github.com/filecoin-project/filecoin-pin) or the [Synapse SDK](/getting-started/). + +## Who is Filecoin Pin for? + +Filecoin Pin is for anyone who needs reliable, verifiable IPFS pinning: + +- **People moving from another pinning service**: if you are coming from Storacha, Pinata, or any other IPFS pinning service, Filecoin Pin gives you a place to keep your IPFS content pinned and accessible. +- **Developers building on IPFS**: if you are building dApps, websites, AI agents, or other applications that rely on IPFS, Filecoin Pin provides the missing persistence layer with cryptographic guarantees. + +:::note[Migrating existing pins from Storacha?] +This guide focuses on pinning new content. For migrating data already pinned on Storacha, see the dedicated migration guide (coming soon). +::: + +## Next Steps + +- **[Quick Start with Filecoin Pin](/getting-started/filecoin-pin/)**: the fastest path to pinning your first file. Install the CLI, connect your wallet, deposit storage credit, and pin content end to end in around 10 minutes. Start here. +- **[Behind the Scenes of Adding a File](https://github.com/filecoin-project/filecoin-pin/blob/master/documentation/behind-the-scenes-of-adding-a-file.md)**: a deep dive into how Filecoin Pin packs, stores, and proves your data on-chain. +- **[Filecoin Pin repository](https://github.com/filecoin-project/filecoin-pin)**: source code and technical documentation. +- **[Filecoin Slack #fil-foc](https://filecoinproject.slack.com/archives/C07CGTXHHT4)**: join for real-time developer support and updates, or [open an issue](https://github.com/filecoin-project/filecoin-pin/issues) on GitHub. diff --git a/docs/src/content/docs/core-concepts/retrieval.mdx b/docs/src/content/docs/core-concepts/retrieval.mdx new file mode 100644 index 000000000..4ea42c505 --- /dev/null +++ b/docs/src/content/docs/core-concepts/retrieval.mdx @@ -0,0 +1,122 @@ +--- +title: Retrieval +description: How the Filecoin Onchain Cloud serves stored data back to applications, from direct storage provider reads to CDN-accelerated delivery with Filecoin Beam. +sidebar: + order: 5 +--- + +Storing data is only half of a cloud platform. Applications also need to read it back quickly and reliably. The **Filecoin Onchain Cloud (FOC)** is built for a "store and serve" model, where every piece you store stays retrievable over HTTP for the life of its data set. + +This page explains how retrieval works in FOC and the paths available to you. + +## Content Addressing + +Every piece in FOC is identified by a **PieceCID**, a content-addressed identifier derived from the data itself. A PieceCID does not point at a location. It points at the content. + +This has two practical consequences for retrieval: + +- **Location independence.** The same PieceCID can be served by any provider that holds the piece, or by a CDN sitting in front of those providers. Retrieval can route around a slow or offline provider without changing the address. +- **Verifiable downloads.** Because the identifier is derived from the bytes, a client can recompute the PieceCID of whatever it receives and confirm it matches what was requested. The Synapse SDK does this automatically on every download, so tampered or corrupted responses are rejected before they reach your application. + +## Retrieval Paths + +FOC offers three ways to retrieve a piece. They share the same PieceCID and can be mixed within a single application. + +| Path | Source | Latency | When to use | +| ----- | ------- | ------- | ----------- | +| **Direct SP retrieval** | Storage provider HTTP API | Seconds | Default. No extra setup or egress charges. | +| **FilBeam (CDN) retrieval** | Filecoin Beam cache, backed by SPs | Milliseconds | Hot data, frequent reads, latency-sensitive apps. | +| **IPFS retrieval** | IPFS network via Filecoin Pin | Varies | IPFS-native applications and gateways. | + +```mermaid +graph TD + App[Application / Synapse SDK] + + App -->|"withCDN"| FB[Filecoin Beam
CDN cache] + App -->|direct| SP[Storage Providers
Curio HTTP API] + App -->|IPFS| PIN[Filecoin Pin
IPFS gateway] + + FB -->|cache miss| SP + PIN --> SP +``` + +## Direct SP Retrieval + +The default path serves data straight from the storage providers that hold it. Each provider runs a Curio node that exposes an HTTP API, and pieces are fetched directly from that endpoint. + +Because data is content-addressed, retrieval does not require you to know which provider holds a given piece. The SDK resolves a serving URL for you: + +1. It reads your data sets on chain to find which providers store the piece. +2. It probes those providers in parallel and selects one that confirms it has the piece. +3. It downloads from that provider and validates the bytes against the PieceCID. + +This makes downloads **SP-agnostic**. If a piece lives on more than one provider, retrieval succeeds as long as any one of them is reachable. + +Direct retrieval has no egress charges. It is the right default for most workloads, with latency in the range of seconds. + +## FilBeam (CDN) Retrieval + +[**Filecoin Beam**](https://docs.filbeam.com/) is the retrieval and delivery layer of FOC. It is a content delivery network that caches pieces close to where they are requested, cutting retrieval latency from seconds to milliseconds. + +FilBeam serves each piece from a per-account subdomain keyed by PieceCID. On mainnet: + +```text +https://.filbeam.io/ +``` + +On calibration the host is `.calibration.filbeam.io`. The SDK builds this URL for you, so you rarely construct it by hand. + +Retrieval through FilBeam follows one of two paths: + +- **Cache hit.** The piece is already in the FilBeam cache and is served directly. This is the fast path. +- **Cache miss.** The piece is not yet cached. FilBeam retrieves it from a storage provider, serves it to the client, and warms the cache so later reads are hits. + +Both paths are metered. FilBeam tracks egress per data set and bills it based on volume, separately from the base storage cost, with cache misses priced higher than cache hits. See the [FilBeam pricing reference](https://docs.filbeam.com/how-it-works/pricing/) for current rates. + +You can inspect the remaining egress quotas for a data set through the SDK: + +```ts twoslash +// @lib: esnext,dom +import { Synapse } from "@filoz/synapse-sdk" +import { privateKeyToAccount } from "viem/accounts" + +const synapse = await Synapse.create({ account: privateKeyToAccount("0x..."), source: "my-app" }) +// ---cut--- +const stats = await synapse.filbeam.getDataSetStats(12345) +console.log("Remaining CDN egress (cache hits):", stats.cdnEgressQuota) +console.log("Remaining cache-miss egress:", stats.cacheMissEgressQuota) +``` + +For dashboards and other ways to track consumption, see the FilBeam [monitor usage guide](https://docs.filbeam.com/how-to-guides/monitor-usage/). + +FilBeam delivery is opt-in per data set. Storing with the `withCDN` option marks a data set as CDN-enabled, which keeps CDN and non-CDN data sets separate and routes downloads through FilBeam when requested. + +## IPFS Retrieval + +For applications that speak IPFS natively, content stored through [**Filecoin Pin**](/core-concepts/filecoin-pin/) is also served over the IPFS network. Filecoin Pin packs your data into an IPFS CAR, stores it on FOC providers, and announces it to IPNI, so it resolves through standard IPFS gateways by its root CID: + +```text +https://dweb.link/ipfs/ +``` + +This path lets IPFS-native apps treat FOC as a durable, verifiable backing store while keeping the addressing and access patterns their stack already uses. See the [Filecoin Pin quick start](/getting-started/filecoin-pin/) to pin and retrieve your first file. + +## Retrieving with the SDK + +The Synapse SDK exposes all of these paths through a single `download` method. Without `withCDN` it resolves a storage provider that holds the piece and downloads from it; setting `withCDN` adds the FilBeam URL to the sources it races. Either way, the returned bytes are validated against the requested PieceCID before they reach your application. + +For usage, code examples, CDN options, and provider-scoped reads, see [Retrieval in the Storage Operations guide](/developer-guides/storage/storage-operations/#retrieval). + +## Summary + +- Pieces are content-addressed by PieceCID, so retrieval is location-independent and verifiable. +- **Direct SP retrieval** is the default. It is SP-agnostic and has no egress charges. +- **FilBeam** adds a CDN layer for millisecond latency, billed on egress per data set. +- **IPFS retrieval** via Filecoin Pin serves the same content to IPFS-native applications. + +## Next Steps + +- [Storage Operations](/developer-guides/storage/storage-operations/) - Upload and download with the SDK +- [Filecoin Warm Storage Service](/core-concepts/fwss-overview/) - The service layer behind storage and retrieval +- [Filecoin Pin](/core-concepts/filecoin-pin/) - Guaranteed IPFS pinning backed by FOC +- [FilBeam Documentation](https://docs.filbeam.com/) - CDN delivery and egress pricing diff --git a/docs/src/content/docs/developer-guides/storage/storage-costs.mdx b/docs/src/content/docs/developer-guides/storage/storage-costs.mdx index 0b3d427ec..b28a47957 100644 --- a/docs/src/content/docs/developer-guides/storage/storage-costs.mdx +++ b/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 are free. | +| **Proving Service** | $0.024/data set/month | Flat per-data-set fee, added on top of the storage rate. | +| **CDN egress** | up to $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. + +### 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. +::: ### 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,55 @@ 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.30 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.30 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.** Earlier pricing used a single monthly minimum. The rate is now `(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 pays nothing 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. + +
+Why the reserve exists: wind-down after termination + +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 [Filecoin Pay spec](https://github.com/FilOzone/filecoin-pay/blob/main/SPEC.md). The [Payments & Storage cookbook](/cookbooks/payments-and-storage/) covers the same mechanics in SDK terms, though its pricing figures predate this update. + +
## Querying Upload Costs +:::caution[SDK pricing update in progress] +The per-operation fees and the additive proving fee above are live in the Warm Storage contract. The SDK cost APIs (`getUploadCosts()`, `prepare()`) are still being updated to surface them, tracked in [synapse-sdk#763](https://github.com/FilOzone/synapse-sdk/issues/763). Until that lands, the returned `rate` and `depositNeeded` values reflect the previous model and may not include every new fee. +::: + Use `getUploadCosts()` to preview costs without executing any transaction. This is useful for displaying pricing in a UI or letting users confirm before proceeding. -Getting the costs for uploading to an existing dataset: +Getting the costs for uploading to an existing data set: ```ts twoslash // @lib: esnext,dom @@ -124,7 +177,7 @@ const costs2 = await synapse.storage.getUploadCosts({ // 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 diff --git a/docs/src/content/docs/getting-started/filecoin-pin.mdx b/docs/src/content/docs/getting-started/filecoin-pin.mdx new file mode 100644 index 000000000..f41e5fe52 --- /dev/null +++ b/docs/src/content/docs/getting-started/filecoin-pin.mdx @@ -0,0 +1,313 @@ +--- +title: Quick Start with Filecoin Pin +description: Install Filecoin Pin, connect your wallet, deposit storage credit, and pin your first file to Filecoin in around 10 minutes. +sidebar: + order: 1 +--- + +import { Steps } from '@astrojs/starlight/components' + +This guide walks you through pinning your first file to Filecoin using the Filecoin Pin CLI. By the end, you will be set up to: + +- Install the Filecoin Pin CLI +- Connect your Ethereum-style wallet on Filecoin +- Deposit storage credit on Filecoin Pay +- Pin a file to Filecoin and retrieve it using standard IPFS tooling + +## Prerequisites + +Before starting, make sure you have: + +- **An Ethereum-style wallet on Filecoin**: MetaMask is the easiest option. If you do not have one set up, see [MetaMask setup](https://docs.filecoin.io/basics/assets/metamask-setup). +- **FIL in your wallet**: to pay transaction gas fees on Filecoin. +- **USDFC in your wallet**: to pay for storage. USDFC is the stablecoin used by Filecoin Onchain Cloud. The easiest way to get some is to [swap FIL for USDFC on Sushi](https://www.sushi.com/filecoin/swap?token0=NATIVE&token1=0x80b98d3aa09ffff255c3ba4a241111ff1262f045). + +## Install the Filecoin Pin CLI + +Install the CLI globally with npm: + +```sh +npm install -g filecoin-pin +``` + +Verify the installation: + +```sh +filecoin-pin --version +``` + +To see all available commands at any time: + +```sh +filecoin-pin --help +``` + +## Connect Your Wallet + +The Filecoin Pin CLI signs transactions using your wallet's private key. You provide it as an environment variable; the CLI reads it directly and never stores it on disk. + + + +1. **Export your private key from MetaMask** + + :::danger[Treat your private key like a password] + Anyone with your private key has full control of your wallet and any funds in it. Never paste it into a website, share it over chat, commit it to a repository, or store it in plain text on a shared system. + ::: + + In MetaMask: + + 1. Open the MetaMask extension. + 2. Click the three dots next to your account name. + 3. Select **Account details**. + 4. Click **Show private key**. + 5. Enter your MetaMask password. + 6. Copy the private key shown. + + The private key is a 64-character hex string, with or without an `0x` prefix. + +2. **Save the private key to a `.env` file** + + Create a file named `.env` in your working directory containing: + + ```sh + export PRIVATE_KEY="0xYOUR_PRIVATE_KEY_HERE" + ``` + + Then secure it and load it into your shell: + + ```sh + chmod 600 .env + source .env + ``` + + Add `.env` to your `.gitignore` if you are inside a git repository. + + + +## Set Up Payments + +Filecoin Pin uses [Filecoin Pay](https://github.com/FilOzone/filecoin-pay) to manage storage payments. Before you can pin anything, you need to: + +1. Authorize the Warm Storage Service contract to spend USDFC on your behalf. +2. Deposit USDFC into Filecoin Pay so storage providers can be paid. + +The CLI walks you through both steps interactively: + +```sh +filecoin-pin payments setup +``` + +The CLI guides you through the following stages: + + + +1. **Connect and check balances** + + The CLI confirms it can connect to Filecoin Mainnet and reports your wallet's FIL and USDFC balances. + + :::note + If you do not have enough FIL for gas or USDFC for storage, the CLI tells you and stops. Top up your wallet and try again. + ::: + +2. **Review pricing** + + The CLI shows current storage pricing per GiB per month and per TiB per month. Use this to estimate how much USDFC you want to deposit. + +3. **Choose a deposit amount** + + The CLI asks: **"Would you like to deposit USDFC to enable storage?"** Answer **Yes**. + + It then shows example monthly costs for common storage amounts (100 GiB, 1 TiB, 10 TiB) so you can pick a sensible deposit. When prompted **"How much USDFC would you like to deposit?"**, enter the amount you want. A first-time deposit of `10.0` USDFC is a reasonable starting point. + +4. **Confirm the deposit** + + The CLI submits the deposit transaction on-chain and shows the transaction hash and your new storage capacity. + +
+ Example output + + ```text + ✓ Deposit complete + Deposit tx: 0x1234...abcd + + New Storage Capacity: + Total deposit: 10.00 USDFC + Capacity: ~XX GiB for 1 month + ``` + +
+ + + +**Top Up Your Runway (Optional)**: + +Once you have data stored, you can top up your deposit to cover a specific number of days at your current usage: + +```sh +filecoin-pin payments fund --days 30 +``` + +This deposits (or withdraws) the right amount of USDFC to give you exactly 30 days of runway based on what you are currently storing. You can use any number of days you like. + +:::note +`payments fund --days ` computes the target from your current storage rate, so it only works **after** you have pinned something. Before your first upload it reports `No active spend detected` — set an explicit target with `filecoin-pin payments fund --amount ` instead, or just come back to this step after pinning your first file. +::: + +To check your current deposit balance, runway, and payment status at any time: + +```sh +filecoin-pin payments status +``` + +## Pin Your First File + +Now you are ready to pin. Create a test file: + +```sh +echo "Hello Filecoin Pin! This is my first file stored on Filecoin with verifiable proofs of storage and retrievable over IPFS." > demo.txt +``` + +:::note +Pieces have a minimum size of 127 bytes once packed. Very small files (a few bytes) are rejected, so make sure your test file has a little content. +::: + +Pin it to Filecoin: + +```sh +filecoin-pin add demo.txt +``` + +The CLI will: + +1. Pack your file into IPFS-compatible format (a CAR file). +2. Select storage providers automatically. +3. Store your file with two providers for redundancy. +4. Verify the upload was advertised to [IPNI indexers](https://github.com/filecoin-project/filecoin-pin/blob/master/documentation/glossary.md#ipni). + +
+Example output + +```text +Filecoin Pin Add + +✓ File validated (122.0 B) +✓ Connected to Filecoin - Mainnet +✓ File packed with root CID: bafybeihkoviema7g3gxyt6la7vd5ho32ictqbilu3wnlo3rs7ewhnp7lly +✓ [Primary] Stored on provider 2 +✓ [Secondary] Stored on provider 9 +✓ IPNI provider records found. IPFS retrieval possible. + +━━━ Add Complete ━━━ + +Root CID: bafybeihkoviema7g3gxyt6la7vd5ho32ictqbilu3wnlo3rs7ewhnp7lly +Piece CID: bafkzcibcfab4grpgq6e6rva4kfuxfcvibdzx3kn2jdw6q3zqgwt5cou7j6k4wfq +Copies: 2/2 + +Add completed successfully +``` + +
+ +The **Root CID** is your IPFS Content Identifier; it is how you will retrieve your data. Save it somewhere. + +You can also pin a directory by passing the directory path instead of a file: + +```sh +mkdir my-data +echo "File 1" > my-data/file1.txt +echo "File 2" > my-data/file2.txt +filecoin-pin add my-data/ +``` + +## Retrieve Your File + +Your file is now retrievable via standard IPFS tooling using its Root CID. + +For example, via a subdomain gateway: + +```text +https://.ipfs.inbrowser.link +``` + +Or via the dweb.link gateway: + +```text +https://dweb.link/ipfs/ +``` + +Try opening one of those URLs in your browser; your file should load. You can also retrieve it programmatically using any IPFS-compatible client (Kubo, Helia, Lassie, etc.) by referencing the Root CID. + +## Inspect Your Storage Proofs + +Filecoin storage providers must cryptographically prove daily that they continue to store your data. You can inspect those proofs and the on-chain payment rails at any time. + +List the data sets associated with your wallet: + +```sh +filecoin-pin data-set ls +``` + +Then get the full on-chain detail for a specific data set: + +```sh +filecoin-pin data-set show +``` + +This queries the smart contracts directly, so the values are live blockchain state. + +
+Example output + +```text +Filecoin Onchain Cloud Data Set Details for #14081 + +#14081 + Status: live + CDN add-on: enabled + + Provider + ID: 4 + Name: + Service URL: https:// + + Metadata + source: "filecoin-pin" + withCDN: "" + withIPFSIndexing: "" + + Payment + PDP rail ID: 17487 + FilBeam rail ID: 17490 + FilBeam cache-miss rail ID: 17489 + Payer: 0xYOUR_WALLET_ADDRESS + Payee: 0xPROVIDER_ADDRESS + + Pieces + Total pieces: 1 + Total size: 219.0 B + + #0 (active) + PieceCID: bafkzcib... + Metadata + ipfsRootCID: "bafkrei..." + name: "demo.txt" +``` + +
+ +Key things to look for: + +- **Status `live`**: your data set is active and being proved. +- **CDN add-on**: whether the FilBeam CDN retrieval add-on is enabled for this data set. +- **PDP rail ID**: your active storage-proof payment rail. +- **Provider Service URL**: direct retrieval endpoint for your pieces. +- **PieceCID / ipfsRootCID** per piece: the PieceCID is what the provider proves; the ipfsRootCID (your Root CID) is what you use to retrieve. + +You have successfully pinned your first file to Filecoin. + +## Next Steps + +- Run `filecoin-pin --help` to explore advanced usage, including auto-funding and custom provider selection. +- Want to understand what is happening behind the scenes? Read [Behind the Scenes of Adding a File](https://github.com/filecoin-project/filecoin-pin/blob/master/documentation/behind-the-scenes-of-adding-a-file.md) for a deep dive into each step. +- Join the community in Filecoin Slack [#fil-foc](https://filecoinproject.slack.com/archives/C07CGTXHHT4) for help, discussion, and updates. +- Found a bug or have a feature request? [Open an issue](https://github.com/filecoin-project/filecoin-pin/issues) on GitHub. diff --git a/docs/src/content/docs/introduction/about.mdx b/docs/src/content/docs/introduction/about.mdx index 4eeb375dc..b57a35c3b 100644 --- a/docs/src/content/docs/introduction/about.mdx +++ b/docs/src/content/docs/introduction/about.mdx @@ -26,7 +26,7 @@ FOC addresses this next-generation demand by creating composable onchain service ### Key Properties -At its core, Filecoin Onchain Cloud delivers cloud-grade performance and usability with verifiable onchain properties: +Filecoin Onchain Cloud combines cloud-grade performance with verifiable onchain properties: - 🔑 **Ownership** — Data, payments, and service logic belong to users and developers, not intermediaries. - 🔍 **Verifiability** — Every transaction, proof, and interaction is recorded, auditable, and cryptographically verifiable on the Filecoin blockchain. @@ -36,38 +36,40 @@ This design allows Filecoin to move beyond static data storage — offering real ### Core Components -The Filecoin Onchain Cloud offers foundational components that together create an onchain verifiable, service-oriented cloud stack. Today, the building blocks includes: +The Filecoin Onchain Cloud's components together form an onchain-verifiable, service-oriented cloud stack. Today, the building blocks include: -- [**Filecoin Warm Storage Service (FWSS)**](https://github.com/FilOzone/filecoin-services) — The operational layer providing fast, persistent, and verifiable data storage backed by Proof of Data Possession, powered by Filecoin's world storage providers. +- [**Filecoin Warm Storage Service (FWSS)**](https://github.com/FilOzone/filecoin-services) — The operational layer providing fast, persistent, and verifiable data storage backed by Proof of Data Possession, across Filecoin's global storage providers. - [**Proof of Data Possession (PDP)**](https://github.com/FilOzone/pdp) — The cryptographic storage proof ensuring data storage integrity and availability. - [**Filecoin Pay**](https://github.com/FilOzone/filecoin-pay) — The financial settlement engine that enables programmable payments for onchain services. -- [**Filecoin Beam**](https://docs.filbeam.com/) — Available as an add-on, a retrieval and delivery layer that ensures global accessibility of stored data. +- [**Filecoin Beam**](https://docs.filbeam.com/) — Available as an add-on, a retrieval and delivery layer that serves stored data globally. -Each of these components works independently yet integrates seamlessly through onchain smart contracts and the [**Synapse SDK**](https://github.com/FilOzone/synapse-sdk), forming a cohesive, modular system. Together, they deliver the core properties of a next-generation decentralized cloud: verifiability, programmability, and composability. +Each component works independently but connects through onchain smart contracts and the [**Synapse SDK**](https://github.com/FilOzone/synapse-sdk). Together they provide the core properties of a decentralized cloud: verifiability, programmability, and composability. ### Key Products -The **Filecoin Onchain Cloud** is not just an infrastructure layer — it’s a platform for innovation. -By exposing verifiable storage, retrieval, and payment capabilities as onchain services, FOC empowers developers to build entirely new products and workflows to expand the functionality of the Onchain Cloud and bring Filecoin closer to becoming a **modular, decentralized cloud** ecosystem. +By exposing verifiable storage, retrieval, and payment capabilities as onchain services, FOC lets developers build products and workflows that extend the Onchain Cloud and move Filecoin toward a **modular, decentralized cloud**. #### Filecoin Pin -**Filecoin** Pin is a fully decentralized persistence layer for IPFS content using the global network of Filecoin storage providers with cryptographic guarantees. It brings **IPFS's filesystem structure to Filecoin Onchain Cloud** for developers building on IPFS who need trustless, economically-incentivized persistence for their content. +**Filecoin Pin** is a decentralized persistence layer for IPFS content, backed by the global network of Filecoin storage providers with cryptographic guarantees. It brings **IPFS's filesystem structure to Filecoin Onchain Cloud** for developers who need trustless, economically incentivized persistence for their content. [Learn more about Filecoin Pin →](https://docs.filecoin.io/builder-cookbook/filecoin-pin) -*More products will be built to extending the capability of the Filecoin Onchain Cloud.* +*More products will be built to extend the capabilities of the Filecoin Onchain Cloud.* ### Pricing -The **Filecoin Onchain Cloud (FOC)** offers transparent and verifiable pricing for its **Filecoin Warm Storage Service (FWSS)** and **Filecoin Beam** retrieval layer. -All payments are settled automatically through Filecoin Pay, ensuring on-chain accountability and proof-linked billing. +The **Filecoin Onchain Cloud (FOC)** prices its **Filecoin Warm Storage Service (FWSS)** and **Filecoin Beam** retrieval layer as follows. +Filecoin Pay settles all payments automatically, with onchain accountability and proof-linked billing. | **Service** | **Pricing** | **Description** | | ------- | --------- | -------------------- | -| **Base Storage & Retrival** | **$2.5/TiB/month/copy** (minimum 2 copies) | Redundant storage ensures durability and continuous PDP verification.
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 cost nothing, 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. | +| **Add-on Retrieval (Filecoin Beam)** | **Up to $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 onchain 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 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. +All storage and retrieval charges are denominated in **USDFC** (or supported ERC-20 tokens) and settled via **Filecoin Pay**. Every transaction is onchain, auditable, and linked to verifiable service proofs. :::