meiqimichelle/ipfs-pinning-data.md

## ipfs-pinning-data.md

      
    Raw
  

              ipfs-pinning-data.md
            
          
    Basic information around IPFS pinning APIs

Braindump from @hsanjuan

Data around pins (depending on where you are pinning, a pin has additional data attached):

The root CID (always)
Type
Name or description? (Cluster for example)
Replication factors and other options (Cluster)
Duration / Cost / Submitted (I guess pinning services track how long something was pinned to bill the cost)
Any metadata/tags (Cluster, Pinata I think too)
Status (pinning/error/pinned)
Progress (in number of DAG nodes pinned, as there is no general way to know the total % of a DAG (in unixfs DAGs yes, but this is not used))


Pinning process:

Sync: the user needs to wait until it is pinned (ipfs)
Async: the user submits the pin (cluster, other pinning services?) and the service pins in the background (potential callback informs the user when process done (i.e. in pinbots))


Pin types:

ipfs has 3 pin types: recursive, direct, indirect
The users mostly use/worry about recursive and that's what most tools do (pinning services, pinbots etc)
Cluster has a few types of pins (the normal one translates to a recursive one on IPFS, but there are also other to support sharded pins)


Pin meaning:

In IPFS it is a DAG (recursive-pins, as identified by its root CID) or a block (direct pins), to not be removed during Garbage Collection (GC)
Anywhere else it is a DAG to be "stored". Out of all the things that pin, the only one that has GC is IPFS. Thus a pin has just mostly come to mean "Merkle-DAG". List my pins = List my Merkle-DAGs.
The PINSET would be the list of pins.


Common questions when pinning that ipfs ecosystem is bad at answering:

Is it pinned?
How long will it take?
How big is this pin?