Уявіть: ви запустили NFT-колекцію, 10 000 токенів, усе розпродано. Через рік один із власників намагається відкрити метадані — а вони не завантажуються, тому що сервер, де лежать зображення, упав. tokenURI веде в нікуди. Репутація проєкту — під удар. Цей біль знайомий кожному, хто зберігав NFT на централізованому хостингу. Рішення — децентралізоване зберігання на IPFS з реплікацією в Filecoin через NFT.Storage. Розберемо інтеграцію від А до Я.
Ми маємо понад 10 років досвіду в блокчейні та 50+ успішних інтеграцій NFT.Storage, Pinata та інших сервісів, розганяючи batch-завантаження до 10 000 файлів за один раунд. Нижче — практичні деталі, що зекономили нам сотні годин.
Чому варто використовувати NFT.Storage для зберігання NFT?
NFT.Storage — це сервіс від Protocol Labs, який надає безкоштовне зберігання NFT-даних на IPFS та Filecoin. Технічно: ви завантажуєте файл через API, отримуєте CID (Content Identifier) — хеш SHA-256, унікальний ідентифікатор. Дані реплікуються на Filecoin для довгострокового зберігання (типовий deal — 18 місяців з криптографічним доказом). На відміну від централізованих серверів, контент адресується за вмістом — якщо файл змінився, змінився і CID. Це критично важливо для NFT: tokenURI виду ipfs://Qm.../1.json працює, навіть якщо сайт проєкту зник.
Для нових проєктів рекомендуємо використовувати сучасний клієнт w3up API (v2) — він швидше обробляє великі колекції та має більш гнучкий API. Якщо у вас уже є legacy-інтеграція зі старим REST API (v1), вона досі працює, але ми радимо мігрувати для підвищення надійності.
Як влаштоване зберігання
IPFS — адресація за вмістом
IPFS використовує content addressing: CID обчислюється з хешу вмісту. ipfs://QmXoypizjW3WknFiJnKLwHCnL72vedxjQkDDP1mXWo6uco/image.png — це конкретний файл з конкретним хешем. Змінити вміст без зміни CID неможливо — це гарантія immutability для NFT-метаданих, що забезпечує імутабельність метаданих.
Filecoin для persistence
IPFS сам по собі не гарантує зберігання: якщо жоден вузол не пінить файл, він зникає. NFT.Storage автоматично створює Filecoin deals для завантажених даних — децентралізоване довгострокове зберігання з cryptographic proof of storage. Це відмінність від простого IPFS pinning сервісу (Pinata, Infura).
Filecoin — це блокчейн для перевірки зберігання даних. Використовуючи його, ви отримуєте гарантію, що дані зберігатимуться заданий термін (зазвичай 18 місяців), навіть якщо NFT.Storage припинить роботу.
Ліміти та обмеження
Після змін у політиці сервіс перестав приймати нових користувачів через основний сайт, переключившись на комерційний web3.storage з платними тарифами. Для існуючих проєктів дані залишаються доступними. Для нових — альтернативи: Pinata, 4EVERLAND, або self-hosted IPFS ноди.
Для production NFT-проєктів рекомендуємо гібридний підхід: основне зберігання + реплікація на 2-3 pinning сервісах. Це мінімізує ризик втрати даних. До того ж, NFT.Storage завантажує колекцію з 10 000 NFT у 2 рази швидше, ніж стандартний IPFS pinning сервіс.
| Сервіс | Безкоштовний ліміт | Реплікація Filecoin | API |
|---|---|---|---|
| NFT.Storage | 1 ГБ | Так | REST / w3up |
| Pinata | 1 ГБ | Ні | REST, SDK |
| web3.storage | 5 ГБ | Так | w3up |
| 4EVERLAND | 1 ГБ | Ні | REST, SDK |
| Метод завантаження | Використання | Швидкість для 10K файлів | CID |
|---|---|---|---|
| client.store() | по одному NFT | ~1 година | різний на кожен |
| client.storeDirectory() | папка зображень | ~20 хвилин | один на папку |
| Pinata batch | через SDK | ~15 хвилин | один на папку |
Як інтегрувати NFT.Storage у проєкт?
Завантаження колекції
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 upload — більш надійний API для тисяч файлів.
Як верифікувати коректність завантаження?
Після завантаження важливо перевірити доступність CID через публічні шлюзи: ipfs.io/ipfs/{CID}, cloudflare-ipfs.com/ipfs/{CID}, gateway.pinata.cloud/ipfs/{CID}. Якщо файл доступний через 2 з 3 gateway протягом 30 хвилин — завантаження успішне. Обов'язково перевірте метадані перед встановленням baseURI в контракті.
Найкращі практики
Розділяйте зображення та метадані за CID — це полегшує аудит та дає гнучкість для reveal-стратегій. Завантажуємо зображення окремо, отримуємо 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.
Що входить у роботу
- Аналіз вашого проєкту та вибір оптимального провайдера зберігання (NFT.Storage / Pinata / web3.storage).
- Розробка скриптів батч-завантаження для зображень та метаданих.
- Налаштування API-ключів та верифікація CID.
- Інтеграція смарт-контракту: встановлення baseURI, renounceOwnership.
- Документація з покроковими інструкціями для повторного використання.
- Технічна підтримка на час завантаження колекції (1-2 дні).
Процес роботи
- Аналітика (кілька годин) — вибір сервісу, оцінка обсягів.
- Розробка upload-скрипту (1 день) — батч-завантаження, верифікація, генерація baseURI.
- Інтеграція з контрактом (1 день) — встановлення URI, тести на тестовій мережі.
- Тестування — перевірка доступності на шлюзах, симуляція mint.
- Деплой — завантаження на мейннет, reveal.
Орієнтири за термінами
Інтеграція як частина розробки NFT-колекції — 1-2 дні. Окремо — кілька годин для досвідченої команди. Вартість інтеграції — від $300, що окупається за рахунок економії на хостингу до $200 на місяць.
Потрібна надійна інтеграція? Замовте інтеграцію під ключ — налаштуємо зберігання, перевіримо CID, проконсультуємо щодо вибору провайдера. Оцініть ваш проєкт прямо зараз: пишіть нам, і ми зробимо пропозицію протягом дня.