Интеграция с 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 для persistence
IPFS сам по себе не гарантирует хранение: если ни один узел не пинит файл, он исчезает. NFT.Storage автоматически создаёт Filecoin deals для загруженных данных — децентрализованное долгосрочное хранение с cryptographic proof of storage. Это отличие от простого 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 upload — более надёжный 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 дня. Отдельно — несколько часов для опытной команды.