Skip to main content

Distributed data storage

While smart contracts can store data, developers don't put large amounts of data in them, especially static or binary files such as images. Instead, they configure distributed storage for the data and put only the link to that data on Tezos itself. For example, when you create NFTs, you can put only basic information about the token in its smart contract and link to its full data in distributed storage, such as metadata in any format or an image that represents the token.

Tezos developers use the InterPlanetary File System (IPFS) protocol to link from smart contracts and tokens to distributed data.

Setting up an IPFS account​

If you haven't done so already, you'll need a way to upload, or pin, files to IPFS. One way is with a free Pinata developer account, which you can set up with these instructions:

  1. Create a free Pinata account at https://app.pinata.cloud/developers/api-keys.

  2. Go to the API Keys tab and click New Key.

  3. On the Create New API Key page, expand API Endpoint Access > Pinning and enable the pinFileToIPFS and pinJSONToIPFS permissions, as in this picture:

    Selecting the permissions for the Pinata key

  4. In the Key Name field, give the key a name, such as "My Key."

  5. Click Create Key.

    The API Key Info window shows the API key and secret, which you must copy immediately, because they are not shown again.

  6. Copy the API Key, API Secret, and JWT fields and save the values on your computer.

    You can see the new API key on the API Keys tab:

    The new Pinata API key in the Pinata web app

  7. Test the API key by running this command, replacing $PINATA_JWT with the value of the Pinata JWT field:

    curl --request GET \
      --url https://api.pinata.cloud/data/testAuthentication \
      --header "accept: application/json" \
      --header "authorization: Bearer $PINATA_JWT"

    Pinata responds with the message {"message":"Congratulations! You are communicating with the Pinata API!"}.

Now your applications can use your Pinata account to pin NFT data to IPFS.

Pinning data to IPFS​

You can pin files to IPFS with Pinata in several different ways, including the Pinata web site, API, CLI, and SDK. For example, this command pins JSON data with the file name theFileIPinned.json:

curl --request POST \
  --url https://api.pinata.cloud/pinning/pinJSONToIPFS \
  --header "accept: application/json" \
  --header "content-type: application/json" \
  --header "authorization: Bearer $PINATA_JWT" \
  --data '
{
  "pinataContent": {
    "somekey": "somevalue",
    "anotherkey": "anotherValue"
  },
  "pinataOptions": {
    "cidVersion": 1
  },
  "pinataMetadata": {
    "name": "theFileIPinned.json"
  }
}
'

The Pinata API responds with an IPFS hash, as in this example:

{
  "IpfsHash": "QmRyTc9KbD7ZSkmEf4e7fk6A44RPciWQ274iyqRGrhbyvj",
  "PinSize":51,
  "Timestamp":"2023-11-08T20:41:03.043Z"
}

You can use IPFS hash to get the URL for the file. For example, if the IPFS hash is QmRyTc9KbD7ZSkmEf4e7fk6A44RPciWQ274iyqRGrhbyvj1, the URL to the data is https://ipfs.io/ipfs/QmRyTc9KbD7ZSkmEf4e7fk6A44RPciWQ274iyqRGrhbyvj.

For more information about pinning with Pinata, see the Pinata documentation.

Last updated on