@helia/ipns


> An implementation of IPNS for Helia

About

IPNS operations using a Helia node

Example - Getting started

With IPNSRouting routers:

``TypeScript
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
const result = await name.resolve(publicKey)

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

Example - Publishing a recursive record

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

`TypeScript
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)

// 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
const result = await name.resolve(recursivePublicKey)
console.info(result.cid.toString() === cid.toString()) // true
`

Example - Publishing a record with a path

It is possible to publish CIDs with an associated path.

`TypeScript
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)

// 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
const result = await name.resolve(publicKey)

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

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.

`TypeScript
import { createHelia, libp2pDefaults } from 'helia'
import { ipns } from '@helia/ipns'
import { pubsub } from '@helia/ipns/routing'
import { unixfs } from '@helia/unixfs'
import { floodsub } from '@libp2p/floodsub'
import { generateKeyPair } from '@libp2p/crypto/keys'
import type { PubSub } from '@helia/ipns/routing'
import type { Libp2p } from '@libp2p/interface'
import type { DefaultLibp2pServices } from 'helia'

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

const helia = await createHelia>({
libp2p: libp2pOptions
})
const name = ipns(helia, {
routers: [
pubsub(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
const result = await name.resolve(publicKey)
`

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.

`TypeScript
import { createHelia } from 'helia'
import { ipns, ipnsValidator } from '@helia/ipns'
import { delegatedRoutingV1HttpApiClient } from '@helia/delegated-routing-v1-http-api-client'
import { CID } from 'multiformats/cid'
import { multihashToIPNSRoutingKey, marshalIPNSRecord } from 'ipns'
import { defaultLogger } from '@libp2p/logger'

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

const ipnsName = 'k51qzi5uqu5dktsyfv7xz8h631pri4ct7osmb43nibxiojpttxzoft6hdyyzg4'
const parsedCid: CID = CID.parse(ipnsName)
const delegatedClient = delegatedRoutingV1HttpApiClient({
url: 'https://delegated-ipfs.dev'
})({
logger: defaultLogger()
})
const record = await delegatedClient.getIPNS(parsedCid)

const routingKey = multihashToIPNSRoutingKey(parsedCid.multihash)
const marshaledRecord = marshalIPNSRecord(record)

// validate that they key corresponds to the record
await ipnsValidator(routingKey, marshaledRecord)

// publish record to routing
await Promise.all(
name.routers.map(async r => {
await r.put(routingKey, marshaledRecord)
})
)
`

Install

`console
$ npm i @helia/ipns
`

Browser
``

API Docs

-

License

Licensed under either of

- Apache 2.0, (LICENSE-APACHE / )
- MIT (LICENSE-MIT / )

Contribute

Contributions welcome! Please check out the issues.

Also see our contributing document for more information on how we work, and about contributing in general.

Please be aware that all interactions related to this repo are subject to the IPFS Code of Conduct.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.