Інтеграція з Pinata (IPFS pinning)

Інтеграція з Pinata (IPFS pinning)

IPFS — контент-адресуємої файлова система: хеш файла та є його адреса. Але якщо ніхто не "пініть" (зберігає) файл — він зникне з мережі. Pinata — managed pinning service: ви завантажуєте файли, вони гарантують доступність. Використовується в NFT-проектах, dApp'ах з on-chain метаданими, децентралізованих сховищах.

Завантаження файлів через Pinata API

const PINATA_JWT = process.env.PINATA_JWT!;  // з dashboard.pinata.cloud

// Завантаження файла
async function uploadFile(fileBuffer: Buffer, filename: string): Promise<string> {
  const formData = new FormData();
  formData.append('file', new Blob([fileBuffer]), filename);
  formData.append('pinataMetadata', JSON.stringify({ name: filename }));
  formData.append('pinataOptions', JSON.stringify({ cidVersion: 1 }));

  const response = await fetch('https://api.pinata.cloud/pinning/pinFileToIPFS', {
    method: 'POST',
    headers: { Authorization: `Bearer ${PINATA_JWT}` },
    body: formData,
  });

  const data = await response.json();
  return data.IpfsHash;  // CIDv1 хеш
}

// Завантаження JSON (для NFT metadata)
async function uploadJson(metadata: object, name: string): Promise<string> {
  const response = await fetch('https://api.pinata.cloud/pinning/pinJSONToIPFS', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${PINATA_JWT}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      pinataContent: metadata,
      pinataMetadata: { name },
      pinataOptions: { cidVersion: 1 },
    }),
  });

  const data = await response.json();
  return data.IpfsHash;
}

Workflow метаданих NFT

Стандартний ERC-721/ERC-1155 workflow:

// 1. Завантажуємо зображення
const imageCid = await uploadFile(imageBuffer, 'nft-image.png');

// 2. Формуємо metadata по ERC-721 Metadata Standard
const metadata = {
  name: 'My NFT #1',
  description: 'Description here',
  image: `ipfs://${imageCid}`,  // ipfs:// URI, не https://
  attributes: [
    { trait_type: 'Background', value: 'Blue' },
    { trait_type: 'Rarity', value: 'Rare' },
  ],
};

// 3. Завантажуємо metadata
const metadataCid = await uploadJson(metadata, 'nft-1-metadata.json');

// 4. tokenURI = ipfs://{metadataCid}
// У контракті: tokenURI(tokenId) повертає ipfs://{metadataCid}

Використовуйте ipfs:// URI в контракті, не https://gateway.pinata.cloud/ipfs/. Gateway може змінитись або бути недоступним — ipfs:// URI працює з будь-яким gateway.

Pinata SDK (v2)

import { PinataSDK } from 'pinata';

const pinata = new PinataSDK({
  pinataJwt: process.env.PINATA_JWT!,
  pinataGateway: process.env.PINATA_GATEWAY!,  // yourname.mypinata.cloud
});

// Завантаження з URL
const upload = await pinata.upload.url('https://example.com/image.png');
console.log(upload.cid);

// Отримання файла через dedicated gateway
const url = await pinata.gateways.convert(`ipfs://${cid}`);
// → https://yourname.mypinata.cloud/ipfs/{cid}

Dedicated gateway (платна опція) значно швидше публічного gateway.pinata.cloud — важливо для NFT маркетплейсів, де зображення грузяться користувачами.

Груповий пін та управління коллекціями

// Список запиненних файлів з фільтрацією
async function listPins(keyValues?: Record<string, string>) {
  const params = new URLSearchParams({
    status: 'pinned',
    pageLimit: '100',
    ...(keyValues ? { 'metadata[keyvalues]': JSON.stringify(keyValues) } : {}),
  });

  const response = await fetch(
    `https://api.pinata.cloud/data/pinList?${params}`,
    { headers: { Authorization: `Bearer ${PINATA_JWT}` } }
  );

  return response.json();
}

// Анпін файла (освобождает хранилище)
async function unpinFile(cid: string) {
  await fetch(`https://api.pinata.cloud/pinning/unpin/${cid}`, {
    method: 'DELETE',
    headers: { Authorization: `Bearer ${PINATA_JWT}` },
  });
}

Використовуйте pinataMetadata.keyvalues для тегірування файлів по проекту або коллекції — потім зручно фільтрувати та управляти сховищем.

Локальне резервування

Pinata — централізований сервіс. Для довгострокової надійності: дублюйте критичні CID в Filecoin через NFT.Storage або web3.storage, або тримайте власну IPFS ноду з ipfs pin add {cid}.

# Власна IPFS нода як додаткове сховище
ipfs pin add bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi

CID однаковий везде — якщо файл є хоча б у однієї ноди в мережі, він досяжний. Два pinning-провайдери = подвійна надійність.