File Pinning Protocol

April 6, 2025 ยท View on GitHub

Permissionless Software Foundation Specification 010 (PS010)

Specification version: 1.0.0

Date originally published: April 6, 2024

Date last updated: April 6, 2024

Authors

Chris Troutner

1. Introduction

This specification describes a protocol for storing (pinning) files on the IPFS network. It is known as the Permissionless Software Foundation File Pinning Protocol (PSFFPP). This file hosting service can be paid through the use of SLP tokens. The protocol in this document describes a process for paying for the hosting of files (using the blockchain) to achieve a fully-decentralized process that is anonymous, permissionless, and censorship-resistant.

This specification builds on top of the PS008 specification for Claims. This protocol centers around a Pin Claim which indicates files that should be pinned by the network, and also provides proof of payment (Proof of Burn). This specification is implemented in the psffpp npm JavaScript library

2. Transactions

The PSFFPP depends on two blockchain transactions:

  • Proof of Burn (PoB) - proves that payment has been made by burning tokens.
  • Pin Claim - indicates the file that should be pinned by the network, and contains the PoB transaction ID.

Proof of Burn

A PoB transaction can encompass any SLP token, but this protocol focuses on the PSF token. An example of a PoB transaction can be viewed here. It is simply a SLP SEND transaction where the output is less than the input. The difference is considered 'burned'.

In the example transaction above, there were 7.57514589 as input, and 7.49179356 output, with a difference burned of 0.08335233 tokens. At the time of the transaction, that was the cost of writing up to 1MB to the PSFFPP network.

The cost (in tokens) for pinning data to the PSFFPP network is set by the PSF Minting Council. They periodically set the price to target $0.01 USD per megabyte for pinning costs. The token price is loosely pegged to the Bitcoin Cash cryptocurrency, so it fluctuates over time relative to the US dollar. As a result, the price is never precisely $0.01 USD.

A minimum cost of $0.01 USD in PSF tokens is required to pin content, even if that content is less than 1 MB in size. Files up to 100 MB can be pinned by the PSFFPP network. To find the current cost per MB of pinning file data, the getMcWritePrice() function can be called. That call will search the BCH blockchain for the latest price authorized by the PSF Minting Council.

Pin Claim

A pin claim is a normal Bitcoin transaction that contains an OP_RETURN in the first output. The data in the OP_RETURN output has four parts:

  1. 0x00510000 - Hexadecimal Lokad ID
  2. PoB TXID - The transaction ID for the Proof of Burn in binary format.
  3. CID - The IPFS Content ID (CID) for the file to be pinned, in utf-8 format.
  4. Filename - The original filename and extension of the file, in utf-8 format.

Here is an example of a valid Pin Claim transaction.

Pin Claims are tracked by the pin-ipfs branch of the psf-slp-indexer. When a Pin Claim transaction is detected by the indexer, the data is passed to the ipfs-file-pin-service software via a webhook. ipfs-file-pin-service will evaluate the Pin Claim and PoB transactions. If they meet the criteria above, and the PoB provides enough payment, the file is pinned by the software.

There are multiple instances of the ipfs-file-pin-service software running in the world. Each one independently evaluates and validates the Pin Claims they find, and they will independently pin the file content. This mimics the behavior of the Bitcoin Cash blockchain, where each node independently validates each transaction.

3. Supplementary Information

Documentation

Videos

Software