IPNS — Изменяемые имена для IPFS

IPNS (InterPlanetary Name System) предоставляет вам стабильные, доступные для обмена адреса, которые можно обновлять для указания на различный контент с течением времени. В то время как CID IPFS меняются при каждом изменении контента, имя IPNS остаётся прежним — вы просто обновляете, на что оно указывает.

Доступно в планах Bodhi (3 имени, 100 публикаций/мес.) и Nirvana (10 имён, 1000 публикаций/мес.).

Узнайте больше об IPNS

Для глубокого погружения в работу IPNS на уровне протокола см. официальную документацию IPFS по IPNS.

Зачем использовать IPNS?

Проблема: Каждый раз, когда вы загружаете новую версию файла в IPFS, вы получаете другой CID. Если вы поделились старым CID с пользователями, они по-прежнему видят старый контент. Вам пришлось бы каждый раз делиться новой ссылкой.

Решение: Создайте имя IPNS один раз, поделитесь им и обновляйте, на что оно указывает, когда ваш контент меняется. Любой, у кого есть адрес IPNS, всегда получает последнюю версию.

Распространённые случаи использования

• Веб-сайты на IPFS — Разверните сайт, получите CID, опубликуйте его под именем IPNS. Повторное развёртывание → новый CID → обновите имя IPNS. URL никогда не меняется.
• Эволюционирующие метаданные NFT — Укажите tokenURI вашего NFT на адрес IPNS. Обновляйте метаданные (например, игровой предмет повышает уровень) без изменения смарт-контракта.
• Файлы конфигурации — Ваше приложение читает конфигурацию с адреса IPNS. Обновляйте конфигурацию без повторного развёртывания приложения.
• Потоки данных — Публикуйте ежедневные наборы данных или ценовые каналы под стабильным адресом IPNS.
• DNSLink — Подключите ваш домен к IPNS, чтобы https://yourdomain.com всегда обслуживал последний контент IPFS.

Использование панели управления

1. Создание имени IPNS

1. Перейдите в IPNS в боковой панели раздела Hosting.
2. Нажмите Создать имя.
3. Введите метку (например, "my-website") и нажмите Создать.
4. Скопируйте адрес IPNS (начинается с k51...) — это ваш постоянный, доступный для обмена адрес.

2. Публикация CID под именем IPNS

1. Найдите имя IPNS в списке и нажмите Опубликовать.
2. Введите CID, на который оно должно указывать (например, QmXk7VRz... или bafybei...).
3. Нажмите Опубликовать. Распространение по сети IPFS может занять до 60 секунд.
4. После публикации контент доступен по адресам:
   • Шлюз IPFS: https://ipfs.ninja/ipns/{your-ipns-name}
   • Любой публичный шлюз: https://dweb.link/ipns/{your-ipns-name}
   • Нативный IPFS: ipns://{your-ipns-name}

3. Обновление контента

Когда ваш контент меняется:

1. Загрузите новую версию в IPFS (через панель управления или API) → получите новый CID.
2. Вернитесь в IPNS, нажмите Опубликовать для того же имени, введите новый CID.
3. Адрес IPNS остаётся прежним — любой, кто его использует, автоматически получает новый контент.

4. Разрешение имени IPNS

Используйте раздел Разрешение в нижней части страницы, чтобы узнать текущий CID для любого имени IPNS — вашего или чужого.

5. Удаление имени IPNS

Нажмите кнопку удаления рядом с любым именем. Запись IPNS истечёт из сети в течение 48 часов.

Подключение домена с DNSLink

Вы можете направить своё доменное имя на адрес IPNS с помощью DNSLink. Это позволяет пользователям получать доступ к вашему контенту IPFS через обычный URL, например https://yourdomain.com.

Как настроить DNSLink

1. Создайте имя IPNS и опубликуйте ваш CID контента (шаги выше).

2. Добавьте DNS TXT-запись у вашего DNS-провайдера:

   _dnslink.yourdomain.com  TXT  "dnslink=/ipns/{your-ipns-name}"

   Пример: Если ваше имя IPNS — k51qzi5uqu5djcpbukxs...:

   _dnslink.myapp.com  TXT  "dnslink=/ipns/k51qzi5uqu5djcpbukxs..."

3. Проверьте запись с помощью dig или nslookup:

   dig +short TXT _dnslink.myapp.com
   # Должно вернуть: "dnslink=/ipns/k51qzi5uqu5djcpbukxs..."

4. Доступ через любой шлюз IPFS, поддерживающий DNSLink:

   https://ipfs.ninja/ipns/myapp.com

   Или через браузер с поддержкой IPFS (например, Brave):

   ipns://myapp.com

Распространение DNS

Изменения DNS могут занять до 24 часов для глобального распространения. После добавления TXT-записи подождите несколько часов перед тестированием.

TIP

DNSLink нужно настроить только один раз. Когда вы публикуете новый CID под именем IPNS, домен автоматически разрешается в новый контент — изменения DNS не требуются.

DNSLink с Cloudflare

Если вы используете Cloudflare:

1. Перейдите в DNS → Records.
2. Добавьте новую запись: Тип: TXT, Имя: _dnslink, Содержимое: dnslink=/ipns/k51...
3. Установите статус прокси на Только DNS (серое облако).

DNSLink с Route 53

1. Перейдите в вашу размещённую зону в Route 53.
2. Создайте запись: Имя: _dnslink.yourdomain.com, Тип: TXT, Значение: "dnslink=/ipns/k51..."

Примеры использования

Пример 1: Развёртывание статического сайта

# 1. Build your site
npm run build

# 2. Upload the build output to IPFS
CID=$(curl -s -X POST https://api.ipfs.ninja/upload/new \
  -H "X-Api-Key: bws_your_api_key" \
  -H "Content-Type: application/json" \
  -d "{\"content\": $(cat dist/index.html | base64 -w0 | jq -Rs .), \"description\": \"Website v2.1\"}" \
  | jq -r '.cid')

echo "Uploaded: $CID"

# 3. Update your IPNS name to point to the new build
curl -X POST https://api.ipfs.ninja/ipns/publish \
  -H "X-Api-Key: bws_your_api_key" \
  -H "Content-Type: application/json" \
  -d "{\"ipnsName\": \"k51qzi5uqu5dlvj2bv6...\", \"cid\": \"$CID\"}"

# Your site at ipns://k51... now serves the new version

Пример 2: Изменяемые метаданные NFT

// Smart contract points tokenURI to IPNS address:
// tokenURI = "ipns://k51qzi5uqu5dlvj2bv6..."

// When the NFT evolves (e.g., game item levels up):
const newMetadata = {
  name: "Dragon Sword",
  description: "A legendary weapon — Level 5",
  image: "ipfs://QmNewImageCID...",
  attributes: [
    { trait_type: "Level", value: 5 },
    { trait_type: "Damage", value: 150 }
  ]
};

// Upload new metadata
const uploadRes = await fetch("https://api.ipfs.ninja/upload/new", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-Api-Key": "bws_your_api_key"
  },
  body: JSON.stringify({ content: newMetadata, description: "Dragon Sword v5" })
});
const { cid } = await uploadRes.json();

// Update the IPNS pointer — tokenURI stays the same!
await fetch("https://api.ipfs.ninja/ipns/publish", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-Api-Key": "bws_your_api_key"
  },
  body: JSON.stringify({ ipnsName: "k51qzi5uqu5dlvj2bv6...", cid })
});

Пример 3: Интеграция CI/CD

# GitHub Actions: auto-publish to IPNS on every push
- name: Upload to IPFS and publish IPNS
  run: |
    CID=$(curl -s -X POST https://api.ipfs.ninja/upload/new \
      -H "X-Api-Key: ${{ secrets.IPFS_NINJA_API_KEY }}" \
      -H "Content-Type: application/json" \
      -d '{"content": '"$(cat build/output.json)"', "description": "Deploy ${{ github.sha }}"}' \
      | jq -r '.cid')

    curl -X POST https://api.ipfs.ninja/ipns/publish \
      -H "X-Api-Key: ${{ secrets.IPFS_NINJA_API_KEY }}" \
      -H "Content-Type: application/json" \
      -d '{"ipnsName": "${{ vars.IPNS_NAME }}", "cid": "'"$CID"'"}'

Справочник API

Все примеры API используют заголовок X-Api-Key. Получите свой API-ключ на странице API-ключи.

Список ключей IPNS

curl https://api.ipfs.ninja/ipns/keys \
  -H "X-Api-Key: bws_your_api_key_here"

Ответ:

[
  {
    "ipnsName": "k51qzi5uqu5dlvj2bv6...",
    "keyName": "my-website",
    "currentCid": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
    "lastPublishedAt": 1711123200000,
    "publishCountMonth": 12,
    "status": "active",
    "createdAt": 1711036800000
  }
]

Создать ключ IPNS

curl -X POST https://api.ipfs.ninja/ipns/keys \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-website"}'

Ответ 201:

{
  "ipnsName": "k51qzi5uqu5dlvj2bv6...",
  "keyName": "my-website",
  "createdAt": 1711036800000
}

Публикация в IPNS

Публикация обновляет имя IPNS, чтобы оно указывало на новый CID. Распространяется в IPFS DHT и может занять до 60 секунд.

curl -X POST https://api.ipfs.ninja/ipns/publish \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"ipnsName": "k51qzi5uqu5dlvj2bv6...", "cid": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi"}'

Ответ:

{
  "ipnsName": "k51qzi5uqu5dlvj2bv6...",
  "cid": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
  "published": true
}

Разрешение имени IPNS

Узнайте текущий CID для любого имени IPNS.

curl https://api.ipfs.ninja/ipns/resolve/k51qzi5uqu5dlvj2bv6... \
  -H "X-Api-Key: bws_your_api_key_here"

Ответ:

{
  "ipnsName": "k51qzi5uqu5dlvj2bv6...",
  "cid": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi"
}

Удалить ключ IPNS

curl -X DELETE https://api.ipfs.ninja/ipns/keys/k51qzi5uqu5dlvj2bv6... \
  -H "X-Api-Key: bws_your_api_key_here"

Ответ:

{ "success": true }

Как работает IPNS

1. Генерация ключа: При создании имени IPNS генерируется криптографическая пара ключей (Ed25519). Хеш открытого ключа становится вашим адресом IPNS (k51...).
2. Публикация: При публикации вы подписываете запись «это имя указывает на CID X» и отправляете её в IPFS DHT (Distributed Hash Table).
3. Разрешение: Когда кто-то ищет ваше имя IPNS, узлы IPFS запрашивают DHT на предмет последней подписанной записи и следуют по ней к CID.
4. Перепубликация: Записи IPNS истекают через 48 часов. IPFS Ninja автоматически перепубликует ваши записи каждые 12 часов для поддержания их активности.
5. Безопасность: Только владелец закрытого ключа (вы) может обновить, на что указывает имя IPNS. Никто другой не может захватить ваше имя.

Лимиты планов

План	Имена IPNS	Публикации / месяц
Dharma (Бесплатный)	Недоступно	—
Bodhi ($5/мес.)	3	100
Nirvana ($29/мес.)	10	1 000

• Записи автоматически перепубликуются каждые 12 часов для поддержания активности в сети IPFS.
• Имена, по которым не было публикаций в течение 90 дней, помечаются как неактивные и перестают перепубликовываться.
• Неактивные имена можно реактивировать, опубликовав новый CID.

Дополнительная литература

• Концепции IPNS — Документация IPFS — Официальная документация о работе IPNS на уровне протокола
• DNSLink — Документация IPFS — Подключение доменных имён к контенту IPFS/IPNS
• Адресация по содержимому — Понимание CID и почему IPNS решает проблему изменяемости