@helia/ipns 8.2.4 → 9.0.0

package/README.md

@@ -30,7 +30,7 @@ repo and examine the changes made.
 
 -->
 
-IPNS operations using a Helia node
+[IPNS](https://docs.ipfs.tech/concepts/ipns/) operations using a Helia node
 
 ## Example - Getting started
 
@@ -40,23 +40,19 @@ 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)
+const { publicKey } = await name.publish('key-1', cid)
 
 // resolve the name
-const result = await name.resolve(privateKey.publicKey)
+const result = await name.resolve(publicKey)
 
 console.info(result.cid, result.path)
 ```
@@ -75,24 +71,18 @@ 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')
+const { publicKey } = await name.publish('key-1', cid)
 
 // publish the recursive name
-await name.publish(recursivePrivateKey, privateKey.publicKey)
+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(recursivePrivateKey.publicKey)
+const result = await name.resolve(recursivePublicKey)
 console.info(result.cid.toString() === cid.toString()) // true
 ```
 
@@ -109,9 +99,6 @@ 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]))
@@ -121,10 +108,10 @@ 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`)
+const { publicKey } = await name.publish('key-1', `/ipfs/${finalDirCid}/foo.txt`)
 
 // resolve the name
-const result = await name.resolve(privateKey.publicKey)
+const result = await name.resolve(publicKey)
 
 console.info(result.cid, result.path) // QmFoo.. 'foo.txt'
 ```
@@ -150,13 +137,14 @@ 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 { floodsub } from '@libp2p/floodsub'
 import { generateKeyPair } from '@libp2p/crypto/keys'
-import type { Libp2p, PubSub } from '@libp2p/interface'
+import type { PubSub } from '@helia/ipns/routing'
+import type { Libp2p } from '@libp2p/interface'
 import type { DefaultLibp2pServices } from 'helia'
 
 const libp2pOptions = libp2pDefaults()
-libp2pOptions.services.pubsub = gossipsub()
+libp2pOptions.services.pubsub = floodsub()
 
 const helia = await createHelia<Libp2p<DefaultLibp2pServices & { pubsub: PubSub }>>({
   libp2p: libp2pOptions
@@ -167,133 +155,30 @@ 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)
+const { publicKey } = await name.publish('key-1', 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:
-
-```TypeScript
-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:
-
-```TypeScript
-// 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.
-
-```TypeScript
-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.
-
-```TypeScript
-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')
+const result = await name.resolve(publicKey)
 ```
 
 ## Example - Republishing an existing IPNS record
 
-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.
+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 } from '@helia/ipns'
+import { ipns, ipnsValidator } from '@helia/ipns'
 import { createDelegatedRoutingV1HttpApiClient } from '@helia/delegated-routing-v1-http-api-client'
 import { CID } from 'multiformats/cid'
+import { multihashToIPNSRoutingKey, marshalIPNSRecord } from 'ipns'
 
 const helia = await createHelia()
 const name = ipns(helia)
@@ -303,7 +188,18 @@ 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)
+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