Представьте: вы запустили 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 (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 сервисах. Это минимизирует риск потери данных.
| Сервис | Бесплатный лимит | Репликация 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 дня. Отдельно — несколько часов для опытной команды.
Нужна надёжная интеграция? Свяжитесь с нами — настроим хранение, проверим CID, проконсультируем по выбору провайдера. Закажите интеграцию уже сегодня.