8.0.0 • Published 9 months ago

@helia/ipns v8.0.0

Weekly downloads
-
License
Apache-2.0 OR MIT
Repository
github
Last release
9 months ago

@helia/ipns

ipfs.tech Discuss codecov CI

An implementation of IPNS for Helia

About

IPNS operations using a Helia node

Example - Getting started

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)

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

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

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 { 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)

Example - Using custom DNS over HTTPS resolvers

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

Example - Using DNS-Over-HTTPS

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')

Example - Using DNS-JSON-Over-HTTPS

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')

Install

$ npm i @helia/ipns

Browser <script> tag

Loading this module through a script tag will make its exports available as HeliaIpns in the global namespace.

<script src="https://unpkg.com/@helia/ipns/dist/index.min.js"></script>

API Docs

License

Licensed under either of

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.

npm.io

8.0.0-dff82ec

9 months ago

8.0.0-0238ed4

9 months ago

8.0.0-23ebae1

9 months ago

8.0.0-efc47fa

9 months ago

8.0.0-693c82d

9 months ago

8.0.0-8364296

9 months ago

8.0.0-460853f

9 months ago

8.0.0-1b2934b

9 months ago

7.2.3-bc64f47

9 months ago

7.2.3-efdefc1

9 months ago

7.2.3-60d8c8a

9 months ago

7.2.3-2f88fc8

9 months ago

8.0.0

9 months ago

7.2.3-c04dbf5

10 months ago

7.2.3-ec8bf66

10 months ago

7.2.2-5fab3a3

1 year ago

7.2.2-117198f

1 year ago

7.2.3-f5a03fc

10 months ago

7.2.3-4f14996

10 months ago

7.2.3-acd876b

10 months ago

7.2.3-8805202

10 months ago

7.2.3-ac4bdb8

11 months ago

7.2.2-74ccc92

1 year ago

7.2.2-62f77df

1 year ago

7.2.2-461d219

12 months ago

7.2.3-3bf5ab0

10 months ago

7.2.2-e6bca0b

1 year ago

7.2.2-5643b1d

12 months ago

7.2.3-5ff6998

10 months ago

7.2.3

12 months ago

7.2.2-011fa92

1 year ago

7.2.3-e567717

10 months ago

7.2.2-3577d3d

1 year ago

7.2.3-c9c644c

10 months ago

7.2.2-f16c9ea

12 months ago

7.2.2-b4877b5

1 year ago

7.2.3-9de08ef

10 months ago

7.2.2-155e24d

1 year ago

7.2.3-23e62e1

10 months ago

7.2.2-6952f05

12 months ago

7.2.2-21ef20c

1 year ago

7.2.2-f46700f

1 year ago

7.2.2-e6b976a

1 year ago

7.2.2-9fa2427

1 year ago

7.2.2-a8fdfc2

1 year ago

7.2.2-55b9650

1 year ago

7.2.1-b0d50e9

1 year ago

7.2.2

1 year ago

7.2.1-7419dfc

1 year ago

7.2.1-fa9bd4b

1 year ago

7.2.1-6a62d1c

1 year ago

7.2.1-36081e0

1 year ago

7.2.1-2d070b9

1 year ago

7.2.1-e4e67d0

1 year ago

7.2.1-361fbd3

1 year ago

7.2.1-0a528bb

1 year ago

7.2.1-f6bcbd4

1 year ago

7.2.1-52dbcf2

1 year ago

7.2.1-f7f71bb

1 year ago

7.2.1-5e98950

1 year ago

7.2.1-0ecb529

1 year ago

7.2.1-5d62dfb

1 year ago

7.2.1-338885f

1 year ago

7.2.1-59de059

1 year ago

7.2.0-9ea934e

1 year ago

7.2.0-9c8a2c0

1 year ago

7.2.0-5323724

1 year ago

7.2.1

1 year ago

7.2.0-ba4b7ba

1 year ago

7.2.0-b67ac5f

1 year ago

7.2.0-b1c761d

1 year ago

7.2.0-395cd9e

1 year ago

7.2.0-532d6c4

1 year ago

7.2.0-7cd012a

1 year ago

7.2.0-e582c63

1 year ago

7.2.0-329652a

1 year ago

7.1.0-1561e4a

1 year ago

7.2.0-6ddefb0

1 year ago

7.2.0

1 year ago

7.2.0-5cf216b

1 year ago

7.1.0-9ac5909

1 year ago

7.1.0-d1c497b

1 year ago

7.1.0

1 year ago

7.0.0-b6765fe

1 year ago

7.0.0

1 year ago

7.0.0-ecf5394

1 year ago

6.0.1-adc5589

1 year ago

6.0.1-a0d651c

1 year ago

6.0.1-2c71b6e

1 year ago

6.0.1-8c9bb7d

1 year ago

6.0.1-a64e5de

1 year ago

6.0.1-c69913c

1 year ago

6.0.1-90c6feb

1 year ago

6.0.0-c3f2ed1

1 year ago

6.0.0-6f8c15b

1 year ago

6.0.0-77e34fc

1 year ago

6.0.1

1 year ago

6.0.0-1319c61

1 year ago

6.0.0-917a1bc

1 year ago

6.0.0-1ee6a4a

1 year ago

6.0.0-2d965be

1 year ago

6.0.0-7c3ce21

1 year ago

6.0.0-dc2e7a6

1 year ago

6.0.0-28d62f7

1 year ago

6.0.0-7c07e11

1 year ago

6.0.0-a04e041

1 year ago

6.0.0-754c7af

1 year ago

6.0.0-8db7792

1 year ago

6.0.0-31cdfa8

1 year ago

6.0.0-75d0a5b

1 year ago

6.0.0-9b1ddf8

1 year ago

6.0.0-7a7c0c1

1 year ago

6.0.0-3283a5c

1 year ago

6.0.0-f58d467

1 year ago

6.0.0-3851fe2

1 year ago

6.0.0-5c0c39c

1 year ago

6.0.0-6c88ee1

1 year ago

6.0.0-f243de2

1 year ago

6.0.0-8a5bc6f

1 year ago

6.0.0

1 year ago

5.0.0-ca8d5eb

1 year ago

5.0.0-e554493

1 year ago

5.0.0-94b0cd1

1 year ago

5.0.0-44f4e88

1 year ago

5.0.0

1 year ago

4.0.0-99c94f4

1 year ago

4.0.0-4836d52

1 year ago

4.0.0-db7d091

1 year ago

4.0.0-19bf9ce

1 year ago

4.0.0-031519c

1 year ago

4.0.0-4943c5b

1 year ago

4.0.0-f2853f8

1 year ago

4.0.0-163df38

1 year ago

4.0.0-a2229bd

1 year ago

4.0.0-3477b27

1 year ago

4.0.0-a966706

1 year ago

4.0.0-843fba4

1 year ago

4.0.0-ce74026

1 year ago

4.0.0-76220cd

1 year ago

4.0.0-5a87bbd

1 year ago

4.0.0-ece384a

1 year ago

4.0.0-5c6a066

1 year ago

4.0.0-5c4fd54

2 years ago

4.0.0-3f4c6bf

2 years ago

4.0.0-10272b4

2 years ago

4.0.0

2 years ago

4.0.0-a0692f9

2 years ago

3.0.1

2 years ago

3.0.0

2 years ago

1.1.7

2 years ago

1.1.6

2 years ago

1.1.5

2 years ago

1.1.4

2 years ago

2.0.3

2 years ago

2.0.2

2 years ago

2.0.1

2 years ago

2.0.0

2 years ago

1.1.1

2 years ago

1.1.3

2 years ago

1.1.2

2 years ago

1.1.0

2 years ago

1.0.1

2 years ago

1.0.0

2 years ago

0.0.0

2 years ago