IPNS — Nomes Mutaveis para IPFS

IPNS (InterPlanetary Name System) oferece endereços estaveis e compartilhaveis que podem ser atualizados para apontar para conteúdo diferente ao longo do tempo. Enquanto os CIDs do IPFS mudam toda vez que o conteúdo muda, um nome IPNS permanece o mesmo — você apenas atualiza para onde ele aponta.

Disponivel nós planos Bodhi (3 nomes, 100 publicações/mes) e Nirvana (10 nomes, 1.000 publicações/mes).

Saiba mais sobre IPNS

Para um aprofundamento sobre como o IPNS funciona no nível do protocolo, consulte a documentação oficial do IPFS sobre IPNS.

Por que usar IPNS?

O problema: Toda vez que você faz upload de uma nova versão de um arquivo para o IPFS, você recebe um CID diferente. Se você compartilhou o CID antigo com usuarios, eles ainda veem o conteúdo antigo. Você teria que compartilhar um novo link toda vez.

A solução: Crie um nome IPNS uma vez, compartilhe-o é atualizatualize para onde ele aponta sempre que seu conteúdo mudar. Qualquer pessoa com o endereço IPNS sempre recebe a versão mais recente.

Casos de uso comuns

• Sites no IPFS — Implante seu site, obtenha um CID, publique-o no seu nome IPNS. Reimplante -> novo CID -> atualize o nome IPNS. A URL nunca muda.
• Metadados NFT que evoluem — Aponte o tokenURI do seu NFT para um endereço IPNS. Atualize os metadados (ex.: item de jogo sobe de nível) sem alterar o contrato inteligente.
• Arquivos de configuração — Sua aplicação le a configuração de um endereço IPNS. Atualize a configuração sem reimplantar a aplicação.
• Feeds de dados — Publique conjuntos de dados diarios ou feeds de preços sob um endereço IPNS estavel.
• DNSLink — Conecte seu dominio ao IPNS para que https://seudominio.com sempre sirva o conteúdo IPFS mais recente.

Usando o Painel de Controle

1. Criar um nome IPNS

1. Va até IPNS na barra lateral em Hosting.
2. Clique em Criar nome.
3. Digite um rótulo (ex.: "meu-site") e clique em Criar.
4. Copie o endereço IPNS (começa com k51...) — este e seu endereço permanente e compartilhavel.

2. Publicar um CID no seu nome IPNS

1. Encontre o nome IPNS na lista e clique em Publicar.
2. Digite o CID para o qual deseja que aponte (ex.: QmXk7VRz... ou bafybei...).
3. Clique em Publicar. Isso se propaga pela rede IPFS e pode levar até 60 segundos.
4. Uma vez publicado, o conteúdo é acessacessível em:
   • Gateway IPFS: https://ipfs.ninja/ipns/{seu-nome-ipns}
   • Qualquer gateway público: https://dweb.link/ipns/{seu-nome-ipns}
   • IPFS nativo: ipns://{seu-nome-ipns}

3. Atualizar seu conteúdo

Quando seu conteúdo muda:

1. Faça upload da nova versão para o IPFS (via painel de controle ou API) -> obtenha um novo CID.
2. Volte ao IPNS, clique em Publicar no mesmo nome, digite o novo CID.
3. O endereço IPNS permanece o mesmo — qualquer pessoa que o use automaticamente recebe o novo conteúdo.

4. Resolver um nome IPNS

Use a seção Resolver na parte inferior da página para consultar o CID atual de qualquer nome IPNS — o seu ou de qualquer outra pessoa.

5. Excluir um nome IPNS

Clique no botão de excluir ao lado de qualquer nome. O registro IPNS expirara da rede dentro de 48 horas.

Conectando um Dominio com DNSLink

Você pode apontar seu próprio nome de dominio para um endereço IPNS usando DNSLink. Isso permite que os usuarios acessem seu conteúdo IPFS através de uma URL regular como https://seudominio.com.

Como configurar DNSLink

1. Crie um nome IPNS e publique o CID do seu conteúdo nele (passos acima).

2. Adicione um registro DNS TXT no provedor DNS do seu dominio:

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

   Exemplo: Se seu nome IPNS for k51qzi5uqu5djcpbukxs...:

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

3. Verifique o registro usando dig ou nslookup:

   dig +short TXT _dnslink.myapp.com
   # Deve retornar: "dnslink=/ipns/k51qzi5uqu5djcpbukxs..."

4. Acesse via qualquer gateway IPFS que suporte DNSLink:

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

   Ou via um navegador com suporte IPFS (como Brave):

   ipns://myapp.com

Propagação DNS

Alterações de DNS podem levar até 24 horas para se propagar globalmente. Após adicionar o registro TXT, aguarde algumas horas antes de testar.

TIP

Você só precisa configurar o DNSLink uma vez. Quando você pública um novo CID no seu nome IPNS, o dominio automaticamente resolve para o novo conteúdo — nenhuma alteração DNS necessária.

DNSLink com Cloudflare

Se você usa Cloudflare:

1. Va até DNS -> Records.
2. Adicione um novo registro: Tipo: TXT, Nome: _dnslink, Conteúdo: dnslink=/ipns/k51...
3. Defina o status do proxy para Somente DNS (nuvem cinza).

DNSLink com Route 53

1. Va até sua zona hospedada no Route 53.
2. Crie um registro: Nome: _dnslink.yourdomain.com, Tipo: TXT, Valor: "dnslink=/ipns/k51..."

Exemplos de Uso

Exemplo 1: Implantação de site estático

# 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

Exemplo 2: Metadados NFT mutaveis

// 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 })
});

Exemplo 3: Integração 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"'"}'

Referência da API

Todos os exemplos da API usam o cabeçalho X-Api-Key. Obtenha sua chave API na página de Chaves API.

Listar Chaves IPNS

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

Resposta:

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

Criar Chave 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"}'

Resposta 201:

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

Publicar no IPNS

Publicar atualiza o nome IPNS para apontar para um novo CID. Isso se propaga pelo DHT do IPFS e pode levar até 60 segundos.

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"}'

Resposta:

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

Resolver Nome IPNS

Consulte o CID atual de qualquer nome IPNS.

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

Resposta:

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

Excluir Chave IPNS

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

Resposta:

{ "success": true }

Como o IPNS Funciona

1. Geracao de chaves: Quando você cria um nome IPNS, um par de chaves criptográficas (Ed25519) e gerado. O hash da chave pública se torna seu endereço IPNS (k51...).
2. Publicação: Quando você pública, assina um registro dizendo "este nome aponta para o CID X" é o transmite para o DHT do IPFS (Tabela Hash Distribuida).
3. Resolução: Quando alguem consulta seu nome IPNS, os nós IPFS consultam o DHT para obter o registro assinado mais recente e seguem o link até o CID.
4. Republicacao: Os registros IPNS expiram após 48 horas. O IPFS Ninja republica automaticamente seus registros a cada 12 horas para mante-los ativos.
5. Segurança: Apenas o detentor da chave privada (você) pode atualizar para onde um nome IPNS aponta. Ninguem mais pode sequestrar seu nome.

Limites do Plano

Plano	Nomes IPNS	Publicações / Mes
Dharma (Gratuito)	Não disponível	—
Bodhi ($5/mes)	3	100
Nirvana ($29/mes)	10	1.000

• Os registros são republicados automaticamente a cada 12 horas para mante-los ativos na rede IPFS.
• Nomes não publicados por 90 dias são marcados como inativos e param de ser republicados.
• Nomes inativos podem ser reativados publicando um novo CID neles.

Leitura Adicional

• Conceitos IPNS — Documentação IPFS — Documentação oficial sobre como o IPNS funciona no nível do protocolo
• DNSLink — Documentação IPFS — Conectando nomes de dominio a conteúdo IPFS/IPNS
• Endereçamento por Conteúdo — Entendendo os CIDs e por que o IPNS resolve o problema da mutabilidade