🔄IPNS - Handle Mutable Data

Using IPNS to handle mutable data

IPNS (InterPlanetary Name System) is a system that allows you to create mutable pointers to data in the IPFS network. In simpler terms, it's like a dynamic address that always points to the latest version of your content. Using the Lighthouse SDK, you can easily create, publish, fetch, and remove IPNS records.

1. What is IPNS?

Think of IPNS as a dynamic domain name for your content on IPFS. While IPFS hashes are static and change when content changes, IPNS provides a static address that can be updated to point to new content.

2. Basic steps involved

Create an IPNS key
Map the IPNS key with a CID
In case of CID change just update the mapping, the IPNS key remains the same
View the file using: https://gateway.lighthouse.storage/ipns/k51qzi5uqu5dlr99jbwpbli7iqtdd60c8hk0wgrsxyvzu3lhymapd1rn4npdd8/

Step 1: Create a New IPNS Key

const keyResponse = await lighthouse.generateKey(apiKey)
/* Sample response
{
  data: {
    "ipnsName": "6cda213e3a534f8388665dee77a26458",
    "ipnsId": "k51qzi5uqu5dm6uvby6428rfpcv1vcba6hxq6vcu52qtfsx3np4536jkr71gnu"
  }
}
*/

Upon successful creation, you will receive an IPNS name and its corresponding ID.

Step 2: Publish an IPFS Hash to IPNS

const pubResponse = await lighthouse.publishRecord(
  "YOUR_IPFS_HASH", // replace with your IPFS hash
  keyResponse.data.ipnsName,
  apiKey
)
/* Sample response
{
  data: {
    "Name": "k51qzi5uqu5dm6uvby6428rfpcv1vcba6hxq6vcu52qtfsx3np4536jkr71gnu",
    "Value": "/ipfs/Qmd5MBBScDUV3Ly8qahXtZFqyRRfYSmUwEcxpYcV4hzKfW"
  }
}
*/

The response will show the IPNS name and the IPFS path it points to.

Step 3: Retrieve All IPNS Keys

const allKeys = await lighthouse.getAllKeys(apiKey)
/* Sample response
{
  data: [
    {
      "ipnsName": "6cda213e3a534f8388665dee77a26458",
      "ipnsId": "k51qzi5uqu5dm6uvby6428rfpcv1vcba6hxq6vcu52qtfsx3np4536jkr71gnu",
      "publicKey": "0xc88c729ef2c18baf1074ea0df537d61a54a8ce7b",
      "cid": "Qmd5MBBScDUV3Ly8qahXtZFqyRRfYSmUwEcxpYcV4hzKfW",
      "lastUpdate": 1684855771773
    }
  ]
}
*/

Step 4: Remove an IPNS Key

const pubResponse = await lighthouse.publishRecord("YOUR_IPFS_HASH",ipns_name,apiKey)

Step 5: Update an IPNS Key

const removeRes = await lighthouse.removeKey(keyResponse.data.ipnsName, apiKey)
/* Sample Response
{
  data: { 
    Keys: [
      {
        "Name": "3090a315e92c495ea36444f2bbaeefaf",
        "Id": "k51qzi5uqu5dm8gfelll8own1epd9osmlig49il5mmphkrcxbnhydkmx101x15"
      }
    ]
  }
}
*/

# Generate Key
curl -H 'Authorization: Bearer API_KEY' 'https://api.lighthouse.storage/api/ipns/generate_key'

# Publish CID
curl -H 'Authorization: Bearer API_KEY' 'https://api.lighthouse.storage/api/ipns/publish_record?cid=<cid>&keyName=<key>'

# Get All Keys
curl -H 'Authorization: Bearer API_KEY' 'https://api.lighthouse.storage/api/ipns/get_ipns_records'

# Remove Key
curl -H 'Authorization: Bearer API_KEY' 'https://api.lighthouse.storage/api/ipns/remove_key?keyName=<keyName>'

lighthouse-web3 ipns --generate-key
#Returns:
#ipnsName: ca9e19dcf8e54e86a4dce40b155ffcad
#ipnsId: k51qzi5uqu5dlk72k0t8c80gg8c4lb9bzd0jsd9xtauso88hfkx9ytgm05caao

lighthouse-web3 ipns --publish --key=ca9e19dcf8e54e86a4dce40b155ffcad --cid=QmWC9AkGa6vSbR4yizoJrFMfmZh4XjZXxvRDknk2LdJffc
#Returns:
#Published:
#Visit: https://gateway.lighthouse.storage/ipns/k51qzi5uqu5dlk72k0t8c80gg8c4lb9bzd0jsd9xtauso88hfkx9ytgm05caao

lighthouse-web3 ipns --list
#Returns:
#List of ipns records:
#  Key:     ca9e19dcf8e54e86a4dce40b155ffcad
#  IPNS ID: k51qzi5uqu5dlk72k0t8c80gg8c4lb9bzd0jsd9xtauso88hfkx9ytgm05caao
#  CID:     QmWC9AkGa6vSbR4yizoJrFMfmZh4XjZXxvRDknk2LdJffc
  
lighthouse-web3 ipns --remove ca9e19dcf8e54e86a4dce40b155ffcad
#Returns:
#Record Removed!!!

Step 1: Create a New IPNS Key

from lighthouseweb3 import Lighthouse

lh = Lighthouse(token="YOUR_API_KEY")
key_response = lh.generateKey()

print(key_response)
# Sample response
# {
#   'data': {
#     'ipnsName': '6cda213e3a534f8388665dee77a26458',
#     'ipnsId': 'k51qzi5uqu5dm6uvby6428rfpcv1vcba6hxq6vcu52qtfsx3np4536jkr71gnu'
#   }
# }

Upon successful creation, you will receive an IPNS name and its corresponding ID.

Step 2: Publish an IPFS Hash to IPNS

ipfs_hash = "YOUR_IPFS_HASH"
pub_response = lh.publishRecord(cid=ipfs_hash, keyName=key_response['data']['ipnsName'])

print(pub_response)
# Sample response
# {
#   'data': {
#     'Name': 'k51qzi5uqu5dm6uvby6428rfpcv1vcba6hxq6vcu52qtfsx3np4536jkr71gnu',
#     'Value': '/ipfs/Qmd5MBBScDUV3Ly8qahXtZFqyRRfYSmUwEcxpYcV4hzKfW'
#   }
# }

The response will show the IPNS name and the IPFS path it points to.

Step 3: Retrieve All IPNS Keys

all_keys = lh.getAllKeys()

print(all_keys)
# Sample response
# {
#   'data': [
#     {
#       'ipnsName': '6cda213e3a534f8388665dee77a26458',
#       'ipnsId': 'k51qzi5uqu5dm6uvby6428rfpcv1vcba6hxq6vcu52qtfsx3np4536jkr71gnu',
#       'publicKey': '0xc88c729ef2c18baf1074ea0df537d61a54a8ce7b',
#       'cid': 'Qmd5MBBScDUV3Ly8qahXtZFqyRRfYSmUwEcxpYcV4hzKfW',
#       'lastUpdate': 1684855771773
#     }
#   ]
# }

Step 4: Update an IPNS Key

To update an IPNS key, simply publish a new CID to the same IPNS name:

new_ipfs_hash = "NEW_IPFS_HASH"
pub_response = lh.publishRecord(cid=new_ipfs_hash, keyName=key_response['data']['ipnsName'])

print(pub_response)

Step 5: Remove an IPNS Key

remove_response = lh.removeKey(keyName=key_response['data']['ipnsName'])

print(remove_response)
# Sample Response
# {
#   'data': { 
#     'Keys': [
#       {
#         'Name': '3090a315e92c495ea36444f2bbaeefaf',
#         'Id': 'k51qzi5uqu5dm8gfelll8own1epd9osmlig49il5mmphkrcxbnhydkmx101x15'
#       }
#     ]
#   }
# }

Step 1: Create a New IPNS Key

package main

import (
    "context"
    "fmt"
    "log"
    "os"

    "github.com/lighthouse-web3/lighthouse-go-sdk/lighthouse"
)

func main() {
    client := lighthouse.NewClient(nil,
        lighthouse.WithAPIKey(os.Getenv("LIGHTHOUSE_API_KEY")),
    )

    ctx := context.Background()

    // Generate a new IPNS key
    k, err := client.IPNS().GenerateKey(ctx, "my-key")
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("IPNS Name: %s\n", k.IPNSName)
    fmt.Printf("IPNS ID: %s\n", k.IPNSId)
}

Upon successful creation, you will receive an IPNS name and its corresponding ID.

Step 2: Publish an IPFS Hash to IPNS

// Publish a CID to the key (use k.IPNSName, not the original keyName)
pub, err := client.IPNS().PublishRecord(ctx, "YOUR_IPFS_HASH", k.IPNSName)
if err != nil {
    log.Fatal(err)
}
fmt.Printf("IPNS Name: %s\n", pub.Name)
fmt.Printf("IPFS Path: %s\n", pub.Value)

The response will show the IPNS name and the IPFS path it points to.

Step 3: Retrieve All IPNS Keys

// List all IPNS keys
keys, err := client.IPNS().ListKeys(ctx)
if err != nil {
    log.Fatal(err)
}
fmt.Printf("Total keys: %d\n", len(keys))
for _, key := range keys {
    fmt.Printf("IPNS Name: %s, IPNS ID: %s\n", key.IPNSName, key.IPNSId)
}

Step 4: Update an IPNS Key

To update an IPNS key, simply publish a new CID to the same IPNS name:

// Update the IPNS key to point to a new CID
pub, err := client.IPNS().PublishRecord(ctx, "NEW_IPFS_HASH", k.IPNSName)
if err != nil {
    log.Fatal(err)
}
fmt.Printf("Updated IPNS: %s -> %s\n", pub.Name, pub.Value)

Step 5: Remove an IPNS Key

// Remove a key (use k.IPNSName, not the original keyName)
_, err = client.IPNS().RemoveKey(ctx, k.IPNSName)
if err != nil {
    log.Fatal(err)
}
fmt.Println("IPNS key removed successfully")

PreviousCheck for Filecoin Deals NextMigrations

Last updated 1 month ago

Was this helpful?