Pinning on Bitsy Wiki

Pinning Services

Mon, 01 Jan 0001 00:00:00 +0000

A pinning service runs the IPFS node a publisher would otherwise run. It takes a content identifier (CID) or a file, keeps the blocks, keeps the process up, keeps the provider records fresh, and usually sells a gateway hostname alongside. The product is uptime and attention, and it is priced like hosting because that is what it is.

Two ways to hand data over#

Uploading the bytes puts the import in the service’s hands, which means the service picks the chunker, the CID version, and whether leaves are raw — so the CID that comes back is a function of their settings, not of the file alone. Two services given the same file routinely return different CIDs, and neither is wrong. A CID that has to be predictable, because it is going into a contract, a signature, or a citation, has to be produced locally and then pinned rather than discovered after the fact.

The Pinning Service API

Mon, 01 Jan 0001 00:00:00 +0000

The IPFS Pinning Service API is one HTTP interface that every pinning service can implement, so a node can be pointed at any of them without new client code. Kubo speaks it natively, which is what turns “which service am I using” into a configuration line rather than an integration project.

The surface#

Five operations over one resource:

POST   /pins                  create a pin request
GET    /pins                  list, filtered by status, cid, name, or time
GET    /pins/{requestid}      one request
POST   /pins/{requestid}      replace the pinned CID, keeping the request
DELETE /pins/{requestid}      unpin

Authentication is a bearer token in the Authorization header. A pin request carries the content identifier (CID), an optional name, an optional meta map the service stores and returns untouched, and origins.

IPFS Cluster

Mon, 01 Jan 0001 00:00:00 +0000

IPFS pins are per-node: a pin on one machine says nothing to any other. IPFS Cluster adds the missing layer — a daemon that runs beside each Kubo instance and gives a group of them one shared pinset, with a replication factor per entry and automatic allocation of each pin to specific peers.

The shape of it#

  peer A                    peer B                    peer C
┌──────────────┐          ┌──────────────┐          ┌──────────────┐
│ ipfs-cluster │◄────────►│ ipfs-cluster │◄────────►│ ipfs-cluster │
│      │       │  pinset  │      │       │  pinset  │      │       │
│   kubo       │          │   kubo       │          │   kubo       │
└──────────────┘          └──────────────┘          └──────────────┘

The cluster peers agree on which content identifiers (CIDs) should be pinned and by whom; the Kubo daemons underneath do the actual pinning and serving. Cluster is not a storage layer and does not touch blocks — it is bookkeeping over a set of nodes that each speak plain IPFS to the outside world.