Module @helia/ipns

Example: Getting started

With IPNSRouting routers:

import { createHelia } from 'helia'
import { ipns } from '@helia/ipns'
import { unixfs } from '@helia/unixfs'

const helia = await createHelia()
const name = ipns(helia)

// store some data to publish
const fs = unixfs(helia)
const cid = await fs.addBytes(Uint8Array.from([0, 1, 2, 3, 4]))

// publish the name
const { publicKey } = await name.publish('key-1', cid)

// resolve the name
for await (const result of name.resolve(publicKey)) {
  console.info(result.record.value) // /ipfs/QmFoo
}
Copy

Example: Publishing a recursive record

A recursive record is a one that points to another record rather than to a value.

import { createHelia } from 'helia'
import { ipns } from '@helia/ipns'
import { unixfs } from '@helia/unixfs'

const helia = await createHelia()
const name = ipns(helia)

// store some data to publish
const fs = unixfs(helia)
const cid = await fs.addBytes(Uint8Array.from([0, 1, 2, 3, 4]))

// publish the name
const { publicKey } = await name.publish('key-1', cid)

// publish the recursive name
const { publicKey: recursivePublicKey } = await name.publish('key-2', publicKey)

// resolve the name recursively - it resolves until a CID is found
for await (const result of name.resolve(recursivePublicKey)) {
  console.info(result.record.value) // /ipfs/QmFoo../foo.txt
}
Copy

Example: Publishing a record with a path

It is possible to publish CIDs with an associated path.

import { createHelia } from 'helia'
import { ipns } from '@helia/ipns'
import { unixfs } from '@helia/unixfs'

const helia = await createHelia()
const name = ipns(helia)

// store some data to publish
const fs = unixfs(helia)
const fileCid = await fs.addBytes(Uint8Array.from([0, 1, 2, 3, 4]))

// store the file in a directory
const dirCid = await fs.addDirectory()
const finalDirCid = await fs.cp(fileCid, dirCid, '/foo.txt')

// publish the name
const { publicKey } = await name.publish('key-1', `/ipfs/${finalDirCid}/foo.txt`)

// resolve the name
for await (const result of name.resolve(publicKey)) {
  console.info(result.record.value) // /ipfs/QmFoo../foo.txt
}
Copy

Example: Using custom PubSub router

Additional IPNS routers can be configured - these enable alternative means to publish and resolve IPNS names.

One example is the PubSub router - this requires an instance of Helia with libp2p PubSub configured.

It works by subscribing to a pubsub topic for each IPNS name that we try to resolve. Updated IPNS records are shared on these topics so an update must occur before the name is resolvable.

This router is only suitable for networks where IPNS updates are frequent and multiple peers are listening on the topic(s), otherwise update messages may fail to be published with "Insufficient peers" errors.

import { ipns, pubSubIPNSRouting } from '@helia/ipns'
import { withLibp2p } from '@helia/libp2p'
import { unixfs } from '@helia/unixfs'
import { fetch } from '@libp2p/fetch'
import { floodsub } from '@libp2p/floodsub'
import { createHelia } from 'helia'

const helia = await withLibp2p(createHelia(), {
  services: {
    fetch: fetch(),
    pubsub: floodsub()
  }
}).start()

const name = ipns(helia, {
  routers: [
    pubSubIPNSRouting(helia)
  ]
})

// store some data to publish
const fs = unixfs(helia)
const cid = await fs.addBytes(Uint8Array.from([0, 1, 2, 3, 4]))

// publish the name
const { publicKey } = await name.publish('key-1', cid)

// resolve the name
for await (const result of name.resolve(publicKey)) {
  console.info(result.record.value)
}
Copy

Example: Republishing an existing IPNS record

It is sometimes useful to be able to republish an existing IPNS record without needing the private key. This allows you to extend the availability of a record that was created elsewhere.

There should be only one republisher per IPNS key. Multiple machines republishing the same key flood the routers with redundant writes.

import { createHelia } from 'helia'
import { ipns } from '@helia/ipns'
import { delegatedRoutingV1HttpApiClient } from '@helia/delegated-routing-v1-http-api-client'
import { defaultLogger } from 'birnam'
import { CID } from 'multiformats/cid'

const helia = await createHelia()
const name = ipns(helia)

const ipnsName = 'k51qzi5uqu5dktsyfv7xz8h631pri4ct7osmb43nibxiojpttxzoft6hdyyzg4'
const parsedCid: CID<unknown, 114, 0 | 18, 1> = CID.parse(ipnsName)
const delegatedClient = delegatedRoutingV1HttpApiClient({
  url: 'https://delegated-ipfs.dev'
})({
  logger: defaultLogger()
})
const record = await delegatedClient.getIPNS(parsedCid)

// import the record into the local store (validates and stores it locally,
// but does not publish it to the routers)
await name.import(parsedCid, record)

// start republishing it; throws RecordObsoleteError if the routers
// already have a newer record for this key
const { record: latestRecord } = await name.republish(parsedCid)

// stop republishing a key
await name.unpublish(parsedCid)
Copy