Filecoin Pin brings multiple technologies together (i.e., existing Filecoin blockchain and storage providers, new Filecoin initiatives including Filecoin Onchain Cloud, IPFS).  As a result, terminology from all these areas is used for describing Filecoin Pin.  This glossary serves as a primer of the key terminology.  Rather than seeking to be the comprehensive source of truth, it seeks to point to where to find authoritative and more in depth information.  Many additional IPFS-related terms can be found in https://docs.ipfs.tech/concepts/glossary.  

## Access Key

The private half of a throwaway key pair the sender makes for one [Share Link](#share-link), for a recipient who has no key pair of their own. [Keysmith](https://github.com/FilOzone/synapse-sdk/tree/master/packages/keysmith) wraps shared keys to a recipient's public key; the share is wrapped to this key's public half. Its text form starts with `fak1_`. By default the link carries it; a restricted link (`--restricted`) leaves it out, and it is sent separately. Whoever holds both the link and the Access key can read that one [Encrypted Upload](#encrypted-upload). Not to be confused with a [Grant](#grant): `login` refuses an Access key pasted in its place. See the [Encryption guide](encryption.md).

## Calibration Network

The "test network" of Filecoin's Mainnet, where developers can have more realistic network conditions without using truly valuable tokens. This is sometimes colloquially known as "calibnet" and has the [chain ID](https://chainlist.org/) of 314159, while Filecoin's Mainnet is 314. See https://docs.filecoin.io/networks/calibration

## CAR

A CAR is a container format and network transport to hold your "IPFS data" (i.e., IPLD blocks).  It just happens to take file form sometimes so is often called a "CAR file".  See https://docs.ipfs.tech/concepts/glossary/#car for more info.

## CID

See https://docs.ipfs.tech/concepts/glossary/#cid.

## Claim Chain

[Keysmith](https://github.com/FilOzone/synapse-sdk/tree/master/packages/keysmith)'s signed record of who may read which key. The root is an EIP-712 `ReadGrant` signed by the [Owner](#owner) wallet, naming a bearer (for a [Grant](#grant), the [Session Key](#session-key)), the [Group Key](#group-key) or part of it, the network's chain id, an expiry, and how many more levels the bearer may delegate (none, for Grants from the console). It travels with the wrapped key in a [Delivery](#delivery). See the [Encryption guide](encryption.md).

## CommP

A common term used in place of [Piece CID](#piece-cid).

## Content Routing

How an IPFS node (including IPFS HTTP Gateways) find other IPFS nodes providing the CIDs.  Content routing refers to the way in which IPFS determines where to find a given CID on the network; specifically, which network peers are providing the CIDs you are requesting. In other words, a node cannot simply find data in the network with a CID alone; it requires information about the IP addresses and ports of its peers on the network.  Read more about [content routing in Filecoin Pin](content-routing-faq.md).

## Curio

Curio is the software that [Filecoin Warm Storage Service](#filecoin-warm-storage-service) [Service Providers](#service-provider) run, which handles:

1. interfacing with data writing clients like [Synapse](#synapse)/filecoin-pin
2. interfacing with [IPNI](#ipni) indexing for content routing
3. data retrieval from HTTP clients
4. interfacing with the blockchain for [Filecoin Warm Storage Service](#filecoin-warm-storage-service) and [Proof of Data Possession](#proof-of-data-possession)

## Data Set

Collections of stored data ([Pieces](#piece)) managed by [Filecoin Warm Storage Service](#filecoin-warm-storage-service). Each Data Set is tied to exactly one [Service Provider](#service-provider); all pieces in a Data Set are stored by the same SP. Each Data Set has [metadata](#metadata), Pieces, and an associated payment rail between [Filecoin Pay](#filecoin-pay) and the SP that handles ongoing storage payments.

Filecoin Pin reuses existing Data Sets by default, matching on [metadata](#metadata) (`source='filecoin-pin'`). When more match than the number of copies requested, it prefers the ones already holding pieces and takes at most one per Service Provider. When the matches do not cover enough distinct providers, Filecoin Pin creates new Data Sets instead.

## Delivery

[Keysmith](https://github.com/FilOzone/synapse-sdk/tree/master/packages/keysmith)'s one-blob format holding a [Claim Chain](#claim-chain) and the key it vouches for, wrapped to the bearer's public key. A [Grant](#grant) is a delivery in text form: `fgr1_` followed by its base64url encoding. See the [Encryption guide](encryption.md).

## Encrypted Root CID

The [IPFS Root CID](#ipfs-root-cid) of an [Encrypted Upload](#encrypted-upload): the root of its [Envelope](#envelope), packed as a single UnixFS file. It is what `add --encrypt` prints and what `get` takes. Gateways and [standard IPFS tooling](#standard-ipfs-tooling) can fetch it, but they return ciphertext. Compare [Plaintext Root CID](#plaintext-root-cid). See the [Encryption guide](encryption.md).

## Encrypted Upload

A file or directory uploaded with `filecoin-pin add --encrypt`. The input is packed as a UnixFS CAR (the same [unixfs-v1-2025](#unixfs-v1-2025-profile) DAG an unencrypted `add` would build, under an anonymous wrapping directory holding the input's own name) and that CAR is wrapped in an [Envelope](#envelope) (a Filecoin Encryption Envelope, FEE). The content key comes from [Keysmith](https://github.com/FilOzone/synapse-sdk/pull/983): the [Owner](#owner) wallet (`PRIVATE_KEY`) signs once for its [Group Key](#group-key), and every upload gets its own key derived from that signature and a fresh random salt. The CLI doesn't save the key: the same wallet derives it again to read the upload back with `filecoin-pin decrypt`, offline, or with `filecoin-pin get`, which also fetches it by its [IPFS Root CID](#ipfs-root-cid). The envelope is packed as `encrypted.fee`, so the `name` [Metadata](#metadata) does not reveal the original filename; names, individual file sizes, the folder structure and the plaintext [CIDs](#cid) exist only inside the ciphertext. The total size is not hidden: the envelope header records the inner CAR's length and the piece size is public, so a single file's size is visible to within a few hundred bytes. Symlinks and special files (FIFOs, sockets, devices) are skipped and counted, never named; hidden entries follow the same `--include-hidden` rule as an unencrypted `add`. A [Session Key](#session-key) with a [Grant](#grant) for the group key can read and write uploads too. The upload is fetched by its [Encrypted Root CID](#encrypted-root-cid); the original content's [Plaintext Root CID](#plaintext-root-cid) is never shown. See the [Encryption guide](encryption.md) for the model and the [README](../README.md#encrypted-uploads) for usage and `--no-ipfs`.

Blocks inside the CAR are written metadata-first: every dag-pb node (breadth-first from the root), then every raw leaf in file order, each CID once. A reader that knows the root can therefore list the tree before the first data byte and map any file offset to a byte range of the envelope without an index, which is what lets `decrypt` run in one pass and a viewer seek inside a video by HTTP Range.

The envelope's public `content_type` is `application/vnd.ipld.car`; decryptors reject any other. Its authenticated `appMetadata` is exactly what Keysmith's `pieceMetadata` emits, which is all a reader needs to derive the key again:

```json
{ "foc/v": 1, "foc/own": "<owner wallet, lowercase>", "foc/ks": "<group key id>", "foc/salt": "<16 random bytes, hex>" }
```

## Envelope

The encrypted file an [Encrypted Upload](#encrypted-upload) uploads, named `encrypted.fee`: a [Filecoin Encryption Envelope](https://github.com/FilOzone/synapse-sdk/tree/master/packages/filecoin-encryption-envelope) (FEE, draft FRC [filecoin-project/FIPs#1294](https://github.com/filecoin-project/FIPs/pull/1294)) wrapping the upload's UnixFS [CAR](#car). Its header is public: the content type, the plaintext length, and the [Owner](#owner), [Group Key](#group-key) id and salt (`foc/own`, `foc/ks`, `foc/salt`). Everything else is ciphertext. See [Format, for integrators](encryption.md#format-for-integrators) in the Encryption guide.

## Group Key

What [Keysmith](https://github.com/FilOzone/synapse-sdk/pull/983) calls a *keyspace*: the root of a key derivation tree, named by a 16-byte id and bound to the [Owner](#owner) wallet by one EIP-712 signature. Filecoin Pin records it on every [Data Set](#data-set) an [Encrypted Upload](#encrypted-upload) writes to, as `foc/ks` (the id) and `foc/kc` (a public commitment to the key, checked before the group key is reused), next to `foc/enc: "1"`, which marks the data set as encrypted and versions its rules. The metadata keys keep Keysmith's names. One group key usually spans multiple data sets: one per copy, plus any separate data set the user wants under the same group key. Only the group key id and its commitment are written on chain, and both are public; the keys themselves are never published. A [Session Key](#session-key) gets a group key through a [Grant](#grant).

An owner wallet can end up with several group keys. `add --encrypt` sorts the wallet's live data sets by `foc/ks`, skips any group key whose data sets disagree on `foc/kc` or are not `foc/enc: "1"`, and uses the group key holding the oldest data set (lowest id). All copies of an upload go to that group key; a copy without a suitable data set gets a new one with the same `foc/ks` and `foc/kc`. A group key is created only when no valid one exists, and it appears on chain with its first upload. The CLI writes nothing about it to your machine.

That first group key's id is derived from the owner address, so every client that sets up encryption before the first upload (the CLI, or several console logins) picks the same id: the first 16 bytes of `keccak256(utf8("filecoin/default-group-key") ‖ owner)`, with the owner as its 20 raw bytes (letter case does not matter), written as `0x`-prefixed lowercase hex. If that id is already on chain but its data sets are not valid (they disagree on `foc/kc` or are not `foc/enc: "1"`), and no other valid group key exists, `add --encrypt` stops with an error rather than writing into the invalid group. See [Lifecycle and limits](encryption.md#lifecycle-and-limits) in the Encryption guide.

## Group

What [Keysmith](https://github.com/FilOzone/synapse-sdk/pull/983) calls a *scope*: a named part of a [Group Key](#group-key) with its own derived key, so access can be granted to some uploads without the whole group key. An upload in a group carries it in the envelope as `foc/scope` (Keysmith's label). `add --encrypt` does not put uploads in groups yet; every upload is under the group key itself. Groups are planned in [#781](https://github.com/filecoin-project/filecoin-pin/issues/781); with them, a [Grant](#grant) can cover part of a group key. Not to be confused with session-key permission scopes (`login --scopes`).

## Grant

A group key Grant: what lets a [Session Key](#session-key) read and write a [Group Key](#group-key) without the owner wallet. `filecoin-pin login --scopes createDataSet,addPieces,encrypt` asks the Filecoin Cloud console (`CONSOLE_URL`, default https://pay.filecoin.cloud) for one. The console has the owner wallet sign a [Keysmith](https://github.com/FilOzone/synapse-sdk/pull/983) root claim for the whole group key (bearer: the session key; expiry: the session key's authorization expiry; the network's chain id) and wraps the group key to the session key's public key. Its text form is `fgr1_` followed by the base64url (unpadded) Keysmith [Delivery](#delivery), which holds the [Claim Chain](#claim-chain) and the wrapped key; whitespace is ignored, since consoles wrap long lines.

The CLI checks a Grant when it is imported and every time it is used: Keysmith checks the signatures, the expiry, that the session key is the bearer, and the key against the commitment the owner signed; the CLI checks the owner, the network, and the group key. It is saved as `GROUP_KEY_ID` and `GROUP_KEY_GRANT` next to the session key; the key it opens is never stored. A session key with a Grant uploads with `add --encrypt` into the group key's [Data Sets](#data-set) (tagging new ones with the `foc/kc` the owner signed) and reads [Encrypted Uploads](#encrypted-upload) under that group key with `get` and `decrypt`.

A Grant cannot be revoked: it gives the session key permanent read access to the whole group key, including future uploads. Session keys cannot pass it on. Not to be confused with the on-chain authorization of the session key's scopes, which `login` also calls a grant, or with an [Access Key](#access-key). See [Two ways to hold the key](encryption.md#two-ways-to-hold-the-key) in the Encryption guide.

## FIL

FIL is Filecoin's native token.  While [Filecoin Onchain Cloud](#filecoin-onchain-cloud) storage is currently denominated in [USDFC](#usdfc), gas for transactions on the Filecoin blockchain (e.g., adding a [Piece](#piece)) need to be paid for using FIL. Most transactions in the data onboarding flow for Filecoin Onchain Cloud are submitted by storage providers so client typically have minimal need to interact directly with FIL.

## FilBeam egress

This concerns the [/piece retrieval](#piece-retrieval) CDN provided by [FilBeam](https://github.com/filbeam). When `filecoin-pin add` or `filecoin-pin import` is run with `--egress-provider beam` (the default is `none`), uploaded pieces are retrievable via FilBeam at `https://{wallet-address}.{filbeam-domain}/{pieceCid}` (e.g., `https://0xabc....calibration.filbeam.io/bafk...` on the [Calibration Network](#calibration-network)).

**What it does today:** Serves [`/piece` Retrieval](#piece-retrieval) only — whole-CAR fetches keyed by [Piece CID](#piece-cid). It does **not** route [`/ipfs` Retrieval](#ipfs-retrieval); for those, use the IPFS retrieval URLs printed alongside the upload result.

**Network support:** FilBeam URLs are only printed on networks with a FilBeam endpoint (mainnet and [Calibration](#calibration-network)). On networks without one (e.g. devnet), passing `--egress-provider beam` is accepted but no FilBeam URL is shown.

**Cost:** CDN egress is paid from funds the data set owner locks up for it — it is not billed to their wallet at data-set creation. Instead, lockup is consumed as retrievals happen. Anyone who knows the piece CID and wallet address can trigger a retrieval, which draws down that egress lockup.

**Lockup:** Creating a new FilBeam-enabled [Data Set](#data-set) requires an extra fixed lockup of 1 USDFC (on top of the data-set creation fee and ongoing storage cost). This is why a CDN upload that creates a new data set needs more deposited funds than a non-CDN one. `--auto-fund` accounts for it automatically; without it, deposit enough to cover the lockup or the upload fails with an insufficient-funds error.

**Future state:** FilBeam is working on routing IPFS-block retrievals through the same CDN ([filbeam/roadmap#85](https://github.com/filbeam/roadmap/issues/85)). [Data Sets](#data-set) uploaded with FilBeam enabled today will benefit automatically when that ships.

**Opting in:** FilBeam routing is off by default. Pass `--egress-provider beam` (or `EGRESS_PROVIDER=beam`) to enable it.

## Filecoin Pay

Filecoin Pay is a generic payment solution between users and various [Filecoin Onchain Cloud](#filecoin-onchain-cloud) services.

Learn more at https://github.com/FilOzone/filecoin-pay

## Filecoin Onchain Cloud

https://filecoin.cloud.

This is the collection of DePIN services offered on Filecoin using shared/consistent payment infrastructure in [Filecoin Pay](#filecoin-pay).  [Filecoin Warm Storage Service](#filecoin-warm-storage-service) is the initial service offering.

This is often abbreviated as “FOC”, which yes, does phonetically resonate with more colorful language 😉.

## Filecoin Pin

https://github.com/filecoin-project/filecoin-pin

Serves as an IPFS-oriented set of tools for interfacing with [Filecoin Onchain Cloud](#filecoin-onchain-cloud) built on top of [Synapse](#synapse).

## `filecoin-pin` CLI

The npm package name and CLI tool for [Filecoin Pin](#filecoin-pin). The package includes both the CLI and the [JavaScript library](#filecoin-pin-javascript-library). See [CLI affordance in the README](../README.md#-cli).

## filecoin-pin-website

https://github.com/filecoin-project/filecoin-pin-website

Example of [Filecoin Pin](#filecoin-pin) in action within a web-browser.  Its purposes are:

1. Demonstrate that Filecoin Pin is usable.  Drag and drop and you're good to go!
2. Serve as a starter or inspiration for dApp builders wanting to use [Filecoin Onchain Cloud](#filecoin-onchain-cloud).

filecoin-pin-website is also hosted at [pin.filecoin.cloud](http://pin.filecoin.cloud), with hardcoded wallet and [session key](#session-key) on the [Calibration](#calibration-network) network.  In future, [integration with tools like Metamask will be supported](https://github.com/filecoin-project/filecoin-pin-website/issues/77).  

## Filecoin Pin GitHub Action

See [GitHub Action affordance in the README](../README.md#-github-action).

## Filecoin Pin JavaScript Library

See [JavaScript Library affordance in the README](../README.md#-javascript-library).

## Filecoin Pin IPFS Pinning Server

See [IPFS Pinning Server affordance in the README](../README.md#-ipfs-pinning-server-daemon-mode).

## Filecoin Pin Management Console

See [Management Console affordance in the README](../README.md#-management-console-gui).

## Filecoin Warm Storage Service

This is the primary smart contract used when interacting with the warm storage functionality offered in [Filecoin Onchain Cloud](#filecoin-onchain-cloud).  It acts as both a "service" contract and a "validator" contract for payment management and settlements, ensuring the warm storage service is actually delivered before payments are released to the [Service Provider](#service-provider).

## GC Window

The time a [Service Provider](#service-provider)'s [Curio](#curio) instance keeps a [Parked Piece](#parked-piece) before garbage-collecting it (roughly 2 hours by default, provider-configurable, not discoverable on chain). The `migrate` command schedules its batched `addPieces` commits to land before its per-provider estimate of this window expires, and lowers the estimate when it observes a GC rejection.

## IPFS Root CID

The CID for the root of a merkle DAG that is usually encoding a file or directory as UnixFS.  Since each `filecoin-pin add` creates a [CAR](#car), regardless if passed a file or directory, there is a single root corresponding to root of the Merkle DAG made out of encoding the file or directory as UnixFS. Typically this will be presented in base32, beginning with `bafy` and be 59 characters long. See [Relationship between Piece CID and IPFS Root CID](#relationship-between-piece-cid-and-ipfs-root-cid) for how this relates to the [Piece CID](#piece-cid).

## `/ipfs` Retrieval

This is one of two retrieval endpoints that [Service Providers](#service-provider) expose (see [Retrieving Your Data](retrieval.md) for a practical walkthrough).  This endpoint conforms with the [IPFS Trustless Gateway Specification](https://specs.ipfs.tech/http-gateways/trustless-gateway/).  All CIDs that are indexed by the SP should be retrievable via this endpoint.  This is the endpoint that is announced through the provider records stored by [IPNI](#ipni) Indexers. 

As a "trustless" protocol, retrieval of IPFS data using this mechanism provides assurance that data has not been tampered with and that what is being retrieved is _exactly_ what was requested. This is in contrast to a "trusted" gateway where IPFS data is reassembled into a form appropriate for rendering. Developers and users are encouraged to perform this reassembly step as close as possible to the user, using existing IPFS technologies such as [Kubo](https://github.com/ipfs/kubo) and [Helia](https://github.com/ipfs/helia). For example, Helia's [`verified-fetch` package](https://www.npmjs.com/package/@helia/verified-fetch) is able to perform this within a browser context and is powering https://inbrowser.link/. On the command line, `filecoin-pin get` does it too: it finds providers through [IPNI](#ipni) and the caller's own [Data Sets](#data-set), downloads the CAR with `?format=car&dag-scope=all` and checks every block against its CID before writing anything.

## IPNI

See https://docs.ipfs.tech/concepts/glossary/#ipni.

IPNI is the content routing system that [Filecoin Pin](#filecoin-pin) relies upon for retrieval to work for [standard IPFS tooling](#standard-ipfs-tooling).  [Service Providers](#service-provider) announce their advertisement changes to IPNI indexers like cid.contact, and the advertised CIDs become discoverable for IPFS Standard tooling.

## Metadata

Key-value pairs supplied when creating [Data Sets](#data-set) or adding [Pieces](#piece). [Filecoin Pin](#filecoin-pin) uses specific metadata keys:

Key | Purpose | Scope
--- | --- | ---
`source` | Set to 'filecoin-pin' to identify data created by this tool | Data Set
`withIPFSIndexing` | Set to empty string to signal the [SP](#service-provider) to index and advertise the data to [IPNI](#ipni) | Data Set
`ipfsRootCID` | Submitted with each Piece to link the [Piece CID](#piece-cid) back to the [IPFS Root CID](#ipfs-root-cid). While this is a convention that Filecoin Pin follows, there is nothing onchain enforcing a correct link between `ipfsRootCID` and `pieceCid`. | Piece
`name` | Original basename of the source path (file or directory). Auto-derived during `add` so the human-readable label survives even though the [UnixFS profile](#unixfs-v1-2025-profile) does not wrap single files in a parent directory. User-supplied piece metadata wins over the auto-derived value; an explicit empty string is treated as an opt-out. Consumers that need to know whether the source was a file or a directory inspect the [IPFS Root CID](#ipfs-root-cid) (codec + UnixFS `Data.Type`), matching the IPFS Pinning Service `name` convention. | Piece

Data Set metadata is stored and remains queryable on-chain. Piece metadata (`ipfsRootCID`, `name`, and user-supplied `--metadata`) is signed and emitted in the Filecoin Warm Storage Service's `PieceAdded` event, but is not retained for later contract queries. Filecoin Pin therefore writes piece metadata during uploads but does not read or display it. `filecoin-pin data-set show` still displays Data Set metadata, while `filecoin-pin data-set piece-status` displays piece ID, PieceCID, size, and reconciled status.

## Member CAR

A single source [CID](#cid)'s verified [CAR](#car), downloaded from a trustless gateway by the `migrate` command and staged on disk. Members are bin-packed into one multi-root CAR that becomes a [Piece](#piece); the member file is deleted once the packed piece records it. See [How migrate works](migrate.md).

## Owner

The wallet an upload belongs to: it pays for storage, authorizes [Session Keys](#session-key), and derives its [Group Keys](#group-key) by signing. Owner mode means the CLI holds this wallet's key (`PRIVATE_KEY`). Every [Envelope](#envelope) names its owner as `foc/own`. See the [Encryption guide](encryption.md).

## Parked Piece

A [Piece](#piece) stored on a [Service Provider](#service-provider) but not yet committed on chain via `addPieces`. Parking starts the provider's [GC Window](#gc-window) clock: a piece parked past the window is garbage-collected and must be stored again.

## unixfs-v1-2025 profile

The [IPIP-499](https://github.com/ipfs/specs/pull/499) UnixFS CID profile that Filecoin Pin uses when packing files and directories. Selecting this profile pins importer settings (CIDv1, raw leaves, 1 MiB chunks, 1024-link DAG width, block-bytes HAMT shard estimation) so that the [IPFS Root CID](#ipfs-root-cid) for a given input matches the CID produced by any other conforming implementation. Filecoin Pin does not wrap single files in a parent directory under this profile; the source basename is preserved via the `name` [Metadata](#metadata) entry instead.

## Piece

A Piece is an individual unit of data identified by [Piece CID](#piece-cid). Multiple Pieces can be added to a [Data Set](#data-set) for storage.

With [Filecoin Pin](#filecoin-pin), the Piece is the [CAR](#car) file itself; an array of bytes representing the serialized content. Each `filecoin-pin add` operation creates exactly one Piece by converting the input file or directory to a CAR file, which then becomes the Piece that is uploaded and stored.

## Piece CID

PieceCID, or "CommP" (Commitment of Piece), is a specific form of [CID](#cid) used in Filecoin to commit Merkle proofs of large _pieces_ of data on chain. A PieceCID includes a digest of the contiguous bytes, with no special handling of any internal format or packing (including CAR formats containing IPFS data). It uses a modified form of SHA2-256 internally, and further details can be found in [FRC-0069](https://github.com/filecoin-project/FIPs/blob/master/FRCs/frc-0069.md). PieceCID is a variant of CID specifically for use in Filecoin's proof system, and will differ from the CIDs used in IPFS. When presented in standard base32 format, it will begin with the characters `bafkzcib` and be between 64 and 65 characters long. See [Relationship between Piece CID and IPFS Root CID](#relationship-between-piece-cid-and-ipfs-root-cid) for how this relates to the [IPFS Root CID](#ipfs-root-cid).

## Piece Copy

In [Filecoin Pin](#filecoin-pin) and [Synapse](#synapse), a copy is one independent storage placement of the same [Piece](#piece) on a single [Service Provider](#service-provider) (usually in its own [Data Set](#data-set)). All copies share the same [Piece CID](#piece-cid); they differ by which SP holds the bytes and records the piece on chain.

This is not the everyday sense of "original plus one duplicate." Here, N copies means N stored instances across N providers, not N extras on top of an unnamed original. Even the first upload target is called a copy with role "primary". (See [Synapse upload docs](https://docs.filecoin.cloud/reference/filoz/synapse-sdk/storage/classes/storagemanager/#upload).)

## `/piece` Retrieval

This is a Filecoin-defined retrieval specification outlined in https://github.com/filecoin-project/FIPs/blob/master/FRCs/frc-0066.md (see [Retrieving Your Data](retrieval.md) for a practical walkthrough).  It is for retrieving pieces by [Piece CID](#piece-cid), optionally taking a byte range specified by standard HTTP request format. Piece retrieval is useful for downloading the bytes _as they are stored and proven_ in Filecoin, either to request the original non-IPFS data stored, or downloading the CAR format data generated by Filecoin Pin.

It takes the form of https://sp.domain/piece/$pieceCid.

## Plaintext Root CID

The [IPFS Root CID](#ipfs-root-cid) of the original content of an [Encrypted Upload](#encrypted-upload), before encryption. It exists only inside the ciphertext: Filecoin Pin never prints or logs it, and it is not the CID to fetch. Compare [Encrypted Root CID](#encrypted-root-cid). See the [Encryption guide](encryption.md).

## Proof of Data Possession

https://github.com/FilOzone/pdp

The cryptographic protocol that verifies [service providers](#service-provider) are actually storing the data they claim to store. Providers must periodically prove they possess the data.  This is distinct from the existing Filecoin proof system, "PoRep" or "Proof of Replication".

This is usually abbreviated as "PDP".

## Relationship between Piece CID and IPFS Root CID

Each `filecoin-pin add` produces both a [Piece CID](#piece-cid) and an [IPFS Root CID](#ipfs-root-cid), but they are computed independently and **neither can be derived directly from the other**.

The **IPFS Root CID** is the root of a Merkle DAG, a tree of content-addressed blocks built by the UnixFS importer. Each block is hashed individually and the root hash rolls up the entire tree. The **Piece CID** is a commitment over the _raw contiguous bytes_ of the [CAR](#car) file that serializes that DAG. It uses a different hash construction (a binary Merkle tree of fixed-size segments using a modified SHA2-256, per [FRC-0069](https://github.com/filecoin-project/FIPs/blob/master/FRCs/frc-0069.md)) and treats the CAR as an opaque byte stream with no awareness of the IPFS blocks inside it.

Because the two hashing schemes are structurally different, there is **no cryptographic link** between them. A Piece CID alone cannot tell you which IPFS Root CID the data represents, and an IPFS Root CID alone cannot tell you which Piece it was packed into.

### How the link is established

[Filecoin Pin](#filecoin-pin) submits the IPFS Root CID as signed Piece [Metadata](#metadata) (`ipfsRootCID`) during upload. The mapping is attested by the uploader, not computed from proof. Filecoin Warm Storage Service emits the metadata in its `PieceAdded` event but does not retain it for later contract queries. This means:

- **Event indexers**, including subgraphs such as PDP Explorer, can recover the uploader-declared `ipfsRootCID` from `PieceAdded`. Filecoin Pin does not currently perform this lookup.
- **[IPNI](#ipni)** provides a reverse lookup path: IPNI indexes IPFS CIDs and each advertisement's ContextID encodes the Piece CID, so you can go from an IPFS CID to a Piece CID via the indexer. This is trust-based: you trust the [Service Provider](#service-provider) to have created the advertisement correctly. See [How to go from IPFS CID to Piece CID using IPNI](#how-to-go-from-ipfs-cid-to-piece-cid-using-ipni) for a worked example.

Both paths are **trust-based, not trustless**. Event metadata attests only what the client declared, event lookups trust the indexer, and IPNI lookups trust the SP and indexer. For end-to-end verification, retrieve the data via [`/piece` retrieval](#piece-retrieval), decode the CAR, and confirm that the DAG root matches the declared IPFS Root CID.

See [Retrieving Your Data](retrieval.md) for how to use each CID to fetch your content.

### How to go from IPFS CID to Piece CID using IPNI

[IPNI](#ipni) advertisements include a `ContextID` that encodes the [Piece CID](#piece-cid). You can use this to reverse-map an IPFS CID back to the Piece it lives in.

1. Look up the IPFS CID in an IPNI indexer, e.g. `https://cid.contact/cid/<ipfs-cid>`.
2. Find the `ContextID` field in one of the provider records. It is base64-encoded.
3. Decode the base64, drop the first byte (a version prefix), and treat the remaining bytes as a CID:

```js
import { CID } from 'multiformats/cid'

const contextId = 'AQGB4gOSICBlxzDbqCDi1dCgK8UmZ/1ACAKoEFxPrfg0zo0IeI8PJQ=='
const pieceCid = CID.decode(Buffer.from(contextId, 'base64').slice(1))
// baga6ea4seaqglrzq3oucbywv2cqcxrjgm76uacacvaifyt5n7a2m5diipchq6ji
```

This gives you the Piece CID that the [Service Provider](#service-provider) advertised for that content. From there, use an event indexer to recover the emitted `ipfsRootCID`, or retrieve the data via [`/piece` retrieval](#piece-retrieval) and verify the CAR's DAG root directly.

Note that this mapping is **trust-based**: you are trusting the SP to have created the IPNI advertisement correctly, and the indexer to have recorded it faithfully.

## RPC Provider

HTTP endpoint/infrastructure for reading or writing blockchain state.  These RPC providers run native blockchain clients and likely are storing blockchain state in an optimized format for faster reads. Filecoin provides support for the common set of Ethereum-style APIs in its RPC endpoints, meaning that most standard Ethereum tooling can interact with Filecoin without significant modification.  See https://docs.filecoin.io/networks/mainnet/rpcs for more information about Filecoin RPC providers.

## Service Provider

Service Providers receive uploaded piece data and then cryptographically prove that they have possession of the uploaded data.  Service providers do this in exchange for payment through [Filecoin Pay](#filecoin-pay) as validated and authorized by [Filecoin Warm Storage Service](#filecoin-warm-storage-service).  Service Providers at least currently run [Curio](#curio).

This is usually abbreviated as "SP".

Note that within [Filecoin Onchain Cloud](#filecoin-onchain-cloud), service providers in the context of warm storage are also commonly referred to as [Storage Providers](#storage-provider), and these two terms are often used interchangeably.

## Service Provider Registry

An onchain registry of [Service Providers](#service-provider) who are participating in [Filecoin Onchain Cloud](#filecoin-onchain-cloud).  They can be viewed at https://filecoin.cloud/service-providers.  By default, only "Approved Providers" are used by [Filecoin Pin](#filecoin-pin) because they have been vetted to support IPFS Mainnet retrievals.

## Session Key

Session Keys are wallet addresses, registered in the **Session Key Registry** on chain and used by [Filecoin Warm Storage Service](#filecoin-warm-storage-service) as an alternative to directly signed operations (e.g., adding pieces).

A session key acts as a credential that permits a scoped-down set of tasks on behalf of a wallet within an expiration window.  For example, the [filecoin-pin-website](#filecoin-pin-website) uses a shared session key so that anonymous users can test out the tool without bringing their own wallet or funds, while the owner of those actions is original (private) wallet of the service.

Session keys require specific permissions (such as CREATE_DATA_SET and ADD_PIECES) and have expiration timestamps.  The filecoin-pin-website session key is scoped to allowing the creation of [data sets](#data-set) and [pieces](#piece), but prevents transferring of funds for example. Wallet owners can also revoke session key permissions before expiration. With `filecoin-pin login --scopes …,encrypt` a session key also gets a [Grant](#grant) to read and write [Encrypted Uploads](#encrypted-upload) without the [Owner](#owner) wallet; see the [Encryption guide](encryption.md).

Note that the filecoin-pin CLI's `--session-key` flag (and `SESSION_KEY` environment variable) expect the session key's **private key** — the `SESSION_KEY` value printed by `filecoin-pin session create` or `filecoin-pin session generate` — not the session address. The (public) session address is only used when authorizing or revoking: `filecoin-pin session authorize <session-address>` and `filecoin-pin session revoke <session-address>`.



## Share Link

A link that opens one [Encrypted Upload](#encrypted-upload) in the Filecoin encryption viewer, or with `get --share`, made by `get-share-link` or `add --encrypt --get-share-link`. It carries that upload's key, wrapped to a throwaway key pair, in the link's fragment, so it never reaches a server. By default it also carries the [Access Key](#access-key) and opens on its own; a restricted link (`--restricted`) leaves the Access Key out, and the recipient needs both. A share cannot be revoked and does not expire. See the [Encryption guide](encryption.md).

## Standard IPFS Tooling

This is shorthand way of referring to all the tooling the traditional IPFS ecosystem has built up for finding and retrieving content on [IPFS Mainnet](https://docs.ipfs.tech/concepts/glossary/#mainnet).  This includes tools like Kubo, Helia, and HTTP gateways.  A goal of filecoin-pin is to make sure data stored with it is retrievable with standard IPFS tooling without any special configuration.

## Storage Provider

A common term used in place of [Service Provider](#service-provider).  Before [Filecoin Onchain Cloud](#filecoin-onchain-cloud), when Filecoin was just focused on storage, SP referred to "Storage Providers".  Now with the broader scope and utility of FOC, the more general "Service Provider" name is preferred.

## Synapse

Synapse is the TypeScript SDK for interfacing with [Filecoin Onchain Cloud](#filecoin-onchain-cloud).  It abstracts [RPC Provider](#rpc-provider) calls, reading/writing smart contract state, and [Service Provider](#service-provider) interactions. Published as `@filoz/synapse-sdk` on npm, it provides TypeScript types and handles all blockchain interactions. Read more at https://synapse.filecoin.cloud.

## USDFC

A US dollar denominated "stable coin" that is backed by [FIL](#fil).  USDFC is the currency used by [Service Providers](#service-provider) in [Filecoin Onchain Cloud](#filecoin-onchain-cloud).  USDFC is an ERC-20 token. Read more at https://docs.secured.finance/usdfc-stablecoin.
