Інтеграція з NFT.Storage
NFT.Storage — це сервіс від Protocol Labs, який надає безплатне зберігання NFT-даних на IPFS та Filecoin. Технічно: ви завантажуєте файл через API, отримуєте CID (Content Identifier), дані реплікуються на Filecoin для довгострокового зберігання. На відміну від централізованих серверів, вміст адресується по хешу його змісту — якщо файл змінився, змінився й CID.
Для NFT-проектів це вирішує конкретну проблему: tokenURI не повинен вказувати на https://myproject.com/metadata/1.json — цей сервер може відключитися, а NFT стане порожнім. IPFS URI виду ipfs://Qm.../1.json працює незалежно від того, існує ли сайт проекту.
Як влаштоване зберігання
IPFS — адресація за вмістом
IPFS використовує content addressing: CID обчислюється з хеша вмісту файлу. ipfs://QmXoypizjW3WknFiJnKLwHCnL72vedxjQkDDP1mXWo6uco/image.png — це конкретний файл з конкретним хешем. Змінити вміст без зміни CID неможливо — це гарантія immutability для NFT-метаданих.
NFT.Storage реалізує два API: старий REST API (v1) та новий w3up клієнт (v2). Для нових проектів рекомендуємо w3up — краща продуктивність на великих колекціях.
Filecoin для персистентності
IPFS сам по собі не гарантує зберігання: якщо ні один вузол не пінує файл, він зникає. NFT.Storage автоматично створює Filecoin deals для завантажених даних — децентралізоване довгострокове зберігання з криптографічним доказом зберігання. Це відрізняється від простого IPFS pinning сервісу (Pinata, Infura).
Ліміти та обмеження
NFT.Storage запровадив обмеження в 2024 році: безплатний тир більше не доступний для нових реєстрацій через основний сайт. Protocol Labs переключив фокус на web3.storage з платними планами. Для існуючих проектів — дані залишаються доступними. Для нових — альтернативи: Pinata (платний), 4EVERLAND, або self-hosted IPFS вузли.
Для production NFT-проектів рекомендуємо гібридний підхід: основне зберігання + репліація на 2-3 pinning сервісах.
Інтеграція через JavaScript SDK
Завантаження колекції
import { NFTStorage, File } from 'nft.storage'
const client = new NFTStorage({ token: process.env.NFT_STORAGE_KEY })
// Завантаження одного NFT з зображенням та метаданими
const metadata = await client.store({
name: 'Collection #1234',
description: 'Description here',
image: new File([imageBuffer], 'image.png', { type: 'image/png' }),
attributes: [
{ trait_type: 'Background', value: 'Blue' }
]
})
console.log(metadata.url) // ipfs://Qm.../metadata.json
console.log(metadata.data.image.href) // ipfs://Qm.../image.png
Батч-завантаження для 10K колекції
Для великих колекцій — storeDirectory для завантаження всього директорія одним CID:
const files = images.map((buffer, i) =>
new File([buffer], `${i}.png`, { type: 'image/png' })
)
const imagesCid = await client.storeBlob(new Blob([/* directory */]))
На практиці зручніше використовувати Pinata pinFileToIPFS з batch завантаженням — більш надійний API для тисяч файлів.
Верифікація завантаження
Після завантаження важливо верифікувати доступність через public gateway перед встановленням baseURI в контракті. Використовуйте кілька gateway: ipfs.io/ipfs/{CID}, cloudflare-ipfs.com/ipfs/{CID}, gateway.pinata.cloud/ipfs/{CID}. Якщо файл доступний через 2 з 3 gateway протягом 30 хвилин — завантаження успішне.
Найкращі практики
Розділяйте зображення та метадані по CID. Завантажуємо зображення окремо, отримуємо CID директорії зображень. Потім генеруємо JSON метадані з image: ipfs://{imagesCid}/{tokenId}.png та завантажуємо їх. Змінити метадані без зміни CID неможливо — це гарантія для покупців.
Зберігайте CID в контракті як константу. Після фінального reveal baseURI повинен бути immutable. Якщо setBaseURI доступний owner навічно — це trust assumption. Розгляньте renounceOwnership для функції зміни URI після reveal.
IPFS gateway в tokenURI. Гаманці та маркетплейси очікують ipfs:// схему, не https://gateway.ipfs.io/. Повертайте ipfs://{CID}/{tokenId}.json — кожен клієнт використовує свій gateway.
Процес роботи
Налаштування (кілька годин). Реєстрація акаунту, отримання API ключа, тест завантаження одного файлу.
Розробка upload скрипту (1 день). Батч завантаження зображень та метаданих, верифікація CID, генерація фінального baseURI.
Інтеграція з контрактом. Встановлення baseURI після верифікації доступності на gateway.
Орієнтири за часом
Інтеграція як частина розробки NFT-колекції — 1-2 дні. Окремо — кілька годин для досвідченої команди.