Glossary

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.

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 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.

CommP

A common term used in place of 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.

Curio

Curio is the software that Filecoin Warm Storage Service Service Providers run, which handles:

1. interfacing with data writing clients like Synapse/filecoin-pin
2. interfacing with IPNI indexing for content routing
3. data retrieval from HTTP clients
4. interfacing with the blockchain for Filecoin Warm Storage Service and Proof of Data Possession

Data Set

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

Filecoin Pin reuses existing Data Sets by default, matching on metadata (source='filecoin-pin'). If multiple exist, it uses the one storing the most data.

FIL

FIL is Filecoin's native token. While Filecoin Onchain Cloud storage is currently denominated in USDFC, gas for transactions on the Filecoin blockchain (e.g., adding a 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 CDN provided by FilBeam. When filecoin-pin add or filecoin-pin import is run with --egress-provider beam (the default), 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).

What it does today: Serves /piece Retrieval only — whole-CAR fetches keyed by Piece CID. It does not route /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). On networks without one (e.g. devnet), --egress-provider beam stays the default 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 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). Data Sets uploaded with FilBeam enabled today will benefit automatically when that ships.

Opting out: Pass --egress-provider none (or EGRESS_PROVIDER=none) to skip FilBeam routing entirely.

Filecoin Pay

Filecoin Pay is a generic payment solution between users and various 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 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 built on top of Synapse.

filecoin-pin CLI

The npm package name and CLI tool for Filecoin Pin. The package includes both the CLI and the JavaScript library. See CLI affordance in the README.

filecoin-pin-website

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

Example of 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-pin-website is also hosted at pin.filecoin.cloud, with hardcoded wallet and session key on the Calibration network. In future, integration with tools like Metamask will be supported.

Filecoin Pin GitHub Action

See GitHub Action affordance in the README.

Filecoin Pin JavaScript Library

See JavaScript Library affordance in the README.

Filecoin Pin IPFS Pinning Server

See IPFS Pinning Server affordance in the README.

Filecoin Pin Management Console

See Management Console affordance in the README.

Filecoin Warm Storage Service

This is the primary smart contract used when interacting with the warm storage functionality offered in 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.

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, 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 for how this relates to the Piece CID.

/ipfs Retrieval

This is one of two retrieval endpoints that Service Providers expose (see Retrieving Your Data for a practical walkthrough). This endpoint conforms with the IPFS Trustless Gateway Specification. 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 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 and Helia. For example, Helia's verified-fetch package is able to perform this within a browser context and is powering https://inbrowser.link/.

IPNI

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

IPNI is the content routing system that Filecoin Pin relies upon for retrieval to work for standard IPFS tooling. Service Providers announce their advertisement changes to IPNI indexer like filecoinpin.contact and cid.contact, and the advertised CIDs become discoverable for IPFS Standard tooling.

Metadata

Key-value pairs stored on-chain, either scoped to Data Sets or Pieces. Filecoin Pin uses specific metadata keys:

unixfs-v1-2025 profile

The IPIP-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 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 entry instead.

Piece

A Piece is an individual unit of data identified by Piece CID. Multiple Pieces can be added to a Data Set for storage.

With Filecoin Pin, the Piece is the 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 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. 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 for how this relates to the IPFS Root CID.

Piece Copy

In Filecoin Pin and Synapse, a copy is one independent storage placement of the same Piece on a single Service Provider (usually in its own Data Set). All copies share the same 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.)

/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 for a practical walkthrough). It is for retrieving pieces by 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.

Proof of Data Possession

https://github.com/FilOzone/pdp

The cryptographic protocol that verifies service providers 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 and an 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 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) 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 bridges this gap by recording the IPFS Root CID as signed on-chain Metadata (ipfsRootCid) on each Piece. The client signs this metadata at upload time, so the mapping is attested by the uploader, not computed from proof. This means:

• On-chain metadata is the primary source of truth for the mapping. Anyone can look up a Piece's metadata and find the ipfsRootCid the uploader declared.
• 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 to have created the advertisement correctly. See How to go from IPFS CID to Piece CID using IPNI for a worked example.
• Subgraphs (e.g., PDP Explorer) can also surface the ipfsRootCid metadata for a given Piece, independently of the SP.

All of these paths are trust-based, not trustless. The on-chain metadata is as reliable as the client that signed it; the IPNI path trusts the SP's advertisement; the subgraph path trusts the indexer. For end-to-end verification, retrieve the data via /piece retrieval, decode the CAR, and confirm that the DAG root matches the declared IPFS Root CID.

See Retrieving Your Data for how to use each CID to fetch your content.

How to go from IPFS CID to Piece CID using IPNI

IPNI advertisements include a ContextID that encodes the 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> (or use filecoinpin.contact for data stored via Filecoin Pin).
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:

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 advertised for that content. From there you can look up the Piece's on-chain Metadata to confirm the ipfsRootCid, or retrieve the data via /piece retrieval.

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 as validated and authorized by Filecoin Warm Storage Service. Service Providers at least currently run Curio.

This is usually abbreviated as "SP".

Note that within Filecoin Onchain Cloud, service providers in the context of warm storage are also commonly referred to as Storage Providers, and these two terms are often used interchangeably.

Service Provider Registry

An onchain registry of Service Providers who are participating in Filecoin Onchain Cloud. They can be viewed at https://filecoin.cloud/service-providers. By default, only "Approved Providers" are used by 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 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 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 and pieces, but prevents transferring of funds for example. Wallet owners can also revoke session key permissions before expiration.

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>.

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. 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. Before 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. It abstracts RPC Provider calls, reading/writing smart contract state, and 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. USDFC is the currency used by Service Providers in Filecoin Onchain Cloud. USDFC is an ERC-20 token. Read more at https://docs.secured.finance/usdfc-stablecoin.