Helia
    Preparing search index...

    Module index

    IPNS operations using a Helia node

    With IPNSRouting routers:

    import { createHelia } from 'helia'
    import { ipns } from '@helia/ipns'
    import { unixfs } from '@helia/unixfs'
    import { generateKeyPair } from '@libp2p/crypto/keys'

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

    // create a keypair to publish an IPNS name
    const privateKey = await generateKeyPair('Ed25519')

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

    // publish the name
    await name.publish(privateKey, cid)

    // resolve the name
    const result = await name.resolve(privateKey.publicKey)

    console.info(result.cid, result.path)

    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'
    import { generateKeyPair } from '@libp2p/crypto/keys'

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

    // create a keypair to publish an IPNS name
    const privateKey = await generateKeyPair('Ed25519')

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

    // publish the name
    await name.publish(privateKey, cid)

    // create another keypair to re-publish the original record
    const recursivePrivateKey = await generateKeyPair('Ed25519')

    // publish the recursive name
    await name.publish(recursivePrivateKey, privateKey.publicKey)

    // resolve the name recursively - it resolves until a CID is found
    const result = await name.resolve(recursivePrivateKey.publicKey)
    console.info(result.cid.toString() === cid.toString()) // true

    It is possible to publish CIDs with an associated path.

    import { createHelia } from 'helia'
    import { ipns } from '@helia/ipns'
    import { unixfs } from '@helia/unixfs'
    import { generateKeyPair } from '@libp2p/crypto/keys'

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

    // create a keypair to publish an IPNS name
    const privateKey = await generateKeyPair('Ed25519')

    // 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
    await name.publish(privateKey, `/ipfs/${finalDirCid}/foo.txt`)

    // resolve the name
    const result = await name.resolve(privateKey.publicKey)

    console.info(result.cid, result.path) // QmFoo.. 'foo.txt'

    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 { createHelia, libp2pDefaults } from 'helia'
    import { ipns } from '@helia/ipns'
    import { pubsub } from '@helia/ipns/routing'
    import { unixfs } from '@helia/unixfs'
    import { gossipsub } from '@chainsafe/libp2p-gossipsub'
    import { generateKeyPair } from '@libp2p/crypto/keys'
    import type { Libp2p, PubSub } from '@libp2p/interface'
    import type { DefaultLibp2pServices } from 'helia'

    const libp2pOptions = libp2pDefaults()
    libp2pOptions.services.pubsub = gossipsub()

    const helia = await createHelia<Libp2p<DefaultLibp2pServices & { pubsub: PubSub }>>({
    libp2p: libp2pOptions
    })
    const name = ipns(helia, {
    routers: [
    pubsub(helia)
    ]
    })

    // create a keypair to publish an IPNS name
    const privateKey = await generateKeyPair('Ed25519')

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

    // publish the name
    await name.publish(privateKey, cid)

    // resolve the name
    const result = await name.resolve(privateKey.publicKey)

    To use custom resolvers, configure Helia's dns option:

    import { createHelia } from 'helia'
    import { ipns } from '@helia/ipns'
    import { dns } from '@multiformats/dns'
    import { dnsOverHttps } from '@multiformats/dns/resolvers'
    import { helia } from '@helia/ipns/routing'

    const node = await createHelia({
    dns: dns({
    resolvers: {
    '.': dnsOverHttps('https://private-dns-server.me/dns-query')
    }
    })
    })
    const name = ipns(node, {
    routers: [
    helia(node.routing)
    ]
    })

    const result = name.resolveDNSLink('some-domain-with-dnslink-entry.com')

    Example: Resolving a domain with a dnslink entry

    Calling resolveDNSLink with the @helia/ipns instance:

    // resolve a CID from a TXT record in a DNS zone file, using the default
    // resolver for the current platform eg:
    // > dig _dnslink.ipfs.io TXT
    // ;; ANSWER SECTION:
    // _dnslink.ipfs.io. 60 IN TXT "dnslink=/ipns/website.ipfs.io"
    // > dig _dnslink.website.ipfs.io TXT
    // ;; ANSWER SECTION:
    // _dnslink.website.ipfs.io. 60 IN TXT "dnslink=/ipfs/QmWebsite"

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

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

    const { answer } = await name.resolveDNSLink('ipfs.io')

    console.info(answer)
    // { data: '/ipfs/QmWebsite' }

    This example uses the Mozilla provided RFC 1035 DNS over HTTPS service. This uses binary DNS records so requires extra dependencies to process the response which can increase browser bundle sizes.

    If this is a concern, use the DNS-JSON-Over-HTTPS resolver instead.

    import { createHelia } from 'helia'
    import { ipns } from '@helia/ipns'
    import { dns } from '@multiformats/dns'
    import { dnsOverHttps } from '@multiformats/dns/resolvers'

    const node = await createHelia({
    dns: dns({
    resolvers: {
    '.': dnsOverHttps('https://mozilla.cloudflare-dns.com/dns-query')
    }
    })
    })
    const name = ipns(node)

    const result = await name.resolveDNSLink('ipfs.io')

    DNS-JSON-Over-HTTPS resolvers use the RFC 8427 application/dns-json and can result in a smaller browser bundle due to the response being plain JSON.

    import { createHelia } from 'helia'
    import { ipns } from '@helia/ipns'
    import { dns } from '@multiformats/dns'
    import { dnsJsonOverHttps } from '@multiformats/dns/resolvers'

    const node = await createHelia({
    dns: dns({
    resolvers: {
    '.': dnsJsonOverHttps('https://mozilla.cloudflare-dns.com/dns-query')
    }
    })
    })
    const name = ipns(node)

    const result = await name.resolveDNSLink('ipfs.io')

    The republishRecord method allows you to republish an existing IPNS record without needing the private key. This is useful for relay nodes or when you want to extend the availability of a record that was created elsewhere.

    import { createHelia } from 'helia'
    import { ipns } from '@helia/ipns'
    import { createDelegatedRoutingV1HttpApiClient } from '@helia/delegated-routing-v1-http-api-client'
    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 = createDelegatedRoutingV1HttpApiClient('https://delegated-ipfs.dev')
    const record = await delegatedClient.getIPNS(parsedCid)

    await name.republishRecord(ipnsName, record)

    Interfaces

    DNSLinkResolveResult
    IPNS
    IPNSComponents
    IPNSOptions
    IPNSResolveResult
    PublishOptions
    RepublishOptions
    RepublishRecordOptions
    ResolveDNSLinkOptions
    ResolveOptions
    ResolveResult

    Type Aliases

    IPNSRecord
    PublishProgressEvents
    RepublishProgressEvents
    ResolveDNSLinkProgressEvents
    ResolveProgressEvents

    Functions

    ipns
    ipnsSelector
    ipnsValidator

    References

    IPNSRouting → IPNSRouting
    IPNSRoutingEvents → IPNSRoutingEvents