@helia/ipns 8.2.4 → 9.0.0-9c67dbd4

package/src/index.ts

@@ -1,7 +1,7 @@
 /**
  * @packageDocumentation
  *
- * IPNS operations using a Helia node
+ * [IPNS](https://docs.ipfs.tech/concepts/ipns/) operations using a Helia node
  *
  * @example Getting started
  *
@@ -11,23 +11,19 @@
  * 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)
  * ```
@@ -46,24 +42,18 @@
  * 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
  * ```
  *
@@ -80,9 +70,6 @@
  * 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]))
@@ -92,10 +79,10 @@
  * 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'
  * ```
@@ -121,13 +108,14 @@
  * 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
@@ -138,133 +126,30 @@
  *  ]
  * })
  *
- * // 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)
@@ -274,47 +159,33 @@
  * 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)
+ *   })
+ * )
  * ```
  */
 
-import { NotFoundError, isPublicKey } from '@libp2p/interface'
-import { logger } from '@libp2p/logger'
-import { peerIdFromString } from '@libp2p/peer-id'
-import { createIPNSRecord, extractPublicKeyFromIPNSRecord, marshalIPNSRecord, multihashToIPNSRoutingKey, unmarshalIPNSRecord } from 'ipns'
-import { ipnsSelector } from 'ipns/selector'
 import { ipnsValidator } from 'ipns/validator'
-import { base36 } from 'multiformats/bases/base36'
-import { base58btc } from 'multiformats/bases/base58'
 import { CID } from 'multiformats/cid'
-import * as Digest from 'multiformats/hashes/digest'
-import { CustomProgressEvent } from 'progress-events'
-import { resolveDNSLink } from './dnslink.js'
-import { InvalidValueError, RecordsFailedValidationError, UnsupportedMultibasePrefixError, UnsupportedMultihashCodecError } from './errors.js'
-import { helia } from './routing/helia.js'
-import { localStore } from './routing/local-store.js'
-import { isCodec, IDENTITY_CODEC, SHA2_256_CODEC, IPNS_STRING_PREFIX } from './utils.js'
+import { IPNS as IPNSClass } from './ipns.js'
 import type { IPNSRouting, IPNSRoutingEvents } from './routing/index.js'
-import type { LocalStore } from './routing/local-store.js'
-import type { Routing } from '@helia/interface'
-import type { AbortOptions, ComponentLogger, Logger, PrivateKey, PublicKey } from '@libp2p/interface'
-import type { Answer, DNS, ResolveDnsProgressEvents } from '@multiformats/dns'
+import type { Routing, HeliaEvents } from '@helia/interface'
+import type { AbortOptions, ComponentLogger, Libp2p, PeerId, PublicKey, TypedEventEmitter } from '@libp2p/interface'
+import type { Keychain } from '@libp2p/keychain'
 import type { Datastore } from 'interface-datastore'
 import type { IPNSRecord } from 'ipns'
-import type { MultibaseDecoder } from 'multiformats/bases/interface'
 import type { MultihashDigest } from 'multiformats/hashes/interface'
 import type { ProgressEvent, ProgressOptions } from 'progress-events'
 
-const log = logger('helia:ipns')
-
-const MINUTE = 60 * 1000
-const HOUR = 60 * MINUTE
-
-const DEFAULT_LIFETIME_MS = 48 * HOUR
-const DEFAULT_REPUBLISH_INTERVAL_MS = 23 * HOUR
-
-const DEFAULT_TTL_NS = BigInt(MINUTE) * 5_000_000n // 5 minutes
-
 export type PublishProgressEvents =
   ProgressEvent<'ipns:publish:start'> |
   ProgressEvent<'ipns:publish:success', IPNSRecord> |
@@ -325,15 +196,11 @@ export type ResolveProgressEvents =
   ProgressEvent<'ipns:resolve:success', IPNSRecord> |
   ProgressEvent<'ipns:resolve:error', Error>
 
-export type RepublishProgressEvents =
-  ProgressEvent<'ipns:republish:start', unknown> |
-  ProgressEvent<'ipns:republish:success', IPNSRecord> |
-  ProgressEvent<'ipns:republish:error', { key?: MultihashDigest<0x00 | 0x12>, record: IPNSRecord, err: Error }>
-
-export type ResolveDNSLinkProgressEvents =
-  ResolveProgressEvents |
-  IPNSRoutingEvents |
-  ResolveDnsProgressEvents
+export type DatastoreProgressEvents =
+  ProgressEvent<'ipns:routing:datastore:put'> |
+  ProgressEvent<'ipns:routing:datastore:get'> |
+  ProgressEvent<'ipns:routing:datastore:list'> |
+  ProgressEvent<'ipns:routing:datastore:error', Error>
 
 export interface PublishOptions extends AbortOptions, ProgressOptions<PublishProgressEvents | IPNSRoutingEvents> {
   /**
@@ -358,23 +225,12 @@ export interface PublishOptions extends AbortOptions, ProgressOptions<PublishPro
   ttl?: number
 }
 
-export interface ResolveOptions extends AbortOptions, ProgressOptions<ResolveProgressEvents | IPNSRoutingEvents> {
-  /**
-   * Do not query the network for the IPNS record
-   *
-   * @default false
-   */
-  offline?: boolean
-
-  /**
-   * Do not use cached IPNS Record entries
-   *
-   * @default false
-   */
-  nocache?: boolean
+export interface IPNSRecordMetadata {
+  keyName: string
+  lifetime: number
 }
 
-export interface ResolveDNSLinkOptions extends AbortOptions, ProgressOptions<ResolveDNSLinkProgressEvents> {
+export interface ResolveOptions extends AbortOptions, ProgressOptions<ResolveProgressEvents | IPNSRoutingEvents> {
   /**
    * Do not query the network for the IPNS record
    *
@@ -383,35 +239,11 @@ export interface ResolveDNSLinkOptions extends AbortOptions, ProgressOptions<Res
   offline?: boolean
 
   /**
-   * Do not use cached DNS entries
+   * Do not use cached IPNS Record entries
    *
    * @default false
    */
   nocache?: boolean
-
-  /**
-   * When resolving DNSLink records that resolve to other DNSLink records, limit
-   * how many times we will recursively resolve them.
-   *
-   * @default 32
-   */
-  maxRecursiveDepth?: number
-}
-
-export interface RepublishOptions extends AbortOptions, ProgressOptions<RepublishProgressEvents | IPNSRoutingEvents> {
-  /**
-   * The republish interval in ms (default: 23hrs)
-   */
-  interval?: number
-}
-
-export interface RepublishRecordOptions extends AbortOptions, ProgressOptions<RepublishProgressEvents | IPNSRoutingEvents> {
-  /**
-   * Only publish to a local datastore
-   *
-   * @default false
-   */
-  offline?: boolean
 }
 
 export interface ResolveResult {
@@ -435,44 +267,73 @@ export interface IPNSResolveResult extends ResolveResult {
   record: IPNSRecord
 }
 
-export interface DNSLinkResolveResult extends ResolveResult {
+export interface IPNSPublishResult {
   /**
-   * The resolved record
+   * The published record
    */
-  answer: Answer
-}
+  record: IPNSRecord
 
-export interface IPNS {
   /**
-   * Creates an IPNS record signed by the passed PeerId that will resolve to the passed value
-   *
-   * If the value is a PeerId, a recursive IPNS record will be created.
+   * The public key that was used to publish the record
    */
-  publish(key: PrivateKey, value: CID | PublicKey | MultihashDigest<0x00 | 0x12> | string, options?: PublishOptions): Promise<IPNSRecord>
+  publicKey: PublicKey
+}
 
+export interface IPNS {
   /**
-   * Accepts a public key formatted as a libp2p PeerID and resolves the IPNS record
-   * corresponding to that public key until a value is found
+   * Configured routing subsystems used to publish/resolve IPNS names
    */
-  resolve(key: PublicKey | MultihashDigest<0x00 | 0x12>, options?: ResolveOptions): Promise<IPNSResolveResult>
+  routers: IPNSRouting[]
 
   /**
-   * Resolve a CID from a dns-link style IPNS record
+   * Creates and publishes an IPNS record that will resolve the passed value
+   * signed by a key stored in the libp2p keychain under the passed key name.
+   *
+   * It is possible to create a recursive IPNS record by passing:
+   *
+   * - A PeerId,
+   * - A PublicKey
+   * - A CID with the libp2p-key codec and Identity or SHA256 hash algorithms
+   * - A Multihash with the Identity or SHA256 hash algorithms
+   * - A string IPNS key (e.g. `/ipns/Qmfoo`)
+   *
+   * @example
+   *
+   * ```TypeScript
+   * import { createHelia } from 'helia'
+   * import { ipns } from '@helia/ipns'
+   *
+   * const helia = await createHelia()
+   * const name = ipns(helia)
+   *
+   * const result = await name.publish('my-key-name', cid, {
+   *   signal: AbortSignal.timeout(5_000)
+   * })
+   *
+   * console.info(result) // { answer: ... }
+   * ```
    */
-  resolveDNSLink(domain: string, options?: ResolveDNSLinkOptions): Promise<DNSLinkResolveResult>
+  publish(keyName: string, value: CID | PublicKey | MultihashDigest<0x00 | 0x12> | PeerId | string, options?: PublishOptions): Promise<IPNSPublishResult>
 
   /**
-   * Periodically republish all IPNS records found in the datastore
+   * Accepts a libp2p public key, a CID with the libp2p-key codec and either the
+   * identity hash (for Ed25519 and secp256k1 public keys) or a SHA256 hash (for
+   * RSA public keys), or the multihash of a libp2p-key encoded CID, or a
+   * Ed25519, secp256k1 or RSA PeerId and recursively resolves the IPNS record
+   * corresponding to that key until a value is found.
    */
-  republish(options?: RepublishOptions): void
+  resolve(key: CID<unknown, 0x72, 0x00 | 0x12, 1> | PublicKey | MultihashDigest<0x00 | 0x12> | PeerId, options?: ResolveOptions): Promise<IPNSResolveResult>
 
   /**
-   * Republish an existing IPNS record without the private key.
+   * Stop republishing of an IPNS record
+   *
+   * This will delete the last signed IPNS record from the datastore, but the
+   * key will remain in the keychain.
    *
-   * Before republishing the record will be validated to ensure it has a valid signature and lifetime(validity) in the future.
-   * The key is a multihash of the public key or a string representation of the PeerID (either base58btc encoded multihash or base36 encoded CID)
+   * Note that the record may still be resolved by other peers until it expires
+   * or is no longer valid.
    */
-  republishRecord(key: MultihashDigest<0x00 | 0x12> | string, record: IPNSRecord, options?: RepublishRecordOptions): Promise<void>
+  unpublish(keyName: string, options?: AbortOptions): Promise<void>
 }
 
 export type { IPNSRouting } from './routing/index.js'
@@ -482,325 +343,35 @@ export type { IPNSRecord } from 'ipns'
 export interface IPNSComponents {
   datastore: Datastore
   routing: Routing
-  dns: DNS
   logger: ComponentLogger
-}
-
-const bases: Record<string, MultibaseDecoder<string>> = {
-  [base36.prefix]: base36,
-  [base58btc.prefix]: base58btc
-}
-
-class DefaultIPNS implements IPNS {
-  private readonly routers: IPNSRouting[]
-  private readonly localStore: LocalStore
-  private timeout?: ReturnType<typeof setTimeout>
-  private readonly dns: DNS
-  private readonly log: Logger
-
-  constructor (components: IPNSComponents, routers: IPNSRouting[] = []) {
-    this.routers = [
-      helia(components.routing),
-      ...routers
-    ]
-    this.localStore = localStore(components.datastore)
-    this.dns = components.dns
-    this.log = components.logger.forComponent('helia:ipns')
-  }
-
-  async publish (key: PrivateKey, value: CID | PublicKey | MultihashDigest<0x00 | 0x12> | string, options: PublishOptions = {}): Promise<IPNSRecord> {
-    try {
-      let sequenceNumber = 1n
-      const routingKey = multihashToIPNSRoutingKey(key.publicKey.toMultihash())
-
-      if (await this.localStore.has(routingKey, options)) {
-        // if we have published under this key before, increment the sequence number
-        const { record } = await this.localStore.get(routingKey, options)
-        const existingRecord = unmarshalIPNSRecord(record)
-        sequenceNumber = existingRecord.sequence + 1n
-      }
-
-      // convert ttl from milliseconds to nanoseconds as createIPNSRecord expects
-      const ttlNs = options.ttl != null ? BigInt(options.ttl) * 1_000_000n : DEFAULT_TTL_NS
-      const record = await createIPNSRecord(key, value, sequenceNumber, options.lifetime ?? DEFAULT_LIFETIME_MS, { ...options, ttlNs })
-      const marshaledRecord = marshalIPNSRecord(record)
-
-      await this.localStore.put(routingKey, marshaledRecord, options)
-
-      if (options.offline !== true) {
-        // publish record to routing
-        await Promise.all(this.routers.map(async r => { await r.put(routingKey, marshaledRecord, options) }))
-      }
-
-      return record
-    } catch (err: any) {
-      options.onProgress?.(new CustomProgressEvent<Error>('ipns:publish:error', err))
-      throw err
-    }
-  }
-
-  async resolve (key: PublicKey | MultihashDigest<0x00 | 0x12>, options: ResolveOptions = {}): Promise<IPNSResolveResult> {
-    const digest = isPublicKey(key) ? key.toMultihash() : key
-    const routingKey = multihashToIPNSRoutingKey(digest)
-    const record = await this.#findIpnsRecord(routingKey, options)
-
-    return {
-      ...(await this.#resolve(record.value, options)),
-      record
-    }
-  }
-
-  async resolveDNSLink (domain: string, options: ResolveDNSLinkOptions = {}): Promise<DNSLinkResolveResult> {
-    const dnslink = await resolveDNSLink(domain, this.dns, this.log, options)
-
-    return {
-      ...(await this.#resolve(dnslink.value, options)),
-      answer: dnslink.answer
-    }
-  }
-
-  republish (options: RepublishOptions = {}): void {
-    if (this.timeout != null) {
-      throw new Error('Republish is already running')
-    }
-
-    options.signal?.addEventListener('abort', () => {
-      clearTimeout(this.timeout)
-    })
-
-    async function republish (): Promise<void> {
-      const startTime = Date.now()
-
-      options.onProgress?.(new CustomProgressEvent('ipns:republish:start'))
-
-      const finishType = Date.now()
-      const timeTaken = finishType - startTime
-      let nextInterval = DEFAULT_REPUBLISH_INTERVAL_MS - timeTaken
-
-      if (nextInterval < 0) {
-        nextInterval = options.interval ?? DEFAULT_REPUBLISH_INTERVAL_MS
-      }
-
-      setTimeout(() => {
-        republish().catch(err => {
-          log.error('error republishing', err)
-        })
-      }, nextInterval)
-    }
-
-    this.timeout = setTimeout(() => {
-      republish().catch(err => {
-        log.error('error republishing', err)
-      })
-    }, options.interval ?? DEFAULT_REPUBLISH_INTERVAL_MS)
-  }
-
-  async #resolve (ipfsPath: string, options: ResolveOptions = {}): Promise<{ cid: CID, path: string }> {
-    const parts = ipfsPath.split('/')
-    try {
-      const scheme = parts[1]
-
-      if (scheme === 'ipns') {
-        const str = parts[2]
-        const prefix = str.substring(0, 1)
-        let buf: Uint8Array | undefined
-
-        if (prefix === '1' || prefix === 'Q') {
-          buf = base58btc.decode(`z${str}`)
-        } else if (bases[prefix] != null) {
-          buf = bases[prefix].decode(str)
-        } else {
-          throw new UnsupportedMultibasePrefixError(`Unsupported multibase prefix "${prefix}"`)
-        }
-
-        let digest: MultihashDigest<number>
-
-        try {
-          digest = Digest.decode(buf)
-        } catch {
-          digest = CID.decode(buf).multihash
-        }
-
-        if (!isCodec(digest, IDENTITY_CODEC) && !isCodec(digest, SHA2_256_CODEC)) {
-          throw new UnsupportedMultihashCodecError(`Unsupported multihash codec "${digest.code}"`)
-        }
-
-        const { cid } = await this.resolve(digest, options)
-        const path = parts.slice(3).join('/')
-        return {
-          cid,
-          path
-        }
-      } else if (scheme === 'ipfs') {
-        const cid = CID.parse(parts[2])
-        const path = parts.slice(3).join('/')
-        return {
-          cid,
-          path
-        }
-      }
-    } catch (err) {
-      log.error('error parsing ipfs path', err)
-    }
-
-    log.error('invalid ipfs path %s', ipfsPath)
-    throw new InvalidValueError('Invalid value')
-  }
-
-  async #findIpnsRecord (routingKey: Uint8Array, options: ResolveOptions = {}): Promise<IPNSRecord> {
-    const records: Uint8Array[] = []
-    const cached = await this.localStore.has(routingKey, options)
-
-    if (cached) {
-      log('record is present in the cache')
-
-      if (options.nocache !== true) {
-        try {
-          // check the local cache first
-          const { record, created } = await this.localStore.get(routingKey, options)
-
-          this.log('record retrieved from cache')
-
-          // validate the record
-          await ipnsValidator(routingKey, record)
-
-          this.log('record was valid')
-
-          // check the TTL
-          const ipnsRecord = unmarshalIPNSRecord(record)
-
-          // IPNS TTL is in nanoseconds, convert to milliseconds, default to one
-          // hour
-          const ttlMs = Number((ipnsRecord.ttl ?? DEFAULT_TTL_NS) / 1_000_000n)
-          const ttlExpires = created.getTime() + ttlMs
-
-          if (ttlExpires > Date.now()) {
-            // the TTL has not yet expired, return the cached record
-            this.log('record TTL was valid')
-            return ipnsRecord
-          }
-
-          if (options.offline === true) {
-            // the TTL has expired but we are skipping the routing search
-            this.log('record TTL has been reached but we are resolving offline-only, returning record')
-            return ipnsRecord
-          }
-
-          this.log('record TTL has been reached, searching routing for updates')
-
-          // add the local record to our list of resolved record, and also
-          // search the routing for updates - the most up to date record will be
-          // returned
-          records.push(record)
-        } catch (err) {
-          this.log('cached record was invalid', err)
-          await this.localStore.delete(routingKey, options)
-        }
-      } else {
-        log('ignoring local cache due to nocache=true option')
-      }
-    }
-
-    if (options.offline === true) {
-      throw new NotFoundError('Record was not present in the cache or has expired')
-    }
-
-    log('did not have record locally')
-
-    let foundInvalid = 0
-
-    await Promise.all(
-      this.routers.map(async (router) => {
-        let record: Uint8Array
-
-        try {
-          record = await router.get(routingKey, {
-            ...options,
-            validate: false
-          })
-        } catch (err: any) {
-          log.error('error finding IPNS record', err)
-
-          return
-        }
-
-        try {
-          await ipnsValidator(routingKey, record)
-
-          records.push(record)
-        } catch (err) {
-          // we found a record, but the validator rejected it
-          foundInvalid++
-          log.error('error finding IPNS record', err)
-        }
-      })
-    )
-
-    if (records.length === 0) {
-      if (foundInvalid > 0) {
-        throw new RecordsFailedValidationError(`${foundInvalid > 1 ? `${foundInvalid} records` : 'Record'} found for routing key ${foundInvalid > 1 ? 'were' : 'was'} invalid`)
-      }
-
-      throw new NotFoundError('Could not find record for routing key')
-    }
-
-    const record = records[ipnsSelector(routingKey, records)]
-
-    await this.localStore.put(routingKey, record, options)
-
-    return unmarshalIPNSRecord(record)
-  }
-
-  async republishRecord (key: MultihashDigest<0x00 | 0x12> | string, record: IPNSRecord, options: RepublishRecordOptions = {}): Promise<void> {
-    let mh: MultihashDigest<0x00 | 0x12> | undefined
-    try {
-      mh = extractPublicKeyFromIPNSRecord(record)?.toMultihash() // embedded public key take precedence, if present
-      if (mh == null) {
-        // if no public key is embedded in the record, use the key that was passed in
-        if (typeof key === 'string') {
-          if (key.startsWith(IPNS_STRING_PREFIX)) {
-            // remove the /ipns/ prefix from the key
-            key = key.slice(IPNS_STRING_PREFIX.length)
-          }
-          // Convert string key to MultihashDigest
-          try {
-            mh = peerIdFromString(key).toMultihash()
-          } catch (err: any) {
-            throw new Error(`Invalid string key: ${err.message}`)
-          }
-        } else {
-          mh = key
-        }
-      }
-
-      if (mh == null) {
-        throw new Error('No public key multihash found to determine the routing key')
-      }
-
-      const routingKey = multihashToIPNSRoutingKey(mh)
-      const marshaledRecord = marshalIPNSRecord(record)
-
-      await ipnsValidator(routingKey, marshaledRecord) // validate that they key corresponds to the record
-
-      await this.localStore.put(routingKey, marshaledRecord, options) // add to local store
-
-      if (options.offline !== true) {
-        // publish record to routing
-        await Promise.all(this.routers.map(async r => { await r.put(routingKey, marshaledRecord, options) }))
-      }
-    } catch (err: any) {
-      options.onProgress?.(new CustomProgressEvent('ipns:republish:error', { key: mh, record, err }))
-      throw err
-    }
-  }
+  libp2p: Libp2p<{ keychain: Keychain }>
+  events: TypedEventEmitter<HeliaEvents> // Helia event bus
 }
 
 export interface IPNSOptions {
+  /**
+   * Different routing systems for IPNS publishing/resolving
+   */
   routers?: IPNSRouting[]
+
+  /**
+   * How often to check if published records have expired and need republishing
+   * in ms
+   *
+   * @default 3_600_000
+   */
+  republishInterval?: number
+
+  /**
+   * How many IPNS records to republish at once
+   *
+   * @default 5
+   */
+  republishConcurrency?: number
 }
 
-export function ipns (components: IPNSComponents, { routers = [] }: IPNSOptions = {}): IPNS {
-  return new DefaultIPNS(components, routers)
+export function ipns (components: IPNSComponents, options: IPNSOptions = {}): IPNS {
+  return new IPNSClass(components, options)
 }
 
 export { ipnsValidator, type IPNSRoutingEvents }